@dtlabs/ai-toolkit 0.23.0 → 0.23.2

package/CHANGELOG.md

@@ -1,4 +1,19 @@
 ## 0.1.4 (2026-07-21)
+## [0.23.2](https://github.com/dtlab-tech/ai-toolkit/compare/v0.23.1...v0.23.2) (2026-10-22)
+
+
+### Bug Fixes
+
+* **pm-phase2:** bound the WBS skeleton call's own Tech-Spec exploration ([6bca6b5](https://github.com/dtlab-tech/ai-toolkit/commit/6bca6b51f4d495b5912434f4ff83bdcefed2d979))
+* **pm-phase2:** bound the WBS skeleton call's own Tech-Spec exploration (needsComponentDetail) ([804d2cc](https://github.com/dtlab-tech/ai-toolkit/commit/804d2ccf529e0e441b81f9e814a168a9a005a783))
+
+## [0.23.1](https://github.com/dtlab-tech/ai-toolkit/compare/v0.23.0...v0.23.1) (2026-10-22)
+
+
+### Bug Fixes
+
+* **task-executor:** disable MSYS argv path-conversion for verification commands ([00d66ee](https://github.com/dtlab-tech/ai-toolkit/commit/00d66eecb94f7b5464c58cbfec33eb1793e82664))
+
 ## [0.23.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.22.1...v0.23.0) (2026-10-22)
 
 

package/lib/task-executor/index.js

@@ -1056,6 +1056,21 @@ function _runVerificationCommand(command, cwd, timeoutMs) {
         shell: false, // never true: shell:true on Windows silently runs cmd.exe, not Bash
         stdio: ['ignore', 'pipe', 'pipe'],
         windowsHide: true,
+        // MSYS2_ARG_CONV_EXCL: this `bash` is MSYS2/git-bash on Windows, which by default
+        // auto-converts any argument shaped like a POSIX path before handing it to a native
+        // (non-MSYS-aware) child process. A verification command invoking a native tool with
+        // leading-slash switches — e.g. MSBuild's `/p:Configuration=Release`, this project's own
+        // documented build syntax for a .NET consumer — gets silently mangled: MSYS treats
+        // `/p:Configuration=Release` as a POSIX-path-shaped argument, finds no matching drive for
+        // `p:`, and strips the leading slash entirely, leaving MSBuild unable to recognize it as
+        // a property switch (MSB1008: "Only one project can be specified"). Confirmed by direct
+        // reproduction (`bash -c 'node dump-argv.js /p:Configuration=Release'` prints
+        // `p:Configuration=Release`, leading slash gone, UNLESS this variable is set). '*'
+        // excludes every argument from conversion — verification commands never rely on MSYS's
+        // automatic POSIX-to-Windows path conversion for an argument (a real path either
+        // resolves natively as a relative repo path, or is already given in Windows-native form
+        // for a native tool), so excluding all of them is safe, not just the switch-shaped ones.
+        env: Object.assign({}, process.env, { MSYS2_ARG_CONV_EXCL: '*' }),
       });
     } catch (err) {
       finish({ spawnError: 'failed to spawn bash: ' + err.message });

package/package.json

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

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

@@ -7,32 +7,40 @@ tools: Read, Glob, Grep
 
 # Generate Work Breakdown — Skeleton Pass
 
-You are an **expert software architect** specializing in work decomposition and delivery planning. Given a feature's functional requirements and technical specification, produce the **skeleton** of a structured work breakdown: every phase and, per task, only the structural fields needed to fix the dependency graph and acceptance-criteria assignment — `id`, `title`, `outcome`, `domain`, `agentType`, `dependsOn`, `acceptanceCriteria`, `estimate`, `outputCount`, `commit`.
+You are an **expert software architect** specializing in work decomposition and delivery planning. Given a feature's functional requirements and technical specification, produce the **skeleton** of a structured work breakdown: every phase and, per task, only the structural fields needed to fix the dependency graph and acceptance-criteria assignment — `id`, `title`, `outcome`, `domain`, `agentType`, `dependsOn`, `acceptanceCriteria`, `outputCount`, `commit`.
 
-This is the **first of two generation passes** (FTR-020). This call decides the whole task graph — IDs, phases, domains, dependencies, AC assignment — once, up front, in one bounded response. A separate per-task agent (`gaia-generate-work-breakdown-task`) is then dispatched once per task, filling in that task's own verification commands and grouping rationale. You do **not** produce verification commands or grouping-rationale prose — see `gaia-generate-work-breakdown-task` for that.
+This is the **first of two generation passes** (FTR-020). This call decides the whole task graph — IDs, phases, domains, dependencies, AC assignment — once, up front, in one bounded response. A separate per-task agent (`gaia-generate-work-breakdown-task`) is then dispatched once per task, filling in that task's own verification commands, grouping rationale, AND effort estimate (`estimate.agentMinutes`/`estimate.tokens` — moved there, not produced in this pass; see that agent's own instructions). You do **not** produce verification commands, grouping-rationale prose, or an effort estimate — see `gaia-generate-work-breakdown-task` for those.
 
 ---
 
 ## Input
 
