@aperant/framework 0.8.7 → 0.10.0

package/CHANGELOG.md

@@ -3,6 +3,148 @@
 All notable changes to `@aperant/framework` are documented here. See
 [`VERSIONING.md`](VERSIONING.md) for the per-tier contract.
 
+## Unreleased
+
+## 0.10.0 — 2026-05-26 — Tauri driver + MCP auto-provision
+
+Adds a bundled Tauri verify-proof driver and install-time auto-provisioning
+of the MCP transport each driver needs, so `/apt:verify-proof` works out of
+the box for Tauri (and web) projects with no manual MCP setup.
+
+### Added
+
+- **Bundled `tauri` verify-proof driver** (`drivers/tauri/`). Same 10-verb
+  IDL adapter-shim surface as the electron driver, `transport.mcp_server_id
+  "tauri"`, `priority 85` (below electron's 90 — Tauri is rarer), `ga`. The
+  verb→tool mapping (the `tauri-plugin-mcp-server` tool surface) lives ONLY
+  in the driver + its README (ID-01) — zero workflow-prose edits; a grep
+  guard pins the no-`mcp__tauri__*`-in-workflow invariant. The resolver
+  already understood `is_tauri`, so it selects the new driver with zero
+  resolver edits. The app-side `tauri-plugin-mcp` Rust plugin + `tauri dev
+  --features mcp-debug` is a documented PREREQUISITE, never installed by the
+  framework.
+- **Install-time MCP/skill auto-provisioning** (`apt-tools init`, and
+  `/apt:update` via the same path). Detects the project runtime and, per
+  SELECTED host CLI, writes the matching transport TOFU/non-clobbering:
+  - claude → JSON-merge the MCP server into project-root `.mcp.json`
+    (`mcpServers.<id>`).
+  - codex → upsert a `[mcp_servers.<id>]` table into project-root
+    `.codex/config.toml` (dependency-free minimal TOML writer).
+  - electron / tauri projects get the matching MCP server (tauri via a
+    generated `scripts/tauri-mcp.sh` launcher, since its npm bin ships
+    without a shebang); web frontends get the browser driver's declared
+    `agent-browser` skill copied into each host skill dir
+    (`.claude/skills/`, `.agents/skills/`) — NOT a puppeteer MCP server.
+  A pre-existing server id, config table, skill file, or launcher is never
+  overwritten (protects a hand-authored `SCREENSHOT_ENCRYPTION_KEY` and a
+  user-edited skill). Each action is audited to
+  `.aperant/events/{date}.jsonl`. Opt out with `verification.provision_mcp:
+  false` (default `true`). v1 host writers: claude + codex.
+
+### Out of scope (documented)
+
+- The Rust/Tauri app-side plugin (`tauri-plugin-mcp`) — a project prereq.
+- Puppeteer MCP server provisioning — web projects get the `agent-browser`
+  skill instead; the browser driver manifest's `mcp_server_id` is untouched.
+- The `agent-browser` CLI binary, and generating/persisting
+  `SCREENSHOT_ENCRYPTION_KEY` — both documented prereqs, not auto-provisioned.
+
+## 0.9.1 — 2026-05-25 — G42 Phase 1: close deferred ship/merge bypass
+
+**Breaking (behavior):** Blocking review findings tagged `deferred` no longer
+silently clear the ship gate. Only `status: "fixed"` clears a `critical` or
+`major` finding. The `--force --reason "<why>"` override (audit-logged to
+`.aperant/events/`) remains the sole intentional bypass.
+
+### Fixed
+
+- **`review-clean` gate now blocks `critical`/`major` findings tagged `deferred`.** Previously,
+  tagging a blocking finding `deferred` (any variant: `deferred`, `deferred-per-spec`,
+  `deferred-followup`, `deferred-out-of-scope`) silently cleared the ship gate, allowing a
+  critical safety defect to ship as ✓MERGED. The gate now only accepts `status: "fixed"` as a
+  clearing condition for blocking severities. A deliberate override is still possible via
+  `--force --reason "<why>"` (audit-logged). (G42 Phase 1)
+- **`r5-verdict-consistency` rule no longer exempts `approved-with-notes` verdict from blocking
+  finding check.** `approved-with-notes` was previously an explicit escape hatch that passed R5
+  regardless of unresolved criticals. It now fails R5 when any unresolved `critical` or `major`
+  finding exists. The check also extends to `major` severity (previously only `critical` was
+  checked). (G42 Phase 1)
+- **`apt-verify` completeness carve-out adds severity floor.** The verifier no longer exempts a
+  `critical` or `major` deferred behavior from Completeness scoring — such findings are now
+  treated as a Completeness gap. (G42 Phase 1)
+- **`apt-verifier` agent instruction updated.** The verifier agent doc no longer instructs agents
+  to use `approved-with-notes` as an escape hatch for unresolved critical/major review findings;
+  the sole bypass is the audited `--force --reason` gate override. (G42 Phase 1)
+- **`init` stamps the APT block into every selected runtime's instruction
+  file.** Previously init picked exactly ONE instruction file (CLAUDE.md if
+  present, else AGENTS.md) regardless of which runtimes were selected, so a
+  `--claude --codex` user got the skill catalog in CLAUDE.md only and native
+  Codex (which reads AGENTS.md) never saw it; `--gemini` users never got a
+  GEMINI.md block at all. `RuntimeDescriptor` now carries a nullable
+  `nativeInstructionFile` (claude → CLAUDE.md, codex/opencode → AGENTS.md,
+  gemini → GEMINI.md; the other 11 runtimes install to their own surface and
+  map to `null`). init resolves the deduplicated target set from the selected
+  runtimes, runs an all-target foreign-row preflight (any offending target →
+  exit 2, NOTHING written), then writes every target. The result envelope gains
+  a plural `instructionFiles[]` array; the singular `instructionFile` stays as a
+  backwards-compat alias = first entry. The single-runtime fallback is
+  preserved: `--claude` against a project with a pre-existing AGENTS.md (and no
+  CLAUDE.md) still writes AGENTS.md.
+- **`uninstall` strips the APT block from GEMINI.md too.** `INSTRUCTION_FILES`
+  expanded to `['CLAUDE.md', 'AGENTS.md', 'GEMINI.md']` so a `--gemini` install
+  no longer leaves a stale managed block behind.
+- **The chat-agent instruction loader dedupes identical APT blocks.**
+  `loadInstructionFiles` (packages/core) now loads a given verbatim
+  `<!-- APT:framework-* -->` block once even when it appears in multiple walk-up
+  files (the post-fix normal state for multi-runtime users) — preventing the
+  skill catalog from rendering twice in the system prompt. Narrow: only
+  identical managed blocks are deduped; non-managed content and distinct blocks
+  are preserved.
+
+## 0.9.0 — 2026-05-25 — github-issues triage backend
+
+Replaces the v1 `github-issues` triage stub with a working `gh`-CLI adapter,
+so projects on `task_tracking.backend: "github-issues"` get real GitHub
+issues synced to triage state.
+
+### Added
+
+- **`github-issues` triage backend is now implemented.** The first triage
+  mirror CREATES a GitHub issue via `gh issue create` (`triage: <task-id>`,
+  labelled `<category>` + `<vocab>:<state>`); subsequent transitions UPDATE
+  the SAME issue (`gh issue edit` label swap); a transition to `wontfix`
+  CLOSES it as "not planned" (`gh issue close --reason "not planned"`). The
+  issue pointer (`github.{issue_number, issue_url, repo}`) persists on
+  `triage.json`, so transitions are idempotent — no duplicate issues. Honors
+  `task_tracking.tracker_label_vocabulary` (absent/`"default"` →
+  `triage:<state>`; otherwise `<vocab>:<state>`). Transport is the `gh` CLI
+  via `execFileSync` arg-arrays (no shell-string interpolation), inheriting
+  the user's existing `gh auth` — zero new credential plumbing. When `gh` is
+  missing / unauthenticated / there is no resolvable git remote, the adapter
+  returns a structured error (`reason: gh-unavailable | gh-unauthenticated |
+  no-remote | gh-command-failed`) and exits non-zero — never a crash or
+  stacktrace. Label operations are best-effort: an unknown label degrades to
+  a `warnings[]` entry while the open/closed state change still lands. A
+  deterministic `APT_TRIAGE_GH_FIXTURE` test hook (mirroring `pr-review.mjs`'s
+  `APT_GH_FIXTURE_JSON`) keeps the unit tests hermetic — no real network.
+  The `app-inbox` backend remains a not-implemented stub (out of scope,
+  post-app-launch).
+
+### Changed
+
+- **`## User Outcomes` coverage gate is now a HARD BLOCK (cutover from the
+  0.8.x warn-only grace window).** As telegraphed in the 0.8.6 release notes
+  ("v0.9.0 will **HARD BLOCK** specs that [lack `## User Outcomes`]"), the
+  `coverage-check` gate flips from `warn` to `block` for STANDARD/DEEP plans
+  whose spec is missing the `## User Outcomes` section, starting this 0.9.0
+  release. The version-gated logic already lived in
+  `userOutcomesGateResult` (warn in 0.8.x, block in 0.9.0+); bumping the
+  kernel to 0.9.0 activates it. Refactor-only specs use the
+  `_No user-observable changes — pure refactor._` empty-with-note escape to
+  pass. QUICK-track tasks remain exempt (Fast Path Guarantee). The
+  `migration_deadline` advisory note (only emitted during the warn window) is
+  no longer surfaced — the deadline has passed.
+
 ## 0.8.7 — 2026-05-24 — Codex parity: drift false-positive fix + agent inlining
 
 Brings the Codex runtime to parity with Claude Code on two fronts.

package/agents/apt-pr-review-fixer.md

@@ -71,9 +71,14 @@ The only valid reasons to skip a finding:
 
 ## Coordination Protocol
 
-When `[PARALLEL_FIXERS]` is true, multiple fix agents work in parallel on different file groups.
-
-1. **Only edit files in your `[FIX_ASSIGNMENT]`** — do NOT touch files assigned to other fixers
+**Fixers run SEQUENTIALLY, never concurrently (FRAMEWORK-BUG-006).** At most one fixer touches the
+shared worktree at any moment — the orchestrator spawns fixer-1, waits for it to return and audits it,
+THEN spawns fixer-2, and so on. You are the ONLY fixer touching this worktree right now. `[PARALLEL_FIXERS]`
+is always `false`; do NOT assume a sibling fixer is editing, staging, or committing at the same time.
+Concurrent `git add`/`git commit` against a shared index either sweeps another fixer's staged files
+into your commit or clobbers their working-tree edits — which is exactly the race this rule prevents.
+
+1. **Only edit files in your `[FIX_ASSIGNMENT]`** — do NOT touch files outside your assigned group (the grouping keeps fixes scoped and the history clean)
 2. **If a finding spans files across groups** — fix only the parts in your group, note the cross-group dependency in your report
 3. **If you discover NEW issues** while fixing — note them in your report but do NOT fix them (they aren't validated)
 
@@ -89,7 +94,7 @@ Findings with severity `critical`:
 
 ## Report Format
 
-Write to `[REVIEW_DIR]/iterations/[N]/fixes-applied-[FIXER_NAME].md` (BUG-030 canonical naming — the audit gate resolves `fixes-applied-${FIXER_NAME}.md` ahead of the legacy `fixes-applied.md`, so parallel fixers no longer collide on a shared report path):
+Write to `[REVIEW_DIR]/iterations/[N]/fixes-applied-[FIXER_NAME].md` (BUG-030 canonical naming — the audit gate resolves `fixes-applied-${FIXER_NAME}.md` ahead of the legacy `fixes-applied.md`. Each fixer owns its own report file; this per-fixer path stays correct now that fixers run sequentially — FRAMEWORK-BUG-006):
 
 ```markdown
 # Fix Report — Iteration [N]

package/agents/apt-verifier.md

@@ -105,9 +105,12 @@ Either shape is accepted:
 
 Gate G8 (`consistency-check`) enforces this on ship via rules R4
 (finding-propagation) and R5 (verdict-consistency):
-- `verdict: "approved"` is incompatible with any unresolved `critical`
-  review finding — use `approved-with-notes` as the escape hatch when you
-  intentionally ship over a flagged finding, and cite it in `findings.notes`.
+- `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: "rejected"` requires at least one cited finding (rejected
   without evidence is treated as drift).
 

package/dist/cli/commands/init.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.mts","sourceRoot":"","sources":["../../../src/cli/commands/init.mjs"],"names":[],"mappings":"AA4EA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wCAHW,MAAM,EAAE,GACN;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,iBAAiB,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,GAAC,IAAI,CAAC;IAAC,WAAW,EAAE,OAAO,CAAC;IAAC,aAAa,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,GAAC,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,CAAC,GAAC,CAAC,GAAC,CAAC,GAAC,CAAC,CAAC;IAAC,mBAAmB,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,OAAO,CAAC;IAAC,aAAa,EAAE,OAAO,CAAC;IAAC,qBAAqB,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAmE1S;AAwzBD;;;;;;;GAOG;AACH,8CAHW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,WACnB,cAAc,0BAoDxB;AAoED;;;;;;GAMG;AACH,oCAJW,MAAM,cACN,MAAM,EAAE,GACN,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA+L3D;;;;;cAtnCa,MAAM,EAAE;;;;qBACR,CAAC,GAAC,CAAC,GAAC,CAAC,GAAC,CAAC;;;;gBACP,MAAM,GAAC,MAAM;;;;4BACb,MAAM,EAAE;;;;aACR,OAAO;;;;mBACP,OAAO;eACP,OAAO,0BAA0B,EAAE,eAAe;;;;;;;;;aAErC,MAAM;eAAS,OAAO;cAAQ,MAAM;iBAAW,MAAM;;;;;;aAErD,MAAM;eAAS,OAAO;gBAAU,MAAM;;;;;;kBAEvC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;0BAAoB,OAAO,EAAE;2BAAqB,OAAO,EAAE;oBAAc,OAAO,EAAE"}
+{"version":3,"file":"init.d.mts","sourceRoot":"","sources":["../../../src/cli/commands/init.mjs"],"names":[],"mappings":"AA8EA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wCAHW,MAAM,EAAE,GACN;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,iBAAiB,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,GAAC,IAAI,CAAC;IAAC,WAAW,EAAE,OAAO,CAAC;IAAC,aAAa,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,GAAC,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,CAAC,GAAC,CAAC,GAAC,CAAC,GAAC,CAAC,CAAC;IAAC,mBAAmB,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,OAAO,CAAC;IAAC,aAAa,EAAE,OAAO,CAAC;IAAC,qBAAqB,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAmE1S;AAwzBD;;;;;;;GAOG;AACH,8CAHW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,WACnB,cAAc,0BAoDxB;AAoED;;;;;;GAMG;AACH,oCAJW,MAAM,cACN,MAAM,EAAE,GACN,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAgN3D;;;;;cAvoCa,MAAM,EAAE;;;;qBACR,CAAC,GAAC,CAAC,GAAC,CAAC,GAAC,CAAC;;;;gBACP,MAAM,GAAC,MAAM;;;;4BACb,MAAM,EAAE;;;;aACR,OAAO;;;;mBACP,OAAO;eACP,OAAO,0BAA0B,EAAE,eAAe;;;;;;;;;aAErC,MAAM;eAAS,OAAO;cAAQ,MAAM;iBAAW,MAAM;;;;;;aAErD,MAAM;eAAS,OAAO;gBAAU,MAAM;;;;;;kBAEvC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;0BAAoB,OAAO,EAAE;2BAAqB,OAAO,EAAE;oBAAc,OAAO,EAAE"}

package/dist/cli/commands/init.mjs

@@ -22,7 +22,7 @@ import { fileURLToPath } from 'node:url';
 import { detectMode } from '../bootstrap/detect-mode.mjs';
 import { deriveSidecar } from '../bootstrap/product-context-sidecar.mjs';
 import { assertConfigWriteAllowed } from '../config/guard.mjs';
-import { AUDIT_001_LOCAL_FIELDS, migrateDeferredFieldsToLocalConfig, writeLocalConfigField, } from '../config/load.mjs';
+import { AUDIT_001_LOCAL_FIELDS, loadMergedProjectConfig, migrateDeferredFieldsToLocalConfig, writeLocalConfigField, } from '../config/load.mjs';
 import { migrateConfigSchema, setAt } from '../config/schema-migrate.mjs';
 import { resolveSharePolicy } from '../config/share-policy.mjs';
 import { buildAperantGitignoreTemplate } from '../config/upgrade-gitignore.mjs';
@@ -30,6 +30,7 @@ import { detectPublicRemote } from '../git/remote.mjs';
 import { detectArchetype } from '../install/archetype.mjs';
 import { installKernel } from '../install/install-kernel.mjs';
 import { MANIFEST_FILENAME } from '../install/manifest.mjs';
+import { provisionMcpConfig } from '../install/mcp-provision.mjs';
 import { discoverCanonicalFiles, runInstall, writeLastInstallSummary, } from '../install/pipeline.mjs';
 import { getRuntime, RUNTIMES, suggestRuntimes } from '../install/runtime-detect.mjs';
 import { runLegacyCleanup } from '../install/runtime-migrate.mjs';
@@ -38,7 +39,7 @@ import { detectAgentRuntime } from '../util/agent-runtime.mjs';
 import { buildAptSection } from '../util/aperant-section.mjs';
 import { atomicWriteJson } from '../util/atomic-write.mjs';
 import { aperantBanner } from '../util/banner.mjs';
-import { copyDirRecursive, injectInstructionFile } from '../util/copy.mjs';
+import { checkInstructionFile, copyDirRecursive, injectInstructionFile } from '../util/copy.mjs';
 import { withFileLock } from '../util/fs-lock.mjs';
 import { emitInitConfigHint } from '../util/init-hints.mjs';
 import { err, exitWith, ok, rawText } from '../util/result.mjs';
@@ -1183,6 +1184,21 @@ export async function cmdInit(projectDir, extraArgs = []) {
         if (envelope?.__earlyExit) {
             return envelope.__earlyExit;
         }
+        // Auto-provision host MCP-server config + the agent-browser skill for
+        // the detected runtime (C38). Runs on BOTH the fresh install AND the
+        // no-drift /apt:update upgrade path (both reach finishInit). finishInit
+        // has already written .aperant/config.json from the template, so the
+        // merged config carries verification.provision_mcp (default true) — the
+        // opt-out gate. TOFU/non-clobbering; never throws.
+        const mergedConfig = loadMergedProjectConfig(installTarget);
+        const mcpProvision = provisionMcpConfig({
+            targetDir: installTarget,
+            selectedRuntimes: effectiveAnswers.runtimes,
+            config: mergedConfig,
+            frameworkRoot: canonicalRoot,
+            version,
+        });
+        envelope.mcp_provision = mcpProvision;
         if (interactiveTty) {
             await renderOutro(effectiveAnswers, results, version, kernelResult);
             // TTY mode: envelope was persisted to disk + suppressed from stdout
@@ -1325,6 +1341,69 @@ async function renderOutro(answers, results, version, kernelResult) {
     clack.note('Relaunch Claude Code / Codex / your AI CLI in this directory\nso the new .claude/ + .codex/ surfaces are picked up.', 'Activate');
     clack.outro(`Installed ${fileCount} files · v${version} · ${xverifyCopy}`);
 }
+/**
+ * Resolve the deduplicated set of root instruction-file paths the selected
+ * runtimes read. Each chosen runtime contributes its `nativeInstructionFile`
+ * (claude→CLAUDE.md, codex/opencode→AGENTS.md, gemini→GEMINI.md); runtimes
+ * mapped to `null` install to their own surface and contribute nothing.
+ * Filenames are deduplicated (codex + opencode both map to AGENTS.md → one
+ * target).
+ *
+ * Resolution rules:
+ *   - Multiple distinct targets (e.g. `--claude --codex`): write all of them
+ *     verbatim — that is the whole point of the fix (AC1, AC2, AC5).
+ *   - Exactly one resolved target that does NOT exist AND it is CLAUDE.md, but
+ *     AGENTS.md already exists (the `--claude` with a pre-seeded AGENTS.md and
+ *     no CLAUDE.md case, Risk 4 / AC9): redirect to the existing AGENTS.md
+ *     rather than creating an orphan CLAUDE.md. This is safe ONLY for the
+ *     claude runtime because native Claude Code reads AGENTS.md as well as
+ *     CLAUDE.md. The redirect is NOT applied for gemini (reads only GEMINI.md)
+ *     or codex/opencode (read only AGENTS.md) — redirecting those to an
+ *     unrelated existing file would reintroduce the very visibility gap this
+ *     fix closes, so their absent target is simply created.
+ *   - Zero resolved targets (no selected runtime maps to an instruction file):
+ *     fall back to the legacy heuristic — CLAUDE.md if present, else AGENTS.md
+ *     if present, else a new CLAUDE.md.
+ *
+ * @param {string[]} chosenIds
+ * @param {string} targetDir
+ * @returns {string[]} absolute instruction-file paths, deduplicated
+ */
+function resolveInstructionTargets(chosenIds, targetDir) {
+    const filenames = [];
+    for (const id of chosenIds) {
+        const runtime = getRuntime(id);
+        const file = runtime?.nativeInstructionFile;
+        if (file && !filenames.includes(file))
+            filenames.push(file);
+    }
+    const claudeMdPath = join(targetDir, 'CLAUDE.md');
+    const agentsMdPath = join(targetDir, 'AGENTS.md');
+    const resolved = filenames.map((name) => join(targetDir, name));
+    if (resolved.length === 0) {
+        // No selected runtime maps to an instruction file — legacy heuristic.
+        if (existsSync(claudeMdPath))
+            return [claudeMdPath];
+        if (existsSync(agentsMdPath))
+            return [agentsMdPath];
+        return [claudeMdPath];
+    }
+    if (resolved.length === 1 && !existsSync(resolved[0])) {
+        // Single registry target that doesn't exist yet. The ONLY safe redirect
+        // is claude→AGENTS.md (Risk 4 / AC9): native Claude Code reads AGENTS.md
+        // too, so when CLAUDE.md is absent but AGENTS.md exists (e.g. a prior
+        // codex install), writing AGENTS.md still serves claude and avoids an
+        // orphan CLAUDE.md. gemini/codex/opencode read only their own native
+        // file — redirecting them to an unrelated existing file would hide the
+        // catalog from their CLI, so we just create their target.
+        if (resolved[0] === claudeMdPath && existsSync(agentsMdPath))
+            return [agentsMdPath];
+        return resolved;
+    }
+    // One or more registry targets, at least one exists OR multiple distinct
+    // targets — write the registry-resolved set verbatim.
+    return resolved;
+}
 /**
  * Synchronous tail of init — runs after the runtime-install promise
  * resolves. Performs all .aperant/ + Claude-hook + remote-warning work
@@ -1488,18 +1567,19 @@ function finishInit(targetDir, installTarget, canonicalRoot, version, chosenIds,
     if (existsSync(installedContextSrc)) {
         copyDirRecursive(installedContextSrc, join(aperantDir, 'context', 'installed'));
     }
-    const claudeMdPath = join(targetDir, 'CLAUDE.md');
-    const agentsMdPath = join(targetDir, 'AGENTS.md');
-    let instructionFile;
-    if (existsSync(claudeMdPath))
-        instructionFile = claudeMdPath;
-    else if (existsSync(agentsMdPath))
-        instructionFile = agentsMdPath;
-    else
-        instructionFile = claudeMdPath;
+    // Resolve every distinct instruction file the selected runtimes read, then
+    // preflight ALL of them before writing ANY — so a single foreign-row abort
+    // leaves no file partially written (US-03 / AC3). Each chosen runtime maps
+    // to its `nativeInstructionFile` (claude→CLAUDE.md, codex/opencode→AGENTS.md,
+    // gemini→GEMINI.md); null-mapped runtimes install to their own surface and
+    // contribute no target. When the selected runtimes resolve to zero targets,
+    // or none of the resolved targets exist on disk, fall back to the legacy
+    // "pick the existing file" heuristic so e.g. `--claude` with a pre-seeded
+    // AGENTS.md (and no CLAUDE.md) still writes AGENTS.md (Risk 4 / AC9).
+    const instructionTargets = resolveInstructionTargets(chosenIds, targetDir);
     // FRAMEWORK-BUG-023 — generate the section from discoverSkills before
     // handing it to the writer. The writer also runs a foreign-row defensive
-    // check; if rows present in the file aren't in the generated set we
+    // check; if rows present in any file aren't in the generated set we
     // signal exit-2 via the __earlyExit sentinel so cmdInit can route the
     // envelope through exitWith() without writing a malformed install.
     const aptSection = buildAptSection({
@@ -1507,26 +1587,75 @@ function finishInit(targetDir, installTarget, canonicalRoot, version, chosenIds,
         targetDir,
         cli: detectAgentRuntime(),
     });
-    const injectionOutcome = injectInstructionFile(instructionFile, {
-        aptSection,
-        force: forceOverwriteCatalog,
+    // Preflight pass — check every target with the write-free helper; collect
+    // all aborting targets so the error lists every offender, not just the first.
+    const abortingTargets = [];
+    for (const filePath of instructionTargets) {
+        const check = checkInstructionFile(filePath, { aptSection, force: forceOverwriteCatalog });
+        if (check.status === 'aborted-foreign-rows') {
+            abortingTargets.push({ path: basename(filePath), foreignRowIds: check.foreignRowIds });
+        }
+    }
+    if (abortingTargets.length > 0) {
+        const allForeignRowIds = [...new Set(abortingTargets.flatMap((t) => t.foreignRowIds))];
+        const fileList = abortingTargets.map((t) => t.path).join(', ');
+        return {
+            __earlyExit: exitWith({
+                ok: false,
+                status: 'error',
+                command: 'init',
+                code: 'instruction-file.foreign-rows',
+                message: `${fileList} contains skill rows not present in the installed framework: ` +
+                    `${allForeignRowIds.join(', ')}. ` +
+                    'Re-run with --force-overwrite-catalog to regenerate anyway, or remove the foreign rows manually.',
+                foreignRowIds: allForeignRowIds,
+                instructionFile: { path: abortingTargets[0].path, status: 'aborted-foreign-rows' },
+                instructionFiles: abortingTargets.map((t) => ({
+                    path: t.path,
+                    status: 'aborted-foreign-rows',
+                })),
+            }, 2),
+        };
+    }
+    // Write pass — no target aborted in the preflight, so write all.
+    const instructionFiles = instructionTargets.map((filePath) => {
+        const outcome = injectInstructionFile(filePath, {
+            aptSection,
+            force: forceOverwriteCatalog,
+        });
+        return {
+            path: basename(filePath),
+            status: outcome.status,
+            foreignRowIds: outcome.foreignRowIds,
+        };
     });
-    if (injectionOutcome.status === 'aborted-foreign-rows') {
+    // TOCTOU guard: if a file gained foreign rows BETWEEN the preflight check and
+    // the write (e.g. another process wrote to it), surface the same error envelope
+    // the preflight uses rather than silently accepting partial writes.
+    const writtenAborts = instructionFiles.filter((f) => f.status === 'aborted-foreign-rows');
+    if (writtenAborts.length > 0) {
+        const allForeignRowIds = [...new Set(writtenAborts.flatMap((f) => f.foreignRowIds ?? []))];
+        const fileList = writtenAborts.map((f) => f.path).join(', ');
         return {
             __earlyExit: exitWith({
                 ok: false,
                 status: 'error',
                 command: 'init',
                 code: 'instruction-file.foreign-rows',
-                message: `${basename(instructionFile)} contains skill rows not present in the installed framework: ` +
-                    `${injectionOutcome.foreignRowIds.join(', ')}. ` +
+                message: `${fileList} contains skill rows not present in the installed framework: ` +
+                    `${allForeignRowIds.join(', ')}. ` +
                     'Re-run with --force-overwrite-catalog to regenerate anyway, or remove the foreign rows manually.',
-                foreignRowIds: injectionOutcome.foreignRowIds,
-                instructionFile: basename(instructionFile),
+                foreignRowIds: allForeignRowIds,
+                instructionFile: { path: writtenAborts[0].path, status: 'aborted-foreign-rows' },
+                instructionFiles: writtenAborts.map((f) => ({
+                    path: f.path,
+                    status: 'aborted-foreign-rows',
+                })),
             }, 2),
         };
     }
-    const injectionResult = injectionOutcome.status;
+    // Primary entry drives the backwards-compat singular alias + structure key.
+    const primaryInstructionFile = instructionFiles[0];
     const installedClaude = chosenIds.includes('claude') || existsSync(join(targetDir, '.claude'));
     const precompactResult = installedClaude
         ? installPrecompactHook(targetDir)
@@ -1560,9 +1689,11 @@ function finishInit(targetDir, installTarget, canonicalRoot, version, chosenIds,
         '.aperant/events/': 'event log (git-ignored)',
         '.aperant/prompts/': 'agent prompt templates',
         '.aperant/install/last-install.json': 'cross-runtime install summary',
-        [basename(instructionFile)]: `APT section ${injectionResult}`,
         '.claude/settings.local.json': `PreCompact hook ${precompactResult}; SessionStart hook ${sessionStartResult}`,
     };
+    for (const f of instructionFiles) {
+        structure[f.path] = `APT section ${f.status}`;
+    }
     if (kernelResult) {
         structure['.aperant/deps/'] =
             kernelResult.status === 'installed'
@@ -1601,7 +1732,10 @@ function finishInit(targetDir, installTarget, canonicalRoot, version, chosenIds,
         framework_version: version,
         configCreated,
         configMigrated,
-        instructionFile: { path: basename(instructionFile), status: injectionResult },
+        // Plural contract (ID-03): one entry per instruction file written.
+        // `instructionFile` (singular) is a backwards-compat alias = first entry.
+        instructionFiles,
+        instructionFile: primaryInstructionFile,
         stateCreated,
         seedsCreated,
         publicRemoteWarning,