@aperant/framework 0.10.0 → 0.12.0

package/workflows/verify-proof.md

@@ -1,10 +1,14 @@
 <purpose>
 Visual proof-of-work verification with structured evidence capture. Creates verification.json
-that tracks every test with action → evidence → verdict. Produces HTML proof report.
+that tracks every outcome with action → evidence → verdict. Produces HTML proof report.
 
 This workflow is adversarial — it assumes things are broken until proven working.
 Every claim requires evidence. Every screenshot follows an interaction.
 
+v0.9.0 — **outcome-walker**: iterate `spec.md ## User Outcomes` parent bullets
+one at a time, reload ONLY that outcome card into working memory, drive the
+stated bullet AND each inferred child, fail-loop on red, advance on green.
+
 OUTPUT FORMAT: verification.json (NOT VERIFICATION.md). JSON is the source of truth.
 </purpose>
 
@@ -40,7 +44,6 @@ Read spec and plan:
 ```bash
 cat spec.md 2>/dev/null
 cat implementation_plan.json 2>/dev/null
-cat testable_features.json 2>/dev/null
 ```
 
 Generate run ID and create proof directory. v0.8.6 — when the spec
@@ -65,12 +68,41 @@ screenshot for that surface.
 </step>
 
 <step name="pre_check">
-## 2. Pre-Check + Driver Selection
+## 2. Pre-Check + Driver Selection + Outcome Loader
 
 If `implementation_plan.json` exists, verify all subtasks are completed.
 If any are pending: report and exit.
 
-### 2a. Resolve the verify-proof driver
+### 2a. Load `## User Outcomes` from spec.md (HARD REQUIREMENT — v0.9.0)
+
+`## User Outcomes` is the verify-proof input contract. Parse the
+section via `parseUserOutcomes`:
+
+```js
+import { parseUserOutcomes } from '.aperant/deps/node_modules/@aperant/framework/src/cli/coverage-check/user-outcomes.mjs'
+const parsed = parseUserOutcomes(readFileSync('spec.md', 'utf-8'))
+```
+
+If `parsed.body_kind !== 'outcomes'` AND `parsed.body_kind !== 'empty-with-note'`,
+**ABORT** with a clear error: `"spec.md missing ## User Outcomes — verify-proof
+requires the outcome contract. Run /apt:plan to author it."`
+
+**Do NOT fall back to feature-registry-derived tests.** The legacy
+"discover features from the registry" path is removed (A4 escape hatch).
+The feature registry is informational only — it does NOT seed test
+generation. Every test entry must trace back to a parent or inferred
+outcome from `## User Outcomes`.
+
+For each parent outcome, `parsed.outcomes[i]` carries:
+
+- `id` — positional ID (`O1`, `O2`, ...)
+- `surface` — closed set `{electron, web, cli, api, electron+web}`
+- `text` — outcome prose (the parent bullet)
+- `inferred` — string[] of indented child bullets (the planning LLM's
+  derived sub-checks; empty `[]` when the author wrote none)
+- `requires` — optional dependency on a prior outcome's ID
+
+### 2b. Resolve the verify-proof driver
 
 The workflow is **runtime-agnostic** — it refers to IDL verbs
 (`driver.click(target)`, `driver.screenshot(path)`), never to concrete
@@ -95,9 +127,8 @@ If no driver satisfies a REQUIRED capability, the resolver throws
 `unsatisfied_required_capability` — fail-closed, NOT a silent
 `blocked_by_platform` skip (per ID-02).
 
-**v0.8.6 — per-outcome dispatch.** When the spec carries
-`## User Outcomes`, the workflow runner picks a driver PER OUTCOME
-SURFACE via `resolveDriversForOutcomes()` instead of a single
+**v0.8.6 — per-outcome dispatch.** The workflow runner picks a driver
+PER OUTCOME SURFACE via `resolveDriversForOutcomes()` instead of a single
 per-run driver pick. Each outcome's `[surface]` tag maps to the
 runtime-capability flag a driver must carry; `[electron+web]`
 outcomes dispatch to TWO drivers (one per surface) sharing the same
@@ -107,7 +138,7 @@ still works for the per-run "what driver would be picked?" preview
 the workflow runner imports `resolveDriversForOutcomes` directly
 from the resolver module in Step 7c.
 
