@aperant/framework 0.11.0 → 0.12.0

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

@@ -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/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):
 

package/src/cli/commands/apply-recipe.mjs

@@ -0,0 +1,105 @@
+/**
+ * commands/apply-recipe.mjs — `apt-tools apply-recipe <projectDir> [--confirm] [--accept-all] [--force]`.
+ *
+ * Wraps applyRecipe() at the CLI surface.
+ *
+ *   --confirm     switches from dry-run (the default) to live writes.
+ *   --accept-all  bypasses per-change confirmation (pipeline/scripted use).
+ *   --force       overrides the TOFU user_modified guard — overwrites files
+ *                 whose SHA diverges from the recipe's expected before value.
+ *                 Files containing the recipe's marker are still skipped.
+ *
+ * The two flags compose: `--confirm` alone enters live mode but defers
+ * per-change accept/skip to the caller — without `--accept-all` and
+ * without a stdin-driven prompt, every change is SKIPPED (fail-safe per
+ * ID-02). Adopters using the interactive apt-setup SKILL.md mini-flow
+ * walk each change one at a time before invoking the CLI with
+ * `--accept-all` once they've reviewed the diff. Adopters in CI /
+ * fan-out / scripted contexts pass both flags up front.
+ *
+ * Exit codes:
+ *   0 — applyRecipe completed (dry-run or confirmed)
+ *   1 — usage error / no-recipe-match / applyRecipe threw
+ */
+
+import { parseFlags } from '../util/args.mjs'
+import { err, exitWith, ok } from '../util/result.mjs'
+import { loadRuntimeCapabilities } from '../util/runtime-capabilities.mjs'
+import { applyRecipe } from '../verify-proof/sandbox/apply.mjs'
+import { matchPatternForProject } from '../verify-proof/sandbox/pattern-matcher.mjs'
+import { discoverBundledRecipes } from '../verify-proof/sandbox/sandbox-config.mjs'
+
+/**
+ * @param {string} projectDir
+ * @param {string[]} [extra]
+ */
+export async function cmdApplyRecipe(projectDir, extra = []) {
+	if (!projectDir) {
+		return err('Usage: apt-tools apply-recipe <project-dir> [--confirm] [--accept-all]')
+	}
+
+	const flags = parseFlags(extra)
+	const confirm = flags.has('confirm')
+	const acceptAll = flags.has('accept-all')
+	const force = flags.has('force')
+
+	const recipes = discoverBundledRecipes()
+	const runtime = loadRuntimeCapabilities(projectDir)
+
+	const explicitRecipeId = flags.get('recipe') ?? null
+	let recipeId
+	let matchReason
+	if (explicitRecipeId) {
+		recipeId = explicitRecipeId
+		matchReason = 'explicit'
+	} else {
+		const match = matchPatternForProject(projectDir, runtime, recipes)
+		recipeId = match.recipeId
+		matchReason = match.reason
+	}
+
+	if (!recipeId) {
+		return exitWith(
+			{
+				status: 'error',
+				command: 'apply-recipe',
+				code: 'E_NO_RECIPE',
+				reason: matchReason,
+				runtime,
+				docs: 'docs/verify-proof-sandbox-patterns.md',
+			},
+			1,
+		)
+	}
+
+	try {
+		const result = await applyRecipe({
+			projectDir,
+			recipeId,
+			recipes,
+			confirm,
+			// AC8 + ID-02 — only auto-accept when the caller passed
+			// --accept-all explicitly. Without the flag the underlying
+			// applyRecipe defaults to skip (every change recorded as
+			// `user_declined`); callers driving per-change UX wrap the
+			// applier directly with their own confirmer.
+			perChangeConfirm: acceptAll ? async () => 'accept' : undefined,
+			force,
+		})
+		return ok({
+			status: 'ok',
+			command: 'apply-recipe',
+			project_dir: projectDir,
+			recipe_id: recipeId,
+			recipe_version: result.recipe_version,
+			confirm,
+			accept_all: acceptAll,
+			aborted: result.aborted,
+			writes: result.writes,
+			skips: result.skips,
+			audit_path: result.audit_path,
+		})
+	} catch (e) {
+		return err(`apply-recipe: ${e?.message ?? String(e)}`)
+	}
+}

package/src/cli/commands/mobile-prepare.mjs

