@hegemonart/get-design-done 1.24.2 → 1.25.0

package/SKILL.md

@@ -87,6 +87,8 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `analyze-dependencies [--slice <name>]` | `get-design-done:analyze-dependencies` | Query the `.design/intel/` store — dependency slices, graph queries, phase-scoped reads |
 | `extract-learnings [--cycle <slug>]` | `get-design-done:extract-learnings` | Extract decisions, lessons, patterns, and surprises from a completed cycle → `.design/cycles/<slug>/LEARNINGS.md` |
 | `skill-manifest [--refresh]` | `get-design-done:skill-manifest` | List or refresh the local skill manifest used by the router for discovery |
+| `quality-gate` | `get-design-done:quality-gate` | Phase 25 — parallel lint/type/test/visual command runner; classifies failures via quality-gate-runner agent |
+| `turn-closeout` | `get-design-done:turn-closeout` | Phase 25 — Stop-hook mirror skill; finalizes per-turn STATE blocks and emits closeout events |
 | `watch-authorities [--refresh] [--since <date>] [--feed <name>] [--schedule <cadence>]` | `get-design-done:gdd-watch-authorities` | Run design-authority-watcher — fetch curated feeds, diff snapshot, classify new entries → `.design/authority-report.md` (consumed by `/gdd:reflect`) |
 | `benchmark <component\|--wave N\|--list\|--refresh component>` | `get-design-done:gdd-benchmark` | Harvest + synthesize per-component design specs from 18 design systems → `reference/components/<name>.md` |
 | `benchmark <component\|--wave N\|--list\|--refresh component>` | `get-design-done:gdd-benchmark` | Harvest + synthesize per-component design specs from 18 design systems → `reference/components/<name>.md` |

package/agents/prototype-gate.md

