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

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

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

# Verify
aphoria --version
```

### Initialize

```bash
aphoria init
```

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

### Scan

```bash
# 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:**
```python
# Before: verify=False
# After:
requests.get(url, verify=True)
```

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

---

## Output Formats

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

---

## Pre-commit Integration

```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 (GitHub Actions)

```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 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](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 |

---

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