@dtlabs/ai-toolkit 0.11.0 → 0.12.0

package/src/claude/scripts/wb-render.js

@@ -105,6 +105,38 @@ function sanitizeField(str) {
     .trim()
 }
 
+// ── Verification-command helpers (LOSSLESS — never sanitized) ─────────────────
+//
+// Verification commands are executable and MUST survive verbatim: operators like
+// `||`, shell pipes `|`, and regex alternations `grep -E 'a|b|c'` are destroyed by
+// sanitizeField (which maps `|` → space to protect table/CSV column structure).
+// These commands are therefore rendered in a dedicated section as fenced code
+// blocks whose content is byte-equivalent to the source JSON. The task table shows
+// only a reference (a count + anchor link), never a sanitized copy of a command.
+
+function getVerificationCommands(task) {
+  const v = task && (task.verificationCommands ?? task.verification?.commands)
+  return Array.isArray(v) ? v : []
+}
+
+// Stable, deterministic HTML anchor id for a task's authoritative detail block.
+// The summary table links here; the "Task Details" section renders every field.
+function taskAnchor(id) {
+  const s = typeof id === 'string' ? id : String(id ?? '')
+  return 'task-' + s.replace(/[^A-Za-z0-9_-]/g, '-')
+}
+
+// Render a single command inside a fenced code block, byte-equivalent to `cmd`.
+// The fence length is chosen to exceed the longest backtick run in the content so a
+// command that itself contains backticks can never prematurely close the fence.
+function fencedCommandBlock(cmd) {
+  const s = typeof cmd === 'string' ? cmd : String(cmd ?? '')
+  const runs = s.match(/`+/g) || []
+  const maxRun = runs.reduce((m, r) => Math.max(m, r.length), 0)
+  const fence = '`'.repeat(Math.max(3, maxRun + 1))
+  return `${fence}\n${s}\n${fence}`
+}
+
 function buildCommitSubject(task) {
   if (!task.commit || typeof task.commit !== 'object') {
     return 'chore: implement task'
@@ -189,8 +221,15 @@ function renderMarkdown(wb, prefix, phaseDepsMap) {
     const est      = mins !== null ? String(mins) : '—'
     const depArr   = Array.isArray(task.dependsOn) && task.dependsOn.length > 0 ? task.dependsOn : null
     const deps     = depArr ? depArr.join(', ') : '—'
-    const verifArr = task.verificationCommands ?? task.verification?.commands ?? []
-    const verif    = verifArr.length > 0 ? sanitizeField(verifArr.join('; ')) : '—'
+    // The summary table is a digest only. Verification commands are NOT rendered
+    // in-table (sanitizeField would destroy their operators). The cell links to the
+    // authoritative per-task "Task Details" section, which carries every field
+    // (outcome, acceptance criteria, estimates, grouping rationale, commit, and the
+    // lossless verification commands). See renderTaskDetails / fencedCommandBlock.
+    const verifCmds = getVerificationCommands(task)
+    const verif     = verifCmds.length > 0
+      ? `${verifCmds.length} cmd — [details](#${taskAnchor(task.id)})`
+      : `[details](#${taskAnchor(task.id)})`
     return `| ${id} | ${title} | ${outcome} | ${domain} | ${est} | ${deps} | ${verif} |`
   }
 
@@ -263,6 +302,66 @@ function renderMarkdown(wb, prefix, phaseDepsMap) {
     }
   }
 
+  // ── Task Details (AUTHORITATIVE) ──
+  // The summary tables above are a digest. This section is the authoritative,
+  // self-contained representation of every task: it renders each field integrally so
+  // the Work Breakdown Markdown (plus the dispatch CSV) is a complete deliverable —
+  // the intermediate JSON is not required by any downstream consumer.
+  //
+  // Free-text fields (title, outcome, grouping rationale, commit subject) are rendered
+  // OUTSIDE any table and are therefore preserved verbatim — including pipes, which
+  // sanitizeField would otherwise map to spaces to protect table/CSV columns.
+  // Verification commands are emitted as fenced code blocks that are byte-equivalent
+  // to the source; the fence length exceeds any backtick run in the command so a
+  // command containing backticks can never break out of its block.
+  const raw = v => (typeof v === 'string' ? v : String(v ?? ''))
+  const getTokens = task => {
+    const t = task.estimate?.tokens ?? task.tokens
+    return (t !== undefined && t !== null) ? String(t) : '—'
+  }
+  const listOrDash = arr =>
+    (Array.isArray(arr) && arr.length > 0) ? arr.join(', ') : '—'
+
+  L.push('## Task Details')
+  L.push('')
+  L.push('> Authoritative per-task detail. Every field is rendered integrally so this document, together with the dispatch CSV, is a complete deliverable requiring no separate JSON. Verification commands are preserved **verbatim** in fenced code blocks — operators such as `||`, shell pipes `|`, and regex alternations (`grep -E \'a|b|c\'`) survive byte-for-byte. Each command is an independent fenced block.')
+  L.push('')
+  for (const phase of wb.phases) {
+    for (const task of (Array.isArray(phase.tasks) ? phase.tasks : [])) {
+      const cmds    = getVerificationCommands(task)
+      const mins    = getAgentMinutes(task)
+      L.push(`<a id="${taskAnchor(task.id)}"></a>`)
+      L.push(`### ${raw(task.id)}`)
+      L.push('')
+      L.push(`- **Task ID:** ${raw(task.id)}`)
+      L.push(`- **Title:** ${raw(task.title)}`)
+      L.push(`- **Outcome:** ${raw(task.outcome)}`)
+      L.push(`- **Domain:** ${raw(task.domain)}`)
+      L.push(`- **Agent type:** ${raw(task.agentType)}`)
+      L.push(`- **Dependencies:** ${listOrDash(task.dependsOn)}`)
+      L.push(`- **Acceptance criteria:** ${listOrDash(task.acceptanceCriteria)}`)
+      L.push(`- **Estimate — agent minutes:** ${mins !== null ? String(mins) : '—'}`)
+      L.push(`- **Estimate — tokens:** ${getTokens(task)}`)
+      L.push(`- **Output count:** ${task.outputCount != null ? String(task.outputCount) : '—'}`)
+      L.push(`- **Grouping rationale:** ${task.groupingRationale != null ? raw(task.groupingRationale) : '—'}`)
+      L.push(`- **Commit type:** ${task.commit && task.commit.type != null ? raw(task.commit.type) : '—'}`)
+      L.push(`- **Commit scope:** ${task.commit && task.commit.scope != null ? raw(task.commit.scope) : '—'}`)
+      L.push(`- **Commit subject:** ${task.commit && task.commit.subject != null ? raw(task.commit.subject) : '—'}`)
+      L.push('')
+      L.push('**Verification commands:**')
+      L.push('')
+      if (cmds.length === 0) {
+        L.push('_No verification commands._')
+        L.push('')
+      } else {
+        for (const cmd of cmds) {
+          L.push(fencedCommandBlock(cmd))
+          L.push('')
+        }
+      }
+    }
+  }
+
   // ── Statistics ──
   L.push('## Statistics')
   L.push('')

package/src/claude/scripts/wb-validate.js

@@ -59,6 +59,36 @@ const ERRORS = {
   EMPTY_PHASE:                  'empty_phase',                   // check 23
 }
 
+// ── Markdown table row splitter ─────────────────────────────────────────────
+// Splits a Markdown table row into cells on unescaped pipe separators only.
+// A backslash-escaped pipe (\|) is treated as a literal pipe *inside* the cell
+// rather than a column separator and is unescaped in the returned cell, so a
+// criterion such as `ai-toolkit ledger open\|close\|fail\|skip` stays in a
+// single cell and does not shift the "Related UC" column.
+// Returns the raw split including the leading/trailing empty cells produced by
+// the row's outer pipes, matching the previous `line.split('|')` contract so
+// callers can keep using `.slice(1, -1)`.
+function splitTableRow(line) {
+  const cells = []
+  let current = ''
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i]
+    if (ch === '\\' && line[i + 1] === '|') {
+      current += '|' // unescape: keep the literal pipe inside this cell
+      i++            // consume the escaped '|'
+      continue
+    }
+    if (ch === '|') {
+      cells.push(current)
+      current = ''
+      continue
+    }
+    current += ch
+  }
+  cells.push(current)
+  return cells
+}
+
 // ── AC table parser (prerequisite for checks 19–21) ─────────────────────────
 
 function parseAcTable(requirementsPath) {
@@ -122,7 +152,7 @@ function parseAcTable(requirementsPath) {
   }
 
   // ── Validate column headers ────────────────────────────────────────────────
-  const headerCells = lines[tableHeaderIdx].split('|').slice(1, -1).map(c => c.trim())
+  const headerCells = splitTableRow(lines[tableHeaderIdx]).slice(1, -1).map(c => c.trim())
   if (headerCells.length < 3) {
     process.stderr.write('Error: AC table header has fewer than 3 columns\n')
     process.exit(2)
@@ -143,7 +173,7 @@ function parseAcTable(requirementsPath) {
     if (!line.trim().startsWith('|')) break
 
     // Skip separator rows: every cell is only dashes, colons, or spaces
-    const rawCells = line.split('|').slice(1, -1)
+    const rawCells = splitTableRow(line).slice(1, -1)
     if (rawCells.every(c => /^[\s\-:]+$/.test(c))) continue
 
     const cells = rawCells.map(c => c.trim())

package/src/claude/skills/implement-feature/SKILL.md

@@ -204,6 +204,8 @@ From the `<usage>` block of the pm-phase3 result, read:
 
 Read `{PREFIX}-Token-Estimate.md`. Append the orchestrator row and grand total:
 
+> **Null-compatibility — actuals reading and cost calculation:** Treat a token value of `null`, `0`, or `not_available` as **data unavailable** — never as a real, observable zero consumption. Render unavailable values as `—` in the Actual tokens and Actual cost columns; exclude them from sums, averages, and grand totals. Preventing resume clobber and legacy misinterpretation requires that no unavailable measurement is coerced into a real zero.
+
 ```markdown
 | project-manager/pm-phase3 (orchestrator) | — | sonnet | 80,000 (estimated) | {subagent_tokens} (actual) | ±{delta} | {duration} |
 
@@ -213,14 +215,14 @@ Read `{PREFIX}-Token-Estimate.md`. Append the orchestrator row and grand total:
 
 | Agent | Task / Scope | Model | Est. tokens | Actual tokens | Delta | Est. cost ($) | Actual cost ($) | Duration |
 |-------|-------------|-------|------------|---------------|-------|--------------|----------------|----------|
-{one row per entry in token_ledger — from phase 1, 2, and 3}
+{one row per entry in token_ledger — from phase 1, 2, and 3; for any entry where actual tokens is null, 0, or not_available show — in Actual tokens and Actual cost and exclude that row from totals}
 | project-manager/pm-phase3 (orchestrator) | — | sonnet | 80,000 | {subagent_tokens} | ±{delta} | $0.4320 | ${actual_cost} | {duration} |
 
 ## Estimation accuracy by agent type
 
 | Model | Count | Avg est. tokens | Avg actual tokens | Avg delta | Trend |
 |-------|-------|----------------|------------------|-----------|-------|
-{one row per model tier (haiku, sonnet) — exclude N/A rows from averages}
+{one row per model tier (haiku, sonnet) — exclude rows where actual tokens is null, 0, or not_available from averages}
 
 ## Grand Total
 

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

@@ -9,38 +9,6 @@ export const meta = {
   ],
 }
 
-// ── Ledger helper functions ───────────────────────────────────────────────────
-
-async function appendLedgerEntry(featureDir, prefix, entry) {
-  const ledgerPath = `${featureDir}/${prefix}-token-ledger.json`
-  // started_at is generated via Bash inside the agent to get a real UTC timestamp with time
-  const entryWithoutTs = JSON.stringify({ ...entry, started_at: '__TS__', completed_at: null })
-  await agent(
-    `Append a JSON object to the ledger array at: ${ledgerPath}\n\n` +
-    `1. Run: date -u +"%Y-%m-%dT%H:%M:%SZ" and capture the output as NOW.\n` +
-    `2. Read the file. If it does not exist or cannot be parsed as a JSON array, start with [].\n` +
-    `3. Push this object onto the array, replacing "__TS__" in started_at with NOW: ${entryWithoutTs}\n` +
-    `4. 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`
-  // completed_at is generated via Bash inside the agent to get a real UTC timestamp with time
-  const updatesWithoutTs = JSON.stringify({ ...updates, completed_at: '__TS__' })
-  await agent(
-    `Update an entry in the ledger array at: ${ledgerPath}\n\n` +
-    `1. Run: date -u +"%Y-%m-%dT%H:%M:%SZ" and capture the output as NOW.\n` +
-    `2. Read the file. If it does not exist or cannot be parsed as a JSON array, do nothing.\n` +
-    `3. Search from the end for the last entry where agent === "${agentKey}".\n` +
-    `4. If found, merge these fields into that entry, replacing "__TS__" in completed_at with NOW: ${updatesWithoutTs}\n` +
-    `5. Write the full array back (JSON, 2-space indent). Return no output.\n` +
-    `6. 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]
@@ -104,7 +72,7 @@ log(`needs_requirements=${discoveryResult.needs_requirements} 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.
+// Touch it with an empty array so the ledger facade 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.`,
@@ -120,23 +88,17 @@ const errors      = []
 
 if (discoveryResult.needs_requirements) {
   const reqKey = 'generate-requirements:phase1'
-  await appendLedgerEntry(feature_dir, prefix, {
-    agent: reqKey,
-    phase: 'phase1',
-    model: 'haiku',
-    status: 'running',
-    phase_delta_tokens: 0,
-    started_at: '__TS__',
-    completed_at: null,
-  })
+  await agent(
+    `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger open --dir ${feature_dir} --prefix ${prefix} --agent ${reqKey} --phase phase1 --model haiku --attempt 1\n\nReturn no output.`,
+    { label: 'ledger-open-requirements', phase: 'Requirements', model: 'haiku' }
+  )
   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: '__TS__',
-    phase_delta_tokens: reqTokens,
-  })
+  await agent(
+    `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger close --dir ${feature_dir} --prefix ${prefix} --agent ${reqKey} --tokens ${reqTokens} --attempt 1\n\nReturn no output.`,
+    { label: 'ledger-close-requirements', phase: 'Requirements', model: 'haiku' }
+  )
   tokenLedger.push({ agent: 'generate-requirements', model: 'haiku', phase_delta_tokens: reqTokens })
   log(`generate-requirements done — phase delta: ${reqTokens} tokens`)
 } else {
@@ -148,23 +110,17 @@ phase('Tech-Spec')
 
 if (discoveryResult.needs_tech_spec) {
   const specKey = 'generate-tech-spec:phase1'
-  await appendLedgerEntry(feature_dir, prefix, {
-    agent: specKey,
-    phase: 'phase1',
-    model: 'haiku',
-    status: 'running',
-    phase_delta_tokens: 0,
-    started_at: '__TS__',
-    completed_at: null,
-  })
+  await agent(
+    `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger open --dir ${feature_dir} --prefix ${prefix} --agent ${specKey} --phase phase1 --model haiku --attempt 1\n\nReturn no output.`,
+    { label: 'ledger-open-tech-spec', phase: 'Tech-Spec', model: 'haiku' }
+  )
   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: '__TS__',
-    phase_delta_tokens: specTokens,
-  })
+  await agent(
+    `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger close --dir ${feature_dir} --prefix ${prefix} --agent ${specKey} --tokens ${specTokens} --attempt 1\n\nReturn no output.`,
+    { label: 'ledger-close-tech-spec', phase: 'Tech-Spec', model: 'haiku' }
+  )
   tokenLedger.push({ agent: 'generate-tech-spec', model: 'haiku', phase_delta_tokens: specTokens })
   log(`generate-tech-spec done — phase delta: ${specTokens} tokens`)
 } else {
@@ -181,23 +137,17 @@ 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}`
-  await appendLedgerEntry(feature_dir, prefix, {
-    agent: valKey,
-    phase: 'phase1',
-    model: 'haiku',
-    status: 'running',
-    phase_delta_tokens: 0,
-    started_at: '__TS__',
-    completed_at: null,
-  })
+  await agent(
+    `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger open --dir ${feature_dir} --prefix ${prefix} --agent ${valKey} --phase phase1 --model haiku --attempt 1\n\nReturn no output.`,
+    { label: `ledger-open-validate-cycle-${cycle}`, phase: 'Validation', model: 'haiku' }
+  )
   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: '__TS__',
-    phase_delta_tokens: valTokens,
-  })
+  await agent(
+    `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger close --dir ${feature_dir} --prefix ${prefix} --agent ${valKey} --tokens ${valTokens} --attempt 1\n\nReturn no output.`,
+    { label: `ledger-close-validate-cycle-${cycle}`, phase: 'Validation', model: 'haiku' }
+  )
   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/src/claude/workflows/pm-phase2.js

@@ -7,42 +7,6 @@ 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`
-  // Defaults come first so the caller can override started_at/completed_at.
-  // Skipped entries pass completed_at: '__TS__' to get a real timestamp; running entries
-  // pass completed_at: null to keep it null. Both are replaced/kept by the agent below.
-  const entryWithoutTs = JSON.stringify({ started_at: '__TS__', completed_at: null, ...entry })
-  await agent(
-    `Append a JSON object to the ledger array at: ${ledgerPath}\n\n` +
-    `1. Run: date -u +"%Y-%m-%dT%H:%M:%SZ" and capture the output as NOW.\n` +
-    `2. Read the file. If it does not exist or cannot be parsed as a JSON array, start with [].\n` +
-    `3. Push this object onto the array, replacing every "__TS__" string value in the object with NOW: ${entryWithoutTs}\n` +
-    `4. 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`
-  // completed_at is generated via Bash inside the agent to get a real UTC timestamp with time
-  const updatesWithoutTs = JSON.stringify({ ...updates, completed_at: '__TS__' })
-  await agent(
-    `Update an entry in the ledger array at: ${ledgerPath}\n\n` +
-    `1. Run: date -u +"%Y-%m-%dT%H:%M:%SZ" and capture the output as NOW.\n` +
-    `2. Read the file. If it does not exist or cannot be parsed as a JSON array, do nothing.\n` +
-    `3. Search from the end for the last entry where agent === "${agentKey}".\n` +
-    `4. If found, merge these fields into that entry, replacing "__TS__" in completed_at with NOW: ${updatesWithoutTs}\n` +
-    `5. Write the full array back (JSON, 2-space indent). Return no output.\n` +
-    `6. If not found, do nothing.`,
-    { label: 'update-ledger', phase: 'Work Breakdown', model: 'haiku' }
-  )
-}
-
 // Output schemas for wb-validate and wb-render agent invocations (used by US-05)
 const WB_WRAPPER_SCHEMA = {
   type: 'object',
@@ -90,8 +54,21 @@ function normalizeError(err) {
 // args: "<path-to-feature.md>"
 const featurePath = (typeof args === 'string' ? args : '').trim().split(/\s+/)[0]
 
+// Feature directory = parent of the feature.md path. Separator-agnostic: the workflow
+// runtime provides no `path` module, so we cannot use path.dirname. Handle BOTH POSIX
+// "/" and Windows "\": strip a trailing "<sep>feature.md" tail when present; if the
+// input is already a directory (no feature.md tail), strip only a trailing separator.
+// This replaces the previous POSIX-only regex (/\/[^/]+$/), which left "\feature.md"
+// attached on Windows paths and produced malformed "…\feature.md/…json" paths that only
+// "worked" because an LLM wrapper agent silently repaired them.
+function deriveFeatureDir(featurePath) {
+  return /[/\\]feature\.md$/i.test(featurePath)
+    ? featurePath.replace(/[/\\]feature\.md$/i, '')
+    : featurePath.replace(/[/\\]+$/, '')
+}
+
 // Derive feature directory and prefix early (needed for ledger writes before metrics agent runs)
-const featureDir  = featurePath.replace(/\/[^/]+$/, '')
+const featureDir  = deriveFeatureDir(featurePath)
 const prefixMatch = featureDir.match(/([A-Z]+-\d+)/)
 const prefix      = prefixMatch ? prefixMatch[1] : 'FTR-000'
 
@@ -101,15 +78,11 @@ phase('Work Breakdown')
 const tokenLedger = []
 
 log(`Running generate-work-breakdown for ${featurePath}`)
-await appendLedgerEntry(featureDir, prefix, {
-  agent: 'generate-work-breakdown:phase2',
-  phase: 'phase2',
-  model: 'haiku',
-  status: 'running',
-  phase_delta_tokens: 0,
-  started_at: '__TS__',
-  completed_at: null,
-})
+const wbKey = 'generate-work-breakdown:phase2'
+await agent(
+  `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger open --dir ${featureDir} --prefix ${prefix} --agent ${wbKey} --phase phase2 --model haiku --attempt 1\n\nReturn no output.`,
+  { label: 'ledger-open-generate-work-breakdown', phase: 'Work Breakdown', model: 'haiku' }
+)
 const beforeWB = budget.spent()
 await agent(featurePath, {
   agentType: 'generate-work-breakdown',
@@ -117,11 +90,10 @@ await agent(featurePath, {
   phase:     'Work Breakdown',
 })
 const wbTokens = budget.spent() - beforeWB
-await updateLedgerEntry(featureDir, prefix, 'generate-work-breakdown:phase2', {
-  status: 'done',
-  completed_at: '__TS__',
-  phase_delta_tokens: wbTokens,
-})
+await agent(
+  `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger close --dir ${featureDir} --prefix ${prefix} --agent ${wbKey} --tokens ${wbTokens} --attempt 1\n\nReturn no output.`,
+  { label: 'ledger-close-generate-work-breakdown', phase: 'Work Breakdown', model: 'haiku' }
+)
 tokenLedger.push({ agent: 'generate-work-breakdown', model: 'haiku', phase_delta_tokens: wbTokens })
 log(`generate-work-breakdown done — phase delta: ${wbTokens} tokens`)
 
@@ -129,11 +101,11 @@ log(`generate-work-breakdown done — phase delta: ${wbTokens} tokens`)
 let wbValidatorReport = null
 let validateFailed = false
 let validateExitCode = null
-await appendLedgerEntry(featureDir, prefix, {
-  agent: 'wb-validate:phase2',
-  phase: 'phase2', model: 'haiku', status: 'running',
-  phase_delta_tokens: 0, started_at: '__TS__', completed_at: null,
-})
+const wbValidateKey = 'wb-validate:phase2'
+await agent(
+  `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger open --dir ${featureDir} --prefix ${prefix} --agent ${wbValidateKey} --phase phase2 --model haiku --attempt 1\n\nReturn no output.`,
+  { label: 'ledger-open-wb-validate', phase: 'Work Breakdown', model: 'haiku' }
+)
 const beforeValidate = budget.spent()
 try {
   const validateWrapper = await agent(
@@ -173,20 +145,14 @@ try {
   if (validateWrapper.exitCode === 1 && wbValidatorReport.valid) {
     throw new Error('Inconsistent wb-validate result: exit 1 with valid=true')
   }
-  await updateLedgerEntry(featureDir, prefix, 'wb-validate:phase2', {
-    status: 'done', completed_at: '__TS__',
-    phase_delta_tokens: budget.spent() - beforeValidate,
-  })
 } catch (err) {
   validateFailed = true
-  await updateLedgerEntry(featureDir, prefix, 'wb-validate:phase2', {
-    status: 'failed', completed_at: '__TS__',
-    phase_delta_tokens: budget.spent() - beforeValidate,
-    error_summary: normalizeError(err),
-    exit_code: err._exitCode ?? validateExitCode ?? null,
-  })
 }
 const validateTokens = budget.spent() - beforeValidate
+await agent(
+  `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger close --dir ${featureDir} --prefix ${prefix} --agent ${wbValidateKey} --tokens ${validateTokens} --attempt 1\n\nReturn no output.`,
+  { label: 'ledger-close-wb-validate', phase: 'Work Breakdown', model: 'haiku' }
+)
 const wbValidatorPassed = !validateFailed && wbValidatorReport !== null
   && wbValidatorReport.valid === true && wbValidatorReport.errors.length === 0
 log(`wb-validate: ${wbValidatorPassed ? 'passed' : 'failed/errors'} — ${validateTokens} tokens`)
@@ -195,18 +161,14 @@ log(`wb-validate: ${wbValidatorPassed ? 'passed' : 'failed/errors'} — ${valida
 let semanticResult = null
 let semanticFailed = false
 let semanticTokens = 0
+const semanticKey = 'validate-work-breakdown-semantic:phase2'
 if (!wbValidatorPassed) {
-  await appendLedgerEntry(featureDir, prefix, {
-    agent: 'validate-work-breakdown-semantic:phase2',
-    phase: 'phase2', model: 'sonnet', status: 'skipped',
-    phase_delta_tokens: 0, started_at: '__TS__', completed_at: '__TS__',
-  })
+  log('validate-work-breakdown-semantic: skipped (wb-validate did not pass)')
 } else {
-  await appendLedgerEntry(featureDir, prefix, {
-    agent: 'validate-work-breakdown-semantic:phase2',
-    phase: 'phase2', model: 'sonnet', status: 'running',
-    phase_delta_tokens: 0, started_at: '__TS__', completed_at: null,
-  })
+  await agent(
+    `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger open --dir ${featureDir} --prefix ${prefix} --agent ${semanticKey} --phase phase2 --model sonnet --attempt 1\n\nReturn no output.`,
+    { label: 'ledger-open-semantic-validator', phase: 'Work Breakdown', model: 'haiku' }
+  )
   const beforeSemantic = budget.spent()
   try {
     semanticResult = await agent(
@@ -218,18 +180,14 @@ if (!wbValidatorPassed) {
         schema:    WB_SEMANTIC_SCHEMA,
       }
     )
-    semanticTokens = budget.spent() - beforeSemantic
-    await updateLedgerEntry(featureDir, prefix, 'validate-work-breakdown-semantic:phase2', {
-      status: 'done', completed_at: '__TS__', phase_delta_tokens: semanticTokens,
-    })
   } catch (err) {
     semanticFailed = true
-    semanticTokens = budget.spent() - beforeSemantic
-    await updateLedgerEntry(featureDir, prefix, 'validate-work-breakdown-semantic:phase2', {
-      status: 'failed', completed_at: '__TS__', phase_delta_tokens: semanticTokens,
-      error_summary: normalizeError(err), exit_code: null,
-    })
   }
+  semanticTokens = budget.spent() - beforeSemantic
+  await agent(
+    `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger close --dir ${featureDir} --prefix ${prefix} --agent ${semanticKey} --tokens ${semanticTokens} --attempt 1\n\nReturn no output.`,
+    { label: 'ledger-close-semantic-validator', phase: 'Work Breakdown', model: 'haiku' }
+  )
 }
 log(`semantic validator: ${semanticFailed ? 'failed' : semanticResult ? 'done' : 'skipped'}`)
 
@@ -237,18 +195,14 @@ log(`semantic validator: ${semanticFailed ? 'failed' : semanticResult ? 'done' :
 const canRender = wbValidatorPassed && !semanticFailed
 let renderFailed = false
 let renderResult = null
+const wbRenderKey = 'wb-render:phase2'
 if (!canRender) {
-  await appendLedgerEntry(featureDir, prefix, {
-    agent: 'wb-render:phase2',
-    phase: 'phase2', model: 'haiku', status: 'skipped',
-    phase_delta_tokens: 0, started_at: '__TS__', completed_at: '__TS__',
-  })
+  log('wb-render: skipped (wb-validate or semantic validator did not pass)')
 } else {
-  await appendLedgerEntry(featureDir, prefix, {
-    agent: 'wb-render:phase2',
-    phase: 'phase2', model: 'haiku', status: 'running',
-    phase_delta_tokens: 0, started_at: '__TS__', completed_at: null,
-  })
+  await agent(
+    `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger open --dir ${featureDir} --prefix ${prefix} --agent ${wbRenderKey} --phase phase2 --model haiku --attempt 1\n\nReturn no output.`,
+    { label: 'ledger-open-wb-render', phase: 'Work Breakdown', model: 'haiku' }
+  )
   const beforeRender = budget.spent()
   try {
     renderResult = await agent(
@@ -291,20 +245,15 @@ if (!canRender) {
         { _exitCode: renderResult.exitCode }
       )
     }
-    await updateLedgerEntry(featureDir, prefix, 'wb-render:phase2', {
-      status: 'done', completed_at: '__TS__',
-      phase_delta_tokens: budget.spent() - beforeRender,
-    })
   } catch (err) {
     renderFailed = true
-    await updateLedgerEntry(featureDir, prefix, 'wb-render:phase2', {
-      status: 'failed', completed_at: '__TS__',
-      phase_delta_tokens: budget.spent() - beforeRender,
-      error_summary: normalizeError(err),
-      exit_code: err._exitCode ?? renderResult?.exitCode ?? null,
-    })
   }
-  tokenLedger.push({ agent: 'wb-render', model: 'haiku', phase_delta_tokens: budget.spent() - beforeRender })
+  const renderTokens = budget.spent() - beforeRender
+  await agent(
+    `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger close --dir ${featureDir} --prefix ${prefix} --agent ${wbRenderKey} --tokens ${renderTokens} --attempt 1\n\nReturn no output.`,
+    { label: 'ledger-close-wb-render', phase: 'Work Breakdown', model: 'haiku' }
+  )
+  tokenLedger.push({ agent: 'wb-render', model: 'haiku', phase_delta_tokens: renderTokens })
 }
 
 tokenLedger.push({ agent: 'wb-validate', model: 'haiku', phase_delta_tokens: validateTokens })