@dtlabs/ai-toolkit 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -1,4 +1,12 @@
 ## 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)
 
 

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.20.0",
+  "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

@@ -281,6 +281,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` +
@@ -445,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