-### 2b. Probe optional evidence-capture tools
+### 2c. Probe optional evidence-capture tools
 
 ```bash
 # CDP video capture (optional)
@@ -120,223 +151,185 @@ sandbox_profile}` and `meta.fallback_attempts: [{driver_id, reason}]`
 (see ST11's schema extension in `templates/proof-verification.md`).
 </step>
 
-<step name="automated_checks">
-## 3. Run Automated Checks (with output capture)
+<step name="load_deferred_tools">
+## 2.5. Load Deferred Driver Tools (Claude Code / OpenCode hosts)
 
-Run each check and capture the FULL terminal output for the proof report.
+> **Precondition.** When `--parallel` is requested, the sandbox gate at apt-verify-proof/SKILL.md Step 2c runs BEFORE this step. An unverified sandbox exits with `{status:"error", code:"E_SANDBOX_UNVERIFIED", verdict:"needs_human", reason:"sandbox_unverified"}` without loading any MCP driver tools or entering the outcome-walker loop. See `docs/verify-proof-sandbox-patterns.md` for setup.
 
-**IMPORTANT:** Capture output, don't just check exit codes.
+On Claude Code and OpenCode hosts, the MCP driver tools listed in
+`drivers/<surface>/manifest.json :: transport.mcp_server_id` are
+**deferred** — they exist in the host's MCP server registry but their
+schemas are NOT loaded by default. Before driving ANY UI-surface outcome
+you MUST load them via `ToolSearch(query='select:...')`.
 
-```bash
-# Tests
-pnpm test 2>&1 | head -200
-```
+**Worked example.** For the bundled `browser` driver (whose manifest
+field `transport.mcp_server_id = "puppeteer"` exposes
+`mcp__puppeteer__*` tools):
 
-```bash
-# Type check
-pnpm typecheck 2>&1 | head -100
+```
+ToolSearch(query='select:mcp__puppeteer__browser_navigate,mcp__puppeteer__browser_click,mcp__puppeteer__browser_screenshot,mcp__puppeteer__browser_type')
 ```
 
-```bash
-# Lint
-pnpm lint 2>&1 | head -100
+For the bundled `electron` driver (whose manifest field
+`transport.mcp_server_id = "electron"` exposes `mcp__electron__*` tools):
+
+```
+ToolSearch(query='select:mcp__electron__app_launch,mcp__electron__app_click,mcp__electron__app_screenshot,mcp__electron__app_type')
 ```
 
-Record results in verification.json `automated_checks` object with full output.
+After the `ToolSearch` call, list the now-loaded tool names back to
+confirm they appear in your tool surface. If any required driver tool
+fails to load, emit `result: "needs_human_with_transport"` on every
+outcome targeting that surface and proceed — do NOT fall back to
+file-evidence (the legacy "commit hash as proof" pattern is rejected
+by the proof_gate).
+
+The manifest field is `transport.mcp_server_id` (and
+`transport.skill_id` where applicable). The names
+`mcp_transport.tool_prefix` and `transport.tool_prefix` are NOT real
+manifest fields — do not search for them.
+
+This step is a no-op on host CLIs whose entire MCP surface is loaded
+eagerly (e.g. some Codex builds). Run it unconditionally; if the
+selected tools are already in the surface, `ToolSearch` is idempotent.
 </step>
 
-<step name="discover_features">
-## 4. Deep Feature Discovery + Coverage Gate
+<step name="automated_checks">
+## 3. Run Automated Checks (HARD STOP gate — no "enforced at commit" dodge)
 
-**This step determines verification quality. Do not rush it.**
+Run each of `pnpm lint`, `pnpm test`, `pnpm typecheck` (or the
+configured equivalents) IN THIS RUN and capture the full terminal output.
 
-### 4a. Check the Feature Registry FIRST
+**Closed set for status.** Each check's `status` MUST be one of
+`{pass, fail}`. The legacy string `"enforced_at_commit"` is no longer
+valid — if you find yourself about to write it, STOP. You must actually
+execute the check in this run.
 
 ```bash
-ls .aperant/features/ 2>/dev/null
-cat .aperant/features/{area}.json 2>/dev/null
+# Tests
+pnpm test 2>&1 | tee /tmp/proof-tests.log
 ```
 
-If `.aperant/features/{area}.json` exists for the area under test:
-- **Use it as your primary source** — it lists every sub-feature, wiring status, and test hints
-- Still verify against current code (the registry may be slightly stale)
-- If you discover features NOT in the registry, add them and flag: "Unregistered feature found"
-
-If no feature registry exists:
-- Suggest: "No feature registry found. Consider running `/apt:scan {area}` first for exhaustive coverage."
-- Proceed with manual discovery below, but warn that coverage may be incomplete
-
-**v0.8.6 — read `## User Outcomes` from spec.md FIRST when present.**
-The PRD-shaped spec.md (STANDARD/DEEP tracks) ships a
-`## User Outcomes` section that is the verify-proof input contract:
-`**Epic:**` headline + N atomic outcomes tagged by `[surface]`. When
-present, each outcome maps 1:1 to a test entry — the workflow runner
-does NOT have to invent test units from the feature registry. Fall
-back to the feature-registry-based discovery below ONLY when the spec
-lacks `## User Outcomes` (the v0.8.x warn-not-block migration window
-per spec ID-06; the section becomes a hard block in v0.9.0).
-
-### 4b. Read the source code
-
-You MUST read the actual source code for the features under test. Do not guess.
-For example, if testing a terminal feature:
-- Read the component files to find every prop, every button, every interaction
-- Read settings/config components to find every slider, dropdown, toggle
-- Read toolbar components to find every button and its handler
-- Read any test files for hints about expected behavior
+```bash
+# Type check
+pnpm typecheck 2>&1 | tee /tmp/proof-typecheck.log
+```
 
-### 4c. Enumerate ALL sub-features
+```bash
+# Lint
+pnpm lint 2>&1 | tee /tmp/proof-lint.log
+```
 
-For each feature area, list every individual testable element:
-- Every button → what does it do when clicked?
-- Every input/slider → what range does it accept? What does it change?
-- Every dropdown → what are the options? What does each option do?
-- Every toggle → what does it enable/disable?
-- Every keyboard shortcut → what does it trigger?
+Record results in `verification.json :: automated_checks` with full
+output. Each entry shape:
 
-### 4d. Compare against reference (if available)
+```json
+{
+  "automated_checks": {
+    "tests":     { "status": "pass | fail", "output": "...", "count": 42 },
+    "typecheck": { "status": "pass | fail", "output": "..." },
+    "lint":      { "status": "pass | fail", "output": "..." }
+  }
+}
+```
 
-If the feature was ported from another codebase, or there is a design reference:
-- What should it look like when working correctly?
-- What visual quality markers indicate production-readiness?
-- A clean shell prompt with path and git branch is NOT the same as a blank terminal with cursor artifacts
+**Hard STOP gate.** If any of the three checks has a `status` outside
+`{pass, fail}` (e.g. `enforced_at_commit`, `skipped`, `unknown`), the
+run aborts immediately with `automation_gate: fail` and overall
+verdict `rejected`. The renderer / mapper rejects any input
+verification.json carrying a non-conforming status.
 
-### 4e. Assess what CAN be tested via MCP
+**Verdict roll-up.** `automation_gate = pass` iff ALL THREE of tests,
+typecheck, lint are `pass`. Any single `fail` → `automation_gate: fail`
+→ overall verdict `rejected` regardless of `proof_gate`.
+</step>
 
-For each sub-feature, decide:
-- **testable**: can interact via MCP click/type/navigate + verify via screenshot
-- **observable**: can see in screenshot but cannot interact (e.g., xterm.js internal rendering)
-- **blocked**: cannot test or observe via available tools
+<step name="execute_outcomes">
+## 4. Execute Outcomes (outcome-walker loop)
 
-Mark blocked items honestly. Do NOT mark them as pass.
+**This step replaces the legacy "Deep Feature Discovery" + "Generate
+Tests" + "Execute Tests" sequence.** The workflow runner iterates the
+parent outcomes from Step 2a (`parsed.outcomes`) ONE AT A TIME, in
+document order. For each parent outcome, drive the stated bullet AND
+each inferred child, capture surface-appropriate evidence per child,
+fix-loop on red, advance on green.
 
-### 4f. Coverage Gate (MANDATORY — blocks test execution)
+### 4a. Reload ONLY the current outcome card
 
-After generating your test list, calculate coverage against the feature registry:
+Before driving outcome `Oi`, reload ONLY that outcome's card into
+working memory:
 
 ```
-registered_count = total sub-features in .aperant/features/{area}.json
-tested_count = number of tests written (each linking to a registry_id)
-coverage = tested_count / registered_count
+const outcome = parsed.outcomes[i]
+// outcome = { id, surface, text, inferred[], requires? }
 ```
 
-**Coverage rules:**
-- If `coverage < 50%`: **BLOCK** — "Only {tested_count}/{registered_count} features have tests. Add more tests before proceeding."
-  - Do NOT proceed to step 5. Go back and write more tests.
-- If `coverage < 80%`: **WARN** — list the top untested features by importance. Proceed but note the gap.
-- If `coverage >= 80%`: Proceed normally.
+Do NOT keep the prior outcome's evidence, screenshots, or driver state
+in active memory — this defends against context bloat on long runs
+(30+ outcomes). Persist progress to `verification.json :: tests[]`
+between outcomes; that file is the durable source of truth.
 
-**Every untested registered feature MUST go in the `skipped` array** with a reason.
-Valid skip reasons:
-- `time_constraint` — would take too long relative to value
-- `unsatisfied_optional_capability` — the selected driver lacks an OPTIONAL IDL verb needed by this test (e.g. `assert_network` not implemented). Loud, deliberate skip.
-- `depends_on_other` — requires a feature not yet implemented
-- `not_applicable` — feature is deprecated or not relevant to this verification
+### 4b. Drive the stated bullet (IDL-verb dispatch, MUST-invoke directives)
 
-> **Legacy alias.** `blocked_by_platform` (pre-driver-architecture) is read by the schema reader as an alias for `unsatisfied_optional_capability` and emits a deprecation warning. New writes MUST use the new reason.
+Use the per-outcome driver from `resolveDriversForOutcomes()`:
 
-> **Fail-closed, not a skip:** if a REQUIRED IDL capability has no implementing driver in the resolver chain, the resolver throws `unsatisfied_required_capability` (per ID-02). This aborts the run — it does NOT silently land in the `skipped` array. Coverage loss is loud, deliberate, and audited.
+```js
+import { resolveDriversForOutcomes } from '.aperant/deps/node_modules/@aperant/framework/src/cli/verify-proof/resolver.mjs'
 
-Silence about untested features is NOT acceptable. Every registered sub-feature must appear
-either as a test (with `registry_id`) or in the `skipped` array.
-</step>
+const entries = resolveDriversForOutcomes({
+  drivers, runtime,
+  outcomes: parsed.outcomes,
+})
+// → [{outcome_id: "O1", surface: "electron", driver: {...}}, ...]
+// For [electron+web] outcomes, two entries share outcome_id.
+```
 
-<step name="generate_tests">
-## 5. Generate Test Cases
-
-For EVERY sub-feature discovered in step 4, generate an **action-based test**.
-
-Each test MUST have:
-- **id**: sequential test ID (e.g., "TEST-01")
-- **registry_id**: the sub-feature ID from `.aperant/features/{area}.json` (e.g., "terminals-grid-auto-tile")
-- **name**: descriptive test name
-- **precondition**: what must be true before testing (e.g., "app is running, terminal tab is active")
-- **action**: a specific thing to DO (e.g., "Type 'echo hello' and press Enter")
-- **expected**: a specific observable result (e.g., "Terminal displays 'hello' on the next line")
-
-**Rules for writing tests:**
-1. Every test involves an interaction (type, click, submit, navigate) OR a visual quality check
-2. "It renders" is NOT a valid test — "it renders X with properties Y when you do Z" IS
-3. If a feature has a text input, you must type into it
-4. If a feature has a button, you must click it
-5. If a feature has a slider, you must change it and verify the change took effect
-6. If a feature creates something, verify the creation AND its quality
-7. **Visual quality tests are valid** — "terminal shows clean prompt with path and git branch" IS a valid test
-8. **Artifact detection is valid** — "no rendering artifacts, stray characters, or broken formatting" IS a valid test
-9. Test sub-features exhaustively — if settings has 5 sliders, write 5 tests, not 1
-10. **Every test must reference a `registry_id`** from the feature registry. This links tests to sub-features and makes coverage tracking automatic.
-
-Write ALL tests into verification.json `tests` array before starting execution.
-
-**Gate:** Do not proceed to step 6 until ALL tests are written AND the coverage gate from step 4f passes.
-</step>
+For each `entry` whose `outcome_id` matches `outcome.id`:
 
-<step name="start_video">
-## 6. Start Video Capture
+1. Compose an action sequence from `outcome.text` (the parent prose
+   describes the user-facing capability — translate into IDL verbs):
+   - If it says "type X" → `driver.type({ target, text: "X" })`
+   - If it says "click X" → `driver.click({ target })`
+   - If it says "navigate to X" → `driver.navigate({ url: "X" })`
+   - If it says "press key X" → `driver.key({ key: "X" })`
+2. Invoke IDL verbs on `entry.driver`.
+3. Capture surface-appropriate evidence per Step 4d.
+4. Record the test entry in `verification.json :: tests[]` with
+   `outcome_id = outcome.id` and `surface = entry.surface`.
 
-If CDP capture is available, start recording BEFORE executing tests:
+**Transport dispatch directive (MUST honor — TD-08).** When `driver.transport.skill_id` is set AND the host CLI exposes the Skill tool AND the outcome surface is `web`, the workflow runner MUST invoke `Skill({skill: driver.transport.skill_id, args: ...})` (passing the IDL verb args) and MUST record `transport: "skill"` on the resulting test entry in verification.json. When the host CLI does NOT expose the Skill tool, fall back to the MCP transport via the existing puppeteer MCP server and record `transport: "mcp"`. The driver's `chooseTransport({has_skill_tool})` helper computes the choice; the workflow runner is the site that knows `has_skill_tool`. This directive is LLM-honored (the v1 verify-proof runner is the host LLM following this workflow as prose); a text-level grep guard (TD-08) pins the `MUST` language so future edits cannot silently soften it to `SHOULD`.
 
-```bash
-apt-proof-video capture --port 9222 --duration {estimated_total_seconds} --fps 2 --output ${PROOF_DIR}
-```
+### 4c. Drive each inferred child
 
-Run this in the background. The video will capture your ACTUAL test session —
-the same interactions that produce screenshots. This ensures video and screenshots
-are from the SAME session.
+For each `child` in `outcome.inferred`:
 
-**Important:** Estimate duration generously. Better to have extra video than to miss tests.
-- ~10 seconds per test is a reasonable estimate
-- Add 30 seconds for navigation overhead
-- If 20 tests: --duration 230
+1. Compose an action sequence from the child prose (these are the
+   sub-checks the planning LLM derived from the parent — e.g. "X-button
+   closes", "outside-click closes", "Esc closes + returns focus").
+2. Invoke IDL verbs.
+3. Capture evidence per Step 4d.
+4. Record a SEPARATE test entry in `verification.json :: tests[]`
+   carrying:
+   - `outcome_id` = `outcome.id` (same as parent)
+   - `inferred_index` = index of the child in `outcome.inferred[]`
+   - `surface` = `entry.surface`
+   - the standard `action / expected / actual / evidence / result` fields.
 
-**Note:** Captured frames are auto-stitched into an MP4 file by the tool. No manual assembly needed.
+### 4d. Capture surface-appropriate evidence (fail-closed)
 
-If CDP is NOT available, note it and proceed without video.
-</step>
+Surface evidence requirements:
 
-<step name="execute_tests">
-## 7. Execute Tests (one at a time)
-
-For each test, in order:
-
-### 7a. Perform the Action
-Actually do what the test says — invoke the IDL verb on the selected driver:
-- If it says "type X" → `driver.type({ target, text: "X" })`
-- If it says "click X" → `driver.click({ target })`
-- If it says "navigate to X" → `driver.navigate({ url: "X" })`
-- If it says "press key X" → `driver.key({ key: "X" })`
-- If it says "run command X" → `driver.execute_js({ script: "X" })`
-
-The driver layer translates IDL verbs to its transport (an MCP server,
-a local binary, or a built-in HTTP request). Workflow prose names ONLY
-IDL verbs per ID-01 — concrete tool names live in
-`packages/framework/drivers/<driver>/driver.mjs`.
-
-**v0.8.6 — transport dispatch directive (MUST honor).** When
-`driver.transport.skill_id` is set AND the host CLI exposes the
-Skill tool AND the outcome surface is `web`, the workflow runner
-MUST invoke `Skill({skill: driver.transport.skill_id, args: ...})`
-(passing the IDL verb args) and MUST record `transport: "skill"` on
-the resulting test entry in verification.json. When the host CLI
-does NOT expose the Skill tool, fall back to the MCP transport via
-the existing puppeteer MCP server and record `transport: "mcp"`.
-The driver's `chooseTransport({has_skill_tool})` helper computes
-the choice; the workflow runner is the site that knows
-`has_skill_tool`. This directive is LLM-honored (the v1 verify-proof
-runner is the host LLM following this workflow as prose); a
-text-level grep guard (TD-08) pins the `MUST` language so future
-edits cannot silently soften it to `SHOULD`.
-
-### 7b. Wait for Result
-Wait for the action to complete. If it involves loading, wait for the load.
-Add a short delay (1-2 seconds) so the CDP capture also captures this state.
-
-### 7c. Capture Evidence
-Take a screenshot AFTER the action completes. v0.8.6 — screenshots
-land under PER-SURFACE subdirectories, with the per-outcome driver
-returned by `resolveDriversForOutcomes()`:
+| Surface | Acceptable evidence |
+|---|---|
+| `electron`, `web`, `electron+web` | Screenshot from `driver.screenshot()` under `${PROOF_DIR}/${surface}/screenshots/...` |
+| `cli` | Captured command output (stdout/stderr) under `${PROOF_DIR}/cli/output/...` |
+| `api` | HTTP request/response capture under `${PROOF_DIR}/api/captures/...` |
 
-```
+For UI-surface outcomes, take a screenshot AFTER each action completes.
+Screenshots land under PER-SURFACE subdirectories — the per-outcome
+driver returned by `resolveDriversForOutcomes()` carries the surface:
+
+```js
 // Pick a driver per outcome surface (NOT per run). `entries[]` is
 // the resolver's per-(outcome, surface) dispatch — for an
 // [electron+web] outcome you get TWO entries sharing outcome_id
@@ -351,130 +344,217 @@ for (const entry of entries) {
 
 Single-surface outcomes (`[electron]`, `[web]`, `[cli]`, `[api]`)
 produce one screenshot under `${PROOF_DIR}/${surface}/screenshots/`;
-cross-surface (`[electron+web]`) produces two — one per surface tree
-— with both test entries in `verification.json:tests[]` carrying the
-same `id` but distinct `surface` and `evidence` fields.
-
-### 7d. Analyze Evidence
-**MANDATORY and CRITICAL.** Every screenshot must be analyzed in detail.
-
-You MUST describe what you see — not what you expect to see. Be adversarial:
-- Are there rendering artifacts? Stray characters? Broken formatting?
-- Does the UI look production-quality or does it look broken?
-- Compare against what a real user would expect to see
-- If testing a terminal: is the prompt clean? Is the path correct? Are there garbage characters?
-- If testing settings: did the value actually change? Is the control responsive?
+cross-surface (`[electron+web]`) produces two — one per surface tree —
+with both test entries in `verification.json :: tests[]` carrying the
+same `outcome_id` but distinct `surface` and `evidence` fields.
 
-Write the analysis into the test's `analysis` field. Be specific and critical.
-"The terminal shows a cursor" is NOT analysis.
-"The terminal shows a blinking cursor at position 0,0 with no shell prompt, path, or git branch — this indicates the PTY session is not connected" IS analysis.
-
-If Gemini API is available, also run:
-```bash
-apt-proof-video analyze "${PROOF_DIR}/screenshots/{feature-id}-test-{n}.png" \
-  --model default \
-  --spec "{expected result from this test}"
-```
-
-### 7e. Record Result to verification.json
-After each test, update the test entry in verification.json `tests` array.
-v0.8.6 adds `surface` and `transport` fields per test entry — the workflow
-runner populates them from the per-outcome dispatch directive:
+Example test entry shape (electron surface, MCP transport):
 
 ```json
 {
   "id": "TEST-01",
-  "registry_id": "terminals-grid-auto-tile",
-  "name": "Three Terminal Grid Auto-Tile",
   "outcome_id": "O3",
   "surface": "electron",
   "transport": "mcp",
-  "precondition": "2 terminals active",
   "action": "Press Cmd+T",
   "expected": "Grid reflows to 2+1 layout",
-  "actual": "Grid correctly tiled",
-  "evidence": "electron/screenshots/03-grid.png",
-  "analysis": "Detailed adversarial analysis of what is actually visible in the screenshot...",
-  "result": "pass",
-  "severity": null
+  "evidence": "electron/screenshots/O3.png",
+  "result": "pass"
 }
 ```
 
-Compare `expected` vs `actual`:
-- If they match → `result: "pass"`
-- If they partially match but have quality issues → `result: "fail"`, `severity: "minor"` or `"cosmetic"`
-- If they don't match → `result: "fail"`, set `severity` (`"blocker"`, `"major"`, `"minor"`, `"cosmetic"`), add to `gaps` array
-- If you can't test → `result: "blocked"`, explain why in `analysis`
+**`file-evidence: <commit-hash>` is NEVER sufficient.** The proof_gate
+rejects that pattern for ALL surfaces — UI surfaces require screenshots,
+CLI requires actual command output, API requires actual HTTP traces.
+A commit hash is not proof a feature works.
+
+**If a UI-surface outcome cannot capture screenshot evidence because
+the host lacks the MCP driver transport (deferred tools didn't load,
+puppeteer/electron-mcp-server unavailable):** write
+`result: "needs_human_with_transport"` on that test entry, include
+a `to_unblock` field explaining what the human needs to install /
+load, and proceed. Do NOT fall back to file-evidence.
+
+### 4e. Analyze evidence (adversarial)
+
+For each evidence artifact, write the `analysis` field with what you
+**see**, not what you **expect to see**. Be adversarial:
+
+- UI: Are there rendering artifacts? Stray characters? Broken layout?
+  Does the actual screenshot match the outcome's stated expectation?
+- CLI: Did the command actually emit the expected output, or just exit 0?
+- API: Did the response payload match the expected shape, or just 200?
+
+"The terminal shows a cursor" is NOT analysis. "The terminal shows a
+blinking cursor at position 0,0 with no shell prompt — the PTY session
+is not connected" IS analysis.
+
+### 4f. Fail-loop on red, advance on green
+
+After processing the parent + all inferred children for outcome `Oi`:
+
+- If ALL test entries for `Oi` have `result ∈ {pass}` → advance to `Oi+1`.
+- If ANY test entry has `result: "fail"` → fix the code, RE-RUN ONLY
+  THE FAILING ENTRIES for `Oi`, capture fresh evidence, write back to
+  `verification.json`. Loop up to `verification.max_iterations` times
+  (default 3 from config). After the iteration cap, leave `Oi` with
+  `result: "fail"` on the unresolved entries and continue — overall
+  verdict will be `rejected`.
+- If ANY test entry has `result: "needs_human_with_transport"` →
+  advance to `Oi+1` (the human will install the transport and re-run).
+  Overall verdict will be `needs_human`.
+
+### 4g. Write verification.json after each outcome
+
+Persist `verification.json :: tests[]` to disk after EVERY outcome
+completes (success, fail, or needs_human_with_transport). This ensures
+progress survives session interruption — `parsed.outcomes[i].id`
+becomes the resume point.
+
+### 4h. Skip-reason taxonomy (legacy compatibility)
+
+When an outcome cannot be driven because the selected driver lacks an
+**OPTIONAL** IDL verb (e.g. `assert_network` not implemented), record
+the test entry with `result: "skip"` and `reason: "unsatisfied_optional_capability"`.
+This is the deliberate, loud skip path — log it in `skipped[]` so
+coverage loss is auditable.
+
+> **Legacy alias.** `blocked_by_platform` (pre-driver-architecture) is
+> read by the schema reader as an alias for `unsatisfied_optional_capability`
+> and emits a deprecation warning. New writes MUST use the new reason.
+
+> **Fail-closed, not a skip:** if a REQUIRED IDL capability has no
+> implementing driver in the resolver chain, the resolver throws
+> `unsatisfied_required_capability` (per ID-02). This aborts the run —
+> it does NOT silently land in `skipped[]`.
+
+**Gate:** Do not proceed to Step 5 until every parent outcome has been
+processed (success, fail, or needs_human_with_transport) AND
+`verification.json :: tests[]` carries entries for every parent +
+inferred-child combination.
+</step>
 
-**Do NOT give a pass to something that has visual artifacts, broken rendering, or
-looks different from the expected production quality.**
+<step name="start_video">
+## 5. Start Video Capture (optional)
 
-### 7f. Write verification.json after each test
-Write the updated verification.json to disk after each test completes.
-This ensures progress is saved even if the session is interrupted.
+If CDP capture is available, start recording BEFORE executing outcomes:
 
-**Gate:** Complete ALL tests before proceeding to step 8.
+```bash
+apt-proof-video capture --port 9222 --duration {estimated_total_seconds} --fps 2 --output ${PROOF_DIR}
+```
+
+Run this in the background. The video will capture your ACTUAL outcome
+walker session — the same interactions that produce screenshots. This
+ensures video and screenshots are from the SAME session.
+
+**Important:** Estimate duration generously. Better to have extra video
+than to miss outcomes.
+- ~15 seconds per outcome (parent + inferred children) is a reasonable estimate
+- Add 30 seconds for navigation overhead
+
+**Note:** Captured frames are auto-stitched into an MP4 file by the tool.
+
+If CDP is NOT available, note it and proceed without video.
+
+(In practice this step is interleaved with Step 4 — kick off the
+capture before the first outcome and stop it after the last.)
 </step>
 
 <step name="score_dimensions">
-## 8. Score QA Dimensions
+## 6. Score QA Dimensions (informational rationale)
 
 Based on the evidence collected (not assumed), score each dimension.
-Write scores to verification.json `dimensions` object:
+Write scores to verification.json `dimensions` object.
+
+**v0.9.0 — dimensions are INFORMATIONAL rationale only.** The verdict
+no longer derives from per-dimension minimums; it derives from the
+two-gate envelope (Step 7).
 
 ```json
 {
   "dimensions": {
-    "completeness": {
-      "score": 7,
-      "rationale": "18/22 spec requirements have passing tests. 4 blocked by platform."
-    },
-    "correctness": {
-      "score": 8,
-      "rationale": "All tested features behave as expected. No blockers or majors."
-    },
-    "code_quality": {
-      "score": 9,
-      "rationale": "Zero lint errors, zero type errors."
-    },
-    "test_coverage": {
-      "score": 6,
-      "rationale": "Unit tests cover core logic but no integration tests for new grid layout."
-    }
+    "completeness": { "score": 7, "rationale": "All 12 outcomes processed; 2 needed transport, 10 driven." },
+    "correctness":  { "score": 8, "rationale": "All driven outcomes matched expected; no regressions." },
+    "code_quality": { "score": 9, "rationale": "Zero lint errors, zero type errors." },
+    "test_coverage":{ "score": 6, "rationale": "Unit tests cover core logic; integration tests for the new outcome walker live in the framework package." }
   }
 }
 ```
 
-**Scoring rules:**
+**Scoring rules** (all 1-10):
 
-**Completeness (1-10):**
-- Count how many spec requirements have passing tests
-- A requirement without a test scores 0
-- A requirement with a failing test scores 0
-- Sub-features not tested (e.g., individual settings) lower this score
+- **Completeness**: count outcomes processed vs. authored (`tests` per
+  parent + inferred / total expected).
+- **Correctness**: per-outcome verdict roll-up — any blocker = max 3,
+  any major = max 5.
+- **Code Quality**: lint + typecheck results.
+- **Test Coverage**: unit + integration tests landed for the feature.
 
-**Correctness (1-10):**
-- Based on automated check results AND manual test results
-- Any blocker = max score 3
-- Any major = max score 5
-- Visual artifacts or rendering issues count as failures
+Dimensions surface in the HTML report as rationale chips alongside the
+two gate badges. They do NOT change the verdict.
+</step>
+
+<step name="derive_verdict">
+## 7. Derive Two-Gate Verdict
+
+The verdict is the closed set `{approved, rejected, needs_human}`.
+**`approved_with_notes` is DELETED — do not emit it.**
+
+### 7a. Compute `automation_gate`
+
+```
+automation_gate = (
+  automated_checks.tests.status === 'pass' AND
+  automated_checks.typecheck.status === 'pass' AND
+  automated_checks.lint.status === 'pass'
+) ? 'pass' : 'fail'
+```
+
+### 7b. Compute `proof_gate`
+
+For each test entry in `verification.json :: tests[]`:
 
-**Code Quality (1-10):**
-- Based on lint results and code review (if done)
+- UI-surface (`electron`, `web`, `electron+web`) with
+  `evidence` matching `^file-evidence:` → that test's effective result
+  is `needs_human_with_transport` regardless of the written `result`.
+- Any test whose effective result is `fail` → contributes to
+  `proof_gate: fail`.
+- Any test whose effective result is `needs_human_with_transport` →
+  contributes to overall verdict `needs_human` (does NOT fail `proof_gate`
+  on its own — the gate "passes" with the caveat that a human needs to
+  install the transport).
 
-**Test Coverage (1-10):**
-- Based on test suite results and whether new code has tests
+```
+proof_gate = (
+  no test has effective result 'fail' AND
+  every outcome has at least one evidence entry per surface
+) ? 'pass' : 'fail'
+```
 
-**Derive verdict:**
-- ALL dimensions >= 7: `"approved"`
-- ALL dimensions >= 5: `"approved_with_notes"`
-- ANY dimension < 5: `"rejected"`
+### 7c. Derive overall verdict
 
-Write verdict to verification.json `verdict` field.
+```
+if (automation_gate === 'fail') return 'rejected'
+if (any test has effective result 'needs_human_with_transport') return 'needs_human'
+if (proof_gate === 'fail') return 'rejected'
+return 'approved'
+```
+
+Write `verification.json :: meta.verdict` and `verification.json :: gates`:
+
+```json
+{
+  "meta": { "verdict": "approved | rejected | needs_human" },
+  "gates": {
+    "automation_gate": "pass | fail",
+    "proof_gate": "pass | fail"
+  }
+}
+```
 </step>
 
 <step name="multi_model" optional="true">
-## 9. Multi-Model Verification (if enabled in config)
+## 8. Multi-Model Verification (if enabled in config)
 
 Only run if `.aperant/config.json` has `multi_model.enabled: true`.
 
@@ -485,7 +565,7 @@ Record each model's verdict in verification.json `model_verdicts` array.
 </step>
 
 <step name="generate_report">
-## 10. Generate HTML Proof Report
+## 9. Generate HTML Proof Report
 
 Use the `apt-proof-video report` command to generate the HTML report from verification.json:
 
@@ -496,10 +576,12 @@ apt-proof-video report --proof-dir "${PROOF_DIR}" --title "{descriptive title}"
 The report command:
 1. Reads verification.json as the primary data source
 2. Recursively scans for screenshots in subdirectories
-3. Generates feature checklists with pass/fail badges per test
-4. Embeds screenshots inline per test
+3. Generates one card per `outcome_id` with stated prose + inferred
+   children + per-child evidence
+4. Renders two gate badges (`automation_gate`, `proof_gate`) plus
+   the overall verdict badge in the header
 5. Shows automated checks with expandable output
-6. Shows QA dimension progress bars
+6. Shows QA dimension rationale chips
 7. Shows gaps with severity badges
 8. Embeds video player (frames are auto-stitched to MP4)
 
@@ -510,7 +592,7 @@ ln -sf "${PROOF_DIR}/report.html" .aperant/proof-report.html
 </step>
 
 <step name="open_report">
-## 11. Open Report
+## 10. Open Report
 
 Read `verification.open_report` from the MERGED config (per-device override lives in `.aperant/config.local.json` per AUDIT-001; do not read raw `.aperant/config.json`). If true (default):
 ```bash
@@ -519,7 +601,7 @@ open "${PROOF_DIR}/report.html"
 </step>
 
 <step name="write_artifacts">
-## 12. Write Artifacts
+## 11. Write Artifacts
 
 Write the following files:
 - `${PROOF_DIR}/verification.json` — the structured verification record (source of truth)
@@ -536,40 +618,35 @@ apt-tools commit "qa: proof verification {verdict}" --files ${PROOF_DIR}/verific
 </step>
 
 <step name="report_output">
-## 13. Final Output
+## 12. Final Output
 
 ```
 Proof Verification: {VERDICT}
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Outcome: {one-line summary}
 
+Gates:
+  automation_gate: {pass/fail}
+  proof_gate:      {pass/fail}
+
 Checks:
   Tests:     {pass/fail} ({count} tests)
   Types:     {pass/fail}
   Lint:      {pass/fail}
 
-Scores:
-  Completeness:  {n}/10
-  Correctness:   {n}/10
-  Code Quality:  {n}/10
-  Test Coverage: {n}/10
-
-Coverage:
-  Registry:  {tested}/{total} features ({percent}%)
-  Skipped:   {n} features (see skipped array)
-
-Evidence:
-  Features:    {n} tested ({passed} pass, {failed} fail, {blocked} blocked)
-  Screenshots: {n} captured, {n} analyzed
-  Video:       {captured/not available}
-  Gaps:        {n} issues ({blockers} blockers, {majors} major)
+Outcomes:
+  Total:     {n} parent outcomes (+ {m} inferred children)
+  Approved:  {n}
+  Rejected:  {n}
+  Needs Human: {n} (transport unavailable)
 
 Proof: {PROOF_DIR}/
-  verification.json  (structured test record)
+  verification.json  (structured outcome record)
   report.html        (opened in browser)
   report.md          (for PR embedding)
 
 {If rejected:} Fix gaps and re-run /apt:verify-proof
+{If needs_human:} Install the missing driver transports and re-run
 {If approved:} Next: /apt:review (optional code review)
 ```
 </step>
@@ -581,17 +658,14 @@ Proof: {PROOF_DIR}/
 
 These gates MUST be respected — do not skip them:
 
-1. **Pre-check gate** (step 2): All subtasks must be completed before verification starts
-2. **Feature discovery gate** (step 4): Source code MUST be read before writing tests
-3. **Coverage gate** (step 4f): Coverage < 50% blocks test execution. Every untested feature must be in the skipped array.
-4. **Test generation gate** (step 5): ALL tests must be written before execution starts
-5. **Registry link gate** (step 5): Every test must have a `registry_id` linking to the feature registry
-6. **Video gate** (step 6): Video capture starts BEFORE test execution, not after
-7. **Test execution gate** (step 7): ALL tests must be executed before scoring
-8. **Evidence gate** (step 7c-7d): Every test must have evidence AND critical analysis
-9. **Quality gate** (step 7d): Visual artifacts, broken rendering, and quality issues MUST be reported as failures
-10. **Scoring gate** (step 8): Scores must be derived from evidence, not assumed
-11. **Output format gate**: Write verification.json, NEVER VERIFICATION.md
+1. **Pre-check gate** (Step 2): All subtasks must be completed before verification starts.
+2. **User Outcomes gate** (Step 2a): spec.md MUST carry `## User Outcomes` with `body_kind ∈ {outcomes, empty-with-note}`. No fallback to feature-registry-derived tests.
+3. **Deferred-tool-load gate** (Step 2.5): On Claude Code / OpenCode hosts, MCP driver tools listed under `drivers/<surface>/manifest.json :: transport.mcp_server_id` MUST be loaded via `ToolSearch(query='select:...')` BEFORE driving any UI-surface outcome.
+4. **Automation gate** (Step 3): `automated_checks.{tests,typecheck,lint}.status ∈ {pass, fail}` (closed set). No `"enforced_at_commit"`. Any single `fail` → `automation_gate: fail`.
+5. **Outcome-walker gate** (Step 4): every parent outcome AND every inferred child has its own test entry in `verification.json :: tests[]` with evidence appropriate to its surface OR `result: "needs_human_with_transport"`. File-evidence (`"file-evidence: ..."`) is NEVER sufficient for any surface.
+6. **Proof gate** (Step 7b): every outcome has surface-appropriate evidence. UI outcomes carrying `evidence: "file-evidence: ..."` are rejected as `needs_human_with_transport`.
+7. **Verdict gate** (Step 7c): the verdict is exactly one of `{approved, rejected, needs_human}`. The legacy `approved_with_notes` middle band is DELETED — emitting it is a hard error.
+8. **Output format gate** (Step 11): Write verification.json, NEVER VERIFICATION.md.
 </gates>
 </process>
 </output>