@dtlabs/ai-toolkit 0.17.4 → 0.18.0

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

@@ -0,0 +1,127 @@
+'use strict'
+
+// FTR-021: loader/renderer for the split Requirements format (req/index.md +
+// req/use-cases/{UC-ID}.md). Unlike wbs-assembler.js (JSON -> Markdown rendering),
+// index.md is already Markdown narrative, so assembly here is textual reassembly:
+// splice each use case's already-rendered file into Section 2's slot, in index-table
+// order. Legacy input (a single monolithic file) is returned unchanged.
+
+const fs = require('fs')
+const path = require('path')
+
+class AssemblyError extends Error {}
+
+// Returns { start, end, lines }: `start` is the index of the "## N. " heading line for
+// `sectionNumber`, `end` is the index of the next "## M. " heading (M > sectionNumber),
+// or lines.length if none follows. Throws if the section is not found at all.
+function findSectionRange(content, sectionNumber) {
+  const lines = content.split('\n')
+  let start = -1
+  let 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 AssemblyError(`missing section ${sectionNumber}`)
+  return { start, end, lines }
+}
+
+// Parses the first Markdown table found inside [start, end) into rows, dropping the
+// header row and the "|---|---|" separator row. Returns an array of cell-arrays.
+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))
+}
+
+// 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.
+function parseUseCaseIndexTable(indexContent) {
+  const { start, end, lines } = findSectionRange(indexContent, 2)
+  return parseTableRows(lines, start, end).map(cells => {
+    const [id, title, actor, priority, fileCol] = cells
+    const fileMatch = fileCol && fileCol.match(/\(([^)]+)\)/)
+    if (!fileMatch) throw new AssemblyError(`malformed File column for UC "${id}" in index.md`)
+    return { id, title, actor, priority, file: fileMatch[1] }
+  })
+}
+
+// The "## 7. Acceptance Criteria" table: ID | Criterion | Related UC | Priority.
+function parseAcTable(indexContent) {
+  const { start, end, lines } = findSectionRange(indexContent, 7)
+  return parseTableRows(lines, start, end).map(cells => {
+    const [id, criterion, relatedUc, priority] = cells
+    return { id, criterion, relatedUc, priority }
+  })
+}
+
+// The "## 3. Business Rules" table: ID | Rule | Applies to.
+function parseBusinessRulesTable(indexContent) {
+  const { start, end, lines } = findSectionRange(indexContent, 3)
+  return parseTableRows(lines, start, end).map(cells => {
+    const [id, rule, appliesTo] = cells
+    return { id, rule, appliesTo }
+  })
+}
+
+// Replaces Section 2's body (everything after its heading, up to but not including the
+// next "## 3." heading) with `section2Body`, keeping the heading line itself and every
+// other section untouched.
+function spliceSection2(indexContent, section2Body) {
+  const { start, end, lines } = findSectionRange(indexContent, 2)
+  const heading = lines[start]
+  const before = lines.slice(0, start).concat([heading]).join('\n')
+  const after = lines.slice(end).join('\n')
+  return `${before}\n\n${section2Body}\n\n${after}`
+}
+
+function loadRequirements(inputPath) {
+  const stat = fs.statSync(inputPath, { throwIfNoEntry: false })
+  if (!stat) throw new AssemblyError(`path does not exist: ${inputPath}`)
+  if (stat.isFile()) return fs.readFileSync(inputPath, 'utf8') // legacy path (AC-07)
+
+  const indexPath = path.join(inputPath, 'index.md')
+  if (!fs.existsSync(indexPath)) throw new AssemblyError(`missing req/index.md at ${indexPath}`)
+  const indexContent = fs.readFileSync(indexPath, 'utf8')
+
+  const ucTable = parseUseCaseIndexTable(indexContent)
+  if (ucTable.length === 0) throw new AssemblyError('req/index.md has no rows in its Use Cases index table')
+
+  const ucBlocks = ucTable.map(row => {
+    const ucPath = path.join(inputPath, row.file)
+    if (!fs.existsSync(ucPath)) throw new AssemblyError(`use case "${row.id}" has no detail file at ${ucPath}`)
+    return fs.readFileSync(ucPath, 'utf8').trimEnd()
+  })
+
+  return spliceSection2(indexContent, ucBlocks.join('\n\n'))
+}
+
+if (require.main === module) {
+  const inputPath = process.argv[2]
+  if (!inputPath) {
+    process.stderr.write('Usage: node req-assembler.js <path-to-req-dir-or-legacy-file>\n')
+    process.exit(1)
+  }
+  try {
+    process.stdout.write(loadRequirements(path.resolve(inputPath)))
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message}\n`)
+    process.exit(err instanceof AssemblyError ? 1 : 2)
+  }
+}
+
+module.exports = {
+  loadRequirements,
+  parseUseCaseIndexTable,
+  parseAcTable,
+  parseBusinessRulesTable,
+  spliceSection2,
+  findSectionRange,
+  parseTableRows,
+  AssemblyError,
+}

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

@@ -0,0 +1,71 @@
+'use strict'
+
+// FTR-021: 4 pure self-consistency check functions for the split Requirements format
+// (req/index.md). Mirrors wb-graph-checks.js's convention: no file I/O, no process.exit,
+// just plain functions over an already-parsed plain object, returning an array of error
+// objects. The actual Markdown parsing lives in req-assembler.js / req-skeleton-check.js.
+
+const UC_ID_RE = /^UC-\d{2,}$/
+
+function checkUniqueUcIds({ ucIds }) {
+  const seen = new Set()
+  const duplicates = new Set()
+  for (const id of ucIds) {
+    if (seen.has(id)) duplicates.add(id)
+    else seen.add(id)
+  }
+  return [...duplicates].map(id => ({
+    category: 'DUPLICATE_UC_ID', severity: 'error', ucId: id,
+    message: `Duplicate UC ID "${id}" appears more than once in the use-case index table`,
+  }))
+}
+
+function checkUcIdFormat({ ucIds }) {
+  return ucIds.filter(id => !UC_ID_RE.test(id)).map(id => ({
+    category: 'INVALID_UC_ID_FORMAT', severity: 'error', ucId: id,
+    message: `UC ID "${id}" does not match the required UC-NN format`,
+  }))
+}
+
+// Orphan-file direction only: a use-cases/*.md file that no longer corresponds to any row
+// in the current table (e.g. left over after a UC was renamed/removed from a hand-edited
+// index.md). Deliberately NOT bidirectional — this check runs BEFORE per-use-case
+// dispatch, when every row is expected to have no file yet, so "table row without a file"
+// is the normal pre-dispatch state, not an error. That direction is enforced correctly,
+// after generation, by req-assembler.js's own missing-file error at assembly time.
+function checkUcTableFileParity({ ucIds }, existingUcFiles) {
+  const idSet = new Set(ucIds)
+  return existingUcFiles.filter(id => !idSet.has(id)).map(id => ({
+    category: 'UC_FILE_WITHOUT_TABLE_ROW', severity: 'error', ucId: id,
+    message: `use-cases/${id}.md exists but has no row in the use-case index table`,
+  }))
+}
+
+function checkCrossReferencesResolve({ ucIds, acTable, businessRules }) {
+  const idSet = new Set(ucIds)
+  const errors = []
+  const checkRefs = (rows, idField, refField, category) => {
+    for (const row of rows) {
+      const raw = row[refField]
+      if (raw == null || raw.trim() === 'All UCs') continue
+      for (const ref of raw.split(',').map(s => s.trim()).filter(Boolean)) {
+        if (!idSet.has(ref)) {
+          errors.push({
+            category, severity: 'error', id: row[idField], ucId: ref,
+            message: `${row[idField]}'s "${refField}" references unknown UC "${ref}"`,
+          })
+        }
+      }
+    }
+  }
+  checkRefs(acTable || [], 'id', 'relatedUc', 'DANGLING_AC_UC_REFERENCE')
+  checkRefs(businessRules || [], 'id', 'appliesTo', 'DANGLING_BR_UC_REFERENCE')
+  return errors
+}
+
+module.exports = {
+  checkUniqueUcIds,
+  checkUcIdFormat,
+  checkUcTableFileParity,
+  checkCrossReferencesResolve,
+}

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

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+'use strict'
+
+// FTR-021: deterministic structural pre-check for a Requirements skeleton (req/index.md),
+// run by pm-phase1.js before any per-use-case generation call is dispatched (UC-02).
+//
+// This is a separate script from req-assembler.js's CLI mode, not a reuse of it, because
+// pm-phase1.js's workflow-script runtime has no `require` (lib/workflow-runner.js) — this
+// is invoked as a real Node subprocess via `c.command(['run-asset',
+// 'scripts/req-skeleton-check.js', ...])`, the same pattern already used for
+// wb-skeleton-check.js/wb-validate.js/wb-render.js (FTR-020).
+
+const fs = require('fs')
+const path = require('path')
+const graphChecks = require('./req-graph-checks')
+const { parseUseCaseIndexTable, parseAcTable, parseBusinessRulesTable } = require('./req-assembler')
+
+function main() {
+  const indexPath = process.argv[2]
+  if (!indexPath) {
+    process.stderr.write('Usage: node req-skeleton-check.js <path-to-req-index.md>\n')
+    process.exit(2)
+  }
+
+  let indexContent
+  try {
+    indexContent = fs.readFileSync(indexPath, 'utf8')
+  } catch (e) {
+    console.log(JSON.stringify({ valid: false, errors: [{ message: `cannot read ${indexPath}: ${e.message}` }] }))
+    process.exit(2)
+  }
+
+  let ucTable, acTable, businessRules
+  try {
+    ucTable = parseUseCaseIndexTable(indexContent)
+    acTable = parseAcTable(indexContent)
+    businessRules = parseBusinessRulesTable(indexContent)
+  } catch (e) {
+    console.log(JSON.stringify({ valid: false, errors: [{ message: `parse failure: ${e.message}` }] }))
+    process.exit(2)
+  }
+
+  const ucIds = ucTable.map(r => r.id)
+  const useCasesDir = path.join(path.dirname(indexPath), 'use-cases')
+  const existingUcFiles = fs.existsSync(useCasesDir)
+    ? fs.readdirSync(useCasesDir).filter(f => f.endsWith('.md')).map(f => f.replace(/\.md$/, ''))
+    : []
+
+  const errors = [
+    ...graphChecks.checkUniqueUcIds({ ucIds }),
+    ...graphChecks.checkUcIdFormat({ ucIds }),
+    ...graphChecks.checkUcTableFileParity({ ucIds }, existingUcFiles),
+    ...graphChecks.checkCrossReferencesResolve({
+      ucIds,
+      acTable: acTable.map(a => ({ id: a.id, relatedUc: a.relatedUc })),
+      businessRules: businessRules.map(b => ({ id: b.id, appliesTo: b.appliesTo })),
+    }),
+  ]
+
+  console.log(JSON.stringify({ valid: errors.length === 0, errors }, null, 2))
+  process.exit(errors.length === 0 ? 0 : 1)
+}
+
+main()

