@hegemonart/get-design-done 1.19.6 → 1.20.0

package/hooks/context-exhaustion.ts

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+/**
+ * context-exhaustion.ts — PostToolUse hook
+ *
+ * Phase 20 Plan 20-13 rewrite of the original context-exhaustion.js.
+ * Behavior is byte-equivalent: when tool_response reports context
+ * consumption at or above THRESHOLD (default 0.85), the hook writes a
+ * <paused> resumption block into .design/STATE.md so the next session
+ * can resume with full context. Only writes once per session — if a
+ * <paused> block from the same trigger already exists, the hook exits
+ * silently.
+ *
+ * Phase 20 addition: every decision (ok / warn) fires a hook.fired
+ * event to .design/telemetry/events.jsonl via appendEvent() (Plan 20-06).
+ *
+ * Hook type: PostToolUse (any tool)
+ * Input:  JSON on stdin { tool_name, tool_input, tool_response }
+ * Output: JSON on stdout { continue, suppressOutput, message } or nothing
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  appendFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import { createInterface } from 'node:readline';
+
+import { appendEvent } from '../scripts/lib/event-stream/index.ts';
+import type { HookFiredEvent } from '../scripts/lib/event-stream/index.ts';
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+interface ToolResponseMeta {
+  context_usage?: number | string;
+  contextUsage?: number | string;
+}
+interface ToolResponse {
+  context_usage?: number | string;
+  contextUsage?: number | string;
+  metadata?: ToolResponseMeta;
+  meta?: ToolResponseMeta;
+  [key: string]: unknown;
+}
+
+interface HookStdin {
+  tool_name?: string;
+  tool_input?: Record<string, unknown>;
+  tool_response?: ToolResponse;
+  [key: string]: unknown;
+}
+
+interface HookOutput {
+  continue: boolean;
+  suppressOutput?: boolean;
+  message?: string;
+}
+
+/** Hook decision emitted on the event stream. */
+export type HookDecision = 'ok' | 'warn';
+
+// ── Constants ───────────────────────────────────────────────────────────────
+
+/**
+ * Context-usage fraction above which the hook paints a <paused> block.
+ * Override via GDD_CONTEXT_THRESHOLD env var (float in [0,1]).
+ */
+export const THRESHOLD: number = (() => {
+  const raw = process.env['GDD_CONTEXT_THRESHOLD'];
+  const parsed = raw !== undefined ? Number.parseFloat(raw) : Number.NaN;
+  return Number.isFinite(parsed) ? parsed : 0.85;
+})();
+
+const STATE_PATH = join(process.cwd(), '.design', 'STATE.md');
+
+// ── helpers ─────────────────────────────────────────────────────────────────
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+/**
+ * Claude Code injects context usage in several shapes across versions.
+ * Try direct fields, then metadata.meta alias, then string forms
+ * (fraction or percentage). Returns null when no usage data is present.
+ */
+export function extractContextUsage(
+  toolResponse: ToolResponse | null | undefined,
+): number | null {
+  if (typeof toolResponse !== 'object' || toolResponse === null) return null;
+
+  if (typeof toolResponse.context_usage === 'number') return toolResponse.context_usage;
+  if (typeof toolResponse.contextUsage === 'number') return toolResponse.contextUsage;
+
+  const meta: ToolResponseMeta =
+    toolResponse.metadata ?? toolResponse.meta ?? {};
+  if (typeof meta.context_usage === 'number') return meta.context_usage;
+  if (typeof meta.contextUsage === 'number') return meta.contextUsage;
+
+  const raw =
+    toolResponse.context_usage ??
+    toolResponse.contextUsage ??
+    meta.context_usage ??
+    meta.contextUsage;
+  if (typeof raw === 'string') {
+    if (raw.endsWith('%')) return Number.parseFloat(raw) / 100;
+    const n = Number.parseFloat(raw);
+    if (Number.isFinite(n)) return n > 1 ? n / 100 : n;
+  }
+  return null;
+}
+
+export function buildPausedBlock(toolName: string, usage: number): string {
+  const pct = Math.round(usage * 100);
+  const thresholdPct = Math.round(THRESHOLD * 100);
+  return `
+<paused>
+recorded: ${now()}
+trigger: context-exhaustion-hook
+context_usage: ${pct}%
+last_tool: ${toolName}
+
+## Resumption instructions
+
+Context reached ${pct}% during the previous session (threshold: ${thresholdPct}%).
+The session was auto-paused to preserve quality.
+
+To resume:
+1. Run \`/gdd:resume\` — it will read this block and restore working context
+2. If mid-plan: check .design/STATE.md for the last completed task
+3. Re-read the active PLAN.md to orient before continuing
+
+Intel store status at pause time:
+  ls .design/intel/files.json 2>/dev/null && echo "present" || echo "missing"
+</paused>
+`;
+}
+
+export function stateFileHasPausedBlock(): boolean {
+  if (!existsSync(STATE_PATH)) return false;
+  const content = readFileSync(STATE_PATH, 'utf8');
+  return (
+    content.includes('<paused>') &&
+    content.includes('context-exhaustion-hook')
+  );
+}
+
+function appendPausedBlock(block: string): void {
+  if (!existsSync(dirname(STATE_PATH))) {
+    mkdirSync(dirname(STATE_PATH), { recursive: true });
+  }
+  if (!existsSync(STATE_PATH)) {
+    writeFileSync(STATE_PATH, '# Design State\n\n', 'utf8');
+  }
+  appendFileSync(STATE_PATH, block, 'utf8');
+}
+
+// ── event-stream emitter ────────────────────────────────────────────────────
+
+let CACHED_SESSION_ID: string | null = null;
+function getSessionId(): string {
+  if (CACHED_SESSION_ID === null) {
+    const iso = new Date().toISOString().replace(/[:.]/g, '-');
+    CACHED_SESSION_ID = `gdd-hook-${iso}-${process.pid}`;
+  }
+  return CACHED_SESSION_ID;
+}
+
+function emitHookFired(decision: HookDecision): void {
+  const ev: HookFiredEvent = {
+    type: 'hook.fired',
+    timestamp: new Date().toISOString(),
+    sessionId: getSessionId(),
+    payload: { hook: 'context-exhaustion', decision },
+  };
+  try {
+    appendEvent(ev);
+  } catch {
+    // Fail open — event-stream errors must never block the hook.
+  }
+}
+
+// ── main ────────────────────────────────────────────────────────────────────
+
+async function readStdin(): Promise<string> {
+  const rl = createInterface({ input: process.stdin });
+  let data = '';
+  for await (const line of rl) data += line + '\n';
+  return data;
+}
+
+export async function main(): Promise<void> {
+  const inputData = await readStdin();
+
+  let parsed: HookStdin;
+  try {
+    parsed = JSON.parse(inputData) as HookStdin;
+  } catch {
+    process.exit(0);
+  }
+
+  const toolName =
+    typeof parsed.tool_name === 'string' && parsed.tool_name.length > 0
+      ? parsed.tool_name
+      : 'unknown';
+  const toolResponse: ToolResponse = parsed.tool_response ?? {};
+
+  const usage = extractContextUsage(toolResponse);
+
+  // No usage data — cannot act. Do not emit a hook.fired event; this
+  // is a non-decision, not an "ok" outcome.
+  if (usage === null) process.exit(0);
+
+  // Below threshold — explicit "ok" decision.
+  if (usage < THRESHOLD) {
+    emitHookFired('ok');
+    process.exit(0);
+  }
+
+  // At or above threshold but block already present — emit ok (we did
+  // the right thing earlier) and bail.
+  if (stateFileHasPausedBlock()) {
+    emitHookFired('ok');
+    process.exit(0);
+  }
+
+  const block = buildPausedBlock(toolName, usage);
+  appendPausedBlock(block);
+  emitHookFired('warn');
+
+  const response: HookOutput = {
+    continue: true,
+    suppressOutput: false,
+    message: `gdd-context-exhaustion: Context at ${Math.round(usage * 100)}% — auto-recorded <paused> block in .design/STATE.md. Run /gdd:resume in the next session to continue.`,
+  };
+  process.stdout.write(JSON.stringify(response));
+}
+
+const isDirectInvocation =
+  process.argv[1] !== undefined &&
+  /context-exhaustion\.ts$/.test(process.argv[1]);
+
+if (isDirectInvocation) {
+  main().catch((err: unknown) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`context-exhaustion hook error: ${msg}\n`);
+    process.exit(0);
+  });
+}

