@dtlabs/ai-toolkit 0.10.1 → 0.12.0

package/{.claude → src/claude}/agents/define-feature.md

@@ -80,56 +80,53 @@ Ask the user to **confirm or correct the draft**. Then grill ONLY on the `❓` g
 
 ## Phase 1 — Setup
 
-### 1a. Discover the next FTR number
+### 1a. Resolve the features root (MANDATORY — single source of truth)
 
-Scan `docs/features/` for existing folders matching the pattern `FTR-[0-9]+*`. Extract the highest number and increment by 1. If no folders exist, start at `FTR-001`.
+Before any file-system operation, run the following command **once** via Bash and capture its stdout into `featuresRoot`:
 
+```bash
+featuresRoot=$(ai-toolkit resolve-features-root) && echo "$featuresRoot"
 ```
-docs/features/FTR-001-user-management/  → max = 1
-docs/features/FTR-002-product-catalog/  → max = 2
+
+If the command exits non-zero, stop immediately and report the error to the user — do not proceed.
+
+This single captured value (`featuresRoot`) is the **sole source of truth** for the features root in every subsequent step. Do **not** hard-code `docs/features/`, `internal_docs/features/`, or any other path. Both the directory under which `feature.md` is written (step 1d) and the `--dir` argument passed to the ledger facade must use this exact value — they must always agree, with no divergent or duplicate roots.
+
+### 1b. Discover the next FTR number
+
+Scan `{featuresRoot}` for existing folders matching the pattern `FTR-[0-9]+*`. Extract the highest number and increment by 1. If no folders exist, start at `FTR-001`.
+
+```
+{featuresRoot}/FTR-001-user-management/  → max = 1
+{featuresRoot}/FTR-002-product-catalog/  → max = 2
 → next = FTR-003
 ```
 
-### 1b. Ask for a feature name
+### 1c. Ask for a feature name
 
 Ask the user: **"What is the name of this feature?"** (short, descriptive, in their language). Use it to build the folder slug in kebab-case.
 
 Example: "Supplier Onboarding" → `FTR-003-supplier-onboarding`
 
-### 1c. Create feature directory and initialize ledger
+### 1d. Create feature directory and open ledger entry
 
-Once you know the PREFIX (from 1a) and the feature slug (from 1b), do the following **before asking any grilling questions**:
+Once you know the PREFIX (from 1b) and the feature slug (from 1c), 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`
+1. Compute `featureDir` using the captured `featuresRoot`:
+   - `featureDir` = `{featuresRoot}/{PREFIX}-{slug}` (e.g. `{featuresRoot}/FTR-003-supplier-onboarding`)
+   - This path is also the `--dir` value for every `ai-toolkit ledger` call that follows.
 
 2. Create the feature directory via Bash:
    ```bash
-   mkdir -p {featureDir}
+   mkdir -p "{featureDir}"
    ```
 
-3. Capture the current UTC timestamp via Bash:
+3. Open the ledger entry via the facade. Run the following command via Bash (quote the `--dir` path to handle spaces):
    ```bash
-   started_at=$(date -u +"%Y-%m-%dT%H:%M:%SZ") && echo $started_at
+   ai-toolkit ledger open --dir "{featureDir}" --prefix {PREFIX} --agent define-feature:define --phase define --model sonnet --attempt 1
    ```
 
-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.
+The ledger now records that the define-feature agent is running. Proceed to Phase 2.
 
 ---
 
@@ -254,12 +251,12 @@ Synthesize all answers into a structured `feature.md` file.
 ### Output path
 
 ```
