@hegemonart/get-design-done 1.19.6 → 1.20.0

package/skills/settings/SKILL.md

@@ -2,18 +2,18 @@
 name: gdd-settings
 description: "Manage .design/config.json settings. Subcommands: profile, parallelism, cleanup, show."
 argument-hint: "<profile <name>|parallelism <key> <value>|cleanup|show>"
-tools: Read, Write, AskUserQuestion, Bash
+tools: Read, Write, AskUserQuestion, Bash, mcp__gdd_state__get, mcp__gdd_state__frontmatter_update
 ---
 
 # gdd-settings
 
-Manages `.design/config.json` — the per-project config for model profile and parallelism. See `reference/config-schema.md` for the full schema.
+Manages `.design/config.json` — the per-project config for model profile and parallelism. See `reference/config-schema.md` for the full schema. This skill also supports patching non-stage STATE.md frontmatter keys (`cycle`, `wave`, custom keys) via `mcp__gdd_state__frontmatter_update`. See **STATE.md frontmatter** below.
 
 ## Subcommands
 
 ### `show`
 
-Print the current `.design/config.json` contents, nicely formatted. If the file is missing, print the defaults with a note that no config exists yet.
+Print the current `.design/config.json` contents, nicely formatted. If the file is missing, print the defaults with a note that no config exists yet. Also call `mcp__gdd_state__get` to print the current STATE.md frontmatter keys (cycle, wave, model_profile) alongside config.json for a unified view.
 
 ### `profile <name>`
 
@@ -50,6 +50,14 @@ Always:
 2. Merge the single field being changed — never overwrite unrelated fields.
 3. Write back as pretty JSON (2-space indent, trailing newline).
 
+## STATE.md frontmatter
+
+For any STATE.md frontmatter patch (cycle, wave, or project-custom keys), call `mcp__gdd_state__frontmatter_update({ patch: { <key>: <value> } })`. Do not `Edit` or `Write` STATE.md directly.
+
+**Stage-patch guard:** this skill cannot patch `stage`. If the user attempts to set `stage` here, reject with: "Use /gdd:brief, /gdd:explore, etc. for stage transitions. The settings skill is for non-stage frontmatter only." The MCP tool itself rejects `stage` patches with a VALIDATION error (surfaced by `mcp__gdd_state__frontmatter_update`), which this prose surfaces up-front so the user gets a clear message before the tool round-trip.
+
+This surface is STATE.md-only. `.design/config.json` mutations continue to use `Read` + `Write` directly (out of scope for the 11-tool MCP catalog).
+
 ## Default Config
 
 If `.design/config.json` does not exist, create it with:

package/skills/todo/SKILL.md

@@ -2,12 +2,12 @@
 name: gdd-todo
 description: "Design backlog — add/list/pick design tasks. Writes to .design/TODO.md."
 argument-hint: "<add|list|pick> [text]"
-tools: Read, Write, AskUserQuestion
+tools: Read, Write, AskUserQuestion, mcp__gdd_state__get, mcp__gdd_state__add_decision, mcp__gdd_state__add_must_have
 ---
 
 # /gdd:todo
 
-**Role:** Design todo list. Three subcommands: `add`, `list`, `pick`. Backing store: `.design/TODO.md`.
+**Role:** Design todo list. Three subcommands: `add`, `list`, `pick`. Backing store: `.design/TODO.md`. For items that are pipeline-level decisions or must-haves (not free-form backlog), route through the `gdd-state` MCP tools instead — see **Pipeline-linked items** below.
 
 ## File format
 
@@ -37,7 +37,8 @@ If text omitted, use `AskUserQuestion`: "What todo item? (include priority P0-P3
 Create TODO.md from the template above if missing.
 
 ### list
-Read `.design/TODO.md`. Print all `- [ ]` and `- [-]` items grouped by priority section, with index numbers.
+1. Call `mcp__gdd_state__get` → pipeline-level decisions + must-haves (shown as context at the top).
+2. Read `.design/TODO.md` (file outside the MCP catalog). Print all `- [ ]` and `- [-]` items grouped by priority section, with index numbers.
 
 ### pick
 Read `.design/TODO.md`. Collect unchecked items. Use `AskUserQuestion` to let the user pick one. Rewrite the chosen line as:
