gdd-budget

name	gdd-budget
description	Forecasts GDD design-cycle spend before the bill arrives. Reads .design/telemetry/costs.jsonl (cost per cycle) + .design/budget.json (the project_cap), runs the pure cost-forecast model via agents/cost-forecaster.md, and projects the next N cycles - surfacing 'at the current rate you'll hit your $X project cap in Y cycles.' Supports --scenario best|typical|worst and --cycles N. Read-only - it forecasts and warns; it never spends, edits budget.json, or halts (the budget-enforcer hook halts). Use to sanity-check spend trajectory before a long run.
argument-hint	[--cycles N] [--scenario best|typical|worst]
user-invocable	true
tools	Read, Bash, Grep, Glob, ToolSearch, Task

{{command_prefix}}budget

Closes the long-horizon cost gap: Phase 10.1 per-task caps + Phase 26 per-runtime telemetry track cost, but nothing forecasts it. This skill projects the next N cycles of spend and tells you how many cycles you have before you hit your project_cap. Read-only - it forecasts and warns; it never spends, never edits budget.json, and never halts (the Phase 25 budget-enforcer hook is the only thing that blocks a spawn). Contract: ../../reference/cost-governance.md.

Invocation

Command	Behavior
{{command_prefix}}budget	Typical-scenario forecast over the next 5 cycles + cycles-to-cap.
{{command_prefix}}budget --cycles N	Forecast over the next N cycles.
{{command_prefix}}budget --scenario best|typical|worst	Pick the projection rate (best / steady / worst).

Steps

1. Check telemetry exists. No .design/telemetry/costs.jsonl (or zero rows) → print budget: no cost telemetry yet — run a cycle first. and exit.
2. Delegate to cost-forecaster (via Task): it groups est_cost_usd by cycle, runs the pure scripts/lib/budget/cost-forecast.cjs model for the requested --scenario/--cycles, reads project_cap_usd from .design/budget.json, and computes cycles-to-cap.
3. Render. Show: the scenario + its per-cycle rate, the best↔worst band, the projected total over N cycles, and - when project_cap_usd > 0 - "at the <scenario> rate (~$X/cycle) you'll reach your $<cap> project cap in <Y> cycles" (or "not at this rate" when the trend is flat/down). When no cap is set, show the trajectory and note that project_cap_usd is unset (so the hook won't halt).
4. Do not act. Never raise/lower the cap, never spend - GDD forecasts; the human sets the budget.

Output

End with:

## BUDGET COMPLETE