-docs/features/{PREFIX}-{slug}/feature.md
+{featuresRoot}/{PREFIX}-{slug}/feature.md
 ```
 
-Example: `docs/features/FTR-003-supplier-onboarding/feature.md`
+Example: `{featuresRoot}/FTR-003-supplier-onboarding/feature.md`
 
-The directory was created in Phase 1c. If for any reason it doesn't exist, create it now.
+The directory was created in Phase 1d using `featuresRoot`. If for any reason it doesn't exist, create it now using the same `featuresRoot` path — do not substitute a different root.
 
 ### feature.md template
 
@@ -352,34 +349,13 @@ For each entity: name, key fields (name, type, constraints), relationships.
 
 ### 4b. Finalize ledger entry
 
-After writing `feature.md`, update the ledger entry to record successful completion:
+After writing `feature.md`, close the ledger entry via the facade. Run the following command via Bash (quote the `--dir` path to handle spaces):
 
-1. Capture the current UTC timestamp via Bash:
-   ```bash
-   completed_at=$(date -u +"%Y-%m-%dT%H:%M:%SZ") && echo $completed_at
-   ```
+```bash
+ai-toolkit ledger close --dir "{featureDir}" --prefix {PREFIX} --agent define-feature:define --attempt 1
+```
 
-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>"
-     }
-   ]
-   ```
+**Important:** `--tokens` is intentionally omitted. The ledger facade records `phase_delta_tokens` as `null` when `--tokens` is not supplied. `define-feature` is an interactive/LLM activity whose token consumption cannot be observed from within the agent itself — do **not** pass `0` or any estimate.
 
 ---
 
@@ -392,7 +368,7 @@ After writing `feature.md`:
 3. Tell the user the next step:
 
 ```
-✅ feature.md written at docs/features/{PREFIX}-{slug}/feature.md
+✅ feature.md written at {featuresRoot}/{PREFIX}-{slug}/feature.md
 
 Summary:
   Actors:               N
@@ -400,7 +376,7 @@ Summary:
   Acceptance criteria:  N (Must: N, Should: N, Could: N)
   Open questions:       N
 
-Next step: run /implement-feature docs/features/{PREFIX}-{slug}/feature.md
+Next step: run /implement-feature {featuresRoot}/{PREFIX}-{slug}/feature.md
            to start the full pipeline (requirements → spec → implementation → PR).
 ```
 

package/{.claude → src/claude}/agents/install-toolkit.md

@@ -6,7 +6,7 @@ model: sonnet
 
 # Install Toolkit
 
-Copies the toolkit's agents, skills, commands, and procedures into a destination project so it can use `/implement-feature`, `/init-agents`, all developer agents, and all slash commands without needing the toolkit repo locally.
+Installs the ai-toolkit into a destination project so it can use `/implement-feature`, `/init-agents`, all developer agents, and all slash commands without needing the toolkit repo locally.
 
 ---
 
@@ -15,130 +15,57 @@ Copies the toolkit's agents, skills, commands, and procedures into a destination
 The user provides:
 1. **Path to the destination project root** (optional) — defaults to the current working directory if not specified
 2. **`--force`** flag (optional) — overwrite files that already exist in the destination
+3. **`--global`** flag (optional) — install into the global Claude Code config directory (`~/.claude/`) instead of a project
 
 ---
 
-## Step 1 — Validate inputs and check version
-
-1. Determine the **toolkit root**: the current working directory (this agent runs from the toolkit repo).
-2. Verify the toolkit root contains `.claude/agents/` — if not, abort: "Error: must be run from the ai-toolkit directory."
-3. Verify the destination path exists — if not, abort: "Error: destination path not found: {path}"
-4. Check if destination is a git repository (look for `.git/`) — warn if not, but continue.
-5. **Version check**:
-   - Read `package.json` from the toolkit root to get the current version (e.g. `0.2.0`)
-   - Check if `.claude/.ai-toolkit-version` exists in the destination:
-     - **File missing** → first install, no prompt needed, continue
-     - **Same version** → inform the user and ask: "Toolkit v{x} is already installed. Re-install anyway?"
-       - If No: abort cleanly
-     - **Different version** → show both versions and ask:
-       ```
-       Version check:
-         Installed : v{installed}
-         Available : v{current}
-
-       Proceed and update from v{installed} to v{current}?
-       ```
-       - If No: abort cleanly with "Your current installation was not changed."
+## Step 1 — Validate inputs
 