@@ -0,0 +1,122 @@
+---
+name: prototype-gate
+description: "Cheap Haiku gate that scores sketch / spike signals from the active brief / context / plan and emits a JSON verdict recommending whether to prototype before continuing."
+tools: Read, Bash, Grep
+color: yellow
+model: inherit
+default-tier: haiku
+tier-rationale: "Signal-counting rubric over a few small inputs — no synthesis, no writes, no agent spawning. Belongs on Haiku to keep gate latency cheap (≤ 2 s typical)."
+size_budget: S
+parallel-safe: always
+typical-duration-seconds: 5
+reads-only: true
+writes: []
+---
+
+@reference/shared-preamble.md
+
+# prototype-gate
+
+## Role
+
+You answer one question at a checkpoint: *should the pipeline pause to sketch or spike before continuing?*
+
+You run at two firing points (Phase 25 D-02):
+1. **Post-`/gdd:explore`** — sketch territory. The question is "what visual / direction?".
+2. **Post-`/gdd:plan` plan-checker** — spike territory. The question is "can this work technically?".
+
+You are read-only. You do not write STATE.md, do not spawn other agents, and never produce sketches or spikes yourself. Your only job is to score signals and emit a JSON verdict.
+
+You also honor the cycle-scoped skip rule (D-02): if `STATE.md` `<prototyping>` already contains a `<skipped at=<your_firing_point> cycle=<active_cycle>/>` entry, recommend `none` immediately with `reason: "skipped this cycle"`. Do not re-evaluate signals.
+
+## Input Contract
+
+The orchestrator supplies these fields in the prompt context:
+
+- `firing_point` — `"explore"` or `"plan"`. Determines which signal rubric you apply.
+- `cycle` — the active cycle identifier from STATE frontmatter.
+- `state_path` — absolute path to the active `.design/STATE.md`.
+- `inputs` — paths to context the rubric scans:
+  - `brief_path` (always supplied) — `.design/BRIEF.md` or equivalent.
+  - `context_path` (firing_point=`"explore"`) — `.design/DESIGN-CONTEXT.md`.
+  - `design_path` (firing_point=`"explore"` if present) — `.design/DESIGN.md`.
+  - `plan_tasks_path` (firing_point=`"plan"`) — `.design/PLAN.md` or `.design/plans/*.md`.
+  - `decisions_snapshot` (always supplied) — newline-separated `D-NN: text (locked|tentative)` lines extracted from STATE `<decisions>`.
+
+Missing input files are not an error — score the signals you can read; treat absent files as zero-signal contributions.
+
+## Cycle-skip short-circuit
+
+Before scoring, scan `<prototyping>` in `state_path` for a `<skipped/>` entry whose `at` matches `firing_point` AND whose `cycle` matches the active `cycle`. If found, emit:
+
+```json
+{"recommend": "none", "confidence": 1.0, "reasons": ["skipped this cycle at the prototype gate"]}
+```
+
+Then exit. Do not score further.
+
+## Signal Rubric
+
+### Sketch signals (firing_point = `"explore"`)
+
+Score 1 point per matched signal:
+
+- **Hero / first-impression language** — BRIEF mentions "hero", "first impression", "novel surface", "landing", "above-the-fold", or names a single high-stakes screen.
+- **DESIGN-CONTEXT visual gray areas** — DESIGN-CONTEXT.md contains an unresolved item tagged `visual:` or `direction:` (case-insensitive).
+- **Empty design canvas** — DESIGN.md is missing or its scan returned no existing patterns to follow (no component references, no token references).
+- **Decision conflict on the same surface** — at least two D-XX entries in `decisions_snapshot` discuss the same surface but disagree (look for paired references to the same component / page / area).
+- **Open-ended language in interview answers** — BRIEF or DESIGN-CONTEXT contains "not sure", "open to", "??", "tbd", "we could" within answer regions.
+- **Multiple viable patterns** — DESIGN-CONTEXT or a phase-researcher artifact lists more than one viable pattern for a single section without a chosen winner.
+
+### Spike signals (firing_point = `"plan"`)
+
+Score 1 point per matched signal:
+
+- **High-risk task** — a plan task carries `Risk: high` or `Confidence: low` (case-insensitive).
+- **Tech outside the components mapper** — a plan task references a library, framework, API, or pattern not present in the project's components / mapper artifacts.
+- **Failed required connection** — `<connections>` reports `unavailable` for a connection that a plan task explicitly depends on.
+- **Experimental language** — a plan task description contains "experimental", "TBD", "unsure", "spike", "prove out", "validate that".
+- **Probe deferred** — a plan task notes "will check at runtime" or similar deferred verification.
+
+## Threshold
+
+| Score | recommend | confidence |
+|-------|-----------|------------|
+| ≥ 3 | `sketch` (explore) or `spike` (plan) | `0.9` |
+| 1–2 | same as above | `0.5` |
+| 0 | `none` | `0.95` |
+
+Confidence is rubric-derived only — do not infer confidence from the size of the inputs or your own uncertainty. The thresholds above are the only valid values.
+
+## Output Contract
+
+Emit exactly one JSON object on its own line. No prose wrapper, no code fence, no leading or trailing text.
+
+```json
+{"recommend": "sketch", "confidence": 0.9, "reasons": ["BRIEF mentions hero", "DESIGN-CONTEXT visual gray area on home"]}
+```
+
+Schema:
+
+- `recommend` — string enum, one of `"sketch" | "spike" | "none"`.
+- `confidence` — number in `[0, 1]`. One of `0.5`, `0.9`, `0.95` per the threshold table; or `1.0` for the cycle-skip short-circuit.
+- `reasons` — array of short strings (≤ 80 chars each). One entry per matched signal, in match order. Empty array allowed when `recommend === "none"` from the threshold (not the skip path).
+
+## Constraints
+
+- **Do not** propose what to sketch / spike — that's the wrap-up flow's job. Your reasons are evidence, not directives.
+- **Do not** read or write STATE.md outside of the cycle-skip lookup described above.
+- **Do not** consult external services or MCP tools. Signal scoring is purely a function of the supplied inputs.
+- **Do not** exceed `size_budget: S`. If inputs are unexpectedly large, prefer to score signals on the first 8 KB of each file rather than refuse to answer.
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
+## GATE COMPLETE

package/agents/quality-gate-runner.md

