@dtlabs/ai-toolkit 0.17.5 → 0.19.0

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.
+-->

package/src/claude/scripts/templates/gaia-dependency-graph-template.md

@@ -0,0 +1,85 @@
+<!--
+DEPENDENCY GRAPH TEMPLATE — developer-plan/dependency-graph.md
+
+STATUS (as of FTR-025): reference/design-only. No generator currently produces this file — grep
+for "dependency-graph"/"dependencyGraph" across lib/ and src/claude/ turns up nothing that writes
+it. Kept here, moved and renamed alongside the other six templates, for whenever the
+developer-plan/dependency-graph.md concept is actually implemented; do not assume it is wired into
+any real pipeline today.
+
+Human-readable companion to developer-plan/plan.json, produced BY THE SAME GENERATOR that writes
+plan.json — never hand-authored per feature, and never a place to restate plan.json's own arrays.
+This file is pure output: nothing reads it back programmatically (unlike the wbs/ task and phase
+templates, there is no parsing contract here — delete this whole comment block in a generated
+instance, there is nothing downstream to keep honest).
+
+Structure, in this fixed order: (1) a one-line pointer note, (2) the Mermaid dependency graph —
+the ONLY data visualization this file keeps, because a diagram is a genuinely different
+representation of plan.json's `readyQueue[].dependsOn`, not the same facts reformatted as another
+table, (3) a fixed "Sequence and waves" section that explicitly refuses to reprint
+`readyQueue`/`phaseWaves` as Markdown tables, (4) a fixed "Integrity" section. An earlier draft of
+this file DID reprint the ready-queue and phase-waves as tables and was reverted after review —
+same facts in two places drifts the moment plan.json regenerates and this file doesn't. Do not
+reintroduce those tables.
+
+Placeholders:
+  {FEATURE}      feature ID, e.g. FTR-020
+  {PHASE_ID}     a phase ID from plan.json's phases[].id
+  {TASK_ID}      a task ID from plan.json's readyQueue[].id
+  {NODE_ID}      {TASK_ID} with every hyphen removed/underscored so it's a legal Mermaid node
+                 name (Mermaid node IDs can't contain hyphens) — drop the phase prefix once the
+                 node already lives inside that phase's subgraph, drop the literal "TASK", keep
+                 it short and unique within the subgraph (e.g. US-02-TASK-BE-01 -> US02_BE01)
+  {sourceDigest} plan.json's own sourceDigest value, copied verbatim, including the "sha256:"
+                 prefix
+-->
+
+# {FEATURE} — Dependency Graph & Implementation Sequence
+
+> Human-readable companion to [`plan.json`](plan.json) — the machine-readable file is
+> authoritative; this is a rendered view of the same data, regenerated alongside it, never
+> hand-edited independently (same convention as `{PREFIX}-Work-Breakdown.md` being generated
+> from the JSON it describes — see `wb-render.js`).
+
+## Dependency graph
+
+<!--
+One `subgraph {PHASE_ID}` block per phase, in plan.json's phases[] order, listing that phase's
+own taskIds as Mermaid nodes ({NODE_ID}[{TASK_ID}]). Below every subgraph block, one
+`{FROM_NODE_ID} --> {TO_NODE_ID}` edge per (task, dependency) pair found by walking every
+readyQueue[].dependsOn entry — one edge per dependency, not one edge per task (a task with 3
+entries in dependsOn gets 3 edges). Edge order: by readyQueue[].sequence, then by the order the
+dependency appears inside that task's own dependsOn array. A task with an empty dependsOn
+contributes no edges, only its node.
+-->
+
+```mermaid
+graph TD
+  subgraph {PHASE_ID}
+    {NODE_ID}[{TASK_ID}]
+  end
+
+  {FROM_NODE_ID} --> {TO_NODE_ID}
+```
+
+## Sequence and waves
+
+The dispatch order (`readyQueue`), the per-task dependencies (`dependsOn`), and the phase
+waves (`phaseWaves`) are **not repeated here** — they already exist as structured data in
+[`plan.json`](plan.json) and reprinting them as a Markdown table would just be the same facts
+in a second place, free to drift the moment `plan.json` is regenerated and this file isn't.
+Read them straight from there; the Mermaid diagram above is the only rendering kept in this
+file, because it's a genuinely different representation (visual graph) rather than the same
+rows reformatted.
+
+## Integrity
+
+- **Source digest:** `{sourceDigest}` — computed over every file under `wbs/` (sorted by
+  relative path, each length-prefixed before hashing, same technique as
+  `lib/task-executor/plan.js`'s own `_computePlanDigest`, extended from "two byte blobs" to
+  "every file in a directory"). A re-run of the same computation against the current `wbs/`
+  must reproduce this exact value, or this plan is stale and must be regenerated before
+  implementation proceeds — mirrors `plan.js`'s existing resume-safety contract, made an
+  explicit, reviewable file instead of an internal runtime-only check.
+- Per-task and per-phase checksums in `plan.json` let a drift check point at the *specific*
+  file that changed, not just "something changed somewhere."

package/src/claude/scripts/templates/gaia-requirements-index-template.md

@@ -0,0 +1,144 @@
+<!--
+REQUIREMENTS INDEX TEMPLATE — req/index.md
+
+Canonical structure for the Requirements index in the split format (FTR-021). Holds everything
+that is NOT naturally owned by a single Use Case — i.e. everything except each Use Case's own flow
+body, which gets its own file under use-cases/{UC-ID}.md (see gaia-use-case-template.md).
+
+This is the REAL, currently-implemented 9-section contract — authoritative source:
+`src/claude/agents/gaia-generate-requirements.md`'s own "Output Structure" section, and
+`src/claude/scripts/req-skeleton-check.js`/`req-assembler.js`, which require exactly these 9
+numbered top-level `## N. ` headings, in order, to exist. An earlier FTR-020 exploratory draft of
+this template used a different 7-section numbering (no "UI Requirements" or "Open Questions" as
+their own sections) that was never what Requirements generation actually shipped — this file
+reflects the real, current format, not that earlier draft.
+
+SPLITTING PRINCIPLE (apply this test to any new section before deciding where it goes): does this
+content belong to exactly one UC, or does it reference/apply to several? A Business Rule that
+applies to 3 UCs, a Data Requirement describing a schema used by the whole feature, an NFR that
+constrains the feature as a whole — none of these are owned by one UC any more than a shared setup
+module is owned by one Work Breakdown task. Only split out content that is genuinely per-item;
+everything cross-cutting stays here, in one place.
+
+EVERY table in this document (and in every use-case file) MUST be followed immediately by a
+one-line legend (blockquote) explaining each column.
+
+Fill in every placeholder (angle brackets) and delete every HTML comment block (including this
+one) before treating the file as finished.
+-->
+
+# {PREFIX} — Functional Requirements (Index)
+
+## 1. Introduction
+
+### 1.1 Purpose
+
+<prose: brief description of what this requirements document covers>
+
+### 1.2 Scope
+
+<prose: what is in scope and out of scope>
+
+### 1.3 Actors
+
+| Actor | Description |
+|-------|-------------|
+| <actor> | <description> |
+
+## 2. Use Cases
+
+<!-- One row per UC. This table is the single place that lists every UC that exists — the
+     use-cases/ directory listing must match it exactly. Title here is a short label, NOT the
+     full flow description — that's in the UC's own file (FTR-021: a separate call per UC fills
+     in each row's full detail after this skeleton is accepted). -->
+
+| UC ID | Title | Actor | Priority | File |
+|-------|-------|-------|----------|------|
+| UC-{NN} | <short title> | <actor(s)> | <Must \| Should \| Could> | [use-cases/UC-{NN}.md](use-cases/UC-{NN}.md) |
+
+> **Legend:** **UC ID** — unique identifier, referenced from Business Rules' `Applies to` and
+> Acceptance Criteria's `Related UC` columns. **Title** — short label; full flow is in the linked
+> file. **Actor** — who/what initiates or participates. **Priority** — MoSCoW; drives downstream
+> Must-coverage checks. **File** — this UC's own detail file.
+
+## 3. Business Rules
+
+| ID | Rule | Applies to |
+|----|------|-----------|
+| BR-{NN} | <rule statement> | <UC-ID, UC-ID, ... \| All UCs> |
+
+> **Legend:** **ID** — unique identifier. **Rule** — the constraint itself. **Applies to** —
+> which UC(s) this rule constrains, or "All UCs" if universal.
+
+## 4. Data Requirements
+
+### 4.1 Entities
+
+<!-- For each entity: fields, types, constraints, relationships. -->
+
+<prose>
+
+### 4.2 Validation Rules
+
+| Field | Rule |
+|-------|------|
+| <field> | <rule> |
+
+## 5. Non-Functional Requirements
+
+| ID | Category | Requirement |
+|----|----------|-------------|
+| NFR-{NN} | <Security \| Performance \| Usability \| ...> | <requirement statement> |
+
+## 6. UI Requirements
+
+<!-- N/A — internal/technical feature; no UI surface is introduced or changed, if that's true for
+     this feature — otherwise fill in both subsections below. -->
+
+### 6.1 Pages / Screens
+
+<!-- For each page: purpose, layout description, components, interactions. -->
+
+<prose>
+
+### 6.2 Navigation Flow
+
+<prose: how pages connect and how the user moves between them>
+
+## 7. Acceptance Criteria
+
+<!--
+Column contract: first three columns MUST be exactly "ID", "Criterion", "Related UC" in that
+order — parsed as-is by wb-graph-checks.js's parseAcTable (do not reinvent the column format).
+"Related UC" must be a single UC-ID, a comma-separated list, or the literal "All UCs".
+-->
+
+| ID | Criterion | Related UC | Priority |
+|----|-----------|-------------|----------|
+| AC-{NN} | <Given/When/Then or plain testable statement> | <UC-ID \| UC-ID, UC-ID \| All UCs> | <Must \| Should \| Could> |
+
+> **Legend:** **ID** — unique identifier; the anchor used across the whole
+> feature.md↔req↔spec↔Work-Breakdown traceability chain. **Criterion** — a testable Given/When/Then
+> statement. **Related UC** — which UC(s) this AC belongs to, or "All UCs"; machine-parsed by
+> `wb-graph-checks.js`'s `parseAcTable`, not just descriptive. **Priority** — MoSCoW; every Must AC
+> must be covered by ≥1 WB task.
+
+## 8. Dependencies and Assumptions
+
+<!-- External prerequisites, prior features this one builds on, fixed constraints, and anything
+     that must be resolved before Gate 1. -->
+
+<prose / bullet list>
+
+## 9. Open Questions
+
+| # | Question | Impact | Suggested resolution |
+|---|----------|--------|---------------------|
+| <N> | <question> | <impact if unresolved> | <suggested resolution, or "open — deferred"> |
+
+<!--
+PARSING CONTRACT — req-skeleton-check.js/req-assembler.js require exactly these 9 numbered
+`## N. ` headings, in order, to exist (assertCompleteSections's truncation guard in pm-phase1.js
+checks the same 9 headings). Section 2's table is the index into use-cases/{UC-ID}.md — never
+write a UC's flow body inline here.
+-->

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

@@ -0,0 +1,92 @@
+<!--
+TASK DETAIL TEMPLATE — wbs/tasks/{TASK_ID}.md
+
+Canonical structure for a task file in the FTR-020 split Work Breakdown format. Every task file
+has exactly three parts, in this order: (1) the field block, (2) Implementation notes,
+(3) Verification commands. Fill in every placeholder below (angle brackets) and delete every
+HTML comment block (including this one) before treating the file as finished. Do not add, remove,
+or reorder the 14 fields — they are parsed positionally as the contiguous run immediately after
+the heading (see "Parsing contract" at the bottom of this file).
+-->
+<a id="task-{TASK_ID}"></a>
+### {TASK_ID}
+
+- **Task ID:** {TASK_ID}
+- **Title:** <Short, specific, action-oriented. Not a restatement of the outcome.>
+- **Outcome:** <The ONE observable thing that exists/changed after this task is done — one
+  factual, verifiable sentence. If you need "and" to describe it, the task is probably not
+  atomic — split it (see Atomicity Contract in gaia-generate-work-breakdown.md).>
+- **Domain:** <one of: BE | FE | DB | DevOps | INFRA | TEST>
+- **Agent type:** <one of: developer-backend | developer-frontend | developer-testing | review-solution>
+- **Dependencies:** <comma-separated task IDs this task's work requires to exist first, or `—` if none>
+- **Acceptance criteria:** <comma-separated AC IDs from Requirements that this task covers, scoped
+  to this task's own phase — or `—` if none>
+- **Estimate — agent minutes:** <integer. Target ≤15 (no flag); 16–20 acceptable (no flag);
+  21–30 is a non-blocking warning — justify in Grouping rationale below; >30 is rejected, split
+  the task instead.>
+- **Estimate — tokens:** <integer, rough order of magnitude for the agent invocation>
+- **Output count:** <integer ≥1. Almost always 1 — see Atomicity Contract. >1 requires a non-null
+  Grouping rationale below.>
+- **Grouping rationale:** <required (non-`—`) only when Output count >1 or the estimate is in the
+  21–30 min warning band; otherwise `—`>
+- **Commit type:** <conventional-commit type: feat | fix | refactor | test | chore | docs | ...>
+- **Commit scope:** <optional conventional-commit scope, or `—`>
+- **Commit subject:** <imperative, concise, no trailing period — the renderer prepends
+  `type(scope): ` automatically, do not include it here>
+
+**Implementation notes:**
+
+<!--
+This is the part that makes a task file self-sufficient: someone (human or agent) reading ONLY
+this file — not the whole Tech-Spec — should know exactly what to do and how.
+
+Write:
+- If this task RELOCATES or MODIFIES existing code: name the exact file(s) and, if you know
+  them, the exact current line ranges to copy from or change. Show a before/after snippet, not
+  just a description of the change.
+- If this task CREATES something new: give its real signature(s) (function names, parameters,
+  return shape) and the actual algorithm as pseudocode or real code — not just a description of
+  what it should do.
+- If this task is a TEST: show at least one concrete `test()`/`describe()` block with real
+  assertions against the real function/CLI being tested, not a prose list of "things to check".
+- Length target: not 10 lines (too thin to act on without re-deriving the design yourself), not
+  10 pages (defeats the point of a small, bounded, independently generated task). A few concrete
+  snippets plus the reasoning that connects them is usually right.
+- It is fine — often good — to include a literal example of this exact task-file format inside a
+  fenced code block (e.g. to show another agent's expected output shape). If you do, see the
+  parsing-contract warning at the bottom of this file: it is specifically about this situation.
+-->
+
+<prose + pseudocode/code here>
+
+**Verification commands:**
+
+<!--
+One or more real shell commands (use AGENTS.md's actual build/test commands for this project)
+that verify this task's output. Must be non-empty. Each command gets its own fenced block,
+preserved byte-for-byte verbatim — never edited, escaped, or "cleaned up" by any tool that
+touches this file; this is what lets a command contain `|`, backticks, or other shell syntax
+safely.
+-->
+
+```
+<command>
+```
+
+<!--
+PARSING CONTRACT (do not delete this section from the real template file; delete only from a
+filled-in task instance) — read by wbs-assembler.js's parseTaskDetailBlock:
+1. Field values are read from the CONTIGUOUS RUN of `- **Label:** value` lines starting
+   immediately after the `### {TASK_ID}` heading. Scanning STOPS at the first line that is not
+   in that shape — so an example block further down in Implementation notes that happens to
+   contain `- **Task ID:** ...`-shaped lines is never mistaken for the real fields. (A real bug,
+   found and fixed during this feature's own definition — see US-03-TASK-INFRA-01.md and
+   Tech-Spec §4.)
+2. The verification commands are the fenced block(s) after the LAST occurrence of
+   "**Verification commands:**" in the file — not the first — for the same reason: an
+   illustrative example earlier in the file must never be mistaken for the real section.
+3. Conclusion for anyone writing Implementation notes: you may safely show an example of this
+   format inside your own notes. You may NOT rely on your example being the last occurrence of
+   "**Verification commands:**" in the file — the real one (at the bottom) always is, by
+   construction, as long as you don't add a second real verification section.
+-->