feat(#2631): planner emits estimate and plan-checker surfaces the over-budget flag (#2670)

* test(#2631): failing-first planner estimate emission and over-budget surfacing

* feat(#2631): emit plan estimate and surface the over-budget split recommendation

* fix(#2631): extract sizing prose to references to fit planner and plan-phase caps

* fix(#2631): move estimate check to plan-checker; fix template regex and caps

* fix(#2631): restore ALWAYS split literal and keep gsd_run after the launcher preamble

* fix(#2631): invoke estimate-check after the launcher preamble in plan-checker

* fix(#2631): stop double-applying calibration; repair COMMANDS table and stale reference

* chore(#2631): backfill changeset pr to 2670

* chore(#2631): backfill changeset pr to 2670

agents/gsd-plan-checker.md

@@ -252,6 +252,19 @@ issue:
 1. Count tasks per plan
 2. Estimate files modified per plan
 3. Check against thresholds
+4. **Smart-zone estimate check (#2631, ADR-2629).** For each plan carrying an `estimate` block, run the
+   `estimate-check --calibrated` verb against its `estimate.tokens` (the `--calibrated` flag is required —
+   the plan's figure already has the factor applied, and omitting it would square the correction) (invoked in Step 1 below, after the launcher
+   preamble). The verb reads `workflow.smart_zone_tokens` and applies the project's calibration. Report
+   one line per plan: plan id, estimated tokens, the budget, and — when `over_budget` is true — the
+   returned `recommendation`, which names how many slices the phase should become.
+
+   **Over budget is a WARNING, never a blocker** (ADR-2629 Decision 5). Recommend re-slicing into a tracer
+   plus expansion slices; never fail the check on it. Report `estimate.confidence` alongside: `low` means
+   fewer than 3 completed phases carry actuals, so the figure is not yet calibrated for this project — say
+   so rather than presenting it as precise, and weigh the task/file thresholds above more heavily.
+
+   A plan with no `estimate` block is not a defect; the field is optional and additive.
 
 **Thresholds:**
 | Metric | Target | Warning | Blocker |
@@ -706,6 +719,13 @@ gsd_run query phase.list-plans "$phase_number"
 gsd_run query phase.list-artifacts "$phase_number" --type research
 gsd_run query roadmap.get-phase "$phase_number"
 gsd_run query phase.list-artifacts "$phase_number" --type summary
+
+# Smart-zone estimate check (#2631) — advisory, never fails the check.
+for plan in "${phase_dir:-$PHASE_DIR}"/*-PLAN.md; do
+  [ -f "$plan" ] || continue   # unmatched glob leaves the literal pattern — skip it
+  EST=$(sed -n '/^estimate:/,/^[a-z_]*:/p' "$plan" | grep -o 'tokens: *[0-9]*' | head -1 | grep -o '[0-9]*')
+  [ -n "$EST" ] && gsd_run query estimate-check --tokens "$EST" --calibrated 2>/dev/null || true
+done
 ```
 
 **Extract:** Phase goal, requirements (decompose goal), locked decisions, deferred ideas.

agents/gsd-planner.md

@@ -288,30 +288,15 @@ See @~/.claude/gsd-core/references/planner-guidance.md for dependency graph buil
 
 <scope_estimation>
 
-## Context Budget Rules
+## Sizing and the Estimate Block
 
-Plans should complete within ~50% context (not 80%). No context anxiety, quality maintained start to finish, room for unexpected complexity.
+Full rules: @~/.claude/gsd-core/references/context-budget.md (Phase Sizing). Read before sizing.
 
-**Each plan: 2-3 tasks maximum.**
-
-| Context Weight | Tasks/Plan | Context/Task | Total |
-|----------------|------------|--------------|-------|
-| Light (CRUD, config) | 3 | ~10-15% | ~30-45% |
-| Medium (auth, payments) | 2 | ~20-30% | ~40-50% |
-| Heavy (migrations, multi-subsystem) | 1-2 | ~30-40% | ~30-50% |
-
-## Split Signals
-
-**ALWAYS split if:**
-- More than 3 tasks
-- Multiple subsystems (DB + API + UI = separate plans)
-- Any task with >5 file modifications
-- Checkpoint + implementation in same plan
-- Discovery + implementation in same plan
-
-**CONSIDER splitting:** >5 files total, natural semantic boundaries, context cost estimate exceeds 40% for a single plan. See `<planner_authority_limits>` for prohibited split reasons.
-
-See @~/.claude/gsd-core/references/planner-guidance.md for Granularity Calibration table (Coarse/Standard/Fine plans-per-phase).
+- **2-3 tasks per plan.** **ALWAYS split if:** >3 tasks, multiple subsystems, or any task touching >5 files.
+- **Emit `estimate`** in PLAN.md frontmatter: run the `estimate-calibration` query, multiply your raw
+  token projection by its calibration factor, and copy its `confidence` verbatim — derived from the
+  sample count, never self-rated.
+- **Over the smart-zone budget?** Re-slice: tracer + expansion slices. Advisory, never a block.
 
 </scope_estimation>
 
@@ -331,6 +316,11 @@ autonomous: true            # false if plan has checkpoints
 requirements: []            # REQUIRED — Requirement IDs from ROADMAP this plan addresses. MUST NOT be empty.
 user_setup: []              # Human-required setup (omit if empty)
 
+estimate:                   # Projected execution cost (see Estimate Emission)
+  tokens: 60000             # calibrated projection
+  tasks: 3                  # task count the projection assumes
+  confidence: low           # low | med | high — DERIVED from sample count, never self-rated
+
 must_haves:
   truths: []                # Observable behaviors
   artifacts: []             # Files that must exist
@@ -412,6 +402,7 @@ Create `.planning/phases/XX-name/{padded_phase}-{plan}-SUMMARY.md` when done
 | `autonomous` | Yes | `true` if no checkpoints |
 | `requirements` | Yes | **MUST** list requirement IDs from ROADMAP. Every roadmap requirement ID MUST appear in at least one plan. |
 | `user_setup` | No | Human-required setup items |
+| `estimate` | No | Projected cost `{tokens, tasks, confidence}`. See Estimate Emission. |
 | `must_haves` | Yes | Goal-backward verification criteria |
 
 Wave numbers are pre-computed during planning. Execute-phase reads `wave` directly from frontmatter.