baldart 3.35.2 → 3.37.0

package/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.37.0] - 2026-05-30
+
+**Two-tier review for `/new`: fast `light` per-card during the loop, one guaranteed FULL pass over the whole batch before merge.** This activates the dormant v3.35.0 Review Profile Selector AND re-introduces an unconditional final full review — together they cut tokens/wall-clock on low-risk cards *without* weakening the merge gate. **No new `baldart.config.yml` keys** — both are changes inside the skill, so the schema-propagation rule does not apply.
+
+> **The design.** `light` (per-card Phase 3.7) is now an **early-feedback optimization**, not the safety gate. The safety gate is the **Final review**, which since this release ALWAYS runs a single FULL `/codexreview` (full agent set) over the **entire batch diff** before merge — no N=1 skip, no cross-card scope reduction. So every line of every card, including any reviewed at `light`, gets a full-depth Codex review at least once before merge. This is what makes activating `light` safe: it shifts the breadth passes (qa-sentinel, api-perf-cost-auditor, doc-reviewer) + CoVe from the per-card loop to the single final pass, rather than dropping them from the merge gate. (The v3.35.0 data gate — which had kept the selector hard-coded to `full` pending consumer telemetry — is lifted by explicit maintainer decision; an adversarial review showed that gate's intended post-hoc telemetry could never have validated it anyway, since the Fix Application Log is blind by construction to blockers `light` *misses*. The final full gate makes that validation question moot.)
+
+### Changed — Review Profile Selector live (per-card early feedback)
+
+- **[framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md)**: Phase 3.7 Step C (sequential) and Team Mode D.4b no longer hard-code `profile = full`. The selector runs as designed — `light` ⟺ Step A matched **0** high-risk triggers **AND** the card's QA profile ∈ {`skip`, `light`}; `full` otherwise. **BUG-0530 invariant preserved**: `light` ≠ skip — Codex adversarial + `code-reviewer` + false-positive gate ALWAYS run per-card; `light` drops only the breadth passes + CoVe.
+
+### Changed — Final review is now an unconditional FULL batch-diff gate (supersedes v3.35.0 scope-reduction)
+
+- **[framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md)** (Final review / Step F.1): the v3.35.0 final-review scope gate (N=1 → skip F.1–F.4; N>1 → reduce to the cross-card surface) is **removed**. The final review now runs Steps F.1–F.5 for **every batch including N=1**, with `review_scope_files` = the **full union** of all touched files, never reduced. F.3 reviews the entire batch diff at full depth (Codex + doc-reviewer + api-perf-cost-auditor + qa-sentinel); F.5 runs the final build. Team mode reaches the same gate via "Post-batch — same as sequential mode" (its prior "cross-card-only scope" note is updated accordingly).
+- **Rationale**: v3.35.0 de-duplicated the final full pass on the assumption that Phase 3.7 had already full-reviewed every card. Selecting `light` breaks that assumption, so the post-batch full pass is re-introduced as the guaranteed merge gate.
+
+### Cost & trade-offs (documented)
+
+- **Net cost**: one full `/codexreview` per batch is re-introduced (the deliberate price of the per-card `light` speed-up). The saving comes from cheaper per-card reviews during the loop; the final pass is paid once per batch, not per card.
+- **Later feedback on `light` cards**: a defect on a `light`-reviewed card may now surface at the final pass rather than at the per-card step — possibly a later fix-cycle. Acceptable: it is still caught before merge.
+- **Revert**: to make Phase 3.7 always-full again, restore `profile = full` (no config kill-switch by design). The final full gate is independent and stays regardless.
+
+## [3.36.0] - 2026-05-30
+
+Adds **opt-in session telemetry** to `/new` and `/prd`: append `-stats` (or `--stats`) to a run and, at the end, the skill writes a per-**agent-role** breakdown of REAL token consumption and wall-clock time. This finally answers "what took the most time and tokens in a `/new` run" — and feeds the v3.35.0 Review Profile Selector **data gate** (still pending precisely because `docs/metrics/` carried no per-role cost data). **No new `baldart.config.yml` keys** — the opt-in is a flag, not a config feature, so the schema-propagation rule does not apply.
+
+> **Zero model-token overhead.** The measurement is a **post-hoc Node script**, not a hook and not LLM self-reporting (the model has no reliable token counter). It reads the Claude Code session transcripts — the orchestrator's `<session>.jsonl` plus every `subagents/agent-*.jsonl` — which already carry `message.usage` (the four token counters) and per-message `timestamp`. On a real `/new` run the bulk of cost lives in the subagents (measured ~53M cumulative subagent tokens vs ~47k orchestrator output), and it is all captured. Cache-read tokens are kept **separate** from fresh input (they bill ~10×cheaper) so the breakdown doesn't mislead.
+
+### Added — `-stats` / `--stats` opt-in session telemetry
+
+- **[framework/scripts/analyze-session-tokens.js](framework/scripts/analyze-session-tokens.js)** (new): post-hoc aggregator. Locates the live transcripts from `$CLAUDE_CODE_SESSION_ID` + the cwd slug, sums the four `usage` counters (`fresh_input` / `cache_read` / `cache_creation` / `output`) **kept separate**, computes per-file wall-clock spans, and maps each subagent file → its role by matching the subagent's first prompt to the `Agent` tool_use `subagent_type` in the main transcript (verified 20/20 on a real `/new` batch; unmatched files bucket as `unknown`). Emits a human-readable `docs/metrics/sessions/<run_id>.md` (per-role table sorted by a weighted `cost_units` figure + totals + caveats) and a machine-readable `TELEMETRY_JSON=` line. **Fail-safe**: any error prints `stats: SKIPPED (<reason>)` and exits 0 — it can never abort a run.
+- **[framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md)**: arg parser strips `-stats` / `--stats` like `-full` and sets an internal `STATS` flag (composes with `-full`). **Phase 8 — Metrics Log** gains a `STATS`-gated step that invokes the script and enriches the same `skill-runs.jsonl` row with a `"cost"` object (`by_role` + `totals` + `run_wall_ms`). Without `-stats`, Phase 8 is byte-for-byte unchanged.
+- **[framework/.claude/skills/prd/SKILL.md](framework/.claude/skills/prd/SKILL.md)**: new **HARD RULE 18** — since `/prd` is conversational (no flag parser), the opt-in is detected once at **Step 1 (Kickoff)** from `$ARGUMENTS` and persisted as `stats_enabled` in the session state file (survives context compression / Step 0 resume). The **Step 7 Metrics Log** reads it and runs the same script (`--skill prd`), enriching its JSONL row identically.
+- **[framework/.claude/skills/prd/assets/state-template.md](framework/.claude/skills/prd/assets/state-template.md)**: new `stats_enabled` header field.
+
+### Notes & caveats
+
+- **Accurate in sequential mode.** Team-mode L0/L1 orchestrators can spawn background / nested sub-orchestrators in *separate* session dirs; their subagents are not under the top-level `<session>/subagents/`. The script detects the gap (Agent spawns in main with no local subagent file) and prints an explicit caveat with the excluded count rather than silently undercounting.
+- The per-role `wall(sum)` reflects active compute time; the headline run wall-clock is the orchestrator span and **includes human idle gaps** — both are labelled in the report.
+
 ## [3.35.2] - 2026-05-30
 
 Resolves the **3.35.1 known follow-up**: a flag introduced in a newer release (e.g. `--on-divergence`, v3.29.0) was rejected by an older global CLI with a cryptic `error: unknown option` **before** the `npx baldart@latest` auto-relaunch could self-upgrade — commander validates options during `program.parse()`, which runs *before* the action handler where the relaunch lives. The `update` command now parses **permissively**, so an unknown flag is captured instead of crashing the parser; the action then transparently relaunches under `@latest` (forwarding the raw argv so the unrecognized flag survives) or, when that isn't possible, emits an **actionable** error instead of commander's cryptic one. **No new `baldart.config.yml` keys** — the schema-propagation rule does not apply.

package/VERSION

@@ -1 +1 @@
-3.35.2
+3.37.0

package/framework/.claude/skills/new/SKILL.md

@@ -37,6 +37,8 @@ Parse the card IDs from the arguments. Cards can be specified as:
 
 If no card IDs are provided, ask the user which cards to implement.
 
+**Opt-in session telemetry (`-stats` / `--stats`)**: strip `-stats` / `--stats` from the args list exactly like `-full` (it is NOT a card ID), and set an internal flag `STATS=true` for this run. When present, Phase 8 additionally measures REAL token + wall-clock cost per agent role (coder, code-reviewer, …) by post-processing the session transcripts — zero model-token overhead, runs in Bash after the work is done. When absent, Phase 8 behaves exactly as before. The flag is batch-scoped and composes with `-full` (`/new FEAT-005 -full -stats`).
+
 ---
 
 ## Context Tracking (CRITICAL)
@@ -1111,7 +1113,7 @@ skill's Phase 1 falls back to deriving Gherkin scenarios from
 
 ### Phase 3 — Doc Review & Sync (code review handled by mandatory Phase 3.7 gate)
 
-> **Note**: Code review is NOT performed in this phase — it is handled by the **mandatory unconditional `/codexreview` gate in Phase 3.7**, which runs per-card BEFORE the Phase 4 commit. The post-batch `/codexreview` in Phase 7 remains as a final cross-card sweep. This Phase 3 focuses exclusively on documentation sync, which must happen per-card (tied to the specific commit).
+> **Note**: Code review is NOT performed in this phase — it is handled by the **mandatory unconditional `/codexreview` gate in Phase 3.7**, which runs per-card BEFORE the Phase 4 commit. The post-batch `/codexreview` in the Final review remains as a final FULL-diff sweep over the entire batch (since v3.37.0 — the guaranteed full-depth merge gate). This Phase 3 focuses exclusively on documentation sync, which must happen per-card (tied to the specific commit).
 
 12. **Update tracker**: phase = "3-doc-review".
 13. Build a **Doc Sync Context** block:
@@ -1285,10 +1287,15 @@ For EVERY card (no conditional skip — the gate ALWAYS runs; only its DEPTH var
    doc-reviewer) and Step 3.5 CoVe — exactly the passes that yield ~nothing on a 0-trigger, QA-light
    diff. The BUG-0530 invariant ("never miss a blocker on a low-risk path") holds because the Codex
    adversarial pass — the one that catches those — always runs.
-   **DATA GATE (BLOCKING for `light`)**: until the consumer's telemetry (`docs/metrics/` Fix
-   Application Log) confirms that `light`-eligible cards have NOT historically produced verified
-   BLOCKER/HIGH at FULL depth, hard-code `profile = full` here. Flip to the selector only after the
-   data passes (no config key — change the line).
+   **ACTIVE since v3.37.0**: the selector above runs as written. Here `light` is an **early-feedback
+   optimization** for the per-card loop — NOT the merge-gate. Safety is guaranteed downstream: since
+   v3.37.0 the **Final review ALWAYS runs a single FULL `/codexreview` over the entire batch diff before
+   merge** (no N=1 skip, no scope reduction — see "Final review → Final-review FULL gate"). So every card
+   reviewed at `light` here still receives a full-depth review before merge; `light` shifts the breadth
+   passes (qa-sentinel, api-perf-cost-auditor, doc-reviewer) + CoVe from the per-card loop to that single
+   final full pass, it does not drop them from the merge gate. The BUG-0530 invariant still holds per-card
+   (Codex adversarial + `code-reviewer` + FP-gate always run in `light`). To make Phase 3.7 always-full
+   again: restore `profile = full` here (the final full gate is independent and stays regardless).
 
    Then dump the card diff (reviewer grounding) and write the lean contract `/codexreview` consumes:
    ```bash
@@ -1400,20 +1407,24 @@ Never block the pipeline indefinitely — recover and continue per the rules abo
 
 Once ALL cards are committed in the worktree:
 
-> **Final-review scope gate (deterministic, since v3.35.0)** — the per-card Phase 3.7 `/codexreview`
-> gate has ALREADY reviewed every card individually before its commit. The final review exists to
-> catch what a per-card pass structurally cannot: **cross-card interactions**. Branch on batch size:
+> **Final-review FULL gate (since v3.37.0 — supersedes the v3.35.0 scope-reduction)** — because
+> Phase 3.7 may now run a card at `light` depth, the per-card pass can NO LONGER be assumed to have
+> full-reviewed every card. The final review is therefore the **unconditional safety gate that makes
+> the Phase 3.7 `light` profile safe**: it ALWAYS runs a single FULL `/codexreview` (full agent set)
+> over the **ENTIRE batch diff** before merge — **no N=1 skip, no cross-card scope reduction**. Every
+> line of every card — including any reviewed at `light` in Phase 3.7 — receives a full-depth Codex
+> review at least once before merge.
+>
+> - Run Steps F.1–F.5 for **EVERY batch, including N=1**. Nothing here is skipped.
+> - `review_scope_files` = the **FULL union** of all touched files across all cards (F.1 step 4 —
+>   NEVER reduced to the cross-card subset).
+> - F.3 invokes the full reviewer set (Codex + doc-reviewer + api-perf-cost-auditor + qa-sentinel)
+>   over that union; F.5 runs the final build.
 >
-> - **Single card (N=1)**: SKIP Steps F.1–F.4 (the lone card is byte-identical to what Phase 3.7
->   already passed — re-review adds nothing). Log:
->   `"Final review (F.1–F.4) skipped — single card already passed /codexreview at Phase 3.7 (PASS), code unchanged since commit"`.
->   Then jump to **Step F.5 and RUN the final build** (`npm run lint && npx tsc --noEmit && npm run build`)
->   — that gate is NOT skipped.
-> - **Multiple cards (N>1)**: run F.1–F.5 but **scope the review to the cross-card surface only**
->   (computed, not discretionary) — see F.1 step 4. If that surface is empty, log
->   `"cross-card review: no shared surface (intersection=∅, depends_on=∅) — F.3 limited to integration sanity"`
->   and run a minimal integration pass (build + type-check across the union) instead of a full
->   per-line re-review. This is a computed scope reduction, NEVER a model-decided skip.
+> Rationale: this re-introduces the post-batch full pass that v3.35.0 de-duplicated away. That
+> de-dup assumed Phase 3.7 had already full-reviewed every card — an assumption broken the moment
+> `light` became selectable. The cost of one full batch-diff review is the deliberate price of the
+> per-card `light` speed-up (explicit maintainer decision, v3.37.0).
 
 ### Step F.1 — Resolve scope
 
@@ -1424,11 +1435,11 @@ Once ALL cards are committed in the worktree:
    git diff --name-only <base-branch>...HEAD
    ```
 3. Read each card's backlog YAML to collect `acceptance_criteria`, `files_likely_touched`.
