Adds a new `wtcraft cost [--all]` subcommand that reads
~/.claude/projects/**/*.jsonl and aggregates token usage (input, output,
cache_read, cache_write) and estimated USD cost by git branch. No API key
or proxy required — purely local JSONL parsing.

Default view filters to branches visible in the current repo's active
worktrees. --all shows every branch on record.

Implemented in src/wtcraft/_cost.py (Python); _cli.py intercepts the
`cost` argv before delegating to bash, so the shell script needs no JSON
parsing. Help text added to shell script for `wtcraft help cost`.

https://claude.ai/code/session_01A5oU4c7YSGpwatMA2PK1AE

https://claude.ai/code/session_01A5oU4c7YSGpwatMA2PK1AE

- docs/budget.md: full spec for the upcoming wtcraft budget command —
  covers hybrid config model (planner.md frontmatter + env vars),
  real-time event hooks (velocity, cache, model recommendations),
  CLI design, and supported agent log parsers
- docs/roadmap.md: promote Phase 4 goal to include budget control and
  link to the new budget.md spec
- README.md: add positioning callout for budget-aware, zero-bloat
  multi-agent orchestration

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

…racking

Vendor-name routing (preferred: claude) is too coarse — within one
family, Haiku / Sonnet / Opus differ by an order of magnitude in price,
reasoning depth, and throughput. Putting them in one bucket throws away
the most important routing signal.

D5 now uses model-level identifiers (claude-opus-4-7, codex-gpt-5.3,
gemini-3.5-flash, …) with a 4-role example that assigns:

- planner: Opus — strong reasoning, few calls, premium worth it
- executor: Codex (GPT-5.3) — main workhorse, JSON event stream
- verifier: Gemini Flash — long-context diff reading, cheapest tier
- finisher: Opus — commit message / PR body quality

The pattern is intentional: priciest model goes where call count is
lowest, cheapest model goes where bulk reading happens. Same-vendor
fallback (Opus → Sonnet) is also enabled — quota-aware routing matters
within a family as much as across.

Adds a new Investigation TODO item for the model identifier scheme:
who owns the mapping from CLI invocation to model string, how to
handle aliases vs pinned ids, how to detect retired names, and whether
to normalize across vendors. Routing examples in D5 remain
documentation-only until this lands.

…EADME

Three layered changes addressing the same concern — pinned model ids
(claude-opus-4-7, codex-gpt-5.3, gemini-3.5-flash) in the D5 routing
example will go stale within months as vendors ship new variants and
retire old names.

- Top-of-doc maintenance callout: warns any reader past ~90 days from
  the last commit that example values are likely stale, and points at
  the alias-resolution proposal as the long-term fix.
- After-YAML alias-resolution proposal: contracts use semantic aliases
  (claude-opus-latest, *-best-reasoning-*, *-cheapest-fast-*) that the
  runtime resolves at handoff time against an updatable mapping table
  (.wtcraft/models.yaml, refreshable via wtcraft sync-models).
  Contracts stay readable across model generations; registry is the
  single point of maintenance instead of every task file.
- README Docs section now links to handoff-and-routing.md with a
  parenthetical noting the maintenance requirement, so new users
  discover the planning doc and its caveat without having to dig
  through the roadmap.