fix(proof): explicit UNVERIFIABLE state for gates without runners (#728) (#801)

* fix(proof): explicit UNVERIFIABLE state for gates without runners (#728)

The 6 PROOF9 gates with no automated runner (e2e, visual, a11y, perf,
demo, manual) previously collapsed to hard FAIL, so most captured
glitches could never be SATISFIED and every run failed perpetually.

- core: new GateOutcome enum (passed/failed/unverifiable); _run_gate
  returns the tri-state and its stale docstring is corrected; run_proof
  maps obligations three-way, keeps requirements OPEN (waivable) on
  unverifiable, and excludes unverifiable from overall_passed
- evidence/ledger: Evidence.status persists the outcome; nullable
  status column added with a PRAGMA-guarded ALTER TABLE migration so
  legacy DBs keep working (old rows read back status=None)
- api: run results carry {gate, satisfied, status}; EvidenceResponse
  gains optional status; passed aggregation mirrors the runner rule
- cli: yellow UNVERIFIABLE cell, waive hint, exit 0 when nothing failed
- tui: distinct ❓ icon for unverifiable obligations
- web-ui: 'unverifiable' GateRunStatus + amber badge/banner/pills on
  /proof and /proof/[req_id] (incl. evidence history filter + sort);
  gate.run.failed notifications no longer fire for unverifiable gates

* fix(web-ui): tidy Gate Results help copy on /proof

* fix(proof): harden evidence-status migration + review polish

- ledger: try/finally around the migration connection, tolerate the
  concurrent-first-run duplicate-column race, and memoize per workspace
  so the PRAGMA doesn't run on every DB access (CodeRabbit + claude-review)
- web-ui: compute evidenceResult once per row; give the unverifiable
  badge distinct styling from in-progress so live runs visibly flip

Author: frankbria

codeframe/cli/proof_commands.py

@@ -144,7 +144,7 @@ def run(
         codeframe proof run --gate unit
     """
     from codeframe.core.workspace import get_workspace
-    from codeframe.core.proof.models import Gate
+    from codeframe.core.proof.models import Gate, GateOutcome
     from codeframe.core.proof.runner import run_proof
 
     workspace_path = repo_path or Path.cwd()
@@ -178,21 +178,41 @@ def run(
     table.add_column("Gate", style="blue")
     table.add_column("Result", style="bold")
 
-    all_pass = True
+    _CELL = {
+        GateOutcome.PASSED: "[green]PASS[/green]",
+        GateOutcome.FAILED: "[red]FAIL[/red]",
+        GateOutcome.UNVERIFIABLE: "[yellow]UNVERIFIABLE[/yellow]",
+    }
+    any_failed = False
+    unverifiable_gates: set[str] = set()
     for req_id, gate_results in results.items():
-        for g, passed in gate_results:
-            status = "[green]PASS[/green]" if passed else "[red]FAIL[/red]"
-            if not passed:
-                all_pass = False
-            table.add_row(req_id, g.value, status)
+        for g, outcome in gate_results:
+            if outcome == GateOutcome.FAILED:
+                any_failed = True
+            elif outcome == GateOutcome.UNVERIFIABLE:
+                unverifiable_gates.add(g.value)
+            table.add_row(req_id, g.value, _CELL[outcome])
 
     console.print(table)
 
-    if all_pass:
-        console.print("\n[green]All obligations satisfied.[/green]")
-    else:
+    if unverifiable_gates:
+        gates = ", ".join(sorted(unverifiable_gates))
+        console.print(
+            f"\n[yellow]Could not verify {len(unverifiable_gates)} gate(s):[/yellow] "
+            f"{gates} — no automated runner. "
+            "Waive with 'cf proof waive <REQ> --reason \"...\"'."
+        )
+
+    if any_failed:
         console.print("\n[red]Some obligations failed.[/red] Fix issues and re-run.")
         raise typer.Exit(1)
+    elif unverifiable_gates:
+        console.print(
+            "\n[green]No obligations failed[/green] "
+            "[dim](some gates could not be verified).[/dim]"
+        )
+    else:
+        console.print("\n[green]All obligations satisfied.[/green]")
 
 
 @proof_app.command("list")
@@ -319,7 +339,13 @@ def show(
     if evidence_list:
         console.print(f"\n[bold]Evidence ({len(evidence_list)}):[/bold]")
         for ev in evidence_list[:10]:
-            status = "[green]PASS[/green]" if ev.satisfied else "[red]FAIL[/red]"
+            if ev.status == "unverifiable":
+                status = "[yellow]UNVERIFIABLE[/yellow]"
+            elif ev.satisfied:
+                status = "[green]PASS[/green]"
+            else:
+                # Legacy rows (status=None) fall back to the satisfied bool.
+                status = "[red]FAIL[/red]"
             console.print(f"  {ev.gate.value} {status} — {ev.artifact_path}")
 
 

codeframe/core/proof/evidence.py

@@ -9,7 +9,7 @@
 from pathlib import Path
 
 from codeframe.core.proof import ledger
-from codeframe.core.proof.models import Evidence, Gate, Requirement
+from codeframe.core.proof.models import Evidence, Gate, GateOutcome, Requirement
 from codeframe.core.workspace import Workspace
 
 
@@ -28,18 +28,23 @@ def attach_evidence(
     req_id: str,
     gate: Gate,
     artifact_path: str,
-    satisfied: bool,
+    outcome: GateOutcome,
     run_id: str,
 ) -> Evidence:
-    """Create and persist an evidence record with artifact checksum."""
+    """Create and persist an evidence record with artifact checksum.
+
+    `satisfied` is True only when the gate PASSED; UNVERIFIABLE and FAILED both
+    record satisfied=False. The tri-state `outcome` is preserved in `status`.
+    """
     evidence = Evidence(
         req_id=req_id,
         gate=gate,
-        satisfied=satisfied,
+        satisfied=(outcome == GateOutcome.PASSED),
         artifact_path=artifact_path,
         artifact_checksum=_sha256(artifact_path),
         timestamp=datetime.now(timezone.utc),
         run_id=run_id,
+        status=outcome.value,
     )
     ledger.save_evidence(workspace, evidence)
     return evidence

codeframe/core/proof/ledger.py

@@ -5,6 +5,7 @@
 """
 
 import json
+import sqlite3
 from datetime import date, datetime, timezone
 from typing import Optional
 
@@ -67,6 +68,7 @@ def init_proof_tables(workspace: Workspace) -> None:
             timestamp TEXT NOT NULL,
             run_id TEXT NOT NULL,
             workspace_id TEXT NOT NULL,
+            status TEXT,
             FOREIGN KEY (req_id) REFERENCES proof_requirements(id)
         )
     """)
@@ -121,6 +123,38 @@ def _ensure_tables(workspace: Workspace) -> None:
     conn.close()
     if missing:
         init_proof_tables(workspace)
+    _migrate_evidence_status_column(workspace)
+
+
+# Workspaces already checked for the #728 status column this process —
+# skips the per-call PRAGMA once the migration is known to have run.
+_status_migrated_workspaces: set[str] = set()
+
+
+def _migrate_evidence_status_column(workspace: Workspace) -> None:
+    """Add proof_evidence.status to pre-existing DBs that predate #728.
+
+    The column is nullable; old rows read back status=None. No-op once present.
+    """
+    if workspace.id in _status_migrated_workspaces:
+        return
+    conn = get_db_connection(workspace)
+    try:
+        cursor = conn.cursor()
+        cursor.execute("PRAGMA table_info(proof_evidence)")
+        columns = {row[1] for row in cursor.fetchall()}
+        if columns and "status" not in columns:
+            try:
+                cursor.execute("ALTER TABLE proof_evidence ADD COLUMN status TEXT")
+                conn.commit()
+            except sqlite3.OperationalError as exc:
+                # Concurrent first-run: another worker added the column
+                # between our check and the ALTER.
+                if "duplicate column" not in str(exc).lower():
+                    raise
+        _status_migrated_workspaces.add(workspace.id)
+    finally:
+        conn.close()
 
 
 # --- Serialization helpers ---
@@ -315,12 +349,13 @@ def save_evidence(workspace: Workspace, evidence: Evidence) -> None:
     cursor.execute(
         """INSERT INTO proof_evidence
            (req_id, gate, satisfied, artifact_path, artifact_checksum,
-            timestamp, run_id, workspace_id)
-           VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
+            timestamp, run_id, workspace_id, status)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)""",
         (
             evidence.req_id, evidence.gate.value, int(evidence.satisfied),
             evidence.artifact_path, evidence.artifact_checksum,
             evidence.timestamp.isoformat(), evidence.run_id, workspace.id,
+            evidence.status,
         ),
     )
     conn.commit()
@@ -334,7 +369,7 @@ def list_evidence(workspace: Workspace, req_id: str) -> list[Evidence]:
     cursor = conn.cursor()
     cursor.execute(
         """SELECT req_id, gate, satisfied, artifact_path, artifact_checksum,