package/hooks/gdd-read-injection-scanner.ts

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * gdd-read-injection-scanner.ts — PostToolUse hook (matcher: Read)
+ *
+ * Phase 20 Plan 20-13 rewrite of the original
+ * gdd-read-injection-scanner.js. Scans Read tool output for common
+ * prompt-injection patterns and warns (does not block) when suspicious
+ * content is found in a read file. Advisory-only — output is a JSON
+ * response containing a `message` field the user / agent can act on.
+ *
+ * Injection patterns come from scripts/injection-patterns.cjs (Tier-2;
+ * not TypeScript-converted per Plan 20-00's policy). We require-load
+ * them through Node's CJS interop using `createRequire()` — this works
+ * under --experimental-strip-types without `package.json "type":"module"`
+ * changes and keeps the .cjs module shared with
+ * scripts/run-injection-scanner-ci.cjs unchanged.
+ *
+ * Phase 20 addition: every decision (block / allow) fires a hook.fired
+ * event via appendEvent() (Plan 20-06). "block" is used for the
+ * warning-emission path even though the hook itself never hard-blocks
+ * — it signals the advisory decision to downstream consumers.
+ *
+ * Hook type: PostToolUse (matcher: Read)
+ * Input:  JSON on stdin { tool_name, tool_input, tool_response }
+ * Output: JSON on stdout { continue, suppressOutput, message } or nothing
+ */
+
+import { createRequire } from 'node:module';
+import { createInterface } from 'node:readline';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+
+import { appendEvent } from '../scripts/lib/event-stream/index.ts';
+import type { HookFiredEvent } from '../scripts/lib/event-stream/index.ts';
+
+// ── require-bridge to the shared .cjs pattern file ──────────────────────────
+
+/**
+ * Load injection-patterns.cjs through Node's CJS require even though
+ * this TS file runs under --experimental-strip-types (which auto-detects
+ * ES-module mode). createRequire() can be anchored on any absolute
+ * filesystem path (or a `file://` URL string) — we deliberately avoid
+ * `import.meta.url` so this module stays compatible with the `Node16`
+ * tsconfig module setting without forcing `"type":"module"` in
+ * package.json (which would break the Tier-2 .cjs tests per Plan 20-00).
+ *
+ * Path resolution: when Claude Code invokes the hook, it passes the
+ * absolute path as argv[1]. We anchor against that (so the .cjs
+ * resolves relative to this file's own directory). Falls back to
+ * process.cwd() — scripts/injection-patterns.cjs lives under the
+ * package root, which is cwd in both CI and npm script contexts.
+ */
+function loadPatterns(): readonly RegExp[] {
+  const hookPath =
+    typeof process.argv[1] === 'string' && process.argv[1].length > 0
+      ? isAbsolute(process.argv[1])
+        ? process.argv[1]
+        : resolve(process.argv[1])
+      : resolve('hooks/gdd-read-injection-scanner.ts');
+  const require = createRequire(hookPath);
+  const candidatePaths: string[] = [
+    join(dirname(hookPath), '..', 'scripts', 'injection-patterns.cjs'),
+    join(process.cwd(), 'scripts', 'injection-patterns.cjs'),
+  ];
+  let lastErr: unknown = null;
+  for (const p of candidatePaths) {
+    try {
+      const mod = require(p) as {
+        INJECTION_PATTERNS: Array<{ name: string; re: RegExp }>;
+      };
+      return mod.INJECTION_PATTERNS.map((entry) => entry.re);
+    } catch (err) {
+      lastErr = err;
+    }
+  }
+  const msg =
+    lastErr instanceof Error ? lastErr.message : String(lastErr);
+  throw new Error(
+    `gdd-read-injection-scanner: failed to load injection-patterns.cjs (${msg})`,
+  );
+}
+
+const INJECTION_PATTERNS: readonly RegExp[] = loadPatterns();
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+interface HookStdin {
+  tool_name?: string;
+  tool_input?: { file_path?: string };
+  tool_response?: { content?: string };
+  [key: string]: unknown;
+}
+
+interface HookOutput {
+  continue: boolean;
+  suppressOutput?: boolean;
+  message?: string;
+}
+
+/** Hook decision tag for the event stream. */
+export type HookDecision = 'block' | 'allow';
+
+// ── event-stream emitter ────────────────────────────────────────────────────
+
+let CACHED_SESSION_ID: string | null = null;
+function getSessionId(): string {
+  if (CACHED_SESSION_ID === null) {
+    const iso = new Date().toISOString().replace(/[:.]/g, '-');
+    CACHED_SESSION_ID = `gdd-hook-${iso}-${process.pid}`;
+  }
+  return CACHED_SESSION_ID;
+}
+
+function emitHookFired(decision: HookDecision): void {
+  const ev: HookFiredEvent = {
+    type: 'hook.fired',
+    timestamp: new Date().toISOString(),
+    sessionId: getSessionId(),
+    payload: { hook: 'gdd-read-injection-scanner', decision },
+  };
+  try {
+    appendEvent(ev);
+  } catch {
+    // Fail open.
+  }
+}
+
+// ── main ────────────────────────────────────────────────────────────────────
+
+async function readStdin(): Promise<string> {
+  const rl = createInterface({ input: process.stdin });
+  let data = '';
+  for await (const line of rl) data += line + '\n';
+  return data;
+}
+
+export async function main(): Promise<void> {
+  const inputData = await readStdin();
+
+  let parsed: HookStdin;
+  try {
+    parsed = JSON.parse(inputData) as HookStdin;
+  } catch {
+    process.exit(0);
+  }
+
+  if (parsed.tool_name !== 'Read') process.exit(0);
+
+  const content = parsed.tool_response?.content ?? '';
+  const matched = INJECTION_PATTERNS.some((p) => p.test(content));
+  if (!matched) {
+    emitHookFired('allow');
+    process.exit(0);
+  }
+
+  const file = parsed.tool_input?.file_path ?? 'unknown';
+  emitHookFired('block');
+  const response: HookOutput = {
+    continue: true,
+    suppressOutput: false,
+    message: `gdd-injection-scanner: Suspicious prompt-injection pattern detected in content read from "${file}". Review before acting on instructions contained in that file.`,
+  };
+  process.stdout.write(JSON.stringify(response));
+  process.exit(0);
+}
+
+const isDirectInvocation =
+  process.argv[1] !== undefined &&
+  /gdd-read-injection-scanner\.ts$/.test(process.argv[1]);
+
+if (isDirectInvocation) {
+  main().catch(() => process.exit(0));
+}

package/hooks/hooks.json

@@ -32,7 +32,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/budget-enforcer.js\""
+            "command": "node --experimental-strip-types \"${CLAUDE_PLUGIN_ROOT}/hooks/budget-enforcer.ts\""
           }
         ]
       },