-The user provides the path to a `feature.md` file. From the same directory, read:
-
-1. Requirements — `req/index.md` (the split format, FTR-021; source of User Stories derived from
-   Use Cases, acceptance criteria, business rules) if it exists, otherwise the legacy
-   `{PREFIX}-Requirements.md`
-2. Tech-Spec — `spec/index.md` (the split format, FTR-024; source of technical tasks,
-   implementation order, file inventory, architecture decisions) if it exists, otherwise the
-   legacy `{PREFIX}-Tech-Spec.md`
-3. `{PREFIX}-Validation-Report.md` — confirms both documents passed coverage validation
-4. `{PREFIX}-Approvals.md` — confirms user has approved the documents
-
-See Step 1 below for exactly how to read whichever shape (1)/(2) actually are, including per-item
-drilldown into `req/use-cases/*.md`/`spec/components/*.md`.
-
-**This agent runs ONLY after validation and human approval.** If Requirements/Tech-Spec exist in
-neither shape, or (3)/(4) are missing, abort and report:
+Your prompt directly inlines the content you need — you do **not** read Requirements or Tech-Spec
+files yourself:
+
+1. **Requirements — full text, every Use Case's own flow detail included.** Inlined under a
+   `Requirements:` label.
+2. **Tech-Spec — SKELETON ONLY.** Inlined under a `Tech-Spec:` label: 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. Do NOT attempt to locate or Read `req/use-cases/*.md`,
+   `spec/components/*`, `{PREFIX}-Requirements.md`, or `{PREFIX}-Tech-Spec.md` on disk — use the
+   inlined text as the complete input for this pass. If a task-domain/dependency/AC-assignment
+   decision genuinely needs a specific component's own design body beyond its Purpose/Addresses/
+   Domain summary, do not guess and do not explore the filesystem for it — request it via
+   `needsComponentDetail` instead (see "Requesting Component Detail" below). The host will supply
+   it and re-ask you in a second, final call.
+3. `{PREFIX}-Validation-Report.md` and `{PREFIX}-Approvals.md` — the host has already confirmed
+   both exist and are satisfied before dispatching you; you do not need to re-check them.
+
+The path to `feature.md` is given to you first; Read it yourself for the feature's own narrative
+context (Problem Statement, Core Flow, Edge Cases) — it is small and not inlined.
+
+**This agent runs ONLY after validation and human approval.** If the inlined Requirements or
+Tech-Spec text is empty or missing, abort and report:
 ```
-Cannot generate work breakdown: `{file}` not found.
+Cannot generate work breakdown: Requirements/Tech-Spec text was not provided.
 The work breakdown requires validated and approved Requirements + Tech-Spec.
 Run /implement-feature to orchestrate the full pipeline (including validation and approval gates).
 ```
@@ -60,7 +68,7 @@ Extract the **feature prefix** from the folder name containing `feature.md`:
 
 The prefix is everything up to and including the second hyphen-separated segment (pattern: `[A-Z]+-[0-9]+`).
 