-                  timestamp, run_id
+                  timestamp, run_id, status
            FROM proof_evidence WHERE req_id = ? AND workspace_id = ?
            ORDER BY timestamp DESC""",
         (req_id, workspace.id),
@@ -346,6 +381,7 @@ def list_evidence(workspace: Workspace, req_id: str) -> list[Evidence]:
             req_id=r[0], gate=Gate(r[1]), satisfied=bool(r[2]),
             artifact_path=r[3], artifact_checksum=r[4],
             timestamp=datetime.fromisoformat(r[5]), run_id=r[6],
+            status=r[7],
         )
         for r in rows
     ]
@@ -460,7 +496,7 @@ def get_run_evidence(workspace: Workspace, run_id: str) -> list[Evidence]:
     cursor = conn.cursor()
     cursor.execute(
         """SELECT req_id, gate, satisfied, artifact_path, artifact_checksum,
-                  timestamp, run_id
+                  timestamp, run_id, status
            FROM proof_evidence WHERE run_id = ? AND workspace_id = ?
            ORDER BY timestamp ASC""",
         (run_id, workspace.id),
@@ -472,6 +508,7 @@ def get_run_evidence(workspace: Workspace, run_id: str) -> list[Evidence]:
             req_id=r[0], gate=Gate(r[1]), satisfied=bool(r[2]),
             artifact_path=r[3], artifact_checksum=r[4],
             timestamp=datetime.fromisoformat(r[5]), run_id=r[6],
+            status=r[7],
         )
         for r in rows
     ]

codeframe/core/proof/models.py

@@ -33,6 +33,19 @@ class Gate(str, Enum):
 PROOF9_GATE_ORDER: tuple[str, ...] = tuple(g.value for g in Gate)
 
 
+class GateOutcome(str, Enum):
+    """Outcome of running a single proof obligation's gate.
+
+    UNVERIFIABLE is distinct from FAILED: the gate has no automated runner
+    (e.g. e2e, visual, a11y, perf, demo, manual), so the obligation could not
+    be checked at all. It never satisfies a requirement and never fails a run.
+    """
+
+    PASSED = "passed"
+    FAILED = "failed"
+    UNVERIFIABLE = "unverifiable"
+
+
 class GlitchType(str, Enum):
     """Classification of the glitch that produced a requirement."""
 
@@ -88,7 +101,7 @@ class Obligation:
     """A single proof obligation attached to a requirement."""
 
     gate: Gate
-    status: str = "pending"  # pending, satisfied, failed
+    status: str = "pending"  # pending, satisfied, failed, unverifiable
 
 
 @dataclass
@@ -121,6 +134,7 @@ class Evidence:
     artifact_checksum: str
     timestamp: datetime
     run_id: str
+    status: Optional[str] = None  # passed, failed, unverifiable (None for legacy rows)
 
 
 @dataclass

codeframe/core/proof/runner.py

@@ -16,6 +16,7 @@
 from codeframe.core.proof.models import (
     PROOF_CONFIG_FILENAME,
     Gate,
+    GateOutcome,
     ProofRun,
     ReqStatus,
 )
@@ -71,27 +72,39 @@ def _load_proof_config(workspace: Workspace) -> tuple[Optional[set[Gate]], str]:
     Gate.SEC: "ruff",
 }
 
+# Map a gate outcome to the persisted obligation status string.
+_OUTCOME_TO_OBLIGATION_STATUS: dict[GateOutcome, str] = {
+    GateOutcome.PASSED: "satisfied",
+    GateOutcome.FAILED: "failed",
+    GateOutcome.UNVERIFIABLE: "unverifiable",
+}
+
 
-def _run_gate(workspace: Workspace, gate: Gate) -> tuple[bool, str]:
-    """Execute a single gate and return (passed, output).
+def _run_gate(workspace: Workspace, gate: Gate) -> tuple[GateOutcome, str]:
+    """Execute a single gate and return (outcome, output).
 
-    Uses core/gates.py for gates that have direct tool support.
-    Returns (True, "") for gates without automated tooling yet.
+    Uses core/gates.py for gates that have direct tool support. Gates without
+    an automated runner return UNVERIFIABLE — the obligation could not be
+    checked, which is distinct from running and failing.
     """
     core_gate_name = _GATE_TO_CORE.get(gate)
     if not core_gate_name:
-        return False, f"Gate {gate.value} has no automated runner — cannot verify"
+        return (
+            GateOutcome.UNVERIFIABLE,
+            f"Gate {gate.value} has no automated runner — cannot verify",
+        )
 
     try:
         from codeframe.core.gates import run as run_gates
         result = run_gates(workspace, gates=[core_gate_name], verbose=False)
         output_parts = [
             f"{check.name}: {check.status.value}" for check in result.checks
         ]
-        return result.passed, "\n".join(output_parts)
+        outcome = GateOutcome.PASSED if result.passed else GateOutcome.FAILED
+        return outcome, "\n".join(output_parts)
     except Exception as exc:
         logger.warning("Gate %s failed to run: %s", gate.value, exc)
-        return False, str(exc)
+        return GateOutcome.FAILED, str(exc)
 
 
 def run_proof(
@@ -100,7 +113,7 @@ def run_proof(
     full: bool = False,
     gate_filter: Optional[Gate] = None,
     run_id: Optional[str] = None,
-) -> dict[str, list[tuple[Gate, bool]]]:
+) -> dict[str, list[tuple[Gate, GateOutcome]]]:
     """Execute proof obligations and collect evidence.
 
     Args:
@@ -110,7 +123,7 @@ def run_proof(
         run_id: Unique run identifier (auto-generated if not provided)
 
     Returns:
-        Dict mapping req_id → list of (Gate, satisfied) tuples
+        Dict mapping req_id → list of (Gate, GateOutcome) tuples
     """
     if not run_id:
         run_id = str(uuid.uuid4())[:8]