@@ -46,9 +47,17 @@ Read `.design/TODO.md`. Collect unchecked items. Use `AskUserQuestion` to let th
 ```
 Print "Picked: <item>".
 
+## Pipeline-linked items
+
+When the user promotes a todo to a pipeline decision or must-have, route through MCP instead of TODO.md:
+
+- Decision → `mcp__gdd_state__add_decision` with `{ id: "D-XX", text: "...", status: "locked"|"tentative" }`.
+- Must-have → `mcp__gdd_state__add_must_have` with `{ id: "M-XX", text: "...", status: "pending" }`.
+
 ## Constraints
 
 - Do not modify files outside `.design/`.
 - Preserve existing sections and ordering on write.
+- Do not mutate STATE.md directly — use the MCP tools above.
 
 ## TODO COMPLETE

package/skills/verify/SKILL.md

@@ -3,6 +3,7 @@ name: verify
 description: "Stage 5 of 5 — spawns design-auditor, design-verifier, and design-integration-checker in sequence; interprets pass/gap result; handles gap-response loop with inline fix (Phase 5 will add AGENT-12 remediation agent). Thin orchestrator."
 argument-hint: "[--auto]"
 user-invocable: true
+tools: mcp__gdd_state__get, mcp__gdd_state__transition_stage, mcp__gdd_state__add_must_have, mcp__gdd_state__add_blocker, mcp__gdd_state__resolve_blocker, mcp__gdd_state__update_progress, mcp__gdd_state__set_status, mcp__gdd_state__checkpoint, mcp__gdd_state__probe_connections
 ---
 
 # Get Design Done — Verify
@@ -13,11 +14,30 @@ user-invocable: true
 
 ## State Integration
 
-1. Read `.design/STATE.md`.
-   - If missing: create minimal skeleton from `reference/STATE-TEMPLATE.md` with `stage=verify`, `status=in_progress`; log warning to user: "No STATE.md found — creating minimal skeleton."
-   - If present and `stage==verify` and `status==in_progress`: RESUME — if `.design/DESIGN-VERIFICATION.md` exists, pick up from the gap-response loop (skip re-spawning agents, go to Step 2). Otherwise re-spawn all three agents from Step 1.
-   - Otherwise: normal transition — set `stage=verify`, `status=in_progress`, `task_progress=0/3`.
-2. Update `<connections>`, `last_checkpoint`. Write STATE.md.
+### Stage entry
+
+1. `mcp__gdd_state__transition_stage` with `to: "verify"`.
+2. `mcp__gdd_state__get` → snapshot `state`. Read `state.must_haves` — this is the verification checklist; each M-XX starts at `status: pending` and will be flipped to `pass` or `fail` as verification concludes.
+3. Resume detection (read `state.position.status` from the snapshot):
+   - If `status==in_progress` and `.design/DESIGN-VERIFICATION.md` exists: RESUME — skip re-spawning agents, go to Step 2 (gap-response loop).
+   - Otherwise: call `mcp__gdd_state__update_progress` with `task_progress: "0/3"`, `status: "in_progress"` to open the stage, then proceed to Step 1.
+4. If STATE.md is missing entirely (edge case — verify is never the entry point): block with "No STATE.md found — run /get-design-done:discover first." Do NOT attempt to create a skeleton from verify; upstream stages own bootstrap.
+
+---
+
+## Flipping a must-have status
+
+When verification concludes that M-XX is satisfied (or failed), record the result by issuing:
+
+`mcp__gdd_state__add_must_have` with the SAME `id` as the existing entry and the updated `status`:
+
+```json
+{ "id": "M-03", "text": "Dark mode toggle persists to localStorage", "status": "pass" }
+```
+
+The gdd-state mutator treats an `add_must_have` with an existing id as an **update-in-place**, not a duplicate append. The entry's position in the `<must_haves>` block is preserved. This is intentional design — verify doesn't need a dedicated `update_must_have_status` tool because `add_must_have` handles both cases correctly.
+
+Pass the original `text` verbatim when you're only flipping the status; supplying a changed `text` overwrites the prose in-place as well (useful when the M-XX description was imprecise and the verifier can restate it). Omit `text` by passing the value from the earlier `mcp__gdd_state__get` snapshot.
 
 ---
 
@@ -37,7 +57,7 @@ Step P2 — Live tool call:
   → Error containing "permission"/blocked → preview: permission_denied
   → Any other error                       → preview: unreachable
 
-Write preview status to .design/STATE.md <connections>.
+Record the preview probe result via `mcp__gdd_state__probe_connections` (batched with the storybook and chromatic probes below — one call per stage, see "Batched connections write" at the end of this section).
 ```
 
 When `preview: available`, the design-verifier agent runs Phase 4B — Screenshot Evidence to resolve `? VISUAL` heuristic flags with real screenshot evidence. See `agents/design-verifier.md` Phase 4B for the screenshot evidence loop.
