cce54358d2
**Git Commit Tracking** - Automatically capture git commit hash when claims/observations are ingested - Store in assertion metadata for temporal context and audit trails - Graceful degradation in non-git environments - Solves double-commit problem by capturing hash at ingestion time **Implementation** - walker/git.rs: get_current_commit_hash() utility function - bridge.rs: Accept optional git_commit parameter in all conversion functions - episteme/local: Store project_root, capture git hash during ingestion - 5 new tests for git hash tracking + metadata validation - All 1162 aphoria tests passing **Documentation Overhaul** - README: Added Observations vs Claims distinction, git tracking, dashboard - CLI Reference: New sections for git integration and ignore/exclusion system - Comprehensive ignore documentation: .aphoriaignore, inline comments, 4 methods - Enhanced verification engine docs with matching capabilities - DOCUMENTATION_UPDATES.md: Complete audit summary **Dashboard Separation** - Moved Aphoria-specific UI from stemedb-dashboard to aphoria-dashboard - Clean separation of concerns: StemeDB for core, Aphoria for security - Added dashboard documentation and setup guides Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
323 lines
9.3 KiB
Markdown
323 lines
9.3 KiB
Markdown
# Aphoria Documentation Index
|
|
|
|
## Quick Links
|
|
|
|
### Getting Started
|
|
- **Main README**: [`applications/aphoria/README.md`](../../aphoria/README.md)
|
|
- Quick start guide
|
|
- Installation instructions
|
|
- Basic scan workflows
|
|
- Output formats
|
|
- Pre-commit integration
|
|
|
|
### User Guides
|
|
- **Guides Index**: [`applications/aphoria/docs/guides/README.md`](../../aphoria/docs/guides/README.md)
|
|
|
|
#### Getting Started Guides
|
|
1. **[The First Scan](../../aphoria/docs/guides/the-first-scan.md)** - First-time user walkthrough
|
|
2. **[Solo Developer Guide](../../aphoria/docs/guides/solo-developer-guide.md)** - For individual developers
|
|
3. **[Enterprise Quick Start](../../aphoria/docs/guides/enterprise-quick-start.md)** - 5-minute enterprise setup
|
|
4. **[Enterprise Pilot Guide](../../aphoria/docs/guides/enterprise-pilot-guide.md)** - Full pilot planning
|
|
|
|
#### Core Workflows
|
|
- **[Federating Truth](../../aphoria/docs/guides/federating-truth.md)** - Trust Pack creation and distribution
|
|
- **[Multi-Team Policy Governance](../../aphoria/docs/guides/multi-team-policy-governance.md)** - Cross-team policies
|
|
- **[Policy Audit Trails](../../aphoria/docs/guides/policy-audit-trails.md)** - Compliance and auditing
|
|
- **[Authoritative State Per Project](../../aphoria/docs/guides/authoritative-state-per-project.md)** - Project-specific policies
|
|
- **[Pre-Flight Checks](../../aphoria/docs/guides/pre-flight-checks.md)** - Pre-commit and CI
|
|
|
|
#### Advanced Topics
|
|
- **[Golden Path Loop](../../aphoria/docs/guides/golden-path-loop.md)** - Continuous policy improvement
|
|
- **[AAA Game Development](../../aphoria/docs/guides/aaa-game-development.md)** - Unreal Engine patterns
|
|
|
|
### Reference Documentation
|
|
- **[CLI Reference](../../aphoria/docs/cli-reference.md)** - Complete command documentation
|
|
- **[Comparison Modes](../../aphoria/docs/comparison-modes.md)** - Claim comparison modes explained
|
|
|
|
### Architecture Documentation
|
|
- **[Architecture Index](../../aphoria/docs/architecture/README.md)** - System design and internals
|
|
|
|
### UAT Reports
|
|
- **[UAT Index](../../aphoria/uat/README.md)** - Validation test results
|
|
- **[Policy Source Tracking UAT](../../aphoria/uat/2026-02-04-uat-real-world-policy-source.md)** - Trust Pack validation
|
|
|
|
### Vision & Strategy
|
|
- **[Vision & Gaps](../../aphoria/docs/vision-gaps.md)** - Product vision and roadmap gaps
|
|
|
|
---
|
|
|
|
## Dashboard-Specific Documentation
|
|
|
|
### Setup & Configuration
|
|
- **[Project Path Implementation](./PROJECT_PATH_IMPLEMENTATION.md)** - localStorage persistence setup
|
|
- **[Quick Reference](./QUICK_REFERENCE.md)** - Developer quick reference
|
|
- **[Bug Fixes](./BUGFIXES.md)** - Hydration and type error fixes
|
|
- **[Corpus Improvements](./CORPUS_IMPROVEMENTS.md)** - Form refactoring and UX improvements
|
|
|
|
### API Documentation
|
|
- **Client**: `src/lib/api/client.ts` - StemeDB API client
|
|
- **Types**: `src/lib/api/types.ts` - TypeScript type definitions
|
|
|
|
### Component Documentation
|
|
- **Claims Card**: `src/components/claims/claim-card.tsx` - Rich claim display
|
|
- **Corpus Panel**: `src/components/corpus/corpus-panel.tsx` - Community patterns
|
|
- **Scans Panel**: `src/components/scans/scans-panel.tsx` - Scan management
|
|
|
|
---
|
|
|
|
## Key Concepts
|
|
|
|
### What is Aphoria?
|
|
A code-level truth linter that validates your code against authoritative technical standards (RFCs, OWASP, vendor documentation). It checks **intent against authority**, not just syntax.
|
|
|
|
### Observations vs Claims
|
|
- **Observations**: Automated pattern matches (e.g., `imports/tokio: true`)
|
|
- **Claims**: Human-authored rules with provenance, invariants, and consequences
|
|
|
|
### Corpus Types
|
|
1. **Authoritative Corpus**: Built-in standards (RFCs, OWASP, CWE)
|
|
2. **Community Corpus**: Aggregated patterns from opt-in users
|
|
3. **Project Claims**: Local `.aphoria/claims.toml` file
|
|
|
|
### Scan Modes
|
|
- **Ephemeral** (default): Fast, in-memory, no persistence (~0.25s)
|
|
- **Persistent** (`--persist`): Stores in Episteme, enables diff/baseline
|
|
- **Sync** (`--persist --sync`): Also pushes to community corpus
|
|
|
|
### Community Sharing
|
|
Opt-in feature that anonymizes observations and contributes to community patterns:
|
|
|
|
```toml
|
|
[community]
|
|
enabled = true # Must opt-in (default: false)
|
|
anonymize = true # Hash project identifiers
|
|
min_confidence = 0.7 # Quality threshold
|
|
```
|
|
|
|
To contribute:
|
|
```bash
|
|
aphoria scan --persist --sync
|
|
```
|
|
|
|
---
|
|
|
|
## Common Workflows
|
|
|
|
### 1. First-Time Setup
|
|
```bash
|
|
# Install
|
|
cargo install --path applications/aphoria
|
|
|
|
# Initialize corpus
|
|
aphoria init
|
|
|
|
# Run first scan
|
|
aphoria scan .
|
|
```
|
|
|
|
### 2. Daily Development
|
|
```bash
|
|
# Quick ephemeral scan
|
|
aphoria scan .
|
|
|
|
# Pre-commit (staged files only)
|
|
aphoria scan --staged --exit-code
|
|
```
|
|
|
|
### 3. CI/CD Integration
|
|
```bash
|
|
# CI mode (fails build on BLOCK)
|
|
aphoria scan --exit-code --format json
|
|
```
|
|
|
|
### 4. Claims Authoring
|
|
```bash
|
|
# List existing claims
|
|
aphoria claims list
|
|
|
|
# Create new claim
|
|
aphoria claims create \
|
|
--id "myapp-tls-001" \
|
|
--concept-path "myapp/api/tls/min_version" \
|
|
--predicate "min_version" \
|
|
--value "TLSv1.3" \
|
|
--comparison equals \
|
|
--provenance "Security policy 2024-Q1" \
|
|
--invariant "API MUST use TLS 1.3 or higher" \
|
|
--consequence "Vulnerable to downgrade attacks" \
|
|
--tier expert \
|
|
--category security
|
|
```
|
|
|
|
### 5. Verification (Audit)
|
|
```bash
|
|
# Verify claims against code
|
|
aphoria verify run
|
|
|
|
# Coverage analysis
|
|
aphoria verify coverage
|
|
|
|
# Generate documentation
|
|
aphoria docs generate
|
|
```
|
|
|
|
### 6. Community Contribution
|
|
```bash
|
|
# Preview what would be shared
|
|
aphoria scan --community-preview
|
|
|
|
# Actually share (with community.enabled = true)
|
|
aphoria scan --persist --sync
|
|
```
|
|
|
|
---
|
|
|
|
## Dashboard Features
|
|
|
|
### Scans Panel (`/scans`)
|
|
- Run new scans
|
|
- View scan history
|
|
- Drill into findings
|
|
- Filter by verdict (PASS/CONFLICT/MISSING)
|
|
|
|
### Claims Panel (`/claims`)
|
|
- List authored claims
|
|
- View claim details (invariant, consequence, provenance)
|
|
- Run verification
|
|
- View coverage metrics
|
|
|
|
### Corpus Panel (`/corpus`)
|
|
- Browse community patterns
|
|
- Filter by subject prefix
|
|
- See project counts
|
|
- Identify consensus patterns
|
|
|
|
---
|
|
|
|
## Configuration Files
|
|
|
|
### Project Config (`.aphoria/config.toml`)
|
|
```toml
|
|
[project]
|
|
name = "myapp"
|
|
|
|
[community]
|
|
enabled = false # Opt-in for corpus contribution
|
|
|
|
[thresholds]
|
|
flag = 0.5
|
|
block = 0.7
|
|
|
|
[extractors]
|
|
# Enable/disable specific extractors
|
|
```
|
|
|
|
### Claims File (`.aphoria/claims.toml`)
|
|
Human-authored claims with full provenance:
|
|
```toml
|
|
[[claim]]
|
|
id = "myapp-rule-001"
|
|
concept_path = "myapp/module/property"
|
|
predicate = "key"
|
|
value = "expected_value"
|
|
comparison = "equals"
|
|
provenance = "Where this rule came from"
|
|
invariant = "What MUST stay true"
|
|
consequence = "What breaks if violated"
|
|
authority_tier = "expert"
|
|
category = "security"
|
|
status = "active"
|
|
```
|
|
|
|
---
|
|
|
|
## CLI Command Reference
|
|
|
|
### Scanning
|
|
```bash
|
|
aphoria scan [PATH] # Quick ephemeral scan
|
|
aphoria scan --persist # Persistent mode
|
|
aphoria scan --persist --sync # + community push
|
|
aphoria scan --staged # Pre-commit (staged files)
|
|
aphoria scan --exit-code # CI mode
|
|
aphoria scan --format json # JSON output
|
|
aphoria scan --format sarif # GitHub Security tab
|
|
aphoria scan --community-preview # Dry run (no data sent)
|
|
```
|
|
|
|
### Claims Management
|
|
```bash
|
|
aphoria claims list # List all claims
|
|
aphoria claims create # Author new claim
|
|
aphoria claims explain <ID> # Explain a claim
|
|
aphoria claims update <ID> # Update existing claim
|
|
aphoria claims supersede <ID> # Supersede with new claim
|
|
aphoria claims deprecate <ID> # Mark as deprecated
|
|
```
|
|
|
|
### Verification
|
|
```bash
|
|
aphoria verify run # Verify all claims
|
|
aphoria verify map # Show extractor→claim mapping
|
|
aphoria verify coverage # Coverage analysis
|
|
```
|
|
|
|
### Documentation
|
|
```bash
|
|
aphoria docs generate # Generate docs from claims
|
|
aphoria explain <CONCEPT> # Explain concept
|
|
```
|
|
|
|
### Corpus Management
|
|
```bash
|
|
aphoria corpus build # Build authoritative corpus
|
|
aphoria corpus list # List corpus sources
|
|
aphoria corpus export-pack # Export as Trust Pack
|
|
```
|
|
|
|
### Pattern Learning
|
|
```bash
|
|
aphoria patterns sync # Sync learned patterns
|
|
aphoria patterns status # Show sync status
|
|
aphoria patterns pull-community # Pull community extractors
|
|
aphoria patterns show # Show learned patterns
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Empty Corpus Panel
|
|
**Problem**: `/corpus` page shows "0 patterns"
|
|
|
|
**Solution**: Community corpus requires:
|
|
1. Enable `community.enabled = true` in config
|
|
2. Run `aphoria scan --persist --sync`
|
|
3. Wait for patterns to aggregate
|
|
|
|
### Claims Not Verifying
|
|
**Problem**: Verification shows "MISSING" for valid code patterns
|
|
|
|
**Solution**: Check:
|
|
1. Concept path matches extractor output
|
|
2. Comparison mode is correct (equals/present/absent/not_equals)
|
|
3. Value matches exactly (including type)
|
|
4. Extractor declares the predicate in `verifiable_predicates()`
|
|
|
|
### Hydration Errors
|
|
**Problem**: React hydration mismatch in dashboard
|
|
|
|
**Solution**: See [`BUGFIXES.md`](./BUGFIXES.md) for SSR safety patterns
|
|
|
|
---
|
|
|
|
## Additional Resources
|
|
|
|
- **Episteme (StemeDB)**: [`../../README.md`](../../README.md) - Knowledge graph database
|
|
- **CLAUDE.md**: [`../../CLAUDE.md`](../../CLAUDE.md) - Project context for AI assistants
|
|
- **Roadmap**: [`../../roadmap.md`](../../roadmap.md) - Current development status
|
|
|
|
---
|
|
|
|
**Last Updated**: 2026-02-08
|