@dtlabs/ai-toolkit 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -1,4 +1,12 @@
 ## 0.1.4 (2026-07-21)
+## [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/package.json

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

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

@@ -23,7 +23,7 @@ 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.
 
 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.

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-phase2.js

@@ -164,10 +164,81 @@ 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).
+// 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) {
   const task = index.tasks[taskId]
   const siblingList = Object.entries(index.tasks)
@@ -184,32 +255,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 +283,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 +326,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 +335,20 @@ 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)) : []
   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), { 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 +359,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 +367,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 +381,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 +405,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: [],