@@ -60,13 +80,13 @@ Step B2 — Dev server detection:
       → Returns JSON → storybook: available (compat endpoint)
       → Fails → storybook: unavailable
 
-Write storybook status to .design/STATE.md `<connections>`.
+Record the storybook probe result for the batched `mcp__gdd_state__probe_connections` call (see below).
 
 ---
 
 ### Storybook A11y Loop (when storybook: available)
 
-If `storybook: available` in STATE.md `<connections>`:
+If `state.connections.storybook === "available"` (from the earlier `mcp__gdd_state__get` snapshot):
 1. Run: Bash: npx storybook test --ci 2>&1 | tee .design/storybook-a11y-report.txt
 2. Read .design/storybook-a11y-report.txt — pass to design-verifier as additional a11y evidence
 3. design-verifier reads this file in its a11y gap analysis section and annotates DESIGN-VERIFICATION.md with per-story violations
@@ -91,7 +111,21 @@ Step C2 — Token check:
   → false → chromatic: unavailable
 
 Also check: if storybook: not_configured → chromatic effectively unavailable (emit note, do not run).
-Write chromatic status to .design/STATE.md <connections>.
+Record the chromatic probe result for the batched `mcp__gdd_state__probe_connections` call below.
+
+### Batched connections write
+
+After all three probes (preview, storybook, chromatic) have a verdict, call `mcp__gdd_state__probe_connections` ONCE with `probe_results` = an array of `{ name, status }` entries — one per probed connection. Example:
+
+```json
+[
+  { "name": "preview",   "status": "available" },
+  { "name": "storybook", "status": "unavailable" },
+  { "name": "chromatic", "status": "not_configured" }
+]
+```
+
+Unspecified connections keep their existing value. Do NOT issue multiple `probe_connections` calls — the tool is designed for a single batch write per stage.
 
 ### Chromatic Visual Delta (when chromatic: available)
 
@@ -135,7 +169,7 @@ Also pass post-handoff context to design-auditor: auditor skips DESIGN-PLAN.md r
 - Read `.design/config.json` `parallelism` (or defaults from `reference/config-schema.md`).
 - Apply rules from `reference/parallelism-rules.md`.
 - `design-verifier` depends on `design-auditor` output (rule 1) → serial between those two. `design-integration-checker` is independent of the auditor's *file* output but runs after verifier in the current sequence; if config opts in, `design-auditor` and `design-integration-checker` can parallelize (disjoint writes). Default: serial.
-- Write `<parallelism_decision>` to STATE.md before spawning.
+- Record `<parallelism_decision>` via `mcp__gdd_state__set_status` (e.g., `status: "verify_parallelism_decided: <serial|parallel>"`) before spawning. Do not write STATE.md directly.
 
 ## Step 1 — Spawn Auditor + Verifier + Integration Checker
 
@@ -169,7 +203,7 @@ Emit `## AUDIT COMPLETE` when done.
 """)
 ```
 
-Wait for `## AUDIT COMPLETE` in the agent response. Once detected, update STATE.md `task_progress=1/3`.
+Wait for `## AUDIT COMPLETE` in the agent response. Once detected, call `mcp__gdd_state__update_progress` with `task_progress: "1/3"` and a short `status` summary (e.g., `status: "audit_done"`).
 
 ### 1b-gate. Lazy gate — should design-verifier run?
 
@@ -193,7 +227,7 @@ Spawn the cheap Haiku gate before the expensive verifier:
 
 Wait for `## GATE COMPLETE`. Parse the JSON:
 
-- `spawn: false` → append pending telemetry row `{ts, agent: "design-verifier", tier: "skipped", tokens_in: 0, tokens_out: 0, cache_hit: false, est_cost_usd: 0, lazy_skipped: true, gate_rationale: "<from gate>", cycle, phase}` (PreToolUse hook from 10.1-01 flushes on next tool use; orchestrator MAY stub-append directly to `.design/telemetry/costs.jsonl` until 10.1-05 lands). Skip 1b. Set `task_progress=2/3`. Emit `design-verifier skipped — gate rationale: <rationale>`.
+- `spawn: false` → append pending telemetry row `{ts, agent: "design-verifier", tier: "skipped", tokens_in: 0, tokens_out: 0, cache_hit: false, est_cost_usd: 0, lazy_skipped: true, gate_rationale: "<from gate>", cycle, phase}` (PreToolUse hook from 10.1-01 flushes on next tool use; orchestrator MAY stub-append directly to `.design/telemetry/costs.jsonl` until 10.1-05 lands). Skip 1b. Call `mcp__gdd_state__update_progress` with `task_progress: "2/3"` and `status: "verifier_gate_skipped"`. Emit `design-verifier skipped — gate rationale: <rationale>`.
 - `spawn: true` → proceed to 1b as currently written.
 
 ### 1b. Run design-verifier (reads auditor output as additional input)
@@ -231,7 +265,7 @@ by structured gap list, then `## VERIFICATION COMPLETE`. If no gaps, just emit `
 """)
 ```
 
-Wait for `## VERIFICATION COMPLETE` in the agent response. Once detected, update STATE.md `task_progress=2/3`.
+Wait for `## VERIFICATION COMPLETE` in the agent response. Once detected, call `mcp__gdd_state__update_progress` with `task_progress: "2/3"` and a short `status` summary (e.g., `status: "verifier_done"`).
 
 ### 1c-gate. Lazy gate — should design-integration-checker run?
 
