stemedb/applications/aphoria

Aphoria

An autonomous knowledge compounding system powered by Episteme.

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)

# 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 - /aphoria-claims for commit-time claim authoring
2. Learn It (20 min) - Complete worked example with database connection pool
3. Build an agent - ADK-Go integration for autonomous operation

Fallback (No LLM Access):

• CLI Quick Start (2 min) - Manual scan workflow (debug interface)

See Getting Started Hub 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.

Install

# From source
cd applications/aphoria
cargo install --path .

# Verify
aphoria --version

Initialize

aphoria init

This sets up your local database. The corpus (RFCs, OWASP guidelines, community patterns) is built dynamically during scans.

Bootstrap corpus (optional):

# Import patterns from wiki documentation (LLM skill recommended)
aphoria corpus import wiki ~/docs/security-best-practices/

Scan (Manual Mode)

# Quick scan (ephemeral, fast)
aphoria scan .

# 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:

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:

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:

# 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:

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)

Typical Day 3 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 reduces Day 3 debugging time from ~70 minutes to ~30 minutes.

Handle Conflicts

Fix the code:

# Before: verify=False
# After:
requests.get(url, verify=True)

Or acknowledge intentionally:

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 below for creating your own claims.

---

Output Formats

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

---

Pre-commit Integration

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: aphoria
        name: Aphoria truth check
        entry: aphoria scan --staged --exit-code
        language: system
        pass_filenames: false

---

CI Integration (GitHub Actions)

- name: Install Aphoria
  run: cargo install --path applications/aphoria

- name: Run Aphoria Scan
  run: aphoria scan --exit-code --format sarif > results.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v2
  with:
    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

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

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

Verification

Command	Description
aphoria verify run	Verify authored claims against codebase
aphoria verify map	Show extractor-to-claim coverage map

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

See CLI Reference for complete command documentation.

---

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

# 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 for detailed examples and decision tree.

Inline Markers

Mark claims directly in code with special comments:

// @aphoria:claim[safety] Wallet MUST NOT derive Clone
#[derive(Debug)]
pub struct Wallet { ... }

Then formalize them:

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."

{
  "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:

# 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 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/ 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	Individual developers, side projects	2 min
Enterprise Pilot Guide	Security teams running pilots	4 weeks
Enterprise Quick Start	Platform engineering	5 min
The First Scan	Everyone	10 min

Reference

Document	Description
CLI Reference	Complete command documentation
Comparison Modes	Guide to claim comparison modes
Declarative Extractors	Complete field reference for declarative extractors
Vision & Gaps	Architecture and implementation status

Examples

Example	Description
Timeout Zero Detection	End-to-end example: code → extractor → claim → conflict

Dogfooding

Document	Description
Common Mistakes	Common mistakes during dogfooding exercises with fixes
msgqueue Evaluation	Day 3 failure analysis and documentation gaps

---

Research & Reference

Vision & Architecture

Document	Description
Vision	Product vision and aspirational architecture
Protocol Vision	Protocol-level design philosophy
Vision & Gaps	Honest assessment of current state vs. vision
Architecture Docs	System design, concept matching, extension points

Testing & Validation

Document	Description
UAT Reports	User acceptance testing results
Phase 6 UAT	Detailed validation of policy workflows
Real-World Policy Source UAT	Trust Pack workflow validation

Gap Analysis & Research

Document	Description
Gap Analysis: Institutional Knowledge	Analysis of knowledge capture gaps
Gap Fixes Summary	Summary of addressed gaps

---

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 for details.