budget

budget — Token Budget Matrix (optional, before gate 2)

Turn the plan's hand-waved budget heuristics into principled numbers. You estimate the token cost of each phase from signals already in the plan, present a matrix, and fill the phase_budget / run_budget fields the loop already consumes (phase_budget → early-escalation signal; run_budget → clean-stop cap).

This step is OPTIONAL. Small plans (few light phases) don't need it — the default heuristics are fine. When the plan looks small, say so and offer the choice as a lettered list (mark one Recommended) rather than deciding silently:

This plan is small (few light phases). Estimate the budget? a) Skip — Recommended, default heuristics are fine here; return to gate 2 b) Run the matrix anyway — you want a cost ceiling set with eyes open

It is worth running when the plan is large, has heavy phases, declares parallel groups, or the user wants a cost ceiling set with eyes open — recommend (b) in those cases.

Timing matters. Run AFTER plan-design has decomposed phases but BEFORE gate-2 approval — the budgets you write become part of the FROZEN contract, approved by the human alongside the phase list. Never edit an already-frozen plan; if invoked on one, re-open it explicitly for re-approval.

It is NOT a gate and NEVER blocks. Estimates are rough by nature. Present ranges and order-of-magnitude, never false precision. The human still decides at gate 2.

Step 1 — Load inputs

• Read the target docs/forge/plans/plan-NNN.md: phases, their tier, process, covers (AC IDs), depends_on, and any ## Parallel Groups.
• Read the PRD docs/forge/prd/NNN-name.md for AC complexity (a multi-clause Given/When/Then costs more than a one-liner).
• Read docs/context/lessons.md — if past runs recorded actual phase costs, calibrate against them instead of priors.

Step 2 — Estimate per phase (drivers, not guesses)

Estimate each phase from these drivers. Treat the anchors as order-of-magnitude priors, not promises: