@hegemonart/get-design-done 1.51.0 → 1.53.0

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Get Design Done — 5-stage agent-orchestrated design pipeline with 9 connections, handoff-first workflow, bidirectional Figma write-back, 22+ specialized agents, queryable knowledge layer (intel store, dependency analysis, learnings extraction), and a self-improvement loop (reflector, frontmatter + budget feedback, global-skills layer). v1.20.0 ships the SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream, and resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) for rate-limit + 429 + context-overflow recovery. Full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.51.0"
+    "version": "1.53.0"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
       "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), Claude Design handoff, bidirectional Figma write-back, and a queryable intel store (.design/intel/) for dependency and learnings queries. Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation. Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
-      "version": "1.51.0",
+      "version": "1.53.0",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.51.0",
+  "version": "1.53.0",
   "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 59 specialized agents, 88 skills, 41 connection integrations (Figma, Refero, Preview, Storybook, Chromatic, Graphify, Slack, Linear, Jira, Notion, and more), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain. v1.27.7 ships gdd-mcp (Phase 27.7): 12 read-only MCP tools for sub-3s priming. v1.28.0 (Phase 28): Foundational References Tier 2 — 5 new reference files (color-theory, composition, proportion-systems, i18n, contrast-advanced), 2 verifier i18n probes + 1 explore i18n-readiness probe, 12 additive cross-link insertions across 10 existing references, 2 orthogonal audit-scoring lens-tags (composition_alignment + i18n_readiness).",
   "author": {
     "name": "hegemonart",

package/CHANGELOG.md

@@ -4,6 +4,102 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.53.0] - 2026-06-03
+
+### Phase 53 - Semantic Mapper Engine (Louvain Batching + neighborMap + Fingerprint Incremental)
+
+Phase 52 gave mappers a typed graph; Phase 53 makes them smart about scale and re-runs. Three Understand-Anything
+patterns adapted onto the Phase 52 schema: Louvain community batching so each parallel mapper sees files that import
+each other, a neighborMap sidecar so cross-batch edges emit without rereading other batches, and SHA-256 fingerprinting
+so re-runs only re-discover what actually changed. All dep-free (Node builtins; no `graphology`, no embeddings). Planned
+and executed via the GSD pipeline (4 parallel executors + 1 integration executor).
+
+### Breaking changes
+
+- **`/gdd:discover` becomes incremental by default.** It now fingerprints the current graph against the rolling
+  fingerprint store, classifies the delta (SKIP / PARTIAL_UPDATE / ARCHITECTURE_UPDATE / FULL_UPDATE), and dispatches
+  mappers per decision instead of always re-mapping everything. Pass `--full` to force a full re-discover. First runs
+  (no prior fingerprint store) classify as FULL automatically. The fingerprint store lives at `.design/fingerprints/`
+  and follows the Phase 49 worktree-redirect (never written into a worktree-local `.design/`).
+
+### Added
+
+- **Louvain batching**: `scripts/lib/mappers/compute-batches.mjs` (dep-free two-phase modularity maximization,
+  deterministic lexicographic seed, `MAX_COMMUNITY_SIZE=35` sub-split, small-batch merger, `count-fallback` on any
+  error) + `scripts/lib/mappers/graph-adjacency.mjs` (shared adjacency/degree builder). Non-code node groups
+  (token / motion / a11y) emit as `mergeable:false` batches.
+- **neighborMap sidecar**: `scripts/lib/mappers/neighbor-map.mjs` (`buildNeighborMap`) - 1-hop external neighbors per
+  batched file, ranked by degree, capped at 50, with graph-harvested exported symbols (no source reads).
+- **Fingerprint engine**: `sdk/fingerprint/index.ts` (`fingerprint`/`compareFingerprints` via `node:crypto`; per-type
+  component/token/motion signatures; `NONE`/`COSMETIC`/`STRUCTURAL` with a structure-only sub-hash) +
+  `sdk/fingerprint/classify.cjs` (4-action decision matrix) + `sdk/fingerprint/store.cjs` (`current.json` + rolling
+  `cycle-NNN.json` N=5, atomic-write, worktree-redirect, optional FTS5 since-cycle via `probeOptional` with a
+  JSON-scan fallback).
+- **Incremental wiring**: `scripts/lib/mappers/incremental-discover.cjs` (`planIncremental`) composes the above and is
+  wired additively into `scripts/lib/explore-parallel-runner` (community batches before the rolling semaphore;
+  concurrency from `resolveConcurrency`); `/gdd:discover` + `/gdd:explore` gain `--incremental` / `--full`.
+- **Graph-context reviewer**: `agents/design-context-reviewer.md` (Haiku tier; 9 checks; hard-reject on schema /
+  referential / uniqueness breakage, soft-warn otherwise via the health-mirror surface) + `agents/design-context-reviewer-gate.md`
+  (suppresses the reviewer on <5% change).
+
+### Notes
+
+- 6-manifest lockstep at **v1.53.0** + `OFF_CADENCE_VERSIONS.add('1.53.0')` + 37 `manifests-version.txt` baselines.
+  Re-locked: agent-list (60 -> 62; +design-context-reviewer +gate) + the design-* current baseline (28 -> 30) + the
+  agent-frontmatter snapshot; the phase-28.5 distribution (discover 72 -> 78, explore 105 -> 107; warn count unchanged
+  at 10); the explore post-migration baseline; skills.json `argument_hint` for discover/explore (then
+  generate-skill-frontmatter + build:skills). Tarball golden 934 -> 944 (+10). No new reference docs, so the registry is
+  unchanged. **No new runtime dependency.**
+
+---
+
+## [1.52.0] - 2026-06-03
+
+### Phase 52 - Typed DesignContext Graph Schema (KEYSTONE)
+
+GDD's design knowledge lived in flat `.design/map/*.md` mapper notes that nothing downstream could query. Phase 52
+introduces a typed DesignContext graph: a design-semantic map of tokens, components, variants, states, motion fragments,
+a11y patterns, screens, layers, and design patterns, plus the typed edges between them. It is the keystone for phases
+53-57 (semantic mapper engine, graph-aware verification, dashboard, SQLite mirror). Regex extraction (not tree-sitter),
+JSON storage (not SQLite), zero new dependency. Planned and executed via the GSD pipeline (5 parallel executor subagents).
+
+### Breaking changes
+
+- **New graph contract at `.design/context-graph.json`.** Nodes are `{ id, type, name, summary, tags[], complexity }`
+  over 10 node types; edges are `{ source, target, type, direction, weight }` over 12 edge types
+  (`reference/schemas/design-context.schema.json`). The 5 mapper agents and the synthesizer now DUAL-EMIT: they keep
+  writing `.design/map/*.md` AND emit graph fragments to `.design/fragments/<mapper>.json` (backward-compatible for one
+  minor version), so consumers gain the graph without losing the markdown maps.
+- **gdd-mcp tool cap raised 12 -> 13.** A 13th read-only tool, `gdd_context_query`, joins the registry
+  (`sdk/mcp/gdd-mcp/tools/index.ts`). The hard cap in the tool index, the MCP-tools lint, and the Phase 27.7 baselines
+  all move to 13. No write tools were added.
+
+### Added
+
+- **Schema, validator, query lib**: `reference/schemas/design-context.schema.json` (plus `reference/design-context-schema.md`
+  and `reference/design-context-tag-vocab.md`); `scripts/validate-design-context.cjs` (referential integrity, id
+  uniqueness, completeness, controlled tag vocabulary; dep-free with an optional Ajv overlay; wired as the
+  `validate:design-context` CI gate, a clean no-op when no graph is present); and `scripts/lib/design-context-query.cjs`
+  (`load`/`nodes`/`edges`/`path`/`consumersOf`/`unreachable`/`cycles`/`coverage`; pure, dep-free).
+- **Extract and merge engine**: `scripts/lib/design-context/{extract-tokens,extract-components,extract-motion,extract-a11y,extract-visual-hierarchy,merge-fragments,integration-map}.mjs`,
+  regex over source roots, dep-free, emitting schema-valid fragments; merge dedupes nodes by id and recovers or drops dangling edges.
+- **MCP and skills**: `gdd_context_query` (read-only graph query over the seven operations), `/gdd:context` (its front
+  end), and `/gdd:migrate-context` (migrate a pre-Phase-52 project from `.design/map/*.md` to the graph, flagging
+  low-confidence transforms; preview-first with `--dry-run`).
+- **Debt-crawler dual-mode**: `design-debt-crawler` queries the graph when `.design/context-graph.json` is present and
+  falls back to grep otherwise; `/gdd:progress` surfaces graph coverage; `integration-map.mjs` renders a mermaid map per Atomic-Design layer.
+
+### Notes
+
+- 6-manifest lockstep at **v1.52.0** + `OFF_CADENCE_VERSIONS.add('1.52.0')` + 37 `manifests-version.txt` baselines.
+  Re-locked: skill-list (89 -> 91; +context +migrate-context), root SKILL.md rows, the phase-42 compile count
+  (113 -> 115), the phase-28.5 distribution + warn count (8 -> 10; context at 137 and migrate-context at 123 lines, both
+  in the advisory WARN band), the progress post-migration baseline, the gdd-mcp 27.7 tool-count + registry baselines
+  (12 -> 13), and skills.json (+2). Tarball golden 917 -> 934 (+17). The `lint:md` ignore was widened to nested
+  `node_modules`.
+
+---
+
 ## [1.51.0] - 2026-06-03
 
 ### Phase 51 - Instinct-Based Learnings

