@dtlabs/ai-toolkit 0.24.4 → 0.24.6

package/CHANGELOG.md

@@ -1,4 +1,21 @@
 ## 0.1.4 (2026-07-21)
+## [0.24.6](https://github.com/dtlab-tech/ai-toolkit/compare/v0.24.5...v0.24.6) (2026-10-29)
+
+
+### Bug Fixes
+
+* **pm-phase1:** feed validation findings back to the generators and d… ([6fcb46d](https://github.com/dtlab-tech/ai-toolkit/commit/6fcb46d4e0d6d1d9ad8e2bf97313ce23691ce665))
+* **pm-phase1:** feed validation findings back to the generators and drop duplicate Related blocks ([86d01df](https://github.com/dtlab-tech/ai-toolkit/commit/86d01dffbaccd9f5b99e3a356cd13e5d902d699b))
+* **pm-phase1:** feed validation findings back to the generators and drop duplicate Related blocks ([9411ea5](https://github.com/dtlab-tech/ai-toolkit/commit/9411ea529d8eccdc54abcd4f8f296542b73e14b9))
+
+## [0.24.5](https://github.com/dtlab-tech/ai-toolkit/compare/v0.24.4...v0.24.5) (2026-10-27)
+
+
+### Bug Fixes
+
+* **pm-phase2:** run the semantic WB validator per phase ([3f279e6](https://github.com/dtlab-tech/ai-toolkit/commit/3f279e6e386eee6c86cea90caec7e5d64b6aa756))
+* **pm-phase2:** run the semantic WB validator per phase, not once over the whole breakdown ([62389cb](https://github.com/dtlab-tech/ai-toolkit/commit/62389cbb8fcf70f4019ee83ed9f8a5a99a96dd23))
+
 ## [0.24.4](https://github.com/dtlab-tech/ai-toolkit/compare/v0.24.3...v0.24.4) (2026-10-27)
 
 

package/package.json

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

package/src/claude/agents/gaia-validate-work-breakdown-semantic.md

@@ -1,8 +1,8 @@
 ---
 name: gaia-validate-work-breakdown-semantic
-description: "Semantic validator for Work Breakdown JSON — analyzes task coherence, scope alignment, and estimate realism. Runs after wb-validate.js exits 0. Input: path to {PREFIX}-Work-Breakdown.json"
+description: "Semantic validator for one phase of a Work Breakdown — analyzes task coherence, scope alignment, and estimate realism. Runs once per phase after wb-validate.js exits 0. Input: the phase's inlined task details, a scoped Requirements excerpt, and an index of other tasks"
 model: sonnet
-tools: Read, Glob, Grep
+tools: Read
 ---
 
 # Validate Work Breakdown — Semantic
@@ -15,17 +15,16 @@ You do NOT repeat structural checks (schema conformance, required fields, ID for
 
 ## Input
 
-The prompt gives you two paths, one per line, in this order:
+Your prompt directly inlines everything you need — you review ONE phase per call:
 
-1. The Work Breakdown directory (the split format, FTR-020) — contains `index.json` (the
-   validated skeleton, schema v2) plus `user-stories/*.md`/`tasks/*.md` detail files. Use Glob/Read
-   to explore it as needed; do not expect a single `{PREFIX}-Work-Breakdown.json` file.
-2. The Requirements source — `req/index.md` for a feature using the split Requirements format
-   (FTR-021; User Story descriptions and Acceptance Criteria text live in its own tables there,
-   unaffected by the per-UC split), or a legacy `{PREFIX}-Requirements.md` file otherwise. Read
-   whichever path is actually given — do not assume either shape.
+1. **Requirements source path** and a **scoped Requirements excerpt** — feature-wide sections in full, plus only the use case(s) this phase realizes.
+2. **The phase under review** — its id, type, title, and `sourceUC`.
+3. **Task details for THIS phase only** — the full detail file of every task in the phase. These are what you review.
+4. **Other tasks in the feature** — a one-line index (id — title — outcome) of every task outside this phase. Use it only to recognize a duplicate of work another phase already owns; do not review those tasks.
 
-Derive the prefix from the Work Breakdown directory's own `index.json`'s `feature` field.
+Do **not** read any file yourself. Do **not** explore the filesystem. Everything you need is in your prompt, and another call reviews every other phase.
+
+Because each call sees only one phase, cross-phase concerns are out of scope for you. Judge the tasks in front of you.
 
 ---
 
@@ -98,4 +97,4 @@ Or when issues are found:
 
 ## Tool use
 
-Use `Read` to load both files. Do not write any files. Do not produce any output other than the single JSON object described above.
+None needed — everything is inlined. Do not write any files. Do not produce any output other than the single JSON object described above.

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

@@ -55,6 +55,28 @@ return c.run(meta.name, featureDir, prefix, async () => {
     return `${prompt}\n\nTemplate (${label}):\n${readTemplate(templateFile)}`
   }
 
+  // Gaps the validator reported on the previous cycle, set only by the revision branch below
+  // before it regenerates. Without this a "revision" was a blind full regeneration from
+  // feature.md alone: the generators never saw what was wrong, so three cycles were three
+  // independent attempts at the same input and convergence depended on luck.
+  let revisionFindings = []
+  function revisionSection(findings) {
+    if (!findings.length) return ''
+    return '\n\nThe previous version of these documents was validated and these gaps were reported. ' +
+      'Resolve every one that concerns the document you are generating, and do not raise a new open ' +
+      'question for anything feature.md already decides:\n' + findings.map(f => `- ${f}`).join('\n')
+  }
+
+  // The use-case agent is told not to write the "Related Business Rules"/"Related Acceptance
+  // Criteria" lines (the host computes them from req/index.md and appends them), but it
+  // sometimes writes its own anyway — with guessed IDs and "—" for the ACs it cannot see. Appending
+  // the host's block after it left two conflicting blocks in the file. Drop anything the model
+  // wrote from its first such line onward, so exactly one host-computed block remains.
+  function stripModelCrossReferences(detail) {
+    const idx = detail.search(/^\*\*Related (?:Business Rules|Acceptance Criteria):\*\*/m)
+    return idx === -1 ? detail : detail.slice(0, idx)
+  }
+
   // Deliberately NOT file('req') — same reasoning as FTR-020's wbsDir: this is a directory
   // nested inside the feature's own already-prefixed folder, so a second prefix would be
   // redundant.
@@ -162,7 +184,7 @@ return c.run(meta.name, featureDir, prefix, async () => {
     const base = `${featurePathArg}\n\nGenerate the full detail for this use case:\n` +
       `UC ID: ${row.id}\nTitle: ${row.title}\nActor: ${row.actor}\nPriority: ${row.priority}\n\n` +
       `Full use-case index (for cross-UC awareness, do not restate):\n${compactIndex}`
-    return `${base}\n\nTemplate (req/use-cases/{UC-ID}.md):\n${ucTemplate}`
+    return `${base}\n\nTemplate (req/use-cases/{UC-ID}.md):\n${ucTemplate}${revisionSection(revisionFindings)}`
   }
 
   // forceAll: bypasses resume-by-existence entirely, re-dispatching the skeleton and every
@@ -193,7 +215,7 @@ 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'))
+      const skeleton = await c.worker(reqId, withTemplate(featurePath, 'req/index.md', 'gaia-requirements-index-template.md') + revisionSection(revisionFindings))
       c.writeOutput(reqIndexPath, skeleton)
     }
 
@@ -231,7 +253,7 @@ return c.run(meta.name, featureDir, prefix, async () => {
         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))
+      c.writeOutput(ucPath, stripModelCrossReferences(detail).trimEnd() + ucCrossReferences(c.read(reqIndexPath), row.id))
     }
     // No assembly/write step here — generation only ever produces req/index.md + its per-UC
     // files. Assembly happens in-memory, on demand, at the top level below (never persisted by
@@ -484,7 +506,7 @@ return c.run(meta.name, featureDir, prefix, async () => {
     const base = `${featurePathArg}\n\nGenerate the full technical design for this component:\n` +
       `Path: ${row.filePath}\nChange: ${row.changeType}\nDomain: ${row.domain}\nAddresses: ${row.addresses}\n\n` +
       `Full component index (for cross-component awareness, do not restate):\n${compactIndex}`
-    return `${base}\n\nTemplate (spec/components/{fileSlug}.md):\n${componentTemplate}`
+    return `${base}\n\nTemplate (spec/components/{fileSlug}.md):\n${componentTemplate}${revisionSection(revisionFindings)}`
   }
 
   // A row's own content fingerprint — the same four fields FTR-030's row-diffing has always
@@ -543,7 +565,7 @@ 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'))
+      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))
     }
 
@@ -740,6 +762,7 @@ return c.run(meta.name, featureDir, prefix, async () => {
       }
       if (cycle === 3) throw new Error('Validation gaps remain after 3 cycles')
       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() }
       if (mergedNeedsTechSpecFix) { await generateTechSpec(true); assembledTechSpec = assembleTechSpec() }
     }

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

@@ -375,6 +375,21 @@ function buildAgentsConventions(root) {
   return kept.length ? kept.join('\n').trim() : null
 }
 
+// Per-phase semantic validation prompt. The whole-WB validator used to receive a directory path and
+// explore it itself with Read/Glob/Grep — on a 123-task feature that single unbounded turn hit the
+// 30-minute worker ceiling, the same failure mode FTR-033 removed from skeleton generation. Each
+// call now sees only its own phase's task details, a one-line index of every OTHER task (for
+// duplicate-across-phases awareness), and that phase's scoped Requirements excerpt.
+function buildSemanticPhasePrompt(phase, taskDetailsText, otherTasksText, requirementsExcerpt, reqIndexPath) {
+  return [
+    `Requirements source: ${reqIndexPath}`,
+    `Phase under review:\n${JSON.stringify({ id: phase.id, type: phase.type, title: phase.title, sourceUC: phase.sourceUC }, null, 2)}`,
+    `Requirements (scoped to this phase's own sourceUC, plus feature-wide sections):\n${requirementsExcerpt}`,
+    `Task details for THIS phase (review these):\n${taskDetailsText}`,
+    `Other tasks in the feature (id — title — outcome; for cross-phase duplicate awareness only, do not review them):\n${otherTasksText || '(none)'}`,
+  ].join('\n\n')
+}
+
 // Compact prompt for the per-phase task-generation worker: this phase's own skeleton entry, its
 // scoped Requirements excerpt, the Tech-Spec skeleton, and every prior phase's own tasks as a
 // lightweight id/title/outcome/domain projection (never a later phase's tasks, which do not exist
@@ -678,11 +693,35 @@ return c.run(meta.name, featureDir, prefix, async () => {
     if (!parsed.valid || parsed.errors.length) throw new Error('Work breakdown structural validation failed: ' + res.stdout)
     return parsed
   })
-  const semantic = await c.worker('gaia.agent.planner.validate-work-breakdown',
-    `${wbsDir}\n${reqIndexPath}`, { schema: {
-      type: 'object', properties: { valid: { type: 'boolean' }, findings: { type: 'array' } }, required: ['valid', 'findings'],
-    } })
-  if (!semantic.valid || semantic.findings.some(f => f.blocking)) throw new Error('Work breakdown semantic validation failed')
+  // Every phase is reviewed even after one fails, so a single run surfaces every blocking finding
+  // at once instead of making the operator fix them one resume at a time.
+  const semanticSchema = {
+    type: 'object', properties: { valid: { type: 'boolean' }, findings: { type: 'array' } }, required: ['valid', 'findings'],
+  }
+  const reqIndexForSemantic = c.read(reqIndexPath)
+  const allFindings = []
+  let semanticValid = true
+  for (const phase of index.phases) {
+    const phaseTaskIds = phase.taskIds
+    const taskDetailsText = phaseTaskIds
+      .map(taskId => `### ${taskId}\n\n${c.read(`${wbsDir}/${index.tasks[taskId].detailFile}`)}`).join('\n\n---\n\n')
+    const otherTasksText = Object.entries(index.tasks)
+      .filter(([id]) => !phaseTaskIds.includes(id))
+      .map(([id, t]) => `- ${id} — ${t.title} — ${t.outcome}`).join('\n')
+    const requirementsExcerpt = hasReq
+      ? buildPhaseRequirementsExcerpt(reqIndexForSemantic, phase.sourceUC, reqDir)
+      : reqIndexForSemantic
+    const verdict = await c.worker('gaia.agent.planner.validate-work-breakdown',
+      buildSemanticPhasePrompt(phase, taskDetailsText, otherTasksText, requirementsExcerpt, reqIndexPath),
+      { schema: semanticSchema, label: `validate-work-breakdown:${phase.id}` })
+    if (!verdict.valid) semanticValid = false
+    for (const finding of verdict.findings) allFindings.push({ ...finding, phaseId: phase.id })
+  }
+  const semantic = { valid: semanticValid, findings: allFindings }
+  if (!semantic.valid || semantic.findings.some(f => f.blocking)) {
+    const blocking = semantic.findings.filter(f => f.blocking).map(f => `[${f.phaseId}] ${f.taskId}: ${f.description}`)
+    throw new Error('Work breakdown semantic validation failed' + (blocking.length ? ':\n' + blocking.join('\n') : ''))
+  }
   // FTR-025: wb-render.js is no longer called automatically here — nothing downstream ever read
   // {PREFIX}-Work-Breakdown.md/.csv (every real consumer already reads wbs/ directly via
   // wbs-assembler.js's loadWorkBreakdown()), so this view is now produced only on demand, via