@@ -0,0 +1,125 @@
+---
+name: quality-gate-runner
+description: "Cheap Haiku classifier that ingests {command, exit_code, stderr} tuples from the quality-gate skill's parallel run and emits a JSON verdict — pass/fail plus per-bucket failure groupings (lint / type / test / visual). Read-only. Does not run commands itself."
+tools: Read, Bash, Grep
+color: amber
+model: inherit
+default-tier: haiku
+tier-rationale: "Pattern-match exit codes and bucket stderr into four named categories — no synthesis, no rewrites, no spawning. Belongs on Haiku to keep classification cost trivial relative to the actual command runs."
+size_budget: S
+parallel-safe: always
+typical-duration-seconds: 5
+reads-only: true
+writes: []
+---
+
+@reference/shared-preamble.md
+
+# quality-gate-runner
+
+## Role
+
+You answer one question for the `quality-gate` skill (Phase 25 Plan 25-03): *given the outputs of the parallel command run, did the gate pass — and if not, into which buckets do the failures fall?*
+
+You are read-only. You do not re-run any commands, do not write STATE.md, do not spawn agents, do not produce fixes. Your only job is to classify the outputs and return JSON.
+
+## Input Contract
+
+The skill supplies a JSON object on stdin (or as the first line of the prompt context — handle both). Shape:
+
+```json
+{
+  "outputs": [
+    {"command": "npm run lint", "exit_code": 0, "stderr": ""},
+    {"command": "npm run typecheck", "exit_code": 1, "stderr": "<verbatim stderr>"},
+    {"command": "npm run test", "exit_code": 0, "stderr": ""},
+    {"command": "npm run chromatic", "exit_code": 1, "stderr": "<verbatim stderr>"}
+  ]
+}
+```
+
+Schema:
+- `outputs` — array, one entry per command actually executed in Step 2 of the skill. Order is preserved from the skill (matches command-list order from Step 1).
+  - `command` — verbatim shell string the skill ran.
+  - `exit_code` — integer. `0` = clean; non-zero = failure to be classified.
+  - `stderr` — verbatim stderr capture. May be empty even on failure (some tools write to stdout); do not assume non-empty stderr means failure.
+
+You may also receive a `stdout` field per entry (forward-compat — the skill plans to add it). Tolerate its absence.
+
+## Bucketing rule
+
+Map each command to exactly one of four buckets based on the verbatim command string. Use case-insensitive substring match against the command line:
+
+| Substring (case-insensitive) | Bucket |
+|------------------------------|--------|
+| `lint`, `eslint`, `stylelint`, `biome lint` | `lint` |
+| `typecheck`, `tsc`, `tsc --noemit`, `flow check` | `type` |
+| `test` (but NOT one of the visual matches below — visual wins) | `test` |
+| `chromatic`, `test:visual`, `loki test`, `playwright test --grep visual` | `visual` |
+
+When a command matches multiple substrings (e.g., `npm run test:visual` matches both `test` and `test:visual`), `visual` wins. If a command matches none, bucket it under `test` (catch-all — most user-supplied custom commands are test-like). Do not invent a fifth bucket.
+
+## Pass / fail rule
+
+- `status === "pass"` if and only if **every** entry's `exit_code === 0`.
+- `status === "fail"` if **any** entry's `exit_code !== 0`.
+
+Empty `outputs` array means `status === "pass"` (no commands ran → nothing failed). The skill is responsible for emitting `quality_gate_skipped` in the no-commands path; you do not.
+
+## Failure summarization
+
+For each failed entry (exit_code !== 0), produce one short summary string and add it to the bucket the command maps to. Summaries should:
+
+- Quote the command name (the basename — e.g., `lint` from `npm run lint`).
+- Include the first non-empty line of `stderr` truncated to 120 chars, if present.
+- Otherwise include `exit_code=N` so the reader still sees something concrete.
+
+Example summary strings:
+- `"lint: 4 problems (3 errors, 1 warning)"` — when stderr's first line is informative.
+- `"typecheck: error TS2304: Cannot find name 'foo' in src/x.ts"` — same.
+- `"test: exit_code=1"` — when stderr is empty.
+
+Do NOT inline full stderr — the bucket entries are summaries, not transcripts. The skill keeps the verbatim outputs for the fixer; your output is for routing only.
+
+Buckets that have no failures are OMITTED from `classified_failures`. Do not emit empty arrays for unaffected buckets — the consumer relies on key-presence as a signal.
+
+## Output Contract
+
+Emit exactly one JSON object on its own line. No prose wrapper, no code fence, no leading or trailing text.
+
+Pass example:
+
+```json
+{"status": "pass", "classified_failures": {}}
+```
+
+Fail example:
+
+```json
+{"status": "fail", "classified_failures": {"type": ["typecheck: error TS2304 in src/x.ts"], "visual": ["chromatic: 2 stories changed"]}}
+```
+
+Schema:
+- `status` — string enum, one of `"pass" | "fail"`. Note: this is NOT the same enum as the skill's STATE-block status (which also has `timeout` and `skipped`); those two cases are decided by the skill, not by you. You only emit `pass | fail`.
+- `classified_failures` — object. Keys are a subset of `lint | type | test | visual`. Values are arrays of short summary strings (≤ 120 chars each). The object is `{}` (empty) when `status === "pass"`.
+
+## Constraints
+
+- **Do not** read `stderr` content beyond the first non-empty line. The skill keeps the verbatim outputs for the design-fixer; your job is routing, not analysis.
+- **Do not** invent buckets outside the four-name set.
+- **Do not** ever emit `status: "timeout"` or `status: "skipped"` — those are skill-level statuses, not classifier outputs.
+- **Do not** consult external services or MCP tools. Classification is a pure function of the supplied input.
+- **Do not** exceed `size_budget: S`. If `outputs[*].stderr` is unexpectedly large, prefer to summarize from the first 4 KB of each stderr rather than refuse.
+- The output JSON object must be parseable with `JSON.parse` — no trailing comma, no comments, no surrounding markdown.
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
+## GATE COMPLETE