-You do not have a Write tool. Return the skeleton as your final response, and nothing else — the host persists your response and splits it into `wbs/index.json` plus one `wbs/user-stories/{phaseId}.md` per phase (your `title`/`commit`/`context` values are written there; see Step 7).
+You do not have a Write tool. Return the skeleton as your final response, and nothing else — the host persists your response and splits it into `wbs/index.json` plus one `wbs/user-stories/{phaseId}.md` per phase (your `title`/`commit`/`context` values are written there; see Step 6).
 
 ---
 
@@ -85,27 +93,36 @@ Every task must be the **smallest independently implementable, verifiable, and c
 
 ## Process
 
-### Step 1 — Load and Cross-Reference
-
-1. Check whether `req/index.md` exists (the split Requirements format, FTR-021). If it does:
-   - Read `req/index.md` fully — it already contains the full Use Cases index table, all Business
-     Rules, all Acceptance Criteria, and all NFRs (FTR-021 kept these feature-wide, not per-UC)
-   - For any UC whose own full flow description you need beyond the index's short Title/Actor
-     summary, Read `req/use-cases/{UC-ID}.md` directly
-   If `req/index.md` does not exist (a legacy feature), Read `{PREFIX}-Requirements.md` fully
-   instead — extract the same information from the monolithic file.
-2. Check whether `spec/index.md` exists (the split Tech-Spec format, FTR-024). If it does:
-   - Read `spec/index.md` fully — it already contains Architecture, Section 9's complete File
-     Inventory/Components table (with Domain/Addresses routing), Implementation Order, and Risks
-   - For any component whose own Backend/Frontend/design detail you need beyond the Components
-     table's one-line Purpose/Addresses summary, Read `spec/components/{file-slug}.md` directly —
-     the `Spec` column in Section 9's table gives you the exact path
-   - If, after reading the index, you cannot determine from its own summary tables which per-item
-     files are relevant to a given phase/task decision, fall back to reading every file under
-     `spec/components/` rather than proceeding with incomplete context
-   If `spec/index.md` does not exist (a legacy feature), Read `{PREFIX}-Tech-Spec.md` fully
-   instead — extract architecture, file inventory, implementation order, data model, API
-   endpoints, frontend components from the monolithic file.
+### Step 1 — Cross-Reference the Inlined Documents
+
+Use the Requirements text (full detail, every UC's own flow included) and the Tech-Spec text
+(skeleton: Section 9's component index table plus feature-wide sections) exactly as inlined in
+your prompt. Cross-reference them to derive every phase and task below — do not Read, Glob, or
+Grep for either document or any of their per-item files; see "Requesting Component Detail" below if
+you hit a genuine information gap only a specific component's own design body can fill.
+
+#### Requesting Component Detail
+
+The Tech-Spec's Section 9 table gives you each component's file path, change type, one-line
+Purpose, `Addresses` (AC IDs), and `Domain` — enough for the large majority of domain/dependency/
+AC-assignment decisions. If a SPECIFIC task decision genuinely needs detail beyond that one-line
+summary (e.g. you cannot tell whether a component's own design implies a second, dependent task,
+or which exact AC(s) within a multi-AC row a particular task slice actually covers), do not guess
+and do not attempt to locate the file yourself. Instead, in your structured output, populate
+`needsComponentDetail` with one entry per component whose own body you need, naming its exact
+Spec-link `fileSlug` and a one-line `reason`:
+
+```json
+"needsComponentDetail": [
+  { "fileSlug": "AuthMiddleware.cs.md", "reason": "need to know whether token refresh is a separate task from validation" }
+]
+```
+
+The host will read exactly those files (nothing else) and dispatch you a SECOND, final call with
+their content appended — answer with your complete, final skeleton on that call; there is no third
+round. Leave `needsComponentDetail` as an empty array `[]` when you have everything you need from
+the skeleton-level summary — this is the common case and costs nothing extra. Never name a
+`fileSlug` that is not a real row in Section 9's own table.
 
 ### Step 2 — Derive User Stories from Use Cases
 
@@ -157,11 +174,10 @@ Decomposition strategy by domain:
 | `agentType` | string | One of: `developer-backend`, `developer-frontend`, `developer-testing`, `review-solution` (deprecated: `developer-database` — maps to `developer-backend`) |
 | `dependsOn` | array of strings | Task IDs this task depends on; may be empty `[]`; all IDs must be defined within this same response |
 | `acceptanceCriteria` | array of strings | AC IDs from Requirements scoped to this task's own phase that this task covers; may be empty `[]`. Never an AC owned by a different phase (see Guidelines) |
-| `estimate` | object | `{ "agentMinutes": N, "tokens": N }` — target ≤ 15 minutes; positive integers |
 | `outputCount` | integer | Number of distinct outputs; must be ≥ 1 |
 | `commit` | object | `{ "type": "feat", "subject": "..." }` — subject must not contain `\|`, CR, or LF |
 
-`verification.commands` and `groupingRationale` are **not** produced in this pass — they are decided by `gaia-generate-work-breakdown-task`, one call per task, from the skeleton entry you produce here (it is told your task's `outputCount`, so it knows whether a grouping rationale is required).
+`verification.commands`, `groupingRationale`, and `estimate` (`agentMinutes`/`tokens`) are **not** produced in this pass — they are decided by `gaia-generate-work-breakdown-task`, one call per task, from the skeleton entry you produce here (it is told your task's `outputCount`, so it knows whether a grouping rationale is required). You still judge task SIZE here — see the Atomicity Contract's own ≤15-minute target, which governs how finely you split tasks — you just don't emit a numeric estimate for it.
 
 **Domain → agentType mapping (default):**
 - `DB` → `developer-backend` (note: `developer-database` is a deprecated alias that still resolves — do NOT use it in new Work Breakdowns)
@@ -200,22 +216,7 @@ For each task, determine `dependsOn` as a list of **task IDs** (not phase IDs):
 
 **Tip:** List only direct dependencies. Transitive dependencies are implied.
 
-### Step 6 — Estimate
-
-For each task, provide:
-- `estimate.agentMinutes`: integer; **target ≤ 15**; above 30 is rejected by the validator
-
-Duration guidance:
-| Band | Range | Action |
-|------|-------|--------|
-| Target | ≤ 15 min | No action needed |
-| Above target | 16–20 min | Acceptable |
-| Warning | 21–30 min | Prefer to split |
-| Split required | > 30 min | **Must split** — the validator will reject this |
-
-- `estimate.tokens`: integer; rough estimate of token consumption (input + output) for the agent invocation; use project norms if available, otherwise estimate based on task complexity (small: 10 000–25 000, medium: 25 000–60 000)
-
-### Step 7 — Return the Skeleton
+### Step 6 — Return the Skeleton
 
 Return the skeleton's content 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. The content must be:
 - Valid JSON
@@ -230,7 +231,8 @@ Return the skeleton's content as your final response, and nothing else (no pream
   "schemaVersion": 3,
   "feature": "{PREFIX}",
   "phases": [ ... ],
-  "tasks": { ... }
+  "tasks": { ... },
+  "needsComponentDetail": [ ... ]
 }
 ```
 
@@ -238,6 +240,7 @@ Return the skeleton's content as your final response, and nothing else (no pream
 - `feature` must be the feature prefix string (e.g., `"FTR-020"`)
 - `phases` is an ordered array of phase objects; INFRA phase first (if present), then US phases in priority order
 - `tasks` is a **map keyed by task ID** (not nested inside each phase) — every phase's `taskIds` array indexes into this map
+- `needsComponentDetail` is optional — omit it or leave it `[]` when you have everything you need (the common case); see "Requesting Component Detail" in Step 1. When non-empty, `phases`/`tasks` may be your best DRAFT given what you currently know — the host discards them and re-asks you with the requested detail appended; only your response on that second call is final.
 
 **Phase object:**
 
@@ -281,7 +284,6 @@ For user-story phases:
   "agentType": "developer-backend",
   "dependsOn": [],
   "acceptanceCriteria": [],
-  "estimate": { "agentMinutes": 8, "tokens": 15000 },
   "outputCount": 1,
   "commit": { "type": "feat", "subject": "add IRepository base interface" }
 }
@@ -321,7 +323,6 @@ For user-story phases:
       "agentType": "developer-backend",
       "dependsOn": [],
       "acceptanceCriteria": [],
-      "estimate": { "agentMinutes": 8, "tokens": 15000 },
       "outputCount": 1,
       "commit": { "type": "feat", "subject": "add IRepository base interface" }
     },
@@ -332,7 +333,6 @@ For user-story phases:
       "agentType": "developer-backend",
       "dependsOn": ["INFRA-TASK-BE-01"],
       "acceptanceCriteria": ["AC-01", "AC-03"],
-      "estimate": { "agentMinutes": 12, "tokens": 28000 },
       "outputCount": 1,
       "commit": { "type": "feat", "subject": "add User entity and migration" }
     },
@@ -343,7 +343,6 @@ For user-story phases:
       "agentType": "developer-backend",
       "dependsOn": ["US-01-TASK-DB-01"],
       "acceptanceCriteria": ["AC-02"],
-      "estimate": { "agentMinutes": 14, "tokens": 35000 },
       "outputCount": 1,
       "commit": { "type": "feat", "subject": "add CreateUserService" }
     }
@@ -369,6 +368,7 @@ Do NOT guess or invent task decompositions when the source is unclear. Ask first
 
 - Write in **English**
 - **Derive all content from the Requirements and Tech-Spec** — do not invent tasks not grounded in those documents
+- **Never self-explore the filesystem for Requirements/Tech-Spec content** — both are inlined in your prompt (Requirements full, Tech-Spec skeleton-only); use `needsComponentDetail` for a genuine component-body gap instead of Reading/Globbing/Grepping for it
 - **Atomicity is mandatory** — each task must have one outcome, one domain, one agent type, one commit subject
 - **Task granularity**: target ≤ 15 minutes of agent time; split any task that cannot be scoped to ≤ 15 minutes
 - **Domain assignment must be unambiguous** — use the domain table in Step 3

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

@@ -56,9 +56,63 @@ const SKELETON_SCHEMA = {
           properties: { type: { type: 'string' }, subject: { type: 'string' } } },
       },
     } },
+    // Bounded drill-down (mirrors pm-phase1.js's own needsComponentDetail precedent for the
+    // feature-doc validator, FTR-028) — declared in `properties` only, never `required`: the
+    // common case is an empty array, costing nothing extra. See gaia-generate-work-breakdown.md's
+    // own "Requesting Component Detail" section for when the agent should populate this instead
+    // of self-exploring spec/components/* (the real, evidenced dominant cost driver on a large
+    // feature — confirmed against a real run: 1.18M of 1.38M total tokens on one failing attempt
+    // were cache_read_input_tokens, not the declared output schema size).
+    needsComponentDetail: { type: 'array', items: { type: 'object',
+      properties: { fileSlug: { type: 'string' }, reason: { type: 'string' } }, required: ['fileSlug'] } },
   },
 }
 
+// Fixed, not externally configurable (same "no real evidence yet justifies external tuning"
+// precedent as every other bounded retry/batch constant in this codebase) — a safety cap, not a
+// typical case; the skeleton agent's own instructions already frame needsComponentDetail as the
+// exception, reserved for a genuine per-task decision gap, not a substitute for broad exploration.
+const SKELETON_DRILL_DOWN_MAX_COMPONENTS = 20
+
+// Builds the skeleton-generation prompt: Requirements FULL text + Tech-Spec SKELETON ONLY
+// (never per-component bodies) inlined directly, mirroring pm-phase1.js's own
+// gaia-validate-feature-docs prompt shape exactly — the agent no longer self-reads either
+// document or any per-item file via its own Read/Glob/Grep tool access.
+function buildSkeletonPrompt(featurePath, requirementsText, techSpecSkeletonText, drillDownText) {
+  const parts = [
+    featurePath,
+    '',
+    'Requirements:',
+    requirementsText,
+    '',
+    'Tech-Spec:',
+    techSpecSkeletonText,
+  ]
+  if (drillDownText) {
+    parts.push('', 'Component detail you requested:', drillDownText)
+  }
+  return parts.join('\n')
+}
+
+// Validates each needsComponentDetail entry's fileSlug against the real component table (a
+// hallucinated/mistyped reference is dropped, never dispatched — mirrors pm-phase1.js's own
+// prepareDrillDownBatches), deduplicates by fileSlug, and caps the total at
+// SKELETON_DRILL_DOWN_MAX_COMPONENTS. Returns the inlinable text block (or null if nothing valid
+// remains) — this reads files directly (deterministic, free), never dispatches another agent.
+function buildComponentDrillDownText(needsComponentDetail, specIndexContent, specDirArg) {
+  const components = parseComponentsTableLocal(specIndexContent)
+  const bySlug = new Map(components.map(c => [c.fileSlug, c]))
+  const uniqueSlugs = [...new Set((needsComponentDetail || [])
+    .map(e => e.fileSlug)
+    .filter(slug => bySlug.has(slug)))]
+    .slice(0, SKELETON_DRILL_DOWN_MAX_COMPONENTS)
+  if (uniqueSlugs.length === 0) return null
+  return uniqueSlugs.map(slug => {
+    const comp = bySlug.get(slug)
+    return `### ${comp.filePath} (${slug})\n\n${c.read(`${specDirArg}/components/${slug}`)}`
+  }).join('\n\n---\n\n')
+}
+
 // Splits the skeleton response into (a) index.json's structural, map-keyed shape and
 // (b) nothing else — phase title/commit/context are NOT copied into index.json (OQ-04); they
 // are rendered straight to each phase's detail file by the caller, from the same skeleton
