@dtlabs/ai-toolkit 0.20.0 → 0.21.1

package/CHANGELOG.md

@@ -1,4 +1,20 @@
 ## 0.1.4 (2026-07-21)
+## [0.21.1](https://github.com/dtlab-tech/ai-toolkit/compare/v0.21.0...v0.21.1) (2026-10-20)
+
+
+### Bug Fixes
+
+* harden pipeline resilience across four real-world failures (FTR-029) ([ef57862](https://github.com/dtlab-tech/ai-toolkit/commit/ef578623541c084d17aeb6b0f53dba076e5a449e))
+* **workflow-control, pm-phase1:** harden pipeline resilience across four real-world failures (FTR-029) ([34a9ec9](https://github.com/dtlab-tech/ai-toolkit/commit/34a9ec9db645d1475e41e0c3875c8431a1ae0fda))
+
+## [0.21.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.20.0...v0.21.0) (2026-10-20)
+
+
+### Features
+
+* bound the feature-doc validator to the Tech-Spec skeleton (FTR-028) ([80869ce](https://github.com/dtlab-tech/ai-toolkit/commit/80869ced8b8d24ef7b0669fabbb152e8bf243794))
+* **pm-phase1, agent-registry:** bound the feature-doc validator to the Tech-Spec skeleton (FTR-028) ([9eb7f72](https://github.com/dtlab-tech/ai-toolkit/commit/9eb7f7222ff80eb2b26815a4f58f923f9ca09f1d))
+
 ## [0.20.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.19.2...v0.20.0) (2026-10-19)
 
 

package/lib/agent-registry.js

@@ -259,6 +259,19 @@ const CATALOG = [
     deprecationTarget:     null,
     platforms:             ['claude'],
   },
+  {
+    agentId:               'gaia.agent.planner.validate-tech-spec-component-detail',
+    nativeNames:           { claude: 'gaia-validate-tech-spec-component-detail' },
+    relativeInstallPath:   '.claude/agents/gaia-validate-tech-spec-component-detail.md',
+    role:                  'planner',
+    type:                  'validation',
+    authorisedPhases:      ['planning'],
+    allowedPipelines:      ['implement-feature'],
+    minimumToolkitVersion: '0.13.0',
+    deprecated:            false,
+    deprecationTarget:     null,
+    platforms:             ['claude'],
+  },
   {
     agentId:               'gaia.agent.planner.define-feature',
     nativeNames:           { claude: 'gaia-define-feature' },

package/lib/workflow-control.js

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

package/package.json

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

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

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

package/src/claude/agents/gaia-validate-feature-docs.md

@@ -16,11 +16,15 @@ A QA agent that cross-references `feature.md` against the Requirements and Tech-
 1. Extract the prefix from the folder name (`FTR-001-user-management` → `FTR-001`)
 2. Read `feature.md` fully — its path is given to you first; use your Read tool.
 3. The Requirements and Tech-Spec document text is included directly below, inlined into this
-   prompt under `Requirements:` and `Tech-Spec:` labels — do NOT attempt to locate or Read
-   `{PREFIX}-Requirements.md`/`{PREFIX}-Tech-Spec.md` on disk; they are not guaranteed to exist
-   (both documents are generated and stored in a split, per-item format by default — `req/`,
-   `spec/` — and only assembled into a single file when a user explicitly requests it). Use the
-   inlined text as the complete, authoritative content of each document for this validation pass.
+   prompt under `Requirements:` and `Tech-Spec:` labels. The Requirements text is the FULL document
+   (every Use Case's own flow detail included). The Tech-Spec text is its SKELETON ONLY — Section
+   9's own component index table (Purpose, Addresses, Domain, Spec-link columns, one row per
+   component) plus every feature-wide section (Overview, Architecture, Security, Database,
+   Configuration, Implementation Order, Risks). It deliberately does NOT include any component's
+   own Change/Algorithm/Schema/Tests design prose — that per-component detail is validated
+   separately, on request, via `needsComponentDetail` (Phase 3). Do NOT attempt to locate or Read
+   `{PREFIX}-Requirements.md`/`{PREFIX}-Tech-Spec.md` or any `spec/components/*` file on disk;
+   use the inlined skeleton as the complete Tech-Spec-level input for this pass.
 4. If either inlined document's text is empty or missing, record a finding identifying it, skip
    checks that require it, and complete Phases 6 and 7 with `valid: false`. Never claim full
    coverage when an input could not be read.
@@ -60,16 +64,26 @@ For each claim extracted in Phase 2, check whether it is addressed in the target
 | Every out-of-scope item → Out of Scope section | Listed |
 | Every functional behaviour → at least one Acceptance Criterion | AC in Given/When/Then format |
 
-### Tech-Spec coverage (against the inlined Tech-Spec text)
+### Tech-Spec coverage (against the inlined Tech-Spec SKELETON — Section 9's component table and
+feature-wide sections only; no per-component design body is available in this pass)
 
 | Check | Pass condition |
 |-------|---------------|
-| Every API endpoint in feature.md → endpoint spec in Tech-Spec | Method, path, request/response documented |
-| Every data model field → entity definition in Tech-Spec | Model/class definition present |
-| Every new service/component → listed in File Inventory | New files section |
-| Every modified file → listed in File Inventory | Modified files section |
-| Every Use Case ID from Requirements → referenced in Implementation Order | Traceability present |
-| Every external integration → documented in External Integrations | Integration section present |
+| Every new/modified service/component in feature.md → listed in File Inventory | Row present with matching Purpose/Domain |
+| Every external integration → documented in External Integrations (Section 5's own feature-wide prose, if any) | Mentioned explicitly |
+| A claim needs exact technical detail not visible in Purpose/Addresses/Domain (e.g. an endpoint's precise method/path/response shape, a schema field, an error code) | Do NOT guess and do NOT mark it a gap outright. Emit a `needsComponentDetail` entry instead (see below) — never silently drop the check |
+
+AC↔component traceability (every Use Case/AC referenced by the right component, and vice versa) is
+NOT this agent's responsibility — it is checked deterministically, by exact ID, by the host after
+this call returns. Do not attempt it here; a prose-based traceability finding in this pass would
+only duplicate or conflict with that exact-ID check.
+
+**When to use `needsComponentDetail` vs a normal finding:** if feature.md describes something a
+component row's Purpose plausibly relates to, but you cannot confirm the EXACT technical detail
+without reading that component's own design body, emit a `needsComponentDetail` entry naming that
+row's own Spec-link `fileSlug` and the specific claim — do not guess, and do not silently treat it
+as either covered or missing. If NO component row is even plausibly related to the claim at all,
+that is a normal missing-coverage finding, not a drill-down case.
 
 ---
 
@@ -154,18 +168,34 @@ Compose `{PREFIX}-Validation-Report.md`'s full content following this template:
 Return a single JSON object with exactly these fields, without Markdown fences or explanatory prose:
 
 ```json
-{"valid": true, "findings": [], "report": "# Validation Report — FTR-001\n\n## Summary\n..."}
+{"valid": true, "findings": [], "report": "# Validation Report — FTR-001\n\n## Summary\n...", "needsComponentDetail": []}
 ```
 
 For remaining gaps:
 
 ```json
-{"valid": false, "findings": ["Requirements: UC-01 lacks an acceptance criterion", "Tech-Spec: POST /api/users lacks a response definition"], "report": "# Validation Report — FTR-001\n\n## Summary\n..."}
+{"valid": false, "findings": ["Requirements: UC-01 lacks an acceptance criterion", "Tech-Spec: POST /api/users lacks a response definition"], "report": "# Validation Report — FTR-001\n\n## Summary\n...", "needsComponentDetail": []}
+```
+
+For a claim needing component-body detail:
+
+```json
+{"valid": false, "findings": [], "report": "# Validation Report — FTR-001\n\n## Summary\n...", "needsComponentDetail": [{"claim": "endpoint returns 401 on expired token", "fileSlug": "AuthMiddleware.cs.md"}]}
 ```
 
 - `valid` is a boolean: `true` only when all required inputs were read, coverage is complete, and no unresolved gaps remain.
 - `findings` is an array of strings, empty only for a clean validation. Missing inputs and ambiguous claims are unresolved findings.
 - `report` is a non-empty string: the complete Phase 6 document content, verbatim, as the host will write it byte-for-byte to `{PREFIX}-Validation-Report.md`.
+- `needsComponentDetail` is an array of `{ claim, fileSlug }` objects — one per claim you could not
+  confirm from the Tech-Spec skeleton alone, naming the specific component (by its Spec-link
+  `fileSlug`) whose Purpose/Domain plausibly covers it. Empty when every claim was resolvable from
+  the skeleton (the common case for small/medium features). An entry here is NOT the same as a
+  `findings` entry — do not also add a `findings` string for the same claim; the host resolves
+  `needsComponentDetail` entries separately and may add its own finding if the drill-down fails.
+- A `valid: false` result caused only by `needsComponentDetail` entries (no other findings) is
+  still `valid: false` with an empty `findings` array — this is expected, not a contradiction: the
+  host treats pending component-detail checks as unresolved until its own drill-down pass clears
+  them.
 - The caller supplies `--json-schema`; use the runtime's structured-output mechanism to return this object in `structured_output`. Plain-text JSON alone does not satisfy that contract.
 - There is only one deliverable now: the structured verdict, with `report` inside it. There is no separate Write step.
 
@@ -182,4 +212,4 @@ If a claim is contradictory or its correct resolution is ambiguous, do not guess
 - **Be specific about gaps** — point to the exact section, claim, and what is missing
 - **Perform one validation pass per invocation** — return remaining gaps to the host
 - **Out-of-scope items are also validated** — ensure they are not accidentally included in outputs
-- **Traceability is mandatory** — every Use Case ID in Requirements must appear in Tech-Spec
+- **AC↔component traceability is NOT your job** — the host checks it deterministically, by exact ID, after this call returns (see Phase 3)

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

@@ -0,0 +1,54 @@
+---
+name: gaia-validate-tech-spec-component-detail
+description: "Verifies a small batch of claims against the specific component design files named by the host. Input: a list of {claim, component file path} pairs"
+model: haiku
+tools: Read, Glob, Grep
+---
+
+# Validate Tech-Spec Component Detail
+
+A narrow QA agent: for each claim in this batch, Read ONLY the one named component file and decide
+whether its own content satisfies that claim. Do not Read, Glob, or Grep for `feature.md`,
+`req/index.md`, `spec/index.md`, or any component file NOT explicitly named in this prompt — every
+file you need is already named below; searching for anything else is out of scope for this agent
+and wastes the narrow batch this call was sized for.
+
+## Phase 1 — Load This Batch
+
+The host supplies, in the dispatch prompt, one entry per line:
+`Claim: {claim text}` followed by `Component file: {absolute path}`.
+Multiple claims may name the SAME component file — Read each distinct file only once, then check
+every claim assigned to it against that one reading.
+
+## Phase 2 — Verify Each Claim
+
+For each claim, Read its named file (if not already read for an earlier claim in this batch) and
+decide: does this file's own actual content (its Change/Algorithm/Schema/Tests sections, or
+whichever of those the file actually has) satisfy the claim? Be specific and literal — a claim
+about an exact endpoint method/path, a schema field, or an error code is satisfied only if that
+exact detail is actually present in the file, not merely plausible given the file's general topic.
+
+## Phase 3 — Structured Completion (MANDATORY — your final response)
+
+Return a single JSON object with exactly one field:
+
+```json
+{"findings": ["Tech-Spec: components/AuthMiddleware.cs.md does not document a 401 response for an expired token, as feature.md requires"]}
+```
+
+- `findings` is an array of strings, one per claim that is NOT satisfied by its named file's
+  content. A satisfied claim produces NO entry — do not report successes.
+- Every finding string is prefixed `"Tech-Spec: "`, matching the same convention
+  `gaia-validate-feature-docs`'s own `findings` array and the host's deterministic
+  AC↔component check already use, so the host can merge every source into one array with no
+  format-specific handling for this agent's own output.
+- An empty array (`{"findings": []}`) means every claim in this batch was confirmed.
+- The caller supplies `--json-schema`; use the runtime's structured-output mechanism to return this
+  object in `structured_output`.
+
+## Guidelines
+
+- **Read only the named files** — never search for or infer any other document.
+- **One call, one batch** — do not ask the host for more context; if a named file's content is
+  genuinely ambiguous about a claim, report it as NOT satisfied (fail closed) rather than guessing.
+- **Be literal, not generous** — "plausibly related" is not the same as "actually documented".

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

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

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

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

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

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

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

@@ -35,6 +35,10 @@ return c.run(meta.name, featureDir, prefix, async () => {
   const specComponentId = 'gaia.agent.planner.tech-spec-component'
   const valId = 'gaia.agent.planner.validate-feature-docs'
   const output = (suffix, inputs = [featurePath]) => ({ path: file(suffix), inputs })
+  // FTR-029/UC-04: bounded immediate retry, fixed constants (not externally configurable) for the
+  // per-UC and per-component generation loops' own fail-fast validity check.
+  const USE_CASE_RETRY_ATTEMPTS = 2
+  const COMPONENT_RETRY_ATTEMPTS = 2
 
   // Templates live under the toolkit's own installed scripts/templates/ — outside this project
   // for a globally-installed toolkit, which a non-interactive `--print` worker invocation has no
@@ -196,8 +200,15 @@ return c.run(meta.name, featureDir, prefix, async () => {
       // an existing use-case file would have been written against the OLD skeleton's row
       // (title/actor/priority may have changed) and cannot be trusted as-is.
       if (!regenSkeleton && c.exists(ucPath) && isValidUseCaseFile(c.read(ucPath), row.id)) continue // resume: skip, no dispatch
-      const detail = await c.worker(reqUcId, buildUcPrompt(row, ucTable, featurePath, ucTemplate),
-        { label: `requirements-use-case:${row.id}` })
+      // FTR-029/UC-04: validate immediately, before writing to disk and before moving to the next
+      // use case — same reasoning as the per-component loop above.
+      let detail, valid = false
+      for (let attempt = 1; attempt <= USE_CASE_RETRY_ATTEMPTS && !valid; attempt++) {
+        detail = await c.worker(reqUcId, buildUcPrompt(row, ucTable, featurePath, ucTemplate),
+          { label: `requirements-use-case:${row.id}:${attempt}` })
+        valid = isValidUseCaseFile(detail, row.id)
+      }
+      if (!valid) throw new Error(`Requirements use case "${row.id}" failed structural validation after ${USE_CASE_RETRY_ATTEMPTS} attempts — missing the required "### ${row.id}: " heading`)
       c.writeOutput(ucPath, detail.trimEnd() + ucCrossReferences(c.read(reqIndexPath), row.id))
     }
     // No assembly/write step here — generation only ever produces req/index.md + its per-UC
@@ -281,6 +292,67 @@ return c.run(meta.name, featureDir, prefix, async () => {
     return changeIdx !== -1 && testsIdx !== -1
   }
 
+  // FTR-028/UC-02: purely deterministic, zero-LLM-cost AC<->component traceability check. Reuses
+  // the two table parsers already duplicated in this file — no new parsing contract invented.
+  // Both directions produce a "Tech-Spec: " finding (always closed by a Tech-Spec revision —
+  // either add missing coverage, or fix a bad AC-ID reference).
+  function computeAcComponentTraceabilityGaps(reqIndexContent, specIndexContent) {
+    const acIds = new Set(parseAcTableRelatedUc(reqIndexContent).map(r => r.id))
+    const components = parseComponentsTable(specIndexContent)
+    const addressedAcIds = new Set()
+    const findings = []
+    for (const comp of components) {
+      const refs = (comp.addresses || '').split(',').map(s => s.trim()).filter(s => s && s !== '—')
+      for (const ref of refs) {
+        addressedAcIds.add(ref)
+        if (!acIds.has(ref)) findings.push(`Tech-Spec: component ${comp.filePath} references nonexistent ${ref}`)
+      }
+    }
+    for (const id of acIds) {
+      if (!addressedAcIds.has(id)) findings.push(`Tech-Spec: ${id} is not addressed by any Tech-Spec component`)
+    }
+    return findings
+  }
+
+  // FTR-028/UC-03: validates each needsComponentDetail entry's fileSlug against the real
+  // component table (a hallucinated/mistyped reference is dropped and reported, never
+  // dispatched), deduplicates by fileSlug (two claims against the same file collapse into one
+  // batch slot), and splits the remaining unique components into groups of at most
+  // DRILL_DOWN_BATCH_SIZE — never one call per claim, never one call covering every flagged
+  // component regardless of count.
+  const DRILL_DOWN_BATCH_SIZE = 8 // fixed constant, not externally configurable
+  function prepareDrillDownBatches(needsComponentDetail, specIndexContent) {
+    const validSlugs = new Set(parseComponentsTable(specIndexContent).map(c => c.fileSlug))
+    const extraFindings = []
+    const claimsByFileSlug = new Map()
+    for (const entry of needsComponentDetail || []) {
+      if (!validSlugs.has(entry.fileSlug)) {
+        extraFindings.push(`Tech-Spec: component-detail check referenced a non-existent file "${entry.fileSlug}" for claim "${entry.claim}"`)
+        continue
+      }
+      if (!claimsByFileSlug.has(entry.fileSlug)) claimsByFileSlug.set(entry.fileSlug, [])
+      claimsByFileSlug.get(entry.fileSlug).push(entry.claim)
+    }
+    const fileSlugs = [...claimsByFileSlug.keys()]
+    const batches = []
+    for (let i = 0; i < fileSlugs.length; i += DRILL_DOWN_BATCH_SIZE) {
+      batches.push(fileSlugs.slice(i, i + DRILL_DOWN_BATCH_SIZE)
+        .map(slug => ({ fileSlug: slug, claims: claimsByFileSlug.get(slug) })))
+    }
+    return { batches, extraFindings }
+  }
+
+  // specDir is already absolute (derived from c.feature()'s realpath-resolved featureDir), so
+  // this needs no extra path.resolve — same reasoning that already lets featurePath be handed to
+  // agents directly elsewhere in this file.
+  function buildDrillDownPrompt(batch) {
+    return batch.map(({ fileSlug, claims }) =>
+      claims.map(claim => `Claim: ${claim}\nComponent file: ${specDir}/components/${fileSlug}`).join('\n\n')
+    ).join('\n\n')
+  }
+
+  const drillDownId = 'gaia.agent.planner.validate-tech-spec-component-detail'
+
   function buildComponentPrompt(row, components, featurePathArg, componentTemplate) {
     const compactIndex = components.map(c => `${c.filePath} (${c.domain})`).join('\n')
     const base = `${featurePathArg}\n\nGenerate the full technical design for this component:\n` +
@@ -378,8 +450,16 @@ return c.run(meta.name, featureDir, prefix, async () => {
     for (const comp of components) {
       const compPath = `${specDir}/components/${comp.fileSlug}`
       if (!regenSkeleton && c.exists(compPath) && isValidComponentDetail(c.read(compPath))) continue // resume: skip, no dispatch
-      const detail = await c.worker(specComponentId, buildComponentPrompt(comp, components, featurePath, componentTemplate),
-        { label: `tech-spec-component:${comp.fileSlug}` })
+      // FTR-029/UC-04: validate immediately, before writing to disk and before moving to the next
+      // component — a bad result otherwise silently continued through every remaining component,
+      // only discovered (expensively) at final assembly or a later invocation's resume check.
+      let detail, valid = false
+      for (let attempt = 1; attempt <= COMPONENT_RETRY_ATTEMPTS && !valid; attempt++) {
+        detail = await c.worker(specComponentId, buildComponentPrompt(comp, components, featurePath, componentTemplate),
+          { label: `tech-spec-component:${comp.fileSlug}:${attempt}` })
+        valid = isValidComponentDetail(detail)
+      }
+      if (!valid) throw new Error(`Tech-Spec component "${comp.filePath}" (${comp.fileSlug}) failed structural validation after ${COMPONENT_RETRY_ATTEMPTS} attempts — missing a real "## Change"/"## Tests" heading`)
       c.writeOutput(compPath, detail)
     }
     // No assembly/write step here — generation only ever produces spec/index.md + its
@@ -445,26 +525,86 @@ return c.run(meta.name, featureDir, prefix, async () => {
       // finding mentioning both document names, or neither, would mis-route or
       // silently skip). The validator agent itself decides which document(s) its
       // own findings implicate.
+      // FTR-028/UC-01: Tech-Spec text is the raw skeleton (c.read(specIndexPath)), never
+      // assembledTechSpec's fully-spliced output — bounds this prompt's size to component COUNT,
+      // not per-component prose length. Requirements stays assembledRequirements (full UC
+      // detail), unchanged — no real incident has shown UC count x flow length to pose the same
+      // risk.
       const result = await c.worker(valId,
-        `${featurePath}\n\nRequirements:\n${assembledRequirements}\n\nTech-Spec:\n${assembledTechSpec}\n\n` +
-        'Validate only; the host owns the revision loop. Return valid, a findings array (one string per remaining gap), needsRequirementsFix/needsTechSpecFix (true only if at least one finding implicates that document), and the full validation report content. Do not dispatch other agents.',
-        { label: `validation:${cycle}`, outputs: [output('Validation-Report', [featurePath, reqIndexPath, specIndexPath])], schema: { type: 'object', properties: { valid: { type: 'boolean' }, findings: { type: 'array', items: { type: 'string' } }, needsRequirementsFix: { type: 'boolean' }, needsTechSpecFix: { type: 'boolean' }, report: { type: 'string' } }, required: ['valid', 'findings', 'needsRequirementsFix', 'needsTechSpecFix', 'report'] } })
-      // A model returning valid:true alongside non-empty findings (or valid:false
-      // with none) contradicts its own schema's intent — never silently treated as
-      // "not clean yet" and spent on another cycle without surfacing the
-      // inconsistency; fail closed instead of masking a confused response.
-      if (result.valid === (result.findings.length > 0)) {
-        throw new Error(`Validation agent returned a contradictory result on cycle ${cycle}: valid=${result.valid} with ${result.findings.length} finding(s)`)
+        `${featurePath}\n\nRequirements:\n${assembledRequirements}\n\nTech-Spec:\n${c.read(specIndexPath)}\n\n` +
+        'Validate only; the host owns the revision loop. Return valid, a findings array (one string per remaining gap), needsRequirementsFix/needsTechSpecFix (true only if at least one finding implicates that document), needsComponentDetail (claims needing a component\'s own design body to verify — see your own instructions for when to use this instead of a finding), and the full validation report content. Do not dispatch other agents.',
+        { label: `validation:${cycle}`, outputs: [output('Validation-Report', [featurePath, reqIndexPath, specIndexPath])], schema: { type: 'object', properties: { valid: { type: 'boolean' }, findings: { type: 'array', items: { type: 'string' } }, needsRequirementsFix: { type: 'boolean' }, needsTechSpecFix: { type: 'boolean' }, report: { type: 'string' }, needsComponentDetail: { type: 'array', items: { type: 'object', properties: { claim: { type: 'string' }, fileSlug: { type: 'string' } }, required: ['claim', 'fileSlug'] } } }, required: ['valid', 'findings', 'report'] } })
+        // FTR-029: needsRequirementsFix/needsTechSpecFix stay declared in `properties` (still
+        // type-checked when present) but are no longer hard-required — confirmed against three
+        // real evidence files that the model reasonably omits both when there is nothing to fix;
+        // the host's own merge logic already treats an absent value as falsy
+        // (mergedNeedsRequirementsFix/mergedNeedsTechSpecFix below), so no further change needed.
+        // needsComponentDetail is declared in `properties` but deliberately NOT in the schema's
+        // top-level `required` array: every pre-existing mocked test response for this agent
+        // (predating this feature) omits the field entirely, and making it hard-required would
+        // break every one of them for no real gain — prepareDrillDownBatches already treats an
+        // absent/undefined value as "no entries" via `needsComponentDetail || []`.
+
+      // Raw self-consistency guard on the MODEL'S OWN response, before any host-side merge: a
+      // pending needsComponentDetail entry is itself a form of "not yet resolved", same as a
+      // non-empty findings array — valid:true requires BOTH to be empty, valid:false requires at
+      // least one to be non-empty. This is intentionally separate from mergedValid below (which
+      // is NOT required to track this raw self-report: a valid:false caused only by
+      // needsComponentDetail entries that the drill-down subsequently confirms must still resolve
+      // to a clean cycle, not a false "contradiction").
+      const rawHasOpenItems = result.findings.length > 0 || (result.needsComponentDetail || []).length > 0
+      if (result.valid === rawHasOpenItems) {
+        throw new Error(`Validation agent returned a contradictory result on cycle ${cycle}: valid=${result.valid} with ${result.findings.length} finding(s) and ${(result.needsComponentDetail || []).length} needsComponentDetail entry(ies)`)
+      }
+
+      // FTR-028/UC-02 + UC-03: every finding source for this cycle, computed/dispatched AFTER the
+      // main call returns (re-reading the index files fresh, since a prior cycle may have
+      // regenerated them). Zero added LLM cost when both come back empty (the common case).
+      const reqIndexContent = c.read(reqIndexPath)
+      const specIndexContent = c.read(specIndexPath)
+      const structuralFindings = computeAcComponentTraceabilityGaps(reqIndexContent, specIndexContent)
+      const { batches, extraFindings } = prepareDrillDownBatches(result.needsComponentDetail, specIndexContent)
+
+      const drillDownFindings = []
+      for (let b = 0; b < batches.length; b++) {
+        const batchResult = await c.worker(drillDownId, buildDrillDownPrompt(batches[b]),
+          { label: `validation:${cycle}:component-detail:${b + 1}`,
+            schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } })
+        drillDownFindings.push(...batchResult.findings)
+      }
+
+      // BR-04: merge everything BEFORE the contradiction guard. A model returning valid:true
+      // while the host's own independent checks found a real gap is not a self-contradiction (it
+      // was never shown that gap) — it is simply now-invalid, same as any other unresolved
+      // finding.
+      const newFindings = [...structuralFindings, ...extraFindings, ...drillDownFindings]
+      const mergedFindings = [...result.findings, ...newFindings]
+      // Deliberately NOT `result.valid && ...`: result.valid may be false SOLELY because of
+      // needsComponentDetail entries that the drill-down above has now fully confirmed (zero
+      // drillDownFindings) — that must resolve to clean, not stay stuck on the model's own
+      // now-stale self-report. The only authoritative signal for the final verdict is whether any
+      // finding remains, from any source, after every check this cycle has run.
+      const mergedValid = mergedFindings.length === 0
+      const mergedNeedsTechSpecFix = result.needsTechSpecFix || newFindings.some(f => f.startsWith('Tech-Spec:'))
+      const mergedNeedsRequirementsFix = result.needsRequirementsFix || newFindings.some(f => f.startsWith('Requirements:'))
+
+      // c.worker() already wrote result.report verbatim via its own outputs[0] contract; only
+      // overwrite it when this cycle actually added findings the LLM's own report text doesn't
+      // mention — the common clean case (newFindings.length === 0) never re-writes the file.
+      if (newFindings.length) {
+        c.write(file('Validation-Report'), result.report +
+          '\n\n## Additional findings (deterministic + component-detail drill-down)\n' +
+          newFindings.map(f => `- ${f}`).join('\n') + '\n')
       }
-      if (result.valid) {
+      if (mergedValid) {
         if (!fresh(file('Validation-Report'), [featurePath, reqIndexPath, specIndexPath])) throw new Error('Validation agent did not produce its report')
         validationSummary = `0 gaps (clean on cycle ${cycle})`
         break
       }
       if (cycle === 3) throw new Error('Validation gaps remain after 3 cycles')
-      if (!result.needsRequirementsFix && !result.needsTechSpecFix) throw new Error(`Validation agent reported gaps on cycle ${cycle} but flagged neither document for revision`)
-      if (result.needsRequirementsFix) { await generateRequirements(true); assembledRequirements = assembleRequirements() }
-      if (result.needsTechSpecFix) { await generateTechSpec(true); assembledTechSpec = assembleTechSpec() }
+      if (!mergedNeedsRequirementsFix && !mergedNeedsTechSpecFix) throw new Error(`Validation agent reported gaps on cycle ${cycle} but flagged neither document for revision`)
+      if (mergedNeedsRequirementsFix) { await generateRequirements(true); assembledRequirements = assembleRequirements() }
+      if (mergedNeedsTechSpecFix) { await generateTechSpec(true); assembledTechSpec = assembleTechSpec() }
     }
   }
   // Binds Gate 1's eventual approval to the EXACT Requirements/Tech-Spec bytes