@aperant/framework 0.8.6 → 0.9.0

package/dist/plugin/skills/apt-triage/SKILL.md

@@ -127,16 +127,18 @@ needed.
 
 `.aperant/config.json.task_tracking.backend` selects the mirror:
 
-| Backend | v1 behavior |
+| Backend | behavior |
 |---|---|
 | `local-only` (default) | State mirrors to `.aperant/tasks/{task-id}/triage.json` only. Zero network dependency. |
-| `github-issues` | Returns `{status: 'not-implemented', backend: 'github-issues', v2_issue: '#TBD'}`. Implementation deferred to v2. |
-| `app-inbox` | Same as github-issues — stub returning not-implemented. |
+| `github-issues` | Mirrors triage state to a real GitHub issue via the `gh` CLI. The first mirror CREATES an issue (`triage: <task-id>`, labelled `<category>` + `<vocab>:<state>`); subsequent transitions UPDATE the same issue (label swap), and `wontfix` CLOSES it as "not planned". The issue pointer (`github.{issue_number, issue_url, repo}`) persists on `triage.json` so transitions stay idempotent — no duplicates. Honors `task_tracking.tracker_label_vocabulary` (default → `triage:<state>`). Requires `gh` installed + authenticated + a resolvable git remote; otherwise returns a structured error (`reason: gh-unavailable | gh-unauthenticated | no-remote | gh-command-failed`) and exits non-zero — never a crash/stacktrace. Label ops are best-effort: an unknown label degrades to a `warnings[]` entry while the open/closed state change still lands. |
+| `app-inbox` | Still a stub: returns `{status: 'not-implemented', backend: 'app-inbox', v2_issue: '#TBD'}`. Belongs to a future Convex-backed task (post-app-launch). |
 
 Skill body reads `task_tracking.backend` at the start of every
-invocation. If the backend's adapter is not implemented, the skill
-fails fast with the `not-implemented` envelope — it does NOT silently
-fall back to `local-only`.
+invocation. For `app-inbox` (still unimplemented), the skill fails fast
+with the `not-implemented` envelope — it does NOT silently fall back to
+`local-only`. The `github-issues` backend is fully implemented (see
+above); its preflight/`gh` failures surface as structured errors, again
+without falling back to `local-only`.
 
 ## Fast Path Guarantee — QUICK never enters triage (AC9, ID-05)
 

package/dist/plugin/skills/apt-update/SKILL.md

