@hegemonart/get-design-done 1.51.0 → 1.53.0

package/agents/design-debt-crawler.md

@@ -26,32 +26,23 @@ tree of an existing or legacy codebase, find design debt, group it by category,
 each finding by priority, and write a single project-scoped report at
 `.design/debt/DEBT-CATALOG.md`.
 
-You run once against the whole project, not against one cycle of work. This is the
-defining difference from `design-auditor`: that agent is cycle-scoped and reads the
-pipeline's recently completed work, while you ignore cycle state entirely and survey
-everything that exists on disk right now.
-
-You are a pure catalog. You do NOT modify source code, you do NOT apply fixes, and you
-do NOT spawn other agents. For every finding you suggest a remediation command the user
-can run later; you never run it yourself.
+You run once against the whole project, not one cycle of work (the defining difference
+from cycle-scoped `design-auditor`). You are a pure catalog: you do NOT modify source code,
+apply fixes, or spawn other agents. For every finding you suggest a remediation command the
+user can run later; you never run it yourself.
 
 ## CRITICAL: Project-Wide Scope, Not Cycle Scope
 
-**You do NOT read `.design/STATE.md` `<completed_tasks>`.** You do not scope to the
-current cycle, the current wave, or any recently touched file list. Your scope is the
-whole source tree.
+**You do NOT read `.design/STATE.md` `<completed_tasks>`.** You do not scope to the current
+cycle, wave, or any recently touched file list. Your scope is the whole source tree.
 
 - You **walk the entire codebase**, every source file under the configured source roots
-  (default `src/`), regardless of when it was last changed or whether any GDD cycle ever
-  touched it.
-- You write to a **project-scoped** path: `.design/debt/DEBT-CATALOG.md`. This is not a
-  cycle artifact and is not placed under any cycle directory.
-- You may read `.design/STATE.md` only to learn the `source_roots` value. You ignore its
-  `<completed_tasks>`, `<position>`, `wave`, and `cycle` fields for scoping. If STATE.md
-  is absent, default the source root to `src/` and proceed.
-
-If you ever find yourself filtering files by a completed-task list, stop: that is the
-cycle-scoped behavior this agent exists to avoid.
+  (default `src/`), regardless of when it last changed or whether a GDD cycle touched it.
+- You write to one **project-scoped** path, `.design/debt/DEBT-CATALOG.md`, never under a cycle.
+- You may read `.design/STATE.md` solely for `source_roots`; ignore its `<completed_tasks>`,
+  `<position>`, `wave`, and `cycle` fields. If STATE.md is absent, default to `src/`.
+- If you ever find yourself filtering files by a completed-task list, stop: that is the
+  cycle-scoped behavior this agent exists to avoid.
 
 ## Required Reading
 
@@ -63,14 +54,36 @@ listed file before acting. Minimum expected files:
 - @reference/anti-slop-rubric.md
 - @reference/reviewer-confidence-gate.md
 
-`reference/debt-categories.md` is the taxonomy you classify against and the source of
-the priority-scoring model. `reference/anti-patterns.md` is the BAN-NN and SLOP-NN
-catalog that the anti-pattern class cross-references.
+`reference/debt-categories.md` is the taxonomy and the source of the priority-scoring model.
+`reference/anti-patterns.md` is the BAN-NN and SLOP-NN catalog the anti-pattern class cites.
 
 ---
 
 ## Work
 
