stemedb/applications/aphoria

Aphoria

A code-level truth linter powered by Episteme.

Aphoria scans your codebase for configuration patterns that contradict authoritative technical standards (RFCs, OWASP, vendor docs). Unlike linters that check syntax or SAST tools that find vulnerability patterns, Aphoria validates intent against authority.

$ aphoria scan .

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

1 conflict found (1 BLOCK).

---

Quick Start

Install

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

# Verify
aphoria --version

Initialize

aphoria init

This loads the authoritative corpus (RFCs, OWASP guidelines) into your local database.

Scan

# Quick scan (ephemeral, fast)
aphoria scan .

# With persistence (enables diff/baseline)
aphoria scan --persist

# CI mode (exit code 1 on BLOCK)
aphoria scan --exit-code

# Pre-commit (staged files only)
aphoria scan --staged --exit-code

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"

---

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

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

---

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	-

---

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

---

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.