@aperant/framework 0.8.6 → 0.9.0

package/dist/cli/util/aperant-section.d.mts

@@ -31,4 +31,16 @@ export function buildAptSection({ canonicalRoot, targetDir, cli }: {
  * @returns {string[]}    Row IDs in file order, e.g. `['/apt', '/apt:quick', …]`.
  */
 export function extractAptSectionRowIds(text: string): string[];
+/**
+ * Matches the full APT managed block (start marker through end marker,
+ * inclusive). Exported so callers in the same package can reference a
+ * single source rather than inlining duplicate regex literals.
+ *
+ * `APT_SECTION_RE`       — no trailing newline; used for in-place replace.
+ * `APT_SECTION_STRIP_RE` — includes optional trailing newline; used for
+ *                          strip operations that want to remove the newline
+ *                          the block was preceded/followed by.
+ */
+export const APT_SECTION_RE: RegExp;
+export const APT_SECTION_STRIP_RE: RegExp;
 //# sourceMappingURL=aperant-section.d.mts.map

package/dist/cli/util/aperant-section.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"aperant-section.d.mts","sourceRoot":"","sources":["../../../src/cli/util/aperant-section.mjs"],"names":[],"mappings":"AAuDA;;;;;;;;;;;;;;;GAeG;AACH,mEAXG;IAAqB,aAAa,EAA1B,MAAM;IAGO,SAAS,EAAtB,MAAM;IACQ,GAAG;CAGzB,GAAU,MAAM,CAqClB;AAED;;;;;;;;;;GAUG;AACH,8CAHW,MAAM,GACJ,MAAM,EAAE,CAoBpB"}
+{"version":3,"file":"aperant-section.d.mts","sourceRoot":"","sources":["../../../src/cli/util/aperant-section.mjs"],"names":[],"mappings":"AAqEA;;;;;;;;;;;;;;;GAeG;AACH,mEAXG;IAAqB,aAAa,EAA1B,MAAM;IAGO,SAAS,EAAtB,MAAM;IACQ,GAAG;CAGzB,GAAU,MAAM,CAqClB;AAED;;;;;;;;;;GAUG;AACH,8CAHW,MAAM,GACJ,MAAM,EAAE,CAoBpB;AA5HD;;;;;;;;;GASG;AACH,oCAA8F;AAC9F,0CACoE"}

package/dist/cli/util/aperant-section.mjs

@@ -20,6 +20,18 @@ import { getTrustedSkillSources } from '../config/load.mjs';
 import { discoverSkills } from '../route/skill-discover.mjs';
 const SECTION_START = '<!-- APT:framework-start -->';
 const SECTION_END = '<!-- APT:framework-end -->';
+/**
+ * Matches the full APT managed block (start marker through end marker,
+ * inclusive). Exported so callers in the same package can reference a
+ * single source rather than inlining duplicate regex literals.
+ *
+ * `APT_SECTION_RE`       — no trailing newline; used for in-place replace.
+ * `APT_SECTION_STRIP_RE` — includes optional trailing newline; used for
+ *                          strip operations that want to remove the newline
+ *                          the block was preceded/followed by.
+ */
+export const APT_SECTION_RE = /<!-- APT:framework-start -->[\s\S]*?<!-- APT:framework-end -->/;
+export const APT_SECTION_STRIP_RE = /<!-- APT:framework-start -->[\s\S]*?<!-- APT:framework-end -->\n?/;
 const SECTION_HEADING = '## Aperant Framework';
 const APPENDIX_REL_PATH = ['templates', 'aperant-claude-md-appendix.md'];
 /**

package/dist/cli/util/aperant-section.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"aperant-section.mjs","sourceRoot":"","sources":["../../../src/cli/util/aperant-section.mjs"],"names":[],"mappings":"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"}
+{"version":3,"file":"aperant-section.mjs","sourceRoot":"","sources":["../../../src/cli/util/aperant-section.mjs"],"names":[],"mappings":"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"}

package/dist/cli/util/copy.d.mts

@@ -1,4 +1,31 @@
 export function copyDirRecursive(src: any, dest: any): void;
+/**
+ * Preflight-only sibling of `injectInstructionFile`. Runs the same
+ * foreign-row defensive check against `filePath` but NEVER writes — used by
+ * the multi-target init flow to check every instruction target up-front so a
+ * single aborting target leaves NO file partially written (US-03 / AC3).
+ *
+ * Returns the same status vocabulary as `injectInstructionFile` minus the
+ * write side-effect: `'created'` (file absent → would be appended-to),
+ * `'updated'` (markers present, no foreign rows → would be replaced),
+ * `'aborted-foreign-rows'` (markers present with rows not in the generated
+ * set → init must abort). `force` short-circuits the foreign-row gate exactly
+ * as the writer does.
+ *
+ * @param {string} filePath
+ * @param {Object} opts
+ * @param {string} opts.aptSection   Output of buildAptSection().
+ * @param {boolean} [opts.force=false]
+ *                                    Bypass the foreign-row check.
+ * @returns {{ status: 'created' | 'updated' | 'aborted-foreign-rows', foreignRowIds?: string[] }}
+ */
+export function checkInstructionFile(filePath: string, { aptSection, force }: {
+    aptSection: string;
+    force?: boolean | undefined;
+}): {
+    status: "created" | "updated" | "aborted-foreign-rows";
+    foreignRowIds?: string[];
+};
 /**
  * Write the (already-generated) APT section into `filePath`. Creates the
  * file if missing; replaces the section in-place if the markers are

package/dist/cli/util/copy.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"copy.d.mts","sourceRoot":"","sources":["../../../src/cli/util/copy.mjs"],"names":[],"mappings":"AAwBA,4DAWC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,gDARW,MAAM,yBAEd;IAAqB,UAAU,EAAvB,MAAM;IAES,KAAK;CAE5B,GAAU;IAAE,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,sBAAsB,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CA0BlH"}
+{"version":3,"file":"copy.d.mts","sourceRoot":"","sources":["../../../src/cli/util/copy.mjs"],"names":[],"mappings":"AAsCA,4DAWC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,+CAPW,MAAM,yBAEd;IAAqB,UAAU,EAAvB,MAAM;IACS,KAAK;CAE5B,GAAU;IAAE,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,sBAAsB,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAgBhG;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,gDARW,MAAM,yBAEd;IAAqB,UAAU,EAAvB,MAAM;IAES,KAAK;CAE5B,GAAU;IAAE,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,sBAAsB,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAqBlH"}

package/dist/cli/util/copy.mjs

@@ -12,7 +12,20 @@
  */
 import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from 'node:fs';
 import { join } from 'node:path';
-import { extractAptSectionRowIds } from './aperant-section.mjs';
+import { APT_SECTION_RE, extractAptSectionRowIds } from './aperant-section.mjs';
+/**
+ * Return the row IDs present in `existing` that are NOT present in
+ * `aptSection`. An empty array means no foreign rows (safe to overwrite).
+ *
+ * @param {string} existing   Current on-disk file contents.
+ * @param {string} aptSection Output of buildAptSection().
+ * @returns {string[]}
+ */
+function computeForeignRowIds(existing, aptSection) {
+    const existingIds = new Set(extractAptSectionRowIds(existing));
+    const generatedIds = new Set(extractAptSectionRowIds(aptSection));
+    return [...existingIds].filter((id) => !generatedIds.has(id));
+}
 export function copyDirRecursive(src, dest) {
     mkdirSync(dest, { recursive: true });
     for (const entry of readdirSync(src, { withFileTypes: true })) {
@@ -26,6 +39,39 @@ export function copyDirRecursive(src, dest) {
         }
     }
 }
+/**
+ * Preflight-only sibling of `injectInstructionFile`. Runs the same
+ * foreign-row defensive check against `filePath` but NEVER writes — used by
+ * the multi-target init flow to check every instruction target up-front so a
+ * single aborting target leaves NO file partially written (US-03 / AC3).
+ *
+ * Returns the same status vocabulary as `injectInstructionFile` minus the
+ * write side-effect: `'created'` (file absent → would be appended-to),
+ * `'updated'` (markers present, no foreign rows → would be replaced),
+ * `'aborted-foreign-rows'` (markers present with rows not in the generated
+ * set → init must abort). `force` short-circuits the foreign-row gate exactly
+ * as the writer does.
+ *
+ * @param {string} filePath
+ * @param {Object} opts
+ * @param {string} opts.aptSection   Output of buildAptSection().
+ * @param {boolean} [opts.force=false]
+ *                                    Bypass the foreign-row check.
+ * @returns {{ status: 'created' | 'updated' | 'aborted-foreign-rows', foreignRowIds?: string[] }}
+ */
+export function checkInstructionFile(filePath, { aptSection, force = false }) {
+    const existing = existsSync(filePath) ? readFileSync(filePath, 'utf-8') : '';
+    if (existing.includes('<!-- APT:framework-start -->')) {
+        if (!force) {
+            const foreignRowIds = computeForeignRowIds(existing, aptSection);
+            if (foreignRowIds.length > 0) {
+                return { status: 'aborted-foreign-rows', foreignRowIds };
+            }
+        }
+        return { status: 'updated' };
+    }
+    return { status: 'created' };
+}
 /**
  * Write the (already-generated) APT section into `filePath`. Creates the
  * file if missing; replaces the section in-place if the markers are
@@ -50,14 +96,12 @@ export function injectInstructionFile(filePath, { aptSection, force = false }) {
     const existing = existsSync(filePath) ? readFileSync(filePath, 'utf-8') : '';
     if (existing.includes('<!-- APT:framework-start -->')) {
         if (!force) {
-            const existingIds = new Set(extractAptSectionRowIds(existing));
-            const generatedIds = new Set(extractAptSectionRowIds(aptSection));
-            const foreignRowIds = [...existingIds].filter((id) => !generatedIds.has(id));
+            const foreignRowIds = computeForeignRowIds(existing, aptSection);
             if (foreignRowIds.length > 0) {
                 return { status: 'aborted-foreign-rows', written: false, foreignRowIds };
             }
         }
-        const updated = existing.replace(/<!-- APT:framework-start -->[\s\S]*?<!-- APT:framework-end -->/, aptSection);
+        const updated = existing.replace(APT_SECTION_RE, aptSection);
         writeFileSync(filePath, updated, 'utf-8');
         return { status: 'updated', written: true };
     }

package/dist/cli/util/copy.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"copy.mjs","sourceRoot":"","sources":["../../../src/cli/util/copy.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACN,YAAY,EACZ,UAAU,EACV,SAAS,EACT,WAAW,EACX,YAAY,EACZ,aAAa,GACb,MAAM,SAAS,CAAA;AAChB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAA;AAE/D,MAAM,UAAU,gBAAgB,CAAC,GAAG,EAAE,IAAI;IACzC,SAAS,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACpC,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QAC/D,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;QACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;QACvC,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACzB,gBAAgB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;QACpC,CAAC;aAAM,CAAC;YACP,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;QAChC,CAAC;IACF,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAQ,EAAE,EAAE,UAAU,EAAE,KAAK,GAAG,KAAK,EAAE;IAC5E,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;IAE5E,IAAI,QAAQ,CAAC,QAAQ,CAAC,8BAA8B,CAAC,EAAE,CAAC;QACvD,IAAI,CAAC,KAAK,EAAE,CAAC;YACZ,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,uBAAuB,CAAC,QAAQ,CAAC,CAAC,CAAA;YAC9D,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,uBAAuB,CAAC,UAAU,CAAC,CAAC,CAAA;YACjE,MAAM,aAAa,GAAG,CAAC,GAAG,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAA;YAC5E,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC9B,OAAO,EAAE,MAAM,EAAE,sBAAsB,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,CAAA;YACzE,CAAC;QACF,CAAC;QACD,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAC/B,gEAAgE,EAChE,UAAU,CACV,CAAA;QACD,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;QACzC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;IAC5C,CAAC;IAED,uDAAuD;IACvD,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAA;IACnD,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,IAAI,EAAE,OAAO,CAAC,CAAA;IAC1E,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;AAC5C,CAAC"}
+{"version":3,"file":"copy.mjs","sourceRoot":"","sources":["../../../src/cli/util/copy.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACN,YAAY,EACZ,UAAU,EACV,SAAS,EACT,WAAW,EACX,YAAY,EACZ,aAAa,GACb,MAAM,SAAS,CAAA;AAChB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAA;AAE/E;;;;;;;GAOG;AACH,SAAS,oBAAoB,CAAC,QAAQ,EAAE,UAAU;IACjD,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,uBAAuB,CAAC,QAAQ,CAAC,CAAC,CAAA;IAC9D,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,uBAAuB,CAAC,UAAU,CAAC,CAAC,CAAA;IACjE,OAAO,CAAC,GAAG,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAA;AAC9D,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,GAAG,EAAE,IAAI;IACzC,SAAS,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACpC,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QAC/D,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;QACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;QACvC,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACzB,gBAAgB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;QACpC,CAAC;aAAM,CAAC;YACP,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;QAChC,CAAC;IACF,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAQ,EAAE,EAAE,UAAU,EAAE,KAAK,GAAG,KAAK,EAAE;IAC3E,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;IAE5E,IAAI,QAAQ,CAAC,QAAQ,CAAC,8BAA8B,CAAC,EAAE,CAAC;QACvD,IAAI,CAAC,KAAK,EAAE,CAAC;YACZ,MAAM,aAAa,GAAG,oBAAoB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAA;YAChE,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC9B,OAAO,EAAE,MAAM,EAAE,sBAAsB,EAAE,aAAa,EAAE,CAAA;YACzD,CAAC;QACF,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAA;IAC7B,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAA;AAC7B,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAQ,EAAE,EAAE,UAAU,EAAE,KAAK,GAAG,KAAK,EAAE;IAC5E,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;IAE5E,IAAI,QAAQ,CAAC,QAAQ,CAAC,8BAA8B,CAAC,EAAE,CAAC;QACvD,IAAI,CAAC,KAAK,EAAE,CAAC;YACZ,MAAM,aAAa,GAAG,oBAAoB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAA;YAChE,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC9B,OAAO,EAAE,MAAM,EAAE,sBAAsB,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,CAAA;YACzE,CAAC;QACF,CAAC;QACD,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,cAAc,EAAE,UAAU,CAAC,CAAA;QAC5D,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;QACzC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;IAC5C,CAAC;IAED,uDAAuD;IACvD,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAA;IACnD,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,IAAI,EAAE,OAAO,CAAC,CAAA;IAC1E,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;AAC5C,CAAC"}

package/dist/cli/verify-proof/idl/index.d.mts

@@ -1,2 +1,13 @@
-export { ASSERTION_VERBS, ASYNC_VERBS, EVIDENCE_VERBS, IDL_VERB_ARGS, IDL_VERB_NAMES, INTERACTION_VERBS, isVerbResult, LIFECYCLE_VERBS, validateVerbArgs } from "@aperant/framework/driver-sdk";
+export const ASSERTION_VERBS: readonly ["assert_visible", "assert_text", "assert_output", "assert_network"];
+export const ASYNC_VERBS: readonly ["trigger", "await_signal"];
+export const EVIDENCE_VERBS: readonly ["screenshot", "record_video", "capture_logs", "dump_state", "dom_dump"];
+export const IDL_VERB_ARGS: Readonly<Record<string, {
+    readonly required: readonly string[];
+    readonly optional: readonly string[];
+}>>;
+export const IDL_VERB_NAMES: readonly string[];
+export const INTERACTION_VERBS: readonly ["click", "type", "key", "navigate", "select", "upload_file", "drag_drop", "swipe", "switch_context", "execute_js", "wait_for_event", "wait_for_idle"];
+export const isVerbResult: typeof import("@aperant/framework/driver-sdk").isVerbResult;
+export const LIFECYCLE_VERBS: readonly ["launch", "teardown"];
+export const validateVerbArgs: typeof import("@aperant/framework/driver-sdk").validateVerbArgs;
 //# sourceMappingURL=index.d.mts.map

package/dist/cli/verify-proof/idl/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../../../src/cli/verify-proof/idl/index.mjs"],"names":[],"mappings":""}
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../../../src/cli/verify-proof/idl/index.mjs"],"names":[],"mappings":"AAoDA,4GAAmD;AACnD,+DAA2C;AAC3C,+GAAiD;AACjD;;;IAA+C;AAC/C,+CAAiD;AACjD,gMAAuD;AACvD,uFAA6C;AAC7C,8DAAmD;AACnD,+FAAqD"}

package/dist/cli/verify-proof/idl/index.mjs

@@ -8,6 +8,55 @@
  * refactor of every callsite.
  *
  * If you add a verb, edit packages/framework/src/driver-sdk/idl.ts.
+ *
+ * Defense-in-depth (issue #248). `@aperant/framework/driver-sdk` resolves
+ * via the package `exports` map to `dist/driver-sdk/index.js`. A *static*
+ * `export … from '@aperant/framework/driver-sdk'` here made this barrel —
+ * and therefore the whole apt-tools CLI, since `dispatch.mjs` eagerly
+ * imports `driver-doctor.mjs` which imports this barrel — crash at
+ * module-resolution time with an opaque `ERR_MODULE_NOT_FOUND` when the
+ * dist was not built (e.g. a CI step that skipped `pnpm build`), before
+ * any command body could run. Resolving the registry via a *dynamic*
+ * `await import()` wrapped in try/catch keeps that dependency off the
+ * hard module-link path: dist present (tests, post-build CI, published
+ * tarball) → the REAL registry values are re-exported unchanged; dist
+ * absent → empty/no-op fallbacks let the CLI load (so commands that don't
+ * touch the IDL registry, like `route`, still run) instead of crashing.
  */
-export { ASSERTION_VERBS, ASYNC_VERBS, EVIDENCE_VERBS, IDL_VERB_ARGS, IDL_VERB_NAMES, INTERACTION_VERBS, isVerbResult, LIFECYCLE_VERBS, validateVerbArgs, } from '@aperant/framework/driver-sdk';
+/** @type {typeof import('@aperant/framework/driver-sdk')} */
+let _sdk;
+try {
+    _sdk = await import('@aperant/framework/driver-sdk');
+}
+catch (err) {
+    // Only the intended "dist not built" condition degrades. A corrupt or
+    // partially-written dist (SyntaxError, broken transitive load) raises a
+    // different code and MUST surface, not be masked into an empty registry.
+    if (err?.code !== 'ERR_MODULE_NOT_FOUND')
+        throw err;
+    // dist/driver-sdk absent — degrade to empty registry so module load
+    // does not crash. Any code path that actually needs a verb registry
+    // (driver-doctor, the bundled drivers) requires a built dist anyway;
+    // commands that don't (e.g. `route`) keep working.
+    _sdk = {
+        ASSERTION_VERBS: [],
+        ASYNC_VERBS: [],
+        EVIDENCE_VERBS: [],
+        IDL_VERB_ARGS: {},
+        IDL_VERB_NAMES: [],
+        INTERACTION_VERBS: [],
+        isVerbResult: () => false,
+        LIFECYCLE_VERBS: [],
+        validateVerbArgs: () => ({ ok: true, errors: [] }),
+    };
+}
+export const ASSERTION_VERBS = _sdk.ASSERTION_VERBS;
+export const ASYNC_VERBS = _sdk.ASYNC_VERBS;
+export const EVIDENCE_VERBS = _sdk.EVIDENCE_VERBS;
+export const IDL_VERB_ARGS = _sdk.IDL_VERB_ARGS;
+export const IDL_VERB_NAMES = _sdk.IDL_VERB_NAMES;
+export const INTERACTION_VERBS = _sdk.INTERACTION_VERBS;
+export const isVerbResult = _sdk.isVerbResult;
+export const LIFECYCLE_VERBS = _sdk.LIFECYCLE_VERBS;
+export const validateVerbArgs = _sdk.validateVerbArgs;
 //# sourceMappingURL=index.mjs.map

package/dist/cli/verify-proof/idl/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../../../../src/cli/verify-proof/idl/index.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACN,eAAe,EACf,WAAW,EACX,cAAc,EACd,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,gBAAgB,GAChB,MAAM,+BAA+B,CAAA"}
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../../../../src/cli/verify-proof/idl/index.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,6DAA6D;AAC7D,IAAI,IAAI,CAAA;AACR,IAAI,CAAC;IACJ,IAAI,GAAG,MAAM,MAAM,CAAC,+BAA+B,CAAC,CAAA;AACrD,CAAC;AAAC,OAAO,GAAG,EAAE,CAAC;IACd,sEAAsE;IACtE,wEAAwE;IACxE,yEAAyE;IACzE,IAAI,GAAG,EAAE,IAAI,KAAK,sBAAsB;QAAE,MAAM,GAAG,CAAA;IACnD,oEAAoE;IACpE,oEAAoE;IACpE,qEAAqE;IACrE,mDAAmD;IACnD,IAAI,GAAG;QACN,eAAe,EAAE,EAAE;QACnB,WAAW,EAAE,EAAE;QACf,cAAc,EAAE,EAAE;QAClB,aAAa,EAAE,EAAE;QACjB,cAAc,EAAE,EAAE;QAClB,iBAAiB,EAAE,EAAE;QACrB,YAAY,EAAE,GAAG,EAAE,CAAC,KAAK;QACzB,eAAe,EAAE,EAAE;QACnB,gBAAgB,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;KAClD,CAAA;AACF,CAAC;AAED,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC,eAAe,CAAA;AACnD,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,CAAA;AAC3C,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,CAAA;AACjD,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,CAAA;AAC/C,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,CAAA;AACjD,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,CAAA;AACvD,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,CAAA;AAC7C,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC,eAAe,CAAA;AACnD,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,CAAA"}

package/dist/cli/verify-proof/resolver.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"resolver.d.mts","sourceRoot":"","sources":["../../../src/cli/verify-proof/resolver.mjs"],"names":[],"mappings":"AA0CA;;;;;;;GAOG;AACH,sCALW,cAAc,GAAG;IAAC,QAAQ,CAAC,EAAE,SAAS,GAAC,MAAM,GAAC,UAAU,CAAA;CAAC,WACzD,mBAAmB,YACnB,MAAM,EAAE,GACN;IAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAC,CAU9C;AA0CD;;;;;;;;;;;;GAYG;AACH,oCARG;IAA+B,OAAO,EAA9B,cAAc,EAAE;IACU,OAAO,EAAjC,mBAAmB;IACJ,qBAAqB,EAApC,MAAM,EAAE;IACQ,kBAAkB;IAClB,QAAQ;CAChC,GAAU;IAAC,QAAQ,EAAE,cAAc,CAAC;IAAC,iBAAiB,EAAE,KAAK,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;CAAC,CAqFrG;AAED;;;;;;;;;;GAUG;AACH,+CAHW,CAAC,UAAU,GAAC,KAAK,GAAC,KAAK,GAAC,KAAK,CAAC,GAC5B,CAAC,aAAa,GAAC,iBAAiB,GAAC,UAAU,CAAC,CAcxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,gDARG;IAA+B,OAAO,EAA9B,cAAc,EAAE;IACU,OAAO,EAAjC,mBAAmB;IAC6D,QAAQ,EAAxF,KAAK,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,UAAU,GAAC,KAAK,GAAC,KAAK,GAAC,KAAK,GAAC,cAAc,CAAA;KAAC,CAAC;IACzD,QAAQ;IACR,kBAAkB;IAClB,qBAAqB;CAC7C,GAAU,KAAK,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,iBAAiB,EAAE,KAAK,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;CAAC,CAAC,CA2C/I;6BAnQY,OAAO,+BAA+B,EAAE,cAAc;kCACtD,OAAO,sBAAsB,EAAE,mBAAmB"}
+{"version":3,"file":"resolver.d.mts","sourceRoot":"","sources":["../../../src/cli/verify-proof/resolver.mjs"],"names":[],"mappings":"AAyFA;;;;;;;GAOG;AACH,sCALW,cAAc,GAAG;IAAC,QAAQ,CAAC,EAAE,SAAS,GAAC,MAAM,GAAC,UAAU,CAAA;CAAC,WACzD,mBAAmB,YACnB,MAAM,EAAE,GACN;IAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAC,CAU9C;AA0CD;;;;;;;;;;;;GAYG;AACH,oCARG;IAA+B,OAAO,EAA9B,cAAc,EAAE;IACU,OAAO,EAAjC,mBAAmB;IACJ,qBAAqB,EAApC,MAAM,EAAE;IACQ,kBAAkB;IAClB,QAAQ;CAChC,GAAU;IAAC,QAAQ,EAAE,cAAc,CAAC;IAAC,iBAAiB,EAAE,KAAK,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;CAAC,CAqFrG;AAED;;;;;;;;;;GAUG;AACH,+CAHW,CAAC,UAAU,GAAC,KAAK,GAAC,KAAK,GAAC,KAAK,CAAC,GAC5B,CAAC,aAAa,GAAC,iBAAiB,GAAC,UAAU,CAAC,CAcxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,gDARG;IAA+B,OAAO,EAA9B,cAAc,EAAE;IACU,OAAO,EAAjC,mBAAmB;IAC6D,QAAQ,EAAxF,KAAK,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,UAAU,GAAC,KAAK,GAAC,KAAK,GAAC,KAAK,GAAC,cAAc,CAAA;KAAC,CAAC;IACzD,QAAQ;IACR,kBAAkB;IAClB,qBAAqB;CAC7C,GAAU,KAAK,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,iBAAiB,EAAE,KAAK,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;CAAC,CAAC,CA2C/I;6BApTY,OAAO,+BAA+B,EAAE,cAAc;kCACtD,OAAO,sBAAsB,EAAE,mBAAmB"}