----
-
-## Step 2 — Plan what to copy
-
-Six source directories to install:
-
-| Source (toolkit) | Destination | Purpose |
-|------------------|-------------|---------|
-| `.claude/agents/` | `{dest}/.claude/agents/` | All spawnable subagents |
-| `.claude/skills/` | `{dest}/.claude/skills/` | All user-invocable skills (except `install-toolkit/`) |
-| `.claude/commands/` | `{dest}/.claude/commands/` | All slash commands |
-| `.claude/workflows/` | `{dest}/.claude/workflows/` | Claude Code Workflow scripts for orchestrated pipelines |
-| `.claude/scripts/` | `{dest}/.claude/scripts/` | CLI scripts for work breakdown validation and rendering |
-| `docs/procedures/` | `{dest}/docs/procedures/` | Generic procedures (only if destination has no override) |
-
-For each file, compare source content against destination using an MD5/hash check and determine status:
-- **NEW** — file does not exist in destination → copy automatically, no prompt
-- **SAME** — file exists and content is identical → skip silently, no prompt
-- **MODIFIED** — file exists but content differs → show to user, ask per-file
-
-Build and display the plan before executing:
-
-```
-📦 Install Plan  →  {destination}
-──────────────────────────────────────────────────
-.claude/agents/
-  ✅ NEW       generate-requirements.md
-  ⚠️  MODIFIED  developer-backend.md    ← content differs
-  ⏭  SAME      review-solution.md
-
-.claude/skills/
-  ✅ NEW       implement-feature/SKILL.md
-  ⏭  SAME      init-agents/SKILL.md
-
-.claude/workflows/
-  ✅ NEW       pm-phase1.js
-  ✅ NEW       pm-phase2.js
-  ✅ NEW       pm-phase3.js
-  ✅ NEW       am-phase1.js
-  ✅ NEW       am-phase2.js
-
-.claude/scripts/
-  ✅ NEW       wb-validate.js
-  ✅ NEW       wb-render.js
-
-docs/procedures/
-  ✅ NEW       code-generation.md
-  ⏭  SAME      testing.md
-──────────────────────────────────────────────────
-New: N  |  Modified: N  |  Unchanged: N
-```
+1. Determine destination:
+   - If `--global` was passed: destination is `~/.claude/` (user-global config dir)
+   - Otherwise: destination is the path provided, or the current working directory if omitted
+2. Verify the destination path exists — if not, abort: "Error: destination path not found: {path}"
+3. Check if destination is a git repository (look for `.git/`) — warn if not, but continue.
 
 ---
 
-## Step 3 — Execute
-
-**Phase A — New files** (no prompt needed): copy all NEW files, creating directories as needed.
+## Step 2 — Run installer
 
-**Phase B — Modified files** (per-file prompt):
+Invoke the ai-toolkit CLI installer. The CLI handles source resolution (no CWD assumption), version checking, asset catalog enumeration, and file copy:
 
-For each MODIFIED file, show:
-```
-  ⚠️  MODIFIED: .claude/agents/developer-backend.md
-  The toolkit version differs from the one already in your project.
-  Overwrite? (y/N):
+```bash
+ai-toolkit install --project "{dest}"   # for a project install
+# or
+ai-toolkit install --global             # for a global install
 ```
 
-Wait for the user's response before moving to the next file. If `--force` was passed, overwrite all modified files without prompting.
-
-**Phase C — Same files**: skip silently (no output for these).
-
-Use shell commands appropriate for the OS. On Windows with bash:
+If `--force` was passed:
 ```bash