@@ -0,0 +1,151 @@
+/**
+ * commands/mobile-prepare.mjs — `apt-tools mobile prepare`.
+ *
+ * Owns the mobile app lifecycle for the verify-proof mobile surface
+ * (decisions D-03/D-04): build → install → launch → Metro → launch-readiness
+ * gate. This is the home for multi-minute orchestration that CANNOT live in a
+ * driver PreflightCheck (those are ≤5s, shell-free, single LocalCommand).
+ *
+ * The command is PLAN-producing: it resolves the ordered launch sequence and
+ * the readiness-gate contract and returns them in the envelope. The
+ * verify-proof workflow runner (which holds the host tool surface) executes
+ * the sequence, gates on the readiness signals, THEN hands UI verbs to the
+ * mobile driver. This mirrors the driver pattern (driver.mjs are adapters;
+ * the runner dispatches).
+ *
+ * Pure, unit-testable seams: `planLaunchSequence` + `isAppReady`.
+ */
+
+import { loadRuntimeCapabilities } from '../util/runtime-capabilities.mjs'
+
+/**
+ * @typedef {{ binary: string, args: string[] }} LocalCommand
+ */
+
+/**
+ * Resolve the ordered launch sequence for a (platform, mode, device).
+ *
+ * - mode 'expo' — `npx expo run:ios|run:android` builds, installs, launches,
+ *   and starts Metro in one step (the common Expo/RN path).
+ * - mode 'native' — device-prep only (`xcrun simctl boot` / `adb
+ *   wait-for-device`); the native build+install+launch is delegated (gradle /
+ *   the XcodeBuildMCP escalation per D-02), out of scope for v1's planner.
+ *
+ * @param {{ platform?: string, mode?: string, device?: string }} [opts]
+ * @returns {LocalCommand[]}
+ */
+export function planLaunchSequence(opts = {}) {
+	const { platform, mode = 'expo', device } = opts
+	if (platform !== 'ios' && platform !== 'android') {
+		throw new Error(`planLaunchSequence: platform must be 'ios' or 'android', got "${platform}"`)
+	}
+	if (mode !== 'expo' && mode !== 'native') {
+		throw new Error(`planLaunchSequence: mode must be 'expo' or 'native', got "${mode}"`)
+	}
+
+	if (mode === 'expo') {
+		const expoArgs = ['expo', platform === 'ios' ? 'run:ios' : 'run:android']
+		if (device) expoArgs.push('--device', device)
+		return [{ binary: 'npx', args: expoArgs }]
+	}
+
+	// native — device prep only.
+	if (platform === 'ios') {
+		return [{ binary: 'xcrun', args: ['simctl', 'boot', device ?? 'booted'] }]
+	}
+	return [{ binary: 'adb', args: device ? ['-s', device, 'wait-for-device'] : ['wait-for-device'] }]
+}
+
+/**
+ * Launch-readiness predicate (D-04). A successful screenshot alone is NOT
+ * enough — for RN/Expo it can capture a native splash, an Expo loading
+ * overlay, a redbox, or the dev-client launcher. ALL signals must hold before
+ * UI driving starts. For a pure-native app (no JS bundle) the caller passes
+ * `bundleConnected: true` and `launcherState: false`.
+ *
+ * @param {{ foregrounded?: boolean, bundleConnected?: boolean, redbox?: boolean, launcherState?: boolean }} [signals]
+ * @returns {boolean}
+ */
+export function isAppReady(signals) {
+	const s = signals && typeof signals === 'object' ? signals : {}
+	return (
+		s.foregrounded === true &&
+		s.bundleConnected === true &&
+		s.redbox !== true &&
+		s.launcherState !== true
+	)
+}
+
+/** The readiness-gate contract surfaced to the workflow runner. */
+const READINESS_GATE = {
+	description:
+		'App-ready gate (D-04). All signals must hold before UI verbs are dispatched to the mobile driver.',
+	signals: ['foregrounded', 'bundleConnected', 'no-redbox', 'no-launcher-state'],
+}
+
+/** @param {string} message */
+function errorEnvelope(message) {
+	return { envelope: { status: 'error', command: 'mobile-prepare', error: message }, exitCode: 1 }
+}
+
+/**
+ * Parse `--platform <ios|android> [--mode <expo|native>] [--device <id>]`.
+ *
+ * @param {string[]} args
+ * @returns {{ platform?: string, mode?: string, device?: string }}
+ */
+function parseFlags(args) {
+	/** @type {{ platform?: string, mode?: string, device?: string }} */
+	const opts = {}
+	for (let i = 0; i < args.length; i++) {
+		if (args[i] === '--platform' && args[i + 1]) opts.platform = args[++i]
+		else if (args[i] === '--mode' && args[i + 1]) opts.mode = args[++i]
+		else if (args[i] === '--device' && args[i + 1]) opts.device = args[++i]
+	}
+	return opts
+}
+
+/**
+ * `apt-tools mobile prepare <project-dir> --platform <ios|android>
+ *  [--mode <expo|native>] [--device <id>]`
+ *
+ * @param {string} projectDir
+ * @param {string[]} args
+ * @returns {{ envelope: object, exitCode: number }}
+ */
+export function cmdMobilePrepare(projectDir, args) {
+	const opts = parseFlags(args ?? [])
+	if (opts.platform !== 'ios' && opts.platform !== 'android') {
+		return errorEnvelope('--platform <ios|android> is required')
+	}
+	if (opts.mode && opts.mode !== 'expo' && opts.mode !== 'native') {
+		return errorEnvelope(`--mode must be 'expo' or 'native', got "${opts.mode}"`)
+	}
+
+	// Infer mode from the project shape when not explicitly given (ties the
+	// detector to the launch story — an Expo/RN project launches via `expo run`).
+	let mode = opts.mode
+	if (!mode) {
+		const caps = loadRuntimeCapabilities(projectDir ?? '.')
+		mode = caps.is_expo || caps.is_react_native ? 'expo' : 'native'
+	}
+
+	const launch_sequence = planLaunchSequence({ platform: opts.platform, mode, device: opts.device })
+
+	return {
+		envelope: {
+			status: 'ok',
+			command: 'mobile-prepare',
+			platform: opts.platform,
+			mode,
+			device: opts.device ?? null,
+			launch_sequence,
+			readiness_gate: READINESS_GATE,
+			note:
+				'Plan only — the verify-proof workflow runner executes the launch sequence, gates on ' +
+				'the readiness signals, then hands UI verbs to the mobile driver. System prereqs ' +
+				'(idb/adb/Xcode/SDK) are validated by `apt-tools driver doctor` (D-09).',
+		},
+		exitCode: 0,
+	}
+}