@@ -255,7 +289,7 @@ Same pattern as 1b-gate:
 
 Wait for `## GATE COMPLETE`. Parse JSON:
 
-- `spawn: false` → append `lazy_skipped: true` telemetry row (same shape), skip 1c, set `task_progress=3/3`, emit `design-integration-checker skipped — gate rationale: <rationale>`.
+- `spawn: false` → append `lazy_skipped: true` telemetry row (same shape), skip 1c, call `mcp__gdd_state__update_progress` with `task_progress: "3/3"` and `status: "integration_checker_gate_skipped"`, emit `design-integration-checker skipped — gate rationale: <rationale>`.
 - `spawn: true` → proceed to 1c as currently written.
 
 ### 1c. Run design-integration-checker (post-verification decision wiring check)
@@ -282,7 +316,7 @@ Emit `## INTEGRATION CHECK COMPLETE` when done.
 """)
 ```
 
-Wait for `## INTEGRATION CHECK COMPLETE` in the agent response. Once detected, update STATE.md `task_progress=3/3`.
+Wait for `## INTEGRATION CHECK COMPLETE` in the agent response. Once detected, call `mcp__gdd_state__update_progress` with `task_progress: "3/3"` and a short `status` summary (e.g., `status: "integration_check_done"`).
 
 **Note:** Integration-checker findings (Orphaned and Missing decisions) are treated as additional gaps and fed into the gap-response loop in Step 2 alongside verifier gaps.
 
@@ -300,14 +334,14 @@ Merge verifier gaps (G-NN entries) and integration-checker gaps (Orphaned/Missin
 
 ### If NO gaps from either source (PASS):
 
-- Update STATE.md `<must_haves>`: set each M-XX `status=pass`.
-- Go to **State Update (exit)** with status=completed.
+- For each M-XX from the earlier `mcp__gdd_state__get` snapshot (`state.must_haves`): call `mcp__gdd_state__add_must_have` with the same `id`, the same `text`, and `status: "pass"`. The mutator updates in-place (see "Flipping a must-have status" above).
+- Go to **Stage exit** with status=completed.
 
 ### If GAPS FOUND (from either source):
 
 - Parse all gaps (verifier + integration-checker combined).
 - Count gaps by severity (BLOCKER, MAJOR, MINOR, COSMETIC).
-- If `auto_mode=true`: preserve DESIGN-VERIFICATION.md, update STATE.md `status=blocked`, append `<blockers>` entry: "[verify] [ISO date]: N blockers found — see .design/DESIGN-VERIFICATION.md and integration-checker output". Exit with message:
+- If `auto_mode=true`: preserve DESIGN-VERIFICATION.md, call `mcp__gdd_state__set_status` with `status: "blocked"`, then call `mcp__gdd_state__add_blocker` with `stage: "verify"` and `text: "N blockers found — see .design/DESIGN-VERIFICATION.md and integration-checker output"` (the mutator stamps the ISO date automatically). Exit with message:
   ```
   Verification failed — N gaps found (X blockers, Y majors, Z minors, W cosmetics).
   Report: .design/DESIGN-VERIFICATION.md
@@ -340,9 +374,9 @@ Choose:
 ### If user chose [2] Save and exit:
 
 - Preserve DESIGN-VERIFICATION.md.
-- Update STATE.md: `<position> status=blocked`.
-- Append `<blockers>`: "[verify] [ISO date]: N gaps outstanding — see .design/DESIGN-VERIFICATION.md".
-- Write STATE.md.
+- Call `mcp__gdd_state__set_status` with `status: "blocked"`.
+- Call `mcp__gdd_state__add_blocker` with `stage: "verify"` and `text: "N gaps outstanding — see .design/DESIGN-VERIFICATION.md"` (ISO date stamped by the mutator).
+- Call `mcp__gdd_state__checkpoint` to record the save-and-exit checkpoint.
 - Exit:
   ```
   Gaps saved. Resume with: /get-design-done:verify
@@ -351,9 +385,9 @@ Choose:
 
 ### If user chose [3] Accept as-is:
 
-- Update STATE.md `<must_haves>`: set `status=fail` for each unmet must-have, but proceed to exit.
-- Append `<blockers>`: "[verify] [ISO date]: accepted with N unresolved gaps".
-- Go to **State Update (exit)** with status=completed.
+- For each unmet must-have (from the earlier snapshot, comparing against verifier gaps): call `mcp__gdd_state__add_must_have` with the same `id`, the same `text`, and `status: "fail"` (update-in-place idiom). Then proceed to exit.
+- Call `mcp__gdd_state__add_blocker` with `stage: "verify"` and `text: "accepted with N unresolved gaps"`.
+- Go to **Stage exit** with status=completed.
 
 ### If user chose [1] Fix now:
 
@@ -381,7 +415,7 @@ Context:
   auto_mode: <true|false>
 
 Emit ## FIX COMPLETE when all in-scope gaps have been attempted (partial success is still ## FIX COMPLETE).
-Write a <blocker> entry to .design/STATE.md for any gap that could not be fixed.
+Record any gap that could not be fixed via mcp__gdd_state__add_blocker with stage: "verify".
 """)
 
 Wait for `## FIX COMPLETE` in the agent response before continuing.
