@aperant/framework 0.10.0 → 0.12.0

package/skills/apt-catch-up/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: apt:catch-up
+description: "Re-view the catch-up panel (Welcome-Back + Team-Change Digest) on demand"
+apt-skill-version: {{APT_VERSION}}
+stage: resume
+intent: capture
+when_to_use: "The user dismissed the auto catch-up panel on their last /apt and wants to re-summon it — an idempotent re-view of where they left off plus what teammates merged. Distinct from /apt:resume (full context restore) and never advances the Last-Seen Marker."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+task_context: none
+default_execution_mode: auto
+execution_modes:
+  - auto
+allowed-tools: "Bash, Read"
+argument-hint: "apt:catch-up"
+gates: []
+---
+<objective>
+Recompute and display the combined catch-up panel — the **Welcome-Back
+Summary** (your most-recently-active task, phase, next step) and the
+**Team-Change Digest** (the PRs teammates merged to main since you last
+pulled) — exactly as the auto-on-apt display would show it, but **without
+advancing the Last-Seen Marker**. This is a read-only re-view: a user who
+dismissed the auto panel can re-summon it without disturbing the baseline and
+without invoking the heavier `/apt:resume`.
+</objective>
+
+<your_environment>
+- **Working directory:** The project root (where you were invoked)
+- **apt-tools:** `node packages/framework/bin/apt-tools.mjs` or the installed `apt-tools` binary
+- **Last-Seen Marker:** `.aperant/last-seen/{email-slug}.json` (gitignored, per-machine) — this skill READS it but NEVER writes it.
+</your_environment>
+
+<process>
+
+## 1. Recompute the panel (read-only)
+
+```bash
+node packages/framework/bin/apt-tools.mjs catch-up .
+```
+
+This computes the SAME panel the interactive route call produces, against the
+**current** marker — and deliberately does **NOT** call `advanceLastSeen`
+(recompute-only contract). Parse the JSON `catch_up` field from the envelope.
+
+## 2. Render the panel
+
+Render exactly as the `apt/SKILL.md` "Catch-up panel" block does — Welcome-Back
+half first, then the Team-Change Digest half. Omit a half whose field is null.
+
+If `catch_up` is null, tell the user there is nothing new since their last
+visit (no active stale task and no new merges on main).
+
+```
+Where you left off: {description} — {lifecycle_phase} · subtask {current_subtask} ({relative_time})
+  Next: {next_step}
+  (+{others_count} others · /apt:resume)
+
+While you were away:
+  #{number} {title} — {author}
+  +{more_count} more on main
+```
+
+</process>
+
+<notes>
+- **Never advances the marker.** Unlike the auto-on-apt display (which advances
+  the Last-Seen Marker after the panel is evaluated), this command is purely a
+  re-view. Re-running it is idempotent.
+- **Distinct from `/apt:resume`.** Resume restores full context and routes to
+  the next action; catch-up is a lightweight orientation re-view.
+- **v1 is lazy compute.** The panel is computed on demand here, bounded by the
+  commits since your last pull. A background pre-warm worker (like the
+  update-check worker) is a tracked follow-up (LD-12), not part of v1.
+- **Vocabulary.** This is the Welcome-Back Summary + Team-Change Digest — not an
+  "activity feed", "changelog", or "notifications".
+</notes>

package/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/skills/apt-pr-review/SKILL.md

@@ -247,10 +247,11 @@ The command resolves in this precedence order:
 
 1. `config.json:pr_review.authorship_overrides['pr-${PR_NUMBER}']` (per-PR pin)
 2. `config.json:pr_review.authorship_override` (global: `owned` | `external` | `auto`)
