@aperant/framework 0.8.7 → 0.9.0

package/dist/plugin/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/dist/plugin/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/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.7",
+  "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>