@dtlabs/ai-toolkit 0.21.0 → 0.21.2

package/CHANGELOG.md

@@ -1,4 +1,20 @@
 ## 0.1.4 (2026-07-21)
+## [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)
+
+
+### Bug Fixes
+
+* harden pipeline resilience across four real-world failures (FTR-029) ([ef57862](https://github.com/dtlab-tech/ai-toolkit/commit/ef578623541c084d17aeb6b0f53dba076e5a449e))
+* **workflow-control, pm-phase1:** harden pipeline resilience across four real-world failures (FTR-029) ([34a9ec9](https://github.com/dtlab-tech/ai-toolkit/commit/34a9ec9db645d1475e41e0c3875c8431a1ae0fda))
+
 ## [0.21.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.20.0...v0.21.0) (2026-10-20)
 
 

package/lib/workflow-control.js

@@ -169,25 +169,31 @@ function createControl(options) {
       });
       (options.log || (() => {}))('Worker evidence: ' + evidence.file);
       try {
-      // Retry a bounded number of times, but ONLY for a recognizable transient
-      // infrastructure failure — a CLI/SDK-level "API Error: ..." (stream idle
-      // timeout, overload, etc.), never a permission denial, schema violation,
-      // or any other deterministic content failure, which would just fail the
-      // same way again. Confirmed safe to retry: every agent dispatched through
-      // this path is read-only by design (no Write tool — see this function's
-      // own comment on why outputs are host-written, not agent-written; any
-      // Bash access granted is explicitly scoped to read-only assessment), so
-      // there is no partial side effect from a dead stream to clean up before
-      // retrying. Token usage from EVERY attempt is accumulated — a failed
-      // attempt still burns real output tokens before the stream dies — and
-      // each attempt's outcome is kept in evidence for diagnosing a recurring
-      // pattern like this one, rather than only ever seeing the last attempt.
+      // Retry a bounded number of times, for either of two recognizable, safe-to-retry
+      // conditions: (a) a transient CLI/SDK-level infrastructure failure ("API Error: ..." —
+      // stream idle timeout, overload, etc.), or (b) — added by FTR-029 — a schema-required
+      // attempt that comes back a clean exit but with no usable structured output even after the
+      // existing extractDelimitedStructuredOutput fallback. (b) was, until this feature, treated
+      // as a permanent content defect never worth retrying — confirmed EMPIRICALLY WRONG for at
+      // least one real, reproducible case: gaia-validate-feature-docs consistently replies with a
+      // logically-complete JSON candidate (valid/findings/report present) that simply omits two
+      // now-optional boolean fields (needsRequirementsFix/needsTechSpecFix) the schema used to
+      // require unconditionally. Neither condition is a permission denial or a present-but-wrong-
+      // type schema violation, which would still just fail the same way again. Confirmed safe to
+      // retry: every agent dispatched through this path is read-only by design (no Write tool —
+      // see this function's own comment on why outputs are host-written, not agent-written; any
+      // Bash access granted is explicitly scoped to read-only assessment), so there is no partial
+      // side effect from a dead stream to clean up before retrying. Token usage from EVERY attempt
+      // is accumulated — a failed attempt still burns real output tokens before the stream dies —
+      // and each attempt's outcome is kept in evidence for diagnosing a recurring pattern like
+      // this one, rather than only ever seeing the last attempt.
       let result;
       let accumulatedTokens = 0;
       const attempts = [];
+      let currentPrompt = prompt;
       for (let attempt = 1; attempt <= WORKER_MAX_ATTEMPTS; attempt++) {
         result = await (options.dispatch || spawnClaudeAgent)({
-          claudePath: options.claudePath, cwd: root, args: cliArgs, prompt,
+          claudePath: options.claudePath, cwd: root, args: cliArgs, prompt: currentPrompt,
           taskTimeoutMs: options.taskTimeoutMs || 1800000,
         });
         const usage = result.result?.usage;
@@ -201,8 +207,15 @@ function createControl(options) {
           resultPreview: typeof result.result?.result === 'string' ? result.result.result.slice(0, 300) : null,
           tokens: attemptTokens });
         evidence.save({ attempts });
-        if (!_isTransientWorkerApiError(result) || attempt === WORKER_MAX_ATTEMPTS) break;
-        await _sleep(WORKER_RETRY_BACKOFF_MS[attempt - 1]);
+        const transientApiError = _isTransientWorkerApiError(result);
+        const missingStructuredOutput = !!opts.schema && _isMissingStructuredOutput(result, opts.schema);
+        if ((!transientApiError && !missingStructuredOutput) || attempt === WORKER_MAX_ATTEMPTS) break;
+        if (missingStructuredOutput) {
+          currentPrompt = `${prompt}\n\n${STRUCTURED_OUTPUT_RETRY_NUDGE}`;
+          await _sleep(STRUCTURED_OUTPUT_RETRY_BACKOFF_MS);
+        } else {
+          await _sleep(WORKER_RETRY_BACKOFF_MS[attempt - 1]);
+        }
       }
       // Count usage before any business/protocol check, including denied tools.
       measuredTokens = accumulatedTokens > 0 ? accumulatedTokens : null;
@@ -364,6 +377,32 @@ function _isTransientWorkerApiError(result) {
     typeof result.result.result === 'string' && /^API Error:/i.test(result.result.result.trim()));
 }
 
+// A clean-exit attempt (never a protocol-level failure — that's handled separately, after the
+// loop, by the existing exitCode/parseError/timedOut/is_error check) whose structured_output is
+// empty AND whose text contains NO JSON-shaped candidate at all — never a candidate that exists
+// but fails schema validation (wrong field names/types), which is a deterministic content defect
+// that would just fail the same way again, not worth retrying (hence the extra
+// _hasAnyParseableJsonCandidate check, not just "extractDelimitedStructuredOutput returned null").
+// Deliberately reuses extractDelimitedStructuredOutput itself for the recoverable case (not a
+// cheaper proxy) so this retry decision and the post-loop fallback extraction can never disagree.
+function _isMissingStructuredOutput(result, schema) {
+  if (result.exitCode !== 0 || result.parseError || result.timedOut ||
+      !result.result || result.result.is_error !== false) return false;
+  if (result.result.structured_output != null) return false;
+  if (typeof result.result.result !== 'string') return true;
+  if (extractDelimitedStructuredOutput(result.result.result, schema) != null) return false;
+  return !_hasAnyParseableJsonCandidate(result.result.result);
+}
+
+const STRUCTURED_OUTPUT_RETRY_NUDGE = 'Your previous response did not populate the required ' +
+  'structured JSON output via the --json-schema tool-call channel. You MUST return your final ' +
+  'answer ONLY as that structured output — do not narrate it in prose or wrap it in a Markdown ' +
+  'code fence in your visible reply.';
+// No network condition to wait out here (unlike a transient API error) — an immediate retry is
+// both faster and sufficient; reusing WORKER_RETRY_BACKOFF_MS's real multi-second delays would pay
+// a wait with no corresponding benefit, for every genuinely unrecoverable response too.
+const STRUCTURED_OUTPUT_RETRY_BACKOFF_MS = 0;
+
 // A model asked to emit a JSON blob as part of a chat reply (rather than through a real
 // serializer, i.e. whenever structured_output didn't get populated and extraction has to
 // recover the payload from free text) is prone to one specific, well-understood defect: a
@@ -412,7 +451,7 @@ function _repairUnescapedControlCharsInStrings(text) {
 // the real closing delimiter, so brace-balance recovery anchored after the last ```json or
 // <json> marker is tried next — immune to that nesting because it tracks braces, not
 // delimiters — followed by an unanchored whole-text brace span as the last resort.
-function extractDelimitedStructuredOutput(text, schema) {
+function _collectJsonCandidates(text) {
   const candidates = [];
   for (const m of [...text.matchAll(/<(\w+)>([\s\S]*?)<\/\1>/g)].reverse()) candidates.push(m[2]);
   for (const m of [...text.matchAll(/```[a-zA-Z]*\s*\n?([\s\S]*?)```/g)].reverse()) candidates.push(m[1]);
@@ -425,7 +464,11 @@ function extractDelimitedStructuredOutput(text, schema) {
   const first = text.indexOf('{');
   const last = text.lastIndexOf('}');
   if (first !== -1 && last > first) candidates.push(text.slice(first, last + 1));
-  for (const raw of candidates) {
+  return candidates;
+}
+
+function extractDelimitedStructuredOutput(text, schema) {
+  for (const raw of _collectJsonCandidates(text)) {
     const trimmed = raw.trim();
     let parsed;
     try {
@@ -442,6 +485,20 @@ function extractDelimitedStructuredOutput(text, schema) {
   return null;
 }
 
+// FTR-029: distinguishes "no JSON-shaped candidate anywhere in the text" (genuinely missing
+// structured output — worth a retry, see _isMissingStructuredOutput) from "a candidate exists but
+// doesn't match this schema" (a deterministic content defect — e.g. wrong field names — that would
+// just fail the same way again, never worth retrying). Deliberately ignores the schema entirely;
+// only asks "did the model attempt to produce SOME JSON object at all".
+function _hasAnyParseableJsonCandidate(text) {
+  for (const raw of _collectJsonCandidates(text)) {
+    const trimmed = raw.trim();
+    try { JSON.parse(trimmed); return true; } catch (e) { /* try repaired form below */ }
+    try { JSON.parse(_repairUnescapedControlCharsInStrings(trimmed)); return true; } catch (e2) { /* try next candidate */ }
+  }
+  return false;
+}
+
 // A worker with a declared JSON output has no Write tool (see worker()'s own comment on why):
 // its entire response text becomes the file verbatim. Some models still wrap that deliverable
 // in conversational prose and/or a Markdown code fence despite being told not to (observed
@@ -535,10 +592,38 @@ function _unwrapWholeResponseFence(text) {
   if (start === -1) return null;
   return lines.slice(start + 1, end - 1).join('\n').trim() + '\n';
 }
+// UC-03: an unclosed whole-response fence wrap (the model opens a ```fence — possibly after some
+// conversational preamble, same as the existing closed-fence case already tolerates — but the
+// response simply ends without a matching close) defeats _unwrapWholeResponseFence entirely (no
+// closing line to match against) AND _hasUnfencedHeading (fence depth never returns to zero,
+// hiding every real heading after the opener). Scans for the FIRST fence-open marker anywhere in
+// the text (mirroring _unwrapWholeResponseFence's own tolerance for preamble before the fence);
+// if NO line anywhere after it closes a fence of that same backtick length, the opener itself is
+// the only defect — strip everything up to and including that one line. Same "always re-validate
+// the candidate" discipline as the existing unwrap: the caller only uses this if the stripped
+// result reveals a real heading.
+function _stripUnclosedLeadingFence(text) {
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const openMatch = lines[i].match(/^(`{3,})\S*\s*$/);
+    if (!openMatch) continue;
+    const fenceLen = openMatch[1].length;
+    let closesSomewhere = false;
+    for (let j = i + 1; j < lines.length; j++) {
+      const closeMatch = lines[j].match(/^(`{3,})\s*$/);
+      if (closeMatch && closeMatch[1].length === fenceLen) { closesSomewhere = true; break; }
+    }
+    if (!closesSomewhere) return lines.slice(i + 1).join('\n').trim() + '\n';
+    return null; // the first fence-opener found DOES close somewhere — not this case
+  }
+  return null;
+}
 function extractMarkdownDocument(text) {
   if (_hasUnfencedHeading(text)) return text;
   const unwrapped = _unwrapWholeResponseFence(text);
   if (unwrapped != null && _hasUnfencedHeading(unwrapped)) return unwrapped;
+  const stripped = _stripUnclosedLeadingFence(text);
+  if (stripped != null && _hasUnfencedHeading(stripped)) return stripped;
   return text;
 }
 

package/package.json

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

package/src/claude/agents/gaia-generate-requirements.md

@@ -123,11 +123,12 @@ Describe how pages connect and how the user moves between them.
 
 ## 7. Acceptance Criteria
 
-For each use case, define testable acceptance criteria:
+For each use case, define testable acceptance criteria. Use the EXACT 4-column shape below — do
+not add, remove, split, or reorder columns; the host's positional parser requires this exact shape:
 
-| ID | Criterion | Related UC |
-|----|-----------|-----------|
-| AC-01 | Given [context], when [action], then [result] | UC-01 |
+| ID | Criterion | Related UC | Priority |
+|----|-----------|-------------|----------|
+| AC-01 | Given [context], when [action], then [result] | UC-01 | Must |
 
 ## 8. Dependencies & Assumptions
 

package/src/claude/scripts/req-assembler.js

@@ -38,6 +38,15 @@ function parseTableRows(lines, start, end) {
     line.split('|').map(c => c.trim()).filter((_, i, a) => i > 0 && i < a.length - 1))
 }
 
+// Returns the raw header-row cells for the first Markdown table found inside [start, end), or
+// null if no table is present at all. Companion to parseTableRows, which deliberately discards
+// this same row — UC-02's AC-table header validation (req-skeleton-check.js) needs it back.
+function parseTableHeader(lines, start, end) {
+  const tableLines = lines.slice(start, end).filter(l => l.trim().startsWith('|'))
+  if (tableLines.length < 1) return null
+  return tableLines[0].split('|').map(c => c.trim()).filter((_, i, a) => i > 0 && i < a.length - 1)
+}
+
 // The "## 2. Use Cases" index table: UC ID | Title | Actor | Priority | File.
 // `File` is a Markdown link `[use-cases/UC-01.md](use-cases/UC-01.md)` — the link
 // TARGET (inside the parens) is authoritative, not the link text.
@@ -123,5 +132,6 @@ module.exports = {
   spliceSection2,
   findSectionRange,
   parseTableRows,
+  parseTableHeader,
   AssemblyError,
 }

package/src/claude/scripts/req-graph-checks.js

@@ -63,9 +63,33 @@ function checkCrossReferencesResolve({ ucIds, acTable, businessRules }) {
   return errors
 }
 
+// UC-02: the AC table's first 3 columns must be exactly "ID", "Criterion", "Related UC" in that
+// order — mirrors wb-graph-checks.js's own identical check for the Work-Breakdown-side AC table
+// (same names, same order, same "at least 3 columns" tolerance for a missing trailing Priority
+// column). Runs BEFORE req-assembler.js's parseAcTable positional destructure, so a malformed
+// header is reported as its own distinct, correctly-attributed error instead of a misleading
+// downstream DANGLING_AC_UC_REFERENCE (the real incident this closes: a 5-column table shifted
+// every cell, silently misattributing "When [...]" text into the Related UC field).
+function checkAcTableHeader(headerCells) {
+  if (!headerCells || headerCells.length < 3) {
+    return [{
+      category: 'MALFORMED_AC_TABLE_HEADER', severity: 'error',
+      message: `AC table header has fewer than 3 columns (found ${headerCells ? headerCells.length : 0})`,
+    }]
+  }
+  if (headerCells[0] !== 'ID' || headerCells[1] !== 'Criterion' || headerCells[2] !== 'Related UC') {
+    return [{
+      category: 'MALFORMED_AC_TABLE_HEADER', severity: 'error',
+      message: `AC table columns must be "ID", "Criterion", "Related UC" in order; got "${headerCells[0]}", "${headerCells[1]}", "${headerCells[2]}"`,
+    }]
+  }
+  return []
+}
+
 module.exports = {
   checkUniqueUcIds,
   checkUcIdFormat,
   checkUcTableFileParity,
   checkCrossReferencesResolve,
+  checkAcTableHeader,
 }

package/src/claude/scripts/req-skeleton-check.js

@@ -13,7 +13,7 @@
 const fs = require('fs')
 const path = require('path')
 const graphChecks = require('./req-graph-checks')
-const { parseUseCaseIndexTable, parseAcTable, parseBusinessRulesTable } = require('./req-assembler')
+const { parseUseCaseIndexTable, parseAcTable, parseBusinessRulesTable, findSectionRange, parseTableHeader } = require('./req-assembler')
 
 function main() {
   const indexPath = process.argv[2]
@@ -31,9 +31,15 @@ function main() {
   }
 
   let ucTable, acTable, businessRules
+  const acHeaderErrors = []
   try {
     ucTable = parseUseCaseIndexTable(indexContent)
-    acTable = parseAcTable(indexContent)
+    // UC-02: validate the AC table's column header BEFORE parseAcTable's positional destructure
+    // ever runs across data rows — a malformed header (e.g. a 5-column table) must never be
+    // silently misparsed into the wrong fields.
+    const { start, end, lines } = findSectionRange(indexContent, 7)
+    acHeaderErrors.push(...graphChecks.checkAcTableHeader(parseTableHeader(lines, start, end)))
+    acTable = acHeaderErrors.length ? [] : parseAcTable(indexContent)
     businessRules = parseBusinessRulesTable(indexContent)
   } catch (e) {
     console.log(JSON.stringify({ valid: false, errors: [{ message: `parse failure: ${e.message}` }] }))
@@ -47,6 +53,7 @@ function main() {
     : []
 
   const errors = [
+    ...acHeaderErrors,
     ...graphChecks.checkUniqueUcIds({ ucIds }),
     ...graphChecks.checkUcIdFormat({ ucIds }),
     ...graphChecks.checkUcTableFileParity({ ucIds }, existingUcFiles),

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

@@ -35,6 +35,10 @@ return c.run(meta.name, featureDir, prefix, async () => {
   const specComponentId = 'gaia.agent.planner.tech-spec-component'
   const valId = 'gaia.agent.planner.validate-feature-docs'
   const output = (suffix, inputs = [featurePath]) => ({ path: file(suffix), inputs })
+  // FTR-029/UC-04: bounded immediate retry, fixed constants (not externally configurable) for the
+  // per-UC and per-component generation loops' own fail-fast validity check.
+  const USE_CASE_RETRY_ATTEMPTS = 2
+  const COMPONENT_RETRY_ATTEMPTS = 2
 
   // Templates live under the toolkit's own installed scripts/templates/ — outside this project
   // for a globally-installed toolkit, which a non-interactive `--print` worker invocation has no
@@ -196,8 +200,15 @@ return c.run(meta.name, featureDir, prefix, async () => {
       // an existing use-case file would have been written against the OLD skeleton's row
       // (title/actor/priority may have changed) and cannot be trusted as-is.
       if (!regenSkeleton && c.exists(ucPath) && isValidUseCaseFile(c.read(ucPath), row.id)) continue // resume: skip, no dispatch
-      const detail = await c.worker(reqUcId, buildUcPrompt(row, ucTable, featurePath, ucTemplate),
-        { label: `requirements-use-case:${row.id}` })
+      // FTR-029/UC-04: validate immediately, before writing to disk and before moving to the next
+      // use case — same reasoning as the per-component loop above.
+      let detail, valid = false
+      for (let attempt = 1; attempt <= USE_CASE_RETRY_ATTEMPTS && !valid; attempt++) {
+        detail = await c.worker(reqUcId, buildUcPrompt(row, ucTable, featurePath, ucTemplate),
+          { label: `requirements-use-case:${row.id}:${attempt}` })
+        valid = isValidUseCaseFile(detail, row.id)
+      }
+      if (!valid) throw new Error(`Requirements use case "${row.id}" failed structural validation after ${USE_CASE_RETRY_ATTEMPTS} attempts — missing the required "### ${row.id}: " heading`)
       c.writeOutput(ucPath, detail.trimEnd() + ucCrossReferences(c.read(reqIndexPath), row.id))
     }
     // No assembly/write step here — generation only ever produces req/index.md + its per-UC
@@ -439,8 +450,16 @@ return c.run(meta.name, featureDir, prefix, async () => {
     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
-      const detail = await c.worker(specComponentId, buildComponentPrompt(comp, components, featurePath, componentTemplate),
-        { label: `tech-spec-component:${comp.fileSlug}` })
+      // 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.
+      let detail, valid = false
+      for (let attempt = 1; attempt <= COMPONENT_RETRY_ATTEMPTS && !valid; attempt++) {
+        detail = await c.worker(specComponentId, buildComponentPrompt(comp, components, featurePath, componentTemplate),
+          { label: `tech-spec-component:${comp.fileSlug}:${attempt}` })
+        valid = isValidComponentDetail(detail)
+      }
+      if (!valid) throw new Error(`Tech-Spec component "${comp.filePath}" (${comp.fileSlug}) failed structural validation after ${COMPONENT_RETRY_ATTEMPTS} attempts — missing a real "## Change"/"## Tests" heading`)
       c.writeOutput(compPath, detail)
     }
     // No assembly/write step here — generation only ever produces spec/index.md + its
@@ -514,7 +533,12 @@ return c.run(meta.name, featureDir, prefix, async () => {
       const result = await c.worker(valId,
         `${featurePath}\n\nRequirements:\n${assembledRequirements}\n\nTech-Spec:\n${c.read(specIndexPath)}\n\n` +
         'Validate 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), needsComponentDetail (claims needing a component\'s own design body to verify — see your own instructions for when to use this instead of a finding), and the full validation report content. Do not dispatch other agents.',
-        { label: `validation:${cycle}`, outputs: [output('Validation-Report', [featurePath, reqIndexPath, specIndexPath])], schema: { type: 'object', properties: { valid: { type: 'boolean' }, findings: { type: 'array', items: { type: 'string' } }, needsRequirementsFix: { type: 'boolean' }, needsTechSpecFix: { type: 'boolean' }, report: { type: 'string' }, needsComponentDetail: { type: 'array', items: { type: 'object', properties: { claim: { type: 'string' }, fileSlug: { type: 'string' } }, required: ['claim', 'fileSlug'] } } }, required: ['valid', 'findings', 'needsRequirementsFix', 'needsTechSpecFix', 'report'] } })
+        { label: `validation:${cycle}`, outputs: [output('Validation-Report', [featurePath, reqIndexPath, specIndexPath])], schema: { type: 'object', properties: { valid: { type: 'boolean' }, findings: { type: 'array', items: { type: 'string' } }, needsRequirementsFix: { type: 'boolean' }, needsTechSpecFix: { type: 'boolean' }, report: { type: 'string' }, needsComponentDetail: { type: 'array', items: { type: 'object', properties: { claim: { type: 'string' }, fileSlug: { type: 'string' } }, required: ['claim', 'fileSlug'] } } }, required: ['valid', 'findings', 'report'] } })
+        // FTR-029: needsRequirementsFix/needsTechSpecFix stay declared in `properties` (still
+        // type-checked when present) but are no longer hard-required — confirmed against three
+        // real evidence files that the model reasonably omits both when there is nothing to fix;
+        // the host's own merge logic already treats an absent value as falsy
+        // (mergedNeedsRequirementsFix/mergedNeedsTechSpecFix below), so no further change needed.
         // needsComponentDetail is declared in `properties` but deliberately NOT in the schema's
         // top-level `required` array: every pre-existing mocked test response for this agent
         // (predating this feature) omits the field entirely, and making it hard-required would

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,