-3. `gh pr view` → `authorAssociation` + `headRepository.owner.login` vs. viewer login
-   - `authorAssociation IN (OWNER, MEMBER, COLLABORATOR)` AND same-repo branch → **owned**
-   - Fork OR `authorAssociation IN (NONE, CONTRIBUTOR, FIRST_TIME_CONTRIBUTOR)` → **external**
-4. Offline / gh unavailable / ambiguous payload → **unknown**
+3. `gh pr view` → `gh.author.login` vs. viewer login (G44 — `owned` means a PR you **authored**, not a branch you can push to)
+   - Same-repo branch AND `gh.author.login === viewer login` → **owned**
+   - Any other same-repo PR (a teammate's, or a repo-`OWNER` viewing someone else's PR) → **external** (`authorAssociation` is no longer consulted for the `owned` decision — it is retained only in the human-readable signal)
+   - Fork (head-repo owner ≠ base-repo owner) → **external**
+4. Offline / gh unavailable / ambiguous payload → **unknown** (treated as `external` for safety, see below)
 
 When the result is `unknown`, treat it as `external` for safety and prompt the user:
 

package/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/skills/apt-setup/SKILL.md

@@ -205,6 +205,7 @@ AskUserQuestion([
 - "Visibility" → jump to **Step 3e** (Batch 6 only), then skip to **Step 4** and **Step 5**
 - "Task Tracking" → jump to **Step 3g** (Batch 8 only), then skip to **Step 4** and **Step 5**
 - "Changelog & Release Notes" → jump to **Step 3h** (Batch 9 only), then skip to **Step 4** and **Step 5**
+- "Collaboration" → jump to **Step 3i** (Batch 10 only), then skip to **Step 4** and **Step 5**
 - "Everything" → proceed to **Step 2** and run all batches (same as fresh setup). **Legacy-completes-Everything marker write:** if the starting config has no `onboarding` block (legacy unmarked config) and the user completes the full flow, write a full `onboarding` block at Step 5 as `{ completed: true, seeded_from_template: false, seeded_at: <ISO-8601 now> }` to record the explicit onboarding pass.
 - "Done" → display "Settings unchanged." and exit
 
@@ -306,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)
 
 ```
@@ -1180,6 +1237,74 @@ The selective-edit pass through Batch 9 MUST respect the §1b dispatch — it do
 
 ---
 
+## 3i. Present Settings (Batch 10: Collaboration Catch-Up)
+
+The **collaboration catch-up** surfaces show on every interactive (TTY) `/apt`
+call: a **Welcome-Back Summary** (your most-recently-active task + next step,
+always-on, local-only) and a **Team-Change Digest** (the PRs teammates merged
+to main since you last pulled — gated to `share.visibility` `team`/`oss`).
+Written to `.aperant/config.json.collaboration`.
+
+```
+AskUserQuestion([
+  {
+    question: "Show the Welcome-Back Summary when you return after a break?",
+    header: "Welcome-Back",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "On your next /apt after the staleness window, surface where you left off — task, phase, next step. Local only." },
+      { label: "No", description: "Never show the welcome-back nudge." }
+    ]
+  },
+  {
+    question: "How many hours away before the Welcome-Back Summary fires?",
+    header: "Threshold (hours)",
+    multiSelect: false,
+    options: [
+      { label: "16 (Recommended)", description: "Roughly 'since yesterday' — fires after an overnight gap." },
+      { label: "8", description: "Fires after a long lunch / half-day gap." },
+      { label: "24", description: "Once-a-day cadence." }
+    ]
+  },
+  {
+    question: "Show the Team-Change Digest (teammates' merged PRs since your last pull)?",
+    header: "Team Digest",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Only computes when share.visibility is team/oss; reads local git history, never fetches." },
+      { label: "No", description: "Never show the digest, even in team/oss mode." }
+    ]
+  },
+  {
+    question: "Maximum PRs to list in the digest before '+N more on main'?",
+    header: "Digest Max Entries",
+    multiSelect: false,
+    options: [
+      { label: "7 (Recommended)", description: "Low-noise ceiling; the rest collapse into a '+N more' tail." },
+      { label: "5", description: "Tighter." },
+      { label: "12", description: "Roomier." }
+    ]
+  }
+])
+```
+
+For hosts without structured prompts, present the same four questions as
+numbered lists (Batch 5 style) and read single-index responses.
+
+### 3i.1 Review-Mode routing entry
+
+The "1b. Review Mode" routing table (§1b) includes "Collaboration" as a
+selectable edit target — jumping directly back into this Batch 10 picker.
+
+### 3i.2 Confirmation row
+
+Add a row to the Step 8 table:
+```
+| Collaboration | welcome-back {on/off} ({N}h) · team-digest {on/off} (max {M}) |
+```
+
+---
+
 ## 4. Map Answers to Config
 
 **AUDIT-001 — file-routing contract for per-device fields (UPDATED 0.8.1 for FRAMEWORK-RFC-001):** the
@@ -1295,6 +1420,12 @@ Note: task ids are slug-first since v0.6.6 — the date-format setting controls
 - "Sub-Agents" → `"sub-agents"`
 - "Sequential" → `"sequential"`
 
+**Collaboration Catch-Up (Batch 10):**
+- Welcome-Back "Yes" → `collaboration.welcome_back.enabled: true`, "No" → `false`
+- Threshold → `collaboration.welcome_back.threshold_hours: <8|16|24>`
+- Team Digest "Yes" → `collaboration.team_digest.enabled: true`, "No" → `false`
+- Digest Max Entries → `collaboration.team_digest.max_entries: <5|7|12>`
+
 ## 5. Write Config
 
 Write merged config to two files per AUDIT-001 routing (see Step 4 block):
@@ -1402,6 +1533,7 @@ Display:
 | Debate Mode          | {Auto / Agent Team / Sub-Agents / Sequential} |
 | Visibility           | {solo / team / oss} (overrides if any)        |
 | Changelog & Release Notes | dev: {Yes/No}; release-notes: {Yes/No} (audience, persona-filter) |
+| Collaboration        | welcome-back {on/off} ({N}h) · team-digest {on/off} (max {M}) |
 | Saved as Defaults    | {Yes/No}                     |
 
 Config saved to: .aperant/config.json

package/skills/apt-verifier.md

@@ -50,10 +50,13 @@ Record pass/fail and details for each.
 | **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.

package/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

package/skills/apt-verify-proof/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: apt:verify-proof
-description: "Visual proof-of-work verification — screenshots, HTML report, optional multi-model review (BETA)"
+description: "Outcome walker — drives spec.md `## User Outcomes` one at a time, captures surface-appropriate evidence, derives a two-gate verdict ({approved, rejected, needs_human}). Fails closed on file-evidence for UI surfaces."
 apt-skill-version: {{APT_VERSION}}
 stage: verify
 intent: ship