package/hooks/budget-enforcer.ts

@@ -80,6 +80,26 @@ const iterationBudget = nodeRequire('../scripts/lib/iteration-budget.cjs') as ty
  * for every hook invocation. The tool_input shape is tool-specific;
  * this hook only consumes Agent-shaped tool_input so we narrow here.
  */
+/** Phase 25 / D-04, D-05: router complexity-class enum. */
+export type ComplexityClass = 'S' | 'M' | 'L' | 'XL';
+
+/**
+ * Phase 25 / D-05: router decision payload as surfaced on
+ * tool_input.context.router_decision. Only the fields this hook reads
+ * are typed; the router emits more (model_tier_overrides,
+ * estimated_cost_usd, cache_hits) but they are not consumed here.
+ */
+interface RouterDecision {
+  path?: 'fast' | 'quick' | 'full';
+  complexity_class?: ComplexityClass;
+  [key: string]: unknown;
+}
+
+interface ToolInputContext {
+  router_decision?: RouterDecision;
+  [key: string]: unknown;
+}
+
 interface ToolInput {
   subagent_type?: string;
   agent?: string;
@@ -91,6 +111,7 @@ interface ToolInput {
   _default_tier?: string;
   _tier_downgraded?: boolean;
   lazy_skipped?: boolean;
+  context?: ToolInputContext;
   [key: string]: unknown;
 }
 
@@ -199,6 +220,46 @@ const BUDGET_DEFAULTS: Required<
   enforcement_mode: 'enforce',
 };
 
