@aperant/framework 0.8.7 → 0.10.0

package/dist/cli/verify-proof/runtime-detect.mjs

@@ -1,209 +1,14 @@
 /**
- * runtime-detect.mjs — pure project-shape capability detection.
+ * verify-proof/runtime-detect.mjs — pure project-shape capability detection.
  *
- * Extracted from packages/core/src/prompts/prompt-loader.ts:572-595 so the
- * framework CLI is self-contained (no @aperant/core dep). Same heuristics:
- * read package.json's dependencies + devDependencies, return a capability
- * record the resolver can score against.
- *
- * Pattern: pure data in → pure data out. No filesystem walking, no exec.
- * Use loadRuntimeCapabilities(projectDir) for the cwd-rooted variant.
- *
- * v0.8.6 — `loadRuntimeCapabilities` now ALSO walks `apps/*` by default
- * (configurable via the second arg `{monorepo_globs}`) and OR-merges
- * each match's `package.json` capabilities with the root. The default
- * `['apps/*']` matches the canonical Aperant monorepo layout; adopters
- * whose monorepo lives elsewhere (e.g. `packages/apps/*`) pass a
- * custom `monorepo_globs`. Setting `monorepo_globs: []` disables the
- * walk entirely (root-only escape hatch).
- */
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-/**
- * @typedef {Object} RuntimeCapabilities
- * @property {boolean} is_electron
- * @property {boolean} is_tauri
- * @property {boolean} is_nextjs
- * @property {boolean} is_nuxt
- * @property {boolean} is_web_frontend
- * @property {boolean} is_expo
- * @property {boolean} is_react_native
- * @property {boolean} has_node
- */
-/** A capability record with every flag defaulted to false. */
-function emptyCapabilities() {
-    return {
-        is_electron: false,
-        is_tauri: false,
-        is_nextjs: false,
-        is_nuxt: false,
-        is_web_frontend: false,
-        is_expo: false,
-        is_react_native: false,
-        has_node: false,
-    };
-}
-/**
- * Detect runtime capabilities from a parsed package.json object.
- *
- * @param {Record<string, unknown> | null} packageJson
- * @returns {RuntimeCapabilities}
+ * The implementation now lives in util/runtime-capabilities.mjs so the install
+ * layer can share it WITHOUT install/ importing from verify-proof/ (the
+ * layer-boundary rule). Re-exported here byte-for-byte so every existing
+ * `import { … } from '../verify-proof/runtime-detect.mjs'` call site (and the
+ * `RuntimeCapabilities` typedef references) keep working unchanged.
  */
