@dtlabs/ai-toolkit 0.24.1 → 0.24.3

package/CHANGELOG.md

@@ -1,4 +1,25 @@
 ## 0.1.4 (2026-07-21)
+## [0.24.3](https://github.com/dtlab-tech/ai-toolkit/compare/v0.24.2...v0.24.3) (2026-10-27)
+
+
+### Bug Fixes
+
+* don't fail a worker call over a read-only permission denial ([1b4c521](https://github.com/dtlab-tech/ai-toolkit/commit/1b4c5217b42e9c9dcb74c9bbe60f209522644f9c))
+* **workflow-control:** don't fail a worker call over a read-only permission denial ([fb283c6](https://github.com/dtlab-tech/ai-toolkit/commit/fb283c6a0f44f56d0ca152bcf84bf81c1ca10125))
+
+## [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)
 
 

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');
@@ -225,10 +230,27 @@ function createControl(options) {
       tokenLedger.push({ agent: identity.nativeName, model: definition.model,
         phase_delta_tokens: measuredTokens, usage: result.result?.usage || null, evidence_path: evidence.file });
       evidence.save({ response: result, attempts });
+      // A denial on a read-only tool (Read/Glob/Grep) means the agent couldn't fetch some EXTRA
+      // context — a real, recurring pattern where a path the model constructs itself (e.g. a
+      // single leading backslash with no drive letter) resolves outside the project directory
+      // and is correctly denied. Confirmed via production evidence twice, on two different
+      // paths: the agent recovers and still produces a complete, structurally valid result, which
+      // this unconditional check threw away anyway, wasting the entire call and forcing a resume.
+      // Any OTHER tool (Write/Edit/Bash/...) stays an immediate, unconditional failure — a denial
+      // there is a near-miss on a real side effect, not a missed read, and must never be silently
+      // tolerated regardless of what the rest of the response looks like.
+      const READ_ONLY_DENIAL_TOOLS = new Set(['Read', 'Glob', 'Grep'])
       const denials = result.result?.permission_denials;
       if (Array.isArray(denials) && denials.length) {
-        const tools = [...new Set(denials.map(d => d.tool_name || 'unknown'))].join(', ');
-        throw new Error('Worker permission denied: ' + id + '; tools: ' + tools);
+        const nonReadOnly = denials.filter(d => !READ_ONLY_DENIAL_TOOLS.has(d.tool_name));
+        if (nonReadOnly.length) {
+          const tools = [...new Set(nonReadOnly.map(d => d.tool_name || 'unknown'))].join(', ');
+          throw new Error('Worker permission denied: ' + id + '; tools: ' + tools);
+        }
+        // Read-only denial(s) only: fall through to the normal result-validity checks below —
+        // an agent that actually proceeded with missing context will still fail there (a bad
+        // exitCode/is_error, or the caller's own downstream structural validation), the same way
+        // it would if no denial had ever happened.
       }
       if (result.exitCode !== 0 || result.parseError || result.timedOut ||
           !result.result || result.result.is_error !== false) {
@@ -361,6 +383,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.1",
+  "version": "0.24.3",
   "description": "AI Toolkit — reusable agents and procedures for developers to build AI-powered applications.",
   "files": [
     "docs/",

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,7 +1,7 @@
 ---
 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
 ---
 
@@ -28,15 +28,17 @@ 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.
 
 ---
 
@@ -83,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>`

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

@@ -129,7 +129,7 @@ return c.run(meta.name, featureDir, prefix, async () => {
   // 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')
@@ -243,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.
@@ -397,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
@@ -460,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
@@ -499,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) {
@@ -508,10 +577,11 @@ 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,

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