package/src/claude/scripts/tech-spec-assembler.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+'use strict'
+
+// FTR-024: loader/renderer for the split Tech-Spec format (spec/index.md +
+// spec/components/*.md). Reconstructs the exact 12-section monolithic shape
+// gaia-generate-tech-spec already produced in one turn before this feature: Section 9 rebuilt
+// from the skeleton's own Components table (authoritative, restated from each component, never
+// re-derived); Sections 3 (Backend)/4 (Frontend)/5 (External Integrations) populated per
+// component Domain routing; Section 10 (Testing Strategy) built from every component's own
+// Tests subsection, unconditionally. Legacy input (a single monolithic file) is returned
+// unchanged.
+
+const fs = require('fs')
+const path = require('path')
+const { findSectionRange, parseTableRows } = require('./req-assembler')
+
+const SECTION_BY_DOMAIN = { BE: 3, FE: 4 } // anything else (DB/DevOps/INFRA/TEST) routes to 5
+
+class AssemblyError extends Error {}
+
+// Same helper tech-spec-graph-checks.js already has (FTR-023) — duplicated here deliberately,
+// not imported: this script reads 5-column rows for a structurally different purpose (section
+// routing, not Addresses validation), and importing a function named for a different module's
+// job would read as a false shared contract. Same precedent as wbs-assembler.js independently
+// reimplementing plan.js's field-parsing convention (FTR-020).
+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 parseComponentsTable(indexContent) {
+  const { start, end, lines } = findSectionRange(indexContent, 9)
+  const entries = []
+  // changeType ('New'/'Modified') comes from WHICH table a row was found in, not from any
+  // column's text — the "Purpose-or-Change" column is free-text (e.g. "does backend stuff"),
+  // never literally the word "New"/"Modified". A real bug, found only by actually assembling a
+  // hand-built fixture and inspecting Section 9's rebuilt New/Modified split: every row landed
+  // under "Modified" because `change.toLowerCase() === 'new'` almost never matched free text.
+  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)) {
+      // Column order: Addresses MUST stay 3rd (index 2) — the exact position
+      // tech-spec-graph-checks.js's unmodified, positional parser already reads from a
+      // 3-column legacy table (FTR-023). Domain/Spec are new trailing columns.
+      const [filePath, purposeOrChange, addresses, domain, specLink] = cells
+      const m = specLink && specLink.match(/\(components\/([^)]+)\)/)
+      if (!m) throw new AssemblyError(`malformed Spec column for "${filePath}" in spec/index.md`)
+      entries.push({ filePath, purposeOrChange, changeType, domain, addresses, fileSlug: m[1] })
+    }
+  }
+  return entries
+}
+
+// Parses one component file into { change, body, tests }: `body` is everything between
+// "## Change" (exclusive of its own heading) and "## Tests" — the component's own
+// Algorithm/Schema content, whatever heading it actually used (the component template's own
+// section-naming is a free-text "menu, not a checklist" — this parser does not care what that
+// heading is literally called, only that it comes after Change and before Tests).
+//
+// Fence-aware: a component's own Change/body/Tests content may legitimately quote another
+// file's literal "## Heading" line inside a fenced code example (e.g. a before/after excerpt of
+// a markdown prompt file being modified, exactly the shape FTR-025's own spec/components/
+// gaia-validate-feature-docs.md.md needed) — a naive line scan mistook that quoted line for a
+// real section boundary, corrupting the assembled Section 3/4/5/10 content. Lines inside a
+// fence are never treated as a heading, regardless of whether the fence appears before or after
+// the real heading in the file.
+//
+// Length-aware, not a plain open/close boolean toggle: real CommonMark fences close only on a
+// backtick run at least as long as the one that opened them, which is exactly what lets a
+// longer outer fence (e.g. ````markdown) legitimately contain a shorter inner one (```) as a
+// nested quoted example — a simple boolean toggle miscounts any such nesting (every backtick
+// run flips it, regardless of length), landing in the wrong state for the rest of the file the
+// moment the total run count is odd. Found exactly this way: FTR-025's own spec/components/
+// SKILL.md.md quotes a before/after Markdown example that itself contains a fenced block.
+function _nonFencedHeadingIndexes(lines, predicate) {
+  let fenceLen = 0 // 0 = not in a fence; otherwise the backtick-run length that opened it
+  const indexes = []
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^(`{3,})/)
+    if (m) {
+      const runLen = m[1].length
+      if (fenceLen === 0) fenceLen = runLen // opens a new fence
+      else if (runLen >= fenceLen) fenceLen = 0 // a run at least as long as the opener closes it
+      // a shorter run while already fenced is just literal backtick content inside the fence
+      continue
+    }
+    if (fenceLen !== 0) continue
+    if (predicate(lines[i])) indexes.push(i)
+  }
+  return indexes
+}
+function parseComponentDetail(content) {
+  const lines = content.split('\n')
+  const changeIdx = _nonFencedHeadingIndexes(lines, l => l.trim() === '## Change')[0] ?? -1
+  const testsIdx = _nonFencedHeadingIndexes(lines, l => l.trim() === '## Tests')[0] ?? -1
+  if (changeIdx === -1) throw new AssemblyError('component file is missing its "## Change" section')
+  if (testsIdx === -1) throw new AssemblyError('component file is missing its "## Tests" section')
+  const nextHeadingIdx = _nonFencedHeadingIndexes(lines, l => /^##\s/.test(l)).find(i => i > changeIdx)
+  const changeEnd = nextHeadingIdx === undefined ? lines.length : nextHeadingIdx
+  return {
+    change: lines.slice(changeIdx + 1, changeEnd).join('\n').trim(),
+    body: lines.slice(changeEnd, testsIdx).join('\n').trim(),
+    tests: lines.slice(testsIdx + 1).join('\n').trim(),
+  }
+}
+
+// Replaces everything between "## {n}. " and the next "## " heading with `body`, keeping the
+// heading line itself — same splice primitive as req-assembler.js's spliceSection2, generalized
+// to any section number instead of hardcoding 2.
+function spliceSectionBody(doc, n, body) {
+  const { start, end, lines } = findSectionRange(doc, n)
+  const heading = lines[start]
+  const before = lines.slice(0, start).concat([heading]).join('\n')
+  const after = lines.slice(end).join('\n')
+  return `${before}\n\n${body}\n\n${after}`
+}
+
+function rewriteSection9(doc, components) {
+  const newFiles = components.filter(c => c.changeType === 'New')
+  const modifiedFiles = components.filter(c => c.changeType === 'Modified')
+  const table = rows => '| Path | Purpose-or-Change | Addresses |\n|---|---|---|\n' +
+    rows.map(c => `| ${c.filePath} | ${c.purposeOrChange} | ${c.addresses} |`).join('\n')
+  const body = `### New files\n${table(newFiles)}\n\n### Modified files\n${table(modifiedFiles)}`
+  return spliceSectionBody(doc, 9, body)
+}
+
+function loadTechSpec(inputPath) {
+  const stat = fs.statSync(inputPath, { throwIfNoEntry: false })
+  if (!stat) throw new AssemblyError(`path does not exist: ${inputPath}`)
+  if (stat.isFile()) return fs.readFileSync(inputPath, 'utf8') // legacy path
+
+  const indexPath = path.join(inputPath, 'index.md')
+  if (!fs.existsSync(indexPath)) throw new AssemblyError(`missing spec/index.md at ${indexPath}`)
+  const indexContent = fs.readFileSync(indexPath, 'utf8')
+  const components = parseComponentsTable(indexContent)
+  if (components.length === 0) throw new AssemblyError('spec/index.md has no rows in its Components table')
+
+  const detailByPath = {}
+  for (const c of components) {
+    const compPath = path.join(inputPath, 'components', c.fileSlug)
+    if (!fs.existsSync(compPath)) throw new AssemblyError(`component "${c.filePath}" has no detail file at ${compPath}`)
+    detailByPath[c.filePath] = parseComponentDetail(fs.readFileSync(compPath, 'utf8'))
+  }
+
+  let doc = rewriteSection9(indexContent, components)
+  for (const sectionNum of [3, 4, 5]) {
+    const matching = components.filter(c => (SECTION_BY_DOMAIN[c.domain] || 5) === sectionNum)
+    const body = matching.length
+      ? matching.map(c => `### ${c.filePath}\n\n${detailByPath[c.filePath].body}`).join('\n\n')
+      : '_No components in this category._'
+    doc = spliceSectionBody(doc, sectionNum, body)
+  }
+  const testsBody = components.map(c => `### ${c.filePath}\n\n${detailByPath[c.filePath].tests}`).join('\n\n')
+  doc = spliceSectionBody(doc, 10, testsBody)
+  return doc
+}
+
+if (require.main === module) {
+  const inputPath = process.argv[2]
+  if (!inputPath) {
+    process.stderr.write('Usage: node tech-spec-assembler.js <path-to-spec-dir-or-legacy-file>\n')
+    process.exit(1)
+  }
+  try {
+    process.stdout.write(loadTechSpec(path.resolve(inputPath)))
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message}\n`)
+    process.exit(err instanceof AssemblyError ? 1 : 2)
+  }
+}
+
+module.exports = {
+  loadTechSpec,
+  parseComponentsTable,
+  parseComponentDetail,
+  spliceSectionBody,
+  findSubsectionRange,
+  AssemblyError,
+}

package/src/claude/scripts/tech-spec-graph-checks.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+'use strict'
+
+// FTR-023: deterministic structural check that every Tech-Spec File Inventory "Addresses"
+// reference resolves to a real Requirements AC ID. Combined parse/check/CLI in one file — unlike
+// wb-graph-checks.js/req-graph-checks.js (several checks, multiple consumers), this feature has
+// exactly one check used in exactly one context, so a separate checks-module + CLI-wrapper split
+// isn't justified.
+
+const fs = require('fs')
+const path = require('path')
+const { findSectionRange, parseTableRows } = require('./req-assembler')
+const { parseAcTable } = require('./wb-graph-checks')
+
+// Locates a "### {heading}" line within [start, end) and returns its own sub-range, up to the
+// next "###" or "##" heading (or `end`). Tech-Spec-specific: req-assembler.js's
+// findSectionRange only knows about numbered "## N." headings, one level up from this.
+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 parseFileInventoryEntries(techSpecContent) {
+  const { start, end, lines } = findSectionRange(techSpecContent, 9)
+  const entries = []
+  for (const heading of ['New files', 'Modified files']) {
+    const sub = findSubsectionRange(lines, start, end, heading)
+    if (!sub) continue // a Tech-Spec with only one of the two tables is valid (e.g. a pure-addition feature)
+    for (const cells of parseTableRows(lines, sub.start, sub.end)) {
+      const filePath = cells[0]
+      const addressesCell = cells[2] // Path | Purpose-or-Change-description | Addresses
+      const acIds = (!addressesCell || addressesCell.trim() === '—') ? []
+        : addressesCell.split(',').map(s => s.trim()).filter(Boolean)
+      entries.push({ filePath, acIds })
+    }
+  }
+  return entries
+}
+
+function checkAddressesResolve(entries, validAcIds) {
+  const idSet = new Set(validAcIds)
+  const errors = []
+  for (const entry of entries) {
+    for (const acId of entry.acIds) {
+      if (!idSet.has(acId)) {
+        errors.push({
+          category: 'DANGLING_TECH_SPEC_AC_REFERENCE', severity: 'error',
+          filePath: entry.filePath, acId,
+          message: `File "${entry.filePath}"'s "Addresses" column references unknown AC "${acId}"`,
+        })
+      }
+    }
+  }
+  return errors
+}
+
+if (require.main === module) {
+  const [techSpecPath, requirementsPath] = process.argv.slice(2)
+  if (!techSpecPath || !requirementsPath) {
+    process.stderr.write('Usage: node tech-spec-graph-checks.js <tech-spec-path> <requirements-path>\n')
+    process.exit(2)
+  }
+  let entries, acMap
+  try {
+    entries = parseFileInventoryEntries(fs.readFileSync(path.resolve(techSpecPath), 'utf8'))
+    acMap = parseAcTable(path.resolve(requirementsPath))
+  } catch (e) {
+    console.log(JSON.stringify({ valid: false, errors: [{ message: `parse failure: ${e.message}` }] }))
+    process.exit(2)
+  }
+  const errors = checkAddressesResolve(entries, [...acMap.keys()])
+  console.log(JSON.stringify({ valid: errors.length === 0, errors }, null, 2))
+  process.exit(errors.length === 0 ? 0 : 1)
+}
+
+module.exports = { parseFileInventoryEntries, checkAddressesResolve, findSubsectionRange }