+/**
+ * Phase 25 / D-05: optional per-class cap map on .design/budget.json.
+ * Documented in reference/config-schema.md as `class_caps_usd?: { S?: number; M?: number; L?: number; XL?: number }`.
+ * Read through the BudgetSchema index signature so we don't have to
+ * regenerate the schema for an additive optional field.
+ */
+type ClassCapsUsd = Partial<Record<ComplexityClass, number>>;
+
+function readClassCaps(budget: BudgetSchema): ClassCapsUsd | undefined {
+  const raw = (budget as { class_caps_usd?: unknown }).class_caps_usd;
+  if (raw === undefined || raw === null || typeof raw !== 'object') {
+    return undefined;
+  }
+  const out: ClassCapsUsd = {};
+  for (const k of ['S', 'M', 'L', 'XL'] as const) {
+    const v = (raw as Record<string, unknown>)[k];
+    if (typeof v === 'number' && Number.isFinite(v) && v > 0) {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+/**
+ * Phase 25 / D-05: resolve the per-spawn cap. If the router decision
+ * payload contains a `complexity_class` AND `.design/budget.json#class_caps_usd[class]`
+ * is defined, use that. Otherwise fall back to `per_task_cap_usd`.
+ */
+function resolvePerSpawnCap(
+  budget: ResolvedBudget,
+  complexityClass: ComplexityClass | undefined,
+): number {
+  if (complexityClass !== undefined) {
+    const caps = readClassCaps(budget);
+    const classCap = caps?.[complexityClass];
+    if (classCap !== undefined) return classCap;
+  }
+  return budget.per_task_cap_usd;
+}
+
 /**
  * Concrete budget shape after defaults-merge. Every field becomes
  * non-optional so downstream branches don't have to null-guard. Defined
@@ -490,6 +551,27 @@ export async function main(): Promise<void> {
   const inputHash =
     typeof toolInput._input_hash === 'string' ? toolInput._input_hash : null;
 
+  // Phase 25 / D-05: extract complexity_class from router decision.
+  // Absent payload → legacy per_task_cap behavior (no regression).
+  // Present payload with class === 'S' → skip enforcement entirely
+  // (defensive: the typical S path is upstream short-circuit where
+  // router never ran and this hook still applies legacy caps; an
+  // explicit S signal here means a caller bypassed the upstream skip
+  // and is asking us to honor the class).
+  const routerDecision: RouterDecision | undefined =
+    toolInput.context?.router_decision !== undefined &&
+    typeof toolInput.context.router_decision === 'object' &&
+    toolInput.context.router_decision !== null
+      ? toolInput.context.router_decision
+      : undefined;
+  const complexityClass: ComplexityClass | undefined =
+    routerDecision?.complexity_class !== undefined &&
+    (['S', 'M', 'L', 'XL'] as const).includes(
+      routerDecision.complexity_class as ComplexityClass,
+    )
+      ? (routerDecision.complexity_class as ComplexityClass)
+      : undefined;
+
   const { cycle, phase } = readCycleAndPhase();
   const cyclePhase = { cycle, phase };
 
@@ -513,6 +595,38 @@ export async function main(): Promise<void> {
 
   const budget = loadBudget();
 
+  // Phase 25 / D-05: explicit S-class short-circuit. The typical S path
+  // skips the router entirely and this hook never runs at all (the
+  // command's SKILL.md does the deterministic skip upstream). When we
+  // DO see complexity_class === 'S' in the payload it means a caller
+  // routed an S-class command through the hook anyway — honor the
+  // class by skipping enforcement (no cap check, no downgrade) but
+  // still write a zero-cost telemetry row + emit an 'allow' event so
+  // observability stays consistent.
+  if (complexityClass === 'S') {
+    writeTelemetry({
+      agent,
+      tier:
+        toolInput._tier_override ??
+        toolInput._default_tier ??
+        'haiku',
+      tokens_in: Number(toolInput._tokens_in_est ?? 0),
+      tokens_out: Number(toolInput._tokens_out_est ?? 0),
+      cache_hit: false,
+      est_cost_usd: Number(toolInput._est_cost_usd ?? 0),
+      enforcement_mode: budget.enforcement_mode,
+      _cyclePhase: cyclePhase,
+    });
+    emitHookFired('allow', cycle);
+    const response: ToolOutput = {
+      continue: true,
+      suppressOutput: true,
+      modified_tool_input: toolInput,
+    };
+    process.stdout.write(JSON.stringify(response));
+    return;
+  }
+
   // Branch B: cache short-circuit (D-05).
   if (inputHash !== null) {
     const cached = cacheLookup(agent, inputHash);
@@ -589,9 +703,15 @@ export async function main(): Promise<void> {
   const estCost = Number(toolInput._est_cost_usd ?? 0);
   const phaseSpend = currentPhaseSpend(phase);
 
+  // Phase 25 / D-05: per-spawn cap is class-specific when
+  // complexity_class is present and class_caps_usd[class] is defined.
+  // Falls back to per_task_cap_usd for backwards compatibility — when
+  // no router decision is supplied, behavior is identical to pre-25.
+  const perSpawnCap = resolvePerSpawnCap(budget, complexityClass);
+
   if (budget.enforcement_mode === 'enforce') {
-    // Branch C: 100% per_task cap hard block.
-    if (estCost >= budget.per_task_cap_usd) {
+    // Branch C: 100% per-spawn cap hard block (class-specific or per_task).
+    if (estCost >= perSpawnCap) {
       writeTelemetry({
         agent,
         tier:
@@ -607,10 +727,14 @@ export async function main(): Promise<void> {
         _cyclePhase: cyclePhase,
       });
       emitHookFired('block', cycle);
+      const capLabel =
+        complexityClass !== undefined && perSpawnCap !== budget.per_task_cap_usd
+          ? `class_caps_usd.${complexityClass}`
+          : 'per-task';
       const response: ToolOutput = {
         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.`,
+        message: `Budget cap reached for ${capLabel}. Estimated: $${estCost.toFixed(4)}, cap: $${perSpawnCap.toFixed(2)}. Raise cap in .design/budget.json or retry after next task.`,
       };
       process.stdout.write(JSON.stringify(response));
       return;
@@ -640,18 +764,19 @@ export async function main(): Promise<void> {
       process.stdout.write(JSON.stringify(response));
       return;
     }
-    // 80% soft-threshold downgrade (D-03): task-scoped.
+    // 80% soft-threshold downgrade (D-03): task-scoped, against the
+    // resolved per-spawn cap so class-specific caps participate.
     if (
       budget.auto_downgrade_on_cap &&
-      estCost >= 0.8 * budget.per_task_cap_usd
+      estCost >= 0.8 * perSpawnCap
     ) {
       toolInput._tier_override = 'haiku';
       toolInput._tier_downgraded = true;
     }
   } else if (budget.enforcement_mode === 'warn') {
-    if (estCost >= budget.per_task_cap_usd) {
+    if (estCost >= perSpawnCap) {
       process.stderr.write(
-        `gdd-budget-enforcer WARN: per-task cap will be exceeded ($${estCost.toFixed(4)} >= $${budget.per_task_cap_usd})\n`,
+        `gdd-budget-enforcer WARN: per-spawn cap will be exceeded ($${estCost.toFixed(4)} >= $${perSpawnCap})\n`,
       );
     }
   }

package/hooks/gdd-decision-injector.js

@@ -23,6 +23,7 @@ const { spawnSync } = require('child_process');
 
 const MIN_BYTES = 1500;
 const TOP_N = 15;
+const PROTOTYPING_TOP_N = 5;
 const MATCHER_RE = /[\\/](?:\.design|reference|\.planning)[\\/][^\n]*\.md$/;
 
 // Phase 19.5: try FTS5 backend first; fall back to grep silently.
@@ -111,6 +112,174 @@ function sortKeyFor(tag) {
   return 0;
 }
 
+/**
+ * Parse a self-closing-tag attribute string ("a=\"x\" b=\"y\"") into a kv map.
+ * Self-contained: avoids a TS-parser import to keep the hook hot path JS-only.
+ */
+function parseAttrs(attrStr) {
+  const out = {};
+  if (!attrStr) return out;
+  const re = /(\w+)\s*=\s*"([^"]*)"/g;
+  let m;
+  while ((m = re.exec(attrStr)) !== null) out[m[1]] = m[2];
+  return out;
+}
+
+/**
+ * One-shot read of STATE.md. Returns `{ prototyping, decisionsMap }` where
+ * `prototyping` is the inner body of `<prototyping>...</prototyping>` (or '')
+ * and `decisionsMap` is a `D-XX -> rationale` lookup parsed from `<decisions>`.
+ * Both fields default to safe empties on unreadable file / absent blocks.
+ *
+ * Single read keeps the hot path tight (STATE.md is small but reading once
+ * beats reading twice).
+ */
+function readStateForPrototyping(stateFile) {
+  const empty = { prototyping: '', decisionsMap: Object.create(null) };
+  if (!stateFile) return empty;
+  let content;
+  try { content = fs.readFileSync(stateFile, 'utf8'); } catch { return empty; }
+  const out = { prototyping: '', decisionsMap: Object.create(null) };
+  const protoMatch = content.match(/<prototyping>([\s\S]*?)<\/prototyping>/);
+  if (protoMatch) out.prototyping = protoMatch[1];
+  const decBlock = content.match(/<decisions>([\s\S]*?)<\/decisions>/);
+  if (decBlock) {
+    const re = /^\s*(D-\d+)\s*:\s*(.+?)\s*$/gm;
+    let m;
+    while ((m = re.exec(decBlock[1])) !== null) {
+      // Strip a trailing `(locked)` / `(tentative)` qualifier if present.
+      out.decisionsMap[m[1]] = m[2].replace(/\s*\((?:locked|tentative)\)\s*$/i, '').trim();
+    }
+  }
+  return out;
+}
+
+/**
+ * Parse `<prototyping>` body into typed entries. Skips comments and unknown tags.
+ */
+function parsePrototypingEntries(body) {
+  const entries = [];
+  if (!body) return entries;
+  const re = /<(sketch|spike|skipped)\b([^>]*?)\/>/g;
+  let m;
+  while ((m = re.exec(body)) !== null) {
+    const type = m[1];
+    const attrs = parseAttrs(m[2]);
+    entries.push({ type, attrs });
+  }
+  return entries;
+}
+
+/**
+ * Tokenize a slug / basename / path for fuzzy comparison.
+ * Splits on hyphens, underscores, dots, and path separators; lowercases;
+ * drops common no-signal tokens (`md`, file extensions, single chars).
+ */
+function tokenize(s) {
+  if (!s) return [];
+  const parts = String(s).toLowerCase().split(/[-_./\\\s]+/).filter(Boolean);
+  const stop = new Set(['md', 'txt', 'json', 'ts', 'js', 'plan', 'context', 'state']);
+  return parts.filter((p) => p.length > 1 && !stop.has(p));
+}
+
+/**
+ * Score a prototyping entry against the opened file's basename + relPath tokens.
+ * Returns the entry's matcher term if any slug-token is shared with a
+ * basename/relPath token (case-insensitive). Falls back to plain substring
+ * for terms that don't tokenize (e.g., free-form `reason` strings).
+ *
+ * Symmetric with the D-XX matcher: the existing recall path greps source
+ * lines for the opened file's basename; here we surface a prototyping entry
+ * whenever it would have grepped successfully — when the entry's slug
+ * mentions the same concept the file's name encodes.
+ */
+function matchPrototypingEntry(entry, basename, relPath) {
+  let term;
+  if (entry.type === 'sketch' || entry.type === 'spike') {
+    term = entry.attrs.slug;
+  } else if (entry.type === 'skipped') {
+    term = entry.attrs.reason;
+  }
+  if (!term) return null;
+  const fileTokens = new Set([...tokenize(basename), ...tokenize(relPath)]);
+  if (fileTokens.size === 0) return null;
+  const termTokens = tokenize(term);
+  for (const t of termTokens) {
+    if (fileTokens.has(t)) return term;
+  }
+  // Fallback: plain substring (helps `reason` strings and slugs containing
+  // tokens that don't survive the stop-word filter).
+  const needle = String(term).toLowerCase();
+  if (basename.toLowerCase().includes(needle) || relPath.toLowerCase().includes(needle)) return term;
+  return null;
+}
+
+/**
+ * Format a single prototyping entry for the additionalContext block.
+ * Shape: "Prototyping outcome (cycle <cycle>): <type>/<slug> — D-<id> — <verdict-or-status>: <rationale>"
+ * Falls back gracefully when fields are missing (e.g., skipped entries lack a D-XX).
+ */
+function formatPrototypingEntry(entry, decisionsMap) {
+  const a = entry.attrs;
+  const cycle = a.cycle || '?';
+  const ident = a.slug || a.at || '?';
+  const segs = [`Prototyping outcome (cycle ${cycle}): ${entry.type}/${ident}`];
+  if (a.decision) {
+    const rationale = decisionsMap[a.decision];
+    segs.push(rationale ? `${a.decision} — ${rationale}` : a.decision);
+  }
+  if (entry.type === 'spike' && a.verdict) {
+    segs.push(`verdict: ${a.verdict}`);
+  } else if (a.status) {
+    segs.push(`status: ${a.status}`);
+  } else if (entry.type === 'skipped' && a.reason) {
+    segs.push(`reason: ${a.reason}`);
+  }
+  return segs.join(' — ');
+}
+
+/**
+ * Build the prototyping outcomes block. Returns null when nothing matches so the
+ * caller can decide whether to omit the heading entirely.
+ *
+ * Sort: most recent cycle first (matches the existing sortKeyFor recency bias).
+ */
+function buildPrototypingBlock(stateFile, basename, relPath) {
+  if (!stateFile) return null;
+  const { prototyping, decisionsMap } = readStateForPrototyping(stateFile);
+  if (!prototyping) return null;
+  const entries = parsePrototypingEntries(prototyping);
+  if (!entries.length) return null;
+
+  const matched = [];
+  for (const e of entries) {
+    const term = matchPrototypingEntry(e, basename, relPath);
+    if (term) matched.push(e);
+  }
+  if (!matched.length) return null;
+
+  // Recency: cycle is typically `cycle-N` or `N`; coerce to a number for sorting.
+  const cycleNum = (e) => {
+    const c = String(e.attrs.cycle || '');
+    const m = c.match(/(\d+)/);
+    return m ? Number(m[1]) : 0;
+  };
+  matched.sort((a, b) => cycleNum(b) - cycleNum(a));
+  const top = matched.slice(0, PROTOTYPING_TOP_N);
+
+  const lines = [];
+  lines.push('');
+  lines.push('### Prior prototyping outcomes');
+  for (const e of top) {
+    lines.push(`> - ${formatPrototypingEntry(e, decisionsMap)}`);
+  }
+  if (matched.length > PROTOTYPING_TOP_N) {
+    lines.push(`> … (${matched.length - PROTOTYPING_TOP_N} more prototyping entr${matched.length - PROTOTYPING_TOP_N === 1 ? 'y' : 'ies'})`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
 function buildRecallBlock(matches, basename, backendLabel) {
   if (!matches.length) return null;
   const uniq = [];
@@ -202,16 +371,27 @@ async function main() {
 
   const backendLabel = BACKEND || (useRgGlobal ? 'ripgrep' : 'node-grep');
   const block = buildRecallBlock(hits, basename, backendLabel);
-  if (!block) {
+
+  // Phase 25 (plan 25-06): surface <prototyping> outcomes when an opened
+  // planning/design .md ≥1500 bytes shares a slug/reason token with a
+  // resolved sketch/spike/skipped entry. STATE.md is the canonical home for
+  // the block (D-01); we read it directly here rather than via the TS parser
+  // so the hook stays self-contained JS.
+  const stateFile = sources.find((p) => p.endsWith(path.sep + 'STATE.md') || p.endsWith('/STATE.md'));
+  const protoBlock = buildPrototypingBlock(stateFile, basename, relPath);
+
+  if (!block && !protoBlock) {
     try { require('./_hook-emit.js').emitHookFired('gdd-decision-injector', 'no-hits', { backend: backendLabel }); } catch { /* swallow */ }
     process.stdout.write(JSON.stringify({ continue: true }));
     return;
   }
 
-  try { require('./_hook-emit.js').emitHookFired('gdd-decision-injector', 'inject', { backend: backendLabel, hit_count: hits.length }); } catch { /* swallow */ }
+  const additionalContext = [block, protoBlock].filter(Boolean).join('\n');
+
+  try { require('./_hook-emit.js').emitHookFired('gdd-decision-injector', 'inject', { backend: backendLabel, hit_count: hits.length, prototyping: !!protoBlock }); } catch { /* swallow */ }
   process.stdout.write(JSON.stringify({
     continue: true,
-    hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: block },
+    hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext },
   }));
 }