@dtlabs/ai-toolkit 0.21.1 → 0.22.0

package/CHANGELOG.md

@@ -1,4 +1,29 @@
 ## 0.1.4 (2026-07-21)
+## [0.22.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.21.2...v0.22.0) (2026-10-21)
+
+
+### Features
+
+* **pm-phase1:** regenerating the Tech-Spec skeleton no longer forces every component to redispatch ([f28173b](https://github.com/dtlab-tech/ai-toolkit/commit/f28173b5dde57f8432eabcb7970af1feeb93711a))
+
+
+### Bug Fixes
+
+* **atomic-rename:** retry a transient Windows EPERM/EBUSY on rename across every atomic-write site ([737d871](https://github.com/dtlab-tech/ai-toolkit/commit/737d871eb98c7d8ea4015734931e344fcef8798e))
+* pm-phase1 AC/Tech-Spec regen, Windows rename retry, task-executor plan parsing & review scoping ([02767d0](https://github.com/dtlab-tech/ai-toolkit/commit/02767d055edea34eb488a46224655199d7c49e43))
+* **pm-phase1:** exempt an AC documented in Risks & Mitigations from the orphan-AC check ([a607306](https://github.com/dtlab-tech/ai-toolkit/commit/a60730650016c97d5895432b20120364f3e4db89))
+* **task-executor/plan:** parse task-detail anchors on CRLF-line-ended Work Breakdowns ([619764f](https://github.com/dtlab-tech/ai-toolkit/commit/619764ff5b4b1b9e4c2456da96ed3b43235aa74a))
+* **task-executor:** execute()/replan() fall back to the split wbs/ directory ([49df349](https://github.com/dtlab-tech/ai-toolkit/commit/49df34902c14f50e8121335700b3fe2f9b32b978))
+* **task-executor:** stop misattributing pre-existing uncommitted content to task commits ([04aee6c](https://github.com/dtlab-tech/ai-toolkit/commit/04aee6c8ab953c1a44997bee5842f7f89296c6d9))
+
+## [0.21.2](https://github.com/dtlab-tech/ai-toolkit/compare/v0.21.1...v0.21.2) (2026-10-21)
+
+
+### Bug Fixes
+
+* **pm-phase2:** read gaia-user-story-template.md via print-asset, not a local-install-relative path ([4913bcf](https://github.com/dtlab-tech/ai-toolkit/commit/4913bcfb71bd37b56d373d340abf9cee17478154))
+* read gaia-user-story-template.md via print-asset (global-install compatibility) ([29486d9](https://github.com/dtlab-tech/ai-toolkit/commit/29486d9eeec4ae6ea2abfe02ffba4753addfc9fb))
+
 ## [0.21.1](https://github.com/dtlab-tech/ai-toolkit/compare/v0.21.0...v0.21.1) (2026-10-20)
 
 

package/lib/atomic-rename.js

@@ -0,0 +1,49 @@
+'use strict';
+
+// Windows can transiently reject fs.renameSync with EPERM/EBUSY under concurrent I/O load (e.g.
+// antivirus/indexer briefly holding a handle open, or another process reading the destination)
+// even though the rename is logically valid and would succeed moments later — a well-documented
+// OS characteristic (the same reason packages like write-file-atomic retry this exact case on
+// Windows), not a defect in the atomic-write protocol around it. Previously documented in
+// docs/task-executor-bootstrap.md as an "operational characteristic, not a code defect" with no
+// actual mitigation; confirmed to recur on a real `executor start` run (not just under heavy
+// parallel-test-suite I/O), and Windows is the only platform this executor is qualified for (E-02)
+// — "just retry by hand" is not an acceptable permanent answer for the one supported platform.
+//
+// A short, bounded retry absorbs the transient case without masking a genuinely permanent failure
+// (a real permission problem, a file locked open for a long time) — those still fail after the
+// bound, exactly as before this existed. Every one of this module's 5 call sites (execution-ledger,
+// task-executor's store/ownership, workflow-control, workflow-worker-evidence) already implements
+// the identical temp-write-then-rename atomic protocol; this is the one place the rename step
+// itself gets hardened, instead of duplicating the same retry loop 5 times.
+const fs = require('fs');
+
+const RETRY_ERROR_CODES = new Set(['EPERM', 'EBUSY']);
+const MAX_ATTEMPTS = 5;
+const BACKOFF_MS = [10, 25, 50, 100, 200];
+
+// A true synchronous sleep (every call site here is itself synchronous, mirroring
+// fs.renameSync) — Atomics.wait on a SharedArrayBuffer-backed Int32Array is the standard,
+// correct way to block the current thread without a CPU-burning busy loop; no external
+// dependency, available in every Node version this project supports.
+function _sleepSyncMs(ms) {
+  const sab = new SharedArrayBuffer(4);
+  Atomics.wait(new Int32Array(sab), 0, 0, ms);
+}
+
+// Drop-in replacement for fs.renameSync(src, dest) — identical contract (throws on a genuinely
+// unrecoverable error, including after exhausting the retry bound), just resilient to the
+// specific transient Windows rename race already characterized above.
+function renameSyncWithRetry(src, dest) {
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    try {
+      fs.renameSync(src, dest);
+      return;
+    } catch (err) {
+      if (!RETRY_ERROR_CODES.has(err.code) || attempt === MAX_ATTEMPTS) throw err;
+      _sleepSyncMs(BACKOFF_MS[attempt - 1]);
+    }
+  }
+}
+
+module.exports = { renameSyncWithRetry };

package/lib/execution-ledger.js

@@ -8,6 +8,7 @@ const crypto = require('crypto');
 // — a destructured reference would capture the original function at require
 // time and bypass any later spy on the module's own export.
 const ownership = require('./task-executor/ownership');
+const { renameSyncWithRetry } = require('./atomic-rename');
 
 // ── Internal I/O helpers (stubs — implemented by INFRA-TASK-BE-03) ──────────
 
@@ -73,30 +74,20 @@ function _writeLedger(ledgerPath, entries) {
   // 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);
-      lastErr = null;
-      break;
-    } catch (err) {
-      lastErr = err;
-      if (err.code !== 'EPERM' && err.code !== 'EEXIST') break;
-      _sleepSync(20);
-    }
-  }
-  if (lastErr) {
+  // The EPERM this used to react to is real and transient (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, and since
+  // confirmed to recur on a real `executor start` run too, not just test-suite load) — something
+  // else briefly holds a handle on ledgerPath (antivirus, indexing, a concurrent reader).
+  // renameSyncWithRetry (lib/atomic-rename.js, shared by every atomic-write call site in this
+  // codebase) retries the SAME rename a bounded number of times with a short backoff, giving that
+  // window a chance to close WITHOUT ever creating a moment where ledgerPath doesn't exist, unlike
+  // the old unlink-first approach this comment originally warned against.
+  try {
+    renameSyncWithRetry(tmpPath, ledgerPath);
+  } catch (err) {
     try { fs.unlinkSync(tmpPath); } catch (_) {}
-    throw lastErr;
+    throw err;
   }
   _fsyncDirSync(dir);
 }

package/lib/task-executor/git.js

@@ -578,6 +578,36 @@ function detectChangedPaths(cwd) {
   return changedPaths;
 }
 
+// ── excludePreExistingPaths ──────────────────────────────────────────────────
+//
+// detectChangedPaths(cwd) reports EVERY uncommitted path in the whole
+// worktree — by design, the run loop dispatches directly against the real
+// project directory (maxConcurrency=1; isolated per-attempt worktrees are
+// US-08 parallel-execution scope only), and Tech-Spec section 8 requires
+// the review to see "exactly what will be checkpointed", which stageTaskFiles
+// then stages unmodified. If anything was ALREADY uncommitted in that
+// directory before this task's own attempt ever ran — most commonly this
+// feature's own Requirements/Tech-Spec/Work-Breakdown docs, left uncommitted
+// by design after Gate 1/Gate 2 approval (see implement-feature/SKILL.md) —
+// it would bleed into every task's review prompt (reproduced on a real run:
+// 400KB+ of unrelated planning docs on a 30-line task's review, "Prompt is
+// too long" on every attempt) and get silently committed into that task's
+// own commit via stageTaskFiles, misattributing unrelated content to it.
+//
+// Filters a "current" detectChangedPaths() result down to only the entries
+// that are NEW or changed relative to a "baseline" snapshot taken before the
+// task started (captured once per task, not per attempt, in
+// _runTaskToResolution — so a later attempt within the same task's retry
+// loop still correctly sees an earlier attempt's own real work, which is not
+// "pre-existing" relative to the TASK as a whole). A path present in both
+// snapshots with the SAME changeType is untouched by this task and excluded;
+// a new path, or one whose changeType differs, is this task's own work and
+// included.
+function excludePreExistingPaths(baselinePaths, currentPaths) {
+  const baselineByPath = new Map(baselinePaths.map(function (e) { return [e.path, e.changeType]; }));
+  return currentPaths.filter(function (e) { return baselineByPath.get(e.path) !== e.changeType; });
+}
+
 // ── createTaskCommit (US-05-TASK-BE-03) ─────────────────────────────────────
 //
 // Creates the task commit for an already-persisted checkpoint intent
@@ -1358,5 +1388,6 @@ module.exports = {
   stageTaskFiles,
   createTaskCommit,
   detectChangedPaths,
+  excludePreExistingPaths,
   integrateAttempt,
 };

package/lib/task-executor/index.js

@@ -2009,6 +2009,13 @@ async function _runTaskToResolution(ctx) {
   const taskId = task.id;
   const agentId = agentRegistry.resolveWorkBreakdownAgentType(task.agentType).canonicalId;
 
+  // Captured once per TASK (not per attempt, so a later retry still sees an
+  // earlier attempt's own real work as part of THIS task, not as pre-existing
+  // dirt) — see git.excludePreExistingPaths's own doc comment for the real
+  // bug this guards against (unrelated uncommitted content, most commonly
+  // this feature's own planning docs, bleeding into every task's review/commit).
+  const taskBaselineChangedPaths = git.detectChangedPaths(projectDir);
+
   for (;;) {
     let state = store.readState(executionRoot, runId);
     state = state.setTaskStatus(taskId, 'active');
@@ -2102,7 +2109,7 @@ async function _runTaskToResolution(ctx) {
       // Detected once per attempt (Gate-1 binding constraint #2's mandatory
       // negative test relies on this: a self-reported "success" that wrote
       // nothing real is caught here/by verification, never trusted alone).
-      changedPaths = git.detectChangedPaths(projectDir);
+      changedPaths = git.excludePreExistingPaths(taskBaselineChangedPaths, git.detectChangedPaths(projectDir));
       const diff = _computeReviewDiff(projectDir, changedPaths);
       review = await runReview({
         executionRoot: executionRoot, runId: runId, task: task, attemptNumber: attemptNumber,
@@ -2814,19 +2821,7 @@ async function execute(args) {
       'execute: could not derive a PREFIX (e.g. "FTR-018") from feature directory "' + featureDir + '"'
     );
   }
-  const mdPath = path.join(featureDir, prefix + '-Work-Breakdown.md');
-  const csvPath = path.join(featureDir, prefix + '-Work-Breakdown.csv');
-  let md;
-  let csv;
-  try {
-    md = fs.readFileSync(mdPath, 'utf8');
-    csv = fs.readFileSync(csvPath, 'utf8');
-  } catch (err) {
-    throw _err(
-      'PLAN_NOT_FOUND',
-      'execute: Work Breakdown MD/CSV not found at "' + mdPath + '" / "' + csvPath + '": ' + err.message
-    );
-  }
+  const { md, csv } = _loadPlanDocs(featureDir, prefix);
   // Propagates PLAN_PARSE_ERROR unmodified — a malformed/unapproved plan
   // never silently starts a run.
   const snapshot = plan.createPlanSnapshot(md, csv);
@@ -3799,6 +3794,50 @@ function _derivePrefix(featureDir) {
   return m ? m[1] : null;
 }
 
+// Loads this feature's plan source as MD/CSV text, trying the legacy rendered
+// view first and falling back to an in-memory render of the split wbs/
+// directory (schema v3) pm-phase2.js writes today. FTR-025 stopped writing
+// {PREFIX}-Work-Breakdown.md/.csv automatically — "nothing downstream ever
+// read" them, per that commit's own comment in pm-phase2.js — but this
+// executor was never updated to match, so the documented pm-phase1 -> Gate 1
+// -> pm-phase2 -> Gate 2 -> executor start flow threw PLAN_NOT_FOUND on
+// every feature using the current format (reported against a real
+// Fincantieri.ISDM.JobScheduler run).
+//
+// The render happens in-process (wb-render.js is required directly, not
+// shelled out to) and is never written to disk here — this function only
+// needs the MD/CSV text to feed plan.createPlanSnapshot unchanged; persisting
+// that view, if ever wanted, stays assemble-docs.js's job, same as today.
+function _loadPlanDocs(featureDir, prefix, errorCode, callerLabel) {
+  const code = errorCode || 'PLAN_NOT_FOUND';
+  const label = callerLabel || 'execute';
+  const mdPath = path.join(featureDir, prefix + '-Work-Breakdown.md');
+  const csvPath = path.join(featureDir, prefix + '-Work-Breakdown.csv');
+  try {
+    return { md: fs.readFileSync(mdPath, 'utf8'), csv: fs.readFileSync(csvPath, 'utf8') };
+  } catch (legacyErr) {
+    const wbsDir = path.join(featureDir, 'wbs');
+    const indexPath = path.join(wbsDir, 'index.json');
+    if (!fs.existsSync(indexPath)) {
+      throw _err(
+        code,
+        label + ': Work Breakdown not found — tried legacy "' + mdPath + '" / "' + csvPath +
+          '" (' + legacyErr.message + ') and split "' + indexPath + '" (does not exist)'
+      );
+    }
+    const { loadWorkBreakdown } = require('../../src/claude/scripts/wbs-assembler');
+    const { computePhaseDependsOn, renderMarkdown, renderCsv } = require('../../src/claude/scripts/wb-render');
+    let wb;
+    try {
+      wb = loadWorkBreakdown(wbsDir);
+    } catch (err) {
+      throw _err(code, label + ': failed to load split Work Breakdown "' + wbsDir + '": ' + err.message);
+    }
+    const phaseDepsMap = computePhaseDependsOn(wb);
+    return { md: renderMarkdown(wb, prefix, phaseDepsMap), csv: renderCsv(wb, prefix, phaseDepsMap) };
+  }
+}
+
 // Minimal, deliberately non-generic Markdown check: does a case-sensitive
 // "## Gate 2" heading appear anywhere in the successor's Approvals.md?
 //
@@ -4025,20 +4064,9 @@ async function replan(args) {
   // 2. Successor plan snapshot — real Work-Breakdown.md/.csv on disk, same
   // parser pipeline every other run uses (plan.createPlanSnapshot). Its own
   // PLAN_PARSE_ERROR propagates unmodified for a malformed successor plan.
-  const successorMdPath = path.join(successorFeatureDir, successorPrefix + '-Work-Breakdown.md');
-  const successorCsvPath = path.join(successorFeatureDir, successorPrefix + '-Work-Breakdown.csv');
-  let successorMd;
-  let successorCsv;
-  try {
-    successorMd = fs.readFileSync(successorMdPath, 'utf8');
-    successorCsv = fs.readFileSync(successorCsvPath, 'utf8');
-  } catch (err) {
-    throw _err(
-      'SUCCESSOR_PLAN_NOT_FOUND',
-      'replan: successor Work Breakdown MD/CSV not found at "' + successorMdPath + '" / "' +
-        successorCsvPath + '": ' + err.message
-    );
-  }
+  const { md: successorMd, csv: successorCsv } = _loadPlanDocs(
+    successorFeatureDir, successorPrefix, 'SUCCESSOR_PLAN_NOT_FOUND', 'replan'
+  );
   const successorSnapshot = plan.createPlanSnapshot(successorMd, successorCsv);
   const successorTaskIds = new Set(successorSnapshot.tasks.map(function (t) { return t.id; }));
 
@@ -4060,7 +4088,7 @@ async function replan(args) {
       throw _err(
         'REPLAN_UNKNOWN_TASK_MAPPING',
         'replan: taskMapping references newTaskId "' + entry.newTaskId +
-          '", which does not exist in the successor plan snapshot (' + successorMdPath + ')'
+          '", which does not exist in the successor plan snapshot (' + successorFeatureDir + ')'
       );
     }
   });

package/lib/task-executor/ownership.js

@@ -44,6 +44,7 @@ const os     = require('os');
 const path   = require('path');
 const crypto = require('crypto');
 const { spawnSync } = require('child_process');
+const { renameSyncWithRetry } = require('../atomic-rename');
 
 function _err(code, message) {
   const e = new Error(message);
@@ -127,8 +128,10 @@ function _atomicReplaceFileSync(filePath, contents) {
     throw err;
   }
 
+  // renameSyncWithRetry (lib/atomic-rename.js): absorbs a transient Windows EPERM/EBUSY on rename
+  // (docs/task-executor-bootstrap.md section 4b) — a genuinely permanent failure still throws.
   try {
-    fs.renameSync(tmpPath, filePath);
+    renameSyncWithRetry(tmpPath, filePath);
   } catch (err) {
     try { fs.unlinkSync(tmpPath); } catch (_) {}
     throw err;

package/lib/task-executor/plan.js

@@ -59,7 +59,7 @@ const _DASH = '—'; // '—' — the placeholder wb-render.js emits for absent
 const _FIELD_LINE_RE = /^- \*\*(.+?):\*\*[ \t]?(.*)$/gm;
 const _FENCE_RE = /^(`{3,})\r?\n([\s\S]*?)\r?\n\1[ \t]*$/gm;
 const _NO_VERIF_RE = /_No verification commands\._/;
-const _TASK_ANCHOR_RE = /<a id="task-[^"]*"><\/a>\n### ([^\n]+)\n([\s\S]*?)(?=\n<a id="task-|$)/g;
+const _TASK_ANCHOR_RE = /<a id="task-[^"]*"><\/a>\r?\n### ([^\r\n]+)\r?\n([\s\S]*?)(?=\r?\n<a id="task-|$)/g;
 
 function _listOrEmpty(value) {
   if (value === _DASH) return [];

package/lib/task-executor/store.js

@@ -20,6 +20,7 @@
 const fs     = require('fs');
 const path   = require('path');
 const crypto = require('crypto');
+const { renameSyncWithRetry } = require('../atomic-rename');
 
 // ── Schema vocabulary ────────────────────────────────────────────────────────
 
@@ -126,8 +127,12 @@ function _atomicWriteFileSync(filePath, contents) {
     throw err;
   }
 
+  // renameSyncWithRetry (lib/atomic-rename.js): Windows can transiently reject this rename with
+  // EPERM/EBUSY under concurrent I/O load — confirmed to recur on a real `executor start` run, not
+  // just under heavy test-suite load (docs/task-executor-bootstrap.md section 4b). A bounded retry
+  // absorbs the transient case; a genuinely permanent failure still throws, unchanged.
   try {
-    fs.renameSync(tmpPath, filePath);
+    renameSyncWithRetry(tmpPath, filePath);
   } catch (err) {
     try { fs.unlinkSync(tmpPath); } catch (_) {}
     throw err;

package/lib/workflow-control.js

@@ -10,6 +10,7 @@ const ledger = require('./execution-ledger');
 const { spawnClaudeAgent } = require('./task-executor/claude-process');
 const { createEvidence } = require('./workflow-worker-evidence');
 const { resolveOutputPath } = require('./workflow-worker-outputs');
+const { renameSyncWithRetry } = require('./atomic-rename');
 const CLI = path.join(__dirname, '..', 'bin', 'cli.js');
 
 
@@ -89,7 +90,8 @@ function createControl(options) {
     const dest = full(p);
     fs.mkdirSync(path.dirname(dest), { recursive: true });
     const tmp = dest + '.tmp-' + crypto.randomUUID();
-    try { fs.writeFileSync(tmp, content, 'utf8'); fs.renameSync(tmp, dest); }
+    // renameSyncWithRetry (./atomic-rename): absorbs a transient Windows EPERM/EBUSY on rename.
+    try { fs.writeFileSync(tmp, content, 'utf8'); renameSyncWithRetry(tmp, dest); }
     finally { if (fs.existsSync(tmp)) fs.unlinkSync(tmp); }
   };
   // Validates a worker-declared (or, for a dynamic multi-file deliverable like

package/lib/workflow-worker-evidence.js

@@ -4,6 +4,7 @@ const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 const os = require('os');
+const { renameSyncWithRetry } = require('./atomic-rename');
 
 // Do not capture the parent environment or stdin prompt. Diagnostic responses
 // can contain document text; redact common credential forms before persistence.
@@ -43,7 +44,8 @@ function createEvidence(options, runId, identity, invocation) {
     const temp = file + '.tmp';
     try {
       fs.writeFileSync(temp, JSON.stringify(redact(record), null, 2) + '\n', { mode: 0o600 });
-      fs.renameSync(temp, file);
+      // renameSyncWithRetry (./atomic-rename): absorbs a transient Windows EPERM/EBUSY on rename.
+      renameSyncWithRetry(temp, file);
     } finally { if (fs.existsSync(temp)) fs.unlinkSync(temp); }
   }
   save({});

package/package.json

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

package/src/claude/scripts/wb-render.js

@@ -4,49 +4,6 @@ const fs   = require('fs')
 const path = require('path')
 const { loadWorkBreakdown } = require('./wbs-assembler')
 
-// ── Argument parsing ──────────────────────────────────────────────────────────
-
-const jsonPath = process.argv[2]
-const prefix   = process.argv[3]
-
-if (!jsonPath || !prefix) {
-  process.stderr.write('Usage: node wb-render.js <path-to-work-breakdown.json> <feature-prefix> [destination-dir]\n')
-  process.exit(1)
-}
-
-const destDir = process.argv[4]
-  ? process.argv[4]
-  : path.dirname(path.resolve(jsonPath))
-
-// ── Read and assemble ──────────────────────────────────────────────────────────
-// Accepts either a single legacy JSON file (schema v2) or a {PREFIX}-wbs/ split
-// directory (schema v3), returning the same in-memory shape either way (FTR-020).
-
-let wb
-try {
-  wb = loadWorkBreakdown(jsonPath)
-} catch (err) {
-  process.stderr.write(`Error: ${err.message}\n`)
-  process.exit(1)
-}
-
-// ── Basic structure check ─────────────────────────────────────────────────────
-
-if (wb.schemaVersion !== 2) {
-  process.stderr.write(`Error: schemaVersion must be 2, got ${JSON.stringify(wb.schemaVersion)}\n`)
-  process.exit(2)
-}
-
-if (!Array.isArray(wb.phases)) {
-  process.stderr.write('Error: "phases" must be an array\n')
-  process.exit(2)
-}
-
-// ── Output file paths ─────────────────────────────────────────────────────────
-
-const mdPath  = path.join(destDir, `${prefix}-Work-Breakdown.md`)
-const csvPath = path.join(destDir, `${prefix}-Work-Breakdown.csv`)
-
 // ── Phase-level depends_on aggregation ───────────────────────────────────────
 
 function computePhaseDependsOn(wb) {
@@ -79,16 +36,6 @@ function computePhaseDependsOn(wb) {
   return result
 }
 
-// ── Compute phase dependencies ────────────────────────────────────────────────
-
-let phaseDepsMap
-try {
-  phaseDepsMap = computePhaseDependsOn(wb)
-} catch (err) {
-  process.stderr.write(`Error: phase dependency aggregation failed: ${err.message}\n`)
-  process.exit(3)
-}
-
 // ── Field helpers ─────────────────────────────────────────────────────────────
 
 function sanitizeField(str) {
@@ -393,11 +340,66 @@ function renderCsv(wb, prefix, phaseDepsMap) {
   return rows.join('\n') + '\n'
 }
 
-// ── Write files and exit ──────────────────────────────────────────────────────
+module.exports = {
+  computePhaseDependsOn,
+  renderMarkdown,
+  renderCsv,
+}
+
+// ── CLI entry point ───────────────────────────────────────────────────────────
+// Same require.main guard pattern as wbs-assembler.js: the functions above are
+// requirable in-process (lib/task-executor/index.js does exactly this, falling
+// back to an in-memory render of the split wbs/ directory when the legacy
+// {PREFIX}-Work-Breakdown.md/.csv files pm-phase2 no longer writes automatically
+// — FTR-025 — are absent), while this block only runs for the standalone CLI use
+// pm-phase2.js's workflow-script runtime (no `require`) and operators still rely on.
+if (require.main === module) {
+  const jsonPath = process.argv[2]
+  const prefix   = process.argv[3]
+
+  if (!jsonPath || !prefix) {
+    process.stderr.write('Usage: node wb-render.js <path-to-work-breakdown.json> <feature-prefix> [destination-dir]\n')
+    process.exit(1)
+  }
+
+  const destDir = process.argv[4]
+    ? process.argv[4]
+    : path.dirname(path.resolve(jsonPath))
+
+  // Accepts either a single legacy JSON file (schema v2) or a {PREFIX}-wbs/ split
+  // directory (schema v3), returning the same in-memory shape either way (FTR-020).
+  let wb
+  try {
+    wb = loadWorkBreakdown(jsonPath)
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message}\n`)
+    process.exit(1)
+  }
 
-const md  = renderMarkdown(wb, prefix, phaseDepsMap)
-const csv = renderCsv(wb, prefix, phaseDepsMap)
-fs.writeFileSync(mdPath, md, 'utf8')
-fs.writeFileSync(csvPath, csv, 'utf8')
-process.stdout.write(JSON.stringify({ exitCode: 0, markdownPath: mdPath, csvPath }) + '\n')
-process.exit(0)
+  if (wb.schemaVersion !== 2) {
+    process.stderr.write(`Error: schemaVersion must be 2, got ${JSON.stringify(wb.schemaVersion)}\n`)
+    process.exit(2)
+  }
+  if (!Array.isArray(wb.phases)) {
+    process.stderr.write('Error: "phases" must be an array\n')
+    process.exit(2)
+  }
+
+  const mdPath  = path.join(destDir, `${prefix}-Work-Breakdown.md`)
+  const csvPath = path.join(destDir, `${prefix}-Work-Breakdown.csv`)
+
+  let phaseDepsMap
+  try {
+    phaseDepsMap = computePhaseDependsOn(wb)
+  } catch (err) {
+    process.stderr.write(`Error: phase dependency aggregation failed: ${err.message}\n`)
+    process.exit(3)
+  }
+
+  const md  = renderMarkdown(wb, prefix, phaseDepsMap)
+  const csv = renderCsv(wb, prefix, phaseDepsMap)
+  fs.writeFileSync(mdPath, md, 'utf8')
+  fs.writeFileSync(csvPath, csv, 'utf8')
+  process.stdout.write(JSON.stringify({ exitCode: 0, markdownPath: mdPath, csvPath }) + '\n')
+  process.exit(0)
+}

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

@@ -221,6 +221,27 @@ If the branch already exists, switch to it without recreating:
 git checkout feature/{PREFIX}-{short-slug}
 ```
 
+### Step 5a — Commit the approved planning documents
+
+The task executor (Step 6) dispatches each task directly against this project directory and
+reviews/commits exactly what `git status` reports changed. If the planning documents this
+pipeline just produced (`<feature-dir>/` — feature.md, req/, spec/, wbs/, coverage-matrix/,
+`{PREFIX}-Approvals.md`, `{PREFIX}-Validation-Report.md`) are still sitting uncommitted at this
+point, every task's own review prompt and commit would be contaminated by them — reproduced on a
+real run (hundreds of KB of unrelated planning docs bleeding into a single task's own small diff,
+"Prompt is too long"). Commit them now, on the feature branch just created above, scoped to the
+feature's own directory only:
+
+```bash
+git add <feature-dir>
+git commit -m "docs({PREFIX}): commit approved Requirements/Tech-Spec/Work Breakdown"
+```
+
+Skip this commit if `git status --porcelain <feature-dir>` reports nothing (e.g. a resumed run
+where the docs were already committed in a prior pass) — do not fail or retry, an empty commit is
+never created. `<feature-dir>` is the directory containing feature.md (same directory derived in
+Step 0).
+
 ---
 
 ## Step 6 — Launch the task executor (Implementation Phase)

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

@@ -308,6 +308,20 @@ return c.run(meta.name, featureDir, prefix, async () => {
         if (!acIds.has(ref)) findings.push(`Tech-Spec: component ${comp.filePath} references nonexistent ${ref}`)
       }
     }
+    // FTR-030: a File-Inventory "Addresses" column only fits a positive, per-file deliverable — an
+    // AC describing a negative/process constraint (e.g. "no files under _old/ were modified",
+    // verified via git diff, never a dedicated component) can never be addressed that way, and was
+    // confirmed as a real, permanent false-positive orphan finding (no amount of regeneration could
+    // ever resolve it, since no component SHOULD exist for it). Section 12 (Risks & Mitigations) is
+    // the Tech-Spec's own existing, real place such constraints are already documented (confirmed
+    // against a real Tech-Spec) — an AC-ID mentioned there by its literal ID counts as addressed.
+    const specLines = specIndexContent.split('\n')
+    const { start: risksStart, end: risksEnd } = findReqSection(specLines, 12)
+    const risksText = risksStart === -1 ? '' : specLines.slice(risksStart, risksEnd).join('\n')
+    for (const id of acIds) {
+      const escapedId = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+      if (new RegExp(`\\b${escapedId}\\b`).test(risksText)) addressedAcIds.add(id)
+    }
     for (const id of acIds) {
       if (!addressedAcIds.has(id)) findings.push(`Tech-Spec: ${id} is not addressed by any Tech-Spec component`)
     }
@@ -424,6 +438,24 @@ return c.run(meta.name, featureDir, prefix, async () => {
       (!fresh(specIndexPath) || missingSections(c.read(specIndexPath), 12).length > 0)
     const regenSkeleton = forceAll || skeletonStale || !c.exists(specIndexPath)
 
+    // FTR-030: capture the OLD component rows (keyed by fileSlug — the stable per-component
+    // identity, a Spec-link target) BEFORE the skeleton is overwritten, so a NATURALLY-triggered
+    // skeleton regen (staleness/missing, never an explicit forceAll) doesn't force EVERY component
+    // to redispatch when only a FEW rows actually changed. Real incident: hand-editing 2 of ~58
+    // rows (adding a missing AC reference) triggered a full skeleton regeneration, which — with no
+    // per-row comparison — forced ALL ~88 components to redispatch even though the vast majority
+    // of rows were byte-identical to before. Deliberately NOT captured when forceAll is true: an
+    // explicit full regen (a `--force` run, or a needsTechSpecFix revision cycle) means something
+    // was flagged wrong that per-row diffing cannot see (e.g. a missing cross-reference only
+    // visible in a component's own body) — that path keeps today's existing "regenerate
+    // everything unconditionally" behavior, unchanged.
+    const oldComponentsByFileSlug = new Map()
+    if (!forceAll && regenSkeleton && c.exists(specIndexPath)) {
+      try {
+        for (const comp of parseComponentsTable(c.read(specIndexPath))) oldComponentsByFileSlug.set(comp.fileSlug, comp)
+      } catch (e) { /* an unparseable old skeleton has nothing worth diffing against — treat as empty */ }
+    }
+
     // 1. Skeleton (no declared worker() output — host writes it itself)
     if (regenSkeleton) {
       const skeleton = await c.worker(specId, withTemplate(featurePath, 'spec/index.md', 'gaia-tech-spec-index-template.md'))
@@ -449,7 +481,16 @@ return c.run(meta.name, featureDir, prefix, async () => {
     const componentTemplate = components.length ? readTemplate('gaia-component-template.md') : null
     for (const comp of components) {
       const compPath = `${specDir}/components/${comp.fileSlug}`
-      if (!regenSkeleton && c.exists(compPath) && isValidComponentDetail(c.read(compPath))) continue // resume: skip, no dispatch
+      // FTR-030: even when the skeleton itself was regenerated, a component whose OWN row is
+      // byte-identical to its prior version doesn't need a new design call — only a row that is
+      // NEW or actually CHANGED does. `regenSkeleton` alone used to force every component to
+      // redispatch unconditionally the moment the skeleton changed at all; this narrows that to
+      // rows that genuinely changed, while still regenerating any row that's new or different.
+      const oldComp = oldComponentsByFileSlug.get(comp.fileSlug)
+      const rowUnchanged = !!oldComp && oldComp.filePath === comp.filePath &&
+        oldComp.changeType === comp.changeType && oldComp.purposeOrChange === comp.purposeOrChange &&
+        oldComp.addresses === comp.addresses && oldComp.domain === comp.domain
+      if ((!regenSkeleton || rowUnchanged) && c.exists(compPath) && isValidComponentDetail(c.read(compPath))) continue // resume: skip, no dispatch
       // FTR-029/UC-04: validate immediately, before writing to disk and before moving to the next
       // component — a bad result otherwise silently continued through every remaining component,
       // only discovered (expensively) at final assembly or a later invocation's resume check.

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

@@ -130,7 +130,13 @@ function renderPhaseDetailBlock(phase, taskTitles, dependsOnPhases) {
     ? taskTitles.map(t => `- \`${t.id}\` — ${t.title}`).join('\n')
     : '_No tasks._'
   const dependsOn = dependsOnPhases.length ? dependsOnPhases.join(', ') : 'none'
-  let text = _stripTemplateComments(c.read('.claude/scripts/templates/gaia-user-story-template.md'))
+  // The template lives under the toolkit's own installed scripts/templates/ — outside the project
+  // for a globally-installed toolkit, which a plain c.read() has no way to resolve (it only reads
+  // project-relative paths). Read via print-asset instead, same as gaia-task-template.md below —
+  // this was previously a bare c.read() of a local-install-relative path, which only worked when
+  // the toolkit happened to be installed locally into this project's own .claude/ folder (a real
+  // incident: a project with only a global install failed with ENOENT on this exact line).
+  let text = _stripTemplateComments(c.command(['print-asset', 'scripts/templates/gaia-user-story-template.md', '--project', c.root]).stdout)
   text = text.replace(/\{PHASE_ID\}/g, phase.id)
   text = _fillFieldBlock(text, {
     'Phase ID': phase.id,