@@ -105,14 +105,58 @@ disable the walk entirely (root-only behaviour, backwards compat).
 The `verification.runtimes[]` override stays the final escape hatch
 and is now usually unnecessary because the walk runs by default.
 
-### Bundled drivers (5)
+### Bundled drivers (6)
 
 - **browser** (priority=100, ga) — Next.js / vanilla web frontends.
 - **electron** (priority=90, ga) — Electron desktop apps.
 - **tauri** (priority=85, ga) — Tauri desktop apps.
+- **mobile** (priority=80, ga) — iOS + Android (Expo / React Native / native) via `mobile-mcp`. App build/launch is owned by `apt-tools mobile prepare`, not the driver.
 - **cli** (priority=60, ga) — headless CI, output-shape assertions.
 - **api** (priority=50, ga) — HTTP / JSON-API regression tests.
 
+> **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.
+
+### Deferred-tool discovery (Claude Code / OpenCode hosts) — A5 fix
+
+On Claude Code and OpenCode hosts, MCP driver tools listed under
+`drivers/<surface>/manifest.json :: transport.mcp_server_id` are
+**deferred** — they live in the host's MCP server registry but their
+schemas are NOT loaded by default. Before driving any UI-surface
+outcome the workflow runner MUST load them via `ToolSearch(query='select:...')`.
+
+**Worked example.** For the bundled `browser` driver (manifest field
+`transport.mcp_server_id = "puppeteer"` → `mcp__puppeteer__*` tools):
+
+```
+ToolSearch(query='select:mcp__puppeteer__browser_navigate,mcp__puppeteer__browser_click,mcp__puppeteer__browser_screenshot,mcp__puppeteer__browser_type')
+```
+
+For the bundled `electron` driver (manifest field
+`transport.mcp_server_id = "electron"` → `mcp__electron__*` tools):
+
+```
+ToolSearch(query='select:mcp__electron__app_launch,mcp__electron__app_click,mcp__electron__app_screenshot,mcp__electron__app_type')
+```
+
+For the bundled `mobile` driver (manifest field
+`transport.mcp_server_id = "mobile-mcp"` → `mcp__mobile-mcp__*` tools):
+
+```
+ToolSearch(query='select:mcp__mobile-mcp__mobile_click_on_screen_at_coordinates,mcp__mobile-mcp__mobile_swipe_on_screen,mcp__mobile-mcp__mobile_save_screenshot,mcp__mobile-mcp__mobile_type_keys')
+```
+
+After the call, list the now-loaded tool names back to confirm they
+appear in the active tool surface. If any required driver tool fails to
+load, emit `result: "needs_human_with_transport"` on each affected
+outcome — 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 block is no-op on hosts whose entire MCP surface is
+loaded eagerly (some Codex builds); `ToolSearch` is idempotent there.
+
 ### Install-time MCP provisioning (verification.provision_mcp)
 
 `apt-tools init` (and `/apt:update`, which routes through the same path)
