[Phase 5] PROOF9: Quality Memory System with Evidence-Based Verification

[frankbria]

Summary

Implement PROOF9 — a quality memory system that turns every failure into a permanent proof obligation with evidence-based verification. Unlike traditional test runners, PROOF9 maintains a requirements ledger where glitches become codified requirements, each with specific proof obligations that are enforced on every subsequent run.

The Core Idea

Quality compounding interest: Every bug found in production, QA, or dogfooding becomes a REQ (requirement) with attached proof obligations. Those obligations are enforced forever. Over time, the system becomes harder to break in ways you've already been burned.

This is the "AFTER" layer in CodeFrame's pipeline:

PRD → Tech Spec → Tasks → Agent Execution → PROOF9 → Deploy
                                                ↑         │
                                                └─────────┘
                                           Glitch → New REQ
                                           (the closed loop)

The 9 Gates

Gate	What It Proves	Tool/Method
UNIT	Logic correctness	pytest / jest
CONTRACT	API/integration contracts hold	Schema validation, contract tests
E2E	User journeys work end-to-end	Playwright
VISUAL	UI renders correctly	Visual snapshot comparison
A11Y	Accessible to all users	axe-core, lighthouse
PERF	Performance within budget	Lighthouse, custom benchmarks
SEC	No security vulnerabilities	OWASP scans, dependency audit
DEMO	Feature demonstrably works	Automated walkthrough with screenshots
MANUAL	Human-verified (waivered automation)	Tracked checklist with expiry

The Requirements Ledger

REQ Schema v0

Each requirement has:

@dataclass
class Requirement:
    id: str                          # REQ-0001
    title: str                       # "Login form rejects empty password"
    description: str                 # What happened, expected vs actual
    severity: Severity               # critical, high, medium, low
    source: Source                    # production, qa, dogfooding, monitoring, user_report
    
    # Scope selector — what does this REQ apply to?
    scope: RequirementScope
    #   routes: ["/login", "/register"]
    #   components: ["LoginForm"]
    #   apis: ["POST /auth/login"]
    #   files: ["src/auth/validator.py"]
    #   tags: ["authentication"]
    
    # Proof obligations — which gates must prove this can't happen again?
    obligations: list[Obligation]
    #   e.g., [UNIT, E2E] for a logic + flow bug
    
    # Evidence rules — what counts as satisfied?
    evidence_rules: list[EvidenceRule]
    #   e.g., test_id="test_login_rejects_empty", must_pass=True
    
    # Lifecycle
    status: ReqStatus               # open, satisfied, waived
    waiver: Waiver | None           # reason, expiry, manual_checklist
    created_at: datetime
    satisfied_at: datetime | None
    
    # Traceability
    created_by: str                 # human or capture agent
    source_issue: str | None        # GitHub issue / bug report link
    related_reqs: list[str]         # REQ IDs this relates to

Obligation Mapping (Glitch Type → Gate Set)

OBLIGATION_MAP = {
    "logic_bug":       [Gate.UNIT, Gate.CONTRACT],
    "integration_bug": [Gate.CONTRACT, Gate.E2E],
    "ui_wiring_bug":   [Gate.E2E, Gate.DEMO],
    "ui_layout_bug":   [Gate.VISUAL, Gate.E2E],
    "a11y_bug":        [Gate.A11Y, Gate.E2E],
    "perf_regression": [Gate.PERF, Gate.E2E],
    "security_issue":  [Gate.SEC],
}

Rule: add the smallest set of obligations that would have caught it. Minimize gate bloat.

The Closed Loop

Capture Flow

Detect glitch → cf proof capture → REQ created → Obligations attached → Artifacts generated

cf proof capture input (minimal, human-friendly):

• What happened? (1-3 sentences)
• Expected vs actual
• Where (URL/screen/API)
• Severity
• Repro steps (optional)
• Screenshot/video (optional)

cf proof capture output (automatic):

