roadmap: #205 filed — prunable worktree lifecycle audit trail missing, no creation timestamp, pinpoint ID, or doctor visibility (Q *YeonGyu Kim cycle #137 / Jobdori cycle #351)

ROADMAP.md

@@ -12419,3 +12419,90 @@ grep -rE 'kind:.*=' src/ | grep -v test | wc -l
 **Status:** Open. No code changed. Filed 2026-04-25 07:47 KST. Branch: feat/jobdori-168c-emission-routing. HEAD: 0730183.
 
 🪨
+
+---
+
+## Pinpoint #204 — `TokenUsage` omits `reasoning_tokens`: reasoning models silently merge reasoning tokens into `output_tokens`, breaking cost estimation parity (Jobdori, cycle #336 / anomalyco/opencode #24233 parity gap)
+
+**Observed:** `rust/crates/runtime/src/usage.rs` defines `TokenUsage` with four fields: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens`. There is no `reasoning_tokens` field. `grep -rn "reasoning_tokens" rust/crates/` returns zero results. When reasoning models (OpenAI o3/o4-mini, xAI grok-3-mini, Alibaba QwQ/Qwen3-Thinking) are used, the chain-of-thought / reasoning tokens are indistinguishably merged into `output_tokens`.
+
+**Gap:**
+- Provider APIs (OpenAI, Anthropic, xAI) return separate `reasoning_tokens` counts in their usage responses for reasoning models
+- claw-code's `TokenUsage` struct discards this information — it is never parsed, stored, or surfaced
+- `UsageCostEstimate` (also in `usage.rs`) prices `output_tokens` at a flat rate (`DEFAULT_OUTPUT_COST_PER_MILLION: f64 = 75.0`). Reasoning tokens are typically priced differently from regular completion tokens (often cheaper or differently tiered)
+- Cost estimates for reasoning-model sessions are therefore materially inaccurate
+- anomalyco/opencode PR #24233 (`fix(provider): honor per-model reasoning token pricing`) exists to fix exactly this in the reference implementation; claw-code has the same gap with no tracking field
+- `claw doctor` cannot report "this session used X reasoning tokens" or price them separately
+
+**Repro:**
+```
+# Run a session with o3 or grok-3-mini
+# Provider response includes usage.reasoning_tokens = 5000, completion_tokens = 500
+# claw-code TokenUsage records: input_tokens=..., output_tokens=5500 (merged)
+# UsageCostEstimate prices all 5500 at $75/million regular output rate
+# Actual cost should be: 500 reasoning tokens @ reasoning_rate + 5000 output @ output_rate
+```
+
+**Expected:**
+- `TokenUsage` includes `reasoning_tokens: u32`
+- Provider response parsing extracts `reasoning_tokens` when present (OpenAI `usage.completion_tokens_details.reasoning_tokens`, Anthropic `usage.output_tokens` breakdown, etc.)
+- `UsageCostEstimate` includes `reasoning_cost_usd` priced via per-model `reasoning_cost_per_million`
+- `claw doctor` surfaces reasoning token counts and their cost contribution
+- Event taxonomy includes `reasoning_tokens` field
+
+**Fix sketch:**
+1. Add `reasoning_tokens: u32` to `TokenUsage` struct (with backward-compatible default 0)
+2. Update provider response parsers (OpenAI-compat, Anthropic, xAI) to extract reasoning token counts from provider-specific usage fields
+3. Add `reasoning_cost_per_million: f64` to `ModelPricing` with per-model defaults
+4. Update `UsageCostEstimate` to include `reasoning_cost_usd` and `total_cost_usd()` to sum it
+5. Update `usage_to_json` / `usage_from_json` to serialize/deserialize `reasoning_tokens`
+6. Add to classifier event taxonomy and `claw doctor` output
+
+**Status:** Open. No code changed. Filed 2026-04-25 12:00 KST. Branch: feat/jobdori-168c-emission-routing. Parity gap with anomalyco/opencode #24233.
+
+🪨
+
+---
+
+## Pinpoint #205 — prunable worktree set has no lifecycle audit trail: no creation timestamp, no associated pinpoint ID, no merged/abandoned status, no doctor visibility (Q *YeonGyu Kim, cycle #137 / Jobdori cycle #351)
+
+**Observed:** Probing the b3/b4/b5 worktree batch reveals 19 worktrees in `/tmp/` all flagged prunable, with zero machine-readable accounting. There is no record of:
+- When each worktree was created
+- Which pinpoint or issue it targets
+- Whether its associated branch is merged, abandoned, or in-flight
+- What state the work is in (dirty/clean/blocked)
+
+`claw doctor` does not surface worktree state — operators cannot distinguish "abandoned worktree safe to prune" from "in-flight work parked overnight" without manual inspection of each.
+
+**Gap:**
+- `git worktree list --porcelain` provides path/HEAD/branch but no creation time, no purpose, no lifecycle stage
+- Pinpoint-driven worktrees (e.g. `feat/jobdori-XXX-pinpoint-name`) carry intent in the branch name only — not in any structured metadata
+- Stale worktrees accumulate indefinitely; `b3/b4/b5` batch shows 19 prunable with no trail of when/why they were created
+- This compounds with #196 (local branch namespace accumulation) and #194 (prunable-worktree accumulation, no gate)
+
+**Repro:**
+```
+cd /tmp && git worktree list --porcelain
+# Shows N worktrees
+# Each line: worktree <path>, HEAD <sha>, branch <name>
+# No creation timestamp, no pinpoint ID, no status field
+claw doctor
+# No worktree section, no audit trail
+```
+
+**Expected:**
+- Worktree metadata sidecar (`.git/worktree-meta.json` or per-worktree `WORKTREE_META`) recording: creation timestamp, target pinpoint/issue ID, intent string, status enum
+- `claw doctor --worktrees` sub-report listing all worktrees with creation age, pinpoint ID, branch state (ahead/behind origin), dirty status
+- Auto-prune candidate detection: worktrees older than N days with no commits ahead of origin AND associated branch merged
+- Optional: `claw worktree create --pinpoint #N --intent "..."` CLI to enforce metadata at creation
+
+**Fix sketch:**
+1. Add `WorktreeMetadata { created_at_ms, pinpoint_id, intent, status }` struct
+2. Persist sidecar at worktree creation time (~/.claw/worktrees/<worktree-name>.json or .git/worktree-meta/<name>.json)
+3. Add `claw doctor --worktrees` subcommand that lists worktrees + metadata + computed status
+4. Add prune-candidate detection logic
+5. ~40 LOC + integration test
+
+**Status:** Open. No code changed. Filed 2026-04-25 17:16 KST by Q *YeonGyu Kim, formalized to ROADMAP by Jobdori cycle #351. Branch: feat/jobdori-168c-emission-routing.
+
+🪨