@aperant/framework 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -3,39 +3,222 @@
 All notable changes to `@aperant/framework` are documented here. See
 [`VERSIONING.md`](VERSIONING.md) for the per-tier contract.
 
-## Unreleased
+## 0.12.0 — 2026-05-31 — Mobile verification surface for verify-proof (iOS + Android)
 
-## 0.11.0 — 2026-05-26 — Collaboration catch-up
-
-Adds a collaboration catch-up panel that greets you with your own
-half-finished work and what teammates merged since you were last here, so
-returning to a shared repo no longer means re-deriving state by hand.
+Adds a mobile verification surface so `/apt:verify-proof` can drive native
+iOS + Android apps. One unified `mobile-mcp` driver covers both platforms
+(platform = device choice inside the driver); the original two-server RFC
+design was reversed via `apt:discuss` + a 3-round `apt:spar` (decisions
+D-01…D-09).
 
 ### Added
 
-- **Collaboration catch-up — route envelope `catch_up` field + `apt-catch-up`
-  skill.** On every interactive (TTY) `/apt` call the router folds a top-level
-  `catch_up` field onto the route envelope (alongside `update_check`), and
-  `apt/SKILL.md` renders it before the mode handler — runtime-agnostic, no
-  Claude-only hook. It carries two panels: the always-on **Welcome-Back
-  Summary** (your own half-finished work) and the gated **Team-Change Digest**
-  (teammates' PRs merged since your last pull, attributed by introduced commit;
-  team/oss visibility only). Merged-PR attribution is parsed from local git
-  history with no network call (default-branch ref resolved locally). The new
-  read-only `/apt:catch-up` skill re-views the same panel on demand **without
-  advancing the marker**. Non-TTY / background / spawned calls carry no
-  `catch_up` and never touch the marker. State lives in a per-machine,
-  gitignored Last-Seen Marker (`.aperant/last-seen/{email-slug}.json`) persisted
-  via the `CoordinationStore` seam.
-- **`/apt:setup` collaboration config block.** New `config.json.collaboration`
-  keys (`welcome_back.{enabled,threshold_hours}`,
-  `team_digest.{enabled,max_entries}`) surfaced through a `/apt:setup` mini-flow
-  (Batch 10).
-
-> **Re-install required (R5):** the new `apt-catch-up` skill and the `catch_up`
-> envelope field require adopters to re-run
-> `apt-tools init . --<runtime> --team|--solo` (or `/apt:update`) so each
-> per-runtime manifest picks up the new skill.
+- **`mobile` driver** (`packages/framework/drivers/mobile/`) — unified iOS +
+  Android UI driver wrapping `mobile-mcp` (`{ mcp_server_id: "mobile-mcp" }`,
+  targets `ios`/`android`/`expo`/`react-native`). `preflight[]` validates
+  `xcrun`/`adb` so `apt-tools driver doctor` surfaces missing system prereqs.
+- **`mobile` User-Outcomes surface** — a `[mobile]` outcome tag resolves to the
+  mobile driver (new `ios`/`android` `matchesRuntime` cases + an `is_mobile`
+  surface mask in the resolver).
+- **`apt-tools mobile prepare`** — resolves the app launch sequence
+  (`expo run:*` / `xcrun simctl` / `adb`) plus the launch-readiness gate
+  (foregrounded + JS-bundle-connected + no redbox) that the verify-proof
+  workflow runner executes before driving UI.
+- **Native project detection** — `is_ios_native` / `is_android_native`
+  (`*.xcodeproj` / `build.gradle` fs-walk in `loadRuntimeCapabilities`;
+  `detectFromPackageJson` stays pure). Reuses existing `is_expo` /
+  `is_react_native`.
+- **`mobile-mcp` auto-provisioning** — `npx -y @mobilenext/mobile-mcp@latest`
+  is provisioned when a mobile project is detected. System prereqs
+  (idb / adb / Xcode / Android SDK) are validated, never auto-installed.
+
+### Scope
+
+The live simulator/emulator path is local-dev only (needs Xcode/Android SDK +
+idb/adb) and is covered by the pure-seam unit tests; real-device runs, Flutter,
+and Mac Catalyst are out of scope (separate RFCs).
+
+## 0.11.0 — 2026-05-27 — Sandbox setup for parallel /apt:verify-proof
+
+Adds the recipe-driven sandbox setup flow so adopters can opt their
+project into parallel-safe `/apt:verify-proof --parallel` (e.g. from
+fan-out worker terminals) without `SQLITE_BUSY`, port collision, or
+Electron `requestSingleInstanceLock` denial. v2-aligned end-to-end —
+the precondition gate's failure envelope shares the
+`verdict: "needs_human"` vocabulary verify-proof v2 emits per-outcome.
+
+**New CLI subcommands** (three; all opt-in):
+
+- `apt-tools recipe-diff <dir> [--format json|md]` — read-only Markdown
+  preview of the proposed config + source-code changes. Exits 0 on
+  match, 1 on no-recipe-match with `code: 'E_NO_RECIPE'`.
+- `apt-tools apply-recipe <dir> [--confirm] [--accept-all]` — dry-run
+  by default (writes ZERO files, ZERO audit row).
+  - `--confirm` alone enters live mode but defers per-change accept/skip
+    to the caller (every change records as `user_declined`, source
+    files untouched — ID-02 fail-safe).
+  - `--confirm --accept-all` writes every change non-interactively
+    (pipeline / scripted / SKILL.md mini-flow after the user reviewed
+    the diff).
+  - `--force` overrides the TOFU non-clobber `user_modified` guard.
+    When present, `apply-recipe` overwrites files whose SHA-256 diverges
+    from the recipe's expected `before` value (i.e. the user has already
+    edited the file). Use with caution — the recipe's expected-before
+    anchor is skipped. Files that contain the recipe's marker substring
+    (`already_applied`) are still skipped even with `--force`.
+  - TOFU non-clobbering (already_applied / user_modified /
+    malformed_json / non_object_root) mirrors `install/mcp-provision.mjs`.
+  - Audit trail at `.aperant/recipes-applied/{recipe-id}.json` (one
+    row per apply invocation).
+  - **v1 limitation — text-insert kinds APPEND** the template at
+    end-of-file. The recipe template comment usually says "insert near
+    the top of X" — review the diff and move the block manually after
+    apply if your runtime requires exact positioning. The
+    per-change-confirmation flow surfaces this before any write lands.
+  - **Path-traversal defense** — recipe `change.path` / `change.template`
+    are validated to stay under the adopter root / recipe templates dir
+    respectively. A malicious community recipe attempting `../../etc/...`
+    is rejected at apply time, regardless of schema acceptance.
+- `apt-tools verify-sandbox <dir>` — spawns TWO instances of the
+  recipe's launch command concurrently (`Promise.all`, jittered 50-150
+  ms) and writes
+  `.aperant/state/verify-proof-sandbox-verified.json` with the
+  v2-shaped envelope `{verified, verdict:'approved'|'needs_human',
+  reason, recipeId, recipeVersion, verifiedAt, host, durationMs}`.
+  win32 short-circuits to `reason:'platform_unsupported'`.
+
+**New SKILL.md gate.** `apt-verify-proof/SKILL.md` § Step 2c reads the
+state file BEFORE the outcome walker enters Step 2.5 (Deferred-tool-
+load). When `--parallel` is requested with no verified state, exit
+with the structured envelope
+`{status:"error", code:"E_SANDBOX_UNVERIFIED", verdict:"needs_human",
+reason:"sandbox_unverified", remediation:"/apt:verify-proof setup"}`
+and stderr `"sandbox not verified — run /apt:verify-proof setup first"`.
+When `--parallel` is requested and the state file's `recipeVersion` is no
+longer in the active recipe's `compatibleWithApplied[]`, exits with
+`{code:"E_SANDBOX_VERDICT_STALE", verdict:"needs_human",
+reason:"sandbox_recipe_version_drift"}` — re-run `apt-tools verify-sandbox`
+to refresh.
+
+**New error codes in `verify-sandbox` envelope.**
+- `E_STATE_WRITE_FAILED` — `withFileLock` exhausted retries (e.g. ELOCKED
+  on Windows). Verdict is `needs_human`; the sandbox run itself may have
+  completed. Re-run `apt-tools verify-sandbox` to retry the state write.
+- `E_UNKNOWN_CHANGE_KIND` — a recipe `changes[]` entry carries a `kind`
+  not in `{file-create, json-merge, text-insert, text-replace}`. The
+  recipe is malformed; do not apply it.
+- `E_INVALID_RECIPE_ID` — `recipeId` fails the `^[a-z][a-z0-9_-]*$`
+  pattern (path-traversal guard). The recipe is rejected before any file
+  read or write.
+
+**New first-run hook.** `apt-setup/SKILL.md` Step 2 and
+`apt-verify-proof/SKILL.md` Step 1 prompt only when
+`host.capabilities.structured_prompts:true` AND `process.stdout.isTTY:true`
+AND `verification.sandbox` is absent (ID-08). Non-interactive surfaces
+print a one-line `[apt] tip:` and skip — never block CI / fan-out.
+
+**New config block.** Optional `verification.sandbox` in
+`.aperant/config.json` (mirrored by JSON-schema at
+`packages/framework/src/cli/verify-proof/sandbox/sandbox-schema.json`).
+Absent block = today's behavior, byte-identical Fast Path Guarantee
+(ID-07).
+
+**New recipe library.** `packages/framework/recipes/` ships
+`recipe-manifest-schema.json` + the v1 canned `electron-libsql/`
+recipe (config block + APERANT_SANDBOX_DB_PATH reader + singleton-lock
+test-mode gate + `scripts/run-sandbox.sh` helper). v1 ships ONE
+recipe; unknown runtimes get a doc pointer to
+`docs/verify-proof-sandbox-patterns.md`.
+
+**Anti-queue invariant (ID-01).** TD-09 grep guard locks: no file
+under `packages/framework/src/cli/verify-proof/sandbox/**` may import
+from `install/install-semaphore.mjs` or reference
+`acquireInstallSlot` / `releaseInstallSlot`. The founder explicitly
+rejected queue semantics in spar round 3 ("queue means parallel isn't
+actually working").
+
+**Docs.** `docs/verify-proof-sandbox-patterns.md` carries the worked
+electron-libsql walkthrough (recipe-diff → apply-recipe → verify-
+sandbox), tauri-rusqlite + nextjs-sqlite config stubs, the
+manual-integration template for unrecognized runtimes, and the v2
+vocabulary cross-reference.
+
+**Multi-runtime re-install.** Adopters MUST re-run `/apt:update` (or
+`apt-tools init . --<runtime>`) after the version bump to propagate
+the new SKILL.md gate text + apt-planner.md v2-envelope-citation
+guidance into each installed runtime.
+
+### verify-proof v2 — outcome walker + two-gate verdict
+
+`/apt:verify-proof` is rewritten end-to-end as an outcome walker. Closes
+four root causes from the 2026-05-26 17:00 run:
+
+- **A1 — automation gate hard-stops on the `enforced_at_commit` dodge.**
+  Step 3 of the workflow requires `automated_checks.{tests,typecheck,lint}.status`
+  to be in the closed set `{pass, fail}`. The legacy `"enforced_at_commit"`
+  string is REJECTED. Verdict rolls up to `rejected` on any single check
+  failing.
+- **A2 — renderer rewrite from feature-grouped to outcome-rooted.**
+  `mapVerificationJson` groups tests by `outcome_id` (not by
+  `registry_id.split('-')[0]`). The HTML renderer emits one card per
+  outcome with `data-outcome-id` + `data-surface` attributes, inferred
+  children inside a `<details>` block, and two gate badges in the header.
+  Report envelope returns `outcomesCount`; `featuresCount` becomes a `0`
+  sentinel for one release.
+- **A4 — feature-registry fallback REMOVED.** When `spec.md` lacks
+  `## User Outcomes`, the workflow aborts at Step 2 with a clear error.
+  The legacy "discover features from the registry" code path is gone.
+- **A5 — deferred-tool-load directive in the skill + workflow.**
+  Claude Code / OpenCode hosts MUST load MCP driver tools via
+  `ToolSearch(query='select:mcp__<server>__<tool>')` BEFORE driving any
+  UI-surface outcome. The real manifest field name is `transport.mcp_server_id`;
+  the hallucinated `mcp_transport.tool_prefix` is grep-guarded out.
+
+### Cutover details
+
+- **Verdict enum is the closed set `{approved, rejected, needs_human}`.**
+  `approved_with_notes` is DELETED — no shim, no silent re-map. Reading a
+  legacy verdict from a stale `qa_signoff.json` throws a migration error
+  pointing at this CHANGELOG entry. **Affected workflow:** re-run
+  `/apt:verify-proof` on any in-flight task whose `qa_signoff.json`
+  carries `approved_with_notes`; that mints a fresh signoff under the
+  new enum.
+- **Two-gate envelope.** `verification.json :: gates: {automation_gate,
+  proof_gate}`. `automation_gate = pass` iff lint + typecheck + tests
+  are all green. `proof_gate = pass` iff every outcome has
+  surface-appropriate evidence. Verdict = `approved` iff both gates
+  pass; `needs_human` when proof_gate fails on a UI-surface transport
+  gap; `rejected` otherwise.
+- **Proof-gate fail-closed on file-evidence.** A UI-surface test
+  (`electron | web | electron+web`) carrying `evidence: "file-evidence:
+  ..."` is coerced to `result: "needs_human_with_transport"`
+  regardless of its written `result`. The overall verdict rolls up to
+  `needs_human`, NOT `approved`.
+- **Inferred bullets in spec.md.** `apt:plan` Section 5.B now instructs
+  the planning LLM to write indented child bullets under each `**ON**`
+  parent outcome representing inferred sub-checks. `parseUserOutcomes`
+  reads them and attaches them as `inferred: string[]`. **NO** patterns
+  library, **NO** `surfaces/<name>/manifest.json` tree, **NO**
+  `OUTCOMES.md` file — inferred bullets live IN spec.md. Author edits
+  once if the inferred list is wrong; the runner does not re-derive
+  them at proof time.
+- **Cross-link.** A3 (features-audit nested-worktree merge-back gap)
+  surfaced in the same run is filed as a follow-up in
+  [`docs/frameworks/spec-gaps.md#a3`](../../docs/frameworks/spec-gaps.md#a3)
+  — explicitly out of scope for this cutover.
+
+### Migration
+
+- Tasks whose `qa_signoff.json` carries `approved_with_notes` must
+  re-run `/apt:verify-proof`. The new run mints a fresh signoff under
+  the closed `{approved, rejected, needs_human}` enum. There is no
+  silent compatibility layer.
+- `qa.approved_with_notes_threshold` in `.aperant/config.json` is
+  silently dropped at read time (logged once) — projects that opted
+  into the legacy threshold-gated acceptance no longer get it. Tasks
+  that previously shipped `approved_with_notes` ship `approved` only
+  if both gates pass; everything else needs a code fix (`rejected`)
+  or a transport install (`needs_human`).
 
 ### Fixed
 
@@ -55,7 +238,7 @@ returning to a shared repo no longer means re-deriving state by hand.
   regression does not return). The per-PR / global `authorship_override` lever
   is unchanged and still wins over auto-detection — set it to `owned` to
   deliberately fix-and-push on a PR you did not author. Behavior-only fix: no
-  CLI flag, signature, or output-shape change.
+  CLI flag, signature, or output-shape change, and no version bump.
 
 ## 0.10.0 — 2026-05-26 — Tauri driver + MCP auto-provision
 

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