@dtlabs/ai-toolkit 0.24.0 → 0.24.2

package/CHANGELOG.md

@@ -1,4 +1,26 @@
 ## 0.1.4 (2026-07-21)
+## [0.24.2](https://github.com/dtlab-tech/ai-toolkit/compare/v0.24.1...v0.24.2) (2026-10-26)
+
+
+### Bug Fixes
+
+* **pm-phase1:** make Tech-Spec component identity permanent via a manifest ([642527f](https://github.com/dtlab-tech/ai-toolkit/commit/642527ffd7de4269d663330a02e1f652920a097e))
+
+
+### Performance Improvements
+
+* bound worker prompt context and stop source-tree exploration ([ebd273b](https://github.com/dtlab-tech/ai-toolkit/commit/ebd273b541fa4adbe34c18fc6172acacc3cb2854))
+* **pm-phase1,pm-phase2:** bound worker prompt context and stop source-tree exploration ([801681a](https://github.com/dtlab-tech/ai-toolkit/commit/801681abbcbdff83600ca68c7434729c9cd27be6))
+
+## [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/lib/workflow-control.js

@@ -69,7 +69,7 @@ function deriveFeatureDir(featurePath) {
 }
 
 function createControl(options) {
-  if (options.workerMaxBudgetUsd != null && (!Number.isFinite(options.workerMaxBudgetUsd) || options.workerMaxBudgetUsd <= 0)) throw new Error('Worker budget must be a positive finite number');
+  if (options.workerMaxBudgetUsd != null && (!Number.isFinite(options.workerMaxBudgetUsd) || options.workerMaxBudgetUsd < 0)) throw new Error('Worker budget must be a non-negative finite number (0 disables the cap)');
   // Windows can alias any long/dotted path segment to an 8.3 short name (e.g. the
   // TEMP env var itself is often short-form: C:\Users\TOMADA~1\...). The spawned
   // CLI resolves a tool call's absolute path in long form regardless, so an
@@ -148,7 +148,12 @@ function createControl(options) {
       // call sites for the same reasoning).
       const cliArgs = ['--print', '--output-format', 'json', '--agent', identity.nativeName, '--no-session-persistence'];
       if (opts.schema) cliArgs.push('--json-schema', JSON.stringify(opts.schema));
-      if (options.workerMaxBudgetUsd != null) cliArgs.push('--max-budget-usd', String(options.workerMaxBudgetUsd));
+      // Runaway circuit breaker, not a tuning knob: a single worker call has no legitimate reason
+      // to cost multiple dollars, but real runs have produced $3+ calls when an agent fell into a
+      // long self-directed exploration loop. Opt-out (explicit 0 disables) rather than opt-in,
+      // because the failure it guards against is exactly the one nobody thinks to configure for.
+      const budgetUsd = options.workerMaxBudgetUsd != null ? options.workerMaxBudgetUsd : DEFAULT_WORKER_MAX_BUDGET_USD;
+      if (budgetUsd) cliArgs.push('--max-budget-usd', String(budgetUsd));
       const outputs = opts.outputs || [];
       for (const output of outputs) {
         if (!output || typeof output.path !== 'string' || !Array.isArray(output.inputs || [])) throw new Error('Invalid worker output contract');
@@ -361,6 +366,12 @@ function createControl(options) {
 // retried by hand from the CLI. 3 total attempts, waiting 5s then 20s between them: long
 // enough for a brief network stall to clear, short enough not to turn a real, deterministic
 // failure into a multi-minute stall before it's reported.
+// Deliberately well above any healthy call (the most expensive legitimate worker measured across
+// two real projects was $1.96, and the prompt-scoping work done alongside this brings that down)
+// — this exists to stop a runaway, not to shape normal spend. Override per run with
+// --worker-max-budget-usd; pass 0 to disable entirely.
+const DEFAULT_WORKER_MAX_BUDGET_USD = 5;
+
 const WORKER_MAX_ATTEMPTS = 3;
 const WORKER_RETRY_BACKOFF_MS = [5000, 20000];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtlabs/ai-toolkit",
-  "version": "0.24.0",
+  "version": "0.24.2",
   "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-phase.md

@@ -2,7 +2,7 @@
 name: gaia-generate-work-breakdown-phase
 description: "Generates one phase's own tasks (structural fields) and narrative context for a Work Breakdown, given that phase's scoped Requirements/Tech-Spec context and every prior phase's already-decided tasks. Input: the phase to generate, its scoped Requirements excerpt, the Tech-Spec skeleton, and prior-phase task projections"
 model: sonnet
-tools: Read, Glob, Grep
+tools: Read
 ---
 
 # Generate Work Breakdown — Per-Phase Task Pass
@@ -30,12 +30,22 @@ Your prompt directly inlines:
    (not full task objects): use these to reference a real prerequisite in `dependsOn`, and to
    recognize/avoid re-implementing something a prior phase already built. You will NEVER be given
    a LATER phase's tasks — they do not exist yet; never invent a dependency on one.
+5. **The design detail of the components this phase's own Acceptance Criteria cover** — the host
+   resolves this deterministically and inlines it. This is the technical design you need; it
+   already describes the real files, signatures and algorithms involved.
+6. **The project's build/verification conventions**, extracted from `AGENTS.md` by the host.
 
-## Step 0 — Read Project Conventions (MANDATORY)
+## Do not explore the project's source tree
 
-Read `AGENTS.md` from the current working directory — tech stack/frameworks (domain
-classification), directory structure (task file paths), build/verification commands. Ensures your
-tasks reference the correct technologies, paths, and commands.
+Everything above is supplied to you. Do **not** go reading the project's real source files to
+rediscover a design that is already inlined, and do not read `AGENTS.md` yourself — the host has
+already extracted the relevant part. This is not a style preference: on real features, self-directed
+source exploration has cost 36-43 turns and several dollars per call, with the great majority of
+that spent re-deriving information the prompt already contained.
+
+If a decision genuinely needs a component's design body that was NOT inlined, ask for it through
+`needsComponentDetail` (see below) — that is the supported, bounded path, and it is far cheaper
+than exploring.
 
 ## Atomicity Contract
 
@@ -131,7 +141,8 @@ in the common case.
 
 - Write in English. Derive content only from the inlined Requirements/Tech-Spec — never invent a
   task not grounded in them.
-- Never self-explore the filesystem for Requirements/Tech-Spec content — both are inlined.
+- Never self-explore the filesystem — Requirements, Tech-Spec, component design detail and build
+  conventions are all inlined (see "Do not explore the project's source tree" above).
 - Atomicity is mandatory (see Atomicity Contract above).
 - `dependsOn` may reference a task from this phase or any prior phase — never a later one, never a
   dangling reference.

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

@@ -1,13 +1,13 @@
 ---
 name: gaia-generate-work-breakdown-task
 description: "Generates one task's detail block (implementation notes, verification commands, grouping rationale) from its skeleton entry. Input: skeleton task entry + Tech-Spec excerpt + compact sibling task list"
-model: sonnet
+model: haiku
 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
@@ -28,22 +28,25 @@ The caller supplies, in the prompt (you do not read `{PREFIX}-Work-Breakdown.jso
    fallback either. This section and the Output section below summarize it; the inlined template
    text is the source of truth if the two ever disagree.
 
-If the prompt is missing any of these four, stop and report exactly what is missing — do not guess at a skeleton entry you were not given.
+5. **The project's build/verification conventions**, extracted from `AGENTS.md` by the host and inlined under its own label. Use that text for your verification commands — do **not** read `AGENTS.md` yourself; it is tens of kilobytes and the host has already pulled out the command-bearing sections.
+
+If the prompt is missing any of these, stop and report exactly what is missing — do not guess at a skeleton entry you were not given.
 
 ---
 
-## Step 0 — Read Project Conventions (MANDATORY)
+## Scope of the Tech-Spec you are given
 
-Before writing verification commands, you MUST:
+You receive an index line for every component your task's Acceptance Criteria cover, plus the full design body only for the component(s) your own task names. That is deliberate: a task normally touches one or two files, and inlining every AC-matched body measured over 100 KB per call on a real feature.
 
-1. Read `AGENTS.md` from the current working directory — this defines build/test commands appropriate for the project's tech stack.
+If the body you actually need is missing, you may read that one component file under `spec/components/` — but do not go exploring the project's wider source tree to re-derive a design the Tech-Spec already states.
 
 ---
 
 ## 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 `—`
 
@@ -82,7 +85,7 @@ Before writing verification commands, scan the compact sibling task list for any
 
 ## Verification Commands
 
-Supply one or more shell commands in `verification.commands` that an agent can run to confirm the task's output is correct. The array must be non-empty. Use commands appropriate for the project's tech stack (read from `AGENTS.md`). Examples:
+Supply one or more shell commands in `verification.commands` that an agent can run to confirm the task's output is correct. The array must be non-empty. Use commands appropriate for the project's tech stack, taken from the build/verification conventions inlined in your prompt. Examples:
 - Compilation check: `npx tsc --noEmit`, `dotnet build`, `node --check <file>`
 - Targeted test run: `npm test -- --testPathPattern=<file>`, `npx jest --testPathPattern=<file>`, `dotnet test --filter <class>`
 - File existence: `test -f <path>`
@@ -111,6 +114,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,13 +104,32 @@ 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,
   // which is exactly why the per-UC generation agent is never given this data at all (see
   // gaia-generate-requirements-use-case.md: it must not re-read req/index.md itself, to avoid
   // re-deciding which UCs exist). The host computes and appends these cross-reference lines
-  // itself, after the agent's own response, mirroring how disambiguateFileSlugs/computeDependsOnPhases
+  // itself, after the agent's own response, mirroring how applyComponentSlugs/computeDependsOnPhases
   // post-process agent/skeleton output elsewhere in this lineage.
   function parseBusinessRulesTable(indexContent) {
     const lines = indexContent.split('\n')
@@ -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`)
@@ -221,6 +243,96 @@ return c.run(meta.name, featureDir, prefix, async () => {
   const specDir = `${featureDir}/spec`
   const specIndexPath = `${specDir}/index.md`
 
+  // The permanent identity registry for Tech-Spec components, replacing fileSlug's own
+  // per-table-position disambiguation. A slug used to be disambiguated only against the OTHER
+  // slugs present in the SAME skeleton table, so the very same source file could be `App.tsx.md`
+  // in one generation and `shell-app-App.tsx.md` in the next purely because the component set
+  // around it changed — which also meant FTR-030's regen row-diffing (keyed on that slug) missed
+  // exactly when the table changed, i.e. precisely when it was supposed to help, regenerating
+  // everything and stranding the old files as orphans. Two append-only, sticky tables instead:
+  // `pathHashes` (a directory's own short hash, computed once and reused for every sibling file
+  // from that directory that ever needs disambiguating) and `components` (a filePath's own
+  // permanently-assigned slug plus bookkeeping). Neither table is ever rewritten once an entry
+  // exists — see assignComponentSlug's own comment for why that matters.
+  const manifestPath = `${specDir}/components.manifest.json`
+  function loadManifest() {
+    if (!c.exists(manifestPath)) return { pathHashes: {}, components: {} }
+    const parsed = c.json(manifestPath)
+    return { pathHashes: parsed.pathHashes || {}, components: parsed.components || {} }
+  }
+  function saveManifest(manifest) {
+    c.writeOutput(manifestPath, JSON.stringify(manifest, null, 2))
+  }
+
+  // Assigns (or reuses) one component's permanent slug. Basename-first for human readability —
+  // `App.tsx.md` reads far better than any path-derived name — falling back to a directory-level
+  // hash prefix ONLY when the basename collides with another file's ALREADY-assigned slug. The
+  // hash is computed from the component's own directory (not its full path), and cached in
+  // `pathHashes` so every other file from that same directory that ever needs disambiguating gets
+  // the SAME prefix — siblings become visually recognizable as a group (`a1b2c3d4-App.tsx.md`,
+  // `a1b2c3d4-main.tsx.md`) instead of each getting an unrelated-looking hash.
+  //
+  // Both lookups are permanent: an already-assigned slug is returned as-is, never recomputed, so a
+  // LATER file claiming the same basename can never force an EARLIER file to rename — the exact
+  // instability the old per-table disambiguation had (see the comment on loadManifest's own
+  // declaration above for the production consequence this caused). One real, accepted side
+  // effect: if the file that originally won a clean basename is later removed from the Tech-Spec,
+  // its slug is never freed — every sibling that collided with it keeps its hash prefix even
+  // though the collision is now only historical.
+  // Writes a provisional `{ slug }` entry immediately (not just returns it), so a second file with
+  // the same basename processed later in this SAME pass correctly sees the first as already taken.
+  function assignComponentSlug(manifest, filePath) {
+    const existing = manifest.components[filePath]
+    if (existing) return existing.slug
+    const basename = filePath.split('/').pop()
+    const cleanSlug = `${basename}.md`
+    const taken = Object.entries(manifest.components).some(([p, e]) => p !== filePath && e.slug === cleanSlug)
+    let slug
+    if (!taken) {
+      slug = cleanSlug
+    } else {
+      const dir = filePath.slice(0, filePath.length - basename.length - 1) || '.'
+      let dirHash = manifest.pathHashes[dir]
+      if (!dirHash) {
+        dirHash = c.hash(dir).replace(/^sha256:/, '').slice(0, 8)
+        manifest.pathHashes[dir] = dirHash
+      }
+      slug = `${dirHash}-${basename}.md`
+    }
+    manifest.components[filePath] = { slug }
+    return slug
+  }
+
+  // Rewrites every row's Spec-link in a freshly-generated skeleton to the manifest-assigned slug
+  // — never trusting whatever the agent's own response contains there (the component template's
+  // own contract already calls that link "provisional, not final" for exactly this reason: a real
+  // skeleton omitted the ".md" suffix entirely on 20 of ~61 rows). Host-computed from `filePath`
+  // alone, so a malformed, missing-suffix, or merely different-looking slug in the agent's own
+  // text is irrelevant — only well-formed `(components/...)` rows are found at all; an entirely
+  // absent Spec link is left for parseComponentsTable's own existing "malformed Spec column" error
+  // to catch later, unchanged.
+  //
+  // Operates per-LINE, not via a global string .replace() over the whole document — same real bug
+  // this function's FTR-027 predecessor (disambiguateFileSlugs) was written to avoid: when two
+  // rows share byte-identical original Spec text, a global .replace() always rewrites the FIRST
+  // occurrence, never the specific row actually being processed.
+  function applyComponentSlugs(skeletonText, manifest) {
+    const lines = skeletonText.split('\n')
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]
+      if (!line.trim().startsWith('|')) continue
+      const cells = line.split('|').map(c => c.trim()).filter((_, idx, a) => idx > 0 && idx < a.length - 1)
+      if (cells.length < 5) continue
+      const filePath = cells[0]
+      const m = cells[4] && cells[4].match(/\(components\/([^)]+)\)/)
+      if (!m) continue // header/separator row, or a row with no Spec link at all yet
+      const slug = assignComponentSlug(manifest, filePath)
+      const escaped = m[1].replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+      lines[i] = lines[i].replace(new RegExp(`components/${escaped}`, 'g'), `components/${slug}`)
+    }
+    return lines.join('\n')
+  }
+
   // Duplicated (not imported) from tech-spec-assembler.js's own export of the same name — this
   // runtime has no `require`, so getting this via another c.command round-trip would be
   // unnecessary overhead for a parse already needed in-process to drive the per-component loop.
@@ -375,58 +487,36 @@ return c.run(meta.name, featureDir, prefix, async () => {
     return `${base}\n\nTemplate (spec/components/{fileSlug}.md):\n${componentTemplate}`
   }
 
-  // Deterministic, host-computed — never asks the model to pick unique names (same principle
-  // as materializeIndex's detailFile/status derivations in the Work Breakdown's own skeleton,
-  // FTR-020). Rewrites any colliding fileSlug's Spec-column link in place, right-to-left
-  // prepending path segments until unique.
-  //
-  // Also enforces the ".md" suffix itself, never trusting the model to have included it. The
-  // component template's own contract calls this Spec link "provisional, not final" specifically
-  // so the host can rewrite it — originally only exercised for collisions, but a real production
-  // run showed the model omits ".md" entirely a meaningful fraction of the time (confirmed: 20 of
-  // ~61 components in one real Tech-Spec skeleton), writing e.g. `components/Settings.tsx`
-  // instead of `components/Settings.tsx.md` — the host then faithfully wrote that component's
-  // Markdown CONTENT into a file literally named `Settings.tsx`. Normalized here before the
-  // collision check runs, so two rows that only differ by their original extension (already
-  // present in the Path column) still correctly collide-and-disambiguate on the normalized slug.
+  // A row's own content fingerprint — the same four fields FTR-030's row-diffing has always
+  // compared (changeType/purposeOrChange/addresses/domain), hashed instead of held onto and
+  // compared field-by-field. Stored in the manifest so the NEXT generation's diff needs nothing
+  // but this one value, not a re-parsed copy of the previous skeleton.
+  function computeRowHash(comp) {
+    return c.hash(JSON.stringify({
+      changeType: comp.changeType, purposeOrChange: comp.purposeOrChange,
+      addresses: comp.addresses, domain: comp.domain,
+    }))
+  }
+
+  // Refreshes every current row's manifest bookkeeping (slug already settled by
+  // applyComponentSlugs; this fills in rowHash and lastSeenInSkeleton) and reports, per filePath,
+  // whether its row is byte-for-byte unchanged from what the manifest held BEFORE this call — the
+  // same "did this component's own row actually change" signal FTR-030 introduced, now backed by
+  // the manifest instead of a second parse of the prior skeleton file.
   //
-  // Operates per-LINE, not via a global string .replace() over the whole document — a real bug,
-  // found by testing two colliding entries directly: when both rows share byte-identical Spec
-  // text (the whole point of a collision), a global .replace() always rewrites the FIRST
-  // occurrence, never the specific (second, third, ...) row actually being disambiguated.
-  function disambiguateFileSlugs(skeletonText) {
-    const lines = skeletonText.split('\n')
-    const seenSlugs = new Set()
-    for (let i = 0; i < lines.length; i++) {
-      const line = lines[i]
-      if (!line.trim().startsWith('|')) continue
-      const cells = line.split('|').map(c => c.trim()).filter((_, idx, a) => idx > 0 && idx < a.length - 1)
-      if (cells.length < 5) continue
-      const filePath = cells[0]
-      const m = cells[4].match(/\(components\/([^)]+)\)/)
-      if (!m) continue // header/separator row, or a row with no valid Spec link yet
-      let slug = m[1]
-      if (!slug.endsWith('.md')) {
-        const escaped = slug.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-        const normalized = `${slug}.md`
-        lines[i] = lines[i].replace(new RegExp(`components/${escaped}`, 'g'), `components/${normalized}`)
-        slug = normalized
-      }
-      if (seenSlugs.has(slug)) {
-        const segments = filePath.split('/')
-        let depth = 1
-        let candidate = slug
-        while (seenSlugs.has(candidate)) {
-          depth += 1
-          candidate = segments.slice(-depth).join('-') + '.md'
-        }
-        const escaped = slug.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-        lines[i] = lines[i].replace(new RegExp(`components/${escaped}`, 'g'), `components/${candidate}`)
-        slug = candidate
-      }
-      seenSlugs.add(slug)
+  // Called unconditionally on every generateTechSpec pass (not just when the skeleton itself was
+  // regenerated), so `lastSeenInSkeleton` stays current even on a pure per-component resume pass —
+  // a component absent from this call for one or more passes becomes identifiable as orphaned
+  // (its entry's lastSeenInSkeleton stops advancing) without any extra bookkeeping of its own.
+  function updateManifestBookkeeping(manifest, components, nowIso) {
+    const rowUnchangedByPath = new Map()
+    for (const comp of components) {
+      const prior = manifest.components[comp.filePath]
+      const rowHash = computeRowHash(comp)
+      rowUnchangedByPath.set(comp.filePath, !!prior && prior.rowHash === rowHash)
+      manifest.components[comp.filePath] = { slug: comp.fileSlug, rowHash, lastSeenInSkeleton: nowIso }
     }
-    return lines.join('\n')
+    return rowUnchangedByPath
   }
 
   // forceAll: bypasses resume-by-existence entirely, re-dispatching the skeleton and every
@@ -438,28 +528,23 @@ return c.run(meta.name, featureDir, prefix, async () => {
       (!fresh(specIndexPath) || missingSections(c.read(specIndexPath), 12).length > 0)
     const regenSkeleton = forceAll || skeletonStale || !c.exists(specIndexPath)
 
-    // FTR-030: capture the OLD component rows (keyed by fileSlug — the stable per-component
-    // identity, a Spec-link target) BEFORE the skeleton is overwritten, so a NATURALLY-triggered
-    // skeleton regen (staleness/missing, never an explicit forceAll) doesn't force EVERY component
-    // to redispatch when only a FEW rows actually changed. Real incident: hand-editing 2 of ~58
-    // rows (adding a missing AC reference) triggered a full skeleton regeneration, which — with no
-    // per-row comparison — forced ALL ~88 components to redispatch even though the vast majority
-    // of rows were byte-identical to before. Deliberately NOT captured when forceAll is true: an
-    // explicit full regen (a `--force` run, or a needsTechSpecFix revision cycle) means something
-    // was flagged wrong that per-row diffing cannot see (e.g. a missing cross-reference only
-    // visible in a component's own body) — that path keeps today's existing "regenerate
-    // everything unconditionally" behavior, unchanged.
-    const oldComponentsByFileSlug = new Map()
-    if (!forceAll && regenSkeleton && c.exists(specIndexPath)) {
+    const manifest = loadManifest()
+    // Bootstrap: a project with an existing spec/index.md but no manifest yet (upgrading onto
+    // this scheme) has Spec-links assigned by the OLD per-table-position disambiguation. Adopt
+    // those slugs as-is — never recompute/rename them — so the very first run after upgrading
+    // does not rename every already-generated component file. This also covers the common
+    // resume-only pass below (no regen at all): components are read from the EXISTING file, so
+    // their current slug is simply what updateManifestBookkeeping records.
+    if (Object.keys(manifest.components).length === 0 && c.exists(specIndexPath)) {
       try {
-        for (const comp of parseComponentsTable(c.read(specIndexPath))) oldComponentsByFileSlug.set(comp.fileSlug, comp)
-      } catch (e) { /* an unparseable old skeleton has nothing worth diffing against — treat as empty */ }
+        for (const comp of parseComponentsTable(c.read(specIndexPath))) manifest.components[comp.filePath] = { slug: comp.fileSlug }
+      } catch (e) { /* an unparseable existing skeleton has nothing to adopt — start fresh */ }
     }
 
     // 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'))
-      c.writeOutput(specIndexPath, disambiguateFileSlugs(skeleton))
+      c.writeOutput(specIndexPath, applyComponentSlugs(skeleton, manifest))
     }
 
     // 2. Structural pre-check (tech-spec-graph-checks.js, unmodified — FTR-023 — now pointed at
@@ -477,6 +562,12 @@ return c.run(meta.name, featureDir, prefix, async () => {
 
     // 3. Per-component generation, resume-by-existence, sequential
     const components = parseComponentsTable(c.read(specIndexPath))
+    // FTR-030, manifest-backed: refreshed on EVERY pass (not just when the skeleton itself was
+    // regenerated), so lastSeenInSkeleton stays current even on a pure per-component resume —
+    // see updateManifestBookkeeping's own comment. Persisted immediately, before any worker call,
+    // so a crash mid-loop never loses slug/bookkeeping state already settled this pass.
+    const rowUnchangedByPath = updateManifestBookkeeping(manifest, components, new Date().toISOString())
+    saveManifest(manifest)
     // Read once, outside the loop — the template is identical for every component in this run.
     const componentTemplate = components.length ? readTemplate('gaia-component-template.md') : null
     for (const comp of components) {
@@ -486,18 +577,23 @@ return c.run(meta.name, featureDir, prefix, async () => {
       // NEW or actually CHANGED does. `regenSkeleton` alone used to force every component to
       // redispatch unconditionally the moment the skeleton changed at all; this narrows that to
       // rows that genuinely changed, while still regenerating any row that's new or different.
-      const oldComp = oldComponentsByFileSlug.get(comp.fileSlug)
-      const rowUnchanged = !!oldComp && oldComp.filePath === comp.filePath &&
-        oldComp.changeType === comp.changeType && oldComp.purposeOrChange === comp.purposeOrChange &&
-        oldComp.addresses === comp.addresses && oldComp.domain === comp.domain
+      // Deliberately ignored when forceAll is true: an explicit full regen (a `--force` run, or a
+      // needsTechSpecFix revision cycle) means something was flagged wrong that per-row diffing
+      // cannot see (e.g. a missing cross-reference only visible in a component's own body) — that
+      // path keeps today's existing "regenerate everything unconditionally" behavior, unchanged.
+      const rowUnchanged = !forceAll && !!rowUnchangedByPath.get(comp.filePath)
       if ((!regenSkeleton || rowUnchanged) && c.exists(compPath) && isValidComponentDetail(c.read(compPath))) continue // resume: skip, no dispatch
       // 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`)

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

@@ -312,12 +312,75 @@ function buildPhaseRequirementsExcerpt(reqIndexContent, sourceUC, reqDirArg) {
   return `${reqIndexContent}\n\n${ucBodies}`
 }
 
+// Parses req/index.md's Section 7 Acceptance Criteria table. Positional, tolerating both the
+// 3-column (ID|Criterion|Related UC) and 4-column (… |Priority) shapes this lineage has used —
+// only ID and Related UC are ever read. "All UCs" is preserved verbatim; callers treat it as
+// matching every phase.
+function parseAcTableLocal(reqIndexContent) {
+  const { start, end, lines } = _findSectionRange(reqIndexContent, 7)
+  return _parseTableRows(lines, start, end)
+    .map(cells => ({ id: cells[0], relatedUC: cells[2] || '' }))
+    .filter(row => /^AC-/.test(row.id || ''))
+}
+
+// Compact one-line-per-component index: everything Section 9's own table already says about a
+// component EXCEPT its design body. Cheap (~25 tokens/row) and always safe to inline in full —
+// it is what lets a worker know a component exists (and name it in a drill-down request) without
+// paying for its body up front.
+function buildComponentIndexRows(components) {
+  return components.map(comp =>
+    `- ${comp.filePath} (${comp.changeType}, ${comp.domain}) — addresses ${comp.addresses || '—'} — ${comp.purposeOrChange || ''}`
+  ).join('\n')
+}
+
+// Cost-hardening: a worker handed only Section 9's index rows will, given Read/Glob/Grep, go read
+// the project's REAL source tree to recover the design it was not given — confirmed against real
+// runs where per-phase calls burned 36-43 turns and $2-3 each doing exactly that, with ~80% of
+// their output tokens being exploration reasoning rather than deliverable. Inlining the component
+// DESIGN bodies the host can already identify deterministically is far cheaper than letting the
+// model rediscover them. Cap is a safety valve, not the expected case.
+const PHASE_COMPONENT_MAX = 14
+function buildPhaseComponentExcerpt(phase, components, acTable, specDirArg) {
+  const sourceUC = phase.sourceUC || []
+  const phaseAcIds = new Set(acTable
+    .filter(row => /all\s+ucs/i.test(row.relatedUC) ||
+      row.relatedUC.split(',').map(s => s.trim()).some(uc => sourceUC.includes(uc)))
+    .map(row => row.id))
+  const relevant = components
+    .filter(comp => (comp.addresses || '').split(',').map(s => s.trim()).some(ac => phaseAcIds.has(ac)))
+    .slice(0, PHASE_COMPONENT_MAX)
+  if (relevant.length === 0) return null
+  return relevant.map(comp =>
+    `### ${comp.filePath}\n\n${c.read(`${specDirArg}/components/${comp.fileSlug}`)}`).join('\n\n')
+}
+
+// Cost-hardening: AGENTS.md is read in full by several agents on EVERY call purely to recover
+// build/verification commands (26-36 KB on the two real projects measured — 7-9K tokens per call,
+// paid once per task). The host extracts just the command-bearing sections instead and inlines
+// them, which measured 87-91% smaller on both. Returns null when nothing matches, so the caller
+// can fall back to the agent's own read rather than silently supplying a conventions block that
+// omits the one command the task needed.
+const AGENTS_SECTION_RE = /(build|test|verif|command|lint|compil)/i
+function buildAgentsConventions(root) {
+  const agentsPath = `${root}/AGENTS.md`
+  if (!c.exists(agentsPath)) return null
+  const lines = c.read(agentsPath).split('\n')
+  const kept = []
+  let keeping = false
+  for (const line of lines) {
+    const heading = line.match(/^(#{2,3})\s+(.*)/)
+    if (heading) keeping = AGENTS_SECTION_RE.test(heading[2])
+    if (keeping) kept.push(line)
+  }
+  return kept.length ? kept.join('\n').trim() : null
+}
+
 // 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
 // yet) — mirrors buildTaskPrompt's own "siblings" list further below, same duplicate-
 // implementation-awareness purpose, one tier up.
-function buildPhaseTaskPrompt(phase, requirementsExcerpt, techSpecSkeletonText, priorTasks, drillDownText) {
+function buildPhaseTaskPrompt(phase, requirementsExcerpt, techSpecSkeletonText, priorTasks, drillDownText, componentExcerpt, conventions) {
   const priorTasksList = priorTasks.length
     ? priorTasks.map(t => `- ${t.id}: ${t.title} — ${t.outcome} (domain: ${t.domain})`).join('\n')
     : '(none — this is the first phase generated)'
@@ -327,27 +390,38 @@ function buildPhaseTaskPrompt(phase, requirementsExcerpt, techSpecSkeletonText,
     `Tech-Spec:\n${techSpecSkeletonText}`,
     `Tasks already decided by prior phases:\n${priorTasksList}`,
   ]
+  if (conventions) parts.push(`Project build/verification conventions (from AGENTS.md — do not read that file yourself):\n${conventions}`)
+  if (componentExcerpt) parts.push(`Design detail for the components this phase's own Acceptance Criteria cover (do not go read the project's source to rediscover this):\n${componentExcerpt}`)
   if (drillDownText) parts.push(`Component detail you requested:\n${drillDownText}`)
   return parts.join('\n\n')
 }
 
-// Matches a task's own acceptanceCriteria against each component's Addresses column (the same
-// relation spec/index.md's own Section 9 table already expresses) to give the per-task worker
-// only the Tech-Spec content relevant to its own task, instead of the entire assembled spec —
-// the single largest structural token cost this feature removes. Falls back to the full
-// Components table (never zero content) when nothing matches, e.g. a purely organizational task.
+// Selects which component DESIGN BODIES a single task's worker actually needs.
+//
+// Matching purely on Acceptance Criteria (FTR-026's original rule) degrades badly on a real
+// feature: AC granularity is coarse (one real feature had 12 ACs across 51 components, with a
+// single AC cited by 14 of them), so a task citing 3 ACs pulled in 26 full design bodies —
+// measured at 106 KB average per task, 12.6 MB across one feature, for work that usually touches
+// one or two files. Narrowing to the component(s) a task actually NAMES in its own title/outcome
+// measured 11 KB average instead, and covers just over half of all tasks; the remainder fall back
+// to the AC match, capped. Section 9's index rows are always included in full regardless, so a
+// task whose real file was not matched can still see every component that exists and go read one.
+const TASK_COMPONENT_FALLBACK_MAX = 4
 function buildTaskTechSpecExcerpt(components, task, specDir, specIndexContent) {
   const acSet = new Set(task.acceptanceCriteria || [])
-  const relevant = components.filter(comp =>
+  const byAc = components.filter(comp =>
     (comp.addresses || '').split(',').map(s => s.trim()).some(acId => acSet.has(acId)))
-  if (relevant.length === 0) {
+  if (byAc.length === 0) {
     return "_No component's Addresses column cites this task's Acceptance Criteria — full " +
       'Components table below._\n\n' + specIndexContent
   }
-  return relevant.map(comp => {
-    const body = c.read(`${specDir}/components/${comp.fileSlug}`)
-    return `### ${comp.filePath}\n\n${body}`
-  }).join('\n\n')
+  const haystack = `${task.title || ''} ${task.outcome || ''}`.toLowerCase()
+  const byPath = components.filter(comp => comp.filePath && haystack.includes(comp.filePath.toLowerCase()))
+  const bodies = byPath.length ? byPath : byAc.slice(0, TASK_COMPONENT_FALLBACK_MAX)
+  const bodyText = bodies.map(comp =>
+    `### ${comp.filePath}\n\n${c.read(`${specDir}/components/${comp.fileSlug}`)}`).join('\n\n')
+  return `Every component this task's Acceptance Criteria cover (index only):\n${buildComponentIndexRows(byAc)}\n\n` +
+    `Full design detail for the component(s) this task itself names:\n${bodyText}`
 }
 
 // FTR-027: duplicates wbs-assembler.js's own _parseVerificationCommands algorithm (last
@@ -367,20 +441,30 @@ function hasVerificationCommands(content) {
 }
 
 // Compact prompt for the per-task detail-generation worker: this task's own skeleton entry,
-// the full skeleton's sibling task list (id + title + outcome only, for duplicate-
-// implementation awareness), and the Tech-Spec excerpt (FTR-026: already pre-sliced to this
-// task's own relevant component(s) by buildTaskTechSpecExcerpt, or the full legacy Tech-Spec
-// text for a feature with no spec/ directory).
-function buildTaskPrompt(index, taskId, techSpecText, taskTemplate) {
+// a sibling task list (id + title + outcome only, for duplicate-implementation awareness), and
+// the Tech-Spec excerpt (FTR-026: already pre-sliced to this task's own relevant component(s) by
+// buildTaskTechSpecExcerpt, or the full legacy Tech-Spec text for a feature with no spec/).
+//
+// Cost-hardening: the sibling list used to carry EVERY task in the feature with its full outcome
+// — 11K tokens per call on a 122-task feature, re-sent once per task, and growing quadratically
+// with feature size. Duplicate implementation is only a real risk against work that is adjacent
+// or already decided, so the list is scoped to this task's own phase plus every earlier phase;
+// a genuinely cross-phase duplicate is still caught deterministically by wb-validate.js.
+function buildTaskPrompt(index, taskId, techSpecText, taskTemplate, conventions) {
   const task = index.tasks[taskId]
+  const phaseIdx = index.phases.findIndex(p => p.taskIds.includes(taskId))
+  const inScope = new Set(index.phases.slice(0, phaseIdx + 1).flatMap(p => p.taskIds))
   const siblingList = Object.entries(index.tasks)
+    .filter(([id]) => inScope.has(id))
     .map(([id, t]) => `- ${id}: ${t.title} — ${t.outcome}`).join('\n')
-  return [
+  const parts = [
     `Task skeleton entry (restate these fields verbatim; do not re-derive them):\n${JSON.stringify({ id: taskId, ...task }, null, 2)}`,
     `Tech-Spec:\n${techSpecText}`,
-    `All tasks in this feature (for duplicate-implementation awareness):\n${siblingList}`,
-    `Template (tasks/{TASK_ID}.md):\n${taskTemplate}`,
-  ].join('\n\n')
+    `Tasks in this task's own phase and every earlier phase (for duplicate-implementation awareness):\n${siblingList}`,
+  ]
+  if (conventions) parts.push(`Project build/verification conventions (from AGENTS.md — do not read that file yourself):\n${conventions}`)
+  parts.push(`Template (tasks/{TASK_ID}.md):\n${taskTemplate}`)
+  return parts.join('\n\n')
 }
 
 const c = control
@@ -475,6 +559,13 @@ return c.run(meta.name, featureDir, prefix, async () => {
   // work-breakdown.md's own Guidelines already produce for the phases array).
   const reqIndexContentForPhases = c.read(reqIndexPath)
   const techSpecSkeletonForPhases = hasSpec ? c.read(specIndexPath) : c.read(file('Tech-Spec.md'))
+  // Computed once, outside the loop — identical for every phase, and both are pure reads.
+  const componentsForPhases = hasSpec ? parseComponentsTableLocal(c.read(specIndexPath)) : []
+  // A Requirements document without a parseable Section 7 table costs this one optimisation, not
+  // the run: fall back to supplying no component excerpt rather than failing WBS generation.
+  let acTableForPhases = []
+  if (hasReq) { try { acTableForPhases = parseAcTableLocal(reqIndexContentForPhases) } catch (e) { acTableForPhases = [] } }
+  const conventions = buildAgentsConventions(c.root)
   const taskIdToPhase = new Map()
   for (const phase of index.phases) {
     if (phase.taskIds.length > 0) {
@@ -485,9 +576,12 @@ return c.run(meta.name, featureDir, prefix, async () => {
       ? buildPhaseRequirementsExcerpt(reqIndexContentForPhases, phase.sourceUC, reqDir)
       : reqIndexContentForPhases
     const priorTasks = Object.entries(index.tasks).map(([id, t]) => ({ id, title: t.title, outcome: t.outcome, domain: t.domain }))
+    const componentExcerpt = hasSpec
+      ? buildPhaseComponentExcerpt(phase, componentsForPhases, acTableForPhases, specDir)
+      : null
 
     let phaseResult = await c.worker('gaia.agent.planner.work-breakdown-phase',
-      buildPhaseTaskPrompt(phase, reqExcerpt, techSpecSkeletonForPhases, priorTasks),
+      buildPhaseTaskPrompt(phase, reqExcerpt, techSpecSkeletonForPhases, priorTasks, null, componentExcerpt, conventions),
       { schema: PHASE_TASKS_SCHEMA, label: `work-breakdown-phase:${phase.id}` })
 
     // Bounded, single-round drill-down (FTR-028 precedent, reused unmodified from FTR-032's own
@@ -497,7 +591,7 @@ return c.run(meta.name, featureDir, prefix, async () => {
       const drillDownText = buildComponentDrillDownText(phaseNeedsComponentDetail, c.read(specIndexPath), specDir)
       if (drillDownText) {
         phaseResult = await c.worker('gaia.agent.planner.work-breakdown-phase',
-          buildPhaseTaskPrompt(phase, reqExcerpt, techSpecSkeletonForPhases, priorTasks, drillDownText),
+          buildPhaseTaskPrompt(phase, reqExcerpt, techSpecSkeletonForPhases, priorTasks, drillDownText, componentExcerpt, conventions),
           { schema: PHASE_TASKS_SCHEMA, label: `work-breakdown-phase:${phase.id}:with-drilldown` })
       }
     }
@@ -548,7 +642,7 @@ return c.run(meta.name, featureDir, prefix, async () => {
         ? buildTaskTechSpecExcerpt(components, task, specDir, c.read(specIndexPath))
         : c.read(file('Tech-Spec.md')) // legacy fallback: unchanged, full text
       const detail = await c.worker('gaia.agent.planner.work-breakdown-task',
-        buildTaskPrompt(index, taskId, techSpecExcerpt, taskTemplate), { label: `work-breakdown-task:${taskId}` })
+        buildTaskPrompt(index, taskId, techSpecExcerpt, taskTemplate, conventions), { label: `work-breakdown-task:${taskId}` })
       c.writeOutput(detailPath, detail)
       task.status = 'generated'
       c.writeOutput(indexPath, JSON.stringify(index, null, 2)) // persist status after each task