-export function detectFromPackageJson(packageJson) {
-    const capabilities = emptyCapabilities();
-    if (packageJson === null || typeof packageJson !== 'object')
-        return capabilities;
-    const allDeps = {
-        ...(packageJson.dependencies ?? {}) /** @type {Record<string,string>} */,
-        ...(packageJson.devDependencies ?? {}) /** @type {Record<string,string>} */,
-    };
-    const deps = new Set(Object.keys(allDeps).map((k) => k.toLowerCase()));
-    if (deps.has('electron') || [...deps].some((d) => d.startsWith('@electron'))) {
-        capabilities.is_electron = true;
-    }
-    if (deps.has('@tauri-apps/api') || deps.has('tauri')) {
-        capabilities.is_tauri = true;
-    }
-    if (deps.has('expo'))
-        capabilities.is_expo = true;
-    if (deps.has('react-native'))
-        capabilities.is_react_native = true;
-    // Web frontends — react/vue/svelte/angular/solid → frontend. BUT: an
-    // Electron app commonly bundles React as its renderer; in that case the
-    // runtime is "electron", not "web_frontend". Electron + react-native +
-    // expo + tauri all win over the web flag.
-    const isNativeContainer = capabilities.is_electron ||
-        capabilities.is_tauri ||
-        capabilities.is_react_native ||
-        capabilities.is_expo;
-    const webFrameworks = ['react', 'vue', 'svelte', 'angular', 'solid'];
-    if (!isNativeContainer && webFrameworks.some((f) => deps.has(f))) {
-        capabilities.is_web_frontend = true;
-    }
-    if (deps.has('next')) {
-        capabilities.is_nextjs = true;
-        capabilities.is_web_frontend = true;
-    }
-    if (deps.has('nuxt')) {
-        capabilities.is_nuxt = true;
-        capabilities.is_web_frontend = true;
-    }
-    if (deps.has('vite') && !isNativeContainer) {
-        capabilities.is_web_frontend = true;
-    }
-    // Node-ish? Anything with a package.json + an entry point counts.
-    if (typeof packageJson.main === 'string' || typeof packageJson.module === 'string') {
-        capabilities.has_node = true;
-    }
-    if (!capabilities.has_node && packageJson.scripts && typeof packageJson.scripts === 'object') {
-        capabilities.has_node = true;
-    }
-    return capabilities;
-}
+export { detectFromPackageJson, loadRuntimeCapabilities, } from '../util/runtime-capabilities.mjs';
 /**
- * Load and detect capabilities from a project directory's package.json.
- * v0.8.6 — also walks `monorepo_globs` (default `['apps/*']`) and
- * OR-merges each match's capabilities with the root.
- *
- * @param {string} projectDir
- * @param {{monorepo_globs?: string[]}} [opts]
- * @returns {RuntimeCapabilities}
- */
-export function loadRuntimeCapabilities(projectDir, opts) {
-    const root = resolve(projectDir);
-    const rootPkgPath = join(root, 'package.json');
-    let rootCaps = emptyCapabilities();
-    if (existsSync(rootPkgPath)) {
-        try {
-            rootCaps = detectFromPackageJson(JSON.parse(readFileSync(rootPkgPath, 'utf-8')));
-        }
-        catch {
-            /* fall through with empty caps */
-        }
-    }
-    // Default to the canonical Aperant monorepo layout. Passing `[]`
-    // disables the walk entirely (root-only escape hatch per spec ID-05).
-    const globs = opts && Array.isArray(opts.monorepo_globs) ? opts.monorepo_globs : ['apps/*'];
-    if (globs.length === 0)
-        return rootCaps;
-    let merged = rootCaps;
-    for (const glob of globs) {
-        const matches = expandSimpleGlob(root, glob);
-        for (const dir of matches) {
-            const childPkgPath = join(dir, 'package.json');
-            if (!existsSync(childPkgPath))
-                continue;
-            try {
-                const childCaps = detectFromPackageJson(JSON.parse(readFileSync(childPkgPath, 'utf-8')));
-                merged = orMergeCapabilities(merged, childCaps);
-            }
-            catch {
-                /* skip malformed package.json */
-            }
-        }
-    }
-    return merged;
-}
-/**
- * Expand a simple `prefix/*` glob against the root. Supports ONLY the
- * `<dir>/*` shape (matches each direct subdirectory of `<dir>`). Other
- * glob syntax is intentionally rejected — v1 keeps the dep surface
- * small. Fails closed on malformed patterns (returns []).
- *
- * @param {string} root
- * @param {string} glob
- * @returns {string[]}
- */
-function expandSimpleGlob(root, glob) {
-    if (typeof glob !== 'string' || !glob.endsWith('/*'))
-        return [];
-    const prefix = glob.slice(0, -2);
-    if (prefix.length === 0 || prefix.includes('*'))
-        return [];
-    const dir = join(root, prefix);
-    if (!existsSync(dir))
-        return [];
-    let entries;
-    try {
-        entries = readdirSync(dir);
-    }
-    catch {
-        return [];
-    }
-    const matches = [];
-    for (const name of entries) {
-        const sub = join(dir, name);
-        try {
-            if (statSync(sub).isDirectory())
-                matches.push(sub);
-        }
-        catch {
-            /* skip unreadable entries */
-        }
-    }
-    return matches;
-}
-/**
- * Boolean OR-merge of two capability records. Any flag true in either
- * input is true in the output. The "Electron wins over web" rule from
- * `detectFromPackageJson` is preserved when this is called repeatedly —
- * each child's flags are honest about that child's own shape, and the
- * OR-merge just unions them.
- *
- * @param {RuntimeCapabilities} a
- * @param {RuntimeCapabilities} b
- * @returns {RuntimeCapabilities}
+ * @typedef {import('../util/runtime-capabilities.mjs').RuntimeCapabilities} RuntimeCapabilities
  */
-function orMergeCapabilities(a, b) {
-    return {
-        is_electron: a.is_electron || b.is_electron,
-        is_tauri: a.is_tauri || b.is_tauri,
-        is_nextjs: a.is_nextjs || b.is_nextjs,
-        is_nuxt: a.is_nuxt || b.is_nuxt,
-        is_web_frontend: a.is_web_frontend || b.is_web_frontend,
-        is_expo: a.is_expo || b.is_expo,
-        is_react_native: a.is_react_native || b.is_react_native,
-        has_node: a.has_node || b.has_node,
-    };
-}
 //# sourceMappingURL=runtime-detect.mjs.map