@@ -70,7 +70,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gdd-read-injection-scanner.js\""
+            "command": "node --experimental-strip-types \"${CLAUDE_PLUGIN_ROOT}/hooks/gdd-read-injection-scanner.ts\""
           }
         ]
       },
@@ -87,7 +87,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/context-exhaustion.js\""
+            "command": "node --experimental-strip-types \"${CLAUDE_PLUGIN_ROOT}/hooks/context-exhaustion.ts\""
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.19.6",
+  "version": "1.20.0",
   "description": "A Claude Code plugin for systematic design improvement",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -26,24 +26,34 @@
     "LICENSE"
   ],
   "bin": {
-    "get-design-done": "./scripts/install.cjs"
+    "get-design-done": "./scripts/install.cjs",
+    "gdd-state-mcp": "./scripts/mcp-servers/gdd-state/server.ts"
   },
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "scripts": {
-    "test": "node --test \"tests/**/*.cjs\"",
+    "test": "node --test --experimental-strip-types \"tests/**/*.cjs\" \"tests/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "codegen:schemas": "node --experimental-strip-types scripts/codegen-schema-types.ts",
     "lint:md": "npx --yes markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#.planning\" \"#.claude\" \"#test-fixture/baselines\"",
     "lint:links": "npx --yes lychee --no-progress --accept 200,206,403,429 \"**/*.md\" || true",
-    "validate:schemas": "node scripts/validate-schemas.cjs",
-    "validate:frontmatter": "node scripts/validate-frontmatter.cjs agents/",
+    "validate:schemas": "node --experimental-strip-types scripts/validate-schemas.ts",
+    "validate:frontmatter": "node --experimental-strip-types scripts/validate-frontmatter.ts agents/",
     "detect:stale-refs": "node scripts/detect-stale-refs.cjs",
     "scan:injection": "node scripts/run-injection-scanner-ci.cjs",
     "test:size-budget": "node --test tests/agent-size-budget.test.cjs",
     "release:extract-changelog": "node scripts/extract-changelog-section.cjs",
     "verify:version-sync": "node scripts/verify-version-sync.cjs"
   },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "ajv-cli": "^5.0.0",