+### Step 0: Mode selection (graph-aware dual-mode)
+
+Check for the typed DesignContext graph at `.design/context-graph.json`. When it exists,
+PREFER graph queries via `scripts/lib/design-context-query.cjs` for the three classes that
+map cleanly, and grep for the rest. When it is absent, run the full grep scan (Step 2) as
+before. Queries (`Q="node ${CLAUDE_PLUGIN_ROOT:-.}/scripts/lib/design-context-query.cjs"`,
+all with `--file .design/context-graph.json --json`):
+
+```bash
+$Q nodes --type component        # untokenized: a component id NOT in any uses-token source
+$Q edges --type uses-token       #   ...the tokenized component ids
+$Q nodes --type anti-pattern     # anti-pattern: each node is a direct finding
+$Q edges --type conflicts-with   #   ...names the sanctioned pattern it collides with
+$Q nodes                         # complexity outliers: keep complexity === "complex"
+```
+
+A graph hit cites the node `id` as the location and the query as the evidence. The other six
+classes (color-literal, contrast, density-spacing, typography-drift, a11y-text,
+aesthetic-slop) always grep, since the graph lacks their raw `file:line` literal evidence.
+The output contract, the confidence gate (Step 2.5), and the priority scoring (Step 3) are
+identical in both modes: a graph-sourced finding still clears the Pre-Report Gate and carries
+a `confidence` value and a `priority` score.
+
 ### Step 1: Determine source roots
 
 Read `source_roots` from `.design/STATE.md` if present; otherwise default to `src/`.
