@hegemonart/get-design-done 1.52.0 → 1.54.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.52.0"
+    "version": "1.54.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.52.0",
+      "version": "1.54.0",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.52.0",
+  "version": "1.54.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,96 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.54.0] - 2026-06-03
+
+### Phase 54 - Composable Reference Addendums (Per-DS + Per-Framework + Per-Motion-Lib)
+
+One general mapper prompt could not be stack-aware: it missed Tailwind's `@theme` tokens, shadcn's `cn()` convention,
+vanilla-extract's `style({})` shape. Phase 54 adds 18 composable prompt addendums (one per design system, framework, and
+motion library) that the explore mappers compose into their prompt at spawn time based on the detected stack. Adapted
+from Understand-Anything's per-language/per-framework addendum pattern. Maintainer-authored and vendor-cross-checked;
+no LLM-generated content. Planned and executed via the GSD pipeline (5 parallel executors + 1 integration executor).
+
+### Breaking changes
+
+- **Mappers are now stack-aware.** `scripts/lib/detect/stack.cjs` detects `{ds, framework, motion_libs[]}` from
+  package.json deps + config files + import signatures; `scripts/lib/mapper-spawn.cjs` composes the matching addendums
+  (capped at 3: one DS, one framework, one motion) into each mapper's prompt before dispatch (additive and
+  backward-compatible: no detected stack or no addendum leaves the base prompt unchanged).
+- **Registry gains a `stack-addendum` type.** `reference/registry.schema.json` adds `"stack-addendum"` to the entry
+  type enum and an optional `composes_into` field; the 18 addendums register against it with their target mappers.
+
+### Added
+
+- **Design-system addendums** (`reference/systems/`): tailwind, shadcn, radix-themes, mui, chakra, vanilla-extract,
+  styled-components, css-modules. **Framework addendums** (`reference/frameworks/`): nextjs, remix, vite-react, astro,
+  sveltekit, storybook. **Motion-lib addendums** (`reference/motion/`): framer-motion, gsap, motion-one, react-spring.
+  Each is at most 50 lines with four sections (Conventions, File patterns, Gotchas, and an Example output fragment in
+  the Phase 52 DesignContext schema).
+- **`/gdd:new-addendum <kind> <name>`** skill + `scripts/lib/new-addendum.cjs` scaffolder (mirrors `/gdd:new-skill`;
+  validates the kind and slug, defaults `composes_into` by kind, writes the 4-section skeleton).
+- **Fallback + coverage**: an unmatched stack falls back to the base prompt and flags the gap; `gsd-health` reports a
+  "N/M detected stacks have addendums" coverage row.
+
+### Notes
+
+- 6-manifest lockstep at **v1.54.0** + `OFF_CADENCE_VERSIONS.add('1.54.0')` + 37 `manifests-version.txt` baselines.
+  Re-locked: skill-list (91 -> 92, +new-addendum) + the phase-28.5 distribution (new-addendum at 81 lines, clean; warn
+  count unchanged at 10) + skill-graph + the registry-diff baseline (+18 stack-addendum entries) + resilience-primitives
+  (+mapper-spawn.cjs +new-addendum.cjs) + the phase-42 compile count (115 -> 116) + the gsd-health check count (8 -> 9).
+  Tarball golden 944 -> 969 (+25). **No new runtime dependency.**
+
+---
+
+## [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)

package/README.md