+    "ajv-formats": "^3.0.1",
+    "json-schema-to-typescript": "^15.0.0",
+    "typescript": "^5.5.0"
+  },
   "keywords": [
     "claude",
     "claude-code",
@@ -103,5 +113,8 @@
   "skills": [
     "SKILL.md"
   ],
-  "hooks": "hooks/hooks.json"
+  "hooks": "hooks/hooks.json",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
 }

package/reference/config-schema.md

@@ -185,7 +185,7 @@ If `.design/budget.json` is missing when any `/gdd:*` command runs, `scripts/boo
 
 ## .design/telemetry/costs.jsonl + .design/agent-metrics.json (Phase 10.1)
 
-Phase 10.1 introduces two measurement artifacts written by `hooks/budget-enforcer.js` (PreToolUse on `Agent` spawns) and `scripts/aggregate-agent-metrics.js` (detached child of the hook + refresh step of `/gdd:optimize`). Both files live under the gitignored `.design/` directory — they are local session state, not committed.
+Phase 10.1 introduces two measurement artifacts written by `hooks/budget-enforcer.js` (PreToolUse on `Agent` spawns) and `scripts/aggregate-agent-metrics.ts` (detached child of the hook + refresh step of `/gdd:optimize`). Both files live under the gitignored `.design/` directory — they are local session state, not committed.
 
 ### .design/telemetry/costs.jsonl
 
@@ -223,7 +223,7 @@ Append-only ledger. One JSON object per line. Written by `hooks/budget-enforcer.
 
 ### .design/agent-metrics.json
 