@@ -417,11 +451,13 @@ Write updated .design/DESIGN-VERIFICATION.md. Emit ## GAPS FOUND (if any), then
 
 ---
 
-## State Update (exit)
+## Stage exit
 
-1. `<position> status=completed` (or `blocked` for save-and-exit).
-2. `<timestamps> verify_completed_at=<ISO date now>`.
-3. Update `last_checkpoint`. Write STATE.md.
+1. Call `mcp__gdd_state__update_progress` with `task_progress: "<verified>/<total>"` (the total is `state.must_haves.length` from the entry snapshot; verified is the count set to `pass`) and `status: "verify_complete"`.
+2. Call `mcp__gdd_state__set_status` with one of:
+   - `status: "pipeline_complete"` — all must-haves passed and no outstanding gaps.
+   - `status: "verify_failed_requires_loop"` — gaps remain (save-and-exit, accept-as-is with fails, or auto-mode blocker).
+3. Call `mcp__gdd_state__checkpoint` — stamps `frontmatter.last_checkpoint` and appends a `verify_completed_at` timestamp entry. No direct STATE.md writes; the checkpoint tool owns the final persist.
 
 ---
 

package/hooks/budget-enforcer.js

@@ -1,329 +0,0 @@
-#!/usr/bin/env node
-/**
- * budget-enforcer.js — PreToolUse hook (matcher: Agent)
- *
- * Intercepts every Agent tool spawn. Consults:
- *   (a) router decision (from tool_input.context.router_decision if supplied)
- *   (b) .design/cache-manifest.json for short-circuit cached answers (D-05)
- *   (c) .design/budget.json for tier_overrides + caps (D-01, D-04, D-10)
- *
- * Enforcement (D-02, D-03, D-11):
- *   - enforcement_mode: "enforce" + 100% cap → block with actionable error
- *   - enforcement_mode: "enforce" + 80% soft-threshold + auto_downgrade_on_cap → rewrite tier to haiku
- *   - enforcement_mode: "warn" → log warning, allow spawn
- *   - enforcement_mode: "log" → advisory only
- *
- * Logs every decision to .design/telemetry/costs.jsonl (OPT-09 schema).
- * Every telemetry write fires a detached child aggregator (scripts/aggregate-agent-metrics.js)
- * that rebuilds .design/agent-metrics.json incrementally.
- *
- * Hook type: PreToolUse
- * Input:  JSON on stdin { tool_name, tool_input }
- * Output: JSON on stdout { continue, suppressOutput, message, modified_tool_input? }
- */
-
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const readline = require('readline');
-const { spawn } = require('child_process');
-
-const BUDGET_PATH = path.join(process.cwd(), '.design', 'budget.json');
-const MANIFEST_PATH = path.join(process.cwd(), '.design', 'cache-manifest.json');
-const TELEMETRY_PATH = path.join(process.cwd(), '.design', 'telemetry', 'costs.jsonl');
-const PHASE_TOTALS_PATH = path.join(process.cwd(), '.design', 'telemetry', 'phase-totals.json');
-const STATE_PATH = path.join(process.cwd(), '.design', 'STATE.md');
-
-// ---- budget.json loader with defaults per D-12 ----
-function loadBudget() {
-  const defaults = {
-    per_task_cap_usd: 2.00,
-    per_phase_cap_usd: 20.00,
-    tier_overrides: {},
-    auto_downgrade_on_cap: true,
-    cache_ttl_seconds: 3600,
-    enforcement_mode: 'enforce'
-  };
-  if (!fs.existsSync(BUDGET_PATH)) return defaults;
-  try { return { ...defaults, ...JSON.parse(fs.readFileSync(BUDGET_PATH, 'utf8')) }; }
-  catch { return defaults; }
-}
-
-// ---- cumulative phase spend (WR-02) ----
-// Reads from the lightweight phase-totals.json written by aggregate-agent-metrics.js
-// instead of replaying the full costs.jsonl on every hook invocation.
-// Falls back to 0 when the file doesn't exist yet (early in a session).
-function currentPhaseSpend(phase) {
-  if (fs.existsSync(PHASE_TOTALS_PATH)) {
-    try {
-      const data = JSON.parse(fs.readFileSync(PHASE_TOTALS_PATH, 'utf8'));
-      return Number(data.totals?.[phase] || 0);
-    } catch { /* fall through */ }
-  }
-  // Fallback: replay JSONL when phase-totals.json not yet written (first spawn of session).
-  if (!fs.existsSync(TELEMETRY_PATH)) return 0;
-  const lines = fs.readFileSync(TELEMETRY_PATH, 'utf8').split(/\r?\n/).filter(Boolean);
-  let sum = 0;
-  for (const line of lines) {
-    try {
-      const row = JSON.parse(line);
-      if (row.phase === phase) sum += Number(row.est_cost_usd || 0);
-    } catch { /* tolerant */ }
-  }
-  return sum;
-}
-
-// ---- cycle + phase reader (STATE.md frontmatter) ----
-function readCycleAndPhase() {
-  const defaults = { cycle: 'unknown', phase: 'unknown' };
-  if (!fs.existsSync(STATE_PATH)) return defaults;
-  try {
-    const content = fs.readFileSync(STATE_PATH, 'utf8');
-    // Match the first frontmatter block: between opening '---' and next '---'
-    const fm = content.match(/^---\s*\n([\s\S]*?)\n---/);
-    const body = fm ? fm[1] : content;
-    const cycleMatch = body.match(/^cycle:\s*"?([^"\n]+)"?/m);
-    const phaseMatch = body.match(/^phase:\s*"?([^"\n]+)"?/m);
-    return {
-      cycle: cycleMatch ? cycleMatch[1].trim() : 'unknown',
-      phase: phaseMatch ? phaseMatch[1].trim() : 'unknown',
-    };
-  } catch {
-    return defaults;
-  }
-}
-
-// Deprecated alias for plan 01 callers (and any other hook/script that imports this).
-// Returns only the phase string; prefer readCycleAndPhase() for new code.
-function currentPhase() {
-  return readCycleAndPhase().phase;
-}
-
-// ---- cache short-circuit (D-05) ----
-function cacheLookup(agent, inputHash) {
-  if (!fs.existsSync(MANIFEST_PATH)) return null;
-  try {
-    const manifest = JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8'));
-    const entry = manifest.entries?.[`${agent}:${inputHash}`];
-    if (!entry) return null;
-    const age = Date.now() / 1000 - entry.ts_unix;
-    if (age > (manifest.ttl_seconds || 3600)) return null;
-    return entry.result;  // cached blob
-  } catch { return null; }
-}
-
-// ---- tier resolution (D-04) ----
-function resolveTier(agent, agentDefaultTier, overrides) {
-  return overrides?.[agent] || agentDefaultTier || 'sonnet';
-}
-
-// ---- detached aggregator invocation ----
-// Fire-and-forget: do not block the hook. The aggregator reads costs.jsonl tail
-// and rewrites .design/agent-metrics.json atomically.
-function spawnAggregator() {
-  try {
-    const aggregatorPath = path.join(process.cwd(), 'scripts', 'aggregate-agent-metrics.js');
-    if (!fs.existsSync(aggregatorPath)) return; // script not installed — fail open
-    const child = spawn('node', [aggregatorPath], {
-      cwd: process.cwd(),
-      detached: true,
-      stdio: 'ignore',
-      env: { PATH: process.env.PATH },  // IN-02: minimal env; aggregator needs no secrets
-    });
-    child.unref();
-  } catch {
-    // Aggregator failures are non-fatal to the hook.
-  }
-}
-
-// ---- locked-schema row builder (OPT-09) ----
-function buildTelemetryRow(partial) {
-  const { cycle, phase } = partial._cyclePhase || readCycleAndPhase();
-  // The nine mandatory fields per OPT-09, always in this order.
-  const row = {
-    ts: partial.ts || new Date().toISOString(),
-    agent: String(partial.agent || 'unknown'),
-    tier: String(partial.tier || 'unknown'),
-    tokens_in: Number(partial.tokens_in || 0),
-    tokens_out: Number(partial.tokens_out || 0),
-    cache_hit: Boolean(partial.cache_hit),
-    est_cost_usd: Number(partial.est_cost_usd || 0),
-    cycle: partial.cycle || cycle,
-    phase: partial.phase || phase,
-  };
-  // Optional diagnostic fields (Phase 11 reflector ignores unknown fields gracefully).
-  if (partial.tier_downgraded !== undefined) row.tier_downgraded = Boolean(partial.tier_downgraded);
-  if (partial.enforcement_mode !== undefined) row.enforcement_mode = String(partial.enforcement_mode);
-  if (partial.lazy_skipped !== undefined) row.lazy_skipped = Boolean(partial.lazy_skipped);
-  if (partial.block_reason !== undefined) row.block_reason = String(partial.block_reason);
-  return row;
-}
-
-// ---- telemetry writer: append one JSON row to costs.jsonl ----
-function writeTelemetry(partial) {
-  const dir = path.dirname(TELEMETRY_PATH);
-  try {
-    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-    const row = buildTelemetryRow(partial);
-    fs.appendFileSync(TELEMETRY_PATH, JSON.stringify(row) + '\n', 'utf8');
-    // Fire-and-forget aggregator — rebuilds .design/agent-metrics.json incrementally.
-    spawnAggregator();
-  } catch {
-    // Fail open: telemetry must never block the hook.
-  }
-}
-
-// Backward-compat alias (plan 01 called it appendTelemetry; keep it working).
-const appendTelemetry = writeTelemetry;
-
-// ---- main ----
-async function main() {
-  const rl = readline.createInterface({ input: process.stdin });
-  let inputData = '';
-  for await (const line of rl) inputData += line + '\n';
-
-  let parsed;
-  try { parsed = JSON.parse(inputData); } catch { process.exit(0); }
-
-  if (parsed.tool_name !== 'Agent') process.exit(0);  // only guard Agent spawns
-
-  const toolInput = parsed.tool_input || {};
-  const agent = toolInput.subagent_type || toolInput.agent || 'unknown';
-  const inputHash = toolInput._input_hash || null;  // supplied by orchestrator if cache-manager pre-computed it
-
-  // Resolve cycle + phase once so every branch can stamp consistent values.
-  const { cycle, phase } = readCycleAndPhase();
-  const cyclePhase = { cycle, phase };
-
-  // Branch A: lazy-gate signal from plan 10.1-04 agents (design-verifier-gate, etc.).
-  // Gate agents set tool_input.lazy_skipped === true when the heuristic declines
-  // to spawn the full checker. We log a zero-cost row and pass through.
-  if (toolInput.lazy_skipped === true) {
-    writeTelemetry({
-      agent,
-      tier: 'gate',
-      tokens_in: 0,
-      tokens_out: 0,
-      cache_hit: false,
-      est_cost_usd: 0,
-      lazy_skipped: true,
-      _cyclePhase: cyclePhase,
-    });
-    const response = { continue: true, suppressOutput: true };
-    process.stdout.write(JSON.stringify(response));
-    return;
-  }
-
-  const budget = loadBudget();
-
-  // Branch B: cache short-circuit (D-05)
-  if (inputHash) {
-    const cached = cacheLookup(agent, inputHash);
-    if (cached !== null) {
-      writeTelemetry({
-        agent,
-        tier: 'cache',
-        tokens_in: 0,
-        tokens_out: 0,
-        cache_hit: true,
-        est_cost_usd: 0,
-        _cyclePhase: cyclePhase,
-      });
-      const response = {
-        continue: false,  // block the real spawn; orchestrator reads suppressOutput.message for cached blob
-        suppressOutput: false,
-        message: `gdd-budget-enforcer: SkippedCached — returning cached result for ${agent}:${inputHash}`,
-        cached_result: cached,
-      };
-      process.stdout.write(JSON.stringify(response));
-      return;
-    }
-  }
-
-  // Layer B: cap checks (D-02)
-  const estCost = Number(toolInput._est_cost_usd || 0);
-  const phaseSpend = currentPhaseSpend(phase);
-
-  if (budget.enforcement_mode === 'enforce') {
-    // Branch C: 100% per_task cap (hard block)
-    if (estCost >= budget.per_task_cap_usd) {
-      writeTelemetry({
-        agent,
-        tier: toolInput._tier_override || toolInput._default_tier || 'sonnet',
-        tokens_in: Number(toolInput._tokens_in_est || 0),
-        tokens_out: Number(toolInput._tokens_out_est || 0),
-        cache_hit: false,
-        est_cost_usd: estCost,
-        enforcement_mode: budget.enforcement_mode,
-        block_reason: 'per_task_cap',
-        _cyclePhase: cyclePhase,
-      });
-      const response = {
-        continue: false,
-        suppressOutput: false,
-        message: `Budget cap reached for per-task. Estimated: $${estCost.toFixed(4)}, cap: $${budget.per_task_cap_usd.toFixed(2)}. Raise cap in .design/budget.json or retry after next task.`,
-      };
-      process.stdout.write(JSON.stringify(response));
-      return;
-    }
-    // Branch D: 100% per_phase cap (hard block)
-    if (phaseSpend + estCost >= budget.per_phase_cap_usd) {
-      writeTelemetry({
-        agent,
-        tier: toolInput._tier_override || toolInput._default_tier || 'sonnet',
-        tokens_in: Number(toolInput._tokens_in_est || 0),
-        tokens_out: Number(toolInput._tokens_out_est || 0),
-        cache_hit: false,
-        est_cost_usd: estCost,
-        enforcement_mode: budget.enforcement_mode,
-        block_reason: 'per_phase_cap',
-        _cyclePhase: cyclePhase,
-      });
-      const response = {
-        continue: false,
-        suppressOutput: false,
-        message: `Budget cap reached for per-phase (${phase}). Cumulative: $${(phaseSpend + estCost).toFixed(4)}, cap: $${budget.per_phase_cap_usd.toFixed(2)}. Raise cap in .design/budget.json or retry after next phase.`,
-      };
-      process.stdout.write(JSON.stringify(response));
-      return;
-    }
-    // 80% soft-threshold downgrade (D-03): task-scoped, per reference/model-tiers.md
-    if (budget.auto_downgrade_on_cap && estCost >= (0.80 * budget.per_task_cap_usd)) {
-      toolInput._tier_override = 'haiku';
-      toolInput._tier_downgraded = true;
-    }
-  } else if (budget.enforcement_mode === 'warn') {
-    if (estCost >= budget.per_task_cap_usd) {
-      process.stderr.write(`gdd-budget-enforcer WARN: per-task cap will be exceeded ($${estCost.toFixed(4)} >= $${budget.per_task_cap_usd})\n`);
-    }
-  }
-  // enforcement_mode === 'log': no blocking, just telemetry
-
-  // D-04: tier_overrides rewrite
-  if (budget.tier_overrides[agent]) {
-    toolInput._tier_override = budget.tier_overrides[agent];
-  }
-
-  // Branch E: standard spawn-allowed (includes tier-downgraded path D-03)
-  writeTelemetry({
-    agent,
-    tier: toolInput._tier_override || toolInput._default_tier || 'sonnet',
-    tokens_in: Number(toolInput._tokens_in_est || 0),
-    tokens_out: Number(toolInput._tokens_out_est || 0),
-    cache_hit: false,
-    est_cost_usd: estCost,
-    tier_downgraded: !!toolInput._tier_downgraded,
-    enforcement_mode: budget.enforcement_mode,
-    _cyclePhase: cyclePhase,
-  });
-
-  const response = {
-    continue: true,
-    suppressOutput: true,
-    modified_tool_input: toolInput
-  };
-  process.stdout.write(JSON.stringify(response));
-}
-
-main().catch(err => { console.error('budget-enforcer hook error:', err); process.exit(0); });