package/src/claude/scripts/templates/gaia-component-template.md

@@ -0,0 +1,64 @@
+<!--
+COMPONENT TEMPLATE — spec/components/{fileSlug}.md
+
+Canonical structure for one component's technical design in the split Tech-Spec format (FTR-024).
+A "component" is one file this feature creates or modifies — the granularity is the same as one
+row in spec/index.md's own Section 9 "File Inventory" / Components table, not an arbitrary
+subdivision.
+
+This is the REAL, currently-implemented contract — authoritative source:
+`src/claude/agents/gaia-generate-tech-spec-component.md`'s own "Output" section, and
+`src/claude/scripts/tech-spec-assembler.js`'s `parseComponentDetail`, which requires exactly
+`## Change` and `## Tests` to exist, in that relative order, to parse a component file correctly.
+An earlier FTR-020 draft of this template (component-template.md) additionally specified
+`Related Open Questions`/`Related components`/`Addresses` header lines and a `Decision:` section —
+none of those exist in the real, shipped format; this file reflects what is actually generated and
+parsed today, not that earlier draft.
+
+Fill in every placeholder (angle brackets) and delete every HTML comment block (including this
+one) before treating the file as finished.
+-->
+
+# {Path} — {New | Modified}
+
+## Change
+
+<!--
+One paragraph: what changes about this file and why — name the specific functions/sections
+affected, not just "this file is updated to support the new feature". If New: what it exports and
+the shape of its inputs/outputs. If Modified: what specifically is added, replaced, or removed,
+and what is explicitly left unchanged.
+-->
+
+<prose>
+
+## {Algorithm | Data Model | Service Interface | Component Props | whichever name fits this
+component's own real nature — pick one, do not invent multiple competing headings}
+
+<!--
+Real pseudocode or real code, not a prose description of "what it does". If this component
+relocates logic from an existing file, name the exact source file and line ranges if known.
+
+If this component genuinely needs no design content beyond Change (e.g. a trivial configuration
+file), omit this entire middle heading rather than inventing content — Change and Tests are always
+required, this one is not.
+-->
+
+<pseudocode/code + prose explaining non-obvious choices>
+
+## Tests
+
+<!--
+The specific test file(s) this component's change requires, and the key cases that matter — not a
+generic "add tests for X".
+-->
+
+<prose / bullet list of test file(s) and key cases>
+
+<!--
+PARSING CONTRACT — read by tech-spec-assembler.js's parseComponentDetail: `## Change` and
+`## Tests` must both exist, in that relative order; everything between them (including the middle
+heading above, whatever it's actually called) is this component's own design body, concatenated
+verbatim into the assembled Tech-Spec's Section 3 (Backend) / 4 (Frontend) / 5 (External
+Integrations), routed by this component's own Domain from spec/index.md's Components table.
+-->