@@ -157,7 +170,7 @@ def run_proof(
     if not full:
         changed_scope = get_changed_scope(workspace)
 
-    results: dict[str, list[tuple[Gate, bool]]] = {}
+    results: dict[str, list[tuple[Gate, GateOutcome]]] = {}
     artifact_dir = workspace.state_dir / "proof_artifacts"
     artifact_dir.mkdir(exist_ok=True)
 
@@ -168,7 +181,7 @@ def run_proof(
             if not intersects(req.scope, changed_scope):
                 continue
 
-        req_results: list[tuple[Gate, bool]] = []
+        req_results: list[tuple[Gate, GateOutcome]] = []
 
         for obl in req.obligations:
             # Apply gate filter
@@ -180,7 +193,7 @@ def run_proof(
                 continue
 
             # Run the gate
-            passed, output = _run_gate(workspace, obl.gate)
+            outcome, output = _run_gate(workspace, obl.gate)
 
             # Write artifact
             artifact_path = artifact_dir / f"{req.id}_{obl.gate.value}_{run_id}.txt"
@@ -189,25 +202,35 @@ def run_proof(
             # Attach evidence
             attach_evidence(
                 workspace, req.id, obl.gate,
-                str(artifact_path), passed, run_id,
+                str(artifact_path), outcome, run_id,
             )
 
             # Update obligation status
-            obl.status = "satisfied" if passed else "failed"
-            req_results.append((obl.gate, passed))
+            obl.status = _OUTCOME_TO_OBLIGATION_STATUS[outcome]
+            req_results.append((obl.gate, outcome))
 
         if req_results:
             results[req.id] = req_results
 
-            # Always persist obligation status updates
-            all_satisfied = all(passed for _, passed in req_results)
-            if all_satisfied and len(req_results) == len(req.obligations):
+            # Always persist obligation status updates. A requirement is only
+            # SATISFIED when every obligation PASSED and all obligations ran —
+            # an unverifiable obligation leaves it OPEN (and waivable).
+            all_passed = all(o == GateOutcome.PASSED for _, o in req_results)
+            if all_passed and len(req_results) == len(req.obligations):
                 req.status = ReqStatus.SATISFIED
             ledger.save_requirement(workspace, req)
 
     completed_at = datetime.now(timezone.utc)
     duration_ms = int((completed_at - started_at).total_seconds() * 1000)
-    executed = [passed for gate_results in results.values() for _, passed in gate_results]
+    # Only gates that actually ran (passed or failed) count toward the tally;
+    # unverifiable gates neither pass nor fail, so a run with only unverifiable
+    # outcomes passes.
+    executed = [
+        outcome == GateOutcome.PASSED
+        for gate_results in results.values()
+        for _, outcome in gate_results
+        if outcome != GateOutcome.UNVERIFIABLE
+    ]
     all_passed = all(executed) if executed else True
     if not all_passed and strictness == "warn":
         logger.warning(