stemedb/applications/aphoria/README.md

# Aphoria

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

## Install

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

## Quick Start

```bash
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):

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

**Or acknowledge intentionally** (creates an audit trail):

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

## Scan Options

```bash
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)

## 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 <marker-id> --id wallet-no-clone-001 --by jml`

## Pre-commit Hook

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

```yaml
- 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](docs/reference/cli-reference.md) 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/](../../sdk/go/adk/)
- **Any LLM with tool use**: Drive Aphoria via CLI

See [The Autonomous Loop](docs/guides/golden-path-loop.md) for the full commit-time flywheel.

## Guides

| 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. Aphoria surfaces *your org's* decisions when you contradict them.