@dtlabs/ai-toolkit 0.24.7 → 0.24.9

package/CHANGELOG.md

@@ -1,4 +1,22 @@
 ## 0.1.4 (2026-07-21)
+## [0.24.9](https://github.com/dtlab-tech/ai-toolkit/compare/v0.24.8...v0.24.9) (2026-11-03)
+
+
+### Bug Fixes
+
+* **pm-phase1:** never overwrite a good skeleton with a non-document reply, and repair last-cycle AC traceability once ([8f2f32f](https://github.com/dtlab-tech/ai-toolkit/commit/8f2f32f1852ade4551da62cbac8bc07d8f0c2961))
+* **pm-phase1:** never overwrite a good skeleton with a non-document reply, and repair last-cycle AC traceability once ([3038efe](https://github.com/dtlab-tech/ai-toolkit/commit/3038efed641464b93da50377cd834cc1d4a85e48))
+* **pm-phase1:** never overwrite a good skeleton with a non-document reply, and repair last-cycle AC traceability once ([784f814](https://github.com/dtlab-tech/ai-toolkit/commit/784f8141fb4afdefe2b2592f9d8b57a4f41207c2))
+
+## [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)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtlabs/ai-toolkit",
-  "version": "0.24.7",
+  "version": "0.24.9",
   "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

@@ -39,6 +39,32 @@ return c.run(meta.name, featureDir, prefix, async () => {
   // per-UC and per-component generation loops' own fail-fast validity check.
   const USE_CASE_RETRY_ATTEMPTS = 2
   const COMPONENT_RETRY_ATTEMPTS = 2
+  const SKELETON_RETRY_ATTEMPTS = 2
+
+  // A skeleton worker occasionally answers with a question or an apology instead of the document
+  // ("I have not generated the skeleton yet ... I'm asking here"). The skeleton was written
+  // straight onto req/index.md or spec/index.md and only checked afterwards, so one such reply
+  // destroyed the good document that was there (FTR-034, revision cycle 2). The reply is now
+  // checked for every numbered section BEFORE the target file is touched; on a bad reply the
+  // worker is asked once more, and if that fails too the run stops with the existing file intact.
+  async function writeSkeleton(label, workerId, basePrompt, sectionCount, outPath, transform) {
+    let raw
+    for (let attempt = 1; attempt <= SKELETON_RETRY_ATTEMPTS; attempt++) {
+      const prompt = attempt === 1 ? basePrompt : basePrompt +
+        '\n\nYour previous reply was not the document. This is a non-interactive run: nobody can answer a question. ' +
+        'Reply with ONLY the complete document, every numbered section included, and with no preamble. Where feature.md ' +
+        'leaves a point undecided, record it inside the document as an open question instead of asking.'
+      raw = await c.worker(workerId, prompt, attempt === 1 ? undefined : { label: `${label}:skeleton:retry:${attempt}` })
+      if (missingSections(raw, sectionCount).length === 0) {
+        c.writeOutput(outPath, transform ? transform(raw) : raw)
+        return
+      }
+    }
+    // same message the post-write completeness check has always produced (truncation guard)
+    try { assertCompleteSections(label, raw, sectionCount) } catch (e) {
+      throw new Error(`${e.message}; after ${SKELETON_RETRY_ATTEMPTS} attempts the existing file was left untouched`)
+    }
+  }
 
   // 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
@@ -215,8 +241,9 @@ return c.run(meta.name, featureDir, prefix, async () => {
     // 1. Skeleton (no declared worker() output — host writes it itself, mirroring FTR-020's
     // skeleton step)
     if (regenSkeleton) {
-      const skeleton = await c.worker(reqId, withTemplate(featurePath, 'req/index.md', 'gaia-requirements-index-template.md') + revisionSection(revisionFindings))
-      c.writeOutput(reqIndexPath, skeleton)
+      await writeSkeleton('Requirements', reqId,
+        withTemplate(featurePath, 'req/index.md', 'gaia-requirements-index-template.md') + revisionSection(revisionFindings),
+        9, reqIndexPath)
     }
 
     // 2. Structural self-consistency pre-check (req-skeleton-check.js, same
@@ -565,8 +592,9 @@ return c.run(meta.name, featureDir, prefix, async () => {
 
     // 1. Skeleton (no declared worker() output — host writes it itself)
     if (regenSkeleton) {
-      const skeleton = await c.worker(specId, withTemplate(featurePath, 'spec/index.md', 'gaia-tech-spec-index-template.md') + revisionSection(revisionFindings))
-      c.writeOutput(specIndexPath, applyComponentSlugs(skeleton, manifest))
+      await writeSkeleton('Tech-Spec', specId,
+        withTemplate(featurePath, 'spec/index.md', 'gaia-tech-spec-index-template.md') + revisionSection(revisionFindings),
+        12, specIndexPath, skeleton => applyComponentSlugs(skeleton, manifest))
     }
 
     // 2. Structural pre-check (tech-spec-graph-checks.js, unmodified — FTR-023 — now pointed at
@@ -677,6 +705,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,
@@ -766,7 +796,32 @@ 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 if the repair
+        // below cannot close them: 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).
+        //
+        // A traceability gap found on the LAST cycle used to be unrecoverable: a Requirements
+        // revision on cycle 2 can add acceptance criteria the Tech-Spec does not yet address, and
+        // that gap is only routed to a Tech-Spec revision on the cycle after. Give it one repair:
+        // regenerate the Tech-Spec once with the gaps as feedback, then re-check mechanically.
+        let repaired = false
+        if (structuralFindings.length) {
+          revisionFindings = structuralFindings
+          await generateTechSpec(true)
+          assembledTechSpec = assembleTechSpec()
+          if (computeAcComponentTraceabilityGaps(c.read(reqIndexPath), c.read(specIndexPath)).length) throw new Error('Validation gaps remain after 3 cycles')
+          repaired = true
+          c.append(file('Validation-Report'), '\n\n## Post-validation repair\nThe AC traceability findings listed above were repaired after the last validation cycle by regenerating the Tech-Spec once. The repaired Tech-Spec was checked mechanically (every AC is addressed) but was not re-validated by the validator.\n')
+        }
+        openGaps = mergedFindings.filter(f => !structuralFindings.includes(f))
+        validationSummary = `${openGaps.length} open gap(s) after 3 cycles, left for Gate 1 review (see the Validation Report)` +
+          (repaired ? '; the Tech-Spec was regenerated once to repair AC traceability and not re-validated' : '')
+        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() }
@@ -784,7 +839,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: [],
   }