@aperant/framework 0.10.0 → 0.12.0

package/templates/proof-verification.md

@@ -17,7 +17,7 @@ JSON schema reference for `.aperant/proof/{app}/{date}/{run}/verification.json`
     "started": "{ISO timestamp}",
     "updated": "{ISO timestamp}",
     "spec": "{spec.md path or task description}",
-    "verdict": "pending | approved | approved_with_notes | rejected",
+    "verdict": "pending | approved | rejected | needs_human",
     "tools": ["electron", "puppeteer", "cdp_video"],
     "selected_driver": {
       "driverId": "electron",
@@ -47,6 +47,11 @@ JSON schema reference for `.aperant/proof/{app}/{date}/{run}/verification.json`
     }
   },
 
+  "gates": {
+    "automation_gate": "pass | fail",
+    "proof_gate": "pass | fail"
+  },
+
   "coverage": {
     "registry_file": ".aperant/features/{area}.json",
     "registered_count": 0,
@@ -76,7 +81,7 @@ JSON schema reference for `.aperant/proof/{app}/{date}/{run}/verification.json`
       "actual": "Grid correctly tiled to 2+1",
       "evidence": "electron/screenshots/03-grid.png",
       "analysis": "Screenshot shows three terminal panes. Top row has 2 equal-width panes, bottom row has 1 centered pane. Grid lines are clean, no overlap or gap artifacts. Each pane shows an active shell prompt with correct path.",
-      "result": "pass | fail | blocked | skip",
+      "result": "pass | fail | blocked | skip | needs_human_with_transport",
       "severity": null
     },
     {
@@ -189,7 +194,19 @@ JSON schema reference for `.aperant/proof/{app}/{date}/{run}/verification.json`
 | `fallback_attempts` | array | IMMUTABLE | Drivers the resolver REJECTED before selecting. Each entry has `driver_id` + `reason` (missing capabilities, stability filter, hash drift, policy denial). Audit trail for coverage-loss decisions. |
 
 ### automated_checks
-Each check has `status` (pass/fail) and `output` (captured terminal output). These are populated in step 3 before any manual testing begins.
+Each check has `status` (closed set `{pass, fail}`) and `output` (captured terminal output). These are populated in Step 3 before any outcome driving begins.
+
+**Hard STOP gate (v0.9.0).** `status` MUST be one of `{pass, fail}`. The legacy `"enforced_at_commit"` dodge string is REJECTED — the workflow runner aborts at Step 3 with `automation_gate: fail` if any check carries a non-conforming status. Each check must actually execute in the run (no deferring to commit-time enforcement).
+
+### gates (v0.9.0)
+
+Top-level `{automation_gate, proof_gate}` derived from `automated_checks` (gate 1) and per-outcome evidence (gate 2). Closed set `{pass, fail}` for each. The two-gate envelope drives `meta.verdict`:
+
+| automation_gate | proof_gate | verdict |
+|---|---|---|
+| `pass` | `pass` | `approved` |
+| `pass` | `fail` | `needs_human` (UI-surface transport gap; install driver and re-run) |
+| `fail` | * | `rejected` (any of lint/typecheck/tests red) |
 
 ### coverage
 | Field | Type | Description |
@@ -219,7 +236,7 @@ Each test entry tracks one sub-feature verification. Fields:
 | `actual` | string | OVERWRITE | What actually happened (filled after testing) |
 | `evidence` | string | OVERWRITE | Screenshot filename or video timestamp. v0.8.6 — paths are PER-SURFACE: `{surface}/screenshots/{outcome-id}.png`. |
 | `analysis` | string | OVERWRITE | Adversarial analysis of evidence — describe what you SEE, not what you expect |
-| `result` | string | OVERWRITE | `pass`, `fail`, `blocked`, or `skip` |
+| `result` | string | OVERWRITE | `pass`, `fail`, `blocked`, `skip`, or `needs_human_with_transport` (v0.9.0 — UI-surface outcome lacks driver transport; host must install MCP server / driver and re-run). `blocked` keeps its legacy meaning: driver advertised the capability but couldn't perform it in this run. |
 | `severity` | string/null | OVERWRITE | `blocker`, `major`, `minor`, `cosmetic`, or `null` if pass |
 
 ### skipped (MANDATORY)
@@ -242,10 +259,12 @@ Four QA dimensions, each with `score` (1-10) and `rationale` (string). Scores ar
 - Any major in the area → max score 5
 - A dimension cannot score above 5 if any blocker exists
 
-**Verdict derivation:**
-- ALL dimensions >= 7 → `approved`
-- ALL dimensions >= 5 → `approved_with_notes`
-- ANY dimension < 5 → `rejected`
+**Verdict derivation (v0.9.0 two-gate envelope — see workflow Step 7):**
+- `automation_gate: pass` AND `proof_gate: pass` → `approved`
+- `automation_gate: pass` AND `proof_gate: fail` → `needs_human`
+- `automation_gate: fail` OR critical issues unresolved → `rejected`
+
+Dimensions are informational rationale only — they do NOT drive the verdict in v0.9.0+.
 
 ### gaps
 Issues discovered during testing. Feeds into the fix planning pipeline.