@dtlabs/ai-toolkit 0.24.6 → 0.24.8

package/CHANGELOG.md

@@ -1,4 +1,22 @@
 ## 0.1.4 (2026-07-21)
+## [0.24.8](https://github.com/dtlab-tech/ai-toolkit/compare/v0.24.7...v0.24.8) (2026-11-02)
+
+
+### Bug Fixes
+
+* **pm-phase1:** hand gaps still open after three validation cycles to Gate 1 instead of failing the run ([a57e05a](https://github.com/dtlab-tech/ai-toolkit/commit/a57e05abf61ea3c42a36a92cd190cc3d3a57a39c))
+* **pm-phase1:** hand gaps still open after three validation cycles to Gate 1 instead of failing the run ([d759efa](https://github.com/dtlab-tech/ai-toolkit/commit/d759efa9e13d464740698d3b8e01f131e91c848a))
+* **pm-phase1:** hand gaps still open after three validation cycles to Gate 1 instead of failing the run ([976aa27](https://github.com/dtlab-tech/ai-toolkit/commit/976aa2724b8e1e2e91293d88bc0581a5fef01f01))
+
+## [0.24.7](https://github.com/dtlab-tech/ai-toolkit/compare/v0.24.6...v0.24.7) (2026-10-30)
+
+
+### Bug Fixes
+
+* **pm-phase1:** route validator findings to a document by their prefix when the flags are omitted ([7bd9a38](https://github.com/dtlab-tech/ai-toolkit/commit/7bd9a38de571c07d233a5212dfba9213a1b7d562))
+* **pm-phase1:** route validator findings to a document by their prefix when the flags are omitted ([f957d72](https://github.com/dtlab-tech/ai-toolkit/commit/f957d726294d2b563e67ba1c3f4e59f9c8d57be4))
+* **pm-phase1:** route validator findings to a document by their prefix when the flags are omitted ([e33faef](https://github.com/dtlab-tech/ai-toolkit/commit/e33faefc4488f256e42ec459cefa547f7b5efbf2))
+
 ## [0.24.6](https://github.com/dtlab-tech/ai-toolkit/compare/v0.24.5...v0.24.6) (2026-10-29)
 
 

package/package.json

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

package/src/claude/skills/implement-feature/SKILL.md

@@ -71,6 +71,9 @@ Extract from the result:
 - `tech_spec.path` / `tech_spec.summary` — Tech-Spec artifact path (the split `spec/index.md` by
   default) and its summary
 - `validation.summary` — validation result (gaps or clean)
+- `validation.open_gaps` — array of the validator's findings still open after the last revision
+  cycle; empty when validation was clean. Non-empty means the workflow stopped revising and left
+  these for the Gate 1 reviewer to accept, reject or send back
 - `docs_digest` — content digest binding this approval to the exact Requirements/Tech-Spec
   bytes just produced; embed verbatim into `{PREFIX}-Approvals.md` in Step 2 below
 - `token_ledger` — array of per-agent token data from phase 1
@@ -92,6 +95,11 @@ Documents generated for {PREFIX}:
   {tech_spec.path}    — {tech_spec.summary}
   {PREFIX}-Validation-Report.md — {validation.summary}
 
+If `validation.open_gaps` is non-empty, also list every entry verbatim under a heading
+"Open validation gaps — your decision at this gate", then continue. These are design points the
+validator could not close in three cycles. "Approve with notes" records the ones you accept in
+`{PREFIX}-Approvals.md`; "Request changes" sends them back.
+
 To view a single combined document instead of the split source files, run:
   /assemble-docs {PREFIX} [req|spec|all]
 ```

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

@@ -677,6 +677,8 @@ return c.run(meta.name, featureDir, prefix, async () => {
   let assembledRequirements = assembleRequirements()
   let assembledTechSpec = assembleTechSpec()
   let validationSummary = 'skipped (fresh)'
+  // Gaps still open after the last revision cycle, handed to Gate 1 for a human decision.
+  let openGaps = []
   if (force || changed || !fresh(file('Validation-Report'), [featurePath, reqIndexPath, specIndexPath])) {
     for (let cycle = 1; cycle <= 3; cycle++) {
       // needsRequirementsFix/needsTechSpecFix: explicit structured routing fields,
@@ -744,8 +746,14 @@ return c.run(meta.name, featureDir, prefix, async () => {
       // 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:'))
+      // Routing reads the prefix of EVERY finding, the validator's own included: the validator is
+      // required to prefix each finding with the document it concerns (gaia-validate-feature-docs,
+      // output contract), and its own example verdict omits needsRequirementsFix/needsTechSpecFix
+      // altogether. Reading the prefix only on host-computed findings made a verdict with prefixed
+      // findings and no flags fail with "flagged neither document" (seen on FTR-034). A finding
+      // with no prefix and no flag still fails closed below.
+      const mergedNeedsTechSpecFix = result.needsTechSpecFix || mergedFindings.some(f => f.startsWith('Tech-Spec:'))
+      const mergedNeedsRequirementsFix = result.needsRequirementsFix || mergedFindings.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
@@ -760,7 +768,17 @@ return c.run(meta.name, featureDir, prefix, async () => {
         validationSummary = `0 gaps (clean on cycle ${cycle})`
         break
       }
-      if (cycle === 3) throw new Error('Validation gaps remain after 3 cycles')
+      if (cycle === 3) {
+        // The deterministic AC<->component traceability gaps stay a hard failure: they are
+        // mechanical and the Work Breakdown relies on that mapping. What the validator judges
+        // (open design points, drill-down findings) is for a person to accept or reject, and Gate
+        // 1 is that review: regenerating again cannot decide a point feature.md leaves undecided
+        // (on FTR-034 three full runs of three cycles each never converged for that reason).
+        if (structuralFindings.length) throw new Error('Validation gaps remain after 3 cycles')
+        openGaps = mergedFindings
+        validationSummary = `${openGaps.length} open gap(s) after 3 cycles, left for Gate 1 review (see the Validation Report)`
+        break
+      }
       if (!mergedNeedsRequirementsFix && !mergedNeedsTechSpecFix) throw new Error(`Validation agent reported gaps on cycle ${cycle} but flagged neither document for revision`)
       revisionFindings = mergedFindings
       if (mergedNeedsRequirementsFix) { await generateRequirements(true); assembledRequirements = assembleRequirements() }
@@ -778,7 +796,7 @@ return c.run(meta.name, featureDir, prefix, async () => {
     prefix, feature_dir: featureDir, feature_path: featurePath,
     requirements: { path: reqIndexPath, summary: 'Requirements ready (split; req/index.md + req/use-cases/*.md)' },
     tech_spec: { path: specIndexPath, summary: 'Tech-Spec ready (split; spec/index.md + spec/components/*.md)' },
-    validation: { path: file('Validation-Report'), summary: validationSummary },
+    validation: { path: file('Validation-Report'), summary: validationSummary, open_gaps: openGaps },
     docs_digest: docsDigest,
     token_ledger: c.tokenLedger, errors: [],
   }