@dtlabs/ai-toolkit 0.18.0 → 0.19.1

package/CHANGELOG.md

@@ -1,4 +1,19 @@
 ## 0.1.4 (2026-07-21)
+## [0.19.1](https://github.com/dtlab-tech/ai-toolkit/compare/v0.19.0...v0.19.1) (2026-10-19)
+
+
+### Bug Fixes
+
+* stop headless workers from Reading their own toolkit templates ([0f2c707](https://github.com/dtlab-tech/ai-toolkit/commit/0f2c7079799cdfb95ab99dcf7333f615a8f49a8e))
+
+## [0.19.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.18.0...v0.19.0) (2026-10-19)
+
+
+### Features
+
+* make the Work Breakdown pipeline split-source-native (FTR-026) ([9d08a17](https://github.com/dtlab-tech/ai-toolkit/commit/9d08a1743e199534753b6c6d47b855ec7953f032))
+* **pm-phase2, ac-task-matrix:** make the Work Breakdown pipeline split-source-native (FTR-026) ([067a8e3](https://github.com/dtlab-tech/ai-toolkit/commit/067a8e369f8a5db72678670bebb62c91c93303d1))
+
 ## [0.18.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.17.5...v0.18.0) (2026-10-19)
 
 

package/bin/cli.js

@@ -2056,6 +2056,51 @@ async function main() {
       process.stderr.write(err.message + '\n');
       process.exit(1);
     }
+  } else if (argv[0] === 'print-asset') {
+    // print-asset <relativePath> [--project <dir>] [--home <dir>]
+    // Security constraints: scripts/templates/ subpath only; .md extension only — the
+    // read-only counterpart to run-asset's "scripts category, .js only, execute" contract.
+    //
+    // Exists so a sandboxed workflow script (pm-phase1.js/pm-phase2.js — no `require()`, no
+    // filesystem access outside its own project root) can fetch a toolkit template's raw
+    // text and inline it directly into a worker's prompt, instead of telling the headless
+    // agent to Read the template file itself. That file lives outside the project root for
+    // a globally-installed toolkit, which is exactly the boundary a non-interactive `--print`
+    // session (no TTY to answer a permission prompt) cannot grant — confirmed by a real
+    // worker run failing with "Worker permission denied: ...; tools: Read" against exactly
+    // this path. Inlining via the host (a plain Node process, never subject to the Claude
+    // Code tool-permission system) sidesteps the problem entirely, the same pattern FTR-025
+    // already established for inlining Requirements/Tech-Spec text into gaia-validate-
+    // feature-docs' prompt instead of telling it to Read those files itself.
+    const remaining = argv.slice(1);
+    let relativePath = null;
+    let projectDir   = process.cwd();
+    let home;
+    for (let i = 0; i < remaining.length; i++) {
+      if      (remaining[i] === '--project' && remaining[i + 1]) { projectDir = remaining[++i]; }
+      else if (remaining[i] === '--home'    && remaining[i + 1]) { home       = remaining[++i]; }
+      else if (!remaining[i].startsWith('-'))                     { relativePath = remaining[i]; }
+    }
+    if (!relativePath) {
+      process.stderr.write('Error: print-asset requires a relative path argument\n');
+      process.exit(1);
+    }
+    if (!relativePath.startsWith('scripts/templates/')) {
+      process.stderr.write(`Error: print-asset is restricted to scripts/templates/ (got: ${relativePath})\n`);
+      process.exit(1);
+    }
+    if (!relativePath.endsWith('.md')) {
+      process.stderr.write(`Error: print-asset only reads .md files (got: ${relativePath})\n`);
+      process.exit(1);
+    }
+    try {
+      const assetPath = resolveClaudeRuntimeAsset(relativePath, { projectDir, home });
+      process.stdout.write(fs.readFileSync(assetPath, 'utf8'));
+      process.exit(0);
+    } catch (err) {
+      process.stderr.write(err.message + '\n');
+      process.exit(1);
+    }
   } else if (argv[0] === 'list-assets') {
     // list-assets --project <dir> --category <name> [--format json|plain] [--home <dir>]
     // Both --project and --category are MANDATORY (Tech Spec contract).

package/lib/workflow-control.js

@@ -106,7 +106,7 @@ function createControl(options) {
   }
   function command(argv, accepted = [0]) {
     if (!Array.isArray(argv) || argv.some(a => typeof a !== 'string')) throw new Error('CLI argv array required');
-    if (options.home && argv[0] === 'run-asset') {
+    if (options.home && (argv[0] === 'run-asset' || argv[0] === 'print-asset')) {
       argv = argv.slice();
       const split = argv.indexOf('--');
       argv.splice(split < 0 ? argv.length : split, 0, '--home', options.home);

package/package.json

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

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

@@ -23,18 +23,21 @@ The host supplies, in the dispatch prompt:
 3. The path to `feature.md` — read it in full before proceeding, to ground this use case's flow
    in the feature's actual described behavior rather than inventing detail the row alone would
    not carry.
+4. The canonical field-table/flow structure, inlined under a `Template (req/use-cases/{UC-ID}.md):`
+   label. Use this text — do NOT attempt to Read, Glob, or otherwise search the filesystem for
+   `gaia-use-case-template.md` yourself; it is not guaranteed to be reachable from where this agent
+   runs, and searching for it is not a safe fallback either.
 
 You do not read `req/index.md` yourself and you never decide which use cases exist — that is
 already fixed by the skeleton call that produced the row you were given.
 
-Read `.claude/scripts/templates/gaia-use-case-template.md` before writing your response for the
-canonical field-table/flow structure. Note: that template also shows "Related Business Rules"/
-"Related Acceptance Criteria" cross-reference lines at the end of the file — do NOT produce them
-yourself. The host computes both, mechanically, from `req/index.md`'s own Business Rules/
-Acceptance Criteria tables, and appends them to your response after you return it — you are not
-given that table data (and must not re-read `req/index.md` yourself to get it), so any version you
-wrote would risk being wrong or duplicated. The Output section below is your actual, complete
-output contract; stop after Postconditions.
+Note: the inlined template also shows "Related Business Rules"/"Related Acceptance Criteria"
+cross-reference lines at the end of the file — do NOT produce them yourself. The host computes
+both, mechanically, from `req/index.md`'s own Business Rules/Acceptance Criteria tables, and
+appends them to your response after you return it — you are not given that table data (and must
+not re-read `req/index.md` yourself to get it), so any version you wrote would risk being wrong or
+duplicated. The Output section below is your actual, complete output contract; stop after
+Postconditions.
 
 ## Mandatory instruction
 

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

@@ -19,11 +19,15 @@ together with those per-use-case files afterward (FTR-021).
 
 The user provides the path to a `feature.md` file. Read it in full before proceeding.
 
-Also read `.claude/scripts/templates/gaia-requirements-index-template.md` before writing your
-response — it is the canonical, authoritative structure for `req/index.md` (section order,
-exact headings, table column contracts, and the parsing contract `req-skeleton-check.js`/
-`req-assembler.js` rely on). The Output Structure section below summarizes it; the template
-itself is the source of truth if the two ever disagree.
+The prompt also includes, inlined under a `Template (req/index.md):` label, the canonical,
+authoritative structure for `req/index.md` (section order, exact headings, table column
+contracts, and the parsing contract `req-skeleton-check.js`/`req-assembler.js` rely on). Use the
+inlined text — do NOT attempt to Read, Glob, or otherwise search the filesystem for
+`gaia-requirements-index-template.md` yourself; it is not guaranteed to be reachable from where
+this agent runs, and searching for it is not a safe fallback either (your Glob/Grep tools remain
+available for exploring the feature's own project, just not for locating this template). The
+Output Structure section below summarizes it; the inlined template text is the source of truth if
+the two ever disagree.
 
 ## Process
 

package/src/claude/agents/gaia-generate-tech-spec-component.md

@@ -28,10 +28,15 @@ The host supplies, in the dispatch prompt:
 You do not read `spec/index.md` yourself and you never decide which components exist — that is
 already fixed by the skeleton call that produced the row you were given.
 
-Read `.claude/scripts/templates/gaia-component-template.md` before writing your response — it is
-the canonical, authoritative structure for your output (Change/design-body/Tests, and the parsing
-contract `tech-spec-assembler.js`'s `parseComponentDetail` relies on). The Output section below is
-a summary; the template itself is the source of truth if the two ever disagree.
+The prompt also includes, inlined under a `Template (spec/components/{fileSlug}.md):` label, the
+canonical, authoritative structure for your output (Change/design-body/Tests, and the parsing
+contract `tech-spec-assembler.js`'s `parseComponentDetail` relies on). Use the inlined text — do
+NOT attempt to Read, Glob, or otherwise search the filesystem for `gaia-component-template.md`
+yourself under any circumstances, including as a fallback if you are unsure of its exact path; it
+is not guaranteed to be reachable from where this agent runs, and guessing at or searching for its
+absolute path is not a safe substitute for the text already given to you below. The Output
+section below is a summary; the inlined template text is the source of truth if
+the two ever disagree.
 
 ## Mandatory instruction
 

package/src/claude/agents/gaia-generate-tech-spec.md

@@ -19,11 +19,15 @@ together with those per-component files afterward (FTR-024).
 
 The user provides the path to a `feature.md` file. Read it in full before proceeding. Also read the relevant existing codebase files to ensure the spec aligns with current architecture.
 
-Also read `.claude/scripts/templates/gaia-tech-spec-index-template.md` before writing your
-response — it is the canonical, authoritative structure for `spec/index.md` (section order, exact
-headings, the Section 9 column-order contract `tech-spec-graph-checks.js` relies on, and the
-parsing contract `tech-spec-assembler.js` relies on). The Output Structure section below
-summarizes it; the template itself is the source of truth if the two ever disagree.
+The prompt also includes, inlined under a `Template (spec/index.md):` label, the canonical,
+authoritative structure for `spec/index.md` (section order, exact headings, the Section 9
+column-order contract `tech-spec-graph-checks.js` relies on, and the parsing contract
+`tech-spec-assembler.js` relies on). Use the inlined text — do NOT attempt to Read, Glob, or
+otherwise search the filesystem for `gaia-tech-spec-index-template.md` yourself; it is not
+guaranteed to be reachable from where this agent runs, and searching for it is not a safe fallback
+either (your Glob/Grep tools remain available for exploring the project's existing codebase, just
+not for locating this template). The Output Structure section below summarizes it; the inlined
+template text is the source of truth if the two ever disagree.
 
 ## Step 0 — Read Project Conventions (MANDATORY)
 

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

@@ -9,11 +9,6 @@ tools: Read, Glob, Grep
 
 You are a **senior implementation planner**. You are given exactly one task's already-decided skeleton entry — its ID, title, outcome, domain, agent type, dependencies, acceptance criteria, estimate, output count, and commit subject are already fixed — and you fill in the fields that are still missing: **implementation notes**, **verification commands**, and, if applicable, **grouping rationale**. You do not re-decide anything the skeleton already fixed.
 
-Read `.claude/scripts/templates/gaia-task-template.md` before writing your response — it is the
-canonical, authoritative structure for your output (field order, the two free-content sections,
-and the exact parsing contract downstream tooling relies on). This section and the Output section
-below summarize it; the template itself is the source of truth if the two ever disagree.
-
 This is the **second of two generation passes** (FTR-020). The skeleton pass (`gaia-generate-work-breakdown`) already produced the whole task graph in one bounded call; this agent is dispatched once per task, so a failure or truncation on one task never requires regenerating any other task.
 
 ---
@@ -23,10 +18,17 @@ This is the **second of two generation passes** (FTR-020). The skeleton pass (`g
 The caller supplies, in the prompt (you do not read `{PREFIX}-Work-Breakdown.json`/`wbs/index.json` yourself — the host extracts and hands you exactly what you need):
 
 1. **This task's own skeleton entry**, verbatim: `id`, `title`, `outcome`, `domain`, `agentType`, `dependsOn`, `acceptanceCriteria`, `estimate`, `outputCount`, `commit`.
-2. **The relevant Tech-Spec excerpt** for this task's domain (not the whole Tech-Spec — keeps this call small, which is the whole point of the per-task split).
+2. **The relevant Tech-Spec excerpt** for this task's own Acceptance Criteria (matched by the host against each component's `Addresses` column in `spec/index.md` — not the whole Tech-Spec, which is the whole point of the per-task split). If no component's `Addresses` column cites any of this task's Acceptance Criteria, you instead receive the full Components table from `spec/index.md` as a fallback — in that case, use your own judgment about which listed component(s) are actually relevant, the same way you would if asked to work from the full Tech-Spec directly.
 3. **The compact full-skeleton task list**: every task's `id` + `title` + `outcome` only (no detail), so you can tell whether another task already built the behavior this one would otherwise duplicate.
+4. **The canonical output template**, inlined under a `Template (tasks/{TASK_ID}.md):` label — the
+   authoritative structure for your output (field order, the two free-content sections, and the
+   exact parsing contract downstream tooling relies on). Use the inlined text — do NOT attempt to
+   Read, Glob, or otherwise search the filesystem for `gaia-task-template.md` yourself; it is not
+   guaranteed to be reachable from where this agent runs, and searching for it is not a safe
+   fallback either. This section and the Output section below summarize it; the inlined template
+   text is the source of truth if the two ever disagree.
 
-If the prompt is missing any of these three, stop and report exactly what is missing — do not guess at a skeleton entry you were not given.
+If the prompt is missing any of these four, stop and report exactly what is missing — do not guess at a skeleton entry you were not given.
 
 ---
 
@@ -142,9 +144,9 @@ Return exactly this block as your final response, and nothing else (no preamble,
 ```
 
 This is the same format already rendered today inside a Work Breakdown's "Task Details"
-section — canonical reference: `.claude/scripts/templates/gaia-task-template.md` (you have a Read
-tool; read it directly rather than relying only on this summary). That template's parsing-contract
-note applies to your own output too: a naive parser reads only the field lines immediately
+section — canonical reference: the `Template (tasks/{TASK_ID}.md):`-labeled text inlined in your
+own prompt (see Input §4 above; rely on that, not just this summary). That template's
+parsing-contract note applies to your own output too: a naive parser reads only the field lines immediately
 following the heading, and the *last* `**Implementation notes:**`/`**Verification commands:**`
 occurrence — so if you need to illustrate this format inside a longer explanation (e.g. showing
 another agent's expected output shape), make sure your own real sections remain the last

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

@@ -17,12 +17,20 @@ This is the **first of two generation passes** (FTR-020). This call decides the
 
 The user provides the path to a `feature.md` file. From the same directory, read:
 
-1. `{PREFIX}-Requirements.md` — source of User Stories (derived from Use Cases), acceptance criteria, business rules
-2. `{PREFIX}-Tech-Spec.md` — source of technical tasks, implementation order, file inventory, architecture decisions
+1. Requirements — `req/index.md` (the split format, FTR-021; source of User Stories derived from
+   Use Cases, acceptance criteria, business rules) if it exists, otherwise the legacy
+   `{PREFIX}-Requirements.md`
+2. Tech-Spec — `spec/index.md` (the split format, FTR-024; source of technical tasks,
+   implementation order, file inventory, architecture decisions) if it exists, otherwise the
+   legacy `{PREFIX}-Tech-Spec.md`
 3. `{PREFIX}-Validation-Report.md` — confirms both documents passed coverage validation
 4. `{PREFIX}-Approvals.md` — confirms user has approved the documents
 
-**This agent runs ONLY after validation and human approval.** If any of the four input files is missing, abort and report:
+See Step 1 below for exactly how to read whichever shape (1)/(2) actually are, including per-item
+drilldown into `req/use-cases/*.md`/`spec/components/*.md`.
+
+**This agent runs ONLY after validation and human approval.** If Requirements/Tech-Spec exist in
+neither shape, or (3)/(4) are missing, abort and report:
 ```
 Cannot generate work breakdown: `{file}` not found.
 The work breakdown requires validated and approved Requirements + Tech-Spec.
@@ -79,8 +87,25 @@ Every task must be the **smallest independently implementable, verifiable, and c
 
 ### Step 1 — Load and Cross-Reference
 
-1. Read `{PREFIX}-Requirements.md` fully — extract all Use Cases (UC-XX), acceptance criteria (AC-XX), business rules (BR-XX), NFRs
-2. Read `{PREFIX}-Tech-Spec.md` fully — extract architecture, file inventory, implementation order, data model, API endpoints, frontend components
+1. Check whether `req/index.md` exists (the split Requirements format, FTR-021). If it does:
+   - Read `req/index.md` fully — it already contains the full Use Cases index table, all Business
+     Rules, all Acceptance Criteria, and all NFRs (FTR-021 kept these feature-wide, not per-UC)
+   - For any UC whose own full flow description you need beyond the index's short Title/Actor
+     summary, Read `req/use-cases/{UC-ID}.md` directly
+   If `req/index.md` does not exist (a legacy feature), Read `{PREFIX}-Requirements.md` fully
+   instead — extract the same information from the monolithic file.
+2. Check whether `spec/index.md` exists (the split Tech-Spec format, FTR-024). If it does:
+   - Read `spec/index.md` fully — it already contains Architecture, Section 9's complete File
+     Inventory/Components table (with Domain/Addresses routing), Implementation Order, and Risks
+   - For any component whose own Backend/Frontend/design detail you need beyond the Components
+     table's one-line Purpose/Addresses summary, Read `spec/components/{file-slug}.md` directly —
+     the `Spec` column in Section 9's table gives you the exact path
+   - If, after reading the index, you cannot determine from its own summary tables which per-item
+     files are relevant to a given phase/task decision, fall back to reading every file under
+     `spec/components/` rather than proceeding with incomplete context
+   If `spec/index.md` does not exist (a legacy feature), Read `{PREFIX}-Tech-Spec.md` fully
+   instead — extract architecture, file inventory, implementation order, data model, API
+   endpoints, frontend components from the monolithic file.
 
 ### Step 2 — Derive User Stories from Use Cases
 

package/src/claude/agents/gaia-validate-work-breakdown-semantic.md

@@ -15,12 +15,17 @@ You do NOT repeat structural checks (schema conformance, required fields, ID for
 
 ## Input
 
-The user provides the path to `{PREFIX}-Work-Breakdown.json`. From the same directory, locate and read:
+The prompt gives you two paths, one per line, in this order:
 
-1. `{PREFIX}-Work-Breakdown.json` — the validated work breakdown (schema v2)
-2. `{PREFIX}-Requirements.md` — User Story descriptions and Acceptance Criteria text
+1. The Work Breakdown directory (the split format, FTR-020) — contains `index.json` (the
+   validated skeleton, schema v2) plus `user-stories/*.md`/`tasks/*.md` detail files. Use Glob/Read
+   to explore it as needed; do not expect a single `{PREFIX}-Work-Breakdown.json` file.
+2. The Requirements source — `req/index.md` for a feature using the split Requirements format
+   (FTR-021; User Story descriptions and Acceptance Criteria text live in its own tables there,
+   unaffected by the per-UC split), or a legacy `{PREFIX}-Requirements.md` file otherwise. Read
+   whichever path is actually given — do not assume either shape.
 
-Derive the prefix from the filename (e.g., `FTR-014-Work-Breakdown.json` → prefix `FTR-014`).
+Derive the prefix from the Work Breakdown directory's own `index.json`'s `feature` field.
 
 ---
 

package/src/claude/scripts/ac-task-matrix.js

@@ -45,6 +45,10 @@ function computeTechSpecCoverage(entries, acMap) {
 }
 
 function renderMatrix(prefix, acMap, coverage, techSpecCoverage = new Map()) {
+  const mustEntries = [...acMap.entries()].filter(([, ac]) => ac.priority === 'Must')
+  const mustCovered = mustEntries.filter(([id]) => coverage.get(id).taskIds.size > 0).length
+  const summary = `**Must-AC coverage:** ${mustCovered}/${mustEntries.length} covered. ` +
+    'Machine-readable data: [index.json](index.json).'
   const rows = [...acMap.entries()].map(([acId, ac]) => {
     const relatedUc = ac.unscoped ? 'All UCs' : ac.relatedUCs.join(', ')
     const cov = coverage.get(acId)
@@ -53,7 +57,7 @@ function renderMatrix(prefix, acMap, coverage, techSpecCoverage = new Map()) {
     const techSpecFiles = [...(techSpecCoverage.get(acId) || [])].join(', ') || '—'
     return `| ${acId} | ${ac.criterion} | ${ac.priority} | ${relatedUc} | ${techSpecFiles} | ${taskIds} | ${phaseIds} |`
   })
-  return `# AC ↔ Task Traceability Matrix — ${prefix}\n\n` +
+  return `# AC ↔ Task Traceability Matrix — ${prefix}\n\n${summary}\n\n` +
     '| AC ID | Criterion | Priority | Related UC | Addressed by Tech-Spec File(s) | Covering Task(s) | Covering Phase(s) |\n' +
     '|---|---|---|---|---|---|---|\n' +
     rows.join('\n') + '\n\n' +
@@ -68,10 +72,36 @@ function renderMatrix(prefix, acMap, coverage, techSpecCoverage = new Map()) {
     'belong to, comma-separated, or `—` if none.\n'
 }
 
+// FTR-026: serializes the same in-memory data renderMatrix() already consumes into a
+// machine-readable shape — one entry per Requirements AC, in table order. No new computation.
+function buildMatrixJson(prefix, acMap, coverage, techSpecCoverage = new Map()) {
+  const acceptanceCriteria = [...acMap.entries()].map(([acId, ac]) => {
+    const cov = coverage.get(acId)
+    return {
+      id: acId,
+      criterion: ac.criterion,
+      priority: ac.priority,
+      unscoped: !!ac.unscoped,
+      relatedUCs: ac.unscoped ? [] : ac.relatedUCs,
+      techSpecFiles: [...(techSpecCoverage.get(acId) || [])],
+      taskIds: [...cov.taskIds],
+      phaseIds: [...cov.phaseIds],
+    }
+  })
+  return { prefix, generatedAt: new Date().toISOString(), acceptanceCriteria }
+}
+
 if (require.main === module) {
-  const [wbsPath, requirementsPath, techSpecPath, prefix] = process.argv.slice(2)
-  if (!wbsPath || !requirementsPath || !techSpecPath || !prefix) {
-    process.stderr.write('Usage: node ac-task-matrix.js <wbs-path> <requirements-path> <tech-spec-path> <prefix>\n')
+  // FTR-026: featureDir is REQUIRED (not optional) — confirmed by grep that pm-phase2.js and this
+  // script's own test suite are the only callers, so there is no backward-compatible no-arg case
+  // worth preserving. Output moves from one loose {prefix}-AC-Task-Matrix.md file (whose location
+  // used to be derived from path.dirname(requirementsPath) — a real bug: that would have silently
+  // moved once a caller passes a Requirements path living under req/) into a dedicated
+  // coverage-matrix/ subfolder under featureDir, as a JSON+MD pair.
+  const [wbsPath, requirementsPath, techSpecPath, prefix, featureDir] = process.argv.slice(2)
+  if (!wbsPath || !requirementsPath || !techSpecPath || !prefix || !featureDir) {
+    process.stderr.write(
+      'Usage: node ac-task-matrix.js <wbs-path> <requirements-path> <tech-spec-path> <prefix> <feature-dir>\n')
     process.exit(1)
   }
   const wb = loadWorkBreakdown(path.resolve(wbsPath))
@@ -79,9 +109,13 @@ if (require.main === module) {
   const coverage = computeCoverage(wb, acMap)
   const techSpecEntries = parseFileInventoryEntries(fs.readFileSync(path.resolve(techSpecPath), 'utf8'))
   const techSpecCoverage = computeTechSpecCoverage(techSpecEntries, acMap)
-  const outPath = path.join(path.dirname(path.resolve(requirementsPath)), `${prefix}-AC-Task-Matrix.md`)
-  fs.writeFileSync(outPath, renderMatrix(prefix, acMap, coverage, techSpecCoverage))
-  console.log(JSON.stringify({ outputPath: outPath }))
+  const outDir = path.join(path.resolve(featureDir), 'coverage-matrix')
+  fs.mkdirSync(outDir, { recursive: true })
+  const jsonPath = path.join(outDir, 'index.json')
+  const mdPath = path.join(outDir, 'index.md')
+  fs.writeFileSync(jsonPath, JSON.stringify(buildMatrixJson(prefix, acMap, coverage, techSpecCoverage), null, 2))
+  fs.writeFileSync(mdPath, renderMatrix(prefix, acMap, coverage, techSpecCoverage))
+  console.log(JSON.stringify({ jsonPath, mdPath }))
 }
 
-module.exports = { computeCoverage, renderMatrix, computeTechSpecCoverage }
+module.exports = { computeCoverage, renderMatrix, computeTechSpecCoverage, buildMatrixJson }

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

@@ -36,6 +36,21 @@ return c.run(meta.name, featureDir, prefix, async () => {
   const valId = 'gaia.agent.planner.validate-feature-docs'
   const output = (suffix, inputs = [featurePath]) => ({ path: file(suffix), inputs })
 
+  // 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
+  // way to get permission for (no TTY to answer a prompt; confirmed by a real run failing with
+  // "Worker permission denied: ...; tools: Read" against exactly this kind of path). The host
+  // reads the template itself (a plain Node process, never subject to the Claude Code
+  // tool-permission system) via the dedicated print-asset CLI command, and inlines its text
+  // directly into the prompt — the agent is never asked to Read it. Same pattern FTR-025 already
+  // established for inlining Requirements/Tech-Spec text into gaia-validate-feature-docs' prompt.
+  function readTemplate(templateFile) {
+    return c.command(['print-asset', `scripts/templates/${templateFile}`, '--project', c.root]).stdout
+  }
+  function withTemplate(prompt, label, templateFile) {
+    return `${prompt}\n\nTemplate (${label}):\n${readTemplate(templateFile)}`
+  }
+
   // Deliberately NOT file('req') — same reasoning as FTR-020's wbsDir: this is a directory
   // nested inside the feature's own already-prefixed folder, so a second prefix would be
   // redundant.
@@ -109,11 +124,12 @@ return c.run(meta.name, featureDir, prefix, async () => {
       (relatedACs.length ? relatedACs.join(', ') : '—') + ' (see [index.md](../index.md#7-acceptance-criteria))\n'
   }
 
-  function buildUcPrompt(row, ucTable, featurePathArg) {
+  function buildUcPrompt(row, ucTable, featurePathArg, ucTemplate) {
     const compactIndex = ucTable.map(r => `${r.id}: ${r.title} (${r.actor})`).join('\n')
-    return `${featurePathArg}\n\nGenerate the full detail for this use case:\n` +
+    const base = `${featurePathArg}\n\nGenerate the full detail for this use case:\n` +
       `UC ID: ${row.id}\nTitle: ${row.title}\nActor: ${row.actor}\nPriority: ${row.priority}\n\n` +
       `Full use-case index (for cross-UC awareness, do not restate):\n${compactIndex}`
+    return `${base}\n\nTemplate (req/use-cases/{UC-ID}.md):\n${ucTemplate}`
   }
 
   // forceAll: bypasses resume-by-existence entirely, re-dispatching the skeleton and every
@@ -144,7 +160,7 @@ return c.run(meta.name, featureDir, prefix, async () => {
     // 1. Skeleton (no declared worker() output — host writes it itself, mirroring FTR-020's
     // skeleton step)
     if (regenSkeleton) {
-      const skeleton = await c.worker(reqId, featurePath)
+      const skeleton = await c.worker(reqId, withTemplate(featurePath, 'req/index.md', 'gaia-requirements-index-template.md'))
       c.writeOutput(reqIndexPath, skeleton)
     }
 
@@ -162,13 +178,15 @@ return c.run(meta.name, featureDir, prefix, async () => {
 
     // 3. Per-use-case generation, resume-by-existence, sequential
     const ucTable = parseUseCaseIndexTable(c.read(reqIndexPath))
+    // Read once, outside the loop — the template is identical for every use case in this run.
+    const ucTemplate = ucTable.length ? readTemplate('gaia-use-case-template.md') : null
     for (const row of ucTable) {
       const ucPath = `${reqDir}/${row.file}`
       // If the skeleton itself was just (re)generated, every use case must regenerate too —
       // 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)) continue // resume: skip, no dispatch
-      const detail = await c.worker(reqUcId, buildUcPrompt(row, ucTable, featurePath),
+      const detail = await c.worker(reqUcId, buildUcPrompt(row, ucTable, featurePath, ucTemplate),
         { label: `requirements-use-case:${row.id}` })
       c.writeOutput(ucPath, detail.trimEnd() + ucCrossReferences(c.read(reqIndexPath), row.id))
     }
@@ -223,11 +241,12 @@ return c.run(meta.name, featureDir, prefix, async () => {
     return entries
   }
 
-  function buildComponentPrompt(row, components, featurePathArg) {
+  function buildComponentPrompt(row, components, featurePathArg, componentTemplate) {
     const compactIndex = components.map(c => `${c.filePath} (${c.domain})`).join('\n')
-    return `${featurePathArg}\n\nGenerate the full technical design for this component:\n` +
+    const base = `${featurePathArg}\n\nGenerate the full technical design for this component:\n` +
       `Path: ${row.filePath}\nChange: ${row.changeType}\nDomain: ${row.domain}\nAddresses: ${row.addresses}\n\n` +
       `Full component index (for cross-component awareness, do not restate):\n${compactIndex}`
+    return `${base}\n\nTemplate (spec/components/{fileSlug}.md):\n${componentTemplate}`
   }
 
   // Deterministic, host-computed — never asks the model to pick unique names (same principle
@@ -279,7 +298,7 @@ return c.run(meta.name, featureDir, prefix, async () => {
 
     // 1. Skeleton (no declared worker() output — host writes it itself)
     if (regenSkeleton) {
-      const skeleton = await c.worker(specId, featurePath)
+      const skeleton = await c.worker(specId, withTemplate(featurePath, 'spec/index.md', 'gaia-tech-spec-index-template.md'))
       c.writeOutput(specIndexPath, disambiguateFileSlugs(skeleton))
     }
 
@@ -298,10 +317,12 @@ return c.run(meta.name, featureDir, prefix, async () => {
 
     // 3. Per-component generation, resume-by-existence, sequential
     const components = parseComponentsTable(c.read(specIndexPath))
+    // Read once, outside the loop — the template is identical for every component in this run.
+    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)) continue // resume: skip, no dispatch
-      const detail = await c.worker(specComponentId, buildComponentPrompt(comp, components, featurePath),
+      const detail = await c.worker(specComponentId, buildComponentPrompt(comp, components, featurePath, componentTemplate),
         { label: `tech-spec-component:${comp.fileSlug}` })
       c.writeOutput(compPath, detail)
     }

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

@@ -164,11 +164,82 @@ function computeDependsOnPhases(skeleton, phaseId, taskIdToPhase) {
   return [...deps]
 }
 
+// FTR-026: local re-implementation of tech-spec-assembler.js's findSectionRange/parseTableRows
+// (from req-assembler.js)/findSubsectionRange/parseComponentsTable — duplicated, not imported,
+// same "sandboxed runtime has no `require`" reason as the template-engine primitives above.
+// Keep in sync with tech-spec-assembler.js if spec/index.md's Section 9 table shape ever changes.
+function _findSectionRange(content, sectionNumber) {
+  const lines = content.split('\n')
+  let start = -1, end = lines.length
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^## (\d+)\.\s/)
+    if (!m) continue
+    const n = Number(m[1])
+    if (n === sectionNumber) start = i
+    else if (start !== -1 && n > sectionNumber) { end = i; break }
+  }
+  if (start === -1) throw new Error(`missing section ${sectionNumber}`)
+  return { start, end, lines }
+}
+function _parseTableRows(lines, start, end) {
+  const tableLines = lines.slice(start, end).filter(l => l.trim().startsWith('|'))
+  if (tableLines.length < 2) return []
+  return tableLines.slice(2).map(line =>
+    line.split('|').map(c => c.trim()).filter((_, i, a) => i > 0 && i < a.length - 1))
+}
+function _findSubsectionRange(lines, start, end, heading) {
+  let subStart = -1
+  for (let i = start; i < end; i++) {
+    if (lines[i].trim() === `### ${heading}`) { subStart = i; break }
+  }
+  if (subStart === -1) return null
+  let subEnd = end
+  for (let i = subStart + 1; i < end; i++) {
+    if (/^#{2,3}\s/.test(lines[i])) { subEnd = i; break }
+  }
+  return { start: subStart, end: subEnd }
+}
+function parseComponentsTableLocal(specIndexContent) {
+  const { start, end, lines } = _findSectionRange(specIndexContent, 9)
+  const entries = []
+  for (const [heading, changeType] of [['New files', 'New'], ['Modified files', 'Modified']]) {
+    const sub = _findSubsectionRange(lines, start, end, heading)
+    if (!sub) continue
+    for (const cells of _parseTableRows(lines, sub.start, sub.end)) {
+      const [filePath, purposeOrChange, addresses, domain, specLink] = cells
+      const m = specLink && specLink.match(/\(components\/([^)]+)\)/)
+      if (!m) throw new Error(`malformed Spec column for "${filePath}" in spec/index.md`)
+      entries.push({ filePath, purposeOrChange, changeType, domain, addresses, fileSlug: m[1] })
+    }
+  }
+  return entries
+}
+
+// Matches a task's own acceptanceCriteria against each component's Addresses column (the same
+// relation spec/index.md's own Section 9 table already expresses) to give the per-task worker
+// only the Tech-Spec content relevant to its own task, instead of the entire assembled spec —
+// the single largest structural token cost this feature removes. Falls back to the full
+// Components table (never zero content) when nothing matches, e.g. a purely organizational task.
+function buildTaskTechSpecExcerpt(components, task, specDir, specIndexContent) {
+  const acSet = new Set(task.acceptanceCriteria || [])
+  const relevant = components.filter(comp =>
+    (comp.addresses || '').split(',').map(s => s.trim()).some(acId => acSet.has(acId)))
+  if (relevant.length === 0) {
+    return "_No component's Addresses column cites this task's Acceptance Criteria — full " +
+      'Components table below._\n\n' + specIndexContent
+  }
+  return relevant.map(comp => {
+    const body = c.read(`${specDir}/components/${comp.fileSlug}`)
+    return `### ${comp.filePath}\n\n${body}`
+  }).join('\n\n')
+}
+
 // Compact prompt for the per-task detail-generation worker: this task's own skeleton entry,
 // the full skeleton's sibling task list (id + title + outcome only, for duplicate-
-// implementation awareness), and the Tech-Spec text (the per-task agent further narrows its
-// own Read/Grep use as needed — this call does not pre-slice the Tech-Spec by domain).
-function buildTaskPrompt(index, taskId, techSpecText) {
+// implementation awareness), and the Tech-Spec excerpt (FTR-026: already pre-sliced to this
+// task's own relevant component(s) by buildTaskTechSpecExcerpt, or the full legacy Tech-Spec
+// text for a feature with no spec/ directory).
+function buildTaskPrompt(index, taskId, techSpecText, taskTemplate) {
   const task = index.tasks[taskId]
   const siblingList = Object.entries(index.tasks)
     .map(([id, t]) => `- ${id}: ${t.title} — ${t.outcome}`).join('\n')
@@ -176,6 +247,7 @@ function buildTaskPrompt(index, taskId, techSpecText) {
     `Task skeleton entry (restate these fields verbatim; do not re-derive them):\n${JSON.stringify({ id: taskId, ...task }, null, 2)}`,
     `Tech-Spec:\n${techSpecText}`,
     `All tasks in this feature (for duplicate-implementation awareness):\n${siblingList}`,
+    `Template (tasks/{TASK_ID}.md):\n${taskTemplate}`,
   ].join('\n\n')
 }
 
@@ -184,32 +256,19 @@ const { featurePath, featureDir, prefix } = c.feature(args[0])
 return c.run(meta.name, featureDir, prefix, async () => {
   const file = suffix => `${featureDir}/${prefix}-${suffix}`
 
-  // FTR-025: pm-phase1.js no longer writes the assembled Requirements/Tech-Spec files — this
-  // phase's own unmodified internals (the Gate 1 digest re-check right below, wb-skeleton-
-  // check.js, wb-validate.js, the semantic validator prompt, ac-task-matrix.js, and
-  // gaia-generate-work-breakdown, which hard-aborts without these files) still need them on
-  // disk. Transparently bridge the gap: assemble fresh from req/+spec/ every run (same two
-  // subprocess calls pm-phase1.js used to make, relocated here), before anything below reads
-  // them. A legacy feature (monolithic files only, no req/spec/ directories — generated before
-  // this feature existed) is left untouched: nothing to assemble, no error.
-  await c.activity('bridge-requirements-tech-spec', async () => {
-    const reqDir = `${featureDir}/req`, specDir = `${featureDir}/spec`
-    // c.exists() only checks isFile() — never true for a directory — so this checks each
-    // split's own index.md (a real file) rather than the directory itself.
-    const hasReq = c.exists(`${reqDir}/index.md`), hasSpec = c.exists(`${specDir}/index.md`)
-    if (!hasReq && !hasSpec) return { bridged: false, reason: 'legacy (no split sources)' }
-    if (hasReq) {
-      const assembledRequirements = c.command(['run-asset', 'scripts/req-assembler.js',
-        '--project', c.root, '--', reqDir]).stdout
-      c.writeOutput(file('Requirements.md'), assembledRequirements)
-    }
-    if (hasSpec) {
-      const assembledTechSpec = c.command(['run-asset', 'scripts/tech-spec-assembler.js',
-        '--project', c.root, '--', specDir]).stdout
-      c.writeOutput(file('Tech-Spec.md'), assembledTechSpec)
-    }
-    return { bridged: true }
-  })
+  // FTR-026: pm-phase2.js is now split-source-native itself — every call site below reads
+  // req/index.md/spec/index.md directly, in-memory assembly feeds only the Gate 1 digest
+  // re-check, and nothing here writes an assembled monolithic file to disk (the
+  // bridge-requirements-tech-spec activity FTR-025 added as a transitional shim is gone; see
+  // git history for FTR-025's original version of this block). A legacy feature (monolithic
+  // files only, no req/spec/ directories) falls back to reading those files directly at every
+  // site below, unchanged from pre-FTR-026 behavior.
+  const reqDir = `${featureDir}/req`, specDir = `${featureDir}/spec`
+  // c.exists() only checks isFile() — never true for a directory — so this checks each split's
+  // own index.md (a real file) rather than the directory itself.
+  const hasReq = c.exists(`${reqDir}/index.md`), hasSpec = c.exists(`${specDir}/index.md`)
+  const reqIndexPath = hasReq ? `${reqDir}/index.md` : file('Requirements.md')
+  const specIndexPath = hasSpec ? `${specDir}/index.md` : file('Tech-Spec.md')
 
   const approvals = c.read(file('Approvals.md'))
   const gate = approvals.match(/^## Gate 1\b[^\n]*\n([\s\S]*?)(?=^## |$(?![\s\S]))/m)
@@ -225,7 +284,16 @@ return c.run(meta.name, featureDir, prefix, async () => {
   // 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')))
+    // FTR-026: recomputed in-memory from the split sources (same req-assembler.js/
+    // tech-spec-assembler.js subprocess calls pm-phase1.js already makes for its own
+    // docsDigest) instead of reading an assembled file from disk — never written here.
+    const assembledRequirements = hasReq
+      ? c.command(['run-asset', 'scripts/req-assembler.js', '--project', c.root, '--', reqDir]).stdout
+      : c.read(file('Requirements.md'))
+    const assembledTechSpec = hasSpec
+      ? c.command(['run-asset', 'scripts/tech-spec-assembler.js', '--project', c.root, '--', specDir]).stdout
+      : c.read(file('Tech-Spec.md'))
+    const currentDigest = c.hash(assembledRequirements + '\u0000' + assembledTechSpec)
     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')
     }
@@ -259,7 +327,7 @@ return c.run(meta.name, featureDir, prefix, async () => {
   // wb-validate.js now imports — run via subprocess since this runtime has no `require`)
   const skeletonCheck = await c.activity('wb-skeleton-check', async () => {
     const res = c.command(['run-asset', 'scripts/wb-skeleton-check.js', '--project', c.root,
-      '--', indexPath, file('Requirements.md')], [0, 1])
+      '--', indexPath, reqIndexPath], [0, 1])
     const parsed = JSON.parse(res.stdout)
     if (typeof parsed.valid !== 'boolean' || !Array.isArray(parsed.errors) ||
         (res.exitCode === 0) !== parsed.valid) throw new Error('Invalid skeleton-check result')
@@ -268,13 +336,27 @@ return c.run(meta.name, featureDir, prefix, async () => {
   })
 
   // 3. Per-task generation, resume-by-status, sequential
+  // FTR-026: each task's own worker call now receives only the Tech-Spec content relevant to its
+  // own Acceptance Criteria, not the entire assembled spec — computed once, before the loop, by
+  // matching each task's acceptanceCriteria against spec/index.md's own Addresses column.
+  const components = hasSpec ? parseComponentsTableLocal(c.read(specIndexPath)) : []
+  // The template lives under the toolkit's own installed scripts/templates/ — outside the
+  // project for a globally-installed toolkit, which a non-interactive worker invocation has no
+  // way to get Read permission for. Read once via print-asset, inline into every task's prompt,
+  // instead of telling the agent to Read it itself (same reasoning as pm-phase1.js's
+  // readTemplate/withTemplate — this runtime duplicates the primitive, not requires it, for the
+  // same "no `require`" reason as every other duplicated helper in this file).
+  const taskTemplate = c.command(['print-asset', 'scripts/templates/gaia-task-template.md', '--project', c.root]).stdout
   for (const phase of index.phases) {
     for (const taskId of phase.taskIds) {
       const task = index.tasks[taskId]
       const detailPath = `${wbsDir}/${task.detailFile}`
       if (task.status === 'generated' && c.exists(detailPath)) continue // resume: skip, no dispatch
+      const techSpecExcerpt = hasSpec
+        ? buildTaskTechSpecExcerpt(components, task, specDir, c.read(specIndexPath))
+        : c.read(file('Tech-Spec.md')) // legacy fallback: unchanged, full text
       const detail = await c.worker('gaia.agent.planner.work-breakdown-task',
-        buildTaskPrompt(index, taskId, c.read(file('Tech-Spec.md'))), { label: `work-breakdown-task:${taskId}` })
+        buildTaskPrompt(index, taskId, techSpecExcerpt, taskTemplate), { label: `work-breakdown-task:${taskId}` })
       c.writeOutput(detailPath, detail)
       task.status = 'generated'
       c.writeOutput(indexPath, JSON.stringify(index, null, 2)) // persist status after each task
@@ -285,7 +367,7 @@ return c.run(meta.name, featureDir, prefix, async () => {
   // existing pipeline, unchanged past this point except the path passed in
   const report = await c.activity('wb-validate', async () => {
     const res = c.command(['run-asset', 'scripts/wb-validate.js', '--project', c.root,
-      '--', wbsDir, file('Requirements.md')], [0, 1])
+      '--', wbsDir, reqIndexPath], [0, 1])
     const parsed = JSON.parse(res.stdout)
     if (typeof parsed.valid !== 'boolean' || !Array.isArray(parsed.errors) ||
         !Array.isArray(parsed.warnings) || (res.exitCode === 0) !== parsed.valid) throw new Error('Invalid validator result')
@@ -293,7 +375,7 @@ return c.run(meta.name, featureDir, prefix, async () => {
     return parsed
   })
   const semantic = await c.worker('gaia.agent.planner.validate-work-breakdown',
-    `${wbsDir}\n${file('Requirements.md')}`, { schema: {
+    `${wbsDir}\n${reqIndexPath}`, { schema: {
       type: 'object', properties: { valid: { type: 'boolean' }, findings: { type: 'array' } }, required: ['valid', 'findings'],
     } })
   if (!semantic.valid || semantic.findings.some(f => f.blocking)) throw new Error('Work breakdown semantic validation failed')
@@ -307,12 +389,17 @@ return c.run(meta.name, featureDir, prefix, async () => {
   const acTaskMatrix = await c.activity('ac-task-matrix', async () => {
     // FTR-023: ac-task-matrix.js's CLI gained a 3rd positional argument (Tech-Spec path) to
     // render the "Addressed by Tech-Spec File(s)" column.
+    // FTR-026: gained a required 5th (featureDir) argument; output moved from one loose
+    // {PREFIX}-AC-Task-Matrix.md file into a coverage-matrix/ subfolder as a JSON+MD pair.
     const result = c.command(['run-asset', 'scripts/ac-task-matrix.js', '--project', c.root,
-      '--', wbsDir, file('Requirements.md'), file('Tech-Spec.md'), prefix])
-    const matrixPath = file('AC-Task-Matrix.md')
-    if (!c.exists(matrixPath)) throw new Error('AC-Task matrix output missing')
-    c.read(matrixPath) // never trust an unread write
-    return { ...result, matrixPath }
+      '--', wbsDir, reqIndexPath, specIndexPath, prefix, featureDir])
+    const matrixJsonPath = `${featureDir}/coverage-matrix/index.json`
+    const matrixMdPath = `${featureDir}/coverage-matrix/index.md`
+    if (!c.exists(matrixJsonPath)) throw new Error('AC-Task matrix JSON output missing')
+    if (!c.exists(matrixMdPath)) throw new Error('AC-Task matrix MD output missing')
+    c.read(matrixJsonPath) // never trust an unread write
+    c.read(matrixMdPath)
+    return { ...result, matrixJsonPath, matrixMdPath }
   })
   // Assembled structure for c.estimates()'s metrics — via wbs-assembler.js's own CLI mode
   // (subprocess), since this runtime cannot `require` it in-process either.
@@ -326,7 +413,8 @@ return c.run(meta.name, featureDir, prefix, async () => {
       js_validator_report: report, js_validator_failed: false,
       semantic_validator_result: semantic, semantic_validator_failed: false,
       gate2_blocked: false,
-      ac_task_matrix_path: acTaskMatrix.matrixPath,
+      ac_task_matrix_json_path: acTaskMatrix.matrixJsonPath,
+      ac_task_matrix_md_path: acTaskMatrix.matrixMdPath,
       duration_bands: report.durationBands, domain_distribution: report.domainDistribution,
       warning_band_tasks: report.warnings.filter(w => w.category === 'duration_warning').map(w => ({ taskId: w.taskId, agentMinutes: w.details?.agentMinutes })),
       split_required_tasks: [], must_ac_uncovered: [], phase_unschedulable: [],