@aperant/framework 0.8.1 → 0.8.6

package/CHANGELOG.md

@@ -3,7 +3,449 @@
 All notable changes to `@aperant/framework` are documented here. See
 [`VERSIONING.md`](VERSIONING.md) for the per-tier contract.
 
-## [Unreleased]
+## 0.8.6 — 2026-05-24 — Outcome-first verify-proof contract + driver-sdk inline (recovery from 0.8.4 npm 404)
+
+> **Migration window.** This release introduces a new `## User Outcomes`
+> section that becomes the verify-proof input contract. Specs WITHOUT
+> the section emit a `coverage-check` **warning** on v0.8.x and a
+> **HARD BLOCK** starting v0.9.0. Refactor-only specs SHOULD use the
+> empty-with-note escape (`_No user-observable changes — pure
+> refactor._`) to declare absence-of-outcomes deliberately. See spec
+> §ID-07 of `verify-proof-monorepo-contract` for the gate table.
+
+> **Recovery.** 0.8.4 shipped with `@aperant/driver-sdk: 0.1.0` as a
+> direct dep, but the driver-sdk package was never published — every
+> `npm install @aperant/framework@0.8.4` since 2026-05-22 failed with
+> a 404 on the transitive dep. 0.8.6 inlines the 875-LOC zero-dep SDK
+> into the framework tarball, removing the broken dep. Users on 0.8.4
+> MUST upgrade to 0.8.6 to install successfully.
+
+### Fixed
+
+- **`@aperant/driver-sdk` inlined into framework src** (recovery from
+  the 0.8.4 npm 404). The SDK lived at `packages/framework-driver-sdk/`
+  with the contract that third-party driver authors would `pnpm add
+  @aperant/driver-sdk` and avoid pulling all of framework. The SDK
+  was never published; pnpm's `workspace:*` rewrite baked an
+  unresolvable `0.1.0` spec into framework's published `package.json`.
+  Fix: 875 LOC of zero-runtime-dep SDK moved to
+  `packages/framework/src/driver-sdk/`, framework imports rewritten to
+  relative paths, the `import-direction.test.ts` invariant repurposed
+  from a package boundary to a subdirectory boundary so re-extraction
+  stays mechanical if a real third-party driver author ever asks for a
+  standalone install. The `@aperant/driver-sdk` npm package remains
+  unpublished — no consumers existed to migrate.
+
+### Added
+
+- **`## User Outcomes` PRD section** — verify-proof's input contract.
+  STANDARD/DEEP specs ship a section between `## Solution` and
+  `## Implementation Decisions` carrying one `**Epic:**` headline + N
+  atomic outcomes tagged by surface (`electron | web | cli | api |
+  electron+web`). Authors write the literal `**ON**` token; IDs are
+  POSITIONAL and synthesized by the parser (O1, O2, …). Optional
+  cross-refs via `*(requires ON N)*`. Empty-with-note refactor escape
+  for non-UX tasks. QUICK track is hard-exempt per the Fast Path
+  Guarantee (ID-05).
+- **`drivers/browser/manifest.json:transport.skill_id = "agent-browser"`**
+  — second transport option alongside `mcp_server_id: "puppeteer"`.
+  On Claude Code / OpenCode hosts the workflow runner dispatches via
+  `Skill({skill: "agent-browser", args: ...})` (one fewer external
+  dep — no Puppeteer MCP install needed); on legacy hosts the MCP
+  path is preserved. `chooseTransport({has_skill_tool})` helper.
+- **`resolveDriversForOutcomes(opts)`** — new resolver entrypoint that
+  returns one entry per (outcome, surface) pair. For `[electron+web]`
+  outcomes emits TWO entries with the same `outcome_id` and different
+  drivers. Delegates to existing `resolveDriver()` for scoring.
+- **`verification.monorepo_globs: string[]`** config key (default
+  `["apps/*"]`) — `loadRuntimeCapabilities` walks each glob match's
+  `package.json` and OR-merges its capabilities with the root.
+  Disable the walk entirely with `monorepo_globs: []`.
+- **`transport` field on `verification.json:tests[]`** — `skill | mcp
+  | binary | http`. Populated by the workflow runner from the
+  dispatcher's directive (Step 7a). Documented in
+  `templates/proof-verification.md`.
+- **`surface` field on `verification.json:tests[]`** — `electron | web
+  | cli | api`. Drives the per-surface screenshot path and the
+  `coverage.by_surface` rollup. Cross-surface outcomes produce TWO
+  test entries sharing the same `outcome_id`.
+
+### Changed
+
+- **`apt-tools detect-runtime`** — now walks `apps/*/package.json` by
+  default. Fixes the canonical Aperant monorepo defect (root
+  package.json with no Electron dep + `apps/desktop/package.json`
+  carrying Electron previously returned `is_electron: false` because
+  the detector only read the root). No user-visible config change
+  needed; opt out via `verification.monorepo_globs: []`.
+- **`apt-tools coverage-check validate`** — payload gains a
+  `user_outcomes` block when the plan is STANDARD/DEEP. Block carries
+  `header_present`, `body_kind` (`empty | empty-with-note | outcomes
+  | absent`), `outcomes_count`, `validation_warnings?`, and
+  `gate_result` (`pass | warn | block`). QUICK plans omit the block
+  entirely per Fast Path Guarantee.
+- **`workflows/verify-proof.md` Step 7** — dispatches per outcome via
+  `resolveDriversForOutcomes()` instead of a single per-run
+  `resolveDriver()` call. Writes screenshots under
+  `${PROOF_DIR}/${surface}/screenshots/${outcome-id}.png` (per-surface
+  split tree). Step 7a gains the MUST-invoke Skill directive
+  (TD-08 grep guard pins the language).
+
+### Deprecated
+
+- **Specs without `## User Outcomes` (STANDARD/DEEP only).** v0.8.x
+  emits a `coverage-check` **warning** with a `migration_deadline`
+  string referencing v0.9.0. v0.9.0 will **HARD BLOCK** specs that
+  lack the section. Refactor-only specs SHOULD use the
+  empty-with-note escape (`_No user-observable changes — pure
+  refactor._`, italic underscores + em dash + period required) to
+  declare absence-of-outcomes deliberately. QUICK-track plans are
+  hard-exempt at every version.
+
+### v0.9.0 telegraph (one-minor window)
+
+The v0.9.0 cutover lands the hard-block on missing `## User Outcomes`
+in STANDARD/DEEP specs. Adopters should retrofit specs in the v0.8.x
+window OR adopt the empty-with-note escape for refactor specs. No
+silent migration of existing specs is provided — the migration is
+deliberate per author.
+
+### Out-of-scope (deferred follow-ups)
+
+- **`verify-proof-executable-runner`** — the v1 verify-proof runner is
+  the host LLM (Claude Code / Codex / OpenCode / Gemini) following
+  `workflows/verify-proof.md` as a prose recipe. The framework does
+  NOT ship an executable `apt-tools verify-proof` command in 0.8.6.
+  The `transport` field, per-outcome dispatch, and MUST-invoke
+  directive are LLM-honored conventions enforced via grep guards on
+  workflow text (TD-08) and schema assertions on `verification.json`
+  shape (AC23). Follow-up `verify-proof-executable-runner` task is
+  deferred per spec §Out of Scope; the triggers that would promote
+  Path B → Path A are documented there.
+- **`apt-tools outcomes lint`** — sentence-shape lint for User
+  Outcomes (catches squishy outcomes, validates surface tags).
+  Deferred to a follow-up framework task.
+
+## 0.8.5 — 2026-05-22 — `/apt:verify-proof` driver layer fixes (bundled drivers + hard override precedence)
+
+### Fixed
+
+- **`drivers/` missing from published tarball.** `packages/framework/package.json:files`
+  did not include `drivers/`, so the four bundled IDL drivers (`browser`,
+  `electron`, `cli`, `api` — each with `manifest.json` + `driver.mjs` +
+  `README.md`) were stripped at `pnpm pack` / `npm publish` time. Downstream
+  effect: `apt-tools detect-runtime` returned `discovered_drivers: []` and
+  `selected_driver_id: null` for every installed kernel, which made the
+  strict `/apt:verify-proof` IDL path unusable (resolver throws
+  `unsatisfied_required_capability`). Fix is a one-line `files` entry —
+  re-pack now ships 4 manifests + 4 driver modules. Self-host installs
+  fix automatically on the next `/apt:update --from-source`; npm-install
+  consumers fix on the next published version bump.
+
+- **`verification.runtimes[]` override was decorative.** The resolver
+  in `packages/framework/src/cli/verify-proof/resolver.mjs` placed
+  override-listed drivers first in the candidate list but then sorted
+  the list by score, wiping the override order. With a Next.js root
+  `package.json` (e.g. a monorepo where Electron lives at `apps/desktop`),
+  forcing `verification.runtimes: ["electron"]` still selected `browser`
+  because the latter had higher `priority` (100 vs 90). The override
+  docstring promised "explicit driverId precedence" but delivered a
+  tie-breaker. Fix: override is now **hard precedence** — listed
+  drivers are tried in override order, first one satisfying every
+  required capability wins regardless of score; non-matching override
+  entries are recorded in `fallback_attempts` with reason
+  `override-listed but missing required capabilities: ...` and the
+  resolver then falls through to the score-based pick on remaining
+  drivers. Two test cases in `verify-proof-resolver.test.ts` lock the
+  new contract (force-pick + fall-through).
+
+## 0.8.4 — 2026-05-22 — `/apt:update` polish + `apt:handoff`, `apt:caveman` skills + `apt:resume` HANDOFF discovery
+
+Bundled release: five `/apt:update` fix bundles (converged from a 3-round
+Codex sparring session at `.aperant/spar/apt-update-fixes-20260522-083919.md`,
+resolving 9 reported issues + 2 hidden defects) plus two new skills and one
+extended skill.
+
+> **VERSIONING.md note.** New skills normally trigger MINOR per the
+> contract. Operator opted for PATCH here because the surface area is
+> small (2 skills, 1 extension) and the apt:update polish is the load-
+> bearing change. Future MINOR bumps remain reserved for transform /
+> manifest / CLI flag additions.
+
+### Added
+
+- **`/apt:handoff`** (new skill at `packages/framework/skills/apt-handoff/SKILL.md`).
+  Agent-to-agent handoff — compacts the current conversation into a
+  `HANDOFF.md` artifact under `.aperant/handoffs/{id}/` (or
+  `{task_dir}/handoffs/{id}/` when inside a routed task), indexed via a
+  new `.aperant/HANDOFFS_INDEX.md`. Distinct from `/apt:pause` along
+  four axes: trigger (agent vs human), audience (different agent vs
+  future-self), uncommitted-work handling (does NOT stash), and index
+  file. `stage: pause`, `intent: capture`, `task_context: none`.
+- **`/apt:caveman`** (new skill at `packages/framework/skills/apt-caveman/SKILL.md`).
+  Ultra-compressed terse output mode — toggles a persistent "smart
+  caveman" style that cuts conversational token usage while keeping
+  full technical accuracy. `stage: ops`, `intent: configure`,
+  `allowed-tools: ""`.
+
+### Changed
+
+- **`/apt:resume`** now discovers HANDOFF artifacts in addition to
+  CONTINUE artifacts. New step `1b` reads `.aperant/HANDOFFS_INDEX.md`;
+  step `1d` scans `.aperant/{tasks/*/handoffs,handoffs}/*/HANDOFF.md` as
+  fallback. The Present Sessions list tags each row `[pause]` or
+  `[handoff]` (handoffs render first — higher urgency). Step 3 splits
+  into `3a` (pause: read CONTINUE.md, pop stash) vs `3b` (handoff: read
+  Focus, verify external state, do NOT pop stash). Cleanup removes the
+  matching index row regardless of type.
+
+### Fixed
+
+- **Bundle A — Workspace-aware version detection.** New helper
+  `findWorkspaceFrameworkVersion(targetDir)` walks up to a sibling
+  `packages/framework/package.json` (max 6 frames, mirroring
+  `route/drift-detect.mjs:32`). The SessionStart worker cache + the
+  `apt-tools check-version --json` envelope now carry an additive
+  `framework.workspace_version: string | null` field. When the
+  workspace is ahead of the running kernel, `update_available` flips
+  true regardless of npm cache state — the workspace is the source of
+  truth on self-host. `--from-source` flag preserved as explicit
+  override per ID-03. Resolves issues 1, 7, 9.
+- **Bundle B — Idempotent kernel install.** `installKernel` short-
+  circuits when the kernel package.json already reports the target
+  version AND the kernel binary exists. Returns the same
+  `status: 'installed'` envelope with `reason: 'already at target
+  version'` + `durationMs: 0` so the three downstream consumers
+  (init.mjs:1441, init.mjs:1735, SKILL.md Scenario D) keep their
+  existing branching. No new enum value (D-02). Resolves issues 5, 6.
+- **Bundle C — SKILL.md doc gaps.** Adds the `pnpm install --filter
+  @aperant/framework... --frozen-lockfile=false` precondition before
+  the `pnpm pack` recipe (AC6); adds a hard warning against
+  substituting `npm pack` — names the `workspace:*` literal +
+  `EUNSUPPORTEDPROTOCOL` keyword (AC7); adds a `Migrated:` line slot
+  to all three Scenario A/B/C templates, conditional on
+  `legacy_cleanup?.ran === true && rmdirs.some(p => p.includes('.codex'))`
+  (AC8). Resolves issues 2, 4, 8.
+- **Bundle D — Workspace-dep chain.** New CLI subcommand
+  `apt-tools install-from-source <project-dir>` walks workspace
+  `dependencies` + `peerDependencies` for `workspace:*` entries
+  (matching by package `name`, not directory name —
+  `@aperant/driver-sdk` lives at `packages/framework-driver-sdk/`),
+  pnpm-packs each, then invokes a single `npm install --prefix
+  .aperant/deps <tarball-list>...` with the existing kernel-install
+  flag set (`--no-save`, `--no-package-lock`, `--no-audit`,
+  `--no-fund`). Handles the same-PR unpublished-pair case
+  (`framework@X` + `driver-sdk@Y` both at `workspace:*`, both
+  unpublished) without `EUNSUPPORTEDPROTOCOL`. SKILL.md §1.7
+  simplified to a single apt-tools invocation; the manual recipe
+  preserved as a debugging-aid footnote. Resolves issue 3.
+- **Bundle E — Init comment inversion + Scenario A null-latest.**
+  Fixed `init.mjs:1253-1268` comment + stderr direction (LEGACY =
+  `.codex/`, CURRENT = `.agents/skills/<folder>/SKILL.md`; was
+  reversed; the v0.8.2 inversion is documented in
+  `runtime-migrate.mjs:7-12`). Scenario A now requires
+  `latest_version != null` to avoid false "version bump" chips when
+  npm-latest is unknown (cache stale, not published, network down).
+  New Scenario E ("no version info available") branch handles that
+  case explicitly — refreshes runtime files for safety, tells the
+  user the bump is deferred. Resolves 2 hidden defects.
+
+### Schema status
+
+Envelope changes are strictly additive — the new
+`framework.workspace_version` field is nullable, existing callers
+ignore unknown fields. **No `schema_version` bump** (cache stays at
+`1`, locked by `update-chips.mjs:97-98` + the
+`check-version-cache-merge.test.ts:137-148` schema-2 rejection
+regression test).
+
+### Decision source
+
+Codex sparring session 2026-05-22 (3 rounds, CONVERGED).
+
+### Tests
+
+- **New:** `find-workspace-framework-version.test.ts`,
+  `install-kernel-idempotent.test.ts`,
+  `apt-update-skill-doc-gaps.test.ts`, `install-from-source.test.ts`,
+  `init-legacy-cleanup-direction.test.ts` (5 files / 23 new cases).
+- **Augmented:** `check-version-cache-merge.test.ts` (+2 cases for
+  the workspace_version envelope field).
+- **Regression-locked:** `apt-update-from-source-skill-structure.test.ts`,
+  `route-source-drift-detection.test.ts`, `legacy-cleanup-codex.test.ts`,
+  `check-version-cache-merge.test.ts` (existing schema_version=2
+  rejection at `:137-148`). All still pass.
+
+## 0.8.3 — 2026-05-21 — FRAMEWORK-RFC-001 — `/apt:spar` pipeline integration with install-time consent
+
+Minor patch release. Flips `/apt:spar` from manual-only (SPAR-07 v1) to
+pipeline-integrated under explicit install-time consent. Adds a per-device
+opt-in question to `/apt:setup` Batch 2 Pipeline; wires `/apt:run` and the
+`/apt` router to honor it with track-aware gates (QUICK rejects, STANDARD
+= `plan` gate, DEEP = `plan,execute` gates); updates SPAR-07 wording.
+Per-invocation `--spar-gates` flag remains as the manual override path;
+rounds always defer to the skill default to avoid reintroducing
+FRAMEWORK-BUG-038.
+
+### What
+
+- **`SparConfig` schema delta** — three per-device fields land in
+  `.aperant/config.local.json` per AUDIT-001: `spar.enabled: boolean`,
+  `spar.partner: 'codex' | 'claude' | 'gemini' | null`, `spar.hint?: boolean`.
+  Added to `packages/framework/src/types/config.ts` as
+  `AperantConfig.spar?: SparConfig`. No migration path needed — spar lands
+  in `config.local.json` from day one with no shared-config legacy.
+
+- **`apt-setup` Sparring Auto-Fire (Batch 2)** — 3-phase question block
+  inserted after PR Review Auto-Suggest:
+  - Phase 1 (Yes/No): master switch.
+  - Phase 2 (partner picker, only if Yes): reads
+    `host.partner_transports.{codex,claude,gemini}` from
+    `apt-tools host-detect` to filter by availability, AND excludes
+    `host.cli` (Open Q1 same-host filter). Graceful skip with
+    `spar.enabled: true, spar.partner: null` when zero partners detected.
+  - Phase 3 (hint sub-picker, only if No): opt-in to per-stage reminder
+    `[apt] {stage} complete. /apt:spar available before next stage.`
+  All three fields route through `writeLocalConfigField` per AUDIT-001.
+
+- **`apt-run` flag + gate handlers** —
+  - `--spar-gates <plan|execute|plan,execute>` flag (per-invocation
+    override of merged-config consent). QUICK hard-rejects with verbatim
+    `[apt:run] --spar-gates ignored for QUICK track (Fast Path Guarantee)`.
+  - §3b "Stage 1.5 — Spar Gate (plan)": resolves effective gates, composes
+    topic frame from spec.md §Scope (task description fallback per
+    Open Q4), dispatches `/apt:spar --timeout-ms 120000 [--with <partner>]`
+    with NO `--rounds` flag (FRAMEWORK-BUG-038 regression guard).
+  - §4b "Stage 2.5 — Spar Gate (execute)": same logic, gate name
+    `"execute"`, topic frame from `build-progress.json`.
+  - Pipeline-mode `--timeout-ms 120000` (2-min Bash-rung fast-fail) is
+    asymmetric with manual mode (5min/15min defaults). Worst-case DEEP
+    wall budget: 2 gates × 3 rounds × 2 min = 12 min (vs ~90 min before
+    this clamp under MCP-rung partner degradation).
+  - §5 Verify spawn context: verifier reads Layer 2 spar findings
+    (`.aperant/spar/<slug>-<ts>.md`) before scoring.
+  - Per-stage `spar.hint` nudge at each of plan/execute/verify/review
+    Output: anchors (4 conditional prints, gated on
+    `spar.hint === true && spar.enabled === false`).
+
+- **`apt` router envelope contract (load-bearing AC11)** — `route.mjs`
+  emits two deterministic consent fields:
+  - `envelope.spar_inject_gates` (flag-override path): pre-computed gate
+    string `"plan"` (STANDARD) or `"plan,execute"` (DEEP) when consent on
+    AND user did NOT pass explicit `--spar-gates`. Absent for QUICK/DEBUG.
+  - `envelope.spar_consent` (host-LLM path): block
+    `{ enabled, partner, user_passed_explicit_gates }` when consent on.
+    Host model composes `--spar-gates` from spar_consent + chosen track.
+  Both fields ABSENT when consent off — envelope byte-equivalent to
+  pre-RFC shape for users who never opted in. `apt/SKILL.md` MODE: classify
+  Step 4 reads ONLY the envelope (never re-reads merged config from
+  prompt-space) — structural test grep-locks this invariant.
+
+- **`apt-plan` + `apt-execute` `--spar` flags** — end-of-process dispatch
+  to `/apt:spar` against local artifacts (spec.md / build-progress.json).
+  Same `--timeout-ms 120000` + no-rounds discipline. Per-skill manual
+  surface for users who don't use `/apt:run` end-to-end.
+
+- **`apt-spar/SKILL.md` SPAR-07 wording** — updated from v1
+  "manually invoked only" to v2 "honors install-time consent". §1-§9
+  process body is byte-equivalent to pre-edit baseline (sha256
+  9c2852ce…7da7b3 preserved by `apt-spar-pipeline-manual-path-preserved.test.ts`
+  hash guard). Manual `/apt:spar` invocation path UNCHANGED.
+
+### Why
+
+Founder usage data confirmed that cross-provider sparring surfaces
+blind-spot defects that single-provider review misses. SPAR-07's v1
+escape hatch was always deferred-pending-data; the data is in. Pipeline
+integration removes the per-task `--spar-gates` flag drudgery while
+preserving QUICK Fast Path Guarantee + manual override surfaces.
+
+### Compatibility
+
+- Backward-compatible. Users who never opt in to `spar.enabled: true`
+  see identical behavior to 0.8.2 — envelope shape byte-equivalent,
+  apt-run pipeline unchanged.
+- Manual `/apt:spar` invocation path BYTE-EQUIVALENT (process body
+  hash-locked).
+- `--spar-gates` flag is opt-in per-invocation. QUICK hard-rejects.
+- Migration: no path needed. Spar lands in `config.local.json` from day
+  one; no shared-config legacy.
+
+### Out of scope (follow-up RFC-001-b candidates)
+
+- Verify-stage spar gate (deferred — verify already iterates fix-and-retry).
+- Pre-ship spar gate (likely redundant with `/apt:pr-review`).
+- Multi-partner concurrent spar (use `/apt:roundtable` for 10-agent).
+- Re-plan-on-spar-cede behavioral feedback loop.
+- `--mcp-timeout-ms` per-invocation flag on `apt-spar` (Open Q5 —
+  MCP-rung pipeline tightening). Today MCP rung is config-only at
+  `apt-spar.mcp_timeout_ms`; pipeline mode accepts the asymmetry.
+
+### Version
+
+- `packages/framework/package.json`: 0.8.2 → 0.8.3
+
+### Commits
+
+- `4d67ca1d` feat(framework): add SparConfig schema for RFC-001 pipeline consent
+- `e301b776` feat(framework): apt-setup Sparring Auto-Fire prompt (RFC-001 install-time consent)
+- `20dea366` feat(framework): update SPAR-07 wording to v2 install-time consent contract
+- `3f9ef384` feat(framework): apt-run --spar-gates flag parsing + QUICK hard-reject
+- `be06429a` feat(framework): apt-run §3b + §4b spar-gate handlers
+- `36c7702d` feat(framework): emit spar_inject_gates + spar_consent envelope fields
+- `d803f8c5` feat(framework): apt router consent-driven --spar-gates auto-inject
+- `726ae3f5` feat(framework): apt-plan + apt-execute --spar per-skill flag
+- `e796580e` feat(framework): apt-run spar.hint nudge at stage success-ends
+
+## 0.8.2 — 2026-05-21 — Codex skill-discovery regression fix
+
+Codex skill-discovery regression fix — install now writes to the
+documented `.agents/skills/<folder>/SKILL.md` surface.
+
+### Fixed
+
+- Codex `installRoot` re-targeted from `.codex` to `.agents` so SKILL.md
+  lands at `<targetDir>/.agents/skills/<folder>/SKILL.md` per
+  https://developers.openai.com/codex/skills. The previous v0.7/v0.8
+  `.codex/agents/` + `.codex/commands/` topology was a dead surface
+  (Codex CLI 0.132.0 doesn't discover skills there) and a fresh
+  `apt-tools init . --codex` reported 95 files installed while
+  `codex debug prompt-input` listed zero apt-* skills.
+- Codex frontmatter strip switched from a 2-key blacklist
+  (`['tools', 'color']`) to an allowed_properties whitelist
+  (`KEEP = ['name', 'description']`), matching
+  `~/.codex/skills/.system/skill-creator/scripts/quick_validate.py:40`
+  and the working third-party skill examples. Drift-proof: any new
+  framework frontmatter key is dropped from Codex output without
+  breaking the validator.
+- Codex transform now emits a single output (`skills/<folder>/SKILL.md`)
+  per canonical skill. The previous two-output emission
+  (`agents/<folder>.md` + `commands/<folder>.md`) is dropped along with
+  the `fileType === 'agent'` branch (markdown agents are not a Codex
+  surface; Codex custom-agents are TOML under `.codex/agents/`).
+- `runLegacyCleanup` now GCs the v0.7/v0.8 `.codex/agents/apt-*.md` +
+  `.codex/commands/apt-*.md` + `.codex/apt-file-manifest.json` misdirect
+  on the next `apt-tools init . --codex`. `.codex/config.toml` and any
+  user-added `.codex/` content is preserved.
+
+### Changed
+
+- `getTrustedSkillSources` now skips the Codex install root in the
+  per-cli filter (`cli !== 'codex'` guard). Keeps
+  `.aperant/logs/route-dropped.jsonl` clean for router invocations on
+  Codex hosts — Codex's stripped frontmatter would otherwise fail
+  `SkillFrontmatterSchema`. Canonical + kernel roots still serve
+  routing.
+- `LEGACY_INSTALL_PATHS` schema gains a `honor_manifest?: boolean`
+  field (default `true`). When `false`, a present
+  `apt-file-manifest.json` at the legacy root does NOT trigger the
+  managed-no-op — used for known-dead surfaces like the v0.7/v0.8
+  codex misdirect. Existing legacy entries are unaffected (default true
+  preserves the managed-install safety).
+
+### Version
+
+- `packages/framework/package.json`: 0.8.1 → 0.8.2
 
 ## 0.8.1 — 2026-05-20 — Pi runtime + idempotent re-init repair
 

package/agents/apt-planner.md

@@ -32,7 +32,8 @@ Before planning, discover project context:
 <environment>
 - **Working directory:** The project root
 - **apt-tools:** Always invoke as `node packages/framework/bin/apt-tools.mjs`
-- **Task directory:** Provided in the spawn prompt as `task_dir`. ALL artifacts (spec.md, implementation_plan.json) are written here, NOT to project root.
+- **Task directory:** Provided in the spawn prompt as `task_dir`. It MUST be an absolute path under the main repo's `.aperant/tasks/{task-id}/`. ALL artifacts (spec.md, implementation_plan.json) are written here, NOT to project root and NOT to a worktree-local `.aperant/tasks/` directory.
+- **Worktree path:** If provided, use it only for code investigation/editing context. Do not derive artifact paths from it.
 - **Config:** `.aperant/config.json` — project preferences
 - **State:** `.aperant/state.json` — execution state
 </environment>
@@ -43,7 +44,7 @@ Before planning, discover project context:
 
 1. Read `CLAUDE.md` and `AGENTS.md` if they exist — extract conventions, stack, constraints
 2. Run `node packages/framework/bin/apt-tools.mjs state .` to understand current project state
-3. Parse the task description and task_dir from the spawn prompt
+3. Parse the task description and task_dir from the spawn prompt. If task_dir is relative, resolve the real main repo path first instead of writing under the current worktree.
 
 ## 2. Assess Complexity
 
@@ -211,7 +212,7 @@ If unable to enumerate (network unavailable, action docs unclear), flag it expli
 
 ## 4. Write Specification
 
-The spec.md content format **branches on track** (Pocock adoption ID-05,
+The spec.md content format **branches on track** (ID-05,
 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.
@@ -239,6 +240,11 @@ survives the task as a second-consumer document.
 
 ### 4.B. STANDARD / DEEP / COMPLEX — PRD-shaped spec.md
 
+**Three orthogonal user-facing sections — keep them distinct.** User
+Stories (motivation prose), User Outcomes (verify-proof input contract),
+and Acceptance Criteria (code-level invariants) serve distinct
+purposes. Do NOT collapse them — STANDARD/DEEP specs carry all three.
+
 ```markdown
 # Spec: {task title}
 
@@ -256,6 +262,22 @@ survives the task as a second-consumer document.
 {One **US-NN (persona).** story per user-value slice. Stories map 1:1
 onto subtasks in implementation_plan.json.}
 
+## User Outcomes
+{Verify-proof input contract. One bolded `**Epic:**` headline + N
+atomic outcomes. Authors write the LITERAL string `**ON**` — IDs are
+POSITIONAL and synthesized by the parser (first row becomes O1, second
+O2, ...). Closed surface set: `electron | web | cli | api | electron+web`.
+Optional cross-refs via `*(requires ON N)*`. Refactor-only specs MAY
+use the empty-with-note escape (verbatim string,
+italic underscores + em dash + period required):}
+
+`_No user-observable changes — pure refactor._`
+
+**Epic:** {one-sentence user-facing capability headline}
+
+- **ON** [surface]: {user does X; system shows/does Y}
+- **ON** [surface]: {user does X; system shows/does Y} *(requires ON 1)*
+
 ## Implementation Decisions
 {Load-bearing principles carried into every subtask. Format:
 "### ID-NN: {title}" + rationale + practical consequence.}
@@ -278,9 +300,19 @@ reference these IDs via the per-subtask `acceptance_criteria` field.}
 ```
 
 **PRD section ordering is load-bearing.** `apt-tools coverage-check
-validate` greps `## Acceptance Criteria`; `apt-tools consistency check`
-greps `## Solution` and `## User Stories`. Renaming or reordering these
-sections breaks downstream tooling and the C15 consistency rules.
+validate` greps `## Acceptance Criteria` AND `## User Outcomes`;
+`apt-tools consistency check` greps `## Solution` and `## User Stories`.
+Renaming or reordering these sections breaks downstream tooling and the
+C15 consistency rules.
+
+**`## User Outcomes` synthesis directive.** Outcomes are
+user-observable (a user does X; the system shows/does Y); Acceptance
+Criteria are code-level invariants (a function returns X; a config key
+exists). Do NOT collapse them — they parse through different gates and
+serve different consumers. STANDARD/DEEP specs carry both sections in
+parallel. IDs are POSITIONAL: the parser counts outcome rows in
+document order and synthesizes `O1`, `O2`, ... — authors MUST write
+the literal `**ON**` token, never `**O1**`/`**O2**`.
 
 **Do NOT interview the user.** The PRD is synthesized from the task
 description + codebase investigation + AGENTS.md, not from a clarifying
@@ -344,7 +376,7 @@ fix it now, not later.
 
 ## 5. Create Implementation Plan
 
-Subtask schema branches on track (Pocock adoption ID-05 — Fast Path Guarantee).
+Subtask schema branches on track.
 
 ### 5.A. QUICK track / SIMPLE complexity — legacy flat subtask schema
 

package/dist/cli/commands/adr.mjs

@@ -1,5 +1,5 @@
 /**
- * commands/adr.mjs — `apt-tools adr write` (Pocock adoption ST-6, AC5).
+ * commands/adr.mjs — `apt-tools adr write`.
  *
  * Writes an ADR under `docs/adr/NNNN-slug.md` ONLY when all three Nygard
  * gates pass: hard-to-reverse AND surprising-without-context AND

package/dist/cli/commands/audit-branch-current.d.mts

@@ -0,0 +1,25 @@
+/**
+ * @param {string} projectDir
+ * @param {string[]} extraArgs
+ */
+export function auditBranchCurrent(projectDir: string, extraArgs?: string[]): import("../util/result.mjs").CommandResult;
+export { parseConflictPaths as __parseConflictPathsForTests };
+/**
+ * Parse `git merge-tree --write-tree --no-messages HEAD origin/<base>` output
+ * for conflict file paths. Modern (git ≥ 2.38) merge-tree emits, on conflict:
+ *
+ *   <tree-OID>
+ *   <conflict report lines, each "<mode> <stage> <oid>\t<path>" for stage > 0>
+ *   (NUL separator)
+ *   <textual conflict messages>
+ *
+ * Older variants emit a `+<<<<<<< ... +======= ... +>>>>>>>` diff per file.
+ * For correctness we use the stable form: extract file paths from the conflict
+ * report. The report includes the SAME path multiple times (once per non-zero
+ * stage), so we de-dupe.
+ *
+ * @param {string} stdout
+ * @returns {string[]}
+ */
+declare function parseConflictPaths(stdout: string): string[];
+//# sourceMappingURL=audit-branch-current.d.mts.map

package/dist/cli/commands/audit-branch-current.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-branch-current.d.mts","sourceRoot":"","sources":["../../../src/cli/commands/audit-branch-current.mjs"],"names":[],"mappings":"AAmIA;;;GAGG;AACH,+CAHW,MAAM,cACN,MAAM,EAAE,8CAgHlB;;AAtKD;;;;;;;;;;;;;;;;GAgBG;AACH,4CAHW,MAAM,GACJ,MAAM,EAAE,CAsBpB"}