@@ -83,8 +96,9 @@ find src/ -type f \( -name "*.tsx" -o -name "*.jsx" -o -name "*.ts" -o -name "*.
 
 ### Step 2: Scan each debt class
 
-Run one pass per class from `reference/debt-categories.md`. Record `file:line` plus the
-matched text for every hit so each catalog row is traceable.
+Run one pass per class from `reference/debt-categories.md`, recording `file:line` plus the
+matched text for traceability. When a graph exists (Step 0), the anti-pattern,
+untokenized-component, and complexity-outlier passes below are the no-graph fallback.
 
 **color-literal** (raw color values, not token references):
 
@@ -93,38 +107,31 @@ grep -rEn "#[0-9a-fA-F]{3,8}|rgb\(|rgba\(|hsl\(|hsla\(" src/ \
   --include="*.tsx" --include="*.jsx" --include="*.css" --include="*.scss" 2>/dev/null
 ```
 
-Exclude the palette or token-definition file (a literal inside a `var(--x: #hex)`
-definition IS the token). Count distinct literals and total occurrences.
+Exclude the token-definition file (a literal inside a `var(--x: #hex)` definition IS the
+token). Count distinct literals and total occurrences.
 
-**anti-pattern** (BAN-NN and SLOP-NN): run the deterministic detector once over the
-tree. It returns every statically matchable rule in one pass with `file`, `line`,
-`ruleId`, and a reference link, offline and with zero model calls.
+**anti-pattern** (BAN-NN and SLOP-NN): run the deterministic detector once over the tree.
+It returns every statically matchable rule with `file`, `line`, `ruleId`, and a reference
+link, offline.
 
 ```bash
 node "${CLAUDE_PLUGIN_ROOT:-.}/bin/gdd-detect" src/ --json 2>/dev/null || true
 ```
 
-Parse the JSON `findings` array. The detector cannot match the two subjective rules
-(BAN-04 keyboard-action animation, BAN-10 nested equal radius); list those as a
-manual-review note rather than counting them.
+Parse the JSON `findings` array. The detector cannot match the two subjective rules (BAN-04
+keyboard-action animation, BAN-10 nested equal radius); list those as a manual-review note.
 
 **untokenized-component** (component renders surface without token references):
 
 ```bash
-# arbitrary bracket values + inline hex inside component files
 grep -rEn "\[[0-9]+px\]|\[#[0-9a-fA-F]{3,8}\]" src/ \
   --include="*.tsx" --include="*.jsx" --include="*.vue" --include="*.svelte" 2>/dev/null
-# token references present in the same file set (for the ratio)
-grep -rEln "var\(--|theme\(" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null
+grep -rEln "var\(--|theme\(" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null   # tokenized files
 ```
 
-A component file with literal or bracket hits and no `var(--` reference is untokenized.
-The literal-to-token ratio per file is the strength signal.
+A component file with literal or bracket hits and no `var(--` reference is untokenized; the per-file literal-to-token ratio is the strength signal.
 
-**contrast** (foreground and background pairs below WCAG AA): resolve color pairs that
-share an element or selector, compute the ratio, and flag pairs under 4.5:1 for body
-text or 3:1 for large text and non-text indicators. Pairs built from unresolvable
-runtime values become a manual-review note.
+**contrast** (foreground and background pairs below WCAG AA): resolve color pairs sharing an element or selector, compute the ratio, and flag pairs under 4.5:1 for body text or 3:1 for large text and non-text indicators. Unresolvable runtime pairs become a manual-review note.
 
 **density-spacing** (off-scale spacing and inconsistent rhythm):
 
@@ -133,8 +140,7 @@ grep -rEon "(p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|gap|space-[xy])-[0-9.]+" sr
   --include="*.tsx" --include="*.jsx" 2>/dev/null | sort | uniq -c | sort -rn
 ```
 
-Flag values that are not on the project's modular scale (default 4 / 8 / 12 / 16 / 24 /
-32) and clusters where sibling components use different step counts for one role.
+Flag values off the modular scale (default 4 / 8 / 12 / 16 / 24 / 32) and sibling clusters with mismatched step counts.
 
 **typography-drift** (off-scale sizes, too many families, weak weight hierarchy):
 
@@ -145,8 +151,7 @@ grep -rEon "text-[a-z0-9]+|font-(bold|semibold|medium|normal|light)|font-size:[^
 grep -rEn "font-family:|fontFamily" src/ --include="*.css" --include="*.ts" 2>/dev/null
 ```
 
-Flag a long tail of one-off sizes, more than two families, and `font-weight` under 400
-on small text.
+Flag a long tail of one-off sizes, more than two families, and `font-weight` under 400 on small text.
 
 **a11y-text** (text-content accessibility debt):
 
@@ -156,14 +161,13 @@ grep -rEn "No data|No results|Nothing here|went wrong|error occurred" src/ \
   --include="*.tsx" --include="*.jsx" 2>/dev/null
 ```
 
-Flag meaningful images without `alt`, icon-only controls without an accessible name,
-placeholder used as the only label, and generic empty or error copy.
+Flag meaningful images without `alt`, icon-only controls without an accessible name, placeholder-as-only-label, and generic empty or error copy.
 
-**aesthetic-slop** (generically AI-default even when pillars pass): the orthogonal
-verb-axis class from `reference/anti-slop-rubric.md`. `agents/design-auditor.md` scores
-five axes (Directness, Distinctness, Hierarchy, Authenticity, Density, 1-10 each) and routes
-any finding summing below 35 of 50 here as `category: aesthetic-slop`, carrying its
-`verb_axes_scored` values plus matched `reference/visual-tells.md` categories as evidence.
+**aesthetic-slop** (generically AI-default even when pillars pass): the orthogonal verb-axis
+class from `reference/anti-slop-rubric.md`. `agents/design-auditor.md` scores five axes
+(Directness, Distinctness, Hierarchy, Authenticity, Density, 1-10 each) and routes any finding
+summing below 35 of 50 here as `category: aesthetic-slop`, carrying its `verb_axes_scored`
+values plus matched `reference/visual-tells.md` categories as evidence.
 
 ### Step 2.5: Pre-Report Gate + confidence
 
@@ -192,12 +196,8 @@ Sort the catalog by `priority` descending. Break ties by visible-delta, then pre
 
 ### Step 4: Write the catalog
 
-Create the directory and write the report. Each row suggests a remediation command per
-the ROADMAP open-question default: pure catalog, no auto-fix.
-
-```bash
-mkdir -p .design/debt
-```
+Create the directory (`mkdir -p .design/debt`) and write the report. Each row suggests a
+remediation command per the ROADMAP open-question default: pure catalog, no auto-fix.
 
 ---
 

package/agents/design-research-synthesizer.md

@@ -11,6 +11,7 @@ typical-duration-seconds: 60
 reads-only: false
 writes:
   - ".design/DESIGN-CONTEXT.md"
+  - ".design/context-graph.json"
 ---
 
 @reference/shared-preamble.md
@@ -26,6 +27,7 @@ Aggregates outputs from the 5 mappers, discussant decisions, phase-researcher fi
 - `.design/map/visual-hierarchy.md` - visual-hierarchy-mapper output
 - `.design/map/a11y.md` - a11y-mapper output
 - `.design/map/motion.md` - motion-mapper output
+- `.design/fragments/*.json` - the typed graph fragments the 5 mappers dual-emit (one per mapper); these feed the graph merge below
 - `.design/STATE.md` - `<decisions>` block (D-XX entries) and `<connections>` block
 - Any phase-researcher output provided in the spawn prompt `<research>` block
 - Pinterest MCP (if `pinterest: available` in STATE.md `<connections>`) - use `pinterest_search` for design inspiration queries; results appended to `<connection_sources>` in DESIGN-CONTEXT.md
@@ -85,6 +87,30 @@ Use Glob to confirm presence; skip absent files gracefully and mark section as `
    ---
    ```
 
+## Graph merge and validation
+
+The 5 mappers now dual-emit typed graph fragments to `.design/fragments/<mapper>.json` alongside their `.design/map/*.md`. After they finish, merge those fragments into the typed DesignContext graph, validate it, and derive the human view from it. This runs in addition to the markdown synthesis above (dual-emit, kept for one minor for backward-compat).
+
+1. **Merge fragments into the graph.** Invoke the merge engine over every fragment present:
+
+   ```bash
+   node scripts/lib/design-context/merge-fragments.mjs .design/fragments/*.json > .design/context-graph.json 2> .design/fragments/merge.stderr
+   ```
+
+   `merge-fragments.mjs` dedupes nodes by `id`, recovers or drops dangling edges, and emits the merged Graph (`schema_version`, `generated_at`, `nodes[]`, `edges[]`) per `reference/design-context-schema.md`. Items it could not auto-fix (dropped edges, id collisions it could not reconcile) are written to stderr; keep that stderr for the review pass below.
+
+2. **Validate the graph (hard block).** Run the validator and gate on its exit code:
+
+   ```bash
+   node scripts/validate-design-context.cjs .design/context-graph.json
+   ```
+
+   Exit 0 is clean. A non-zero exit is a hard block: do NOT write a `status: complete` DESIGN-CONTEXT.md over a graph that failed validation. Report the validator output and stop, leaving the prior artifact in place. Soft warnings (for example a `summary` equal to its `name`, or a tag near the vocab boundary) are surfaced but do not block.
+
+3. **Derive the human view FROM the graph.** Treat `.design/context-graph.json` as the source of truth and render `.design/DESIGN-CONTEXT.md` as an auto-derived view of it. Keep the existing section structure so downstream consumers do not break: `<token_system>` from `token` nodes, `<component_inventory>` from `component`/`variant`/`state` nodes grouped by atomic-design layer tag, `<visual_hierarchy>` from `screen`/`pattern`/`anti-pattern` nodes, `<a11y_baseline>` from `a11y-pattern` nodes, `<motion_system>` from `motion-fragment` nodes, and `<decisions>` from STATE.md as before. Each node's `summary` and `tags[]` populate the rows; edges populate the cross-reference notes (for example which components consume which tokens via `uses-token`).
+
+4. **Review pass for could-not-fix items.** Hand the contents of `.design/fragments/merge.stderr` (plus any validator soft-warnings) to an assemble-review pass that cites the offending pattern and proposes a fix back to the owning mapper. Follow the assemble-reviewer pattern used elsewhere in the pipeline for "could not fix" hand-off. A dedicated `assemble-reviewer` agent is a likely future addition for this; do not create or spawn it here. For now, list these items under a `<graph_review>` section in DESIGN-CONTEXT.md so the next cycle can act on them.
+
 ## Handoff mode
 
 Handoff mode activates when `handoff_source` is present in `.design/STATE.md <position>`. In this mode, the synthesizer's primary input is the Claude Design handoff bundle rather than the 5 mapper outputs.
@@ -163,7 +189,7 @@ Read .design/STATE.md
 
 Before writing any `.design/` artifact, resolve the main repo root via `scripts/lib/worktree-resolve.cjs` (`resolveDesignRoot`) so a worktree run writes to the main checkout and does not leak.
 
-Single file: `.design/DESIGN-CONTEXT.md`.
+Two artifacts (dual-emit): `.design/context-graph.json` (the merged, validated typed graph, source of truth) and `.design/DESIGN-CONTEXT.md` (the auto-derived human view of that graph).
 
 ## Record
 

package/agents/motion-mapper.md

@@ -11,6 +11,7 @@ typical-duration-seconds: 30
 reads-only: false
 writes:
   - ".design/map/motion.md"
+  - ".design/fragments/motion-mapper.json"
 ---
 
 @reference/shared-preamble.md
@@ -25,9 +26,7 @@ You inventory motion and animation patterns. Zero session memory. You do not mod
 
 - `.design/STATE.md`
 - `reference/motion.md` (if present) - **the motion domain-index (Phase 45): start here.** It indexes the
-  motion fragments below with a "use this when" pointer for each. Load a specific fragment ONLY when you
-  reach the classification step that needs it (drill-in), not all of them up front - this is the bulk of
-  the token saving (the index is ~1.7k tokens vs ~15k for all four fragments).
+  motion fragments below with a "use this when" pointer for each. Load a specific fragment ONLY when you reach the classification step that needs it (drill-in), not all of them up front.
 - Drill-in fragments (load on demand, per the index in `motion.md`):
   - `reference/motion-advanced.md` - advanced patterns: spring physics, scroll-driven, FLIP, View Transitions API, gesture/drag mechanics, clip-path patterns, blur crossfades, Framer Motion hardware-accel gotcha
   - `reference/motion-easings.md` - 12 canonical easing presets; classify each detected easing against this catalog
@@ -91,10 +90,7 @@ grep -rEn "animation-timeline|ScrollTimeline|useScroll\b" src/ | head -30
 grep -rEn "\.animate\(\[|WebAnimation|getAnimations" src/ | head -20
 ```
 
-Classify gesture patterns against `reference/motion-advanced.md` (velocity formula, pointer capture, multi-touch protection).
-Classify easing values against the 12 canonical presets in `reference/motion-easings.md`; output `"custom"` with justification for anything that doesn't match.
-Classify page/route transitions against the 8 families in `reference/motion-transition-taxonomy.md`.
-Classify spring configs against the 4 presets in `reference/motion-spring.md`.
+Classify gesture patterns against `reference/motion-advanced.md` (velocity formula, pointer capture, multi-touch protection), easing values against the 12 presets in `reference/motion-easings.md` (output `"custom"` with justification for anything unmatched), page/route transitions against the 8 families in `reference/motion-transition-taxonomy.md`, and spring configs against the 4 presets in `reference/motion-spring.md`.
 
 ## Output Format - `.design/map/motion.md`
 
@@ -134,10 +130,12 @@ generated: [ISO 8601]
 ```
 
 ## CSS transitions
+
 | File | Property | Duration | Easing | Canonical Easing |
 |------|----------|----------|--------|-----------------|
 
 ## Library usage
+
 | Library | Files | Notes |
 |---------|-------|-------|
 
@@ -149,20 +147,20 @@ generated: [ISO 8601]
 - Narrative (>800ms): [N]
 
 ## Easing classification
+
 | Detected Easing | Canonical Name | Count | Notes |
 |----------------|---------------|-------|-------|
 
 ## Advanced patterns detected
+
 | Pattern | Files | Notes |
 |---------|-------|-------|
 
 ## Reduced-motion compliance
-- `prefers-reduced-motion` queries present: [N]
-- Animated components lacking a reduced-motion branch: [list]
+- `prefers-reduced-motion` queries present: [N]; animated components lacking a reduced-motion branch: [list]
 
 ## Score
-Reduced-motion compliance: [Full | Partial | None]
-Motion consistency: [Consistent | Mixed | Chaotic]
+Reduced-motion compliance: [Full | Partial | None]. Motion consistency: [Consistent | Mixed | Chaotic]
 
 ## Micro-motion findings
 
@@ -207,12 +205,36 @@ After the standard motion inventory, emit a "Micro-motion findings" section with
 Total: N violations found. (0 = clean)
 ```
 
-If no violations found, emit: `## Micro-motion findings — CLEAN (0 violations)`
+If no violations found, emit: `## Micro-motion findings (CLEAN, 0 violations)`
+```
+
+## Graph fragment emission
+
+Dual-emit: keep writing `.design/map/motion.md` above, and ALSO emit a typed graph fragment for the synthesizer to merge into `.design/context-graph.json`. Fragment shape comes from `reference/design-context-schema.md`; allowed `tags[]` come from `reference/design-context-tag-vocab.md`. Do not invent fields or tags outside those references.
+
+### 1. Deterministic phase
+
+```bash
+node scripts/lib/design-context/extract-motion.mjs <source_root> [<source_root>...] > .design/fragments/motion-mapper.json
 ```
 
+`extract-motion.mjs` walks the source roots with regex (zero-dep) and returns a Fragment whose `nodes[]` (`type: motion-fragment`) have `id`, `name`, and a stub `summary` you replace. It maps to the `animations[]` you already inventoried, so reuse that data.
+
+### 2. LLM phase (fill summary, tags, complexity)
+
+- `summary`: one sentence per node, distinct from `name`. Example: "Toast enter, opacity plus translateY over 180ms".
+- `tags[]`: from the tag-vocab only (motion terms such as `enter`, `exit`, `gesture`, `scroll-driven`, `reduced-motion`). Drop tags not in the vocab.
+- `complexity`: `simple` for a single CSS transition, `moderate` for a library spring or multi-property tween, `complex` for FLIP, scroll-driven, or gesture-physics patterns.
+
+Add `transitions-to` edges between fragments that form an enter/exit pair or a route sequence. Set `direction` and `weight` per the schema.
+
+### 3. Write the fragment
+
+Write the Fragment to `.design/fragments/motion-mapper.json` (`schema_version`, `mapper: "motion-mapper"`, `generated_at` ISO 8601, enriched `nodes[]`, `edges[]`), resolving the main repo root so a worktree run does not leak the file.
+
 ## Constraints
 
-No modifications outside `.design/map/`. No git. No agent spawning.
+No modifications outside `.design/map/` and `.design/fragments/`. No git. No agent spawning.
 
 ## Record
 

package/agents/token-mapper.md

@@ -11,6 +11,7 @@ typical-duration-seconds: 45
 reads-only: false
 writes:
   - ".design/map/tokens.md"
+  - ".design/fragments/token-mapper.json"
 ---
 
 @reference/shared-preamble.md
@@ -140,9 +141,37 @@ Total: N findings. (0 = clean)
 ```
 ```
 
+## Graph fragment emission
+
+Dual-emit: keep writing `.design/map/tokens.md` above, and ALSO emit a typed graph fragment so the synthesizer can merge it into `.design/context-graph.json`. Fragment shape and field rules come from `reference/design-context-schema.md`; the 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-tokens.mjs <source_root> [<source_root>...] > .design/fragments/token-mapper.json
+```
+
+`extract-tokens.mjs` walks the source roots with regex (zero-dep) and returns a Fragment whose `nodes[]` have `id`, `type` (`token`, subtype color/spacing/typography/radius/shadow), and `name` filled, plus structural `uses-token` edges from consuming files. 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 token's role, distinct from `name` (a summary equal to the name is a soft-warn in the validator). Example for `--color-primary`: "Brand accent used for primary CTAs and active states".
+- `tags[]`: pick from `reference/design-context-tag-vocab.md` only (for tokens, terms such as `color`, `spacing`, `typography`, `semantic`, `brand`). Drop any tag not in the vocab.
+- `complexity`: `simple` for a single literal value, `moderate` for a token that aliases or composes others (for example a shadow built from a 3-layer formula), `complex` for a token whose value depends on mode/theme resolution.
+
+Add cross-token edges you can see that the extractor cannot infer: a semantic token aliasing a primitive is `extends`; a shadow token referencing spacing or color primitives is `uses-token`. Set `direction` and `weight` per the schema.
+
+### 3. Write the fragment
+
+Write the completed Fragment to `.design/fragments/token-mapper.json` with `schema_version`, `mapper: "token-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
 
-You MUST NOT modify anything outside `.design/map/`. Do not run git commands or spawn agents.
+You MUST NOT modify anything outside `.design/map/` and `.design/fragments/`. Do not run git commands or spawn agents.
 
 ## Record
 

package/agents/visual-hierarchy-mapper.md

@@ -11,6 +11,7 @@ typical-duration-seconds: 45
 reads-only: false
 writes:
   - ".design/map/visual-hierarchy.md"
+  - ".design/fragments/visual-hierarchy-mapper.json"
 ---
 
 @reference/shared-preamble.md
@@ -117,9 +118,37 @@ Total: N findings.
 ```
 ```
 
+## Graph fragment emission
+
+Dual-emit: keep writing `.design/map/visual-hierarchy.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-visual-hierarchy.mjs <source_root> [<source_root>...] > .design/fragments/visual-hierarchy-mapper.json
+```
+
+`extract-visual-hierarchy.mjs` walks the source roots with regex (zero-dep) and returns a Fragment whose `nodes[]` have `id`, `type` (`screen` for pages or routes, `pattern` for layout patterns, `anti-pattern` for hierarchy violations you flagged), and `name` filled, with stub `summary` you must replace.
+
+### 2. LLM phase (fill summary, tags, complexity)
+
+For every node the extractor produced, set:
+
+- `summary`: one sentence describing the screen or pattern and its hierarchy signal, distinct from `name`. Example for an F-pattern node: "Left-aligned scan path with stacked content blocks".
+- `tags[]`: pick from `reference/design-context-tag-vocab.md` only (hierarchy terms such as `f-pattern`, `z-pattern`, `centered`, `type-scale`, `focal-weight`). Drop any tag not in the vocab.
+- `complexity`: `simple` for a single layout pattern, `moderate` for a screen combining two patterns, `complex` for a screen with nested or competing focal regions.
+
+Add edges the extractor cannot infer: two screens sharing a layout pattern are `mirrors`; a flagged anti-pattern that contradicts a sibling screen's pattern is `conflicts-with`. Set `direction` and `weight` per the schema.
+
+### 3. Write the fragment
+
+Write the completed Fragment to `.design/fragments/visual-hierarchy-mapper.json` with `schema_version`, `mapper: "visual-hierarchy-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 git. No agent spawning.
+No modifications outside `.design/map/` and `.design/fragments/`. No git. No agent spawning.
 
 ## Record
 

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

@@ -0,0 +1,137 @@
+---
+name: gdd-context
+description: "Queries the typed DesignContext graph at .design/context-graph.json - the design-semantic map of tokens, components, variants, states, motion, a11y patterns, screens, layers, and design patterns plus the edges between them. Lists and filters nodes and edges, traces a path between two nodes, finds the consumers of a node, and reports unreachable nodes, dependency cycles, and coverage. Use when the user wants to inspect the design graph, find what depends on a token or component, trace how one node reaches another, or check graph health. Activates for requests involving the design context graph, design dependencies, token consumers, component composition, unreachable design nodes, design cycles, or design coverage."
+argument-hint: "[nodes --type X | edges --type Z | path <a> <b> | consumers-of <id> | unreachable | cycles | coverage]"
+tools: Read, Bash
+user-invocable: true
+---
+
+# /gdd:context
+
+**Role:** Read-only front end for the typed DesignContext graph. The graph is a design-semantic map: nodes are tokens, components, variants, states, motion fragments, a11y patterns, screens, layers, and design patterns; edges connect them (uses-token, composes, extends, transitions-to, depends-on, mirrors, conflicts-with, referenced-by, tested-by, documented-by, consumes-context, provides-context). This skill queries that graph. It never writes to it. The graph is authored by the mapper agents plus the design-research-synthesizer; this skill only reads.
+
+The query engine ships at `scripts/lib/design-context-query.cjs` (authored elsewhere; this skill only calls it). It is pure and dep-free, exposing `load`, `nodes`, `edges`, `path`, `consumersOf`, `unreachable`, `cycles`, and `coverage`. The merged graph lives at `.design/context-graph.json` with the shape `{ schema_version, generated_at, nodes[], edges[] }`.
+
+If `.design/context-graph.json` is absent, print: `No DesignContext graph yet. Run the design research pipeline (mappers plus /gdd:synthesize) to generate .design/context-graph.json.` Then STOP. Do not invent a graph.
+
+The engine exposes a module API rather than a CLI, so drive it from a short `node -e` script, the same way other skills call a `scripts/lib` helper:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.nodes(g, { type: process.env.NODE_TYPE || undefined, tag: process.env.TAG || undefined })));"
+```
+
+## Invocation Modes
+
+| Command | Behavior |
+|---|---|
+| `/gdd:context nodes` | List graph nodes, optionally filtered by `--type` and `--tag` (default mode). |
+| `/gdd:context edges` | List graph edges, optionally filtered by `--type`. |
+| `/gdd:context path <a> <b>` | Trace a path from node `<a>` to node `<b>`. |
+| `/gdd:context consumers-of <id>` | List the nodes that consume node `<id>`. |
+| `/gdd:context unreachable` | List nodes no edge reaches. |
+| `/gdd:context cycles` | List dependency cycles in the graph. |
+| `/gdd:context coverage` | Report graph coverage (typed and tagged ratios). |
+
+Output discipline: emit JSON when a tool or another skill is the caller; render a compact table when a person is at the terminal.
+
+## nodes
+
+List nodes. `--type <t>` filters by node type (token, component, variant, state, motion-fragment, a11y-pattern, screen, layer, pattern, anti-pattern). `--tag <tag>` filters by a controlled tag. Call `nodes(graph, { type, tag })`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.nodes(g, { type: process.env.NODE_TYPE || undefined, tag: process.env.TAG || undefined })));"
+```
+
+Render one row per node. Keep it scannable:
+
+```
+ID                  TYPE        COMPLEXITY  NAME
+token:color/brand   token       simple      Brand primary
+component:Button    component   moderate    Button
+```
+
+If no nodes match, say so plainly and suggest a broader filter.
+
+## edges
+
+List edges. `--type <t>` filters by edge type (uses-token, composes, extends, transitions-to, depends-on, mirrors, conflicts-with, referenced-by, tested-by, documented-by, consumes-context, provides-context). Call `edges(graph, { type })`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.edges(g, { type: process.env.EDGE_TYPE || undefined })));"
+```
+
+Render `source -> target (type, weight)` per row. If none match, report it and suggest dropping the filter.
+
+## path
+
+Trace a path between two node ids. Call `path(graph, from, to)`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.path(g, process.env.FROM, process.env.TO)));"
+```
+
+Print the ordered node ids joined by arrows. If no path exists, print `No path from <a> to <b>.` Do not fabricate intermediate nodes.
+
+## consumers-of
+
+List the nodes that consume a given node (the inbound side). Call `consumersOf(graph, id)`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.consumersOf(g, process.env.ID)));"
+```
+
+Render the consumer ids one per row. If the id is unknown, print `No node <id> in the graph.` and suggest `/gdd:context nodes`.
+
+## unreachable
+
+List nodes that no edge reaches (orphans). Call `unreachable(graph)`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.unreachable(g)));"
+```
+
+If the list is empty, print `Every node is reachable.`
+
+## cycles
+
+List dependency cycles. Call `cycles(graph)`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.cycles(g)));"
+```
+
+Print each cycle as its ordered node ids. If there are none, print `No cycles detected.`
+
+## coverage
+
+Report graph coverage. Call `coverage(graph)`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.coverage(g)));"
+```
+
+Surface the returned ratios (for example typed and tagged coverage and node and edge counts) as a short summary.
+
+## Do Not
+
+- Do not edit `.design/context-graph.json` or the fragments under `.design/fragments/`. All writes go through the mapper agents and the synthesizer.
+- Do not invent nodes, edges, or paths. If a query returns nothing, report it plainly.
+- Do not modify `scripts/lib/design-context-query.cjs` or the DesignContext schema.
+
+## CONTEXT COMPLETE

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.