-Per-agent aggregate derived from `costs.jsonl` by `scripts/aggregate-agent-metrics.js`. Written atomically via tmp-file + rename. Overwritten in full on every refresh — not append-only. Consumers should treat it as a snapshot.
+Per-agent aggregate derived from `costs.jsonl` by `scripts/aggregate-agent-metrics.ts`. Written atomically via tmp-file + rename. Overwritten in full on every refresh — not append-only. Consumers should treat it as a snapshot.
 
 **Schema:**
 

package/reference/error-recovery.md

@@ -0,0 +1,58 @@
+# Error recovery
+
+This is the recovery-action protocol for low-level errors inside the GDD pipeline. It sits on top of `scripts/lib/error-classifier.cjs` (Plan 20-14) and references the rate-guard, jittered-backoff, and iteration-budget primitives.
+
+## Recovery protocol
+
+On `status=413` or `context_overflow`, re-emit with compressed context (drop oldest non-system turns, target 50% reduction, retry once).
+
+On `status=429`, consult `scripts/lib/rate-guard.cjs` → `blockUntilReady(provider)` before retry.
+
+On network-transient (5xx, ECONNRESET), use jittered backoff (`scripts/lib/jittered-backoff.cjs`); max 3 retries.
+
+On auth-error, surface to user — do not retry.
+
+## Recovery-action table
+
+The `FailoverReason` enum in `scripts/lib/error-classifier.cjs` has eight values. Each row below is the canonical recovery action for one of those values. The classifier's `suggestedAction` field returns a one-liner drawn from this table; this doc is the authoritative long form.
+
+| FailoverReason      | Retryable | Action                                                                                                                                                     |
+| ------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rate_limited`      | yes       | Call `rate-guard.ingestHeaders(provider, response.headers)` to record the rate-limit signal, then `rate-guard.blockUntilReady(provider)` before retrying. The blocker waits until `resetAt` on disk — synchronized siblings (watch-authorities + update-check) therefore share the backoff boundary. After the block returns, retry with jittered backoff at attempt 0. |
+| `context_overflow`  | yes       | Compress context — drop the oldest non-system turns (or the oldest attachments) targeting roughly 50 % token reduction. Retry **once** with the compressed payload. If the retry also raises `context_overflow`, escalate to the user as an unrecoverable block — further compression destroys information. |
+| `auth_error`        | no        | Surface the error to the user with actionable text: which credential, which provider, and the renewal path (OAuth re-auth URL, API-key environment variable, etc.). Do not retry automatically — a loop would just multiply the failure. |
+| `network_transient` | yes       | Retry with `scripts/lib/jittered-backoff.cjs` — `await sleep(attempt)` inside a bounded loop. Cap at 3 attempts before giving up. When retries exhaust, reclassify as `network_permanent` and surface to the user. |
+| `network_permanent` | no        | Surface to user. The endpoint is wrong, DNS is broken, or the resource was removed. A retry without operator action will just re-fail. |
+| `tool_not_found`    | no        | Surface to user. Either the tool name drifted (common for MCP servers whose prefixes change across sessions) or the MCP is not registered. Reprobe via the connection's probe sequence before retrying anything. |
+| `validation`        | no        | Surface the validation detail to the caller. Do not retry the same input — 4xx is the server saying "your payload is wrong". Fixing the payload is caller work. |
+| `unknown`           | no        | Surface the raw error to the user. Do not retry — we can't tell whether it's safe. Add a telemetry row so we can tighten the classifier over time. |
+
+## Integration points
+
+| Caller                    | When to classify                             | What to do with `reason`                                                                                           |
+| ------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `hooks/budget-enforcer.ts` | pre-spawn rate-guard check (Plan 20-14)      | If upstream state already shows `rate_limited`, emit `decision: 'rate-limited'` and short-circuit before any spawn. |
+| Figma MCP probe           | live `get_metadata` call errors              | `network_transient` → jittered-backoff retry. `auth_error` → STOP with a reauth note. `rate_limited` → block then retry. |
+| Watch-authorities fetcher | per-feed HTTP fetch                          | Same policy as Figma probe; `validation` also possible on ETag stalemate (304). |
+| Update-check HTTP curl    | GitHub `releases/latest` fetch               | Silent failure by D-04 of Plan 13.3 — classify but don't surface; log and exit 0. |
+| MCP transport             | tool-call errors (gdd-state, figma, 21st-dev)| Map `tool_not_found` to a probe-reissue; map `auth_error` to STOP; retry transient classes via the caller's own loop. |
+
+## Fix-loop iteration interaction
+
+Retries consume iteration budget when paired with the Layer-B cache:
+
+1. On cache hit, `iteration-budget.refund(1)` preserves the iteration that would otherwise have been spent.
+2. On each actual retry that does real work (no cache hit), the caller `iteration-budget.consume(1)` before the spawn.
+3. When the budget's `remaining === 0`, further retries throw `IterationBudgetExhaustedError` and the caller must surface to user — a retry cycle has become pathological.
+
+This protects the "infinite fix loop" case — a blocker that regenerates after every fix — from burning unbounded context.
+
+## Telemetry
+
+Every classification result that leads to a retry or a surfaced error should append an event to `.design/telemetry/events.jsonl`:
+
+```json
+{ "type": "error.classified", "timestamp": "…", "sessionId": "…", "payload": { "reason": "rate_limited", "retryable": true, "caller": "figma-probe" } }
+```
+
+The event subtype is defined in `scripts/lib/event-stream/types.ts`. Consumers (`gdd-reflector`, dashboard) aggregate by `reason` to detect classifier drift — if `unknown` spikes, the classifier needs tightening.

package/reference/registry.json

@@ -3,6 +3,13 @@
   "version": 1,
   "generated_at": "2026-04-24T00:00:00.000Z",
   "entries": [
+    {
+      "name": "error-recovery",
+      "path": "reference/error-recovery.md",
+      "type": "meta-rules",
+      "phase": 20,
+      "description": "Phase 20 resilience recovery protocol — rate-limit + 429 + context-overflow retry guidance for the SDK runner (jittered-backoff / rate-guard / error-classifier / iteration-budget integration)"
+    },
     {
       "name": "component-authoring",
       "path": "reference/component-authoring.md",

package/reference/schemas/budget.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://get-design-done.example/schemas/budget.schema.json",
+  "title": ".design/budget.json",
+  "description": "Shape of .design/budget.json — the Phase 10.1 optimization-layer budget governance file. Consumed by hooks/budget-enforcer.ts on every PreToolUse:Agent spawn. Bootstrap writes the Default Config from reference/config-schema.md if the file is missing.",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "per_task_cap_usd": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Hard ceiling per agent spawn (USD). Breach under enforcement_mode=enforce triggers D-02 block."
+    },
+    "per_phase_cap_usd": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Cumulative ceiling across all spawns within the current phase (USD). Read from .design/STATE.md frontmatter `phase:` field."
+    },
+    "tier_overrides": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string",
+        "enum": ["haiku", "sonnet", "opus"]
+      },
+      "description": "Per-agent tier override map (agent-name -> tier). Wins over agent frontmatter default-tier per D-04."
+    },
+    "auto_downgrade_on_cap": {
+      "type": "boolean",
+      "description": "When true, hook silently rewrites tier -> haiku at 80% of per_task_cap_usd per D-03; logged as tier_downgraded: true in telemetry."
+    },
+    "cache_ttl_seconds": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "TTL (seconds) driving .design/cache-manifest.json entry expiry per D-08 Layer B. Default 3600."
+    },
+    "enforcement_mode": {
+      "type": "string",
+      "enum": ["enforce", "warn", "log"],
+      "description": "D-11 enforcement policy. enforce = block + auto-downgrade; warn = print warnings but allow spawn; log = advisory-only telemetry without gating."
+    }
+  }
+}