@@ -287,6 +287,6 @@ Runtime files were still refreshed; `/apt` will still work from PATH if `apt-too
 - **Worker hasn't run yet**: the cache file is missing. That's fine — run check-version directly (step 1 is robust to a missing cache). Proceed normally.
 - **Re-install fails (non-zero exit from init)**: surface the JSON `error` field verbatim in a single line, then stop. Do NOT delete the cache file — the chip should remain visible so the user sees the failure persists.
 - **Kernel install fails but runtime install succeeds**: see Scenario D above. Do not treat this as a total failure; the user's skills still work via PATH fallback.
-- **CLAUDE.md / AGENTS.md foreign rows (exit 2, `instruction-file.foreign-rows`)** — 0.7.0+ — init now refuses to silently clobber custom rows in the `<!-- APT:framework-* -->` block. If `init` exits 2 with `code: instruction-file.foreign-rows`, the `foreignRowIds[]` field lists the rows the generator did NOT produce. Two paths: (a) remove the foreign rows from CLAUDE.md / AGENTS.md by hand and re-run init, or (b) re-run with `--force-overwrite-catalog` to regenerate anyway. Unattended upgrade flows should detect this code and surface it to the operator — silent bypass is a regression.
+- **Instruction-file foreign rows (exit 2, `instruction-file.foreign-rows`)** — 0.7.0+ — init now refuses to silently clobber custom rows in the `<!-- APT:framework-* -->` block. Since the multi-file fix, init stamps the block into EVERY instruction file the selected runtimes read (claude → CLAUDE.md, codex/opencode → AGENTS.md, gemini → GEMINI.md) and runs an all-target foreign-row preflight: if ANY target has foreign rows, init writes NOTHING and exits 2 (no partial install). If `init` exits 2 with `code: instruction-file.foreign-rows`, the `foreignRowIds[]` field lists the rows the generator did NOT produce and `instructionFiles[]` lists the offending files. Two paths: (a) remove the foreign rows from the listed file(s) by hand and re-run init, or (b) re-run with `--force-overwrite-catalog` to regenerate anyway. Unattended upgrade flows should detect this code and surface it to the operator — silent bypass is a regression.
 
 </edge_cases>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aperant/framework",
-  "version": "0.8.6",
+  "version": "0.9.0",
   "description": "AI coding framework — composable skills for planning, executing, verifying, and reviewing code with any LLM provider. Works as Claude Code commands, Codex tasks, or programmatically.",
   "author": "Mikalsen AI <hello@mikalsen.ai>",
   "type": "module",

package/skills/apt-pr-review/SKILL.md

@@ -65,11 +65,12 @@ PHASE 3 -- PARALLEL REVIEW (6 agents, independent, all spawned in ONE message):
 PHASE 4 -- VALIDATION (1 agent):
   validator          -> Re-investigates every finding, confirms or dismisses
 
-PHASE 6 -- FIX LOOP (up to 3 agents per iteration, max 4 iterations):
-  fixer-1, fixer-2, fixer-3
+PHASE 6 -- FIX LOOP (up to 3 fixers per iteration, spawned ONE AT A TIME, max 4 iterations):
+  fixer-1, fixer-2, fixer-3  (groups still exist; they run SEQUENTIALLY, never concurrently)
   - Read validated finding files directly
-  - Fix assigned issues, run verification, stage changes
+  - Fix assigned issues, run verification, commit atomically per finding
   - Report brief status to orchestrator
+  - NEVER run pr-review fixers in parallel in a shared worktree (FRAMEWORK-BUG-006)
 
 PHASE 7 -- SELF-REVIEW (1 fresh agent):
   self-reviewer
@@ -594,6 +595,16 @@ Construct a toolchain commands object:
 
 Save to `.aperant/pr-reviews/${REVIEW_ID}/toolchain.json`.
 
+**Cache-bypass variant (FRAMEWORK-BUG-006 Part B).** `toolchain-detect` emits an additive
+`no_cache_command` field on `typecheck` (and `test`) when the project's verify command is turbo-backed
+(e.g. `typecheck: { tool, command, no_cache_command: "pnpm run typecheck --force" }`). A turbo-backed
+verify can return a STALE CACHE HIT ("replaying logs") that reports PASS while a fixer-introduced broken
+import sits on disk — sighted on PR #244, where only a `--force` (no-cache) typecheck exposed it.
+**Whenever a `no_cache_command` exists for a check, every POST-FIX verification (auto-checks re-runs,
+the Phase 6 fixer verification, and the Phase 7 self-reviewer) MUST use it instead of the plain
+`command`** so a stale cache cannot mask a broken import. Non-turbo projects have no `no_cache_command`
+(plain `tsc`/`vitest` have no cache to bust) and use the plain command unchanged.
+
 Update `metadata.json` with the toolchain summary and trigger count.
 
 ---
@@ -663,8 +674,8 @@ cd {WORKTREE_PATH}
 ```
 
 1. Lint: {LINT_COMMAND}
-2. Typecheck: {TYPECHECK_COMMAND}
-3. Tests: {TEST_COMMAND}
+2. Typecheck: {TYPECHECK_COMMAND}  (use toolchain.json `typecheck.no_cache_command` if present — FRAMEWORK-BUG-006: a turbo-backed typecheck can replay a stale cached PASS and mask a broken import)
+3. Tests: {TEST_COMMAND}  (use toolchain.json `test.no_cache_command` if present, same cache-bypass rationale)
 
 ## Output
 
@@ -1171,8 +1182,9 @@ This is the owned-mode path. External-mode invocations run Phase 6b instead of t
 for ITERATION in 1 2 3 4:
   1. Create iteration directory
   2. Group findings into fix assignments (max 3 groups)
