stemedb/applications/aphoria

Aphoria

Aphoria scans your code and finds where it contradicts authoritative standards (RFCs, OWASP, your own rules).

Install

cargo install --path applications/aphoria
aphoria --version

Quick Start

cd your-project

# Initialize (loads RFC/OWASP corpus into local database)
aphoria init

# Scan
aphoria scan

Output:

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

Handle Conflicts

Fix the code (preferred):

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

Or acknowledge intentionally (creates an audit trail):

aphoria ack "code://python/requests/tls/cert_verification" \
  --reason "Local dev environment with self-signed certs"

Scan Options

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

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.

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:

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

Then formalize: aphoria claims formalize-marker <marker-id> --id wallet-no-clone-001 --by jml

Pre-commit Hook

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

- 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

Command	Description
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

See CLI Reference for all commands.

Automate with LLM Workflows

For continuous, autonomous operation, integrate LLM workflows that scan on every commit, author claims from diffs, and create extractors automatically:

• Claude Code skills: /aphoria-claims, /aphoria-suggest, /aphoria-custom-extractor-creator
• Go ADK agents: sdk/go/adk/
• Any LLM with tool use: Drive Aphoria via CLI

See The Autonomous Loop for the full commit-time flywheel.

Guides

Guide	Audience
Solo Developer Guide	Individual developers (2 min)
The First Scan	Detailed walkthrough (10 min)
Enterprise Quick Start	Platform engineering (5 min)
Declarative Extractors	Custom pattern matching
Comparison Modes	Claim verification patterns
Worked Example	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. Aphoria surfaces your org's decisions when you contradict them.