@aperant/framework 0.11.0 → 0.12.0

package/dist/cli/verify-proof/sandbox/sandbox-config.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-config.mjs","sourceRoot":"","sources":["../../../../src/cli/verify-proof/sandbox/sandbox-config.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAC/D,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAExC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;AAEzD;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB;IAChC,+DAA+D;IAC/D,yCAAyC;IACzC,OAAO,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC,CAAA;AAC7D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB;IACrC,MAAM,GAAG,GAAG,iBAAiB,EAAE,CAAA;IAC/B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAA;IAC/B,MAAM,GAAG,GAAG,EAAE,CAAA;IACd,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QAC/D,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE;YAAE,SAAQ;QAClC,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,EAAE,aAAa,CAAC,CAAA;QACvD,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;YAAE,SAAQ;QACrC,IAAI,CAAC;YACJ,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;QACxD,CAAC;QAAC,MAAM,CAAC;YACR,4BAA4B;QAC7B,CAAC;IACF,CAAC;IACD,OAAO,GAAG,CAAA;AACX,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAU;IAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,UAAU,EAAE,aAAa,CAAC,CAAA;IACjE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA;IAClC,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAA;QACtD,MAAM,CAAC,GAAG,MAAM,EAAE,YAAY,CAAA;QAC9B,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAA;QACpD,OAAO,CAAC,CAAC,OAAO,IAAI,IAAI,CAAA;IACzB,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,CAAA;IACZ,CAAC;AACF,CAAC"}

package/dist/cli/verify-proof/sandbox/self-test.d.mts

@@ -0,0 +1,39 @@
+/**
+ * @typedef {Object} SelfTestVerdict
+ * @property {boolean} verified
+ * @property {'approved'|'needs_human'} verdict
+ * @property {null|'self_test_failed_sqlite_busy'|'self_test_failed_port_conflict'|'self_test_failed_app_init_timeout'} reason
+ * @property {number} durationMs
+ * @property {{A: ChildOutcome, B: ChildOutcome}} children
+ */
+/**
+ * @typedef {Object} ChildOutcome
+ * @property {boolean} ready
+ * @property {string|null} failureReason
+ * @property {string} stderrTail
+ */
+/**
+ * @param {{projectDir: string, recipeId: string, recipes: object[]}} args
+ * @returns {Promise<SelfTestVerdict>}
+ */
+export function runSelfTest({ projectDir, recipeId, recipes }: {
+    projectDir: string;
+    recipeId: string;
+    recipes: object[];
+}): Promise<SelfTestVerdict>;
+export type SelfTestVerdict = {
+    verified: boolean;
+    verdict: "approved" | "needs_human";
+    reason: null | "self_test_failed_sqlite_busy" | "self_test_failed_port_conflict" | "self_test_failed_app_init_timeout";
+    durationMs: number;
+    children: {
+        A: ChildOutcome;
+        B: ChildOutcome;
+    };
+};
+export type ChildOutcome = {
+    ready: boolean;
+    failureReason: string | null;
+    stderrTail: string;
+};
+//# sourceMappingURL=self-test.d.mts.map

package/dist/cli/verify-proof/sandbox/self-test.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-test.d.mts","sourceRoot":"","sources":["../../../../src/cli/verify-proof/sandbox/self-test.mjs"],"names":[],"mappings":"AAgCA;;;;;;;GAOG;AAEH;;;;;GAKG;AAEH;;;GAGG;AACH,+DAHW;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAC,GACvD,OAAO,CAAC,eAAe,CAAC,CA4CpC;;cA5Da,OAAO;aACP,UAAU,GAAC,aAAa;YACxB,IAAI,GAAC,8BAA8B,GAAC,gCAAgC,GAAC,mCAAmC;gBACxG,MAAM;cACN;QAAC,CAAC,EAAE,YAAY,CAAC;QAAC,CAAC,EAAE,YAAY,CAAA;KAAC;;;WAKlC,OAAO;mBACP,MAAM,GAAC,IAAI;gBACX,MAAM"}

package/dist/cli/verify-proof/sandbox/self-test.mjs

