@dtlabs/ai-toolkit 0.17.0 → 0.17.2

package/CHANGELOG.md

@@ -1,4 +1,24 @@
 ## 0.1.4 (2026-07-21)
+## [0.17.2](https://github.com/dtlab-tech/ai-toolkit/compare/v0.17.1...v0.17.2) (2026-10-12)
+
+
+### Bug Fixes
+
+* **am-phase1:** resume already-landed assessor output after a crash ([057916e](https://github.com/dtlab-tech/ai-toolkit/commit/057916e975cca4e98f838000309546bf2ceb8787))
+* **cli:** harden installer/CLI crash paths and fix several silent-failure bugs ([f93d18a](https://github.com/dtlab-tech/ai-toolkit/commit/f93d18a04cbea5a8d393102e3125170b170b6ae2))
+* **execution-ledger:** retry rename on transient EPERM instead of unlinking destination ([fc07a4c](https://github.com/dtlab-tech/ai-toolkit/commit/fc07a4c1fdad0f953dd38f7027bec96b0b8807c2))
+* **gaia-install-toolkit:** resolve self-contradiction on editing settings.local.json ([b385325](https://github.com/dtlab-tech/ai-toolkit/commit/b38532586f4661ef788b1178013991b81ecc0ea5))
+* harden workflow gates, CLI installer, and ledger durability ([a9e8b65](https://github.com/dtlab-tech/ai-toolkit/commit/a9e8b6509dea2ead6d63277835254eda8ba3e5e0))
+* **pm-phase:** bind Gate 1 approval to doc content, not just its text ([8f5b2f1](https://github.com/dtlab-tech/ai-toolkit/commit/8f5b2f1cbaa9262d1f11c559302b798dedcf4b4f))
+
+## [0.17.1](https://github.com/dtlab-tech/ai-toolkit/compare/v0.17.0...v0.17.1) (2026-10-08)
+
+
+### Bug Fixes
+
+* **task-executor:** persist the reviewer's raw response on its receipt ([487b267](https://github.com/dtlab-tech/ai-toolkit/commit/487b2676467b72d4f6649c784b9fc6311d7819ac))
+* **task-executor:** persist the reviewer's raw response on its receipt ([1ca8491](https://github.com/dtlab-tech/ai-toolkit/commit/1ca8491e81ea35cc27a5f5b9f2b970fe85b1aeef))
+
 ## [0.17.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.16.9...v0.17.0) (2026-10-08)
 
 

package/bin/cli.js

@@ -322,8 +322,10 @@ function writeManifest(destRoot, fileList, installationMode, fileHashes) {
   try {
     ensureDir(manifestPath);
     fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
+    return true;
   } catch (err) {
     console.log(dim(`Warning: could not write manifest — ${err.message}`));
+    return false;
   }
 }
 
@@ -372,11 +374,19 @@ async function runInstall(label, mappings, force, destRoot, dryRun = false, inst
   let keptCount    = 0;
 
   if (!dryRun) {
+    // A failed orphan removal (e.g. a locked file) must not abort the whole
+    // install — new/modified files still need copying and the manifest still
+    // needs writing. Warn and keep going; the orphan is left in place for a
+    // future run to retry.
     if (force) {
       for (const orphan of existingOrphans) {
-        moveToTrash(destRoot, orphan);
-        removedCount++;
-        console.log(`     ${clr('red', '∅')} ${dim(orphan)}`);
+        try {
+          moveToTrash(destRoot, orphan);
+          removedCount++;
+          console.log(`     ${clr('red', '∅')} ${dim(orphan)}`);
+        } catch (err) {
+          console.log(`     ${clr('yellow', '⚠')} Could not remove ${dim(orphan)} — ${err.message}`);
+        }
       }
     } else {
       for (const orphan of existingOrphans) {
@@ -384,9 +394,13 @@ async function runInstall(label, mappings, force, destRoot, dryRun = false, inst
         if (!fs.existsSync(fullPath)) continue;
         const ok = await askConfirm(`  Move to trash  ${clr('red', orphan)}?`);
         if (ok) {
-          moveToTrash(destRoot, orphan);
-          console.log(`     ${clr('green', '✔')} Moved to trash\n`);
-          removedCount++;
+          try {
+            moveToTrash(destRoot, orphan);
+            console.log(`     ${clr('green', '✔')} Moved to trash\n`);
+            removedCount++;
+          } catch (err) {
+            console.log(`     ${clr('yellow', '⚠')} Could not move to trash — ${err.message}\n`);
+          }
         } else {
           console.log(`     ${clr('gray', '✖')} Kept as-is\n`);
           keptCount++;
@@ -432,8 +446,7 @@ async function runInstall(label, mappings, force, destRoot, dryRun = false, inst
 
   if (modified.length === 0) {
     console.log(`  ${clr('green', '✔')}  All new files copied. No conflicts.\n`);
-    writeManifest(destRoot, newFileSet, installationMode, _buildFileHashes(destRoot, newFileSet));
-    return;
+    return writeManifest(destRoot, newFileSet, installationMode, _buildFileHashes(destRoot, newFileSet));
   }
 
   if (force) {
@@ -443,8 +456,7 @@ async function runInstall(label, mappings, force, destRoot, dryRun = false, inst
       fs.copyFileSync(e.src, e.dest);
       console.log(`     ${clr('yellow', '↺')} ${dim(path.relative(process.cwd(), e.dest))}`);
     }
-    writeManifest(destRoot, newFileSet, installationMode, _buildFileHashes(destRoot, newFileSet));
-    return;
+    return writeManifest(destRoot, newFileSet, installationMode, _buildFileHashes(destRoot, newFileSet));
   }
 
   console.log(`  ${clr('yellow', 'These files differ from the toolkit version — decide for each:')}\n`);
@@ -472,7 +484,7 @@ async function runInstall(label, mappings, force, destRoot, dryRun = false, inst
     `  ${clr('gray',  `✖ Kept as-is: ${skipped}`)}\n`
   );
 
-  writeManifest(destRoot, newFileSet, installationMode, _buildFileHashes(destRoot, newFileSet));
+  return writeManifest(destRoot, newFileSet, installationMode, _buildFileHashes(destRoot, newFileSet));
 }
 
 // Compute SHA-256 for every relative path in relPaths under destRoot.
@@ -1804,10 +1816,15 @@ async function installLocal(targetDir, force, dryRun = false) {
     { src: path.join(packageRoot, 'docs'),      dest: path.join(targetDir, 'docs') },
     { src: path.join(packageRoot, 'CLAUDE.md'), dest: path.join(targetDir, 'CLAUDE.md') },
   ];
-  await runInstall(`local project`, mappings, force, targetDir, dryRun, 'local');
+  const manifestWritten = await runInstall(`local project`, mappings, force, targetDir, dryRun, 'local');
   if (dryRun) return;
   writeInstalledVersion(targetDir);
-  console.log(`  ${clr('green', '✔')}  ${bold('Install complete.')}\n`);
+  if (manifestWritten === false) {
+    console.log(`  ${clr('yellow', '⚠')}  ${bold('Install complete, but the manifest could not be written.')}\n` +
+      `     Reinstall/orphan-cleanup detection will not see these files until it is.\n`);
+  } else {
+    console.log(`  ${clr('green', '✔')}  ${bold('Install complete.')}\n`);
+  }
   checkSpawnDepth(targetDir);
   console.log(divider());
   console.log(`\n  ${bold('Next steps:')}`);
@@ -1839,10 +1856,15 @@ async function installGlobal(force, dryRun = false, homeOverride = undefined) {
       { src: path.join(packageRoot, 'docs'),             dest: path.join(target, 'docs') },
       { src: path.join(packageRoot, 'CLAUDE.global.md'), dest: path.join(target, 'CLAUDE.md') },
     ];
-    await runInstall('global Claude folder', mappings, force, homedir, dryRun, 'global');
+    const manifestWritten = await runInstall('global Claude folder', mappings, force, homedir, dryRun, 'global');
     if (dryRun) return;
     writeInstalledVersion(homedir);
-    console.log(`  ${clr('green', '✔')}  ${bold('Global install complete.')}\n`);
+    if (manifestWritten === false) {
+      console.log(`  ${clr('yellow', '⚠')}  ${bold('Global install complete, but the manifest could not be written.')}\n` +
+        `     Reinstall/orphan-cleanup detection will not see these files until it is.\n`);
+    } else {
+      console.log(`  ${clr('green', '✔')}  ${bold('Global install complete.')}\n`);
+    }
     checkSpawnDepth(homedir);
     console.log(divider());
     console.log(`\n  ${bold('Next steps:')}`);
@@ -1891,7 +1913,9 @@ async function main() {
     if (sub === '--project') {
       await installLocal(argv[2] || '.', force, dryRun);
     } else if (sub === '--global') {
-      await installGlobal(force, dryRun);
+      const homeIdx = argv.indexOf('--home');
+      const homeOverride = homeIdx !== -1 ? argv[homeIdx + 1] : undefined;
+      await installGlobal(force, dryRun, homeOverride);
     } else {
       // No sub-flag: install into current directory (same as bare invocation)
       await installLocal(sub && !sub.startsWith('-') ? sub : '.', force, dryRun);
@@ -1955,6 +1979,10 @@ async function main() {
     const home       = homeIdx    !== -1 ? remaining[homeIdx    + 1] : undefined;
     runDoctorAgents({ projectDir, home });
     process.exit(0);
+  } else if (argv[0] === 'doctor') {
+    process.stderr.write(`Unknown doctor subcommand: ${argv[1] || '(none)'}\n` +
+      'Available: doctor resolution, doctor agents\n');
+    process.exit(1);
   } else if (argv[0] === 'validate-purity') {
     runValidatePurity(argv[1]);
   } else if (argv[0] === 'resolve-asset') {
@@ -2102,7 +2130,10 @@ async function main() {
     process.exit(0);
   } else if (argv[0] === 'resolve-features-root') {
     try {
-      const resolved = resolveFeaturesRoot(process.cwd());
+      const remaining = argv.slice(1);
+      const overrideIdx = remaining.indexOf('--features-root');
+      const featuresRoot = overrideIdx !== -1 ? remaining[overrideIdx + 1] : undefined;
+      const resolved = resolveFeaturesRoot(process.cwd(), { featuresRoot });
       process.stdout.write(resolved + '\n');
       process.exit(0);
     } catch (err) {
@@ -2495,17 +2526,31 @@ async function handleAgentsCommand(argv) {
     const effectiveHome    = home !== undefined ? path.resolve(home) : os.homedir();
     const effectiveProject = path.resolve(projectDir);
 
-    // Locate the active manifest (project-scoped takes precedence over global).
+    // Locate the active manifest. Both scopes present is ambiguous — matches
+    // agentRegistry.resolveAgent/listRegisteredAgents' own 'conflict' handling
+    // for the same dual-manifest case, rather than silently preferring project.
     const projectManifestPath = path.join(effectiveProject, '.claude', MANIFEST_FILE);
     const globalManifestPath  = path.join(effectiveHome,    '.claude', MANIFEST_FILE);
+    const hasProjectManifest  = fs.existsSync(projectManifestPath);
+    const hasGlobalManifest   = fs.existsSync(globalManifestPath);
+
+    if (hasProjectManifest && hasGlobalManifest) {
+      process.stdout.write(
+        JSON.stringify({ status: 'conflict', candidates: [], missing: [],
+          error: 'Both local and global toolkit installations found; installation is ambiguous. ' +
+                 'Remove one installation or reinstall to a single scope.' }, null, 2) + '\n'
+      );
+      process.exitCode = 0;
+      return;
+    }
 
     let installRoot    = null;
     let manifestData   = null;
 
-    if (fs.existsSync(projectManifestPath)) {
+    if (hasProjectManifest) {
       installRoot  = effectiveProject;
       manifestData = readJsonSafe(projectManifestPath);
-    } else if (fs.existsSync(globalManifestPath)) {
+    } else if (hasGlobalManifest) {
       installRoot  = effectiveHome;
       manifestData = readJsonSafe(globalManifestPath);
     }
@@ -2934,7 +2979,10 @@ async function handleExecutorCommand(argv) {
 // When required as a module (e.g., by Jest), skip main() and export pure
 // functions so they can be unit-tested without side effects.
 if (require.main === module) {
-  main();
+  main().catch(err => {
+    console.error(`\n  ${clr('red', '✖')}  ${err && err.message ? err.message : err}\n`);
+    process.exitCode = 1;
+  });
 } else {
   module.exports = {
     fileHash,
@@ -2947,6 +2995,7 @@ if (require.main === module) {
     moveToTrash,
     trashTimestamp,
     writeManifest,
+    runInstall,
     CANONICAL_ALLOW,
     CANONICAL_ASK,
     commandToPermission,

package/docs/task-executor-bootstrap.md

@@ -64,6 +64,32 @@ always throws `NOT_IMPLEMENTED` (exit 1, attributed to `US-06-TASK-BE-02`); unti
 deeper per-attempt evidence inspection means using `reconcile`/`resume`, both fully implemented
 and reporting each task's classification.
 
+**If the run ends up `blocked`: do not default to restarting from scratch.** `execute()` always
+mints a brand-new `runId` and resets every task to `pending` — a plain `start` on the same feature
+re-dispatches real, budget-consuming agents against tasks that already succeeded, re-proving work
+that is already correct and already committed. Found costing real budget on a real run across
+multiple restarts before anyone thought to check for an alternative: the alternative already
+exists, it is just never suggested at the one moment it matters.
+
+Before restarting, check whether `replan` + `start --from-replan-run-id` applies instead (full
+contract in `docs/task-executor-cli.md`'s `replan`/`start` sections):
+
+1. Confirm no worker from the blocked run is still live (`replan` itself refuses otherwise via
+   `LIVE_WORKER_BLOCKS_REPLAN` — this is enforced, not just advised).
+2. Call `replan` against the blocked run with a `--task-mapping-json` that maps every already-
+   `checkpointed`/`integrated` task to itself (or to its corrected ID, if the Work Breakdown
+   genuinely changed) — the successor plan does **not** need to differ from the original; "same
+   plan, just let me continue" is a valid, intended use, not only "the plan changed".
+3. Start the successor run with `--from-replan-run-id <the-blocked-run's-id>`. Every task
+   `replan` marked `carriesCompletion: true` is seeded straight to `checkpointed` — no
+   re-dispatch, no new commit, no re-spent budget — and only the tasks that genuinely still need
+   work are actually dispatched.
+
+This does **not** help a task that was completed by hand outside the executor entirely (direct
+subagent dispatch, no executor run ever recorded it) — `replan` can only carry forward evidence
+the executor itself already checkpointed. For that gap, see section 4c below
+("`resume()`/`reconcile()` only inspect and report").
+
 For the full flag reference, exit-code table, and JSON result schemas of every subcommand
 (`start`, `status`, `diagnose`, `stop`, `reconcile`, `resume`, `replan`), see
 `docs/task-executor-cli.md` — this document intentionally does not restate that contract.
@@ -205,6 +231,13 @@ the interrupted run will automatically finish its remaining tasks. `execute()` a
 brand-new run (a fresh `runId`, all tasks reset to pending); there is no run loop wired into
 `resume()`.
 
+**Update:** this gap now has a real, explicit (never automatic) partial workaround for the
+executor's own already-checkpointed work — see section 1's "If the run ends up `blocked`"
+guidance above (`replan` + `start --from-replan-run-id`). It still does not cover work completed
+entirely outside the executor (direct subagent dispatch that never recorded an attempt) — there
+is still no way to adopt that into the evidence trail short of a human/agent confirming it and
+deciding what to do by hand.
+
 ### d. Dormant concurrency gap in `dispatchTaskAttempt` (must be resolved before N>1 wiring)
 
 Confirmed by US-08-TASK-TEST-01 (`tests/task-executor/parallel.test.js`, commit `2f06883`),

package/lib/agent-registry.js

@@ -542,7 +542,12 @@ function _provenanceGuard(projectDir, agentId, platform, homeDir) {
       platform:   platform,
       nativeName: nativeName,
       status:     'manifest-missing',
-      error:      'No toolkit installation found; manifest absent at both project and global scope.',
+      // Precise claim: only the manifest is confirmed absent. Payload files or a
+      // version stamp may still be on disk (isToolkitInstalled in bin/cli.js checks
+      // those too) — this function cannot read agent registration data without a
+      // manifest, so it reports exactly that, not a broader "nothing is installed".
+      error:      'No installation manifest found at either project or global scope; ' +
+                  'agent registration data cannot be read.',
     };
   }
 

package/lib/execution-ledger.js

@@ -58,15 +58,59 @@ function _writeLedger(ledgerPath, entries) {
     throw err;
   }
 
-  try {
-    fs.renameSync(tmpPath, ledgerPath);
-  } catch (err) {
-    if (err.code === 'EEXIST' || err.code === 'EPERM') {
-      try { fs.unlinkSync(ledgerPath); } catch (_) {}
+  // Never unlink ledgerPath before/instead of the rename as a recovery step:
+  // fs.renameSync already atomically replaces an existing destination on every
+  // platform this runs on (POSIX rename(2); Windows via MoveFileEx with
+  // REPLACE_EXISTING). An EEXIST/EPERM-triggered unlink-then-rename "fallback"
+  // used to live here — if the process died in the window between that unlink
+  // succeeding and the rename completing (or if the rename then failed for an
+  // unrelated reason), the ledger file was simply gone, and _readLedger's
+  // ENOENT handling (above) treats a missing file as "empty, no error" — real,
+  // silent data loss, worse than the corrupt-ledger path this same module
+  // guards carefully via _backupCorruptFile.
+  //
+  // The EPERM/EEXIST this used to react to is real and transient, though
+  // (confirmed against a genuine, unmocked failure under parallel Windows test
+  // load, same "known environmental characteristic" docs/task-executor-
+  // bootstrap.md already documents for store.js's own rename) — something
+  // else briefly holds a handle on ledgerPath (antivirus, indexing, a
+  // concurrent reader). Retrying the SAME rename a bounded number of times
+  // with a short backoff gives that window a chance to close WITHOUT ever
+  // creating a moment where ledgerPath doesn't exist, unlike the old
+  // unlink-first approach.
+  let lastErr;
+  for (let attempt = 0; attempt < 5; attempt++) {
+    try {
       fs.renameSync(tmpPath, ledgerPath);
-    } else {
-      try { fs.unlinkSync(tmpPath); } catch (_) {}
-      throw err;
+      lastErr = null;
+      break;
+    } catch (err) {
+      lastErr = err;
+      if (err.code !== 'EPERM' && err.code !== 'EEXIST') break;
+      _sleepSync(20);
+    }
+  }
+  if (lastErr) {
+    try { fs.unlinkSync(tmpPath); } catch (_) {}
+    throw lastErr;
+  }
+  _fsyncDirSync(dir);
+}
+
+// Best-effort directory fsync after a rename — identical to, and genuinely
+// mirroring this time, lib/task-executor/store.js's own _fsyncDirSync.
+function _fsyncDirSync(dir) {
+  let dfd;
+  try {
+    dfd = fs.openSync(dir, 'r');
+    fs.fsyncSync(dfd);
+  } catch (_) {
+    // Directory-handle fsync is not supported on every platform/filesystem
+    // (notably Windows). Best-effort only — file fsync + rename already
+    // happened before this call.
+  } finally {
+    if (dfd !== undefined) {
+      try { fs.closeSync(dfd); } catch (_) {}
     }
   }
 }

package/lib/task-executor/index.js

@@ -715,7 +715,7 @@ function _extractReviewVerdict(spawnResult) {
     : null;
 
   if (text === null) {
-    return { passed: null, criticalFindings: [] };
+    return { passed: null, criticalFindings: [], responseText: null };
   }
 
   const verdictMatch = text.match(/Verdict:\s*(PASS|FAIL)/i);
@@ -754,7 +754,16 @@ function _extractReviewVerdict(spawnResult) {
     }
   }
 
-  return { passed: passed, criticalFindings: criticalFindings };
+  // Persisted verbatim on the review receipt (persistVerificationReviewOutcome)
+  // so a FAIL this function cannot fully explain — any future template
+  // variation neither the CRITICAL section nor the Build/Tests fold-in
+  // above recognizes — is still diagnosable from the receipt itself,
+  // instead of requiring the diff to be reconstructed and re-judged by hand
+  // after the fact (confirmed necessary against a real run: this exact
+  // "reviewPassed:false, criticalFindings:[]" shape recurred on a THIRD,
+  // previously-clean task, meaning the Build/Tests fold-in does not cover
+  // every real cause of an unexplained FAIL).
+  return { passed: passed, criticalFindings: criticalFindings, responseText: text };
 }
 
 /**
@@ -824,7 +833,8 @@ function _extractReviewVerdict(spawnResult) {
  *   runId: string, taskId: string, attemptNumber: number,
  *   agentId: string, nativeAgentName: string,
  *   ledgerOperationId: string, spawnResult: object,
- *   reviewPassed: (boolean|null), criticalFindings: string[]
+ *   reviewPassed: (boolean|null), criticalFindings: string[],
+ *   responseText: (string|null)
  * }>}
  * @throws {Error} NO_LOCK_HELD, AGENT_NOT_VERIFIED, DEFINITION_HASH_MISMATCH,
  *   DISPATCH_VALIDATION_ERROR, or any error surfaced by spawnClaudeAgent
@@ -918,6 +928,7 @@ async function runReview(args) {
     spawnResult: spawnResult,
     reviewPassed: verdict.passed,
     criticalFindings: verdict.criticalFindings,
+    responseText: verdict.responseText,
   };
 }
 

package/lib/task-executor/store.js

@@ -777,6 +777,14 @@ function persistVerificationReviewOutcome(executionRoot, runId, taskId, attemptN
       attemptNumber: attemptNumber,
       reviewPassed: review.reviewPassed === undefined ? null : review.reviewPassed,
       criticalFindings: review.criticalFindings,
+      // Verbatim review-solution reply, persisted so a FAIL neither the
+      // CRITICAL section nor the Build/Tests fold-in can explain
+      // (_extractReviewVerdict's own criticalFindings: [] either way) is
+      // still diagnosable from this receipt — never requires reconstructing
+      // and re-judging the diff by hand after the fact. null (never '') when
+      // the reply had no readable envelope at all — see
+      // _extractReviewVerdict's own null-compatibility.
+      responseText: review.responseText === undefined ? null : review.responseText,
       authoritative: verificationPassed === true,
     });
   }

package/lib/workflow-control.js

@@ -286,6 +286,10 @@ function createControl(options) {
     feature, parseArgs, tokenLedger, spent: () => spent,
     mtime: p => fs.statSync(full(p)).mtimeMs,
     json: p => JSON.parse(read(p)),
+    // Same 'sha256:'-prefixed format validateIdentity already uses for agent
+    // definition integrity (line ~40) — reused here to bind a Gate approval
+    // to the exact document content it approved, not just "a file exists".
+    hash: text => 'sha256:' + crypto.createHash('sha256').update(String(text), 'utf8').digest('hex'),
     log: text => (options.log || (() => {}))(String(text)),
     append: (p, text) => { fs.mkdirSync(path.dirname(full(p)), { recursive: true }); fs.appendFileSync(full(p), text); },
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtlabs/ai-toolkit",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "description": "AI Toolkit — reusable agents and procedures for developers to build AI-powered applications.",
   "files": [
     "docs/",

package/src/claude/agents/gaia-generate-work-breakdown.md

@@ -55,6 +55,8 @@ The prefix is everything up to and including the second hyphen-separated segment
 
 **Do NOT write `{PREFIX}-Work-Breakdown.md` or `{PREFIX}-Work-Breakdown.csv`.** Those are generated deterministically from the JSON by `wb-render.js` in a later pipeline step.
 
+"Authoritative" above means authoritative **for this agent's own generation and for `wb-validate.js`'s structural checks** — it does not mean every downstream reader consumes the JSON. The rendered `.md` (plus the dispatch `.csv`) is the tested, complete deliverable for everything that reads a Work Breakdown afterward: `lib/task-executor/plan.js` (the real task executor parses `.md`+`.csv`, never the JSON) and the `gaia-developer-*` agents both read the `.md`, and `tests/wb-render.*.test.js` specifically guards that every field they need (dependencies, verification commands, acceptance criteria, etc.) survives the JSON→Markdown rendering byte-for-byte. Only `gaia-validate-work-breakdown-semantic` reads the JSON directly, for its own programmatic comparison against Requirements ACs.
+
 ---
 
 ## Atomicity Contract

package/src/claude/agents/gaia-install-toolkit.md

@@ -243,6 +243,6 @@ If any modified files were kept by the user (not overwritten), list them so they
 
 - **Never overwrite `docs/procedures/` files** regardless of `--force` — project overrides take priority
 - **Never copy `install-toolkit.md`** — it's a toolkit-internal utility
-- **Never copy or edit `settings.json` / `settings.local.json`** — user-owned config; only verify and advise (Step 4b)
+- **The installer (Step 2) never copies `settings.json` / `settings.local.json`**, and Step 4's spawn-depth check is read-only (verify and advise, never write). The ONE exception is Step 6's Bash allowlist, which edits `settings.local.json` — but only via the dedicated `merge-allowlist` CLI, and only after the user explicitly opts in; never edit either file directly or outside that step
 - **Create directories as needed** — destination may not have `.claude/` yet
 - **Abort cleanly** if destination path is invalid — do not create partial installs

package/src/claude/skills/implement-feature/SKILL.md

@@ -7,7 +7,7 @@ argument-hint: <path-to-feature.md> [--force]
 
 Runs documentation and work breakdown through the deterministic Node workflow host, then implementation through the FTR-018 task executor. Approval gates remain in the main loop.
 
-Workflows are JavaScript assets, never agent types. Do not pass pm-phase1/2/3 or am-phase1/2 to agentType, subagent_type, or --agent. Use the workflow CLI below. Resolve the absolute Claude executable path as described in docs/task-executor-bootstrap.md.
+Workflows are JavaScript assets, never agent types. Do not pass pm-phase1/2/3 or am-phase1/2 to agentType, subagent_type, or --agent. Use the workflow CLI below. Resolve the absolute Claude executable path as described in `docs/task-executor-bootstrap.md` — never relative to this skill's own package directory (which holds only this `SKILL.md`, no `docs/` subfolder). That path is relative to wherever this toolkit's `docs/` landed for the install actually in use: the project root for a local install, or `~/.claude/` for a global install (`bin/cli.js`'s `installLocal`/`installGlobal` — a global install nests `docs/` under `~/.claude/docs/` alongside `skills/`/`agents/`; a local install places it at `<project-root>/docs/`, a sibling of `.claude/`, not inside it).
 
 ---
 
@@ -68,6 +68,8 @@ Extract from the result:
 - `requirements.summary` — requirements file summary
 - `tech_spec.summary` — tech-spec file summary
 - `validation.summary` — validation result (gaps or clean)
+- `docs_digest` — content digest binding this approval to the exact Requirements/Tech-Spec
+  bytes just produced; embed verbatim into `{PREFIX}-Approvals.md` in Step 2 below
 - `token_ledger` — array of per-agent token data from phase 1
 - `errors` — any agent failures during phase 1
 
@@ -117,6 +119,8 @@ The pipeline CANNOT continue until you reply directly.
 | {PREFIX}-Tech-Spec.md | ✅ Approved | {today} | {notes or —} |
 | {PREFIX}-Validation-Report.md | ✅ Approved | {today} | {notes or —} |
 
+**Docs Digest:** `{docs_digest}`
+
 ## Approval History
 
 | Cycle | Action | Date | Details |

package/src/claude/workflows/am-phase1.js

@@ -32,9 +32,21 @@ return c.run(meta.name, outputDir, prefix, async () => {
   // Neither assessor below has a Write tool: each returns its report as plain response
   // text, which the host persists to its declared `outputs` path (see worker()'s own
   // comment in lib/workflow-control.js for why — "Never ask an LLM to do I/O").
+  // Resume: unlike pm-phase1's own fresh() check, a crash between two assessors
+  // finishing and a third one still running used to force ALL of them to be
+  // re-dispatched from scratch on retry — c.parallel()'s own Promise.allSettled
+  // already lets the OTHER assessors' outputs land on disk even when one fails
+  // (confirmed in lib/workflow-control.js), but nothing here checked for that
+  // already-landed output before paying for a fresh dispatch. An assessor's own
+  // output is never partially written (worker() persists it only after a
+  // successful, fully-parsed response), so a non-empty existing file is safe to
+  // treat as already-done and skip.
   const assessmentResults = await c.parallel([...groups].map(([id, areas]) => async () => {
     const suffix = { 'gaia.agent.assessment.generic': 'Generic', 'gaia.agent.assessment.layered-architecture': 'Layer', 'gaia.agent.assessment.concurrency': 'Concurrency' }[id]
     const output_file = `${outputDir}/${prefix}-${suffix}-Assessment.md`
+    if (c.exists(output_file) && c.read(output_file).trim().length > 0) {
+      return { agent: id, scopes: areas, result: c.read(output_file), output_file }
+    }
     const result = await c.worker(id,
       `${targetPath} --prefix ${prefix} --output-dir ${outputDir}\n` +
       `Read-only assessment. Explicit scope: ${areas.join(', ')}. Inspect risks, evidence, severity and recommendations for EACH listed scope. ` +

package/src/claude/workflows/pm-phase1.js

@@ -31,24 +31,43 @@ return c.run(meta.name, featureDir, prefix, async () => {
   let validationSummary = 'skipped (fresh)'
   if (force || changed || !fresh(file('Validation-Report'), [featurePath, file('Requirements'), file('Tech-Spec')])) {
     for (let cycle = 1; cycle <= 3; cycle++) {
-      const result = await c.worker(valId, featurePath + '\nValidate only; the host owns the revision loop. Return valid, a findings array (one string per remaining gap), and the full validation report content. Do not dispatch other agents.', { label: `validation:${cycle}`, outputs: [output('Validation-Report', [featurePath, file('Requirements'), file('Tech-Spec')])], schema: { type: 'object', properties: { valid: { type: 'boolean' }, findings: { type: 'array', items: { type: 'string' } }, report: { type: 'string' } }, required: ['valid', 'findings', 'report'] } })
-      const text = result.findings.join('\n')
-      if (result.valid && result.findings.length === 0) {
+      // needsRequirementsFix/needsTechSpecFix: explicit structured routing fields,
+      // not inferred by substring-matching the free-text `findings` array (which a
+      // finding mentioning both document names, or neither, would mis-route or
+      // silently skip). The validator agent itself decides which document(s) its
+      // own findings implicate.
+      const result = await c.worker(valId, featurePath + '\nValidate only; the host owns the revision loop. Return valid, a findings array (one string per remaining gap), needsRequirementsFix/needsTechSpecFix (true only if at least one finding implicates that document), and the full validation report content. Do not dispatch other agents.', { label: `validation:${cycle}`, outputs: [output('Validation-Report', [featurePath, file('Requirements'), file('Tech-Spec')])], schema: { type: 'object', properties: { valid: { type: 'boolean' }, findings: { type: 'array', items: { type: 'string' } }, needsRequirementsFix: { type: 'boolean' }, needsTechSpecFix: { type: 'boolean' }, report: { type: 'string' } }, required: ['valid', 'findings', 'needsRequirementsFix', 'needsTechSpecFix', 'report'] } })
+      // A model returning valid:true alongside non-empty findings (or valid:false
+      // with none) contradicts its own schema's intent — never silently treated as
+      // "not clean yet" and spent on another cycle without surfacing the
+      // inconsistency; fail closed instead of masking a confused response.
+      if (result.valid === (result.findings.length > 0)) {
+        throw new Error(`Validation agent returned a contradictory result on cycle ${cycle}: valid=${result.valid} with ${result.findings.length} finding(s)`)
+      }
+      if (result.valid) {
         if (!fresh(file('Validation-Report'), [featurePath, file('Requirements'), file('Tech-Spec')])) throw new Error('Validation agent did not produce its report')
         validationSummary = `0 gaps (clean on cycle ${cycle})`
         break
       }
       if (cycle === 3) throw new Error('Validation gaps remain after 3 cycles')
-      if (!text.includes('Tech-Spec') || text.includes('Requirements')) await requirements()
-      if (!text.includes('Requirements') || text.includes('Tech-Spec')) await techSpec()
+      if (!result.needsRequirementsFix && !result.needsTechSpecFix) throw new Error(`Validation agent reported gaps on cycle ${cycle} but flagged neither document for revision`)
+      if (result.needsRequirementsFix) await requirements()
+      if (result.needsTechSpecFix) await techSpec()
     }
   }
+  // Binds Gate 1's eventual approval to the EXACT Requirements/Tech-Spec bytes
+  // produced here, not just "a file named *-Requirements.md exists" — SKILL.md's
+  // Step 2 embeds this verbatim into Approvals.md, and pm-phase2.js's Gate 1 check
+  // fails closed if the current file content no longer matches it (content
+  // regenerated after approval, e.g. via a later --force run, must re-approve).
+  const docsDigest = c.hash(c.read(file('Requirements')) + '\u0000' + c.read(file('Tech-Spec')))
   c.append(`${featureDir}/${prefix}-process-log.txt`, `[${new Date().toISOString()}] pm-phase1: ${validationSummary}; Gate 1 approval requested\n`)
   return {
     prefix, feature_dir: featureDir, feature_path: featurePath,
     requirements: { path: file('Requirements'), summary: 'Requirements ready' },
     tech_spec: { path: file('Tech-Spec'), summary: 'Tech-Spec ready' },
     validation: { path: file('Validation-Report'), summary: validationSummary },
+    docs_digest: docsDigest,
     token_ledger: c.tokenLedger, errors: [],
   }
 })

package/src/claude/workflows/pm-phase2.js

@@ -14,6 +14,22 @@ return c.run(meta.name, featureDir, prefix, async () => {
   const approvals = c.read(file('Approvals.md'))
   const gate = approvals.match(/^## Gate 1\b[^\n]*\n([\s\S]*?)(?=^## |$(?![\s\S]))/m)
   if (!gate || !/✅\s*Approved/.test(gate[1])) throw new Error('Gate 1 approval evidence missing')
+  // Binds this approval to the EXACT Requirements/Tech-Spec content pm-phase1
+  // produced when it was approved (docs_digest, written into Approvals.md by
+  // SKILL.md's Step 2) — never just "a Gate 1 row says Approved". A missing
+  // digest (an approval recorded before this check existed) is not enforced,
+  // same null-compatible "unavailable, never fabricated" convention used
+  // throughout this toolkit; a PRESENT digest that no longer matches the
+  // current files fails closed — the approved documents changed since
+  // approval (e.g. a later --force re-run of pm-phase1) and must be
+  // re-approved, not silently carried forward on stale consent.
+  const digestMatch = gate[1].match(/\*\*Docs Digest:\*\*\s*`([^`]+)`/)
+  if (digestMatch) {
+    const currentDigest = c.hash(c.read(file('Requirements.md')) + '\u0000' + c.read(file('Tech-Spec.md')))
+    if (digestMatch[1] !== currentDigest) {
+      throw new Error('Gate 1 approval is stale: Requirements/Tech-Spec content no longer matches what was approved (docs digest mismatch) — re-approve Gate 1 before proceeding')
+    }
+  }
   const jsonPath = file('Work-Breakdown.json')
   await c.worker('gaia.agent.planner.work-breakdown', featurePath, {
     outputs: [{ path: jsonPath, inputs: [featurePath, file('Requirements.md'), file('Tech-Spec.md')] }],