-4. Build `review_scope_files` as union of card-indicated files + git-touched files. **For N>1 (per
-   the Final-review scope gate above), then REDUCE `review_scope_files` to the cross-card subset**:
-   files appearing in ≥2 cards' File Ownership Map entries ∪ files of any `depends_on`-linked card
-   pair. Record both the full union and the reduced set in the tracker; downstream F.3 reviews the
-   reduced set.
+4. Build `review_scope_files` as the **FULL union** of card-indicated files + git-touched files
+   across ALL cards in the batch. **Since v3.37.0 this union is NEVER reduced** (the v3.35.0
+   cross-card scope-reduction is removed) — the final review is a full-depth pass over the entire
+   batch diff, so cards reviewed at `light` in Phase 3.7 still get a guaranteed full review before
+   merge. Record the union in the tracker; downstream F.3 reviews it in full.
 
 ### Step F.2 — Architecture baseline
 
@@ -2191,7 +2202,7 @@ After ALL agents in the group complete successfully:
 
 4a. **D.4a — Per-card doc gate (consumes D.2, since v3.35.0)** — Do NOT re-spawn `doc-reviewer`. For EACH card in the group, take that card's doc findings from D.2's per-card-attributed output; if any exist, spawn a targeted fix-coder for that card only. (Previously D.4a re-ran doc-reviewer per card — a duplicate of D.2; collapsed to a single attributed D.2 pass. D.4b's per-card `/codexreview` also skips its doc-reviewer via the lean contract, so doc-review now runs once per group instead of ~3× per card.)
 
-4b. **D.4b — Pre-Merge Codex Review Gate (per-card, MANDATORY — UNCONDITIONAL)** — Invoke `/codexreview` for EACH card in the group, one at a time, BEFORE any commit. This mirrors Phase 3.7 of the sequential path and is non-skippable regardless of file paths or perceived risk. Apply the same fix sub-loop: if the consolidated report shows verified BLOCKER/HIGH findings, spawn a fix-coder and re-run `/codexreview <CARD-ID>` (max 2 retries per card). If still BLOCKER/HIGH after retries, ask the user before proceeding to D.5. The D.5 commits MUST NOT happen until every card in the group has a PASS verdict (or explicit user override via `AskUserQuestion`). Log results in the tracker under `## Pre-Merge Codex Review` per card. **Lean + profile (since v3.35.0)**: before each card's `/codexreview`, apply the same Review Profile Selector and write the same `/tmp/codexreview-lean-<CARD-ID>.json` contract as sequential Phase 3.7 Step C — `arch_baseline_path` pointing at `/tmp/arch-baseline-group-<FIRST-CARD-ID>.md`, `skip_doc_reviewer: true`, and `profile: light|full` from (0 triggers + QA ∈ {skip,light}). LIGHT still runs Codex adversarial + code-reviewer + FP-gate (subject to the same DATA GATE: keep `full` until telemetry confirms).
+4b. **D.4b — Pre-Merge Codex Review Gate (per-card, MANDATORY — UNCONDITIONAL)** — Invoke `/codexreview` for EACH card in the group, one at a time, BEFORE any commit. This mirrors Phase 3.7 of the sequential path and is non-skippable regardless of file paths or perceived risk. Apply the same fix sub-loop: if the consolidated report shows verified BLOCKER/HIGH findings, spawn a fix-coder and re-run `/codexreview <CARD-ID>` (max 2 retries per card). If still BLOCKER/HIGH after retries, ask the user before proceeding to D.5. The D.5 commits MUST NOT happen until every card in the group has a PASS verdict (or explicit user override via `AskUserQuestion`). Log results in the tracker under `## Pre-Merge Codex Review` per card. **Lean + profile (since v3.35.0)**: before each card's `/codexreview`, apply the same Review Profile Selector and write the same `/tmp/codexreview-lean-<CARD-ID>.json` contract as sequential Phase 3.7 Step C — `arch_baseline_path` pointing at `/tmp/arch-baseline-group-<FIRST-CARD-ID>.md`, `skip_doc_reviewer: true`, and `profile: light|full` from (0 triggers + QA ∈ {skip,light}). LIGHT still runs Codex adversarial + code-reviewer + FP-gate. The Review Profile Selector is **ACTIVE since v3.37.0** — same status as sequential Phase 3.7 Step C above: `light` is per-card early feedback, and the merge-gate safety is the post-batch **Final-review FULL gate** (a single FULL `/codexreview` over the entire batch diff, which team mode reaches via "Post-batch — same as sequential mode"). To make per-card always-full again, restore `profile = full`; the final full gate stays regardless.
 
 5. **D.5 — Commit** — One commit per card using explicit staging from the ownership map. **NO stash in worktrees** (stashes are globally shared via `refs/stash` — see Phase 4 WORKTREE COMMIT RULE):
    ```bash
@@ -2243,7 +2254,7 @@ Before starting group N, verify ALL cards in groups 0..N-1 are status: done. If
 
 ### Post-batch (same as sequential mode)
 
-After all groups are complete, run the same Final Review, Phase 6 (merge), and Phase 7 (production readiness) as documented above. Team mode is always N>1, so the Final Review applies its deterministic **cross-card-only scope** (per the Final-review scope gate) — not a full per-line re-review.
+After all groups are complete, run the same Final Review, Phase 6 (merge), and Phase 7 (production readiness) as documented above. Since v3.37.0 the Final Review runs a **single FULL `/codexreview` over the entire batch diff** (per the Final-review FULL gate) — no scope reduction — so every team-mode card, including any reviewed at `light` in D.4b, receives a guaranteed full review before merge.
 
 ---
 
@@ -2287,6 +2298,19 @@ and QA quality over time.
 
 5. Note in tracker: `## Metrics Log: WRITTEN (run_id: batch-<FIRST-CARD-ID>)`
 
+6. **Session token telemetry (ONLY when `STATS=true`)** — if the run was invoked with `-stats` / `--stats`:
+
+   Measure REAL per-role token + wall-clock cost by post-processing the session transcripts (zero model-token cost — runs in Bash). Invoke:
+
+   ```bash
+   node .framework/framework/scripts/analyze-session-tokens.js \
+     --skill new --run-id "batch-<FIRST-CARD-ID>" --out-dir docs/metrics
+   ```
+
+   The script reads `$CLAUDE_CODE_SESSION_ID` from the environment and derives the transcript paths itself (do NOT pass `--session` / `--project-dir` — those are test-only overrides). It writes a human-readable breakdown to `docs/metrics/sessions/batch-<FIRST-CARD-ID>.md` and prints a summary plus a final `TELEMETRY_JSON=<json>` line.
+
+   Parse the `TELEMETRY_JSON=` line and **enrich the same skill-runs.jsonl row** you wrote in step 3 by adding a `"cost"` key holding that JSON object (`by_role` + `totals` + `run_wall_ms`). If the script printed `stats: SKIPPED (...)` instead, add `"cost":{"skipped":"<reason>"}` and continue. Echo the script's summary to the user so they see the per-role breakdown.
+
 **If `docs/metrics/skill-runs.jsonl` does not exist**: create it first with `touch docs/metrics/skill-runs.jsonl`.
 **If batch tracker is missing or unreadable**: log "Metrics Log: SKIPPED (tracker not found)" and proceed without blocking.
-**This phase is NON-BLOCKING** — if it fails for any reason, do not abort the run.
+**This phase is NON-BLOCKING** — if it fails for any reason, do not abort the run. The `-stats` step in particular is best-effort: the script is fail-safe (always exits 0), so never let it block the commit.

package/framework/.claude/skills/prd/SKILL.md

@@ -199,6 +199,16 @@ message. You ask questions, wait for answers, and iterate.
     repository, or the consumer has explicitly disabled docs worktrees via
     overlay), STOP and report the error to the user. Do NOT silently fall back
     to writing on the main repo — that defeats the entire purpose of this rule.