-  3. Spawn fix agents
-  4. Wait for completion
+  3. Spawn fix agents ONE AT A TIME (never in parallel — FRAMEWORK-BUG-006):
+       for each group: spawn fixer → wait → audit (Step 4b) → next group
+  4. (folded into step 3's per-fixer wait)
   5. Generate new diff
   6. If fixes were applied: spawn fresh review on new diff
   7. If ITERATION <= 2: accept new findings into the backlog
@@ -1197,6 +1209,14 @@ Take all confirmed, fixable findings and group them into up to 3 independent gro
 
 #### Step 3: Spawn Fix Agents
 
+> **HARD RULE (FRAMEWORK-BUG-006): NEVER run pr-review fixers in parallel in a shared worktree.**
+> All fixers share ONE worktree, ONE git index, and ONE branch. git's index is not a
+> concurrency-safe surface — concurrent `git add` / `git commit` / self-audit `git log`/`git diff`
+> from sibling fixers either SWEEP one fixer's staged files into another's commit (PR #114
+> entanglement) or CLOBBER another fixer's working-tree edits entirely (PR #244 work-loss). Spawn
+> fixers **one at a time**: spawn fixer-1, wait for it to return, run the Step 4b audit-fixer gate on
+> it, THEN spawn fixer-2, and so on. At most one fixer touches the shared worktree at any moment.
+
 **Capture the iteration-start SHA BEFORE spawning fixers** (used by both the Step 4b audit gate AND the per-fixer Pre-Return Self-Audit added in BUG-016 — fixers now commit atomically per finding, and the audit window is scoped by this SHA):
 
 ```bash
@@ -1211,9 +1231,9 @@ For each fix group, spawn a fix agent. Read the agent definition from `.claude/a
 | `[FIX_ASSIGNMENT]` | List of finding IDs and files for this group |
 | `[N]` | Current iteration number |
 | `[FIXER_NAME]` | `fixer-1`, `fixer-2`, or `fixer-3` |
-| `[TOOLCHAIN_COMMANDS]` | Commands from `toolchain.json` (the `all` command, or individual commands) |
+| `[TOOLCHAIN_COMMANDS]` | Commands from `toolchain.json` (the `all` command, or individual commands). **For the post-fix typecheck/test, pass the `no_cache_command` variant when `toolchain.json` provides one** (FRAMEWORK-BUG-006: a turbo-backed verify can replay a stale cached PASS and mask the fixer's own broken import). |
 | `[CRITICAL_APPROVAL]` | `true` or `false` for each critical finding in this group |
-| `[PARALLEL_FIXERS]` | `true` if more than 1 fixer is spawned this iteration |
+| `[PARALLEL_FIXERS]` | Always `false` (FRAMEWORK-BUG-006). Fixers are spawned one at a time in the shared worktree — never concurrently. The placeholder is retained only so the fixer-agent Coordination Protocol can assert "you are the only fixer touching this worktree right now." |
 | `[WORKTREE_PATH]` | The worktree path — fix agents edit files HERE, not in the user's working directory |
 | `[ITERATION_START_SHA]` | The SHA captured BEFORE spawning fixers (see Step 4b's `ITERATION_START_SHA=$(...)` capture). Required for BUG-016 commit-discipline Pre-Return Self-Audit. |
 
@@ -1226,18 +1246,31 @@ Agent(
 )
 ```
 
-If there are 2-3 groups, spawn all fix agents in ONE message for parallel execution.
+If there are 2-3 groups, spawn the fixers **sequentially — one fixer at a time, never in parallel**
+(FRAMEWORK-BUG-006). Concretely, loop over the groups:
+
+```
+for each fix group (in order):
+  1. Spawn the fixer for THIS group only (a single Agent call in its own message)
+  2. Wait for it to return its brief status line (Step 4)
+  3. Run the Step 4b audit-fixer gate on it
+  4. Only THEN spawn the fixer for the next group
+```
+
+Do NOT batch multiple `Agent(...)` fixer calls into one message — that is the parallel-shared-worktree
+race this bug fixes. The atomic-per-finding commit discipline (BUG-016) and the Step 4b audit gate are
+UNCHANGED; they now simply run without a concurrent sibling mutating the index.
 
 #### Step 4: Wait for Completion
 
-Wait for all fix agents to return their brief status:
+Wait for the **current** fix agent to return its brief status (you spawned only one this turn):
 ```
 FIXED: X | FAILED: Y | SKIPPED: Z | VERIFICATION: PASS/FAIL
 ```
 
 #### Step 4b: Audit Fixer Output (Hallucination Gate)
 
-On 2026-04-20 a live fix agent returned `FIXED: 2 | FAILED: 0 | SKIPPED: 0 | VERIFICATION: PASS` and wrote a convincing 140-line `fixes-applied.md` — but the worktree had zero edits matching the claimed files. The orchestrator trusted the self-reported status line and nearly shipped two fabricated fixes. This step is the deterministic gate that closes that hole: for EACH fixer that returned in Step 4, run the audit CLI and cross-check the fixer's claims against the actual git state.
+On 2026-04-20 a live fix agent returned `FIXED: 2 | FAILED: 0 | SKIPPED: 0 | VERIFICATION: PASS` and wrote a convincing 140-line `fixes-applied.md` — but the worktree had zero edits matching the claimed files. The orchestrator trusted the self-reported status line and nearly shipped two fabricated fixes. This step is the deterministic gate that closes that hole: for the fixer that just returned in Step 4 (fixers run one at a time — FRAMEWORK-BUG-006), run the audit CLI and cross-check the fixer's claims against the actual git state BEFORE spawning the next group's fixer.
 
 **Capture the iteration-start SHA BEFORE spawning fixers** so the audit can cover committed fixes (bug-5, 2026-04-23 — fixers that commit their edits before returning would otherwise present an empty working tree and trip a false-positive hallucination verdict):
 
@@ -1271,7 +1304,7 @@ Rule of thumb: pass `--since-sha "${ITERATION_START_SHA}"` on every audit invoca
 
 The CLI returns a JSON envelope with `verdict` ∈ `verified | hallucinated | skipped`, writes `iterations/${ITERATION}/audit.json` (append-only), and bumps `metadata.json.fixer_hallucinations_total` on every `hallucinated` outcome. The envelope's `observed.since_sha` + `observed.since_sha_source` fields record which SHA was used and where it came from (`flag` | `merge-base` | `null`). The same envelope is used for the fixer and the self-reviewer (Phase 7) — `--fixer self-reviewer` reads from `self-review.md`.
 
-**Canonical fix-report filename per fixer (BUG-030):** each fixer agent writes to `fixes-applied-${FIXER_NAME}.md` (e.g. `fixes-applied-fixer-1.md`). The audit CLI resolves candidates in strict order: `fixes-applied-group{N}.md` (legacy group-named, pre-BUG-030 reviews) → `fixes-applied-fixer-{N}.md` (NEW fixer-named) → `fixes-applied-${FIXER_NAME}.md` (exact match, preferred for non-numeric fixer names) → `fixes-applied.md` (legacy unscoped, single-fixer reviews only). Writing the canonical name eliminates the cross-fixer false-positive `hallucinated` verdict that fired when two parallel fixers shared `fixes-applied.md`.
+**Canonical fix-report filename per fixer (BUG-030):** each fixer agent writes to `fixes-applied-${FIXER_NAME}.md` (e.g. `fixes-applied-fixer-1.md`). The audit CLI resolves candidates in strict order: `fixes-applied-group{N}.md` (legacy group-named, pre-BUG-030 reviews) → `fixes-applied-fixer-{N}.md` (NEW fixer-named) → `fixes-applied-${FIXER_NAME}.md` (exact match, preferred for non-numeric fixer names) → `fixes-applied.md` (legacy unscoped, single-fixer reviews only). Writing the canonical name eliminates the cross-fixer false-positive `hallucinated` verdict that fired when fixers shared `fixes-applied.md` (a per-fixer report path is still correct now that fixers run sequentially — each fixer owns its own report file).
 
 | Verdict | Orchestrator Action |
 |---------|---------------------|
@@ -1430,7 +1463,7 @@ Read the agent definition from `.claude/agents/apt-pr-review-self-reviewer.md` a
 |-------------|-------|
 | `[FIX_DIFF]` | The combined fix diff content or path to the concatenated file |
 | `[REVIEW_DIR]` | `.aperant/pr-reviews/{REVIEW_ID}` |
-| `[TOOLCHAIN_COMMANDS]` | Commands from `toolchain.json` |
+| `[TOOLCHAIN_COMMANDS]` | Commands from `toolchain.json`. **Use the `no_cache_command` variant for the typecheck/test when one is present** (FRAMEWORK-BUG-006: a turbo-backed verify can replay a stale cached PASS and mask a broken import the fixes introduced). |
 | `[WORKTREE_PATH]` | The worktree path — self-reviewer works HERE |
 
 ```
@@ -1683,11 +1716,15 @@ Fix agents self-report their outcome via a status line (`FIXED: X | FAILED: Y |
 **Wrong:** Reading the full finding text from agent responses and processing it in orchestrator context.
 **Right:** Agent responses are brief (3-5 lines). All detail goes to files. Orchestrator reads files via Read tool only when needed.
 
-### Mistake 2: Spawning Agents Sequentially
+### Mistake 2: Spawning the Phase 3 REVIEW Agents Sequentially
 
 **Wrong:** Spawn security agent, wait, spawn quality agent, wait, etc.
 **Right:** Spawn all 6 review agents in ONE message using 6 parallel Agent tool calls. They run concurrently.
 
+> Scope note: this applies ONLY to the Phase 3 review specialists, which are read-only (Read/Grep/Glob,
+> no Edit/Bash, no git writes) and therefore cannot race the index. The Phase 6 FIXERS are the
+> opposite — they MUST be spawned one at a time (FRAMEWORK-BUG-006). Never parallelize fixers.
+
 ### Mistake 3: Skipping the Validator
 
 **Wrong:** Sending raw review findings directly to fix agents.

package/skills/apt-setup/SKILL.md

@@ -966,8 +966,9 @@ ST-3 apt:execute --tdd).
 
 Per ID-01 (Framework full-featured locally; backends are pluggable), the
 default is `local-only` — zero GitHub auth required on first run. Users
-can switch to `github-issues` (v1 stub) or `app-inbox` (v1 stub) later;
-the framework abstraction is open for v2 adapter implementations.
+can switch to `github-issues` (implemented — creates + syncs real issues
+via the `gh` CLI) or `app-inbox` (still a stub) later; the framework
+abstraction is open for further adapter implementations.
 
 ### 3g.1 Present the task-tracking picker
 
@@ -979,10 +980,10 @@ AskUserQuestion([
     options: [
       { label: "Local files only (recommended for solo / 2-founder)",
         description: "Writes to .aperant/tasks/{id}/triage.json. Zero net dep." },
-      { label: "GitHub Issues (v2 — stub returns not-implemented in v1)",
-        description: "v1 ships the adapter shape only; full implementation in v2." },
-      { label: "App inbox (post-app-launch — stub in v1)",
-        description: "Convex-backed; same state machine, app-rendered." }
+      { label: "GitHub Issues (creates + syncs real issues via the gh CLI)",
+        description: "First mirror creates an issue; transitions update the same issue (label swap), wontfix closes it as not-planned. Requires gh installed + authed + a git remote." },
+      { label: "App inbox (post-app-launch — stub)",
+        description: "Convex-backed; same state machine, app-rendered. Still a stub." }
     ]
   },
   {

package/skills/apt-triage/SKILL.md

@@ -127,16 +127,18 @@ needed.
 
 `.aperant/config.json.task_tracking.backend` selects the mirror:
 
-| Backend | v1 behavior |
+| Backend | behavior |
 |---|---|
 | `local-only` (default) | State mirrors to `.aperant/tasks/{task-id}/triage.json` only. Zero network dependency. |
-| `github-issues` | Returns `{status: 'not-implemented', backend: 'github-issues', v2_issue: '#TBD'}`. Implementation deferred to v2. |
-| `app-inbox` | Same as github-issues — stub returning not-implemented. |
+| `github-issues` | Mirrors triage state to a real GitHub issue via the `gh` CLI. The first mirror CREATES an issue (`triage: <task-id>`, labelled `<category>` + `<vocab>:<state>`); subsequent transitions UPDATE the same issue (label swap), and `wontfix` CLOSES it as "not planned". The issue pointer (`github.{issue_number, issue_url, repo}`) persists on `triage.json` so transitions stay idempotent — no duplicates. Honors `task_tracking.tracker_label_vocabulary` (default → `triage:<state>`). Requires `gh` installed + authenticated + a resolvable git remote; otherwise returns a structured error (`reason: gh-unavailable | gh-unauthenticated | no-remote | gh-command-failed`) and exits non-zero — never a crash/stacktrace. Label ops are best-effort: an unknown label degrades to a `warnings[]` entry while the open/closed state change still lands. |
+| `app-inbox` | Still a stub: returns `{status: 'not-implemented', backend: 'app-inbox', v2_issue: '#TBD'}`. Belongs to a future Convex-backed task (post-app-launch). |
 
 Skill body reads `task_tracking.backend` at the start of every
-invocation. If the backend's adapter is not implemented, the skill
-fails fast with the `not-implemented` envelope — it does NOT silently
-fall back to `local-only`.
+invocation. For `app-inbox` (still unimplemented), the skill fails fast
+with the `not-implemented` envelope — it does NOT silently fall back to
+`local-only`. The `github-issues` backend is fully implemented (see
+above); its preflight/`gh` failures surface as structured errors, again
+without falling back to `local-only`.
 
 ## Fast Path Guarantee — QUICK never enters triage (AC9, ID-05)
 

package/skills/apt-update/SKILL.md

@@ -287,6 +287,6 @@ Runtime files were still refreshed; `/apt` will still work from PATH if `apt-too
 - **Worker hasn't run yet**: the cache file is missing. That's fine — run check-version directly (step 1 is robust to a missing cache). Proceed normally.
 - **Re-install fails (non-zero exit from init)**: surface the JSON `error` field verbatim in a single line, then stop. Do NOT delete the cache file — the chip should remain visible so the user sees the failure persists.
 - **Kernel install fails but runtime install succeeds**: see Scenario D above. Do not treat this as a total failure; the user's skills still work via PATH fallback.
-- **CLAUDE.md / AGENTS.md foreign rows (exit 2, `instruction-file.foreign-rows`)** — 0.7.0+ — init now refuses to silently clobber custom rows in the `<!-- APT:framework-* -->` block. If `init` exits 2 with `code: instruction-file.foreign-rows`, the `foreignRowIds[]` field lists the rows the generator did NOT produce. Two paths: (a) remove the foreign rows from CLAUDE.md / AGENTS.md by hand and re-run init, or (b) re-run with `--force-overwrite-catalog` to regenerate anyway. Unattended upgrade flows should detect this code and surface it to the operator — silent bypass is a regression.
+- **Instruction-file foreign rows (exit 2, `instruction-file.foreign-rows`)** — 0.7.0+ — init now refuses to silently clobber custom rows in the `<!-- APT:framework-* -->` block. Since the multi-file fix, init stamps the block into EVERY instruction file the selected runtimes read (claude → CLAUDE.md, codex/opencode → AGENTS.md, gemini → GEMINI.md) and runs an all-target foreign-row preflight: if ANY target has foreign rows, init writes NOTHING and exits 2 (no partial install). If `init` exits 2 with `code: instruction-file.foreign-rows`, the `foreignRowIds[]` field lists the rows the generator did NOT produce and `instructionFiles[]` lists the offending files. Two paths: (a) remove the foreign rows from the listed file(s) by hand and re-run init, or (b) re-run with `--force-overwrite-catalog` to regenerate anyway. Unattended upgrade flows should detect this code and surface it to the operator — silent bypass is a regression.
 
 </edge_cases>

package/src/cli/commands/init.mjs

@@ -59,7 +59,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'
@@ -1459,6 +1459,69 @@ async function renderOutro(answers, results, version, kernelResult) {
 	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
@@ -1652,15 +1715,19 @@ function finishInit(
 		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({
@@ -1668,11 +1735,59 @@ function finishInit(
 		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(
 				{
@@ -1681,17 +1796,22 @@ function finishInit(
 					command: 'init',
 					code: 'instruction-file.foreign-rows',
 					message:
-						`${basename(instructionFile)} contains skill rows not present in the installed framework: ` +
-						`${injectionOutcome.foreignRowIds.join(', ')}. ` +
+						`${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
@@ -1730,9 +1850,11 @@ function finishInit(
 		'.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'
@@ -1772,7 +1894,10 @@ function finishInit(
 		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,

package/src/cli/commands/toolchain-detect.mjs

@@ -274,6 +274,32 @@ export function cmdToolchainDetect(projectDir, extraArgs = []) {
 	}
 	const scripts = packageJson?.scripts ?? {}
 
+	// FRAMEWORK-BUG-006 (Part B) — turbo cache-bypass detection.
+	// A turbo-backed verify command can replay a STALE CACHE HIT and report
+	// PASS while a broken import sits on disk (sighted on PR #244). When the
+	// project is turbo-backed we additionally emit a `no_cache_command`
+	// variant that appends turbo's `--force` flag so pr-review (and any
+	// consumer) can run a cache-bypassing verification. This is ADDITIVE —
+	// the existing `command` strings are never altered (ID-03).
+	const hasTurboConfig = existsSync(join(scopePath, 'turbo.json'))
+	// A package script "resolves through turbo" when its script body invokes
+	// the turbo CLI (e.g. "turbo run typecheck"). package.json scripts are
+	// hand-authored and tiny; a substring match on the `turbo` token is
+	// sufficient and avoids parsing shell.
+	function scriptIsTurboBacked(scriptName) {
+		const body = scripts[scriptName]
+		return typeof body === 'string' && /\bturbo\b/.test(body)
+	}
+	// Append --force to a turbo-backed package script so it reaches the
+	// underlying `turbo run …`. Only used when the command is known to be
+	// turbo-backed, so --force is always meaningful here. npm does NOT
+	// forward trailing args to the script unless they follow a `--`
+	// separator (`npm run typecheck --force` swallows --force as an npm flag),
+	// so insert `--` for npm. pnpm/yarn/bun forward trailing args directly.
+	function withTurboForce(command) {
+		return pm === 'npm' ? `${command} -- --force` : `${command} --force`
+	}
+
 	// Read pyproject.toml as string if present
 	let pyproject = null
 	const pyprojectPath = join(scopePath, 'pyproject.toml')
@@ -331,6 +357,19 @@ export function cmdToolchainDetect(projectDir, extraArgs = []) {
 	} else if (pyproject && pyproject.includes('[tool.mypy]')) {
 		typecheck = { tool: 'mypy', command: 'mypy .' }
 	}
+	// Additive turbo cache-bypass variant (FRAMEWORK-BUG-006). When the
+	// project is turbo-backed AND has a turbo-backed typecheck script, the
+	// plain command (often `tsc --noEmit` when tsconfig.json wins above) can
+	// be masked by a replayed turbo cache PASS. The no_cache_command routes
+	// through the turbo-backed script with `--force` so pr-review's post-fix
+	// typecheck cannot be fooled by a stale cache.
+	if (typecheck && hasTurboConfig) {
+		if (scriptIsTurboBacked('typecheck')) {
+			typecheck.no_cache_command = withTurboForce(`${pmRun} typecheck`)
+		} else if (scriptIsTurboBacked('type-check')) {
+			typecheck.no_cache_command = withTurboForce(`${pmRun} type-check`)
+		}
+	}
 
 	// --- Test ---
 	let test = null
@@ -364,6 +403,11 @@ export function cmdToolchainDetect(projectDir, extraArgs = []) {
 	if (!test && scripts.test) {
 		test = { tool: 'package-script', command: `${pmRun} test` }
 	}
+	// Additive turbo cache-bypass variant for tests (FRAMEWORK-BUG-006), same
+	// rationale as typecheck above — only when turbo backs the test script.
+	if (test && hasTurboConfig && scriptIsTurboBacked('test')) {
+		test.no_cache_command = withTurboForce(`${pmRun} test`)
+	}
 
 	// --- Build ---
 	let build = null