Spec 17: burn projector v2 — month-end forecast + alert thresholds

[0bserver07]

Goal

Project month-end spend from current burn rate; surface "you'll hit your plan limit by day N" before the user runs out of budget, plus configurable alert thresholds (50% / 75% / 90%).

Why now

stackunderflow plan already tracks budgets. Today it shows used / remaining; users have to do the projection in their head. Plan show should answer "am I going to overrun?" automatically.

Schema

None. Pure read-side over usage_events (post-v0.8.0 cost-fix path) + plans table. Settings keys for thresholds.

User-visible surface

• CLI: stackunderflow plan show already exists; extend output with projected_month_end_usd, projection_method (linear / weighted-7d), days_to_limit, and a "alert" line when crossing a threshold.
• CLI: stackunderflow plan thresholds set 50 75 90 to configure (settings-backed).
• API: extend /api/plan response with the new fields.
• MCP / meta-agent tool: get_burn_projection() returns the same dict so the meta-agent can answer "will I overrun this month?".
• UI: Plan tab gains a forecast strip + amber/red banner when over a threshold.

Implementation plan

1. New service stackunderflow/services/burn.py — pure functions linear_projection(daily_costs), weighted_projection(daily_costs, decay=0.85), days_to_limit(spent, daily_avg, limit).
2. Extend routes/plan.py to include the projection block.
3. CLI extension to plan show + new plan thresholds set/show.
4. MCP + meta-agent tool entry.
5. Frontend forecast strip on Plan tab.

Tests

• Linear vs weighted projections on synthetic daily-cost arrays.
• Edge cases: empty store, single day, day 1 of month, overrun-already-happened.
• Threshold-crossed detection at 50/75/90.

Hard parts

• "Day N" math when current day-of-month is mid-month — need to project forward from today, not from day 1.
• Time-zone handling for "month boundary" (use settings-configured TZ if set, else UTC).

Out of scope

• Email / Slack notifications when threshold crosses (separate spec — webhook surface).
• Multi-plan budgets per project.

Dependencies

• None.

Estimated effort

Size S — single agent, ~30 min.

Hard rules

• DO NOT touch versions or move CHANGELOG headings.
• Branch: feat/burn-projector-v2 off main.
• See docs/HANDOFF.md for standing rules.