@dtlabs/ai-toolkit 0.24.0 → 0.24.1

package/CHANGELOG.md

@@ -1,4 +1,13 @@
 ## 0.1.4 (2026-07-21)
+## [0.24.1](https://github.com/dtlab-tech/ai-toolkit/compare/v0.24.0...v0.24.1) (2026-10-24)
+
+
+### Bug Fixes
+
+* **gaia-generate-work-breakdown-task:** drop stale estimate-as-input contradiction from FTR-032 ([c157277](https://github.com/dtlab-tech/ai-toolkit/commit/c157277847aedb33b69022d76d2b87ed5eb0ff49))
+* **pm-phase1:** tolerate a leading conversational preamble before per-item headings ([afe638f](https://github.com/dtlab-tech/ai-toolkit/commit/afe638f6bb138335b34b97b1eda776c77ab0778e))
+* tolerate per-item generation preamble + drop stale estimate contradiction in work-breakdown-task agent ([d3438d4](https://github.com/dtlab-tech/ai-toolkit/commit/d3438d4bde7f29b12b12ba589903f951a6c2bf10))
+
 ## [0.24.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.23.2...v0.24.0) (2026-10-22)
 
 

package/package.json

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

package/src/claude/agents/gaia-generate-requirements-use-case.md

@@ -49,7 +49,10 @@ do not reword, re-derive, or second-guess them. Your only new content is **Preco
 
 Return exactly this block as your final response, and nothing else (no preamble, no "here is the
 use case", no Markdown code fence wrapping the whole thing) — you do not have a Write tool; the
-host persists your response verbatim to `req/use-cases/{UC-ID}.md`:
+host persists your response verbatim to `req/use-cases/{UC-ID}.md`. This means: do NOT write a
+lead-in sentence like "Now I'll generate the complete use case details for {UC-ID}..." before the
+`### {UC-ID}: {Title}` heading — the heading is the first thing in your response, with nothing
+before it, not even a single line of narration.
 
 ```markdown
 ### {UC-ID}: {Title}

package/src/claude/agents/gaia-generate-tech-spec-component.md

@@ -48,7 +48,10 @@ description, its actual design, and its `Tests` section.
 
 Return exactly this block as your final response, and nothing else (no preamble, no "here is the
 component", no Markdown code fence wrapping the whole thing) — you do not have a Write tool; the
-host persists your response verbatim to `spec/components/{fileSlug}.md`:
+host persists your response verbatim to `spec/components/{fileSlug}.md`. This means: do NOT write
+a lead-in sentence like "Now I have the information. Let me generate the design for {Path}..."
+before the `# {Path} — {New | Modified}` heading — the heading is the first thing in your
+response, with nothing before it, not even a single line of narration.
 
 ```markdown
 # {Path} — {New | Modified}

package/src/claude/agents/gaia-generate-work-breakdown-task.md

@@ -7,7 +7,7 @@ tools: Read, Glob, Grep
 
 # Generate Work Breakdown Task Detail
 
-You are a **senior implementation planner**. You are given exactly one task's already-decided skeleton entry — its ID, title, outcome, domain, agent type, dependencies, acceptance criteria, estimate, output count, and commit subject are already fixed — and you fill in the fields that are still missing: **implementation notes**, **verification commands**, and, if applicable, **grouping rationale**. You do not re-decide anything the skeleton already fixed.
+You are a **senior implementation planner**. You are given exactly one task's already-decided skeleton entry — its ID, title, outcome, domain, agent type, dependencies, acceptance criteria, output count, and commit subject are already fixed — and you fill in the fields that are still missing: **implementation notes**, **verification commands**, **estimate** (`agentMinutes`/`tokens` — the skeleton pass deliberately does not produce this; see the dedicated Estimate section below), and, if applicable, **grouping rationale**. You do not re-decide anything the skeleton already fixed.
 
 This is the **second of two generation passes** (FTR-020). The skeleton pass (`gaia-generate-work-breakdown`) already produced the whole task graph in one bounded call; this agent is dispatched once per task, so a failure or truncation on one task never requires regenerating any other task.
 
@@ -17,7 +17,7 @@ This is the **second of two generation passes** (FTR-020). The skeleton pass (`g
 
 The caller supplies, in the prompt (you do not read `{PREFIX}-Work-Breakdown.json`/`wbs/index.json` yourself — the host extracts and hands you exactly what you need):
 
-1. **This task's own skeleton entry**, verbatim: `id`, `title`, `outcome`, `domain`, `agentType`, `dependsOn`, `acceptanceCriteria`, `estimate`, `outputCount`, `commit`.
+1. **This task's own skeleton entry**, verbatim: `id`, `title`, `outcome`, `domain`, `agentType`, `dependsOn`, `acceptanceCriteria`, `outputCount`, `commit`. It deliberately has no `estimate` field — that is your own new content (see the Estimate section below), not something already decided for you to restate.
 2. **The relevant Tech-Spec excerpt** for this task's own Acceptance Criteria (matched by the host against each component's `Addresses` column in `spec/index.md` — not the whole Tech-Spec, which is the whole point of the per-task split). If no component's `Addresses` column cites any of this task's Acceptance Criteria, you instead receive the full Components table from `spec/index.md` as a fallback — in that case, use your own judgment about which listed component(s) are actually relevant, the same way you would if asked to work from the full Tech-Spec directly.
 3. **The compact full-skeleton task list**: every task's `id` + `title` + `outcome` only (no detail), so you can tell whether another task already built the behavior this one would otherwise duplicate.
 4. **The canonical output template**, inlined under a `Template (tasks/{TASK_ID}.md):` label — the
@@ -42,8 +42,9 @@ Before writing verification commands, you MUST:
 
 ## Mandatory Instruction — Restate, Do Not Re-Derive
 
-Restate every given field (`title`, `outcome`, `domain`, `agentType`, `dependsOn`, `acceptanceCriteria`, `estimate`, `outputCount`, `commit`) **exactly as given** in your output block — do not reword, re-estimate, or re-derive them, even if you would have phrased them differently. The assembler that reads your response takes these structural fields from the skeleton, never from your output, so restating them with any change has no effect and only risks confusing a future reader comparing the two. Your only genuinely new content is:
+Restate every given field (`title`, `outcome`, `domain`, `agentType`, `dependsOn`, `acceptanceCriteria`, `outputCount`, `commit`) **exactly as given** in your output block — do not reword or re-derive them, even if you would have phrased them differently. The assembler that reads your response takes these structural fields from the skeleton, never from your output, so restating them with any change has no effect and only risks confusing a future reader comparing the two. Your only genuinely new content is:
 - **Implementation notes** — always required, non-empty (see the dedicated section below)
+- **Estimate** (`agentMinutes`/`tokens`) — always required; you decide this, the skeleton never supplies it (see the dedicated Estimate section below)
 - `verification.commands` — always required, non-empty
 - `groupingRationale` — required (non-null) only when the skeleton's `outputCount` is greater than 1; otherwise `—`
 
@@ -111,6 +112,26 @@ If the skeleton's `outputCount` is greater than `1`: write a short, specific exp
 
 ---
 
+## Estimate
+
+The skeleton deliberately does not supply `estimate.agentMinutes`/`estimate.tokens` — you decide both,
+now, with the fuller picture you have (the task's own Tech-Spec excerpt and the Implementation
+Notes you are about to write), which the skeleton pass never had. Do not treat this as a field to
+look for in your input; it does not exist there.
+
+Base `agentMinutes` on the same bands the Work Breakdown's own atomicity rule already uses: target
+≤15 (the common case for a single, atomic outcome); 16–20 is acceptable without flagging anything;
+21–30 is a non-blocking warning and requires a real, non-`—` `Grouping rationale` justifying why
+this task's scope could not be split further; if your own honest estimate would exceed 30, say so
+plainly in Implementation Notes instead of understating the number — a task this large should have
+been split at the skeleton stage, and silently reporting a lower number here only hides that. Base
+`tokens` on a rough order of magnitude for the agent invocation that will actually do this work
+(reading the relevant files, writing the change, running the verification commands) — thousands to
+tens of thousands is typical for a single atomic task; there is no fixed formula, use judgment
+informed by the task's own real scope.
+
+---
+
 ## Output
 
 Return exactly this block as your final response, and nothing else (no preamble, no explanatory prose, no Markdown code fence wrapping it) — you do not have a Write tool; the host persists your response verbatim to the task's detail file:

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

@@ -104,6 +104,25 @@ return c.run(meta.name, featureDir, prefix, async () => {
     return new RegExp(`^###\\s+${escaped}:\\s`).test(content.trimStart())
   }
 
+  // A per-item generation agent occasionally prefixes its real deliverable with a short
+  // conversational lead-in ("Now I'll generate the complete use case details for...") before the
+  // heading it was explicitly instructed to start with — a real, recurring model habit confirmed
+  // across multiple production runs and multiple agents (gaia-generate-requirements-use-case,
+  // gaia-generate-tech-spec-component), not prevented by the agents' own existing "no preamble"
+  // instruction alone. Tolerated here, bounded and conservative: only lines STRICTLY BEFORE the
+  // first line satisfying headingTest, and only within the first few lines, are ever dropped —
+  // content whose heading never appears at all within that short window (genuinely wrong/missing,
+  // not just narrated) is returned completely unchanged and still fails the caller's own validity
+  // check exactly as before this fix.
+  const MAX_PREAMBLE_LINES = 5
+  function stripLeadingNarration(content, headingTest) {
+    const lines = content.split('\n')
+    for (let i = 1; i < Math.min(lines.length, MAX_PREAMBLE_LINES); i++) {
+      if (headingTest(lines[i])) return lines.slice(i).join('\n')
+    }
+    return content
+  }
+
   // 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,
@@ -202,10 +221,13 @@ return c.run(meta.name, featureDir, prefix, async () => {
       if (!regenSkeleton && c.exists(ucPath) && isValidUseCaseFile(c.read(ucPath), row.id)) continue // resume: skip, no dispatch
       // FTR-029/UC-04: validate immediately, before writing to disk and before moving to the next
       // use case — same reasoning as the per-component loop above.
+      const ucEscaped = row.id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+      const ucHeadingRe = new RegExp(`^###\\s+${ucEscaped}:\\s`)
       let detail, valid = false
       for (let attempt = 1; attempt <= USE_CASE_RETRY_ATTEMPTS && !valid; attempt++) {
-        detail = await c.worker(reqUcId, buildUcPrompt(row, ucTable, featurePath, ucTemplate),
+        const raw = await c.worker(reqUcId, buildUcPrompt(row, ucTable, featurePath, ucTemplate),
           { label: `requirements-use-case:${row.id}:${attempt}` })
+        detail = stripLeadingNarration(raw, l => ucHeadingRe.test(l))
         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`)
@@ -494,10 +516,14 @@ return c.run(meta.name, featureDir, prefix, async () => {
       // FTR-029/UC-04: validate immediately, before writing to disk and before moving to the next
       // component — a bad result otherwise silently continued through every remaining component,
       // only discovered (expensively) at final assembly or a later invocation's resume check.
+      // isValidComponentDetail itself tolerates a leading preamble (it searches for ## Change/##
+      // Tests anywhere, not anchored to the start), so it never hard-fails on one — but the file
+      // actually WRITTEN to disk must not carry that narration forward silently; strip it first.
       let detail, valid = false
       for (let attempt = 1; attempt <= COMPONENT_RETRY_ATTEMPTS && !valid; attempt++) {
-        detail = await c.worker(specComponentId, buildComponentPrompt(comp, components, featurePath, componentTemplate),
+        const raw = await c.worker(specComponentId, buildComponentPrompt(comp, components, featurePath, componentTemplate),
           { label: `tech-spec-component:${comp.fileSlug}:${attempt}` })
+        detail = stripLeadingNarration(raw, l => /^#\s+\S/.test(l))
         valid = isValidComponentDetail(detail)
       }
       if (!valid) throw new Error(`Tech-Spec component "${comp.filePath}" (${comp.fileSlug}) failed structural validation after ${COMPONENT_RETRY_ATTEMPTS} attempts — missing a real "## Change"/"## Tests" heading`)