@@ -149,10 +193,99 @@ IDL types, error taxonomy, and conformance kit live inside the framework
 itself under `packages/framework/src/driver-sdk/` — see that directory's
 public-api-lock test for the surface contract.
 
-## Execution
+## Step 1 — First-run sandbox-setup hook (interactive `--parallel` only)
+
+When the user invokes `/apt:verify-proof --parallel` on a project where
+`verification.sandbox` is ABSENT from `.aperant/config.json` AND
+`host.capabilities.structured_prompts === true` AND
+`process.stdout.isTTY === true`, prompt:
+
+```
+AskUserQuestion([
+  {
+    question: "Parallel /apt:verify-proof is not configured. Run setup now?",
+    header: "Sandbox Setup",
+    multiSelect: false,
+    options: [
+      { label: "Yes — run sandbox setup", description: "Walk recipe-diff with you, then apply-recipe --confirm --accept-all (after you've reviewed each change), then verify-sandbox before continuing" },
+      { label: "Cancel", description: "Exit; re-invoke without --parallel for single-instance verify-proof" }
+    ]
+  }
+])
+```
+
+On `Yes`, dispatch `/apt:verify-proof setup` (the setup-mode flow) before
+returning to the walker. On `Cancel`, exit with the same envelope the
+Step 2c gate would produce so the user sees the structured remediation.
+
+Non-interactive surfaces (`structured_prompts:false` OR
+`stdout.isTTY:false`) print the one-line stderr tip and proceed:
+
+```
+[apt] tip: run `/apt:verify-proof setup` to enable parallel verification
+```
+
+then exit at the Step 2c gate. Never block CI / fan-out children on
+this prompt (ID-08).
+
+## Step 2c — Sandbox gate (precondition for `--parallel`)
+
+When `--parallel` is requested AND `.aperant/config.json :: verification.sandbox`
+is present, this gate runs BEFORE Step 2.5 (Deferred-tool-load) and BEFORE
+entering the Outcome Walker loop. It is a **precondition gate**, NOT a
+per-outcome transport-failure gate.
+
+**Dispatch on the state file** at
+`.aperant/state/verify-proof-sandbox-verified.json`:
+
+| condition | action |
+|-----------|--------|
+| `--parallel` requested + state file shows `verified:true` (verdict:`approved`) | **proceed** to Step 2.5; the parallel surface is now safe (each instance has its own SQLite path + userData dir + singleton-lock opt-out). |
+| `--parallel` requested + state file missing OR `verified:false` | **exit BEFORE Step 2.5** with the JSON envelope below; do NOT load deferred MCP tools, do NOT initialize the outcome walker, do NOT write verification.json. |
+| `--parallel` NOT requested | today's behavior unchanged — this gate is a no-op (Fast Path Guarantee ID-07). |
+
+**Fail-loud envelope.** sandbox not verified — run `/apt:verify-proof setup` first:
+
+```json
+{
+  "status": "error",
+  "code": "E_SANDBOX_UNVERIFIED",
+  "verdict": "needs_human",
+  "reason": "sandbox_unverified",
+  "remediation": "/apt:verify-proof setup"
+}
+```
+
+The single-line stderr message is: `sandbox not verified — run \`/apt:verify-proof setup\` first`.
+
+**v2 vocabulary alignment.** The gate's failure envelope uses verify-proof
+v2's existing `verdict:"needs_human"` vocabulary (ID-09) so reviewers,
+downstream tools, and the e2e see one shape across both the per-run
+envelope and per-outcome verification.json. We deliberately do NOT emit
+per-outcome `needs_human_with_transport` rows for this case — sandbox
+unverified is a precondition failure for the whole walker, not a
+per-outcome transport failure for individual outcomes. Only the two
+v2-shipped verdicts (`approved`, `needs_human`) appear in this gate's
+envelope — the deprecated middle-band verdict v2 removed is not
+referenced anywhere in this block (TD-07 grep guard locks this).
+
+**Anti-queue invariant.** This gate fails loud rather than silently
+serializing parallel invocations through a cooperative queue. The
+`install/install-semaphore.mjs` queuing primitive is explicitly forbidden
+in this code path (ID-01); a regression test grep-guards the invariant.
+
+See `docs/verify-proof-sandbox-patterns.md` for the worked
+electron-libsql adopter flow + the manual-integration template for
+unrecognized runtimes.
+
+## Execution — Outcome Walker (v0.9.0)
 
 Execute the verify-proof workflow end-to-end using IDL verbs (the driver
-maps verbs to its transport — MCP server, local command, HTTP):
+maps verbs to its transport — MCP server, local command, HTTP). The
+workflow is an **outcome walker**: iterate `spec.md ## User Outcomes`
+parent bullets one at a time, drive the stated bullet AND each inferred
+child, capture surface-appropriate evidence, fix-loop on red, advance on
+green.
 
 <execution_context>
 @packages/framework/workflows/verify-proof.md