• New REQ-#### in requirements ledger
• Suggested gate obligations (with defaults from obligation map)
• Starter pack of test stubs:
  • Unit test skeleton
  • Playwright test from repro steps
  • Visual snapshot target
  • a11y assertion if relevant
  • Perf budget entry if relevant

Enforcement Flow

On every PR / cf proof run:

1. Determine what changed (files, routes, components)
2. Find REQs whose scope intersects the change
3. For intersecting REQs, run relevant obligations
4. Attach evidence artifacts (test results, snapshots, metrics)
5. Mark obligations satisfied or failing
6. Block merge if any required obligation fails

Evidence Attachment Format

@dataclass
class Evidence:
    req_id: str
    gate: Gate
    satisfied: bool
    artifact_path: str          # relative path to test output / screenshot / report
    artifact_checksum: str      # SHA-256 for integrity
    timestamp: datetime
    run_id: str                 # CodeFrame run that produced this

Agent Integration

Two agent roles (used with CodeFrame's agent adapter architecture, #408):

Capture Agent

• Turns bug report + artifacts into a REQ
• Suggests obligations and scope via obligation mapping
• Generates skeleton tests (not full implementations unless trivial)
• Does NOT claim the bug is fixed

Proof Agent

• Picks failing obligations (like "ready" tasks in CodeFrame)
• Implements/fixes tests and code
• Attaches evidence artifacts
• The evidence is what closes the loop, not the agent's claim

This avoids the "agent says it fixed it" problem — PROOF9 doesn't trust claims, it trusts evidence.

Sub-Issues

This is a large feature that will need breakdown once implementation begins. Likely sub-issues:

• REQ schema and ledger storage (SQLite)
• cf proof capture CLI command with AI-assisted classification
• Obligation mapping engine (glitch type → gates)
• Test stub generator (per gate type)
• Scope intersection engine (what changed → which REQs apply)
• cf proof run command (execute relevant obligations, collect evidence)
• Evidence attachment and artifact management
• Waiver system with expiry tracking
• Integration with CodeFrame's existing gates (core/gates.py)
• cf proof status / cf proof report for dashboard view

CLI Commands

# Capture
cf proof capture                      # Interactive glitch capture
cf proof capture --from-issue GH-123  # Import from GitHub issue

# Run
cf proof run                          # Run obligations for current changes
cf proof run --full                   # Run all obligations (release mode)
cf proof run --gate unit              # Run only UNIT gate

# Manage
cf proof list                         # List all REQs
cf proof show REQ-0001                # Show REQ with obligation status
cf proof waive REQ-0001 --reason "..." --expires 2026-04-01
cf proof status                       # Dashboard: satisfied/failing/waived counts
cf proof report                       # Full evidence report

Waivers Are First-Class

Sometimes you can't automate yet. Fine — but it's tracked:

@dataclass
class Waiver:
    reason: str
    expires: date | None            # None = permanent waiver (rare, needs approval)
    manual_checklist: list[str]     # Manual verification steps
    approved_by: str

Waived REQs show up in cf proof status as a distinct category. Expired waivers revert to failing.

Acceptance Criteria

• REQ schema defined and stored in SQLite
• cf proof capture creates REQ with obligations from glitch description
• Obligation mapping classifies glitch type → gate set
• Test stubs generated for each obligation
• cf proof run executes relevant obligations based on changed files
• Evidence artifacts attached with checksums
• Failing obligations block (or warn) on merge
• Waiver system with expiry
• REQs accumulate across sessions (the "memory" property)
• cf proof status shows satisfied/failing/waived counts

Dependencies

• Benefits from existing core/gates.py (UNIT, E2E gate infrastructure)
• Benefits from [Phase 4] Agent Adapter Architecture: Delegate to Frontier Coding Agents #408 (agent adapter) — Proof Agent uses same engine abstraction
• Benefits from [Phase 4] Verification Gate Wrapper for External Agents #415 (verification wrapper) — gates already run after execution
• Independent of PRD/task generation — can be used standalone

The Elevator Pitch

PROOF9 is:

• A standard for what must be proven
• A runner that produces evidence
• A loop that turns real-world glitches into permanent proof obligations

That's not just quality gates. That's a quality memory.

[traycerai]

Plan

Observations

• The project uses Typer for CLI, SQLAlchemy + aiosqlite for storage, Pydantic for models, and Rich for console output — all available in pyproject.toml.
• CLI follows a strict domain → verb structure, with sub-apps registered via app.add_typer(...) at the bottom of file:codeframe/cli/app.py.
• file:codeframe/core/gates.py already defines GateStatus, GateCheck, and GateResult — these are the existing gate primitives PROOF9 must integrate with, not replace.
• Architecture rule: Core must be headless (no FastAPI), CLI must not require a server. All new domain logic lives in codeframe/core/, commands in codeframe/cli/.
• No existing proof/ directory exists — this is greenfield within the established pattern.

Approach

Add a codeframe/core/proof/ package for all domain logic (ledger, obligations, evidence, stubs, scope intersection) and a codeframe/cli/proof_commands.py Typer sub-app wired into the main app. Storage uses SQLAlchemy with the existing SQLite pattern already employed in the project. The existing GateStatus/GateResult from core/gates.py are referenced for gate execution integration.

---

Implementation Plan

Step 1 — Core Package Scaffold

Create the codeframe/core/proof/ package with the following modules:

• codeframe/core/proof/__init__.py — exports the public API
• codeframe/core/proof/models.py — dataclass/Pydantic definitions
• codeframe/core/proof/ledger.py — SQLAlchemy storage engine
• codeframe/core/proof/obligations.py — obligation mapping engine
• codeframe/core/proof/scope.py — scope intersection engine
• codeframe/core/proof/evidence.py — evidence attachment logic
• codeframe/core/proof/stubs.py — test stub generator
• codeframe/core/proof/runner.py — cf proof run execution engine
• codeframe/core/proof/capture.py — cf proof capture logic (capture agent)

---

Step 2 — Data Models (codeframe/core/proof/models.py)

Define the following using Python dataclasses and enum.Enum, consistent with how GateCheck/GateResult are defined in file:codeframe/core/gates.py:

Class	Fields (key ones)
Gate (Enum)	UNIT, CONTRACT, E2E, VISUAL, A11Y, PERF, SEC, DEMO, MANUAL
GlitchType (Enum)	logic_bug, integration_bug, ui_wiring_bug, ui_layout_bug, a11y_bug, perf_regression, security_issue
Severity (Enum)	critical, high, medium, low
Source (Enum)	production, qa, dogfooding, monitoring, user_report
ReqStatus (Enum)	open, satisfied, waived
RequirementScope	routes, components, apis, files, tags
Obligation	req_id, gate, status
EvidenceRule	test_id, must_pass
Evidence	req_id, gate, satisfied, artifact_path, artifact_checksum, timestamp, run_id
Waiver	reason, expires, manual_checklist, approved_by
Requirement	All fields from the ticket's REQ schema — id, title, description, severity, source, scope, obligations, evidence_rules, status, waiver, created_at, satisfied_at, created_by, source_issue, related_reqs

---

Step 3 — Ledger Storage (codeframe/core/proof/ledger.py)

Use SQLAlchemy (already a dependency) with a SQLite backing file stored in the workspace's .codeframe/ state directory, consistent with how other core modules persist state.

Define the following SQLAlchemy table models:

• RequirementRow — maps 1:1 to Requirement, with JSON columns for scope, obligations, evidence_rules, waiver, related_reqs
• EvidenceRow — maps 1:1 to Evidence

Implement these public functions:

• init_ledger(workspace: Workspace) → None — creates tables
• save_requirement(workspace: Workspace, req: Requirement) → None
• get_requirement(workspace: Workspace, req_id: str) → Requirement | None
• list_requirements(workspace: Workspace, status: ReqStatus | None = None) → list[Requirement]
• save_evidence(workspace: Workspace, evidence: Evidence) → None
• list_evidence(workspace: Workspace, req_id: str) → list[Evidence]
• next_req_id(workspace: Workspace) → str — generates sequential REQ-0001 style IDs

---

Step 4 — Obligation Mapping Engine (codeframe/core/proof/obligations.py)

Implement the OBLIGATION_MAP dict mapping GlitchType → list[Gate] exactly as specified in the ticket.

Implement:

• classify_glitch(description: str) → GlitchType — heuristic or LLM-assisted classification from a natural language description; start with keyword heuristics (can be LLM-backed later)
• get_obligations(glitch_type: GlitchType) → list[Gate] — returns the minimal gate set from OBLIGATION_MAP
• suggest_evidence_rules(gate: Gate, description: str) → list[EvidenceRule] — returns starter evidence rule stubs

---

Step 5 — Scope Intersection Engine (codeframe/core/proof/scope.py)

Implement:

• build_scope_from_capture(where: str) → RequirementScope — parses user-provided location (URL, file path, component name, API route) into a RequirementScope
• get_changed_scope(workspace: Workspace) → RequirementScope — uses gitpython (already a dependency via gitpython>=3.1.40) to detect changed files and extract routes/components/apis/files from the diff
• intersects(req_scope: RequirementScope, changed_scope: RequirementScope) → bool — returns True if any field overlaps

---

Step 6 — Test Stub Generator (codeframe/core/proof/stubs.py)

Implement generate_stubs(req: Requirement) → dict[Gate, str] — returns a mapping of gate → file content string (template) for each obligation in the requirement:

Gate	Stub type
UNIT	pytest function skeleton
CONTRACT	Schema validation test skeleton
E2E	Playwright test skeleton (TypeScript)
VISUAL	Snapshot test stub
A11Y	axe-core assertion stub
PERF	Lighthouse budget entry
SEC	Dependency audit check note
DEMO	Walkthrough script skeleton
MANUAL	Markdown checklist template

Use Jinja2 (already available as jinja2>=3.1.6) for stub templates — store templates as strings within the module or in a codeframe/core/proof/templates/ subdirectory.

---

Step 7 — Evidence Attachment (codeframe/core/proof/evidence.py)

Implement:

• attach_evidence(workspace: Workspace, req_id: str, gate: Gate, artifact_path: str, satisfied: bool, run_id: str) → Evidence — computes SHA-256 checksum of the artifact file, creates an Evidence record, persists via ledger.save_evidence
• check_obligation_satisfied(workspace: Workspace, req: Requirement, gate: Gate) → bool — queries evidence records to determine if the obligation has a passing evidence entry

---

Step 8 — Capture Logic (codeframe/core/proof/capture.py)

Implement capture_requirement(workspace: Workspace, *, title: str, description: str, where: str, expected: str, actual: str, severity: Severity, source: Source, screenshot_path: str | None, source_issue: str | None) → tuple[Requirement, dict[Gate, str]]:

1. Call classify_glitch(description) to infer GlitchType
2. Call get_obligations(glitch_type) to build Obligation list
3. Call build_scope_from_capture(where) to build RequirementScope
4. Call suggest_evidence_rules(gate, description) per obligation
5. Generate next_req_id(workspace) for REQ-####
6. Construct Requirement dataclass
7. Call save_requirement(workspace, req)
8. Call generate_stubs(req) and return stubs alongside the Requirement

---

Step 9 — Runner (codeframe/core/proof/runner.py)

Implement run_proof(workspace: Workspace, *, full: bool = False, gate: Gate | None = None, run_id: str) → dict[str, list[tuple[Gate, bool]]]:

sequenceDiagram
    participant CLI
    participant runner
    participant scope
    participant ledger
    participant gates (core/gates.py)
    participant evidence

    CLI->>runner: run_proof(workspace, full, gate, run_id)
    runner->>scope: get_changed_scope(workspace)
    runner->>ledger: list_requirements(workspace)
    loop each REQ
        runner->>scope: intersects(req.scope, changed_scope)
        alt intersects or full mode
            loop each obligation gate
                runner->>gates: run(workspace, gates=[gate_name])
                runner->>evidence: attach_evidence(...)
            end
        end
    end
    runner-->>CLI: results dict {req_id → [(Gate, satisfied)]}

• When full=True, skip the scope intersection check and run all obligations for all REQs.
• When gate is specified, run only that gate for intersecting REQs.
• Use the existing run() function from file:codeframe/core/gates.py for UNIT gate execution (and similar tool invocations for others where possible).
• After running, update each Requirement.status to satisfied if all obligations pass, leaving it open otherwise.

---

Step 10 — Waiver System

Add to codeframe/core/proof/ledger.py:

• waive_requirement(workspace: Workspace, req_id: str, waiver: Waiver) → Requirement — sets status=waived, attaches the Waiver
• check_expired_waivers(workspace: Workspace) → list[Requirement] — finds waived requirements where waiver.expires < today and reverts their status to open

Call check_expired_waivers at the start of run_proof and proof status.

---

Step 11 — CLI Commands (codeframe/cli/proof_commands.py)

Create a new file codeframe/cli/proof_commands.py following the exact patterns of file:codeframe/cli/app.py (Typer sub-app with Rich console).

proof_app = typer.Typer(name="proof", help="PROOF9 quality memory system")

Implement these commands:

Command	Function	Core call
cf proof capture	capture()	capture.capture_requirement(...)
cf proof capture --from-issue GH-123	capture(from_issue=...)	fetch issue + capture_requirement
cf proof run	run()	runner.run_proof(...)
cf proof run --full	run(full=True)	runner.run_proof(full=True)
cf proof run --gate unit	run(gate="unit")	runner.run_proof(gate=Gate.UNIT)
cf proof list	list_reqs()	ledger.list_requirements(...)
cf proof show REQ-0001	show(req_id)	ledger.get_requirement(...) + evidence
cf proof waive REQ-0001 --reason ... --expires ...	waive(req_id, ...)	ledger.waive_requirement(...)
cf proof status	status_cmd()	ledger.list_requirements(...) grouped counts
cf proof report	report()	full evidence report via Rich Table

The capture command should be interactive (using typer.prompt) when run without arguments, collecting: what happened, expected vs actual, where, severity, repro steps, screenshot path, and source issue.

After capture, print the new REQ-#### ID, the inferred glitch type, the obligations list, and the stubs file paths.

---

Step 12 — Wire Into Main CLI

In file:codeframe/cli/app.py, add after the existing add_typer block (around line 4793):

from codeframe.cli.proof_commands import proof_app
app.add_typer(proof_app, name="proof")

This makes cf proof available as a first-class sub-command.

---

Step 13 — Workspace Init Integration

In ledger.py's init_ledger(), check if the workspace's .codeframe/ state directory exists and create proof.db (SQLite) there. The path should follow the same convention as other workspace state files.

Optionally call init_ledger(workspace) inside the existing init command in file:codeframe/cli/app.py so the ledger is set up when a workspace is initialized.

Import In IDE

🤖 Prompt for AI Agents

## Observations

- The project uses **Typer** for CLI, **SQLAlchemy + aiosqlite** for storage, **Pydantic** for models, and **Rich** for console output — all available in `pyproject.toml`.
- CLI follows a strict `domain → verb` structure, with sub-apps registered via `app.add_typer(...)` at the bottom of `file:codeframe/cli/app.py`.
- `file:codeframe/core/gates.py` already defines `GateStatus`, `GateCheck`, and `GateResult` — these are the **existing** gate primitives PROOF9 must integrate with, not replace.
- Architecture rule: **Core must be headless** (no FastAPI), CLI must not require a server. All new domain logic lives in `codeframe/core/`, commands in `codeframe/cli/`.
- No existing `proof/` directory exists — this is greenfield within the established pattern.

## Approach

Add a `codeframe/core/proof/` package for all domain logic (ledger, obligations, evidence, stubs, scope intersection) and a `codeframe/cli/proof_commands.py` Typer sub-app wired into the main app. Storage uses SQLAlchemy with the existing SQLite pattern already employed in the project. The existing `GateStatus`/`GateResult` from `core/gates.py` are referenced for gate execution integration.

---

## Implementation Plan

### Step 1 — Core Package Scaffold

Create the `codeframe/core/proof/` package with the following modules:

- `codeframe/core/proof/__init__.py` — exports the public API
- `codeframe/core/proof/models.py` — dataclass/Pydantic definitions
- `codeframe/core/proof/ledger.py` — SQLAlchemy storage engine
- `codeframe/core/proof/obligations.py` — obligation mapping engine
- `codeframe/core/proof/scope.py` — scope intersection engine
- `codeframe/core/proof/evidence.py` — evidence attachment logic
- `codeframe/core/proof/stubs.py` — test stub generator
- `codeframe/core/proof/runner.py` — `cf proof run` execution engine
- `codeframe/core/proof/capture.py` — `cf proof capture` logic (capture agent)

---

### Step 2 — Data Models (`codeframe/core/proof/models.py`)

Define the following using Python `dataclasses` and `enum.Enum`, consistent with how `GateCheck`/`GateResult` are defined in `file:codeframe/core/gates.py`:

| Class | Fields (key ones) |
|---|---|
| `Gate` (Enum) | `UNIT, CONTRACT, E2E, VISUAL, A11Y, PERF, SEC, DEMO, MANUAL` |
| `GlitchType` (Enum) | `logic_bug, integration_bug, ui_wiring_bug, ui_layout_bug, a11y_bug, perf_regression, security_issue` |
| `Severity` (Enum) | `critical, high, medium, low` |
| `Source` (Enum) | `production, qa, dogfooding, monitoring, user_report` |
| `ReqStatus` (Enum) | `open, satisfied, waived` |
| `RequirementScope` | `routes, components, apis, files, tags` |
| `Obligation` | `req_id, gate, status` |
| `EvidenceRule` | `test_id, must_pass` |
| `Evidence` | `req_id, gate, satisfied, artifact_path, artifact_checksum, timestamp, run_id` |
| `Waiver` | `reason, expires, manual_checklist, approved_by` |
| `Requirement` | All fields from the ticket's REQ schema — `id, title, description, severity, source, scope, obligations, evidence_rules, status, waiver, created_at, satisfied_at, created_by, source_issue, related_reqs` |

---

### Step 3 — Ledger Storage (`codeframe/core/proof/ledger.py`)

Use **SQLAlchemy** (already a dependency) with a SQLite backing file stored in the workspace's `.codeframe/` state directory, consistent with how other core modules persist state.

Define the following SQLAlchemy table models:
- `RequirementRow` — maps 1:1 to `Requirement`, with JSON columns for `scope`, `obligations`, `evidence_rules`, `waiver`, `related_reqs`
- `EvidenceRow` — maps 1:1 to `Evidence`

Implement these public functions:
- `init_ledger(workspace: Workspace) → None` — creates tables
- `save_requirement(workspace: Workspace, req: Requirement) → None`
- `get_requirement(workspace: Workspace, req_id: str) → Requirement | None`
- `list_requirements(workspace: Workspace, status: ReqStatus | None = None) → list[Requirement]`
- `save_evidence(workspace: Workspace, evidence: Evidence) → None`
- `list_evidence(workspace: Workspace, req_id: str) → list[Evidence]`
- `next_req_id(workspace: Workspace) → str` — generates sequential `REQ-0001` style IDs

---

### Step 4 — Obligation Mapping Engine (`codeframe/core/proof/obligations.py`)

Implement the `OBLIGATION_MAP` dict mapping `GlitchType → list[Gate]` exactly as specified in the ticket.

Implement:
- `classify_glitch(description: str) → GlitchType` — heuristic or LLM-assisted classification from a natural language description; start with keyword heuristics (can be LLM-backed later)
- `get_obligations(glitch_type: GlitchType) → list[Gate]` — returns the minimal gate set from `OBLIGATION_MAP`
- `suggest_evidence_rules(gate: Gate, description: str) → list[EvidenceRule]` — returns starter evidence rule stubs

---

### Step 5 — Scope Intersection Engine (`codeframe/core/proof/scope.py`)

Implement:
- `build_scope_from_capture(where: str) → RequirementScope` — parses user-provided location (URL, file path, component name, API route) into a `RequirementScope`
- `get_changed_scope(workspace: Workspace) → RequirementScope` — uses `gitpython` (already a dependency via `gitpython>=3.1.40`) to detect changed files and extract routes/components/apis/files from the diff
- `intersects(req_scope: RequirementScope, changed_scope: RequirementScope) → bool` — returns `True` if any field overlaps

---

### Step 6 — Test Stub Generator (`codeframe/core/proof/stubs.py`)

Implement `generate_stubs(req: Requirement) → dict[Gate, str]` — returns a mapping of gate → file content string (template) for each obligation in the requirement:

| Gate | Stub type |
|---|---|
| `UNIT` | `pytest` function skeleton |
| `CONTRACT` | Schema validation test skeleton |
| `E2E` | Playwright test skeleton (TypeScript) |
| `VISUAL` | Snapshot test stub |
| `A11Y` | axe-core assertion stub |
| `PERF` | Lighthouse budget entry |
| `SEC` | Dependency audit check note |
| `DEMO` | Walkthrough script skeleton |
| `MANUAL` | Markdown checklist template |

Use **Jinja2** (already available as `jinja2>=3.1.6`) for stub templates — store templates as strings within the module or in a `codeframe/core/proof/templates/` subdirectory.

---

### Step 7 — Evidence Attachment (`codeframe/core/proof/evidence.py`)

Implement:
- `attach_evidence(workspace: Workspace, req_id: str, gate: Gate, artifact_path: str, satisfied: bool, run_id: str) → Evidence` — computes SHA-256 checksum of the artifact file, creates an `Evidence` record, persists via `ledger.save_evidence`
- `check_obligation_satisfied(workspace: Workspace, req: Requirement, gate: Gate) → bool` — queries evidence records to determine if the obligation has a passing evidence entry

---

### Step 8 — Capture Logic (`codeframe/core/proof/capture.py`)

Implement `capture_requirement(workspace: Workspace, *, title: str, description: str, where: str, expected: str, actual: str, severity: Severity, source: Source, screenshot_path: str | None, source_issue: str | None) → tuple[Requirement, dict[Gate, str]]`:

1. Call `classify_glitch(description)` to infer `GlitchType`
2. Call `get_obligations(glitch_type)` to build `Obligation` list
3. Call `build_scope_from_capture(where)` to build `RequirementScope`
4. Call `suggest_evidence_rules(gate, description)` per obligation
5. Generate `next_req_id(workspace)` for `REQ-####`
6. Construct `Requirement` dataclass
7. Call `save_requirement(workspace, req)`
8. Call `generate_stubs(req)` and return stubs alongside the `Requirement`

---

### Step 9 — Runner (`codeframe/core/proof/runner.py`)

Implement `run_proof(workspace: Workspace, *, full: bool = False, gate: Gate | None = None, run_id: str) → dict[str, list[tuple[Gate, bool]]]`:

```
sequenceDiagram
    participant CLI
    participant runner
    participant scope
    participant ledger
    participant gates (core/gates.py)
    participant evidence

    CLI->>runner: run_proof(workspace, full, gate, run_id)
    runner->>scope: get_changed_scope(workspace)
    runner->>ledger: list_requirements(workspace)
    loop each REQ
        runner->>scope: intersects(req.scope, changed_scope)
        alt intersects or full mode
            loop each obligation gate
                runner->>gates: run(workspace, gates=[gate_name])
                runner->>evidence: attach_evidence(...)
            end
        end
    end
    runner-->>CLI: results dict {req_id → [(Gate, satisfied)]}
```

- When `full=True`, skip the scope intersection check and run all obligations for all REQs.
- When `gate` is specified, run only that gate for intersecting REQs.
- Use the existing `run()` function from `file:codeframe/core/gates.py` for `UNIT` gate execution (and similar tool invocations for others where possible).
- After running, update each `Requirement.status` to `satisfied` if all obligations pass, leaving it `open` otherwise.

---

### Step 10 — Waiver System

Add to `codeframe/core/proof/ledger.py`:
- `waive_requirement(workspace: Workspace, req_id: str, waiver: Waiver) → Requirement` — sets `status=waived`, attaches the `Waiver`
- `check_expired_waivers(workspace: Workspace) → list[Requirement]` — finds `waived` requirements where `waiver.expires < today` and reverts their status to `open`

Call `check_expired_waivers` at the start of `run_proof` and `proof status`.

---

### Step 11 — CLI Commands (`codeframe/cli/proof_commands.py`)

Create a new file `codeframe/cli/proof_commands.py` following the exact patterns of `file:codeframe/cli/app.py` (Typer sub-app with Rich console).

```python
proof_app = typer.Typer(name="proof", help="PROOF9 quality memory system")
```

Implement these commands:

| Command | Function | Core call |
|---|---|---|
| `cf proof capture` | `capture()` | `capture.capture_requirement(...)` |
| `cf proof capture --from-issue GH-123` | `capture(from_issue=...)` | fetch issue + `capture_requirement` |
| `cf proof run` | `run()` | `runner.run_proof(...)` |
| `cf proof run --full` | `run(full=True)` | `runner.run_proof(full=True)` |
| `cf proof run --gate unit` | `run(gate="unit")` | `runner.run_proof(gate=Gate.UNIT)` |
| `cf proof list` | `list_reqs()` | `ledger.list_requirements(...)` |
| `cf proof show REQ-0001` | `show(req_id)` | `ledger.get_requirement(...)` + evidence |
| `cf proof waive REQ-0001 --reason ... --expires ...` | `waive(req_id, ...)` | `ledger.waive_requirement(...)` |
| `cf proof status` | `status_cmd()` | `ledger.list_requirements(...)` grouped counts |
| `cf proof report` | `report()` | full evidence report via Rich `Table` |

The `capture` command should be interactive (using `typer.prompt`) when run without arguments, collecting: what happened, expected vs actual, where, severity, repro steps, screenshot path, and source issue.

After capture, print the new `REQ-####` ID, the inferred glitch type, the obligations list, and the stubs file paths.

---

### Step 12 — Wire Into Main CLI

In `file:codeframe/cli/app.py`, add after the existing `add_typer` block (around line 4793):

```python
from codeframe.cli.proof_commands import proof_app
app.add_typer(proof_app, name="proof")
```

This makes `cf proof` available as a first-class sub-command.

---

### Step 13 — Workspace Init Integration

In `ledger.py`'s `init_ledger()`, check if the workspace's `.codeframe/` state directory exists and create `proof.db` (SQLite) there. The path should follow the same convention as other workspace state files.

Optionally call `init_ledger(workspace)` inside the existing `init` command in `file:codeframe/cli/app.py` so the ledger is set up when a workspace is initialized.

---

Execution Information

Branch: main
Commit: 705b160

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

🔗 Related PRs

#137 - Add skip detection quality gate to prevent bypassed tests [merged]
#156 - Evidence-Based Quality Enforcement Integration [merged]
#303 - feat(gates): add BUILD validation gate for config errors [merged]
#384 - feat: adaptive iteration budget, autofix, and loop detection for ReactAgent [merged]
#386 - [Phase 2.5-F] Harden verification gates and add batch-level QA [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!