-mkdir -p "{dest_dir}"
-cp "{source_file}" "{dest_file}"
+ai-toolkit install --project "{dest}" --force
 ```
 
-**Never copy the `install-toolkit/` skill directory** — this skill is toolkit-internal and has no use in a destination project.
+The installer will:
+- Compare installed version vs available version and ask for confirmation if already installed at the same version
+- Enumerate all installable assets from the asset catalog (`src/claude/`)
+- Copy NEW files automatically; prompt for MODIFIED files (or overwrite silently if `--force`)
+- Skip SAME files silently
+- Never copy `install-toolkit` skill or `settings.json` / `settings.local.json`
+- Never clobber `docs/procedures/` overrides that exist in the destination
+- Stamp the installed version in `{dest}/.claude/.ai-toolkit-version`
 
-**Never copy `.claude/settings.json` or `.claude/settings.local.json`** — these are user-owned configuration. Copying them would clobber the destination's existing settings. The toolkit's own `settings.json` exists only to configure this repo; it is verified and advised on (Step 4b), never installed.
-
-**For `docs/procedures/`**: copy only files that don't already exist in the destination (regardless of `--force`) — project-specific procedure overrides must never be clobbered.
+Show the installer's output to the user without modification.
 
 ---
 
-## Step 4 — Verify and stamp version
+## Step 3 — Verify result
 
-After copying:
-1. Verify all expected files are present in the destination
-2. Verify no files are zero bytes
-3. Write the installed version to `.claude/.ai-toolkit-version` in the destination:
-   ```bash
-   echo "{current_version}" > "{dest}/.claude/.ai-toolkit-version"
-   ```
-   This file is read on future installs to show the version comparison prompt.
+After the installer exits:
+1. Confirm exit code was 0 — if non-zero, report the error and stop
+2. Verify `.claude/.ai-toolkit-version` was written in the destination
 
 ---
 
-## Step 4b — Verify subagent spawn depth (verify & advise ONLY — never write)
+## Step 4 — Verify subagent spawn depth (verify & advise ONLY — never write)
 
 The orchestrated pipelines (`/implement-feature`, `/assess-codebase`) require the
 environment variable `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` to be set to `2` or higher.

package/{.claude → 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/{.claude → 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/{.claude → 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/{.claude → src/claude}/workflows/am-phase1.js

@@ -2,7 +2,7 @@ export const meta = {
   name: 'am-phase1',
   description: 'Assessment pipeline phase 1: discover assessment agents → scope filter → parallel assessment → intervention-documentation-standard → Token-Estimate → Effort-Estimate → findings_gate_payload.',
   phases: [
-    { title: 'Discovery',      detail: 'Scan .claude/agents/ for assessment agents, apply scope filter' },
+    { title: 'Discovery',      detail: 'Run ai-toolkit list-assets --category agents --format json, apply scope filter' },
     { title: 'Assessment',     detail: 'Dispatch all assessment agents in parallel' },
     { title: 'Interventions',  detail: 'Run intervention-documentation-standard on all findings' },
     { title: 'Estimates',      detail: 'Write Token-Estimate and Effort-Estimate files' },
@@ -66,17 +66,14 @@ const SCOPE_AGENT_MAP = {
 }
 
 const discovery = await agent(
-  `Scan .claude/agents/ and list all assessment agents.
-
-An assessment agent is a .md file whose name or description contains one of: "assessment", "audit", "analysis".
-Exclude orchestrators (files containing "manager" in their name).
-Exclude remediation-only agents (files containing "refactoring", "hardening", "decomposition" in their name UNLESS they also contain "assessment" or "audit").
-
-For each matching agent, read its frontmatter and extract:
-- name (from the name: field in frontmatter)
-- description (from the description: field)
-
-Return { "assessment_agents": [ { "name": "...", "description": "..." }, ... ] }`,
+  `Run this command and parse its output:\n` +
+  `ai-toolkit list-assets --category agents --format json\n\n` +
+  `The command outputs a JSON array of installed agent file paths (e.g. [".claude/agents/foo.md", ...]).\n` +
+  `For each path in the array, read the file and extract the YAML frontmatter fields: name, description.\n\n` +
+  `An assessment agent is one whose file name or description contains one of: "assessment", "audit", "analysis".\n` +
+  `Exclude orchestrators (files containing "manager" in their name).\n` +
+  `Exclude remediation-only agents (files containing "refactoring", "hardening", "decomposition" in their name UNLESS they also contain "assessment" or "audit").\n\n` +
+  `Return { "assessment_agents": [ { "name": "...", "description": "..." }, ... ] }`,
   {
     label:  'discover-assessment-agents',
     phase:  'Discovery',