@@ -334,7 +388,33 @@ return c.run(meta.name, featureDir, prefix, async () => {
   // 1. Skeleton (no declared worker() output — host writes every file itself)
   let index
   if (!c.exists(indexPath)) {
-    const skeleton = await c.worker('gaia.agent.planner.work-breakdown', featurePath, { schema: SKELETON_SCHEMA })
+    // Requirements FULL text + Tech-Spec SKELETON ONLY, inlined directly — same shape as
+    // pm-phase1.js's own validator prompt (FTR-028). Computed unconditionally here (not reused
+    // from the Gate-1 digest check above, which only runs when Approvals.md carries a digest
+    // line) so this prompt is always built the same way regardless of that check's own outcome.
+    const requirementsForSkeleton = hasReq
+      ? c.command(['run-asset', 'scripts/req-assembler.js', '--project', c.root, '--', reqDir]).stdout
+      : c.read(file('Requirements.md'))
+    const techSpecSkeletonForSkeleton = hasSpec ? c.read(specIndexPath) : c.read(file('Tech-Spec.md'))
+
+    let skeleton = await c.worker('gaia.agent.planner.work-breakdown',
+      buildSkeletonPrompt(featurePath, requirementsForSkeleton, techSpecSkeletonForSkeleton),
+      { schema: SKELETON_SCHEMA })
+
+    // Bounded, single-round drill-down (FTR-028 precedent) — see buildComponentDrillDownText's
+    // own comment. No further rounds: the second call's own response is used as-is, even if it
+    // asks for more (fail-fast rather than open-ended retries, matching this codebase's other
+    // bounded-retry conventions).
+    const needsComponentDetail = skeleton.needsComponentDetail || []
+    if (hasSpec && needsComponentDetail.length > 0) {
+      const drillDownText = buildComponentDrillDownText(needsComponentDetail, c.read(specIndexPath), specDir)
+      if (drillDownText) {
+        skeleton = await c.worker('gaia.agent.planner.work-breakdown',
+          buildSkeletonPrompt(featurePath, requirementsForSkeleton, techSpecSkeletonForSkeleton, drillDownText),
+          { schema: SKELETON_SCHEMA, label: 'work-breakdown-skeleton:with-drilldown' })
+      }
+    }
+
     index = materializeIndex(skeleton)
     const taskIdToPhase = new Map(skeleton.phases.flatMap(p => p.taskIds.map(taskId => [taskId, p.id])))
     for (const phase of index.phases) {