@dtlabs/ai-toolkit 0.19.2 → 0.21.0

package/CHANGELOG.md

@@ -1,4 +1,20 @@
 ## 0.1.4 (2026-07-21)
+## [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)
+
+
+### Features
+
+* **pm-phase1, pm-phase2:** resume-safe per-item generation (FTR-027) ([41e021f](https://github.com/dtlab-tech/ai-toolkit/commit/41e021f65aad694c18d51b6a7876e4a83373a4d9))
+* resume-safe per-item generation + component fileSlug normalization (FTR-027) ([e7e6b89](https://github.com/dtlab-tech/ai-toolkit/commit/e7e6b89596f267c4954c9be92bc2c4b3de8b9194))
+
 ## [0.19.2](https://github.com/dtlab-tech/ai-toolkit/compare/v0.19.1...v0.19.2) (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/package.json

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

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/workflows/pm-phase1.js

@@ -90,6 +90,16 @@ return c.run(meta.name, featureDir, prefix, async () => {
     })
   }
 
+  // FTR-027: resume-by-existence must not trust mere presence — a use-case file that exists but
+  // is garbled/off-topic (e.g. echoes a different UC) should be regenerated, not skipped forever.
+  // Only the ID fragment is checked, never the free-text title after the colon: the title is
+  // prose the agent may legitimately phrase differently across a retry, and comparing it would
+  // reject a valid regeneration for no real reason.
+  function isValidUseCaseFile(content, ucId) {
+    const escaped = ucId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    return new RegExp(`^###\\s+${escaped}:\\s`).test(content.trimStart())
+  }
+
   // Business Rules' "Applies to" / Acceptance Criteria's "Related UC" columns are the same
   // cross-cutting-reference shape: a comma-separated UC-ID list, or the literal "All UCs". Both
   // are 100% mechanically derivable from req/index.md's own tables — no LLM judgment needed,
@@ -185,7 +195,7 @@ return c.run(meta.name, featureDir, prefix, async () => {
       // If the skeleton itself was just (re)generated, every use case must regenerate too —
       // an existing use-case file would have been written against the OLD skeleton's row
       // (title/actor/priority may have changed) and cannot be trusted as-is.
-      if (!regenSkeleton && c.exists(ucPath)) continue // resume: skip, no dispatch
+      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}` })
       c.writeOutput(ucPath, detail.trimEnd() + ucCrossReferences(c.read(reqIndexPath), row.id))
@@ -241,6 +251,97 @@ return c.run(meta.name, featureDir, prefix, async () => {
     return entries
   }
 
+  // FTR-027: duplicates tech-spec-assembler.js's parseComponentDetail's own fence-aware
+  // "## Change"/"## Tests" heading scan (see that file for the full "why length-aware, not a
+  // boolean toggle" rationale) — returns a boolean instead of throwing/returning parsed sections,
+  // since every call site here only needs the yes/no "is this a structurally valid component
+  // file" signal, for resume-by-existence: a component file that exists but fails this check
+  // (e.g. a whole-response fence wrap, a truncated reply) must be regenerated, not skipped
+  // forever — found via a real incident where exactly this silently blocked every retry.
+  function _nonFencedHeadingIndexesLocal(lines, predicate) {
+    let fenceLen = 0
+    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
+        else if (runLen >= fenceLen) fenceLen = 0
+        continue
+      }
+      if (fenceLen !== 0) continue
+      if (predicate(lines[i])) indexes.push(i)
+    }
+    return indexes
+  }
+  function isValidComponentDetail(content) {
+    const lines = content.split('\n')
+    const changeIdx = _nonFencedHeadingIndexesLocal(lines, l => l.trim() === '## Change')[0] ?? -1
+    const testsIdx = _nonFencedHeadingIndexesLocal(lines, l => l.trim() === '## Tests')[0] ?? -1
+    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` +
@@ -254,6 +355,16 @@ return c.run(meta.name, featureDir, prefix, async () => {
   // FTR-020). Rewrites any colliding fileSlug's Spec-column link in place, right-to-left
   // prepending path segments until unique.
   //
+  // Also enforces the ".md" suffix itself, never trusting the model to have included it. The
+  // component template's own contract calls this Spec link "provisional, not final" specifically
+  // so the host can rewrite it — originally only exercised for collisions, but a real production
+  // run showed the model omits ".md" entirely a meaningful fraction of the time (confirmed: 20 of
+  // ~61 components in one real Tech-Spec skeleton), writing e.g. `components/Settings.tsx`
+  // instead of `components/Settings.tsx.md` — the host then faithfully wrote that component's
+  // Markdown CONTENT into a file literally named `Settings.tsx`. Normalized here before the
+  // collision check runs, so two rows that only differ by their original extension (already
+  // present in the Path column) still correctly collide-and-disambiguate on the normalized slug.
+  //
   // Operates per-LINE, not via a global string .replace() over the whole document — a real bug,
   // found by testing two colliding entries directly: when both rows share byte-identical Spec
   // text (the whole point of a collision), a global .replace() always rewrites the FIRST
@@ -270,6 +381,12 @@ return c.run(meta.name, featureDir, prefix, async () => {
       const m = cells[4].match(/\(components\/([^)]+)\)/)
       if (!m) continue // header/separator row, or a row with no valid Spec link yet
       let slug = m[1]
+      if (!slug.endsWith('.md')) {
+        const escaped = slug.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+        const normalized = `${slug}.md`
+        lines[i] = lines[i].replace(new RegExp(`components/${escaped}`, 'g'), `components/${normalized}`)
+        slug = normalized
+      }
       if (seenSlugs.has(slug)) {
         const segments = filePath.split('/')
         let depth = 1
@@ -279,7 +396,7 @@ return c.run(meta.name, featureDir, prefix, async () => {
           candidate = segments.slice(-depth).join('-') + '.md'
         }
         const escaped = slug.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-        lines[i] = line.replace(new RegExp(`components/${escaped}`, 'g'), `components/${candidate}`)
+        lines[i] = lines[i].replace(new RegExp(`components/${escaped}`, 'g'), `components/${candidate}`)
         slug = candidate
       }
       seenSlugs.add(slug)
@@ -321,7 +438,7 @@ return c.run(meta.name, featureDir, prefix, async () => {
     const componentTemplate = components.length ? readTemplate('gaia-component-template.md') : null
     for (const comp of components) {
       const compPath = `${specDir}/components/${comp.fileSlug}`
-      if (!regenSkeleton && c.exists(compPath)) continue // resume: skip, no dispatch
+      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}` })
       c.writeOutput(compPath, detail)
@@ -352,8 +469,17 @@ return c.run(meta.name, featureDir, prefix, async () => {
   // for free by gating on the assembled document's own freshness (which could never look
   // "complete" while a referenced item was missing) — removing that gate (FTR-025) removed this
   // side effect along with it, so it needs restating explicitly here.
-  const anyUcFileMissing = indexContent => parseUseCaseIndexTable(indexContent).some(row => !c.exists(`${reqDir}/${row.file}`))
-  const anyComponentFileMissing = indexContent => parseComponentsTable(indexContent).some(comp => !c.exists(`${specDir}/components/${comp.fileSlug}`))
+  // FTR-027: "missing" now also means "present but invalid" — a structurally broken-but-existing
+  // file must trigger re-entry into generation the same way an absent one already does, otherwise
+  // the outer gate alone could never notice it (only the per-item loop would, one phase later).
+  const anyUcFileMissing = indexContent => parseUseCaseIndexTable(indexContent).some(row => {
+    const ucPath = `${reqDir}/${row.file}`
+    return !c.exists(ucPath) || !isValidUseCaseFile(c.read(ucPath), row.id)
+  })
+  const anyComponentFileMissing = indexContent => parseComponentsTable(indexContent).some(comp => {
+    const compPath = `${specDir}/components/${comp.fileSlug}`
+    return !c.exists(compPath) || !isValidComponentDetail(c.read(compPath))
+  })
 
   let changed = false
   if (force || !fresh(reqIndexPath) || missingSections(c.read(reqIndexPath), 9).length ||
@@ -380,26 +506,81 @@ 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', 'needsRequirementsFix', 'needsTechSpecFix', 'report'] } })
+        // 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

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

@@ -234,6 +234,22 @@ function buildTaskTechSpecExcerpt(components, task, specDir, specIndexContent) {
   }).join('\n\n')
 }
 
+// FTR-027: duplicates wbs-assembler.js's own _parseVerificationCommands algorithm (last
+// occurrence of the marker wins — an illustrative example earlier in Implementation notes must
+// never be mistaken for the real section) — returns a boolean instead of the parsed array, since
+// resume-by-status only needs the yes/no "does this task file have at least one verification
+// command" signal, per the task template's own documented "Must be non-empty" contract. A task
+// file that exists and is marked `generated` but has none is regenerated, not skipped forever.
+const FENCE_RE_LOCAL = /```[^\n]*\n([\s\S]*?)```/g
+function hasVerificationCommands(content) {
+  const marker = '**Verification commands:**'
+  const idx = content.lastIndexOf(marker)
+  if (idx === -1) return false
+  const verifPart = content.slice(idx + marker.length)
+  FENCE_RE_LOCAL.lastIndex = 0
+  return FENCE_RE_LOCAL.test(verifPart)
+}
+
 // Compact prompt for the per-task detail-generation worker: this task's own skeleton entry,
 // the full skeleton's sibling task list (id + title + outcome only, for duplicate-
 // implementation awareness), and the Tech-Spec excerpt (FTR-026: already pre-sliced to this
@@ -351,7 +367,7 @@ return c.run(meta.name, featureDir, prefix, async () => {
     for (const taskId of phase.taskIds) {
       const task = index.tasks[taskId]
       const detailPath = `${wbsDir}/${task.detailFile}`
-      if (task.status === 'generated' && c.exists(detailPath)) continue // resume: skip, no dispatch
+      if (task.status === 'generated' && c.exists(detailPath) && hasVerificationCommands(c.read(detailPath))) continue // resume: skip, no dispatch
       const techSpecExcerpt = hasSpec
         ? buildTaskTechSpecExcerpt(components, task, specDir, c.read(specIndexPath))
         : c.read(file('Tech-Spec.md')) // legacy fallback: unchanged, full text