From 28fc3b5391e8d4b6f89ec434daa5e3df5c82b5df Mon Sep 17 00:00:00 2001 From: jordan Date: Thu, 12 Feb 2026 03:02:33 -0700 Subject: [PATCH] feat(aphoria): add C language support and streamline documentation Add Language::C variant with file detection (.c, Makefile, CMakeLists.txt) and integration across prompts, regex_gen, and path_mapper. Simplify README and guides to be more concise and scannable. Co-Authored-By: Claude Opus 4.6 --- applications/aphoria/LATEST-SCAN.md | 49 ++ applications/aphoria/README.md | 572 ++++-------------- applications/aphoria/docs/guides/README.md | 126 +--- .../docs/guides/solo-developer-guide.md | 9 +- .../aphoria/docs/guides/the-first-scan.md | 11 +- applications/aphoria/src/llm/prompts.rs | 3 + .../aphoria/src/promotion/regex_gen.rs | 1 + applications/aphoria/src/types/language.rs | 10 + .../aphoria/src/walker/path_mapper.rs | 1 + 9 files changed, 198 insertions(+), 584 deletions(-) create mode 100644 applications/aphoria/LATEST-SCAN.md diff --git a/applications/aphoria/LATEST-SCAN.md b/applications/aphoria/LATEST-SCAN.md new file mode 100644 index 0000000..a4e40ff --- /dev/null +++ b/applications/aphoria/LATEST-SCAN.md @@ -0,0 +1,49 @@ +# Aphoria Scan: stemedb + +**725** files scanned | **2530** observations | **39** claims (7 pass, 0 conflict, 32 missing) + +## Claim Verification + +| Verdict | Claim | Invariant | Explanation | +|---------|-------|-----------|-------------| +| MISSING | `aphoria-no-unwrap-001` | Production code MUST NOT use unwrap() or expect() | No matching observation found | +| MISSING | `aphoria-bridge-tier-001` | Observation-to-assertion bridge MUST assign Community tier by default | Expected observation to be present, but none found | +| MISSING | `aphoria-lifecycle-skip-001` | Observations bypass Pending lifecycle stage | Expected observation to be present, but none found | +| PASS | `aphoria-tls-verify-001` | TLS certificate verification MUST NOT be disabled in production code | Forbidden value not found (as expected) | +| PASS | `aphoria-no-tokio-core-001` | stemedb-core MUST NOT import tokio to prevent runtime coupling | Forbidden value not found (as expected) | +| PASS | `aphoria-no-md5-001` | MD5 MUST NOT be used for hashing in any security context | No observations found (no contradiction) | +| PASS | `aphoria-no-wildcard-cors-001` | CORS MUST NOT use wildcard (*) origin in production services | Forbidden value not found (as expected) | +| PASS | `aphoria-jwt-audience-001` | JWT audience validation MUST NOT be disabled | Forbidden value not found (as expected) | +| PASS | `aphoria-hsts-enabled-001` | HSTS header MUST NOT be disabled on HTTPS-serving endpoints | Forbidden value not found (as expected) | +| PASS | `aphoria-no-hardcoded-secrets-001` | API keys MUST NOT be hardcoded in source files | Forbidden value not found (as expected) | +| MISSING | `dbpool-max-conn-required-001` | max_connections MUST be a required field, not Optional | No matching observation found | +| MISSING | `dbpool-plaintext-pwd-001` | Connection strings MUST NOT contain plaintext passwords | No matching observation found | +| MISSING | `dbpool-max-lifetime-required-001` | max_lifetime MUST be a required field, not Optional | No matching observation found | +| MISSING | `dbpool-conn-timeout-max-001` | connection_timeout MUST NOT exceed 30 seconds | No matching observation found | +| MISSING | `dbpool-min-conn-minimum-001` | min_connections MUST be at least 2 | No matching observation found | +| MISSING | `dbpool-validation-required-001` | validate_on_checkout MUST be enabled | No matching observation found | +| MISSING | `dbpool-metrics-recommended-001` | Metrics collection SHOULD be enabled for production deployments | No matching observation found | +| MISSING | `httpclient-connect-timeout-001` | TCP connection timeout MUST NOT exceed 10 seconds | No matching observation found | +| MISSING | `httpclient-request-timeout-001` | HTTP request timeout MUST NOT exceed 30 seconds | No matching observation found | +| MISSING | `httpclient-read-timeout-001` | Response body read timeout MUST NOT exceed 30 seconds | No matching observation found | +| MISSING | `httpclient-idle-timeout-001` | Idle connection timeout MUST be configured | No matching observation found | +| MISSING | `httpclient-idle-timeout-default-001` | Idle timeout default SHOULD be 60 seconds | No matching observation found | +| MISSING | `httpclient-tls-cert-validation-001` | HTTPS connections MUST validate server certificates | No matching observation found | +| MISSING | `httpclient-tls-enabled-001` | HTTPS SHOULD be enabled by default for all connections | No matching observation found | +| MISSING | `httpclient-tls-min-version-001` | TLS version MUST be >= 1.2 (TLS 1.0/1.1 deprecated) | No matching observation found | +| MISSING | `httpclient-tls-ciphers-001` | TLS cipher suites SHOULD use modern ciphers only | No matching observation found | +| MISSING | `httpclient-max-redirects-001` | HTTP redirect limit MUST NOT exceed 10 | No matching observation found | +| MISSING | `httpclient-redirect-loop-001` | Redirect loop detection MUST be implemented | No matching observation found | +| MISSING | `httpclient-retry-max-001` | Retry attempts MUST NOT exceed 3 | No matching observation found | +| MISSING | `httpclient-retry-backoff-001` | Retry backoff MUST use exponential strategy | No matching observation found | +| MISSING | `httpclient-retry-idempotent-001` | Retries MUST only apply to idempotent methods | No matching observation found | +| MISSING | `httpclient-retry-post-excluded-001` | POST requests MUST be excluded from automatic retries | No matching observation found | +| MISSING | `httpclient-metrics-enabled-001` | Metrics collection SHOULD be enabled for production HTTP clients | No matching observation found | +| MISSING | `httpclient-metrics-exposed-001` | Core HTTP metrics MUST be exposed: request_count, active_connections, latency_p99, error_rate | No matching observation found | +| MISSING | `httpclient-pool-size-001` | Connection pool size SHOULD be 50-100 per host in production | No matching observation found | +| MISSING | `httpclient-pool-default-size-001` | Default pool size SHOULD be 10 connections per host | No matching observation found | +| MISSING | `httpclient-connection-pooling-001` | Connection pooling SHOULD be enabled for multi-request scenarios | No matching observation found | +| MISSING | `httpclient-user-agent-001` | User-Agent header MUST be sent with all requests | No matching observation found | +| MISSING | `httpclient-error-handling-001` | HTTP request failures MUST return Result, NEVER panic | No matching observation found | + + diff --git a/applications/aphoria/README.md b/applications/aphoria/README.md index 010737f..ca2077b 100644 --- a/applications/aphoria/README.md +++ b/applications/aphoria/README.md @@ -1,266 +1,112 @@ # Aphoria -**An autonomous knowledge compounding system powered by Episteme.** +Aphoria scans your code and finds where it contradicts authoritative standards (RFCs, OWASP, your own rules). -Aphoria is a **continuous learning flywheel** that runs on every commit, using LLM workflows to scan code, fix violations, dynamically evaluate patterns, author claims, and create extractors—constantly learning from your organization's decisions. - -## The Autonomous Loop - -``` -Developer commits code - ↓ -1. SCAN: Extractors → observations - ↓ -2. CHECK: Compare observations against claims → violations - ↓ -3. FIX: Developer fixes violations - ↓ -4. GET REMAINING CLAIMS: Identify claims without extractors - ↓ -5. CREATE EXTRACTORS: Dynamically generate extractors for uncovered claims - ↓ -6. SUGGEST NEW CLAIMS: LLM analyzes patterns → suggests new claims - ↓ -7. CREATE NEW EXTRACTORS: Generate extractors for new claims - ↓ -(Loop repeats, knowledge compounds) -``` - -**Knowledge compounds** with every commit. Each scan benefits from all previous commits' learning—not through ML training, but through accumulated structured decisions. - -## LLM-Driven Workflows - -Aphoria's autonomous operation **requires LLM integration**: - -- **Claude Code skills** - `/aphoria-claims`, `/aphoria-suggest`, `/aphoria-custom-extractor-creator` -- **Go ADK agents** - Custom tool-use agents for autonomous claim authoring -- **Any LLM with tool use** - Build your own integration via the CLI interface - -**The CLI is a debug/fallback interface**, not the primary workflow. Manual operation doesn't scale—LLMs enforce naming conventions, reason about consequences, and drive the autonomous flywheel. - -**Note:** `/aphoria-custom-extractor-creator` operates in BOTH phases: creating extractors for existing uncovered claims AND for newly suggested claims. - -## Quick Example (Via LLM Workflow) +## Install ```bash -# Developer commits code with TLS misconfiguration -$ git commit -m "Add API client" - -# LLM skill analyzes diff, finds violation -/aphoria-claims - -BLOCK code://python/requests/tls/cert_verification - Your code: verify=False (api/client.py:42) - RFC 5246: TLS certificate verification MUST be enabled - Conflict: 0.92 - -# LLM suggests fix -> Fix detected: Enable TLS verification - -# LLM creates claim for project-specific pattern -> Claim authored: api-client-tls-001 -``` - ---- - -## Getting Started - -**New to Aphoria?** Start with LLM-driven workflows: - -1. **[Load the skill](../../.claude/skills/aphoria-claims/)** - `/aphoria-claims` for commit-time claim authoring -2. **[Learn It (20 min)](dogfood/dbpool/)** - Complete worked example with database connection pool -3. **[Build an agent](../../sdk/go/adk/)** - ADK-Go integration for autonomous operation - -**Fallback (No LLM Access):** -- **[CLI Quick Start (2 min)](docs/guides/solo-developer-guide.md#quick-start-2-minutes)** - Manual scan workflow (debug interface) - -See [Getting Started Hub](docs/guides/) for all paths. - ---- - -## CLI Reference (Debug/Fallback Interface) - -**⚠️ The CLI is for debugging, testing, and environments without LLM access. For production workflows, use [LLM-driven skills](#llm-driven-workflows).** - -### Install - -```bash -# From source -cd applications/aphoria -cargo install --path . - -# Verify +cargo install --path applications/aphoria aphoria --version ``` -### Initialize +## Quick Start ```bash +cd your-project + +# Initialize (loads RFC/OWASP corpus into local database) aphoria init + +# Scan +aphoria scan ``` -This sets up your local database. The corpus (RFCs, OWASP guidelines, community patterns) is built dynamically during scans. +Output: -**Bootstrap corpus (optional):** -```bash -# Import patterns from wiki documentation (LLM skill recommended) -aphoria corpus import wiki ~/docs/security-best-practices/ +``` +BLOCK code://node/server/tls/cert_verification + Your code: rejectUnauthorized: false (server.js:42) + RFC 5246: TLS certificate verification MUST be enabled + Conflict: 0.92 + +BLOCK code://node/auth/jwt/algorithm + Your code: algorithms: ["none"] (auth.js:15) + RFC 7519: 'none' algorithm MUST NOT be accepted + Conflict: 0.98 + +2 conflicts found (2 BLOCK). ``` -### Scan (Manual Mode) +## Handle Conflicts -```bash -# Quick scan (ephemeral, fast) -aphoria scan . +**Fix the code** (preferred): -# With persistence (enables diff/baseline, required for flywheel) -aphoria scan --persist - -# With sync (enables community learning, required for flywheel) -aphoria scan --persist --sync - -# CI mode (exit code 1 on BLOCK) -aphoria scan --exit-code - -# Pre-commit (staged files only) -aphoria scan --staged --exit-code -``` - -**⚠️ Manual scanning alone does NOT activate the flywheel.** The flywheel requires LLM workflows to evaluate patterns, suggest claims, and create extractors autonomously. - -### Debug Extractor Alignment - -When extractors aren't detecting violations, use these commands to diagnose issues: - -#### Show Observations - -See all observations created during scan with concept paths: - -```bash -aphoria scan --show-observations -``` - -**Output shows:** -- All observations with concept paths, predicates, and values -- File locations and matched text -- Which claims matched (✅) or didn't match (❌) -- Tail-path analysis for debugging mismatches - -**Use case:** Debugging why extractors aren't detecting violations. Helps identify concept_path mismatches between extractors and claims. - -#### Validate Extractors - -Check extractor configuration before scanning: - -```bash -aphoria extractors validate -``` - -**Output shows:** -- ✅ Valid extractors (subject matches a claim) -- ❌ Invalid extractors (subject doesn't match any claim) -- Suggestions for fixing mismatches - -**Example fix:** -```toml -# BEFORE (invalid): -[[extractors.declarative]] -[extractors.declarative.claim] -subject = "queue/max_size" # ❌ No claim with this path - -# AFTER (valid): -[[extractors.declarative]] -[extractors.declarative.claim] -subject = "msgqueue/queue/max_size" # ✅ Matches claim msgqueue-015 -``` - -**Use case:** Pre-flight check before scanning. Catches subject/concept_path mismatches upfront, saving debugging time. - -#### Test Single Extractor - -Test an extractor against a specific file without running full scan: - -```bash -aphoria extractors test EXTRACTOR_NAME --file PATH - -# Example: -aphoria extractors test timeout_zero_detector --file src/config.rs -``` - -**Output shows:** -- Whether pattern matches code -- Which lines matched -- What observation would be created -- Troubleshooting tips if no match - -**Use cases:** -- Debug why extractor isn't finding violations -- Test pattern against expected code -- Verify observation format before scanning -- Faster iteration when creating extractors (< 5 seconds per test vs full scan) - -**Iterative development workflow:** -1. Create extractors → 2. `aphoria extractors validate` → 3. Fix subjects → 4. `aphoria extractors test` for each → 5. `aphoria scan --show-observations` → 6. Iterate - -This workflow enables rapid iteration when building custom extractors. - -### Handle Conflicts - -**Fix the code:** ```python -# Before: verify=False -# After: +# Before +requests.get(url, verify=False) +# After requests.get(url, verify=True) ``` -**Or acknowledge intentionally:** +**Or acknowledge intentionally** (creates an audit trail): + ```bash aphoria ack "code://python/requests/tls/cert_verification" \ --reason "Local dev environment with self-signed certs" ``` ---- - -## Key Concepts: Observations vs Claims - -Aphoria distinguishes between two types of extracted information: - -| Type | What it is | Who creates it | Example | -|------|-----------|----------------|---------| -| **Observation** | Pattern match: "this code does X" | Extractors (automated) | `imports/tokio: true` | -| **Claim** | Rule: "code MUST do X because Y" | Humans (you!) | "Core MUST NOT import tokio because it creates runtime coupling" | - -**Observations** are what extractors find - they're grep results with confidence scores. They have no opinion about whether something is good or bad. - -**Claims** are human-authored rules with: -- **Provenance** - Where the rule came from (RFC, security review, architecture decision) -- **Invariant** - What must stay true ("Wallet MUST NOT derive Clone") -- **Consequence** - What breaks if violated ("Multiple wallet instances → double-spend") -- **Authority tier** - How much weight this rule carries -- **Evidence** - Supporting artifacts (ADRs, test cases, etc.) - -When you run `aphoria scan`, it compares observations against: -1. **Authoritative corpus** - RFC/OWASP standards + community patterns (emergent from real usage) -2. **Your authored claims** - Project-specific rules in `.aphoria/claims.toml` - -The corpus is **emergent**: patterns with 95%+ adoption across projects auto-promote to authoritative status. - -See [Claims-Based Verification](#claims-based-verification) below for creating your own claims. - ---- - -## Output Formats +## Scan Options ```bash -aphoria scan --format table # Human-readable (default) -aphoria scan --format json # Machine-readable -aphoria scan --format sarif # GitHub Security tab -aphoria scan --format markdown # Documentation +aphoria scan # Quick scan (default) +aphoria scan --persist # Persist results (enables diff/baseline) +aphoria scan --persist --sync # Persist + community learning +aphoria scan --exit-code # Exit 1 on BLOCK (for CI) +aphoria scan --staged # Staged files only (for pre-commit) +aphoria scan --show-observations # Debug: see all extractor output +aphoria scan --format json # Also: table, markdown, sarif ``` ---- +**Latest scan report:** [LATEST-SCAN.md](LATEST-SCAN.md) -## Pre-commit Integration +## Verdicts + +| Verdict | Meaning | CI Behavior | +|---------|---------|-------------| +| **BLOCK** | High-confidence conflict with RFC/OWASP | Fails with `--exit-code` | +| **FLAG** | Moderate-confidence conflict | Passes, visible in report | +| **ACK** | Acknowledged conflict | Passes, tracked for audit | +| **PASS** | No conflict | - | + +## Author Claims + +Claims are project-specific rules with provenance and consequences. They go beyond the built-in corpus. + +```bash +aphoria claims create \ + --id wallet-no-clone-001 \ + --concept-path maxwell/core/wallet/type/wallet/derives \ + --predicate traits --value Clone --comparison not_contains \ + --provenance "Wallet is singleton with atomic state" \ + --invariant "Wallet type MUST NOT derive Clone" \ + --consequence "Clone allows multiple instances, breaking single-balance invariant" \ + --tier expert --category safety --by jml + +# Verify claims against code +aphoria verify run +``` + +Or mark claims inline: + +```rust +// @aphoria:claim[safety] Wallet MUST NOT derive Clone +#[derive(Debug)] +pub struct Wallet { ... } +``` + +Then formalize: `aphoria claims formalize-marker --id wallet-no-clone-001 --by jml` + +## Pre-commit Hook ```yaml # .pre-commit-config.yaml @@ -274,9 +120,7 @@ repos: pass_filenames: false ``` ---- - -## CI Integration (GitHub Actions) +## CI Integration ```yaml - name: Install Aphoria @@ -291,252 +135,46 @@ repos: sarif_file: results.sarif ``` ---- - ## Key Commands -### Scanning | Command | Description | |---------|-------------| -| `aphoria scan` | Scan for conflicts with authoritative sources | -| `aphoria ack` | Acknowledge a conflict as intentional | -| `aphoria bless` | Define a pattern as your authoritative standard | +| `aphoria scan` | Scan for conflicts | +| `aphoria ack` | Acknowledge a conflict | +| `aphoria bless` | Define a local standard | +| `aphoria claims create` | Author a claim | +| `aphoria claims list` | List claims | +| `aphoria verify run` | Verify claims against code | +| `aphoria extractors validate` | Check extractor config | +| `aphoria extractors test NAME --file PATH` | Test a single extractor | +| `aphoria policy export` | Export standards as Trust Pack | +| `aphoria policy import` | Import a Trust Pack | -### Claims Management -| Command | Description | -|---------|-------------| -| `aphoria claims create` | Author a new claim with provenance and consequences | -| `aphoria claims list` | List all authored claims | -| `aphoria claims explain` | Generate detailed claim explanations | -| `aphoria claims update` | Update an existing claim | -| `aphoria claims supersede` | Mark claim as superseded by newer claim | -| `aphoria claims deprecate` | Deprecate a claim with reason | +See [CLI Reference](docs/reference/cli-reference.md) for all commands. -### Inline Markers -| Command | Description | -|---------|-------------| -| `aphoria claims list-markers` | List pending inline claim markers | -| `aphoria claims formalize-marker` | Convert marker to full claim | -| `aphoria claims reject-marker` | Reject an inline marker | +## Automate with LLM Workflows -### Verification -| Command | Description | -|---------|-------------| -| `aphoria verify run` | Verify authored claims against codebase | -| `aphoria verify map` | Show extractor-to-claim coverage map | +For continuous, autonomous operation, integrate LLM workflows that scan on every commit, author claims from diffs, and create extractors automatically: -### Policy & Governance -| Command | Description | -|---------|-------------| -| `aphoria policy export` | Export standards as a Trust Pack | -| `aphoria policy import` | Import a Trust Pack from your security team | -| `aphoria governance pending` | List approval requests (Phase 14) | -| `aphoria audit export` | Export audit trail for SOC 2 compliance | +- **Claude Code skills**: `/aphoria-claims`, `/aphoria-suggest`, `/aphoria-custom-extractor-creator` +- **Go ADK agents**: [sdk/go/adk/](../../sdk/go/adk/) +- **Any LLM with tool use**: Drive Aphoria via CLI -See [CLI Reference](docs/reference/cli-reference.md) for complete command documentation. +See [The Autonomous Loop](docs/guides/golden-path-loop.md) for the full commit-time flywheel. ---- +## Guides -## Claims-Based Verification - -Beyond scanning for RFC/OWASP conflicts, Aphoria supports **human-authored claims** that encode your project's architectural decisions and safety invariants. - -### Quick Example - -```bash -# Author a claim -aphoria claims create \ - --id wallet-no-clone-001 \ - --concept-path maxwell/core/wallet/type/wallet/derives \ - --predicate traits \ - --value Clone \ - --comparison not_contains \ - --provenance "Wallet is singleton with atomic state" \ - --invariant "Wallet type MUST NOT derive Clone" \ - --consequence "Clone allows multiple instances, breaking single-balance invariant" \ - --tier expert \ - --category safety \ - --by jml - -# Verify claim against codebase -aphoria verify run - -# Output: -# PASS wallet-no-clone-001 | maxwell/core/wallet/type/wallet/derives/traits -# Clone not found (as expected) -``` - -### Comparison Modes - -Claims support six comparison modes for different verification patterns: - -- `equals` - Value must be exactly X -- `not_equals` - Value must NOT be X -- `present` - Something must exist at this path -- `absent` - Nothing should exist at this path -- `contains` - Value must contain substring/list element (e.g., "Serialize" in "Clone,Debug,Serialize") -- `not_contains` - Value must NOT contain substring/list element (e.g., "Clone" NOT in derives) - -See [Comparison Modes Guide](docs/reference/comparison-modes.md) for detailed examples and decision tree. - -### Inline Markers - -Mark claims directly in code with special comments: - -```rust -// @aphoria:claim[safety] Wallet MUST NOT derive Clone -#[derive(Debug)] -pub struct Wallet { ... } -``` - -Then formalize them: -```bash -aphoria claims list-markers -aphoria claims formalize-marker marker-001 --id wallet-no-clone-001 --by jml -``` - -### Git Commit Tracking - -Aphoria automatically captures the git commit hash when claims and observations are ingested. This provides: -- **Temporal context** - Know exactly which code version a claim was authored against -- **Audit trail** - Trace architectural decisions through git history -- **Graceful degradation** - Works seamlessly in non-git environments - -The commit hash is stored in assertion metadata and captured at ingestion time (not when TOML files are edited), avoiding the "double-commit problem." - -```json -{ - "authored": true, - "git_commit": "de7af7c1b9e...", - "claim_id": "wallet-no-clone-001", - "provenance": "Wallet is singleton with atomic state" -} -``` - -### Bulk Import Claims - -Import claims in bulk from TOML files instead of creating them one-by-one via CLI. - -**Quick start:** -```bash -# Generate template -aphoria claims import --template > my-claims.toml - -# Validate format -aphoria claims import my-claims.toml --validate-only - -# Preview changes -aphoria claims import my-claims.toml --dry-run - -# Import for real -aphoria claims import my-claims.toml -``` - -**Benefits:** -- **Faster:** Import 22 claims in <1 second (vs. 15 minutes for shell scripts) -- **Safer:** Pre-import validation catches all errors before any writes -- **Clearer:** TOML format is more readable than 340 lines of bash -- **Atomic:** All claims imported or none (no partial writes on error) - -**Merge strategies:** -- `--merge skip_existing` (default) - Skip claims with duplicate IDs -- `--merge overwrite` - Replace existing claims with same ID -- `--merge fail_on_duplicate` - Exit with error if any ID exists - -**Output formats:** -- `--format table` (default) - Human-readable with symbols (✓, ⊗, ↻) -- `--format json` - Machine-readable for tooling integration - -See [Bulk Import Guide](docs/guides/bulk-claim-import.md) for complete documentation and examples. - ---- - -## Conflict Verdicts - -| Verdict | Description | CI Behavior | -|---------|-------------|-------------| -| **BLOCK** | High-confidence conflict with RFC/OWASP | Fails with `--exit-code` | -| **FLAG** | Moderate-confidence conflict | Passes, visible in report | -| **ACK** | Acknowledged conflict | Passes, tracked for audit | -| **PASS** | No conflict | - | - ---- - -## Web Dashboard - -Aphoria includes a web-based dashboard for visualizing scan results, managing claims, and exploring the authoritative corpus. See [`applications/aphoria-dashboard/`](../aphoria-dashboard/) for setup instructions. - -Features: -- Real-time scan visualization -- Claims management interface -- Corpus exploration and search -- Policy governance workflows - ---- - -## Documentation - -### Guides -| Guide | Audience | Time | -|-------|----------|------| -| [Solo Developer Guide](docs/guides/solo-developer-guide.md) | Individual developers, side projects | 2 min | -| [Enterprise Pilot Guide](docs/guides/enterprise-pilot-guide.md) | Security teams running pilots | 4 weeks | -| [Enterprise Quick Start](docs/guides/enterprise-quick-start.md) | Platform engineering | 5 min | -| [The First Scan](docs/guides/the-first-scan.md) | Everyone | 10 min | - -### Reference -| Document | Description | -|----------|-------------| -| [CLI Reference](docs/reference/cli-reference.md) | Complete command documentation | -| [Comparison Modes](docs/reference/comparison-modes.md) | Guide to claim comparison modes | -| [Declarative Extractors](docs/extractors/declarative-extractors.md) | Complete field reference for declarative extractors | - -### Examples -| Example | Description | -|---------|-------------| -| [Timeout Zero Detection](docs/examples/extractors/timeout-zero-example.md) | End-to-end example: code → extractor → claim → conflict | - -### Dogfooding -| Document | Description | -|----------|-------------| -| [Common Mistakes](docs/dogfooding-common-mistakes.md) | Common mistakes during dogfooding exercises with fixes | -| [msgqueue Evaluation](dogfood/msgqueue/eval/EVALUATION-REPORT-2026-02-10.md) | Day 3 failure analysis and documentation gaps | - ---- - -## Research & Reference - -### Vision & Architecture -| Document | Description | -|----------|-------------| -| [Vision](vision.md) | Product vision and aspirational architecture | -| [Protocol Vision](docs/advanced/eap-protocol.md) | Protocol-level design philosophy | -| [Architecture Docs](docs/architecture/README.md) | System design, concept matching, extension points | - -### Testing & Validation -| Document | Description | -|----------|-------------| -| [UAT Reports](../../uat/README.md) | User acceptance testing results | -| [Phase 6 UAT](../../uat/phase6-uat.md) | Detailed validation of policy workflows | -| [Real-World Policy Source UAT](../../uat/2026-02-04-uat-real-world-policy-source.md) | Trust Pack workflow validation | - -### Historical Documents (Archived) -| Document | Description | -|----------|-------------| -| [Vision & Gaps (2026-02-08)](docs/archive/vision-gaps-2026-02-08.md) | Historical: Architecture analysis and implementation status | -| [Gap Analysis: Institutional Knowledge](docs/archive/gap-analysis-institutional-knowledge-2026-02.md) | Historical: Knowledge capture gap analysis | -| [Gap Fixes Summary](docs/gap-fixes-summary.md) | Summary of addressed gaps | - ---- +| Guide | Audience | +|-------|----------| +| [Solo Developer Guide](docs/guides/solo-developer-guide.md) | Individual developers (2 min) | +| [The First Scan](docs/guides/the-first-scan.md) | Detailed walkthrough (10 min) | +| [Enterprise Quick Start](docs/guides/enterprise-quick-start.md) | Platform engineering (5 min) | +| [Declarative Extractors](docs/extractors/declarative-extractors.md) | Custom pattern matching | +| [Comparison Modes](docs/reference/comparison-modes.md) | Claim verification patterns | +| [Worked Example](dogfood/dbpool/) | Database connection pool (20 min) | ## What Aphoria Is Not - **Not a linter.** Linters check syntax. Aphoria checks decisions against authoritative sources. - **Not SAST.** SAST finds vulnerability patterns. Aphoria finds contradictions to specific standards. -- **Not AI autocomplete.** Copilot suggests code from the internet. Aphoria surfaces *your org's* decisions at the moment you contradict them. - ---- - -## License - -See [LICENSE](../../LICENSE) for details. +- **Not AI autocomplete.** Copilot suggests code. Aphoria surfaces *your org's* decisions when you contradict them. diff --git a/applications/aphoria/docs/guides/README.md b/applications/aphoria/docs/guides/README.md index 5c69c48..23d4f69 100644 --- a/applications/aphoria/docs/guides/README.md +++ b/applications/aphoria/docs/guides/README.md @@ -1,123 +1,45 @@ # Aphoria Guides -**Aphoria is an autonomous learning system powered by LLM workflows.** Choose your integration path: +## Getting Started ---- - -## 🤖 I Want Autonomous Operation (Recommended) - -**LLM-Driven Workflows:** Skills, agents, or custom integrations - -**Claude Code Skills:** -- Load `/aphoria-claims` - Commit-time claim authoring -- Load `/aphoria-suggest` - Pattern-based claim suggestions -- Load `/aphoria-custom-extractor-creator` - Generate custom extractors - -**Go ADK Agents:** -- See [ADK-Go Integration](../../../sdk/go/adk/) - Fully autonomous tool-use agents - -**Custom Integration:** -- Any LLM with tool-use capability can drive Aphoria via CLI - -**Why LLM workflows?** -- Enforce naming conventions (manual errors break tail-path matching) -- Reason about consequences (not just pattern matching) -- Suggest claims from patterns automatically -- Create extractors for custom patterns -- **Enable the autonomous flywheel** (scan→fix→evaluate→claim→create) - -**The CLI is a debug/fallback interface.** For production use, integrate LLM workflows. - ---- - -## 📚 I Want to Learn It (20 minutes) - -**Worked Example:** Follow a complete use case from documentation → claims → violations → fixes - -[Database Connection Pool Example](../../dogfood/dbpool/) - See how a solo developer: -1. Extracts 25-30 claims from HikariCP/PostgreSQL docs -2. Writes code (with intentional violations) -3. Runs Aphoria scan (catches all 7-8 violations) -4. Fixes violations incrementally -5. Reaches production-ready code - -**What you get:** -- Complete claim extraction walkthrough with decision framework -- Pre-flight validator to check your environment -- Expected output examples for every command -- Real scan results showing BLOCK/FLAG/PASS verdicts - -**Time:** 20 minutes to read, 5 days to execute (optional) - ---- - -## 🚀 Fallback: No LLM Access (Debug Interface) - -**CLI-Only Mode:** For environments without LLM access or debugging - -**⚠️ Limitations:** -- Manual claim authoring (naming errors break tail-path matching) -- No autonomous flywheel (scan only, no evaluate/claim/create) -- Requires manual pattern analysis - -## 🔧 I Want to Integrate It (30 minutes) - -**Production Integration:** Pre-commit hooks, CI/CD, team workflows - -See: -- [Pre-Flight Checks Guide](./pre-flight-checks.md) - Git hooks and CI integration -- [Enterprise Quick Start](./enterprise-quick-start.md) - Team deployment -- [Multi-Team Policy Governance](./multi-team-policy-governance.md) - Scaling to multiple teams - ---- - -## Getting Started Guides - -| Guide | Audience | Description | -|-------|----------|-------------| -| [Solo Developer Guide](./solo-developer-guide.md) | Individual developers | Get immediate value on personal or side projects | -| [Enterprise Pilot Guide](./enterprise-pilot-guide.md) | Security teams | Run a measurable pilot with stakeholder buy-in | -| [Enterprise Quick Start](./enterprise-quick-start.md) | Platform engineering | 5-minute path from git clone to enforcing standards | -| [The First Scan](./the-first-scan.md) | Everyone | Your first Aphoria scan walkthrough | -| [Pre-Flight Checks](./pre-flight-checks.md) | DevOps | Pre-commit and CI integration | +| Guide | Audience | Time | +|-------|----------|------| +| [Solo Developer Guide](./solo-developer-guide.md) | Individual developers, side projects | 2 min | +| [The First Scan](./the-first-scan.md) | Detailed walkthrough for everyone | 10 min | +| [Enterprise Quick Start](./enterprise-quick-start.md) | Platform engineering teams | 5 min | +| [Enterprise Pilot Guide](./enterprise-pilot-guide.md) | Security teams running pilots | 4 weeks | ## Core Workflows | Guide | Description | |-------|-------------| -| [Bulk Claim Import](./bulk-claim-import.md) | Import claims in bulk from TOML files with validation | +| [Bulk Claim Import](./bulk-claim-import.md) | Import claims from TOML files | | [Federating Truth](./federating-truth.md) | Trust Pack creation and distribution | | [Multi-Team Policy Governance](./multi-team-policy-governance.md) | Managing policies across teams | | [Policy Audit Trails](./policy-audit-trails.md) | Compliance and auditing | -| [Authoritative State Per Project](./authoritative-state-per-project.md) | Project-specific policy management | +| [Pre-Flight Checks](./pre-flight-checks.md) | Pre-commit and CI integration | -## Advanced Topics +## Advanced | Guide | Description | |-------|-------------| -| [Golden Path Loop](./golden-path-loop.md) | Continuous policy improvement | +| [Golden Path Loop](./golden-path-loop.md) | Autonomous commit-time flywheel | +| [LLM Wiki Extraction](./llm-wiki-extraction.md) | Extract claims from docs using LLM | | [AAA Game Development](./aaa-game-development.md) | Unreal Engine patterns | -| [LLM Wiki Extraction](./llm-wiki-extraction.md) | Extract claims from technical docs using LLM skill | -## Reference Materials +## LLM Automation + +For autonomous operation, integrate LLM workflows: + +- **Claude Code skills**: `/aphoria-claims`, `/aphoria-suggest`, `/aphoria-custom-extractor-creator` +- **Go ADK agents**: [sdk/go/adk/](../../../sdk/go/adk/) + +## Reference | Document | Purpose | |----------|---------| | [CLI Reference](../reference/cli-reference.md) | Complete command documentation | -| [Comparison Modes](../reference/comparison-modes.md) | How Aphoria evaluates conflicts | -| [Configuration](../reference/configuration.md) | .aphoria/config.toml reference | -| [Architecture](../architecture/README.md) | System design and algorithms | - -## UAT Results - -See [UAT Reports](../../uat/) for validation results: -- [Policy Source Tracking UAT](../../uat/2026-02-04-uat-real-world-policy-source.md) - Trust Pack workflow validation - ---- - -## Support - -- **Installation issues:** See [Solo Developer Guide](./solo-developer-guide.md#quick-start-2-minutes) -- **Scan not finding violations:** Check [Troubleshooting](../reference/cli-reference.md#troubleshooting) -- **Custom extractors:** See [Architecture: Extractors](../architecture/README.md#extractors) -- **Enterprise deployment:** See [Enterprise Pilot Guide](./enterprise-pilot-guide.md) +| [Comparison Modes](../reference/comparison-modes.md) | Claim comparison modes | +| [Configuration](../reference/configuration.md) | `.aphoria/config.toml` reference | +| [Declarative Extractors](../extractors/declarative-extractors.md) | Custom extractor field reference | +| [Architecture](../architecture/README.md) | System design | diff --git a/applications/aphoria/docs/guides/solo-developer-guide.md b/applications/aphoria/docs/guides/solo-developer-guide.md index bffbc2a..a06e0a3 100644 --- a/applications/aphoria/docs/guides/solo-developer-guide.md +++ b/applications/aphoria/docs/guides/solo-developer-guide.md @@ -41,14 +41,7 @@ cd /path/to/your-project aphoria init ``` -This creates `.aphoria/config.toml` and loads the authoritative corpus (RFCs, OWASP) into your local database. - -**Expected output:** -``` -✓ Created .aphoria/config.toml -✓ Loaded 247 authoritative claims from corpus -✓ Project initialized: your-project -``` +This creates `.aphoria/` and loads the authoritative corpus (RFCs, OWASP) into your local database. --- diff --git a/applications/aphoria/docs/guides/the-first-scan.md b/applications/aphoria/docs/guides/the-first-scan.md index bb4692f..44553be 100644 --- a/applications/aphoria/docs/guides/the-first-scan.md +++ b/applications/aphoria/docs/guides/the-first-scan.md @@ -31,20 +31,17 @@ $ aphoria --version aphoria 0.1.0 ``` -## 2. Initialize the Cortex +## 2. Initialize -Before scanning, Aphoria needs to know "the truth." It needs a corpus of authoritative assertions (RFCs, OWASP cheat sheets, vendor docs). +Aphoria needs a corpus of authoritative assertions (RFCs, OWASP) to scan against. ```bash $ aphoria init -Initializing Aphoria... -Ingested 1,240 authoritative assertions. -Ready. ``` -This downloads strict security requirements (RFC 7519 for JWT, RFC 5246 for TLS, etc.) into your project database (`.aphoria/db`). +This creates `.aphoria/` in your project and loads the authoritative corpus (RFC 7519, RFC 5246, OWASP guidelines, etc.) into a local database. -> **Note:** By default, each project has its own isolated database. To share a database across all projects on your machine, set `data_dir = "~/.aphoria/db"` in `aphoria.toml`. +Each project has its own isolated database by default. ## 3. The First Scan diff --git a/applications/aphoria/src/llm/prompts.rs b/applications/aphoria/src/llm/prompts.rs index 6f24b69..736c9c1 100644 --- a/applications/aphoria/src/llm/prompts.rs +++ b/applications/aphoria/src/llm/prompts.rs @@ -50,6 +50,7 @@ pub fn language_to_prefix(language: Language) -> &'static str { Language::Python => "python", Language::JavaScript => "javascript", Language::TypeScript => "typescript", + Language::C => "c", Language::Cpp => "cpp", Language::Java => "java", Language::Php => "php", @@ -79,6 +80,7 @@ pub fn language_to_name(language: Language) -> &'static str { Language::Python => "Python", Language::JavaScript => "JavaScript", Language::TypeScript => "TypeScript", + Language::C => "C", Language::Cpp => "C++", Language::Java => "Java", Language::Php => "PHP", @@ -108,6 +110,7 @@ pub fn language_to_extension(language: Language) -> &'static str { Language::Python => "python", Language::JavaScript => "javascript", Language::TypeScript => "typescript", + Language::C => "c", Language::Cpp => "cpp", Language::Java => "java", Language::Php => "php", diff --git a/applications/aphoria/src/promotion/regex_gen.rs b/applications/aphoria/src/promotion/regex_gen.rs index 6fe4045..d1b4519 100644 --- a/applications/aphoria/src/promotion/regex_gen.rs +++ b/applications/aphoria/src/promotion/regex_gen.rs @@ -233,6 +233,7 @@ fn language_to_string(lang: Language) -> String { Language::Python => "python", Language::TypeScript => "typescript", Language::JavaScript => "javascript", + Language::C => "c", Language::Cpp => "cpp", Language::Java => "java", Language::Php => "php", diff --git a/applications/aphoria/src/types/language.rs b/applications/aphoria/src/types/language.rs index f43d69e..7db6ab2 100644 --- a/applications/aphoria/src/types/language.rs +++ b/applications/aphoria/src/types/language.rs @@ -20,6 +20,8 @@ pub enum Language { TypeScript, /// JavaScript source files. JavaScript, + /// C source files (.c). + C, /// C++ source files (including headers). Cpp, /// Java source files. @@ -67,6 +69,7 @@ impl fmt::Display for Language { Language::Python => "python", Language::TypeScript => "typescript", Language::JavaScript => "javascript", + Language::C => "c", Language::Cpp => "cpp", Language::Java => "java", Language::Php => "php", @@ -101,6 +104,7 @@ impl FromStr for Language { "python" | "py" => Ok(Language::Python), "typescript" | "ts" => Ok(Language::TypeScript), "javascript" | "js" => Ok(Language::JavaScript), + "c" => Ok(Language::C), "cpp" | "c++" => Ok(Language::Cpp), "java" => Ok(Language::Java), "php" => Ok(Language::Php), @@ -159,6 +163,7 @@ impl Language { "go.mod" => return Language::GoMod, "package.json" => return Language::NpmManifest, "requirements.txt" | "pyproject.toml" => return Language::PythonManifest, + "Makefile" | "CMakeLists.txt" => return Language::C, _ if file_name.starts_with("Dockerfile") => return Language::Docker, _ if file_name.starts_with("docker-compose") => return Language::Docker, _ if file_name.starts_with(".env") => return Language::Dotenv, @@ -172,6 +177,7 @@ impl Language { "py" => Language::Python, "ts" | "tsx" => Language::TypeScript, "js" | "jsx" => Language::JavaScript, + "c" => Language::C, "cpp" | "cxx" | "cc" | "h" | "hpp" => Language::Cpp, "java" => Language::Java, "php" => Language::Php, @@ -197,6 +203,9 @@ mod tests { assert_eq!(Language::from_path(Path::new("src/main.rs")), Language::Rust); assert_eq!(Language::from_path(Path::new("main.go")), Language::Go); assert_eq!(Language::from_path(Path::new("app.py")), Language::Python); + assert_eq!(Language::from_path(Path::new("main.c")), Language::C); + assert_eq!(Language::from_path(Path::new("Makefile")), Language::C); + assert_eq!(Language::from_path(Path::new("CMakeLists.txt")), Language::C); assert_eq!(Language::from_path(Path::new("game.cpp")), Language::Cpp); assert_eq!(Language::from_path(Path::new("header.hpp")), Language::Cpp); assert_eq!(Language::from_path(Path::new("config.ini")), Language::Ini); @@ -227,6 +236,7 @@ mod tests { assert_eq!(Language::from_str("ts").unwrap(), Language::TypeScript); assert_eq!(Language::from_str("javascript").unwrap(), Language::JavaScript); assert_eq!(Language::from_str("js").unwrap(), Language::JavaScript); + assert_eq!(Language::from_str("c").unwrap(), Language::C); assert_eq!(Language::from_str("cpp").unwrap(), Language::Cpp); assert_eq!(Language::from_str("c++").unwrap(), Language::Cpp); assert_eq!(Language::from_str("java").unwrap(), Language::Java); diff --git a/applications/aphoria/src/walker/path_mapper.rs b/applications/aphoria/src/walker/path_mapper.rs index 75bc512..6676b15 100644 --- a/applications/aphoria/src/walker/path_mapper.rs +++ b/applications/aphoria/src/walker/path_mapper.rs @@ -35,6 +35,7 @@ impl PathMapper { Language::Python | Language::PythonManifest => "python", Language::TypeScript => "typescript", Language::JavaScript | Language::NpmManifest => "javascript", + Language::C => "c", Language::Cpp => "cpp", Language::Java => "java", Language::Php => "php",