package/dist/cli/verify-proof/runtime-detect.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-detect.mjs","sourceRoot":"","sources":["../../../src/cli/verify-proof/runtime-detect.mjs"],"names":[],"mappings":"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"}
+{"version":3,"file":"runtime-detect.mjs","sourceRoot":"","sources":["../../../src/cli/verify-proof/runtime-detect.mjs"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACN,qBAAqB,EACrB,uBAAuB,GACvB,MAAM,kCAAkC,CAAA;AAEzC;;GAEG"}

package/dist/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "aperant",
-  "version": "0.8.7",
+  "version": "0.10.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": {
     "name": "Mikalsen AI",

package/dist/plugin/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/dist/plugin/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/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
@@ -468,6 +469,55 @@ fi
 
 After this point, the per-round artifact root is `.aperant/pr-reviews/pr-${PR_NUMBER}/rounds/${ROUND}/` (the `${REVIEW_ID}` is still used for the git worktree branch and temporary files). Subsequent `git diff` invocations within the round use `${PINNED_HEAD_SHA}` as the head ref.
 
+### Step 4c: Mergeability Pre-Check (PR reviews only)
+
+**Why this exists.** The review diff is `git diff {BASE}...{HEAD}` (three-dot — from the *merge-base*), so it shows the PR's own changes relative to where it branched. It is **blind to drift on `{BASE}` since then** and therefore says nothing about whether the PR still merges cleanly. A PR can pass a glowing review and be unmergeable. This step closes that gap: it is **informational, never blocking** (the review still runs in full), but a conflicting/stale state MUST be surfaced so the reader doesn't trust a review of a diff that no longer applies.
+
+```bash
+# PR-mode only. Query GitHub's authoritative mergeability + measure drift.
+if [ -n "$PR_NUMBER" ]; then
+  MERGE_JSON=$(gh pr view ${PR_NUMBER} --json mergeable,mergeStateStatus,baseRefName 2>/dev/null)
+  MERGEABLE=$(echo "$MERGE_JSON" | jq -r '.mergeable // "UNKNOWN"')
+  MERGE_STATE=$(echo "$MERGE_JSON" | jq -r '.mergeStateStatus // "UNKNOWN"')
+  BASE_REF=$(echo "$MERGE_JSON" | jq -r '.baseRefName // "main"')
+  git fetch origin "${BASE_REF}" 2>/dev/null
+  BEHIND=$(git rev-list --count ${PINNED_HEAD_SHA}..origin/${BASE_REF} 2>/dev/null || echo "?")
+  AHEAD=$(git rev-list --count origin/${BASE_REF}..${PINNED_HEAD_SHA} 2>/dev/null || echo "?")
+
+  # If GitHub reports a conflict (or hasn't computed yet), enumerate the conflicting
+  # files locally without touching any working tree (git >= 2.38):
+  CONFLICT_FILES=""
+  if [ "$MERGEABLE" = "CONFLICTING" ] || [ "$MERGE_STATE" = "DIRTY" ]; then
+    CONFLICT_FILES=$(git merge-tree --write-tree --name-only origin/${BASE_REF} ${PINNED_HEAD_SHA} 2>/dev/null \
+                     | tail -n +2 | sed '/^$/d' | grep '/' )
+  fi
+fi
+```
+
+Record the result in `metadata.json` under a `mergeability` key:
+
+```json
+{
+  "mergeability": {
+    "mergeable": "CONFLICTING | MERGEABLE | UNKNOWN",
+    "merge_state_status": "DIRTY | CLEAN | BLOCKED | BEHIND | ...",
+    "base_ref": "main",
+    "commits_behind_base": 101,
+    "commits_ahead_base": 91,
+    "conflicting_files": ["apps/.../App.tsx", "..."]
+  }
+}
+```
+
+**How to use the result:**
+
+- `MERGEABLE` ∈ {`CONFLICTING`} OR `MERGE_STATE` = `DIRTY` → the PR has conflicts. Surface a **⚠️ Mergeability** block in the Phase 5 intermediate report AND the Phase 8 final report, listing `commits_behind_base` and the `conflicting_files`. In **external / comment-only** mode, include the same block in the Phase 6b comment. State plainly that the branch needs a rebase/merge from `{BASE}` and that **the reviewed diff may be stale** with respect to current `{BASE}`.
+- `MERGE_STATE` = `BEHIND` (mergeable but behind) → note the drift (`commits_behind_base`) as a softer advisory; no conflict, but the diff predates recent `{BASE}` commits.
+- `MERGEABLE` = `UNKNOWN` (GitHub hasn't finished computing, common right after a push) → record `UNKNOWN`; optionally re-poll once after a few seconds. Do not block.
+- `MERGEABLE` = `MERGEABLE`, `MERGE_STATE` = `CLEAN` → record it and move on silently.
+
+This step never changes the review's findings or assessment — a conflicting PR with zero code findings is still `approve` on its own merits. Mergeability is reported as a **separate** signal so the reader knows whether the approval can actually land.
+
 ### Step 5: Read All Changed Files
 
 For every file in the changed file list, read it in full using the Read tool **from the worktree**:
@@ -594,6 +644,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 +723,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
 
@@ -1047,6 +1107,10 @@ Review Synthesis (Before Auto-Fix)
 Auto-Checks: {PASS/FAIL}
   lint: {P/F} | typecheck: {P/F} | tests: {P/F}
 
+Mergeability (PR reviews — from Step 4c): {MERGEABLE/CONFLICTING/UNKNOWN}
+  {if CONFLICTING/DIRTY: "⚠️ conflicts with {BASE} — {behind} commits behind — needs rebase — reviewed diff may be stale"}
+  {if conflicting_files: list them}
+
 Validated Findings:
   CRITICAL: {N}
   HIGH: {N}
@@ -1171,8 +1235,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 +1262,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 +1284,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 +1299,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 +1357,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 +1516,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 |
 
 ```
@@ -1597,6 +1683,7 @@ Output the human-readable summary:
 
   Review ID: {REVIEW_ID}
   Assessment: {APPROVE / REQUEST CHANGES / COMMENT}
+  Mergeability: {MERGEABLE / CONFLICTING (N behind {BASE}, needs rebase) / UNKNOWN}   # PR reviews — from Step 4c / metadata.json.mergeability
 
   Scores:
     Security:      {score}/10
@@ -1683,11 +1770,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/dist/plugin/skills/apt-verify/SKILL.md

@@ -60,7 +60,7 @@ Before spawning any verifier subagent or running scoring against acceptance crit
 </locked_decisions>
 ```
 
-Verifiers apply this digest when interpreting "completeness" and "correctness" — if a decision explicitly deferred a behavior, its absence is NOT a verification failure.
+Verifiers apply this digest when interpreting "completeness" and "correctness" — if a decision explicitly deferred a behavior AND the deferred finding has severity below critical or major, its absence is NOT a verification failure. A deferred critical or major finding IS a Completeness gap — score accordingly and note it in the issues list.
 </decision_ledger_inject>
 
 <process>

package/dist/plugin/skills/apt-verify-proof/SKILL.md

@@ -20,6 +20,7 @@ gates: []
 config_keys:
   - verification.open_report
   - verification.report_formats
+  - verification.provision_mcp
 ---
 
 # Proof Verification
@@ -104,13 +105,36 @@ disable the walk entirely (root-only behaviour, backwards compat).
 The `verification.runtimes[]` override stays the final escape hatch
 and is now usually unnecessary because the walk runs by default.
 
-### Bundled drivers (4)
+### Bundled drivers (5)
 
 - **browser** (priority=100, ga) — Next.js / vanilla web frontends.
 - **electron** (priority=90, ga) — Electron desktop apps.
+- **tauri** (priority=85, ga) — Tauri desktop apps.
 - **cli** (priority=60, ga) — headless CI, output-shape assertions.
 - **api** (priority=50, ga) — HTTP / JSON-API regression tests.
 
+### Install-time MCP provisioning (verification.provision_mcp)
+
+`apt-tools init` (and `/apt:update`, which routes through the same path)
+auto-provisions the MCP transport a driver needs into each SELECTED host
+CLI's config, so verify-proof works at the prompt with no manual MCP
+setup. It detects the project runtime and, per host:
+
+- **claude** → JSON-merges the server into the project-root `.mcp.json`
+  (`mcpServers.<id>`).
+- **codex** → upserts a `[mcp_servers.<id>]` table into the project-root
+  `.codex/config.toml`.
+
+Electron and Tauri projects get the matching MCP server; web frontends
+get the browser driver's declared `agent-browser` skill copied into the
+host skill dir (`.claude/skills/` / `.agents/skills/`) — its `agent-browser`
+CLI is a documented one-time prereq, the same class as the
+`electron-mcp-server` / `tauri-plugin-mcp-server` npm packages (see each
+driver's README). All writes are **TOFU/non-clobbering**: a pre-existing
+server id, config table, or skill file is never overwritten. Opt out with
+`verification.provision_mcp: false` (default `true`) — then init/update
+writes no host MCP config and no skill.
+
 ### Driver authors
 
 Third-party driver authors should run `apt-tools driver doctor .` before