@@ -0,0 +1,248 @@
+/**
+ * self-test.mjs — two-instance concurrent self-test for parallel
+ * /apt:verify-proof.
+ *
+ * Spawns TWO instances of the recipe's launch command concurrently
+ * (Promise.all with B jittered 50-150 ms) against per-instance sandbox
+ * dirs. Asserts BOTH instances reach the recipe's `readiness.logPattern`
+ * within `readiness.timeoutMs` AND neither emits `SQLITE_BUSY` or
+ * `EADDRINUSE`/`bind` errors in stderr.
+ *
+ * The verdict envelope shape mirrors verify-proof v2's
+ * `verification.json :: meta.verdict`:
+ *   {verified: bool, verdict: 'approved'|'needs_human',
+ *    reason: null|'self_test_failed_sqlite_busy'|
+ *            'self_test_failed_port_conflict'|
+ *            'self_test_failed_app_init_timeout',
+ *    durationMs: number}
+ *
+ * Cross-platform via `node:child_process.spawn` (NO shell). win32 short-
+ * circuits at the verify-sandbox command layer (subtask 4.2) — this
+ * module assumes a POSIX-ish host.
+ *
+ * No state-file writing here (4.2's job). Pure functional contract so
+ * the integration tests can drive it via `vi.spyOn(child_process,
+ * 'spawn')`.
+ */
+import child_process from 'node:child_process';
+import { mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+/**
+ * @typedef {Object} SelfTestVerdict
+ * @property {boolean} verified
+ * @property {'approved'|'needs_human'} verdict
+ * @property {null|'self_test_failed_sqlite_busy'|'self_test_failed_port_conflict'|'self_test_failed_app_init_timeout'} reason
+ * @property {number} durationMs
+ * @property {{A: ChildOutcome, B: ChildOutcome}} children
+ */
+/**
+ * @typedef {Object} ChildOutcome
+ * @property {boolean} ready
+ * @property {string|null} failureReason
+ * @property {string} stderrTail
+ */
+/**
+ * @param {{projectDir: string, recipeId: string, recipes: object[]}} args
+ * @returns {Promise<SelfTestVerdict>}
+ */
+export async function runSelfTest({ projectDir, recipeId, recipes }) {
+    const recipe = (recipes ?? []).find((r) => r && r.recipeId === recipeId);
+    if (!recipe) {
+        throw new Error(`runSelfTest: recipe not found: ${recipeId}`);
+    }
+    const launch = recipe.launch;
+    if (!launch?.binary) {
+        throw new Error(`runSelfTest: recipe ${recipeId} missing launch.{binary, args}`);
+    }
+    const readiness = recipe.readiness;
+    if (!readiness || typeof readiness.logPattern !== 'string') {
+        throw new Error(`runSelfTest: recipe ${recipeId} missing readiness.logPattern`);
+    }
+    const timeoutMs = readiness.timeoutMs ?? 30000;
+    const pid = process.pid;
+    const sandboxRoot = join(tmpdir(), `aperant-sandbox-${pid}-${Date.now()}`);
+    const dirs = {
+        A: join(sandboxRoot, 'A'),
+        B: join(sandboxRoot, 'B'),
+    };
+    mkdirSync(dirs.A, { recursive: true });
+    mkdirSync(dirs.B, { recursive: true });
+    const startedAt = Date.now();
+    const jitter = 50 + Math.random() * 100;
+    // Concurrency by construction: A starts immediately, B's start is
+    // awaited via a microtask + jitter delay. Promise.all races them.
+    const [outcomeA, outcomeB] = await Promise.all([
+        spawnInstance({ index: 'A', launch, readiness, timeoutMs, sandboxDir: dirs.A, projectDir }),
+        delay(jitter).then(() => spawnInstance({ index: 'B', launch, readiness, timeoutMs, sandboxDir: dirs.B, projectDir })),
+    ]);
+    const durationMs = Date.now() - startedAt;
+    const verdict = decideVerdict(outcomeA, outcomeB);
+    return {
+        ...verdict,
+        durationMs,
+        children: { A: outcomeA, B: outcomeB },
+    };
+}
+/**
+ * Race a readiness signal against the timeout, scanning stderr for the
+ * three known-bad patterns. Resolves to a ChildOutcome regardless of
+ * which arm wins. Always kills the child before resolving.
+ */
+function spawnInstance({ index: _index, launch, readiness, timeoutMs, sandboxDir, projectDir }) {
+    return new Promise((resolveOutcome) => {
+        const env = renderLaunchEnv(launch.envTemplate ?? {}, sandboxDir);
+        const child = child_process.spawn(launch.binary, launch.args ?? [], {
+            cwd: resolve(projectDir),
+            env: { ...process.env, ...env, SANDBOX_DIR: sandboxDir },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let resolved = false;
+        let stderrBuf = '';
+        const stdoutBuf = [];
+        const MAX_STDERR_BYTES = 4096;
+        const finish = (outcome) => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(timer);
+            try {
+                child.kill('SIGTERM');
+            }
+            catch {
+                /* already gone */
+            }
+            // SIGKILL grace
+            setTimeout(() => {
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch {
+                    /* gone */
+                }
+            }, 5000).unref?.();
+            resolveOutcome(outcome);
+        };
+        // onStderrText: appends to stderrBuf and checks failure-reason patterns.
+        // Must NOT be called with stdout data — informational app logs that mention
+        // "SQLITE_BUSY" or "EADDRINUSE" must not trigger failure verdicts (LOG-001).
+        const onStderrText = (text) => {
+            stderrBuf = (stderrBuf + text).slice(-MAX_STDERR_BYTES);
+            if (/SQLITE_BUSY/i.test(text)) {
+                finish({
+                    ready: false,
+                    failureReason: 'self_test_failed_sqlite_busy',
+                    stderrTail: stderrBuf.slice(-500),
+                });
+                return;
+            }
+            if (/EADDRINUSE|bind\s+failed|address already in use|EACCES|EPERM/i.test(text)) {
+                finish({
+                    ready: false,
+                    failureReason: 'self_test_failed_port_conflict',
+                    stderrTail: stderrBuf.slice(-500),
+                });
+                return;
+            }
+        };
+        // onStdoutText: checks readiness signal only. Never touches stderrBuf and
+        // never triggers failure-reason heuristics — stdout is not an error stream.
+        const onStdoutText = (text) => {
+            if (text.includes(readiness.logPattern)) {
+                finish({ ready: true, failureReason: null, stderrTail: stderrBuf.slice(-500) });
+            }
+        };
+        child.stdout?.on?.('data', (chunk) => {
+            const text = String(chunk);
+            stdoutBuf.push(text);
+            onStdoutText(text);
+        });
+        child.stderr?.on?.('data', (chunk) => {
+            const text = String(chunk);
+            onStderrText(text);
+            // Readiness may also appear on stderr (some apps log to stderr only).
+            if (text.includes(readiness.logPattern)) {
+                finish({ ready: true, failureReason: null, stderrTail: stderrBuf.slice(-500) });
+            }
+        });
+        child.on?.('error', (err) => {
+            finish({
+                ready: false,
+                failureReason: 'self_test_failed_app_init_timeout',
+                stderrTail: String(err.message ?? err),
+            });
+        });
+        child.on?.('exit', () => {
+            if (!resolved) {
+                // Process exited before signalling readiness. Treat as init timeout
+                // unless the stderr already revealed a known bad pattern (handled
+                // above before exit).
+                finish({
+                    ready: false,
+                    failureReason: 'self_test_failed_app_init_timeout',
+                    stderrTail: stderrBuf.slice(-500),
+                });
+            }
+        });
+        const timer = setTimeout(() => {
+            finish({
+                ready: false,
+                failureReason: 'self_test_failed_app_init_timeout',
+                stderrTail: stderrBuf.slice(-500),
+            });
+        }, timeoutMs);
+        // Don't keep the event loop alive on the timer.
+        timer.unref?.();
+    });
+}
+/**
+ * Combine two outcomes into the v2-shaped verdict envelope.
+ * Failure precedence: sqlite_busy > port_conflict > app_init_timeout.
+ *
+ * Every spawnInstance() resolution sets failureReason explicitly on the
+ * !ready path (the four finish() call sites cover SQLITE_BUSY, port
+ * conflict, app_init_timeout, and the child-error path which also maps
+ * to app_init_timeout). The priority loop therefore always finds a
+ * match; the unreachable fallthrough that used to live here was
+ * deleted per CLAUDE.md guideline 2 (no handling for impossible
+ * scenarios).
+ */
+function decideVerdict(a, b) {
+    if (a.ready && b.ready) {
+        return { verified: true, verdict: /** @type {const} */ ('approved'), reason: null };
+    }
+    const reasons = [a.failureReason, b.failureReason].filter(Boolean);
+    const priority = [
+        'self_test_failed_sqlite_busy',
+        'self_test_failed_port_conflict',
+        'self_test_failed_app_init_timeout',
+    ];
+    for (const cand of priority) {
+        if (reasons.includes(cand)) {
+            return {
+                verified: false,
+                verdict: /** @type {const} */ ('needs_human'),
+                reason: /** @type {any} */ (cand),
+            };
+        }
+    }
+    throw new Error(`self-test decideVerdict: unreachable — both outcomes failed without a known reason: ${JSON.stringify({ a, b })}`);
+}
+/**
+ * Substitute ${SANDBOX_DIR} placeholders in the recipe's envTemplate.
+ */
+function renderLaunchEnv(envTemplate, sandboxDir) {
+    const out = {};
+    for (const [k, v] of Object.entries(envTemplate)) {
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: config template marker, not a typo
+        out[k] = typeof v === 'string' ? v.replaceAll('${SANDBOX_DIR}', sandboxDir) : v;
+    }
+    return out;
+}
+function delay(ms) {
+    return new Promise((res) => {
+        const t = setTimeout(res, ms);
+        t.unref?.();
+    });
+}
+//# sourceMappingURL=self-test.mjs.map

package/dist/cli/verify-proof/sandbox/self-test.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-test.mjs","sourceRoot":"","sources":["../../../../src/cli/verify-proof/sandbox/self-test.mjs"],"names":[],"mappings":"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"}

package/dist/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "aperant",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "AI coding framework — composable skills for planning, executing, verifying, and reviewing code with any LLM provider. Works as Claude Code commands, Codex tasks, or programmatically.",
   "author": {
     "name": "Mikalsen AI",

package/dist/plugin/agents/apt-planner.md

@@ -217,6 +217,21 @@ Fast Path Guarantee). QUICK-routed tasks keep the existing 4-section
 shape; STANDARD/DEEP/COMPLEX tasks get a PRD-shaped artifact that
 survives the task as a second-consumer document.
 
+**Sandbox-gated parallel verify-proof — cite the v2 envelope verbatim.**
+When the plan calls for parallel `/apt:verify-proof` (e.g. fan-out
+worker spawned a verify-proof child, or `--parallel` is passed to
+`/apt:verify-proof`), the spec's User Outcomes section MUST cite the
+sandbox gate's v2 failure envelope verbatim:
+`{verdict: "needs_human", reason: "sandbox_unverified"}` (plus the
+structured error code `E_SANDBOX_UNVERIFIED` and the remediation
+`/apt:verify-proof setup`). Downstream agents reading the spec
+dispatch on these exact strings; paraphrasing them breaks the
+contract. The gate runs BEFORE Step 2.5 (Deferred-tool-load) and
+BEFORE the outcome walker — sandbox-unverified is a precondition
+failure, not a per-outcome transport failure. See
+`apt-verify-proof/SKILL.md` Step 2c for the gate definition and
+`docs/verify-proof-sandbox-patterns.md` for the worked adopter flow.
+
 ### 4.A. QUICK track / SIMPLE complexity — legacy 4-section spec
 
 ```markdown

package/dist/plugin/agents/apt-verifier.md

@@ -80,10 +80,13 @@ If the planner claims a dimension is covered but the implementation does not act
 | **Code Quality** | Clean, idiomatic, lint-clean | Good, minor style issues | Acceptable, needs cleanup | Poor quality | Unacceptable |
 | **Test Coverage** | Comprehensive, edge cases | Good main-path coverage | Basic tests exist | Minimal tests | No coverage |
 
-## 4. Derive Verdict
-- **approved:** ALL dimensions >= 7, no critical issues
-- **approved-with-notes:** ALL dimensions >= 5
-- **rejected:** ANY dimension < 5 or critical issues
+## 4. Derive Verdict (v0.9.0 two-gate envelope)
+
+Verdict is the closed set `{approved, rejected, needs_human}`. Derived from the two-gate envelope (`automation_gate` AND `proof_gate`); dimensions are informational rationale only.
+
+- **approved:** `automation_gate: pass` AND `proof_gate: pass`.
+- **needs_human:** `automation_gate: pass` AND `proof_gate: fail` (typically: a UI-surface outcome lacked driver transport — see `/apt:verify-proof`).
+- **rejected:** `automation_gate: fail` (any of lint/typecheck/tests red) OR critical findings unresolved.
 
 ## 5. Write QA Sign-off
 Write `{task_dir}/qa_signoff.json` with scores, checks, issues, and verdict.
@@ -105,14 +108,16 @@ Either shape is accepted:
 
 Gate G8 (`consistency-check`) enforces this on ship via rules R4
 (finding-propagation) and R5 (verdict-consistency):
-- `verdict: "approved"` or `verdict: "approved-with-notes"` is incompatible
-  with any unresolved `critical` or `major` review finding (G42 Phase 1).
-  Neither verdict escapes R5 for blocking-severity findings. The sole bypass
-  is `--force --reason "<why>"` on the gate CLI (audit-logged). For
-  non-blocking findings (suggestion/note/info/nitpick), cite them in
-  `findings.notes` and use `approved-with-notes`.
+- `verdict: "approved"` is incompatible with any unresolved `critical` or
+  `major` review finding (G42 Phase 1). The sole bypass is `--force --reason
+  "<why>"` on the gate CLI (audit-logged). For non-blocking findings
+  (suggestion/note/info/nitpick), cite them in `findings.notes` and keep
+  the verdict `approved`.
 - `verdict: "rejected"` requires at least one cited finding (rejected
   without evidence is treated as drift).
+- `verdict: "needs_human"` signals a transport gap (e.g. UI-surface outcome
+  with no MCP driver). The R5 rule does not gate on it; re-run verify-proof
+  after installing the missing transport.
 
 ## 6. Report
 Output verdict with dimension scores and next step recommendation.

package/dist/plugin/skills/apt-plan/SKILL.md

@@ -209,6 +209,8 @@ see the gate table below.}
 **Epic:** {one-sentence user-facing capability headline}
 
 - **ON** [surface]: {user does X; system shows/does Y}
+  - {indented inferred sub-check derived by the planning LLM}
+  - {another inferred sub-check}
 - **ON** [surface]: {user does X; system shows/does Y} *(requires ON 1)*
 - **ON** [electron+web]: {cross-surface outcome — runs twice, once per surface}
 
@@ -246,6 +248,27 @@ ID. Subtasks reference these IDs via their per-subtask
 plan-coverage-check input.}
 ```
 
+### Inferred sub-checks (v0.9.0 — verify-proof-v2-outcome-walker)
+
+Under each `**ON**` parent bullet, write indented child bullets (2-space
+prefix + `- `) representing inferred sub-checks the planning LLM derives
+from the outcome prose + surface. These are NOT user-written invariants;
+they are the planner's judgment of "what else must be true for this
+outcome to be approved." The verify-proof runner walks each inferred
+child the same way it walks the parent.
+
+Worked example (copy this shape verbatim into spec.md):
+
+    - **ON** [electron]: Clicking 'Settings' opens the settings modal.
+      - The modal traps focus on the close button.
+      - Clicking outside the modal closes it.
+      - Pressing Esc closes it and returns focus to the trigger.
+
+**NO `patterns/` library, NO `surfaces/<name>/manifest.json` tree, NO
+`OUTCOMES.md` file** — inferred bullets live IN spec.md. The author
+edits spec.md once if the inferred list is wrong; the runner does not
+re-derive them at proof time.
+
 **`## User Outcomes` is the verify-proof input contract (STANDARD/DEEP
 only — QUICK is hard-exempt per ID-05 / Fast Path Guarantee).** The
 section sits between `## User Stories` (product motivation prose) and

package/dist/plugin/skills/apt-run/SKILL.md

@@ -281,7 +281,7 @@ Execute the apt:verify workflow inline:
 6. Score on 4 dimensions (completeness, correctness, quality, coverage)
 7. Fix all issues found — every severity, not just critical (up to 4 iterations: first 2 discovery, last 2 verification-only)
 8. Write qa_signoff.json
-9. If `status` is `approved` or `approved-with-notes`, flip lifecycle to `reviewing` so Stage 4 (or `/apt:ship` when review is skipped) finds the task in the correct from-state. Skip this step entirely on `rejected`:
+9. If `status` is `approved`, flip lifecycle to `reviewing` so Stage 4 (or `/apt:ship` when review is skipped) finds the task in the correct from-state. Skip this step entirely on `rejected` (fix the code and re-run) or `needs_human` (install the missing driver transport and re-run /apt:verify-proof):
    ```bash
    node packages/framework/bin/apt-tools.mjs task update . --id {task-id} --lifecycle-phase reviewing
    ```

package/dist/plugin/skills/apt-setup/SKILL.md

@@ -307,6 +307,62 @@ AskUserQuestion([
 ])
 ```
 
+### Sandbox-setup hook — parallel /apt:verify-proof (FRAMEWORK milestone fw-sandbox-parallel-verify-proof)
+
+Gated on THREE conditions ALL true (ID-08):
+
+1. `verification.sandbox` is ABSENT from `.aperant/config.json` (the
+   adopter has not opted in yet — once configured this hook never
+   fires again).
+2. `host.capabilities.structured_prompts === true` (the host supports
+   native question dialogs — Claude Code, Gemini CLI, OpenCode).
+3. `process.stdout.isTTY === true` (interactive shell — never block CI
+   or fan-out child terminals on a setup prompt).
+
+When all three hold, ask one yes/no question:
+
+```
+AskUserQuestion([
+  {
+    question: "Parallel /apt:verify-proof is not configured. Run setup now?",
+    header: "Sandbox Setup",
+    multiSelect: false,
+    options: [
+      { label: "Yes — set up parallel verify-proof", description: "Walk recipe-diff one change at a time, then apply-recipe with --confirm --accept-all once you've reviewed all four, then verify-sandbox" },
+      { label: "Not now", description: "Skip; re-prompted on next /apt:setup if still unconfigured" }
+    ]
+  }
+])
+```
+
+On `Yes`, dispatch the three sandbox commands in order, surfacing the
+output of each to the user before moving to the next. The CLI defaults
+to skipping every change when `--confirm` is passed without
+`--accept-all` (ID-02 fail-safe), so the interactive flow walks the
+adopter through each change in the diff first, then applies once they
+confirm:
+
+```bash
+apt-tools recipe-diff .                     # preview, no writes
+# (host CLI shows each change in the Markdown diff to the user)
+# (host CLI asks: "All four changes accepted? [y/N]")
+apt-tools apply-recipe . --confirm --accept-all
+apt-tools verify-sandbox .
+```
+
+On `Not now`, continue with the rest of /apt:setup unchanged.
+
+**Non-interactive surfaces** (CI runs, fan-out child terminals, headless
+agents — `host.capabilities.structured_prompts === false` OR
+`process.stdout.isTTY === false`) SKIP this hook entirely. Print a
+one-line stderr tip:
+
+```
+[apt] tip: run `/apt:verify-proof setup` from an interactive terminal to enable parallel verification
+```
+
+and continue. NEVER block on a setup prompt in a non-interactive context.
+
 ## 3. Present Settings (Batch 2: Pipeline)
 
 ```

package/dist/plugin/skills/apt-verify/SKILL.md

@@ -211,15 +211,15 @@ Rate each of the 4 dimensions on a 1-10 scale using the rubrics below. Provide a
 - **3-4:** Minimal tests, many untested paths
 - **1-2:** No meaningful test coverage
 
-### Verdict Derivation
+### Verdict Derivation (v0.9.0 two-gate envelope)
 
-Derive the verdict from dimension scores using these threshold rules:
+Verdict is the closed set `{approved, rejected, needs_human}`. It derives from the two-gate envelope (`automation_gate` AND `proof_gate`); dimensions are informational rationale only.
 
-- **approved** -- ALL dimensions >= 7, no critical issues
-- **approved-with-notes** -- ALL dimensions >= 5, minor issues noted
-- **rejected** -- ANY dimension < 5, or critical issues found
+- **approved** -- `automation_gate: pass` AND `proof_gate: pass` AND no critical issues
+- **needs_human** -- `automation_gate: pass` AND `proof_gate: fail` (typically: UI-surface outcome lacked driver transport; the human must install it and re-run /apt:verify-proof)
+- **rejected** -- `automation_gate: fail` (any of lint/typecheck/tests red) OR critical issues unresolved
 
-These thresholds match `QA_DIMENSION_THRESHOLDS` in `packages/framework/src/types/qa-scoring.ts`.
+The `deriveVerdict({automation_gate, proof_gate})` helper in `packages/framework/src/types/qa-scoring.ts` is the canonical mapping. The legacy `approved_with_notes` middle band is deleted in v0.9.0+; reading the legacy value from a stale `qa_signoff.json` crashes the consumer with a clear migration error.
 
 ## 6. Fix-Verify Loop (max 4 iterations)
 
@@ -272,7 +272,7 @@ Create `qa_signoff.json` using the `ScoredQASignoff` format (see `packages/frame
 
 ```json
 {
-  "status": "approved|approved-with-notes|rejected",
+  "status": "approved|rejected|needs_human",
   "timestamp": "{ISO date}",
   "iterations": 1,
   "dimensions": [
@@ -281,6 +281,10 @@ Create `qa_signoff.json` using the `ScoredQASignoff` format (see `packages/frame
     { "dimension": "code_quality", "score": 7, "rationale": "Clean code, follows conventions" },
     { "dimension": "test_coverage", "score": 7, "rationale": "Good coverage of main paths" }
   ],
+  "gates": {
+    "automation_gate": "pass",
+    "proof_gate": "pass"
+  },
   "checks": {
     "tests": { "status": "pass", "count": 42, "failures": [] },
     "typecheck": { "status": "pass", "errors": [] },
@@ -293,10 +297,10 @@ Create `qa_signoff.json` using the `ScoredQASignoff` format (see `packages/frame
 
 The `dimensions` array must contain exactly the 4 dimensions defined in `QA_DIMENSIONS`: `completeness`, `correctness`, `code_quality`, `test_coverage`. Each entry includes a numeric `score` (1-10) and a `rationale` string explaining the score.
 
-The `status` field is derived from the minimum dimension score:
-- All >= 7 and no critical issues: `"approved"`
-- All >= 5 and no critical issues: `"approved-with-notes"`
-- Any < 5 or critical issues: `"rejected"`
+The `status` field derives from the two gates:
+- `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"`
 
 ```bash
 node packages/framework/bin/apt-tools.mjs commit "qa: verification {status}" --files qa_signoff.json
@@ -304,10 +308,11 @@ node packages/framework/bin/apt-tools.mjs commit "qa: verification {status}" --f
 
 ### Mark lifecycle phase as `reviewing` (approved path only)
 
-If `status` is `approved` or `approved-with-notes`, flip the task's lifecycle
-phase so the next stage (`/apt:review`, or `/apt:ship` if review is skipped)
-finds the task in the correct from-state. Skip this transition entirely on
-`rejected` — the task stays in `verifying` until the user re-runs after fixes.
+If `status` is `approved`, flip the task's lifecycle phase so the next stage
+(`/apt:review`, or `/apt:ship` if review is skipped) finds the task in the
+correct from-state. Skip this transition on `rejected` (the task stays in
+`verifying` until the user re-runs after fixes) or `needs_human` (re-run
+/apt:verify-proof after installing the missing driver transport).
 
 ```bash
 node packages/framework/bin/apt-tools.mjs task update . --id {task-id} --lifecycle-phase reviewing