@dtlabs/ai-toolkit 0.7.0 → 0.8.0

package/.claude/agents/define-feature.md

@@ -96,6 +96,41 @@ Ask the user: **"What is the name of this feature?"** (short, descriptive, in th
 
 Example: "Supplier Onboarding" → `FTR-003-supplier-onboarding`
 
+### 1c. Create feature directory and initialize ledger
+
+Once you know the PREFIX (from 1a) and the feature slug (from 1b), do the following **before asking any grilling questions**:
+
+1. Compute the paths:
+   - `featureDir` = `docs/features/{PREFIX}-{slug}` (e.g. `docs/features/FTR-003-supplier-onboarding`)
+   - `ledgerPath` = `{featureDir}/{PREFIX}-token-ledger.json`
+
+2. Create the feature directory via Bash:
+   ```bash
+   mkdir -p {featureDir}
+   ```
+
+3. Capture the current UTC timestamp via Bash:
+   ```bash
+   started_at=$(date -u +"%Y-%m-%dT%H:%M:%SZ") && echo $started_at
+   ```
+
+4. Write the initial ledger file at `{ledgerPath}` using the Write tool with exactly this content (substitute the actual PREFIX and timestamp):
+   ```json
+   [
+     {
+       "agent": "define-feature:define",
+       "phase": "define",
+       "model": "sonnet",
+       "status": "running",
+       "phase_delta_tokens": 0,
+       "started_at": "<started_at from step 3>",
+       "completed_at": null
+     }
+   ]
+   ```
+
+The ledger records that the define-feature agent is now running. Proceed to Phase 2.
+
 ---
 
 ## Phase 2 — Grilling (only the gaps)
@@ -224,7 +259,7 @@ docs/features/{PREFIX}-{slug}/feature.md
 
 Example: `docs/features/FTR-003-supplier-onboarding/feature.md`
 
-Create the directory if it doesn't exist.
+The directory was created in Phase 1c. If for any reason it doesn't exist, create it now.
 
 ### feature.md template
 
@@ -315,6 +350,37 @@ For each entity: name, key fields (name, type, constraints), relationships.
 - Acceptance criteria must be **testable** (Given/When/Then) — for technical features, express them as observable/verifiable checks (e.g. "grep returns nothing", "build passes", "output file exists")
 - Be concrete and specific — avoid vague statements like "the system should be fast"
 
+### 4b. Finalize ledger entry
+
+After writing `feature.md`, update the ledger entry to record successful completion:
+
+1. Capture the current UTC timestamp via Bash:
+   ```bash
+   completed_at=$(date -u +"%Y-%m-%dT%H:%M:%SZ") && echo $completed_at
+   ```
+
+2. Read the ledger file at `{featureDir}/{PREFIX}-token-ledger.json` using the Read tool.
+
+3. Write the updated ledger file using the Write tool, replacing the entry's fields:
+   - `"status"`: `"done"`
+   - `"completed_at"`: the timestamp captured in step 1
+   - `"phase_delta_tokens"`: leave as `0` — token measurement is not available to the agent directly
+
+   Example final ledger content:
+   ```json
+   [
+     {
+       "agent": "define-feature:define",
+       "phase": "define",
+       "model": "sonnet",
+       "status": "done",
+       "phase_delta_tokens": 0,
+       "started_at": "<original started_at>",
+       "completed_at": "<completed_at from step 1>"
+     }
+   ]
+   ```
+
 ---
 
 ## Phase 5 — Confirm and handoff

package/.claude/agents/install-toolkit.md

@@ -251,6 +251,39 @@ COMPACT_SECTION
 
 ---
 
+## Step 6 — Bash Permission Allowlist opt-in
+
+After the Compact Instructions step, offer an opt-in to create or update `.claude/settings.local.json` in the destination project with a pre-approved Bash command allowlist.
+
+1. **Offer the opt-in** — inform the user and ask:
+
+   > "Would you like to create or update `.claude/settings.local.json` in this project with a pre-approved Bash command allowlist? This lets pm-phase3 worker agents run read-only commands (ls, git status, git log, npm test, dotnet build, etc.) without prompting you. Dangerous commands (git push, gh pr create, rm, git reset, git clean) will always require confirmation."
+   >
+   > Options: "Yes — write allowlist" / "No — skip"
+
+2. If the user selects **No**: skip silently; set `allowlist_status = "skipped (user said No)"`.
+
+3. If the user selects **Yes**:
+
+   a. **Invoke the merge CLI** from the toolkit root directory:
+      ```bash
+      node bin/cli.js merge-allowlist "{dest}"
+      ```
+      Capture stdout and the exit code.
+      - If exit code is non-zero: set `allowlist_status = "failed — see above"` and continue to Step 7 (allowlist is advisory, not blocking).
+      - If exit code is 0: the stdout line will be one of:
+        - `Allowlist: written` → set `allowlist_status = "written"`
+        - `Allowlist: merged (N rules preserved)` → set `allowlist_status = "merged (N rules preserved)"`
+        - `Allowlist: reset` → set `allowlist_status = "reset (file was malformed)"`
+
+   b. **Check and update `.gitignore`**:
+      ```bash
+      node bin/cli.js update-gitignore "{dest}"
+      ```
+      This ensures `.claude/settings.local.json` is gitignored in the destination project. The CLI is idempotent — it appends the line only if it is not already present.
+
+---
+
 ## Step 7 — Report
 
 ```
@@ -262,6 +295,7 @@ Modified/kept:        N  (user chose to keep existing version)
 Unchanged (same):    N  (skipped silently)
 Spawn depth: ✅ CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=2+ present / ⚠️ MISSING — see action above
 Compact instructions: {compact_instructions_status}
+Allowlist: {allowlist_status}
 ──────────────────────────────────────────────────
 Next steps:
   1. Run /init-agents to generate AGENTS.md for this project

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

@@ -9,6 +9,26 @@ export const meta = {
   ],
 }
 
+// ── Ledger helper functions ───────────────────────────────────────────────────
+
+async function appendLedgerEntry(featureDir, prefix, entry) {
+  const ledgerPath = `${featureDir}/${prefix}-token-ledger.json`
+  const entryJson = JSON.stringify(entry)
+  await agent(
+    `Append a JSON object to the ledger array at: ${ledgerPath}\n\n1. Read the file. If it does not exist or cannot be parsed as a JSON array, start with [].\n2. Push this object onto the array: ${entryJson}\n3. Write the full array back (JSON, 2-space indent). Return no output.`,
+    { label: 'append-ledger', phase: 'Requirements', model: 'haiku' }
+  )
+}
+
+async function updateLedgerEntry(featureDir, prefix, agentKey, updates) {
+  const ledgerPath = `${featureDir}/${prefix}-token-ledger.json`
+  const updatesJson = JSON.stringify(updates)
+  await agent(
+    `Update an entry in the ledger array at: ${ledgerPath}\n\n1. Read the file. If it does not exist or cannot be parsed as a JSON array, do nothing.\n2. Search from the end for the last entry where agent === "${agentKey}".\n3. If found, merge these fields into that entry: ${updatesJson}\n4. Write the full array back (JSON, 2-space indent). Return no output.\n5. If not found, do nothing.`,
+    { label: 'update-ledger', phase: 'Requirements', model: 'haiku' }
+  )
+}
+
 // ── Parse args ────────────────────────────────────────────────────────────────
 // args is the raw prompt string: "<path-to-feature.md> [--force]"
 const featurePath = args.split(/\s+/)[0]
@@ -70,6 +90,16 @@ const { prefix, feature_dir } = discoveryResult
 log(`Prefix: ${prefix} | Dir: ${feature_dir}`)
 log(`needs_requirements=${discoveryResult.needs_requirements} needs_tech_spec=${discoveryResult.needs_tech_spec}`)
 
+// ── Ensure ledger file exists (US-02-T02) ─────────────────────────────────────
+// If define-feature was not used, the ledger file will not exist yet.
+// Touch it with an empty array so appendLedgerEntry can always assume a valid base.
+const ledgerFilePath = `${feature_dir}/${prefix}-token-ledger.json`
+await agent(
+  `Check whether the file ${ledgerFilePath} exists.\n\n1. Try to read the file using the Read tool.\n2. If the file does NOT exist: write it now using the Write tool with contents: []\n3. If the file already exists and is a valid JSON array: do nothing.\n4. If the file exists but is not valid JSON: overwrite it with: []\n5. Return no output.`,
+  { label: 'ensure-ledger', phase: 'Discovery', model: 'haiku' }
+)
+log(`Ledger ensured at ${ledgerFilePath}`)
+
 // ── generate-requirements ─────────────────────────────────────────────────────
 phase('Requirements')
 
@@ -77,9 +107,25 @@ const tokenLedger = []
 const errors      = []
 
 if (discoveryResult.needs_requirements) {
+  const reqKey = 'generate-requirements:phase1'
+  const reqStartedAt = new Date().toISOString()
+  await appendLedgerEntry(feature_dir, prefix, {
+    agent: reqKey,
+    phase: 'phase1',
+    model: 'haiku',
+    status: 'running',
+    phase_delta_tokens: 0,
+    started_at: reqStartedAt,
+    completed_at: null,
+  })
   const beforeReq = budget.spent()
   const reqResult = await agent(featurePath, { agentType: 'generate-requirements', label: 'generate-requirements', phase: 'Requirements' })
   const reqTokens = budget.spent() - beforeReq
+  await updateLedgerEntry(feature_dir, prefix, reqKey, {
+    status: 'done',
+    completed_at: new Date().toISOString(),
+    phase_delta_tokens: reqTokens,
+  })
   tokenLedger.push({ agent: 'generate-requirements', model: 'haiku', phase_delta_tokens: reqTokens })
   log(`generate-requirements done — phase delta: ${reqTokens} tokens`)
 } else {
@@ -90,9 +136,25 @@ if (discoveryResult.needs_requirements) {
 phase('Tech-Spec')
 
 if (discoveryResult.needs_tech_spec) {
+  const specKey = 'generate-tech-spec:phase1'
+  const specStartedAt = new Date().toISOString()
+  await appendLedgerEntry(feature_dir, prefix, {
+    agent: specKey,
+    phase: 'phase1',
+    model: 'haiku',
+    status: 'running',
+    phase_delta_tokens: 0,
+    started_at: specStartedAt,
+    completed_at: null,
+  })
   const beforeSpec = budget.spent()
   const specResult = await agent(featurePath, { agentType: 'generate-tech-spec', label: 'generate-tech-spec', phase: 'Tech-Spec' })
   const specTokens = budget.spent() - beforeSpec
+  await updateLedgerEntry(feature_dir, prefix, specKey, {
+    status: 'done',
+    completed_at: new Date().toISOString(),
+    phase_delta_tokens: specTokens,
+  })
   tokenLedger.push({ agent: 'generate-tech-spec', model: 'haiku', phase_delta_tokens: specTokens })
   log(`generate-tech-spec done — phase delta: ${specTokens} tokens`)
 } else {
@@ -108,9 +170,25 @@ const MAX_CYCLES = 3
 
 for (let cycle = 1; cycle <= MAX_CYCLES; cycle++) {
   log(`validate-feature-docs cycle ${cycle}`)
+  const valKey = `validate-feature-docs:phase1:cycle${cycle}`
+  const valStartedAt = new Date().toISOString()
+  await appendLedgerEntry(feature_dir, prefix, {
+    agent: valKey,
+    phase: 'phase1',
+    model: 'haiku',
+    status: 'running',
+    phase_delta_tokens: 0,
+    started_at: valStartedAt,
+    completed_at: null,
+  })
   const beforeVal = budget.spent()
   const valResult = await agent(featurePath, { agentType: 'validate-feature-docs', label: `validate-feature-docs (cycle ${cycle})`, phase: 'Validation' })
   const valTokens = budget.spent() - beforeVal
+  await updateLedgerEntry(feature_dir, prefix, valKey, {
+    status: 'done',
+    completed_at: new Date().toISOString(),
+    phase_delta_tokens: valTokens,
+  })
   tokenLedger.push({ agent: `validate-feature-docs (cycle ${cycle})`, model: 'haiku', phase_delta_tokens: valTokens })
 
   // valResult is the agent's text output — check for gap indicators

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

@@ -7,15 +7,54 @@ export const meta = {
   ],
 }
 
+// ── Ledger helper functions ───────────────────────────────────────────────────
+// Route all ledger I/O through agent() — fs is not available in the workflow runtime.
+// Mirrors appendLedgerEntry / updateLedgerEntry from bin/cli.js (same contract).
+
+async function appendLedgerEntry(featureDir, prefix, entry) {
+  const ledgerPath = `${featureDir}/${prefix}-token-ledger.json`
+  const entryJson = JSON.stringify(entry)
+  await agent(
+    `Append a JSON object to the ledger array at: ${ledgerPath}\n\n1. Read the file. If it does not exist or cannot be parsed as a JSON array, start with [].\n2. Push this object onto the array: ${entryJson}\n3. Write the full array back (JSON, 2-space indent). Return no output.`,
+    { label: 'append-ledger', phase: 'Work Breakdown', model: 'haiku' }
+  )
+}
+
+async function updateLedgerEntry(featureDir, prefix, agentKey, updates) {
+  const ledgerPath = `${featureDir}/${prefix}-token-ledger.json`
+  const updatesJson = JSON.stringify(updates)
+  await agent(
+    `Update an entry in the ledger array at: ${ledgerPath}\n\n1. Read the file. If it does not exist or cannot be parsed as a JSON array, do nothing.\n2. Search from the end for the last entry where agent === "${agentKey}".\n3. If found, merge these fields into that entry: ${updatesJson}\n4. Write the full array back (JSON, 2-space indent). Return no output.\n5. If not found, do nothing.`,
+    { label: 'update-ledger', phase: 'Work Breakdown', model: 'haiku' }
+  )
+}
+
+// ── Parse args ────────────────────────────────────────────────────────────────
+
 // args: "<path-to-feature.md>"
 const featurePath = (typeof args === 'string' ? args : '').trim().split(/\s+/)[0]
 
+// Derive feature directory and prefix early (needed for ledger writes before metrics agent runs)
+const featureDir  = featurePath.replace(/\/[^/]+$/, '')
+const prefixMatch = featureDir.match(/([A-Z]+-\d+)/)
+const prefix      = prefixMatch ? prefixMatch[1] : 'FTR-000'
+
 // ── generate-work-breakdown ───────────────────────────────────────────────────
 phase('Work Breakdown')
 
 const tokenLedger = []
 
 log(`Running generate-work-breakdown for ${featurePath}`)
+const wbStartedAt = new Date().toISOString()
+await appendLedgerEntry(featureDir, prefix, {
+  agent: 'generate-work-breakdown:phase2',
+  phase: 'phase2',
+  model: 'haiku',
+  status: 'running',
+  phase_delta_tokens: 0,
+  started_at: wbStartedAt,
+  completed_at: null,
+})
 const beforeWB = budget.spent()
 await agent(featurePath, {
   agentType: 'generate-work-breakdown',
@@ -23,6 +62,11 @@ await agent(featurePath, {
   phase:     'Work Breakdown',
 })
 const wbTokens = budget.spent() - beforeWB
+await updateLedgerEntry(featureDir, prefix, 'generate-work-breakdown:phase2', {
+  status: 'done',
+  completed_at: new Date().toISOString(),
+  phase_delta_tokens: wbTokens,
+})
 tokenLedger.push({ agent: 'generate-work-breakdown', model: 'haiku', phase_delta_tokens: wbTokens })
 log(`generate-work-breakdown done — phase delta: ${wbTokens} tokens`)
 
@@ -48,7 +92,34 @@ const PARSE_SCHEMA = {
   required: ['prefix', 'user_stories', 'total_tasks', 'work_breakdown_path'],
 }
 
-const phase1Tokens = wbTokens  // tokens consumed by this phase so far
+// ── Load token pricing ────────────────────────────────────────────────────────
+// Pricing config is read inline (haiku agent) so it survives path-agnostic installs.
+// Cost formula: tokens * (0.8 * input + 0.2 * output) / 1_000_000 * usd_to_eur
+// (80/20 input/output split — no per-agent breakdown available in the ledger)
+const pricingRaw = await agent(
+  `Read the file docs/token-pricing.json and return its raw JSON contents as a string, nothing else.`,
+  { label: 'read-pricing', phase: 'Effort Estimate', model: 'haiku' }
+)
+let pricing = null
+try { pricing = JSON.parse(typeof pricingRaw === 'string' ? pricingRaw.trim() : '{}') } catch (_) {}
+
+function tokenCostEur(tokens, model) {
+  if (!pricing || !pricing.models) return null
+  const m = pricing.models[model] || pricing.models['sonnet']
+  const usdPer1M = 0.8 * m.input_per_1m_usd + 0.2 * m.output_per_1m_usd
+  return (tokens * usdPer1M / 1_000_000) * (pricing.usd_to_eur || 1)
+}
+
+function formatEur(val) {
+  if (val === null || val === undefined) return '—'
+  return '€' + val.toFixed(4)
+}
+
+// NOTE: pm-phase2 is a separate workflow and does NOT receive pm-phase1's token ledger,
+// so the real Phase 1 actuals (generate-requirements/tech-spec/validate) are unknown here.
+// They are written as "—" placeholders below and filled later by the orchestrator (the
+// implement-feature skill Step 7, which holds all three phase ledgers). Do NOT reuse wbTokens
+// as a stand-in for Phase 1 — that mislabels Phase 2's tokens as Phase 1's.
 
 const metrics = await agent(
   `You have four tasks:
@@ -113,46 +184,52 @@ Write {feature_dir}/{PREFIX}-Token-Estimate.md with this format:
 
 ## Phase 1 — Documentation (Actuals)
 
-| Agent | Task | Model | Tokens Est. | Tokens Actual |
-|-------|------|-------|------------|--------------|
-| generate-requirements | Generate requirements from feature.md | haiku | — | {phase1_req_tokens} |
-| generate-tech-spec | Generate tech spec from feature.md | haiku | — | {phase1_spec_tokens} |
-| validate-feature-docs | Validate requirements + tech spec | haiku | — | {phase1_val_tokens} |
-| **Phase 1 total** | | | **—** | **${phase1Tokens}** |
+Phase 1 ran in a separate workflow (pm-phase1); its per-agent token actuals are filled in
+by the orchestrator after implementation. Leave the Tokens Actual cells as "—" here.
+
+| Agent | Task | Model | Tokens Est. | Est. cost € | Tokens Actual | Actual cost € |
+|-------|------|-------|------------|------------|--------------|--------------|
+| generate-requirements | Generate requirements from feature.md | haiku | — | — | — | — |
+| generate-tech-spec | Generate tech spec from feature.md | haiku | — | — | — | — |
+| validate-feature-docs | Validate requirements + tech spec | haiku | — | — | — | — |
+| **Phase 1 total** | | | **—** | **—** | **—** | **—** |
 
 ## Phase 2 — Work Breakdown (Actuals)
 
-| Agent | Task | Model | Tokens Est. | Tokens Actual |
-|-------|------|-------|------------|--------------|
-| generate-work-breakdown | Generate work breakdown from docs | haiku | — | {wbTokens from above} |
-| **Phase 2 total** | | | **—** | **{wbTokens from above}** |
+| Agent | Task | Model | Tokens Est. | Est. cost € | Tokens Actual | Actual cost € |
+|-------|------|-------|------------|------------|--------------|--------------|
+| generate-work-breakdown | Generate work breakdown from docs | haiku | — | — | {wbTokens from above} | ${formatEur(tokenCostEur(wbTokens, 'haiku'))} |
+| **Phase 2 total** | | | **—** | **—** | **{wbTokens from above}** | **${formatEur(tokenCostEur(wbTokens, 'haiku'))}** |
 
 ## Phase 3 — Implementation (Estimates)
 
 Estimates based on {total_tasks} tasks ({domain_breakdown}), {user_stories} User Stories.
 Baseline: ~15,000 tokens/BE task, ~8,000/TEST task, ~5,000/INFRA task.
 
-| Agent | Task | Model | Tokens Est. | Tokens Actual |
-|-------|------|-------|------------|--------------|
-| developer-backend | Implement BE/INFRA tasks | sonnet | {estimated: be_tasks * 15000 + infra_tasks * 5000} | — |
-| developer-testing | Implement TEST tasks | sonnet | {estimated: test_tasks * 8000} | — |
-| review-solution (×{user_stories}) | Architect review per US | sonnet | {estimated: user_stories * 8000} | — |
-| remediation | Fix review issues | sonnet | ~10,000 | — |
-| pr-and-registry | Push branch, create PR | sonnet | ~5,000 | — |
-| write-actuals | Update Token/Effort Estimate | sonnet | ~3,000 | — |
-| **Phase 3 total** | | | **{sum of phase 3 estimates}** | **—** |
+| Agent | Task | Model | Tokens Est. | Est. cost € | Tokens Actual | Actual cost € |
+|-------|------|-------|------------|------------|--------------|--------------|
+| developer-backend | Implement BE/INFRA tasks | sonnet | {estimated: be_tasks * 15000 + infra_tasks * 5000} | {cost for that estimate, sonnet} | — | — |
+| developer-testing | Implement TEST tasks | sonnet | {estimated: test_tasks * 8000} | {cost for that estimate, sonnet} | — | — |
+| review-solution (×{user_stories}) | Architect review per US | sonnet | {estimated: user_stories * 8000} | {cost for that estimate, sonnet} | — | — |
+| remediation | Fix review issues | sonnet | ~10,000 | {cost for 10000, sonnet} | — | — |
+| pr-and-registry | Push branch, create PR | sonnet | ~5,000 | {cost for 5000, sonnet} | — | — |
+| write-actuals | Update Token/Effort Estimate | sonnet | ~3,000 | {cost for 3000, sonnet} | — | — |
+| **Phase 3 total** | | | **{sum of phase 3 token estimates}** | **{sum of phase 3 cost estimates}** | **—** | **—** |
+
+For the "Est. cost €" column in Phase 3: use the formula tokens * (0.8 * 3.00 + 0.2 * 15.00) / 1_000_000 * ${pricing ? pricing.usd_to_eur : 0.92} for sonnet rows. Round to 4 decimal places, prefix with €.
 
 ## Grand Total
 
-| Phase | Tokens Est. | Tokens Actual |
-|-------|------------|--------------|
-| Phase 1 — Documentation | — | ${phase1Tokens} |
-| Phase 2 — Work Breakdown | — | {wbTokens from above} |
-| Phase 3 — Implementation | {sum of phase 3 estimates} | — |
-| **Total** | **{sum of phase 3 estimates}** | **{phase1Tokens + wbTokens} (partial)** |
+| Phase | Tokens Est. | Est. cost € | Tokens Actual | Actual cost € |
+|-------|------------|------------|--------------|--------------|
+| Phase 1 — Documentation | — | — | — (filled by orchestrator) | — |
+| Phase 2 — Work Breakdown | — | — | {wbTokens from above} | ${formatEur(tokenCostEur(wbTokens, 'haiku'))} |
+| Phase 3 — Implementation | {sum of phase 3 token estimates} | {sum of phase 3 cost estimates} | — | — |
+| **Total** | **{sum of phase 3 token estimates}** | **{sum of phase 3 cost estimates}** | **{wbTokens} (partial)** | **${formatEur(tokenCostEur(wbTokens, 'haiku'))} (partial)** |
 
 ---
 *Actuals will be appended by pm-phase3 after implementation completes.*
+*Cost assumes 80% input / 20% output token split. Pricing: sonnet $3.00/$15.00 per 1M, haiku $0.80/$4.00 per 1M (USD). Rate: $1 = €${pricing ? pricing.usd_to_eur : '0.92'} (${pricing ? pricing.usd_to_eur_date : 'see docs/token-pricing.json'}).*
 
 TASK 4 — Set return values.
 Set effort_estimate_path to the full path of the written Effort-Estimate.md.

package/.claude/workflows/pm-phase3.js

@@ -425,12 +425,19 @@ const persistedLedgerRaw = await agent(
 try {
   const persisted = JSON.parse(typeof persistedLedgerRaw === 'string' ? persistedLedgerRaw.trim() : '[]')
   if (Array.isArray(persisted)) {
-    const seen = new Set(tokenLedger.map(e => e.agent))
+    const inMemoryByAgent = new Map(tokenLedger.map((e, i) => [e.agent, i]))
     for (const entry of persisted) {
-      if (entry && entry.agent && !seen.has(entry.agent)) {
+      if (!entry || !entry.agent) continue
+      const idx = inMemoryByAgent.get(entry.agent)
+      if (idx === undefined) {
+        // entry exists on disk but not in memory — recover it (e.g. from a prior interrupted run)
         tokenLedger.push(entry)
-        seen.add(entry.agent)
+        inMemoryByAgent.set(entry.agent, tokenLedger.length - 1)
         log(`Recovered ledger entry from disk: ${entry.agent} (${entry.phase_delta_tokens} tokens)`)
+      } else if (tokenLedger[idx].phase_delta_tokens === 0 && (entry.phase_delta_tokens || 0) > 0) {
+        // in-memory entry has delta=0 (cached agent on resume) but disk has real data — prefer disk
+        tokenLedger[idx] = entry
+        log(`Restored real token count from disk: ${entry.agent} (${entry.phase_delta_tokens} tokens)`)
       }
     }
   }
@@ -440,6 +447,44 @@ try {
 
 const totalPhase3Tokens = tokenLedger.reduce((s, e) => s + (e.phase_delta_tokens || 0), 0)
 
+// ── Load token pricing for cost columns ──────────────────────────────────────
+const pricingRaw3 = await agent(
+  `Read the file docs/token-pricing.json and return its raw JSON contents as a string, nothing else.`,
+  { label: 'read-pricing', phase: 'Actuals', model: 'haiku' }
+)
+let pricing3 = null
+try { pricing3 = JSON.parse(typeof pricingRaw3 === 'string' ? pricingRaw3.trim() : '{}') } catch (_) {}
+
+function tokenCostEur3(tokens, model) {
+  if (!pricing3 || !pricing3.models) return null
+  const m = pricing3.models[model] || pricing3.models['sonnet']
+  const usdPer1M = 0.8 * m.input_per_1m_usd + 0.2 * m.output_per_1m_usd
+  return (tokens * usdPer1M / 1_000_000) * (pricing3.usd_to_eur || 1)
+}
+
+function formatEur3(val) {
+  if (val === null || val === undefined) return '—'
+  return '€' + val.toFixed(4)
+}
+
+// Aggregate the per-agent ledger into per-role totals so the actuals line up with the
+// per-role estimate rows pm-phase2 wrote (developer-backend, developer-testing,
+// review-solution, pr-and-registry, write-actuals, plus final-test-run). Precomputing
+// here keeps the write-actuals agent from having to reason about grouping.
+const roleTotals = {}
+const roleModels = {}
+for (const e of tokenLedger) {
+  const role = String(e.agent).split(':')[0]
+  roleTotals[role] = (roleTotals[role] || 0) + (e.phase_delta_tokens || 0)
+  roleModels[role] = e.model || 'sonnet'
+}
+const roleRows = Object.entries(roleTotals)
+  .map(([role, tok]) => `| ${role} | ${tok} | ${formatEur3(tokenCostEur3(tok, roleModels[role]))} |`)
+  .join('\n')
+const totalPhase3CostEur = formatEur3(
+  Object.entries(roleTotals).reduce((s, [role, tok]) => s + (tokenCostEur3(tok, roleModels[role]) || 0), 0)
+)
+
 const ACTUALS_SCHEMA = {
   type: 'object',
   properties: {
@@ -462,30 +507,50 @@ ${JSON.stringify(tokenLedger, null, 2)}
 
 Total tokens consumed by pm-phase3 workflow: ${totalPhase3Tokens} (exact, from budget tracking)
 
-TASK 1 — Append actuals to ${prefix}-Token-Estimate.md:
-Find the file in the feature directory. If it does not exist, create it.
+TASK 1 — Fill in the Phase 3 actuals in ${prefix}-Token-Estimate.md IN PLACE.
+Read the file in the feature directory first (it was written by pm-phase2 and already contains
+Phase 1/Phase 2 actuals and the Phase 3 estimate table). If it does not exist, create it.
 
-Append this section at the end of the file:
+Do NOT append a second Phase 3 table. Instead:
 
----
+1. Locate the existing "## Phase 3 — Implementation (Estimates)" section. Replace its heading
+   with "## Phase 3 — Implementation (Est. vs Actual, by role)" and REPLACE its table with the
+   per-role reconciliation below — filling the "Tokens Actual" and "Actual cost €" columns of the
+   existing per-role estimate rows (keep the existing Tokens Est. and Est. cost € values; add a Delta column):
 
-## Phase 3 — Implementation (Actuals)
+| Role | Model | Tokens Actual | Actual cost € |
+|------|-------|--------------|--------------|
+${roleRows}
+| **Phase 3 total** | | **${totalPhase3Tokens}** | **${totalPhase3CostEur}** |
 
-> Phase totals are exact measurements from budget tracking.
-> Per-agent values are exact where each agent ran separately; proportional where merged.
+   Match each existing estimate row (developer-backend, developer-testing, review-solution,
+   remediation, pr-and-registry, write-actuals) to the actual role total above by name, write the
+   actual into its "Tokens Actual" and "Actual cost €" cells, and compute Delta = Actual − Est (tokens).
+   Roles present in the actuals but absent from the estimate rows (e.g. final-test-run) get a new row with Est. = —.
 
-| Agent | Phase | Model | Tokens Est. | Tokens Actual |
-|-------|-------|-------|------------|--------------|
-${tokenLedger.map(e => `| ${e.agent} | — | ${e.model} | — | ${e.phase_delta_tokens} |`).join('\n')}
-| **Phase 3 total** | | | **—** | **${totalPhase3Tokens}** |
+2. Immediately after that table, add the per-agent detail as a sub-table (source of truth):
 
-## Grand Total (updated)
+### Phase 3 — per-agent detail (actuals)
 
-| Phase | Tokens Est. | Tokens Actual |
-|-------|------------|--------------|
-| Phase 1 — Documentation | — | *(see above)* |
-| Phase 2 — Work Breakdown | — | *(see above)* |
-| Phase 3 — Implementation | *(see above)* | ${totalPhase3Tokens} |
+| Agent | Model | Tokens Actual | Actual cost € |
+|-------|-------|--------------|--------------|
+${tokenLedger.map(e => `| ${e.agent} | ${e.model} | ${e.phase_delta_tokens} | ${formatEur3(tokenCostEur3(e.phase_delta_tokens, e.model))} |`).join('\n')}
+| **Detail total** | | **${totalPhase3Tokens}** | **${totalPhase3CostEur}** |
+
+3. Update the existing "## Grand Total" table. Read the Phase 1 and Phase 2 actual totals from
+   the top of THIS SAME file (the "Phase 1 total" and "Phase 2 total" rows already present) and
+   copy them verbatim — never the literal text "(see above)". If a value there is "—" (Phase 1 is
+   written as a placeholder by pm-phase2 and filled later by the orchestrator), keep it as "—";
+   do NOT invent a number. The table must read:
+
+| Phase | Tokens Est. | Est. cost € | Tokens Actual | Actual cost € | Delta (tokens) |
+|-------|------------|------------|--------------|--------------|---------------|
+| Phase 1 — Documentation | — | — | {Phase 1 total from this file, or — if placeholder} | — | — |
+| Phase 2 — Work Breakdown | — | — | {Phase 2 total from this file} | {Phase 2 cost from this file} | — |
+| Phase 3 — Implementation | {existing Phase 3 estimate total} | {existing Phase 3 est. cost} | ${totalPhase3Tokens} | ${totalPhase3CostEur} | {Actual − Est} |
+| **Total** | **{sum of numeric Est}** | **{sum of numeric Est. cost}** | **{sum of numeric Actual}** | **{sum of numeric Actual cost}** | **{Actual − Est}** |
+
+4. Append (or update if present) the Implementation Summary section:
 
 ## Implementation Summary
 
@@ -495,6 +560,8 @@ ${tokenLedger.map(e => `| ${e.agent} | — | ${e.model} | — | ${e.phase_delta_
 | US passed | ${usPassed.join(', ') || 'N/A'} |
 | US escalated | ${usEscalated.join(', ') || 'none'} |
 
+Remove the stale "*Actuals will be appended by pm-phase3...*" footer line if it is still present.
+
 TASK 2 — Update actuals in ${prefix}-Effort-Estimate.md:
 Find the file in the feature directory. Read the existing Per-Phase Breakdown table and update the "Actual Agent" column for each phase that was implemented. Use the token ledger to infer which phases completed:
 - Phases in usPassed: ${usPassed.join(', ') || 'none'} — mark Actual Agent as completed (write the wall-clock duration if available, otherwise write "done (agent)")
@@ -558,6 +625,17 @@ ${phase3Events}`,
   { label: 'finalize-process-log', phase: 'Actuals' }
 )
 
+await agent(
+  `Commit the actuals files for this feature delivery run.
+
+Run these exact git commands in the repository root:
+  git add "${featureDir3}/${prefix}-Token-Estimate.md" "${featureDir3}/${prefix}-Effort-Estimate.md" "${featureDir3}/${prefix}-process-log.txt"
+  git commit -m "docs(${prefix}): add token/effort actuals and process log"
+
+If there is nothing to commit (all files already committed), that is fine — report success.`,
+  { label: 'commit-actuals', phase: 'Actuals' }
+)
+
 return {
   pr_url:       prResult.pr_url,
   token_ledger: tokenLedger,