@@ -168,15 +301,17 @@ to adopt the adversarial QA mindset. You are not a helpful assistant during veri
 you are trying to break things and prove they work.
 
 Respect ALL workflow gates:
-1. Pre-check gate — all subtasks completed
-2. Design-lint gate (C11) — for every UI-touching task, run `apt-tools design-lint` against the implementation's generated HTML + `{task_dir}/mockups/mockup_final.html` (when present). The DESIGN.md contract's `antiPatterns` block is the authority. Violations MUST be surfaced in the VERIFICATION.md report as a distinct section; they are NOT blocking by themselves but they contribute to the visual-quality score.
-3. Test generation gate — ALL tests written before execution
-4. Test execution gate — ALL tests executed before scoring
-5. Evidence gate — every test has evidence AND analysis
-6. Scoring gate — scores derived from evidence, not assumed
+1. **Pre-check gate** — all subtasks completed.
+2. **User Outcomes gate** — 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** — on Claude Code / OpenCode hosts, MCP driver tools 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** — `automated_checks.{tests,typecheck,lint}.status ∈ {pass, fail}` (closed set, no `"enforced_at_commit"` dodge).
+5. **Outcome-walker gate** — every parent outcome AND every inferred child has its own test entry with evidence appropriate to its surface OR `result: "needs_human_with_transport"`.
+6. **Proof gate** — UI-surface outcomes carrying `evidence: "file-evidence: ..."` are rejected as `needs_human_with_transport`. File-evidence is NEVER sufficient for any surface.
+7. **Verdict gate** — verdict is exactly one of `{approved, rejected, needs_human}`. The legacy `approved_with_notes` middle band is DELETED.
+8. **Design-lint gate (C11)** — for every UI-touching task, run `apt-tools design-lint` against the implementation's generated HTML + `{task_dir}/mockups/mockup_final.html` (when present). Violations contribute to the proof-gate evidence story but are NOT blocking on their own.
 
 Use the proof-verification template (@packages/framework/templates/proof-verification.md)
-for the VERIFICATION.md output format.
+for the verification.json output schema.
 
 **Design-lint invocation** (when the task touched UI):