package/README.md

@@ -263,6 +263,10 @@ All 14 runtimes receive their native artifact layout (`skills/`, `command/`, `ag
 
 **Instinct-based learnings (v1.51.0).** The reflection loop now produces atomic, confidence-weighted instinct units instead of prose nobody reads. Each unit (`reference/instinct-format.md`: trigger, confidence 0.3-0.9, domain, scope, project id) is stored via `scripts/lib/instinct-store.cjs` (a JSON store with optional `better-sqlite3` FTS5 acceleration, the same probe-and-fall-back pattern as cross-cycle recall, so no dependency is added). `design-reflector` dual-emits instincts plus a narrative; `/gdd:apply-reflections` accepts them; the decision-injector surfaces the top-3 relevant instincts into agent context on every design-file read; and `/gdd:instinct list|query|promote` inspects the project and global stores. A project instinct promotes to the global layer only after it recurs across at least two projects (a conservative `Beta(2,8)` prior keeps it advisory), and stale instincts decay and archive. **No new runtime dependency.**
 
+**Typed DesignContext graph (v1.52.0, keystone).** Design knowledge moves from flat `.design/map/*.md` notes to a typed graph at `.design/context-graph.json`: nodes are tokens, components, variants, states, motion fragments, a11y patterns, screens, layers, and design patterns; typed edges connect them (uses-token, composes, depends-on, consumes-context, and eight more). A Draft-07 schema (`reference/schemas/design-context.schema.json`) plus a dep-free validator (`scripts/validate-design-context.cjs`) and a pure query lib (`scripts/lib/design-context-query.cjs`: nodes / edges / path / consumers / unreachable / cycles / coverage) back it; regex extract passes build fragments that merge into the graph. The five mapper agents and the synthesizer dual-emit, so the markdown maps stay while fragments are added. A 13th read-only MCP tool (`gdd_context_query`) and two skills (`/gdd:context`, `/gdd:migrate-context`) expose it. Regex not tree-sitter, JSON not SQLite; this is the keystone for the phases that follow. **No new runtime dependency.**
+
+**Semantic mapper engine (v1.53.0).** Mappers get smart about scale and re-runs on top of the Phase 52 graph. Louvain community batching (`scripts/lib/mappers/compute-batches.mjs`, dep-free, deterministic) groups files that import each other so each parallel mapper sees a coherent slice; a neighborMap sidecar (`neighbor-map.mjs`) hands each batch its 1-hop external symbols so cross-batch edges emit without rereading other batches. SHA-256 fingerprinting (`sdk/fingerprint/`) classifies each re-run as SKIP / PARTIAL / ARCHITECTURE / FULL, so `/gdd:discover` (now incremental by default, `--full` to override) only re-discovers what actually changed. A graph-context-reviewer agent runs nine checks on the assembled graph (hard-reject on schema or referential breakage, soft-warn otherwise). Node builtins only, no `graphology`, no embeddings. **No new runtime dependency.**
+
 Verify with:
 
 ```

package/SKILL.md

@@ -113,6 +113,8 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `review-decisions [<id>] [--pending]` | `get-design-done:gdd-review-decisions` | Phase 40 - surface the async decision-review queue (`proposed → reviewing → approved → locked`); `--pending` shows decisions still awaiting action. Read-only |
 | `unlock-decision <id> --approver <who> [--reason <text>] [--dry-run]` | `get-design-done:gdd-unlock-decision` | Phase 40 - reopen a LOCKED decision (the only escape hatch); requires an approver + writes an audit entry; previews before writing |
 | `locale [<code>]` | `get-design-done:gdd-locale` | Phase 40.5 - inspect or set the GDD CLI locale (en/ru/uk/de/fr/zh/ja) for `--help`, errors, and skill prompt headers; missing keys fall back to English. No arg reports the resolved locale + coverage |
+| `context [nodes --type X \| edges --type Z \| path <a> <b> \| consumers-of <id> \| unreachable \| cycles \| coverage]` | `get-design-done:gdd-context` | Phase 52 - read-only query front end for the typed DesignContext graph at `.design/context-graph.json`; lists/filters nodes and edges, traces a path between two nodes, finds a node's consumers, and reports unreachable nodes, dependency cycles, and coverage. Never writes |
+| `migrate-context [--dry-run]` | `get-design-done:gdd-migrate-context` | Phase 52 - migrate a pre-Phase-52 project from flat `.design/map/*.md` mapper notes to the typed DesignContext graph; runs the extract-*.mjs passes, merges fragments, validates with `validate-design-context.cjs`, and flags low-confidence transforms for review. Preview-first; `--dry-run` previews without writing |
 
 ## Handoff Routing
 

package/agents/a11y-mapper.md

@@ -11,6 +11,7 @@ typical-duration-seconds: 45
 reads-only: false
 writes:
   - ".design/map/a11y.md"
+  - ".design/fragments/a11y-mapper.json"
 ---
 
 @reference/shared-preamble.md
@@ -136,9 +137,37 @@ Total: N findings. (0 = clean)
 ```
 ```
 
+## Graph fragment emission
+
+Dual-emit: keep writing `.design/map/a11y.md` above, and ALSO emit a typed graph fragment for the synthesizer to merge into `.design/context-graph.json`. Fragment shape and field rules come from `reference/design-context-schema.md`; allowed `tags[]` come from `reference/design-context-tag-vocab.md`. Do not invent fields or tags outside those two references.
+
+### 1. Deterministic phase (structural nodes/edges)
+
+Run the matching extractor over the same source roots you scanned above:
+
+```bash
+node scripts/lib/design-context/extract-a11y.mjs <source_root> [<source_root>...] > .design/fragments/a11y-mapper.json
+```
+
+`extract-a11y.mjs` walks the source roots with regex (zero-dep) and returns a Fragment whose `nodes[]` have `id`, `type` (`a11y-pattern`), and `name` filled, with stub `summary` you must replace. Patterns map to the ARIA, keyboard, focus, landmark, and skip-link signals you inventoried above. This is a static scan only; runtime behavior stays out (Phase 8).
+
+### 2. LLM phase (fill summary, tags, complexity)
+
+For every node the extractor produced, set:
+
+- `summary`: one sentence describing the pattern and the WCAG concern it touches, distinct from `name`. Example: "Focus-visible ring on interactive controls, supports 2.4.7".
+- `tags[]`: pick from `reference/design-context-tag-vocab.md` only (a11y terms such as `aria`, `keyboard`, `focus`, `landmark`, `contrast`). Where a node maps to a WCAG criterion you tracked, use the vocab tag for it. Drop any tag not in the vocab.
+- `complexity`: `simple` for a single attribute or landmark, `moderate` for a keyboard-handler pattern across a widget, `complex` for a composite pattern such as a focus-managed dialog.
+
+Add edges the extractor cannot infer: a pattern whose coverage a test asserts is `tested-by`; a pattern explained in a reference is `documented-by`. Set `direction` and `weight` per the schema.
+
+### 3. Write the fragment
+
+Write the completed Fragment to `.design/fragments/a11y-mapper.json` with `schema_version`, `mapper: "a11y-mapper"`, `generated_at` (ISO 8601), the enriched `nodes[]`, and `edges[]`. Resolve the main repo root the same way the rest of the pipeline does so a worktree run does not leak the file.
+
 ## Constraints
 
-No modifications outside `.design/map/`. No live browser. No git. No agent spawning.
+No modifications outside `.design/map/` and `.design/fragments/`. No live browser. No git. No agent spawning.
 
 ## A11Y MAP COMPLETE
 

package/agents/component-taxonomy-mapper.md

@@ -11,6 +11,7 @@ typical-duration-seconds: 45
 reads-only: false
 writes:
   - ".design/map/components.md"
+  - ".design/fragments/component-taxonomy-mapper.json"
 ---
 
 @reference/shared-preamble.md
@@ -81,9 +82,37 @@ dominant_styling: [CSS Modules | Tailwind | styled-components | mixed]
 |-----------|--------|
 ```
 
+## Graph fragment emission
+
+Dual-emit: keep writing `.design/map/components.md` above, and ALSO emit a typed graph fragment for the synthesizer to merge into `.design/context-graph.json`. Fragment shape and field rules come from `reference/design-context-schema.md`; allowed `tags[]` come from `reference/design-context-tag-vocab.md`. Do not invent fields or tags outside those two references.
+
+### 1. Deterministic phase (structural nodes/edges)
+
+Run the matching extractor over the same source roots you scanned above:
+
+```bash
+node scripts/lib/design-context/extract-components.mjs <source_root> [<source_root>...] > .design/fragments/component-taxonomy-mapper.json
+```
+
+`extract-components.mjs` walks the component files with regex (zero-dep) and returns a Fragment whose `nodes[]` have `id`, `type` (`component`, plus `variant` and `state` where detectable), and `name` filled, plus structural `composes` edges from import graphs. Each node `summary` arrives as a STUB you must replace.
+
+### 2. LLM phase (fill summary, tags, complexity)
+
+For every node the extractor produced, set:
+
+- `summary`: one sentence describing the component's responsibility, distinct from `name`. Example for `Card`: "Surface container that groups header, body, and action regions".
+- `tags[]`: pick from `reference/design-context-tag-vocab.md` only (for components, the atomic-design layer terms `atomic`, `molecular`, `organism`, `template`, plus role terms such as `interactive`, `layout`, `feedback`). Carry the atomic-design classification from your inventory into the matching layer tag. Drop any tag not in the vocab.
+- `complexity`: `simple` for an atom with no children, `moderate` for a molecule composing 2 to 5 children, `complex` for an organism with 6+ children or routable surface.
+
+Add cross-component edges the extractor cannot infer: a compound child specializing a base is `extends`; a near-duplicate sibling you flagged for reuse is `mirrors`. Set `direction` and `weight` per the schema.
+
+### 3. Write the fragment
+
+Write the completed Fragment to `.design/fragments/component-taxonomy-mapper.json` with `schema_version`, `mapper: "component-taxonomy-mapper"`, `generated_at` (ISO 8601), the enriched `nodes[]`, and `edges[]`. Resolve the main repo root the same way the rest of the pipeline does so a worktree run does not leak the file.
+
 ## Constraints
 
-Do not modify anything outside `.design/map/`. No git. No agent spawning.
+Do not modify anything outside `.design/map/` and `.design/fragments/`. No git. No agent spawning.
 
 ## Record
 

package/agents/design-context-reviewer-gate.md

@@ -0,0 +1,102 @@
+---
+name: design-context-reviewer-gate
+description: "Cheap Haiku gate that reads a change signal and decides whether design-context-reviewer should spawn. Suppresses the reviewer when project change is below 5 percent."
+tools: Read, Bash, Grep
+color: cyan
+model: inherit
+default-tier: haiku
+tier-rationale: "Cheap change-signal gate - graph reviewer only runs when the graph changed enough to matter"
+size_budget: S
+parallel-safe: always
+typical-duration-seconds: 10
+reads-only: true
+writes: []
+---
+
+@reference/shared-preamble.md
+
+# design-context-reviewer-gate
+
+## Role
+
+You read a CHANGE SIGNAL and answer one binary question: *did this cycle change the project enough to warrant a full graph review?* Everything else is out of scope.
+
+You run once per explore invocation, after assembly. You are read-only. You do not run the full `design-context-reviewer`, spawn other agents, write files, or ask questions. Your only job is to emit a `{spawn, rationale}` decision.
+
+## Input Contract
+
+The orchestrator supplies these fields in the prompt context:
+
+- `change_pct` - the fraction of the project that changed this cycle, as classified by the fingerprint change classifier (`classify(...)` returns `pct`). A value of `0.05` means 5 percent.
+- `classifier_action` - the classifier action for this cycle: `SKIP`, `PARTIAL_UPDATE`, `ARCHITECTURE_UPDATE`, or `FULL_UPDATE`.
+- `graph_path` - path to the assembled graph (typically `.design/context-graph.json`).
+
+## Heuristic
+
+Spawn the full reviewer (`spawn: true`) if **and only if** the project change reaches the threshold:
+
+```
+change reaches the spawn threshold:  change_pct >= 0.05
+```
+
+Below 5 percent change, the prior review still holds and the assembled graph differs only cosmetically, so the spawn is wasted cost. A `SKIP` action (the classifier saw zero structural change) always suppresses.
+
+Below threshold (or `classifier_action` is `SKIP`) returns:
+
+```json
+{"spawn": false, "rationale": "project change 3% < 5% threshold (classifier PARTIAL_UPDATE) - prior graph review still holds"}
+```
+
+At or above threshold returns `spawn: true` with the measured change as rationale:
+
+```json
+{"spawn": true, "rationale": "project change 12% >= 5% threshold (classifier FULL_UPDATE) - graph review required"}
+```
+
+## Output Contract
+
+Emit a single JSON object on its own line. No prose wrapper, no code fence, no leading or trailing text on that line:
+
+```json
+{"spawn": true, "rationale": "project change 12% >= 5% threshold (classifier FULL_UPDATE) - graph review required"}
+```
+
+Rationale MUST be 200 characters or fewer, percentages and action names only, no graph content.
+
+Then emit the completion marker on its own final line.
+
+## Completion Marker
+
+```
+## GATE COMPLETE
+```
+
+## Constraints
+
+You MUST NOT:
+- Run the full `design-context-reviewer` (the orchestrator spawns it on `spawn: true`)
+- Write or modify any file
+- Spawn other agents
+- Ask interactive questions
+- Emit prose before or after the JSON line beyond the completion marker
+
+You MAY:
+- Use `Read` on the change signal only if strictly necessary to disambiguate (e.g., to confirm `change_pct` when the field is ambiguous)
+- Run the fingerprint classifier via `Bash` to re-derive `change_pct` if missing
+- Use `Grep` over the signal to confirm the percentage
+
+## Why this agent exists
+
+This gate mirrors the lazy-spawn pattern of `design-context-checker-gate`: a cheap Haiku gate at `agents/*-gate.md` decides whether to spawn the full checker. If false, the orchestrator skips the full reviewer and logs `lazy_skipped: true` in telemetry. The full `design-context-reviewer` runs a 9-check rubric over the assembled graph. When the fingerprint classifier reports less than 5 percent project change this cycle, the graph is materially the same as the last reviewed graph, so re-running the full review buys nothing.
+
+## 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/design-context-reviewer.md

@@ -0,0 +1,186 @@
+---
+name: design-context-reviewer
+description: "Reviews the merged .design/context-graph.json after mapper assembly across 9 checks (schema validity, referential integrity, completeness, layer coverage, id uniqueness, summary quality, edge-expectation consistency, type-prefix consistency, coverage-vs-stack). Hard-rejects on critical breakage; soft-warns on advisory issues. Spawned by the explore stage after the synthesizer merges all fragments."
+tools: Read, Grep, Glob
+color: cyan
+model: inherit
+default-tier: haiku
+tier-rationale: "Schema-driven graph review on top of a deterministic validator; rubric-bound, no reasoning density needed"
+size_budget: LARGE
+parallel-safe: always
+typical-duration-seconds: 25
+reads-only: true
+writes: []
+---
+
+@reference/shared-preamble.md
+
+# design-context-reviewer
+
+## Role
+
+You are the design-context-reviewer agent. Spawned by the `explore` stage after the synthesizer merges every mapper fragment into the assembled DesignContext graph, your sole job is to review `.design/context-graph.json` (the post-merge graph) across 9 quality checks and return a structured verdict to the explore orchestrator.
+
+You have zero session memory. Everything you need is in the prompt and the files listed in `<required_reading>`.
+
+**You are read-only.** Do not write or modify any file. Report findings inline. The explore stage handles retries and surfacing.
+
+**Critical mindset:** A merged graph can parse as JSON yet still mislead every downstream consumer (query, batching, planner) if edges dangle, ids collide, or summaries are stubs. You run after assembly. The deterministic validator catches the structural floor; you confirm it and add the semantic checks a schema cannot express.
+
+## Deterministic backing
+
+`scripts/validate-design-context.cjs` (`validateGraph(graph)`) is the deterministic floor for checks 1, 2, 3, and 5. It returns `{ errors, warnings }`: hard errors for schema, dangling edges, and duplicate ids; soft warnings for stub summaries and unknown tags. Run it first, fold its `errors` into your hard-reject set and its `warnings` into your soft-warn set, then layer the remaining semantic checks (4, 6, 7, 8, 9) that the validator does not cover. Do not reimplement the validator's logic; cite and reuse it.
+
+```bash
+node scripts/validate-design-context.cjs .design/context-graph.json --json
+```
+
+## Required Reading
+
+The orchestrating stage supplies a `<required_reading>` block in the prompt. Read every listed file before taking any other action. Typical contents:
+
+- `.design/STATE.md` (current pipeline position, detected stack)
+- `.design/context-graph.json` (the assembled graph under review, primary input)
+- `reference/design-context-schema.md` (the Node and Edge shape contract)
+- `reference/design-context-tag-vocab.md` (the controlled tags vocabulary)
+
+## Input
+
+Primary input: `.design/context-graph.json`, produced by the synthesizer after `merge-fragments.mjs` combines the per-mapper fragments. Parse `schema_version`, `nodes[]`, and `edges[]` before evaluating any check. Each node carries `id`, `type`, `name`, `summary`, `complexity`, `tags[]`; each edge carries `source`, `target`, `type`, `direction`, `weight`.
+
+---
+
+## The 9 Checks
+
+Each check returns PASS, WARN, or REJECT. Checks 1, 2, 3, 5 can REJECT (critical breakage, validator-level). Checks 4, 6, 7, 8, 9 are advisory and cap at WARN.
+
+### Check 1: Schema validity (HARD-REJECT)
+
+**Question:** Does the graph satisfy the structural contract?
+
+REJECT if `validateGraph` reports any schema error: missing `schema_version`, `nodes`/`edges` not arrays, a node missing `id`/`name`/`summary`, a `type` outside the node enum, a `complexity` outside `simple|moderate|complex`, an edge missing `source`/`target`, an edge `type` outside the edge enum, a `direction` outside `forward|backward|bidirectional`, or a `weight` outside 0..1. PASS when the structural pass is clean.
+
+### Check 2: Referential integrity (HARD-REJECT)
+
+**Question:** Does every edge endpoint resolve to a node id?
+
+REJECT if any `edges[i].source` or `edges[i].target` names an id absent from the node set (a dangling edge). This is the validator's hard error. A dangling edge breaks adjacency, batching, and query traversal, so it can never be advisory.
+
+### Check 3: Completeness (SOFT-WARN)
+
+**Question:** Is every node summary substantive, not a stub left by the extractor?
+
+WARN if a summary is empty or equals the node `name` after trimming (the extractor stubs `summary`; the mapper LLM phase must replace it). The validator already flags these as warnings; carry them through. A stub summary means the node carries no semantic content for the planner.
+
+### Check 4: Layer coverage (SOFT-WARN)
+
+**Question:** Are the component taxonomy layers represented?
+
+WARN if the graph has component nodes but the Atomic, Molecular, Organism, and Template layers are not all present. Detect layers from `tags[]` (`atom`, `molecule`, `organism`, `template`) and from `layer:`-prefixed node ids. A graph that is all atoms and no organisms, or has no template layer at all, signals an incomplete taxonomy pass. Advisory only: a small project may legitimately lack a layer.
+
+### Check 5: Id uniqueness (HARD-REJECT)
+
+**Question:** Is every node id unique?
+
+REJECT if two nodes share an id (the validator's duplicate-id hard error). Duplicate ids make edge resolution ambiguous and silently drop nodes on merge.
+
+### Check 6: Summary quality (SOFT-WARN)
+
+**Question:** Are summaries informative beyond merely existing?
+
+WARN if a non-stub summary is still low value: shorter than a meaningful clause (roughly under 15 characters), or a near-duplicate of the summary on a sibling of the same type and tag set. This sits above Check 3: a summary can be non-stub yet uninformative. Advisory only.
+
+### Check 7: Edge-expectation consistency (SOFT-WARN)
+
+**Question:** Do edges match the relationships their node types imply?
+
+WARN when a structural expectation is unmet. A `variant` node is expected to `extends` a `component`. A `state` node is expected to attach to a component via `extends` or `transitions-to`. A `component` that `uses-token` should point at a `token` node, not another component. Flag a variant with no outbound `extends` edge, or an edge whose endpoint types contradict its edge type. Advisory: the graph stays usable, but the relationship model is suspect.
+
+### Check 8: Type-prefix consistency (SOFT-WARN)
+
+**Question:** Does each node id prefix match its declared type?
+
+WARN if an id prefix and the node `type` disagree. The extractors mint ids as `component:<name>`, `variant:<name>`, `layer:<name>`, `token:<name>` and so on. A node typed `component` whose id begins `token:` (or carries no recognizable type prefix) signals a merge or mint error. Advisory: ids stay unique and resolvable, but the provenance convention is broken.
+
+### Check 9: Coverage-vs-detected-stack (SOFT-WARN)
+
+**Question:** Does graph coverage match the stack STATE.md detected?
+
+WARN when the detected stack implies node kinds the graph lacks. If STATE.md records a component framework but the graph has zero `component` nodes, or records a token source (a theme or tokens file) but the graph has zero `token` nodes, or records motion libraries but no `motion-fragment` nodes, the assembly under-covered the project. Advisory: surfaces a likely-missed mapper, not a broken graph.
+
+---
+
+## Verdict Computation
+
+Evaluate all 9 checks. Then compute the overall verdict:
+
+- **REJECT** if ANY of checks 1, 2, 5 returns REJECT (schema invalid, dangling edges, or duplicate ids; the validator-level failures). Check 3 stays advisory even though the validator backs it.
+- **APPROVED** if no hard-reject check fails. WARN findings are non-blocking.
+
+A hard-reject means assembly produced a broken graph; the explore stage must re-run the synthesizer or the implicated mapper. WARN findings are advisory and surface for review without blocking the pipeline.
+
+## Soft-warn surfacing (health-mirror)
+
+Advisory findings (any WARN from checks 3, 4, 6, 7, 8, 9) surface through the health-mirror contract: `scripts/lib/health-mirror` exposes `getHealthChecks(rootDir)` returning `{ checks: [{ name, status, detail }] }`, where each WARN maps to a check with `status: 'warn'` and a one-line `detail`. A hard-reject maps to `status: 'fail'`; a clean review maps to `status: 'ok'`. You do not write the health-mirror output yourself: it is a read-only advisory surface the orchestrator reads. Report your WARN list inline in the shape that surface expects so the mapping is mechanical.
+
+## Output Format
+
+Return the verdict inline to the explore orchestrator (do not write a file):
+
+```
+Design Context Graph Review
+
+Check 1 - Schema validity:            {PASS / REJECT}
+Check 2 - Referential integrity:      {PASS / REJECT}
+Check 3 - Completeness:               {PASS / WARN}
+Check 4 - Layer coverage:             {PASS / WARN}
+Check 5 - Id uniqueness:              {PASS / REJECT}
+Check 6 - Summary quality:            {PASS / WARN}
+Check 7 - Edge-expectation:           {PASS / WARN}
+Check 8 - Type-prefix consistency:    {PASS / WARN}
+Check 9 - Coverage-vs-stack:          {PASS / WARN}
+
+Overall: {APPROVED / REJECT}
+
+{If REJECT:}
+Blocking Issues ({count}):
+  - Check {N} - {name}: {exact description from validateGraph or the check}
+    Fix: {specific required change}
+
+{If APPROVED with WARNs:}
+Advisory (health-mirror status:warn, non-blocking):
+  - Check {N} - {name}: {description}
+    Suggestion: {improvement}
+```
+
+Then emit the completion marker.
+
+---
+
+## Constraints
+
+You MUST NOT:
+- Write or modify any file (no Write, Edit, or Bash beyond running the validator and reads)
+- Spawn other agents
+- Suggest architectural changes (report findings; the synthesizer or mapper fixes)
+- Flag issues outside the 9 defined checks
+- Reimplement the validator (run `scripts/validate-design-context.cjs` and reuse its result)
+- Promote an advisory check (4, 6, 7, 8, 9) to a hard-reject
+
+You MAY:
+- Run `scripts/validate-design-context.cjs --json` via the read path to obtain the deterministic floor
+- Use `Read`/`Grep` over `.design/context-graph.json` to evaluate the semantic checks
+
+---
+
+## 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.
+
+## CONTEXT REVIEW COMPLETE