+18. **Opt-in session telemetry (`-stats` / `--stats`).** Unlike `/new`, this skill
+    has no flag parser — it is conversational. So detect the opt-in ONCE at **Step 1
+    (Kickoff)**: inspect `$ARGUMENTS` for the token `-stats` or `--stats`. If present,
+    set `stats_enabled: true` in the state-file header (the field exists in
+    `assets/state-template.md`); otherwise `false`. Persisting it in the state file is
+    what makes it survive context compression and Step 0 resume. The Metrics Log step
+    (inside Step 7) reads this field and, when `true`, post-processes the session
+    transcripts for REAL per-role token + wall-clock cost. The token itself is NOT part
+    of the feature description — strip it before recording the user's verbatim feature
+    text in `## Feature Description`.
 
 ---
 
@@ -372,6 +382,15 @@ exactly the correct semantics). No special handling needed.
    {"ts":"<ISO-8601-UTC>","skill":"prd","run_id":"prd-<slug>","prd_slug":"<slug>","cards_created":0,"ac_coverage_ratio":0.0,"isa_count":0,"has_test_plan_pct":0.0,"has_db_indexes_pct":0.0,"discovery_iterations":1,"prd_path":"${paths.prd_dir}/<slug>/PRD.md"}
    ```
 
-3. Add the file to the explicit stage list in validation-phase.md Step 7 point 6 (the stage list is at point 6; point 5 is the invocation of this very Metrics Log step).
+3. **Session token telemetry (ONLY when `stats_enabled: true` in the state file)** — measure REAL per-role token + wall-clock cost by post-processing the session transcripts (zero model-token cost — runs in Bash). Invoke:
 
-**This step is NON-BLOCKING** — if it fails, do not abort. Log "Metrics Log: SKIPPED" in the progress bar. The PRD merge proceeds regardless.
+   ```bash
+   node .framework/framework/scripts/analyze-session-tokens.js \
+     --skill prd --run-id "prd-<slug>" --out-dir "$WORKTREE_PATH/docs/metrics"
+   ```
+
+   The script reads `$CLAUDE_CODE_SESSION_ID` and derives the transcript paths itself (do NOT pass `--session` / `--project-dir` — test-only overrides). It writes `$WORKTREE_PATH/docs/metrics/sessions/prd-<slug>.md` and prints a summary plus a final `TELEMETRY_JSON=<json>` line. Parse that line and add its object under a `"cost"` key on the same JSONL row from step 2; on `stats: SKIPPED (...)` add `"cost":{"skipped":"<reason>"}`. Echo the summary to the user. Add the new `sessions/prd-<slug>.md` file to the explicit stage list too (point 4 below).
+
+4. Add the file(s) to the explicit stage list in validation-phase.md Step 7 point 6 (the stage list is at point 6; point 5 is the invocation of this very Metrics Log step).
+
+**This step is NON-BLOCKING** — if it fails, do not abort. Log "Metrics Log: SKIPPED" in the progress bar. The PRD merge proceeds regardless. The `-stats` script is itself fail-safe (always exits 0).

package/framework/.claude/skills/prd/assets/state-template.md

@@ -1,6 +1,7 @@
 # PRD Session: {{slug}}
 Created: {{YYYY-MM-DD HH:MM}}
 Status: discovery
+stats_enabled: {{true if invoked with -stats/--stats, else false}}
 
 ## Worktree
 - path: {{absolute worktree path returned by worktree-manager nw-docs}}

package/framework/scripts/analyze-session-tokens.js

@@ -0,0 +1,411 @@
+#!/usr/bin/env node
+// Post-hoc session telemetry for /new and /prd (opt-in via `-stats`).
+//
+// Reads the live Claude Code transcripts — the orchestrator's main transcript
+// plus every subagent transcript — and aggregates REAL token usage and wall-clock
+// time by AGENT ROLE (coder, code-reviewer, qa-sentinel, doc-reviewer, …). The
+// data already exists in the transcripts (`message.usage` + `timestamp`), so this
+// costs ZERO model tokens: it runs in Node, after the run, outside the model.
+//
+// Transcript layout (verified):
+//   ~/.claude/projects/<slug>/<session_id>.jsonl                  ← orchestrator (main)
+//   ~/.claude/projects/<slug>/<session_id>/subagents/agent-*.jsonl ← one file per subagent
+//   where slug = cwd with every "/" replaced by "-".
+//
+// Role mapping: each `Agent` tool_use in the main transcript carries
+// `input.subagent_type` (= role) and `input.prompt`. Every subagent file's first
+// user message IS that prompt, so we link file→role by prompt-prefix match
+// (verified 20/20 on a real /new run). Unlinkable files fall back to role
+// "unknown" with a slug-derived label — their token/time data stays accurate.
+//
+// Cache accounting: the four usage counters are kept SEPARATE on purpose.
+// `cache_read` is billed ~10% of fresh input; conflating them would overstate
+// cost and mislead "what consumed the most". A single headline `cost_units`
+// figure weights them: output + fresh_input + cache_creation×1.25 + cache_read×0.1.
+//
+// Usage:
+//   node analyze-session-tokens.js --skill new --run-id batch-FEAT-0001
+//   node analyze-session-tokens.js --skill prd --run-id prd-checkout --out-dir docs/metrics
+//   # test/override (bypass env + cwd derivation):
+//   node analyze-session-tokens.js --skill new --run-id X --session <id> --project-dir <path>
+//
+// Output:
+//   - <out-dir>/sessions/<run_id>.md  — human-readable per-role breakdown + totals
+//   - stdout: same summary, PLUS a final line `TELEMETRY_JSON=<json>` carrying the
+//     totals object for the skill to embed in docs/metrics/skill-runs.jsonl.
+//
+// Fail-safe: ANY error prints `stats: SKIPPED (<reason>)` and exits 0. This script
+// must NEVER abort a /new or /prd run.
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// ---- arg parsing -----------------------------------------------------------
+
+function getArg(name, fallback) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i !== -1 && process.argv[i + 1] ? process.argv[i + 1] : fallback;
+}
+
+// Bail out softly — telemetry is never allowed to break a run.
+function skip(reason) {
+  console.log(`stats: SKIPPED (${reason})`);
+  process.exit(0);
+}
+
+const skill = getArg('skill', 'new');
+const runId = getArg('run-id', null);
+const outDir = getArg('out-dir', path.join('docs', 'metrics'));
+const sessionId = getArg('session', process.env.CLAUDE_CODE_SESSION_ID || null);
+const projectDir = getArg('project-dir', null);
+
+if (!runId) skip('no --run-id provided');
+if (!sessionId) skip('no session id ($CLAUDE_CODE_SESSION_ID unset, no --session)');
+
+// ---- locate transcripts ----------------------------------------------------
+
+function projectSlug(cwd) {
+  // Claude Code stores transcripts under a slug = cwd with "/" → "-".
+  return cwd.replace(/\//g, '-');
+}
+
+let baseDir;
+if (projectDir) {
+  baseDir = projectDir;
+} else {
+  baseDir = path.join(os.homedir(), '.claude', 'projects', projectSlug(process.cwd()));
+}
+
+const mainTranscript = path.join(baseDir, `${sessionId}.jsonl`);
+const subDir = path.join(baseDir, sessionId, 'subagents');
+
+if (!fs.existsSync(mainTranscript)) skip(`main transcript not found: ${mainTranscript}`);
+
+// ---- jsonl helpers ---------------------------------------------------------
+
+function* readLines(file) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    return;
+  }
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    let obj;
+    try {
+      obj = JSON.parse(line);
+    } catch (err) {
+      continue; // tolerate partial / malformed lines
+    }
+    yield obj;
+  }
+}
+
+function contentBlocks(rec) {
+  const c = rec && rec.message && rec.message.content;
+  if (Array.isArray(c)) return c;
+  if (typeof c === 'string') return [{ type: 'text', text: c }];
+  return [];
+}
+
+function blocksText(blocks) {
+  return blocks
+    .map((b) => (typeof b === 'string' ? b : b && typeof b.text === 'string' ? b.text : ''))
+    .join('')
+    .trim();
+}
+
+// Aggregate the four usage counters + wall-clock span of one transcript file.
+function aggregateFile(file) {
+  const acc = {
+    fresh_input: 0,
+    cache_read: 0,
+    cache_creation: 0,
+    output: 0,
+    turns: 0,
+    firstTs: null,
+    lastTs: null,
+  };
+  for (const rec of readLines(file)) {
+    const ts = rec.timestamp ? Date.parse(rec.timestamp) : NaN;
+    if (!Number.isNaN(ts)) {
+      if (acc.firstTs === null || ts < acc.firstTs) acc.firstTs = ts;
+      if (acc.lastTs === null || ts > acc.lastTs) acc.lastTs = ts;
+    }
+    if (rec.type !== 'assistant') continue;
+    const u = (rec.message && rec.message.usage) || null;
+    if (!u) continue;
+    acc.fresh_input += u.input_tokens || 0;
+    acc.cache_read += u.cache_read_input_tokens || 0;
+    acc.cache_creation += u.cache_creation_input_tokens || 0;
+    acc.output += u.output_tokens || 0;
+    acc.turns += 1;
+  }
+  return acc;
+}
+
+function costUnits(a) {
+  return Math.round(a.output + a.fresh_input + a.cache_creation * 1.25 + a.cache_read * 0.1);
+}
+
+function wallMs(a) {
+  return a.firstTs !== null && a.lastTs !== null ? a.lastTs - a.firstTs : 0;
+}
+
+// ---- role map from main transcript -----------------------------------------
+
+// Collect every Agent spawn: { role, promptPrefix } in spawn order.
+const agentSpawns = [];
+for (const rec of readLines(mainTranscript)) {
+  for (const blk of contentBlocks(rec)) {
+    if (blk && blk.type === 'tool_use' && blk.name === 'Agent' && blk.input) {
+      const role = blk.input.subagent_type || 'unknown';
+      const prompt = (blk.input.prompt || '').trim();
+      agentSpawns.push({ role, prompt });
+    }
+  }
+}
+
+function matchRole(firstPrompt) {
+  if (!firstPrompt) return null;
+  for (const s of agentSpawns) {
+    if (!s.prompt) continue;
+    // bidirectional prefix match tolerates truncation on either side
+    if (firstPrompt.startsWith(s.prompt.slice(0, 50)) || s.prompt.startsWith(firstPrompt.slice(0, 50))) {
+      return s.role;
+    }
+  }
+  return null;
+}
+
+// ---- aggregate subagents + main --------------------------------------------
+
+const byRole = new Map(); // role → { agg, agents }
+function addToRole(role, agg) {
+  if (!byRole.has(role)) {
+    byRole.set(role, {
+      fresh_input: 0,
+      cache_read: 0,
+      cache_creation: 0,
+      output: 0,
+      turns: 0,
+      agents: 0,
+      wallSumMs: 0,
+    });
+  }
+  const r = byRole.get(role);
+  r.fresh_input += agg.fresh_input;
+  r.cache_read += agg.cache_read;
+  r.cache_creation += agg.cache_creation;
+  r.output += agg.output;
+  r.turns += agg.turns;
+  r.agents += 1;
+  r.wallSumMs += wallMs(agg);
+}
+
+let subFiles = [];
+if (fs.existsSync(subDir)) {
+  try {
+    subFiles = fs
+      .readdirSync(subDir)
+      .filter((f) => f.endsWith('.jsonl'))
+      .map((f) => path.join(subDir, f));
+  } catch (err) {
+    subFiles = [];
+  }
+}
+
+let unmatchedFiles = 0;
+for (const f of subFiles) {
+  const agg = aggregateFile(f);
+  if (agg.turns === 0 && wallMs(agg) === 0) continue; // empty/aborted subagent
+  // role: first user prompt of the subagent file
+  let firstPrompt = '';
+  for (const rec of readLines(f)) {
+    if (rec.type === 'user') {
+      firstPrompt = blocksText(contentBlocks(rec));
+      break;
+    }
+  }
+  const role = matchRole(firstPrompt);
+  if (!role) unmatchedFiles += 1;
+  addToRole(role || 'unknown', agg);
+}
+
+// orchestrator (main transcript) as its own row
+const mainAgg = aggregateFile(mainTranscript);
+addToRole('orchestrator', mainAgg);
+
+// team-mode nesting caveat: Agent calls in main with no local subagent file
+// (background / nested orchestrators write to a different session dir).
+const localSubCount = subFiles.length;
+const spawnedCount = agentSpawns.length;
+const missingNested = Math.max(0, spawnedCount - localSubCount);
+
+// ---- totals ----------------------------------------------------------------
+
+const totals = {
+  fresh_input: 0,
+  cache_read: 0,
+  cache_creation: 0,
+  output: 0,
+  turns: 0,
+  agents: 0,
+};
+for (const r of byRole.values()) {
+  totals.fresh_input += r.fresh_input;
+  totals.cache_read += r.cache_read;
+  totals.cache_creation += r.cache_creation;
+  totals.output += r.output;
+  totals.turns += r.turns;
+  totals.agents += r.agents;
+}
+totals.cost_units = costUnits(totals);
+
+// run wall-clock = span of the main transcript (first→last timestamp)
+const runWallMs = wallMs(mainAgg);
+
+// ---- formatting helpers -----------------------------------------------------
+
+function fmtTokens(n) {
+  if (n >= 1e6) return `${(n / 1e6).toFixed(1)}M`;
+  if (n >= 1e3) return `${(n / 1e3).toFixed(1)}k`;
+  return String(n);
+}
+function fmtDuration(ms) {
+  if (!ms || ms < 0) return '-';
+  const s = Math.round(ms / 1000);
+  const m = Math.floor(s / 60);
+  const rs = s % 60;
+  return m > 0 ? `${m}m${rs.toString().padStart(2, '0')}s` : `${rs}s`;
+}
+function pad(s, w) {
+  s = String(s);
+  return s.length >= w ? s : s + ' '.repeat(w - s.length);
+}
+function padL(s, w) {
+  s = String(s);
+  return s.length >= w ? s : ' '.repeat(w - s.length) + s;
+}
+
+// rows sorted by cost_units desc
+const roleRows = [...byRole.entries()]
+  .map(([role, r]) => ({ role, ...r, cost_units: costUnits(r) }))
+  .sort((a, b) => b.cost_units - a.cost_units);
+
+// ---- write per-run markdown summary ----------------------------------------
+
+const lines = [];
+lines.push(`# Session telemetry — ${runId}`);
+lines.push('');
+lines.push(`- **skill**: ${skill}`);
+lines.push(`- **session**: ${sessionId}`);
+lines.push(`- **run wall-clock** (orchestrator span, includes idle): ${fmtDuration(runWallMs)}`);
+lines.push(`- **agents**: ${totals.agents - 1} subagent(s) + 1 orchestrator`);
+lines.push(`- **total cost units**: ${fmtTokens(totals.cost_units)}  _(output + fresh_in + cache_creation×1.25 + cache_read×0.1)_`);
+lines.push('');
+lines.push('## By role');
+lines.push('');
+const H = ['role', 'agents', 'wall(sum)', 'output', 'fresh_in', 'cache_cr', 'cache_rd', 'cost_units', '% cost'];
+const W = [20, 7, 10, 9, 9, 9, 9, 11, 7];
+lines.push(H.map((h, i) => pad(h, W[i])).join(' | '));
+lines.push(W.map((w) => '-'.repeat(w)).join('-|-'));
+for (const r of roleRows) {
+  const pct = totals.cost_units ? `${((r.cost_units / totals.cost_units) * 100).toFixed(0)}%` : '-';
+  lines.push(
+    [
+      pad(r.role, W[0]),
+      padL(r.agents, W[1]),
+      padL(fmtDuration(r.wallSumMs), W[2]),
+      padL(fmtTokens(r.output), W[3]),
+      padL(fmtTokens(r.fresh_input), W[4]),
+      padL(fmtTokens(r.cache_creation), W[5]),
+      padL(fmtTokens(r.cache_read), W[6]),
+      padL(fmtTokens(r.cost_units), W[7]),
+      padL(pct, W[8]),
+    ].join(' | ')
+  );
+}
+lines.push(W.map((w) => '-'.repeat(w)).join('-|-'));
+lines.push(
+  [
+    pad('TOTAL', W[0]),
+    padL(totals.agents, W[1]),
+    padL(fmtDuration(runWallMs), W[2]),
+    padL(fmtTokens(totals.output), W[3]),
+    padL(fmtTokens(totals.fresh_input), W[4]),
+    padL(fmtTokens(totals.cache_creation), W[5]),
+    padL(fmtTokens(totals.cache_read), W[6]),
+    padL(fmtTokens(totals.cost_units), W[7]),
+    padL('100%', W[8]),
+  ].join(' | ')
+);
+lines.push('');
+lines.push('> wall(sum) is the sum of per-agent spans and reflects ACTIVE compute time; the');
+lines.push('> run wall-clock is the orchestrator first→last span and INCLUDES human idle gaps.');
+lines.push('> Subagents may run in parallel, so wall(sum) can exceed the run wall-clock.');
+lines.push('> cache_read tokens are ~10% the cost of fresh input — kept separate on purpose.');
+if (unmatchedFiles > 0) {
+  lines.push('>');
+  lines.push(`> ⚠ ${unmatchedFiles} subagent file(s) could not be mapped to a role (bucketed as "unknown").`);
+}
+if (missingNested > 0) {
+  lines.push('>');
+  lines.push(
+    `> ⚠ team-mode caveat: ${missingNested} Agent spawn(s) in the main transcript have no local`
+  );
+  lines.push(
+    `> subagent file (likely background / nested orchestrators in separate sessions) — their`
+  );
+  lines.push(`> tokens are NOT included in these totals. Sequential-mode runs are fully accurate.`);
+}
+lines.push('');
+
+// ---- emit ------------------------------------------------------------------
+
+const sessionsDir = path.join(outDir, 'sessions');
+try {
+  fs.mkdirSync(sessionsDir, { recursive: true });
+  fs.writeFileSync(path.join(sessionsDir, `${runId}.md`), lines.join('\n'));
+} catch (err) {
+  skip(`could not write summary: ${err.message}`);
+}
+
+// human summary to stdout
+console.log(lines.join('\n'));
+
+// machine-readable totals for the skill to embed in skill-runs.jsonl
+const jsonOut = {
+  run_wall_ms: runWallMs,
+  by_role: Object.fromEntries(
+    roleRows.map((r) => [
+      r.role,
+      {
+        agents: r.agents,
+        output: r.output,
+        fresh_input: r.fresh_input,
+        cache_creation: r.cache_creation,
+        cache_read: r.cache_read,
+        cost_units: r.cost_units,
+        wall_sum_ms: r.wallSumMs,
+      },
+    ])
+  ),
+  totals: {
+    agents: totals.agents,
+    output: totals.output,
+    fresh_input: totals.fresh_input,
+    cache_creation: totals.cache_creation,
+    cache_read: totals.cache_read,
+    cost_units: totals.cost_units,
+    turns: totals.turns,
+  },
+  unmatched_subagents: unmatchedFiles,
+  nested_agents_excluded: missingNested,
+};
+console.log(`TELEMETRY_JSON=${JSON.stringify(jsonOut)}`);
+process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "3.35.2",
+  "version": "3.37.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"