package/dist/cli/verify-proof/resolver.mjs

@@ -29,11 +29,61 @@
  *
  * Existing `resolveDriver()` and `scoreDriver()` exports are unchanged.
  */
-import { UnsatisfiedRequiredCapabilityError } from '@aperant/framework/driver-sdk';
 /**
  * @typedef {import('@aperant/framework/driver-sdk').DriverManifest} DriverManifest
  * @typedef {import('./runtime-detect.mjs').RuntimeCapabilities} RuntimeCapabilities
  */
+/**
+ * Defense-in-depth (issue #248). The driver-sdk error class lives in
+ * `@aperant/framework/driver-sdk`, whose `exports` map resolves to
+ * `dist/driver-sdk/index.js`. An eager *static* top-level
+ * `import { UnsatisfiedRequiredCapabilityError } from '@aperant/framework/driver-sdk'`
+ * made the WHOLE apt-tools CLI crash at module-resolution time when the
+ * dist was not built (e.g. a CI step that skipped `pnpm build`): the
+ * static import is resolved at module-link, so an opaque
+ * `ERR_MODULE_NOT_FOUND` was raised before any command body — or any
+ * `--no-fail` downgrade in run-route-eval.mjs — could run.
+ *
+ * We instead resolve the class via a *dynamic* `await import()` that is
+ * wrapped in try/catch. Dynamic import is still evaluated at module
+ * load (top-level await), but its failure is now swallowable rather than
+ * a hard link-time crash:
+ *   - dist present (tests, post-build CI, published tarball) → the REAL
+ *     class is bound, so any thrown error stays
+ *     `instanceof UnsatisfiedRequiredCapabilityError` for every consumer
+ *     (including the resolver suites that import the class from the same
+ *     `@aperant/framework/driver-sdk` ESM specifier);
+ *   - dist absent → we fall back to a structurally identical local class
+ *     (same `.name` / `.capability` / `.attempts` shape, which
+ *     `detect-runtime.mjs` inspects via `.attempts`) so the CLI degrades
+ *     to a clear, catchable error instead of crashing at load.
+ *
+ * `resolveDriver` stays fully synchronous — the class is already bound by
+ * the time any importer of this module finishes linking.
+ *
+ * @type {new (message: string, capability?: string, attempts?: ReadonlyArray<{driver_id: string, reason: string}>) => Error}
+ */
+let UnsatisfiedRequiredCapabilityError;
+try {
+    ;
+    ({ UnsatisfiedRequiredCapabilityError } = await import('@aperant/framework/driver-sdk'));
+}
+catch (err) {
+    // Only the intended "dist not built" condition degrades. A corrupt or
+    // partially-written dist (SyntaxError, broken transitive load) raises a
+    // different code and MUST surface, not be masked into a silent fallback.
+    if (err?.code !== 'ERR_MODULE_NOT_FOUND')
+        throw err;
+    // dist/driver-sdk absent — degrade instead of crashing the CLI.
+    UnsatisfiedRequiredCapabilityError = class UnsatisfiedRequiredCapabilityError extends Error {
+        constructor(message, capability, attempts = []) {
+            super(message);
+            this.name = 'UnsatisfiedRequiredCapabilityError';
+            this.capability = capability;
+            this.attempts = attempts;
+        }
+    };
+}
 const STABILITY_RANK = { ga: 3, beta: 2, experimental: 1 };
 const LOCALITY_RANK = { bundled: 3, user: 2, registry: 1 };
 /**

package/dist/cli/verify-proof/resolver.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"resolver.mjs","sourceRoot":"","sources":["../../../src/cli/verify-proof/resolver.mjs"],"names":[],"mappings":"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"}
+{"version":3,"file":"resolver.mjs","sourceRoot":"","sources":["../../../src/cli/verify-proof/resolver.mjs"],"names":[],"mappings":"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"}

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

@@ -1,6 +1,6 @@
 {
   "name": "aperant",
-  "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": {
     "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/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." }
     ]
   },
   {