@@ -265,6 +265,10 @@ All 14 runtimes receive their native artifact layout (`skills/`, `command/`, `ag
 
 **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.**
+
+**Composable reference addendums (v1.54.0).** One general mapper prompt cannot know Tailwind's `@theme` tokens from shadcn's `cn()` from vanilla-extract's `style({})`. Phase 54 adds 18 stack-specific addendums (8 design systems, 6 frameworks, 4 motion libraries) under `reference/{systems,frameworks,motion}/`, each at most 50 lines with Conventions / File patterns / Gotchas / Example-output sections. `scripts/lib/detect/stack.cjs` detects the project stack from dependencies plus config files and import signatures; `scripts/lib/mapper-spawn.cjs` composes the matching addendums (capped at one DS + one framework + one motion) into each explore mapper's prompt at spawn time, additively, so a project on an unknown stack just keeps the base prompt and `gsd-health` reports the coverage gap. A `/gdd:new-addendum` scaffolder adds more. Maintainer-authored, vendor-cross-checked, no LLM-generated content. **No new runtime dependency.**
+
 Verify with:
 
 ```

package/SKILL.md

@@ -2,7 +2,7 @@
 name: get-design-done
 short_name: gdd
 description: "Master design pipeline for Claude Code. 5-stage workflow: Brief → Explore → Plan → Design → Verify. Run 'brief' first in any new project to capture the design problem, then 'explore' to inventory the codebase and interview for context. Invoke without arguments for status and auto-routing."
-argument-hint: "[brief|explore|plan|design|verify|handoff|map|next|help|status|style|darkmode|live|compare|figma-write|graphify|discuss|list-assumptions|progress|health|todo|stats|note|plant-seed|add-backlog|review-backlog|scan|discover|settings|update|reapply-patches|audit|pause|resume|new-cycle|debug|quick|new-project|complete-cycle|fast|do|ship|undo|pr-branch|sketch|sketch-wrap-up|spike|spike-wrap-up|reflect|apply-reflections|analyze-dependencies|extract-learnings|skill-manifest|pin|unpin|list-pins|new-skill|instinct|warm-cache|optimize|cache-manager|watch-authorities|check-update|benchmark|recall|timeline|continue|zoom-out]"
+argument-hint: "[brief|explore|plan|design|verify|handoff|map|next|help|status|style|darkmode|live|compare|figma-write|graphify|discuss|list-assumptions|progress|health|todo|stats|note|plant-seed|add-backlog|review-backlog|scan|discover|settings|update|reapply-patches|audit|pause|resume|new-cycle|debug|quick|new-project|complete-cycle|fast|do|ship|undo|pr-branch|sketch|sketch-wrap-up|spike|spike-wrap-up|reflect|apply-reflections|analyze-dependencies|extract-learnings|skill-manifest|pin|unpin|list-pins|new-skill|new-addendum|instinct|warm-cache|optimize|cache-manager|watch-authorities|check-update|benchmark|recall|timeline|continue|zoom-out]"
 user-invocable: true
 ---
 
@@ -94,6 +94,7 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `unpin <skill>` | `get-design-done:gdd-unpin` | Phase 46 - remove pinned aliases for a skill (only files carrying the gdd-pinned-skill marker) |
 | `list-pins` | `get-design-done:gdd-list-pins` | Phase 46 - show pinned aliases per harness with their source skill and last-pinned timestamp |
 | `new-skill <name>` | `get-design-done:gdd-new-skill` | Phase 50 - interactive scaffolder for a new Phase 28.5 + v3-compliant skill (multi-paragraph description, lifecycle stage, optional composes_with); writes source/skills/<name>/SKILL.md |
+| `new-addendum <kind> <name>` | `get-design-done:gdd-new-addendum` | Phase 54 - scaffold a composable reference addendum (kind = system\|framework\|motion); validates the slug, defaults composes_into by kind, writes a 4-section skeleton at reference/{systems\|frameworks\|motion}/<name>.md that an explore mapper composes at spawn time |
 | `instinct [list\|query <kw>\|promote <id>]` | `get-design-done:gdd-instinct` | Phase 51 - inspect and manage atomic instinct learning units (project + global stores); list, search by keyword, or promote a vetted project instinct to global once it clears the cross-project gate |
 | `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 |

package/agents/component-taxonomy-mapper.md

@@ -18,6 +18,9 @@ writes:
 
 # component-taxonomy-mapper
 
+<!-- {{addendum_block}} -->
+Stack-specific guidance (a `## Stack-specific guidance` block for the detected DS / framework / motion library) is appended here at spawn time by `scripts/lib/mapper-spawn.cjs`. When present, follow it as an extension of the rules below.
+
 ## Role
 
 You inventory the component taxonomy of the codebase. Zero session memory. You do not modify source code or spawn other agents.

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

package/agents/motion-mapper.md

@@ -18,6 +18,7 @@ writes:
 
 # motion-mapper
 
+<!-- {{addendum_block}}: a `## Stack-specific guidance` block for the detected DS / framework / motion library is appended here at spawn time by scripts/lib/mapper-spawn.cjs. When present, follow it as an extension of the rules below. -->
 ## Role
 
 You inventory motion and animation patterns. Zero session memory. You do not modify source code and do not spawn other agents.

package/agents/token-mapper.md

@@ -18,6 +18,9 @@ writes:
 
 # token-mapper
 
+<!-- {{addendum_block}} -->
+Stack-specific guidance (a `## Stack-specific guidance` block for the detected DS / framework / motion library) is appended here at spawn time by `scripts/lib/mapper-spawn.cjs`. When present, follow it as an extension of the rules below.
+
 ## Role
 
 You map design tokens from the codebase. Zero session memory - everything you need is in the prompt and `<required_reading>`. You do not modify source code or spawn other agents.

package/dist/claude-code/.claude/skills/discover/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: discover
 description: "Stage 1.5 of 4 orchestrator that probes Figma / Refero / Pinterest connections, spawns design-context-builder (auto-detect + interview) and (via lazy gate) design-context-checker (6-dimension validator), producing .design/DESIGN-CONTEXT.md. Use after /gdd:scan when a fast-path context build is wanted instead of the full /gdd:explore. Activates for requests involving detecting an existing design system, inventorying tokens and components, or onboarding a brownfield repo."
-argument-hint: "[--auto]"
+argument-hint: "[--auto] [--incremental] [--full]"
 user-invocable: true
 ---
 
@@ -30,6 +30,12 @@ When `--auto` is passed to the builder: if `tailwind.config.{js,cjs,mjs,ts}` exi
 
 ---
 
+## Incremental Mode (Phase 53, default)
+
+`--incremental` is the DEFAULT after Phase 53; pass `--full` to opt out and re-map everything. Incremental runs the change classifier FIRST (via the fingerprint store at `.design/fingerprints/`): it fingerprints the current DesignContext graph, diffs each node against the prior cycle, and dispatches mappers per the verdict. SKIP (cosmetic-only / no-op) dispatches 0 mappers; PARTIAL re-maps only the affected community batches; ARCHITECTURE re-batches the dir-reshaped subset; FULL (or `--full`, or a first run with no prior store) re-maps all batches. The batching + classifier engine lives in `explore` (`scripts/lib/explore-parallel-runner` + `scripts/lib/mappers/incremental-discover.cjs`); this flag selects the path. Detail: `./discover-procedure.md` §Incremental Mode.
+
+---
+
 ## Step 1 - Spawn design-context-builder
 
 Spawn `design-context-builder` -> `.design/DESIGN-CONTEXT.md`. The agent auto-detects via grep/glob first and interviews only for areas where auto-detect returned no confident answer. Baseline audit directory chain: `src/` -> `app/` -> `pages/` -> `lib/` -> flag "layout unknown". Common gray areas to probe (Area 7): font-change risk, token-layer introduction risk, component rebuild-vs-restyle. Wait for `## CONTEXT COMPLETE`, then update STATE.md `task_progress = 0.5`. Full prompt: `./discover-procedure.md` §Step 1.

package/dist/claude-code/.claude/skills/explore/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: gdd-explore
 description: "Stage 2 of 5 - unified exploration merging inventory grep + design interview. Probes 6 connections, scans the codebase, conducts the AskUserQuestion interview, and writes .design/DESIGN.md + DESIGN-DEBT.md + DESIGN-CONTEXT.md. Use after /gdd:brief to map the existing system and lock decisions before planning. Activates for requests involving researching design direction, gathering references, or exploring visual options."
-argument-hint: "[--skip-interview] [--skip-scan]"
+argument-hint: "[--skip-interview] [--skip-scan] [--incremental] [--full]"
 tools: Read, Write, Bash, Grep, Glob, Task, AskUserQuestion, mcp__gdd_state__get, mcp__gdd_state__transition_stage, mcp__gdd_state__probe_connections, mcp__gdd_state__update_progress, mcp__gdd_state__set_status, mcp__gdd_state__add_blocker, mcp__gdd_state__checkpoint, mcp__gdd_state__add_decision
 ---
 
@@ -49,6 +49,8 @@ For each greenfield component in scope: `21st_magic_component_search(component_n
 
 **Parallelism decision**: read `.design/config.json` + `reference/parallelism-rules.md`. Record verdict via `mcp__gdd_state__set_status` (`"explore_parallel"` / `"explore_serial"`). Parallel -> multiple `Task()` in one response; serial -> sequential.
 
+**Incremental batching (Phase 53, default)**: `--incremental` (default; `--full` opts out) runs the change classifier first via the fingerprint store, groups the DesignContext graph into Louvain community batches, and dispatches mappers per the verdict (SKIP=0, PARTIAL=affected batches only, FULL=all). Engine: `scripts/lib/explore-parallel-runner` + `scripts/lib/mappers/incremental-discover.cjs`; dispatch concurrency comes from `concurrency-tuner.cjs`. Detail: `./explore-procedure.md` §Incremental Batching.
+
 Run the canonical scan grep/glob inventory (POSIX ERE, preserving PLAT-01/02): component detection (Glob `**/*.{tsx,jsx,vue,svelte}`), color extraction (hex / rgb / hsl / Tailwind arbitrary), typography scan (font-family / Tailwind `font-*` / `text-*`), motion scan (`transition` / `animate-` / `@keyframes` / `framer-motion`), token detection (tailwind.config / CSS custom properties / token JSON), layout detection (ordered fallback `src/` -> `app/` -> `pages/` -> `lib/` -> unknown). Write `.design/DESIGN.md` + `.design/DESIGN-DEBT.md`. Then `mcp__gdd_state__update_progress` for scan progress. Detail: `./explore-procedure.md` §Step 2.
 
 **Step 2.x - i18n readiness probe (informational, per D-04)**: check `package.json` deps against `{react-intl, next-intl, i18next, vue-i18n, formatjs, lingui}` -> `framework-managed`; else grep `Intl.(DateTimeFormat|NumberFormat|...)` in `src/` -> `partial`; else `none`. Emit single line `Localization readiness: <state>` in the report. NO gate, NO blocking - surface signal only (D-07). Detail: `./explore-procedure.md` §Step 2.x.

package/dist/claude-code/.claude/skills/new-addendum/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: gdd-new-addendum
+description: "Scaffolds a new Phase-54 composable reference addendum for a design-system, framework, or motion library: validates the kind and the slug, defaults composes_into by kind, and writes a 4-section skeleton at reference/{systems|frameworks|motion}/<name>.md from the pure generator. Use when adding stack-specific guidance that an explore mapper should compose at spawn time and you want the frontmatter, the composes_into wiring, and the mandatory sections correct from the first commit. Activates for requests involving authoring a reference addendum, adding stack-specific mapper guidance, scaffolding a systems or frameworks or motion doc, or registering a new design-system."
+argument-hint: "<kind> <name>"
+tools: Read, Write, Bash, AskUserQuestion
+user-invocable: true
+---
+
+# /gdd:new-addendum
+
+**Role:** Scaffold a contract-compliant stack addendum. Validate the kind and the name, then write `reference/{systems|frameworks|motion}/<name>.md` from the pure generator at `scripts/lib/new-addendum.cjs`. This skill writes ONE reference file. It does NOT touch `reference/registry.json` and does NOT run any build; it prints the exact follow-up steps instead.
+
+An addendum is a registry entry, not a skill. Read `reference/registry.json` for the `type:"stack-addendum"` entry shape and `scripts/lib/mapper-spawn.cjs` for how `composes_into` selects an addendum at spawn time. Read one shipped example first, for instance `reference/systems/tailwind.md`, to match the house style.
+
+## Step 1 - Gather the fields
+
+1. **kind**: the first token of `$ARGUMENTS` if present, else ask. Must be one of `system`, `framework`, or `motion`. This picks the target subdir and the default `composes_into`.
+2. **name**: the second token of `$ARGUMENTS` if present, else ask. Must match `^[a-z0-9][a-z0-9-._]*$`. The basename is also the matcher key in `mapper-spawn.cjs`, so it must equal the value `detectStack` reports for this stack (for example `tailwind`, `nextjs`, `framer-motion`). Reject a `reference/{dir}/<name>.md` collision.
+3. **composes_into** (optional): accept the kind default, or override with a comma list of mapper names. Defaults: `system` to `token-mapper, component-taxonomy-mapper`; `framework` to `component-taxonomy-mapper, visual-hierarchy-mapper`; `motion` to `motion-mapper`.
+
+Resolve the target path and check for a collision:
+
+```bash
+node -e "
+const a = require('./scripts/lib/new-addendum.cjs');
+console.log(a.targetPathFor(process.argv[1], process.argv[2]));
+" "<kind>" "<name>"
+```
+
+If that path already exists, stop and tell the user to edit the existing file instead.
+
+## Step 2 - Write the file
+
+Build the record and render the skeleton with the pure generator, then write it with the Write tool (not shell redirection):
+
+```bash
+node -e "
+const a = require('./scripts/lib/new-addendum.cjs');
+const rec = a.buildAddendumRecord({
+  kind: process.env.AD_KIND,
+  name: process.env.AD_NAME,
+  composesInto: process.env.AD_COMPOSES || undefined,
+});
+process.stdout.write(a.renderAddendumMd(rec));
+"
+```
+
+`buildAddendumRecord` throws on an invalid kind, an invalid name, or a malformed composes_into list. Surface the thrown message to the user and re-prompt the offending field. Capture stdout and write it verbatim to the path from Step 1 via the Write tool.
+
+## Step 3 - Fill the four sections
+
+The skeleton ships four mandatory sections with TODO placeholders: Conventions, File patterns, Gotchas, Example output. Replace every TODO with terse vendor-checked bullets (keep the file at or under about 50 lines). Rules:
+
+- Lead with the real vendor docs URL in the attribution comment.
+- The Example output block uses ONLY the Phase 52 DesignContext schema (node types token / component / variant / state / motion-fragment / screen / layer; edge types uses-token / composes / extends / transitions-to / mirrors).
+- Tags must come from `reference/design-context-tag-vocab.md`; drop any tag not in that vocabulary.
+- For a motion addendum, reuse the `reference/motion-transition-taxonomy.md` duration classes (instant / quick / standard / slow / narrative) and call out the seconds-vs-ms-vs-no-duration unit trap.
+- No em dashes anywhere (the `lint:prose` gate scans `reference/`).
+
+## Step 4 - Tell the user the follow-up
+
+The skill stops here by contract. Print the next steps for the maintainer to run:
+
+```
+1. Add a registry entry for "<name>" to reference/registry.json
+   (name addendum-<kind>-<name>, path, type "stack-addendum", phase 54, kind, composes_into, description).
+2. node -e "require('./scripts/lib/reference-registry.cjs').validateRegistry({cwd:process.cwd()})"
+   must report ok:true (the round-trip scan picks up the new subdir file).
+3. npm test (the reference-registry + phase-54 suites must stay green).
+```
+
+The registry round-trip test stays red until the registry entry exists; that is expected and is the maintainer's step.
+
+## Do Not
+
+- Do not edit `reference/registry.json`, `package.json`, or `scripts/lib/manifest/skills.json`.
+- Do not run a build or the registry generator for the user; print the steps.
+- Do not write the file with shell redirection; use the Write tool so the content is exact.
+- Do not invent vendor facts; the addendum content must be vendor-checked.
+
+## NEW-ADDENDUM COMPLETE

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.52.0",
+  "version": "1.54.0",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",