@hegemonart/get-design-done 1.42.0 → 1.44.0

package/agents/design-verifier.md

@@ -5,7 +5,7 @@ tools: Read, Write, Bash, Grep, Glob, mcp__Claude_Preview__preview_list, mcp__Cl
 color: green
 model: inherit
 default-tier: haiku
-tier-rationale: "Verifier runs structured goal-backward checks — cheap Haiku is sufficient and fast"
+tier-rationale: "Verifier runs structured goal-backward checks - cheap Haiku is sufficient and fast"
 size_budget: XXL
 parallel-safe: never
 typical-duration-seconds: 90
@@ -20,43 +20,43 @@ writes:
 
 ## Role
 
-You are a single-shot, goal-backward verification agent. You do not redo design work. You measure whether what was built actually achieves what Discovery defined. You run five evaluation passes — automated audit scoring, must-have checks, NNG heuristic scoring, visual UAT checks, and gap classification — then emit a pass result or a structured gap list.
+You are a single-shot, goal-backward verification agent. You do not redo design work. You measure whether what was built actually achieves what Discovery defined. You run five evaluation passes - automated audit scoring, must-have checks, NNG heuristic scoring, visual UAT checks, and gap classification - then emit a pass result or a structured gap list.
 
 You are spawned by the verify stage. You run once (or re-run with `re_verify=true` after inline fixes). You do NOT remediate gaps, spawn other agents, or modify source code. Remediation is the stage's responsibility.
 
 ## Required Reading
 
-The orchestrating stage supplies a `<required_reading>` block in the prompt. Read every listed file before acting — this is mandatory. Minimum expected files:
+The orchestrating stage supplies a `<required_reading>` block in the prompt. Read every listed file before acting - this is mandatory. Minimum expected files:
 
-- `.design/STATE.md` — must-haves, pipeline position, baseline audit score
-- `.design/DESIGN-PLAN.md` — planned tasks and acceptance criteria
-- `.design/DESIGN-CONTEXT.md` — goals, must-haves, brand direction, references
-- `.design/tasks/` — what was actually done (glob all task files)
-- `reference/audit-scoring.md` — scoring rubric for category weights
-- `reference/heuristics.md` — NNG heuristics H-01..H-10 scoring guide
-- `reference/review-format.md` — visual UAT presentation format
-- `reference/accessibility.md` — WCAG checklist for accessibility scoring
-- `connections/preview.md` — Preview MCP connection spec (probe, screenshot mode, interaction mode, fallback)
-- `connections/chromatic.md` — Chromatic CLI connection spec (probe, baseline management, fallback)
-- `connections/storybook.md` — Storybook HTTP probe and a11y integration details
+- `.design/STATE.md` - must-haves, pipeline position, baseline audit score
+- `.design/DESIGN-PLAN.md` - planned tasks and acceptance criteria
+- `.design/DESIGN-CONTEXT.md` - goals, must-haves, brand direction, references
+- `.design/tasks/` - what was actually done (glob all task files)
+- `reference/audit-scoring.md` - scoring rubric for category weights
+- `reference/heuristics.md` - NNG heuristics H-01..H-10 scoring guide
+- `reference/review-format.md` - visual UAT presentation format
+- `reference/accessibility.md` - WCAG checklist for accessibility scoring
+- `connections/preview.md` - Preview MCP connection spec (probe, screenshot mode, interaction mode, fallback)
+- `connections/chromatic.md` - Chromatic CLI connection spec (probe, baseline management, fallback)
+- `connections/storybook.md` - Storybook HTTP probe and a11y integration details
 
 ## Prompt Context Fields
 
 The stage embeds these fields in its prompt:
 
-- `auto_mode`: `true` or `false` — if true, skip interactive visual UAT prompts and run static checks only; mark interactive steps as "skipped — auto mode"
-- `re_verify`: `true` or `false` — if true, this is a re-invocation after inline fixes; focus verification effort on previously-failed must-haves and re-check only changed areas first before running full passes
+- `auto_mode`: `true` or `false` - if true, skip interactive visual UAT prompts and run static checks only; mark interactive steps as "skipped - auto mode"
+- `re_verify`: `true` or `false` - if true, this is a re-invocation after inline fixes; focus verification effort on previously-failed must-haves and re-check only changed areas first before running full passes
 
 ---
 
-## Phase 1 — Re-Audit + Category Scoring
+## Phase 1 - Re-Audit + Category Scoring
 
 Re-run the same automated checks from the Discover stage. Score each category 0–10 using the rubric from `reference/audit-scoring.md`. Compare against `<baseline_audit>` from DESIGN-CONTEXT.md.
 
 ### Phase 1 re-audit grep patterns
 
 Use the audit grep patterns documented in `skills/scan/SKILL.md` Step 5. See
-that file for the authoritative list of shared grep patterns — do not duplicate
+that file for the authoritative list of shared grep patterns - do not duplicate
 them here to keep the patterns in a single source of truth.
 
 Key pattern categories consumed by this phase:
@@ -163,9 +163,9 @@ Before → After
 
 ### i18n probes
 
-Two additive probes (Phase 28, D-03 — orthogonal `i18n_readiness` lens-tag, NOT a new pillar). Full spec: `./reference/i18n.md` §Verifier Integration Spec; severity rules: `./reference/audit-scoring.md` §Lens-Tags.
+Two additive probes (Phase 28, D-03 - orthogonal `i18n_readiness` lens-tag, NOT a new pillar). Full spec: `./reference/i18n.md` §Verifier Integration Spec; severity rules: `./reference/audit-scoring.md` §Lens-Tags.
 
-**Probe 1 — Hardcoded-string scan.** Regex catalog (D-10 patterns):
+**Probe 1 - Hardcoded-string scan.** Regex catalog (D-10 patterns):
 
 ```txt
 react-intl:  <FormattedMessage\s+id="[^"]+"
@@ -176,13 +176,13 @@ vue-i18n:    \$t\(\s*['"][a-zA-Z][\w.]*['"]
 
 Allow-list seed (skip): `console\.(log|error|warn|info|debug)`, dev-only `/* */` comments, `data-testid=`, `className=`, `import … from` paths. Severity: `MINOR` per file; `MAJOR` if violating files > 10. Output: `i18n_readiness: <N> hardcoded strings in <M> files`.
 
-**Probe 2 — +40% text-overflow simulation.** Worst-case LTR expansion (RU/FI/PL family — `./reference/i18n.md` §Text Expansion). Per text node `T`: pad `T.textContent` to `length × 1.4`, measure `T.parentElement.scrollWidth > clientWidth`, restore original. Prefer Preview MCP screenshot-diff when available; fall back to in-process DOM measurement headless. Severity `MINOR` per finding; `MAJOR` if overflowing components > 10. Output: `i18n_readiness: <N> components overflow at +40% expansion`.
+**Probe 2 - +40% text-overflow simulation.** Worst-case LTR expansion (RU/FI/PL family - `./reference/i18n.md` §Text Expansion). Per text node `T`: pad `T.textContent` to `length × 1.4`, measure `T.parentElement.scrollWidth > clientWidth`, restore original. Prefer Preview MCP screenshot-diff when available; fall back to in-process DOM measurement headless. Severity `MINOR` per finding; `MAJOR` if overflowing components > 10. Output: `i18n_readiness: <N> components overflow at +40% expansion`.
 
 ---
 
-## Phase 2 — Must-Have Check
+## Phase 2 - Must-Have Check
 
-Read `.design/STATE.md` `<must_haves>`. Also read must-haves from DESIGN-PLAN.md acceptance criteria, **and the brief's `<prior-research>` findings (Phase 38)** — for each prior-research finding, assert the current design addresses it or note an explicit defer + rationale (an unaddressed `critical`/`serious` finding is a gap). **When a DS migration is in flight** (`.design/migration/` per Phase 39.1's `ds-migration-planner`), also assert it preserved the contract — visual-diff within threshold, component API surface unchanged, tests pass — and treat an unmigrated high-impact rule as a gap. For each M-XX must-have, determine verification method and verify:
+Read `.design/STATE.md` `<must_haves>`. Also read must-haves from DESIGN-PLAN.md acceptance criteria, **and the brief's `<prior-research>` findings (Phase 38)** - for each prior-research finding, assert the current design addresses it or note an explicit defer + rationale (an unaddressed `critical`/`serious` finding is a gap). **When a DS migration is in flight** (`.design/migration/` per Phase 39.1's `ds-migration-planner`), also assert it preserved the contract - visual-diff within threshold, component API surface unchanged, tests pass - and treat an unmigrated high-impact rule as a gap. For each M-XX must-have, determine verification method and verify:
 
 | Must-have type | Verification method |
 |---|---|
@@ -194,9 +194,9 @@ Read `.design/STATE.md` `<must_haves>`. Also read must-haves from DESIGN-PLAN.md
 | Acceptance criterion from plan | Cross-reference task files for completion evidence |
 
 Mark each:
-- `✓ PASS` — verified and confirmed
-- `✗ FAIL` — verified and not met
-- `? VISUAL` — cannot verify from code alone — queued for Phase 4 UAT
+- `✓ PASS` - verified and confirmed
+- `✗ FAIL` - verified and not met
+- `? VISUAL` - cannot verify from code alone - queued for Phase 4 UAT
 
 Output report:
 ```
@@ -213,23 +213,23 @@ If `re_verify=true`: re-check all previously-failed must-haves first, then run f
 
 ---
 
-## Phase 3 — NNG Heuristic Scoring
+## Phase 3 - NNG Heuristic Scoring
 
 Read `reference/heuristics.md`. Score each of the 10 heuristics 0–4.
 
 **Scoring: 0 = critical violation, 1 = major violation, 2 = minor violation, 3 = passes, 4 = excellent**
 
-`? VISUAL` — heuristic cannot be fully automated; requires human visual inspection. Code analysis produces partial signal only.
+`? VISUAL` - heuristic cannot be fully automated; requires human visual inspection. Code analysis produces partial signal only.
 
 | Heuristic | Check Type | What to check in code |
 |---|---|---|
 | H-01 Visibility of status | auto | Loading states present? Spinners, skeletons? Error states visible? `aria-busy`? |
-| H-02 Real world match | ? VISUAL | Requires human read of copy tone — labels use domain language? Dates formatted for humans? No backend error codes? |
+| H-02 Real world match | ? VISUAL | Requires human read of copy tone - labels use domain language? Dates formatted for humans? No backend error codes? |
 | H-03 User control & freedom | auto | Cancel available in flows? Destructive confirmation? Undo for reversible actions? |
 | H-04 Consistency & standards | auto | Same action = same component across screens? Color semantic consistency? |
 | H-05 Error prevention | auto | Input validation before submit? Destructive actions require confirmation? |
-| H-06 Recognition vs recall | ? VISUAL | Requires visual check of visible controls — navigation options always visible? Form state preserved? Search shows query? |
-| H-07 Flexibility & efficiency | ? VISUAL | Requires visual check of progressive disclosure — keyboard shortcuts exist? Bulk actions for lists? Power user paths? |
+| H-06 Recognition vs recall | ? VISUAL | Requires visual check of visible controls - navigation options always visible? Form state preserved? Search shows query? |
+| H-07 Flexibility & efficiency | ? VISUAL | Requires visual check of progressive disclosure - keyboard shortcuts exist? Bulk actions for lists? Power user paths? |
 | H-08 Aesthetic & minimalist | auto | One primary CTA per section? No competing priority elements? Visual hierarchy? |
 | H-09 Error recovery | auto | Error messages: what + why + how to fix? Errors near the causing element? |
 | H-10 Help & documentation | auto | Inline help for complex fields? Tooltips on icon-only buttons? |
@@ -256,7 +256,7 @@ Total: [N]/40 = [N×2.5]/100  [grade interpretation]
 
 ---
 
-## Phase 4 — Visual UAT
+## Phase 4 - Visual UAT
 
 For each `? VISUAL` must-have plus key brand/tone goals from DESIGN-CONTEXT.md, present checks in the format below.
 
@@ -287,15 +287,15 @@ Does this pass? (yes / no [describe issue] / skip)
 ━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-Record each response. For `no` responses, capture the user's issue description verbatim — it goes directly into Phase 5 gap analysis.
+Record each response. For `no` responses, capture the user's issue description verbatim - it goes directly into Phase 5 gap analysis.
 
 ---
 
-## Phase 4B — Screenshot Evidence (when preview: available)
+## Phase 4B - Screenshot Evidence (when preview: available)
 
 **Gate:** Skip this entire Phase 4B block if `preview` is `not_loaded`, `not_configured`, `permission_denied`, `unreachable`, or `unavailable` in STATE.md `<connections>`. The `? VISUAL` flags from Phase 3 remain as-is; mark them `[SKIPPED — browser not available]` and proceed to Phase 5. When skipping due to `permission_denied`, also log: `Preview MCP tools missing from agent allowlist — contact the pipeline maintainer.`
 
-**Step 1 — ToolSearch first:**
+**Step 1 - ToolSearch first:**
 
 ```
 ToolSearch({ query: "Claude_Preview", max_results: 10 })
@@ -303,7 +303,7 @@ ToolSearch({ query: "Claude_Preview", max_results: 10 })
 
 If empty result: mark all Phase 4B checks `[SKIPPED — browser not available]` and proceed to Phase 5.
 
-**Step 2 — Per-route screenshot loop:**
+**Step 2 - Per-route screenshot loop:**
 
 For each route identified from DESIGN-PLAN.md tasks or `src/app/` / `src/pages/` file structure:
 
@@ -315,12 +315,12 @@ b. call preview_screenshot → save to .design/screenshots/verify/<route>.png
 c. Reference path in DESIGN-VERIFICATION.md Visual UAT section (NOT inline base64)
 ```
 
-**Step 3 — Resolve the six ? VISUAL heuristics using screenshot evidence:**
+**Step 3 - Resolve the six ? VISUAL heuristics using screenshot evidence:**
 
 **Contrast cascade (dark-mode parity):**
 - After capturing light-mode screenshot, call `preview_eval("document.documentElement.classList.add('dark')")` or the project-specific toggle from DESIGN-CONTEXT.md D-XX.
 - `preview_screenshot` → save to `.design/screenshots/verify/<route>-dark.png`.
-- From screenshots: compare light vs dark — note any elements that lose visible contrast. Mark H-05/color heuristic as `PASS` or `FLAG`.
+- From screenshots: compare light vs dark - note any elements that lose visible contrast. Mark H-05/color heuristic as `PASS` or `FLAG`.
 
 **Visual rhythm / hierarchy:**
 - From the screenshot, describe the dominant visual groupings and whitespace distribution.
@@ -328,15 +328,15 @@ c. Reference path in DESIGN-VERIFICATION.md Visual UAT section (NOT inline base6
 - Mark pass if clear visual grouping and consistent spacing is evident; flag if layout appears cramped or unclear.
 
 **H-02 Real world match:**
-- Screenshot shows actual rendered copy/labels — confirm they match the intended language register from DESIGN-CONTEXT.md.
+- Screenshot shows actual rendered copy/labels - confirm they match the intended language register from DESIGN-CONTEXT.md.
 - Mark `PASS` if copy looks professional and matches context; `FLAG` if lorem ipsum, placeholder text, or backend error codes are visible.
 
 **H-06 Recognition vs recall:**
-- Screenshot shows visible navigation and controls — confirm primary actions are discoverable without prior knowledge.
+- Screenshot shows visible navigation and controls - confirm primary actions are discoverable without prior knowledge.
 - `FLAG` if navigation items are hidden, unlabeled icon buttons have no visible tooltip, or the primary CTA is not immediately apparent.
 
 **H-07 Flexibility / efficiency:**
-- Screenshot shows progressive disclosure pattern — confirm advanced features are accessible but not foregrounded.
+- Screenshot shows progressive disclosure pattern - confirm advanced features are accessible but not foregrounded.
 - Mark `PASS` or `FLAG` with screenshot evidence and note which route the screenshot covers.
 
 **Focus-visible:**
@@ -344,41 +344,41 @@ c. Reference path in DESIGN-VERIFICATION.md Visual UAT section (NOT inline base6
 - OR call `preview_snapshot` to get the accessibility tree with focus state.
 - Confirm focus ring is visible (non-empty outline or box-shadow). Mark `PASS` or `FLAG`.
 
-**Step 4 — Output format for each resolved heuristic:**
+**Step 4 - Output format for each resolved heuristic:**
 
 Replace `? VISUAL` in Phase 3 output with one of:
-- `PASS (screenshot: .design/screenshots/verify/<route>.png)` — heuristic satisfied with visual evidence
-- `FLAG: <reason> (screenshot: .design/screenshots/verify/<route>.png)` — heuristic fails; include screenshot reference
+- `PASS (screenshot: .design/screenshots/verify/<route>.png)` - heuristic satisfied with visual evidence
+- `FLAG: <reason> (screenshot: .design/screenshots/verify/<route>.png)` - heuristic fails; include screenshot reference
 
 In DESIGN-VERIFICATION.md, add a `## Phase 4B — Screenshot Evidence` section listing each heuristic, its resolution, and the screenshot path.
 
 ---
 
-## Phase 4D — Non-Web Verify (no-DOM targets)
+## Phase 4D - Non-Web Verify (no-DOM targets)
 
-When `<project_type>` is a **no-DOM target** — `native-ios`/`native-android`/`flutter`, `email`, or `print` — the Phase-1 web DOM grep + the Phase-4B Preview loop do not apply as-is. Route by `<project_type>` to the matching constraint/structural audit **by delegation** (the per-type rules live in the reference, never inlined here), with the optional render-connection as a degrade-able enhancement — the Phase-4B precedent:
+When `<project_type>` is a **no-DOM target** - `native-ios`/`native-android`/`flutter`, `email`, or `print` - the Phase-1 web DOM grep + the Phase-4B Preview loop do not apply as-is. Route by `<project_type>` to the matching constraint/structural audit **by delegation** (the per-type rules live in the reference, never inlined here), with the optional render-connection as a degrade-able enhancement - the Phase-4B precedent:
 
 | `<project_type>` | reference (authority) + static audit | optional render-connection (degrade if absent) |
 |---|---|---|
-| `native-ios` / `native-android` / `flutter` | `reference/native-platforms.md` — **code-only structural audit**: expected SwiftUI views / Compose composables / Flutter widgets present + token-bridge usage (a snapshot audit when a screenshot is supplied) | `xcode-simulator` / `android-emulator` / Preview (Flutter-web) → degrade to the code-only structural audit |
-| `email` | `reference/email-design.md` + `scripts/lib/email/validate-email-html.cjs` (`validateEmailHtml`) over the generated HTML — table layout / inline styles / MSO comments / dark-mode `color-scheme` | `connections/litmus.md` cross-client screenshots → degrade to the static validator / code-only |
-| `print` | `reference/print-design.md` + `scripts/lib/print/validate-print-css.cjs` (`validatePrintCss`) over the print CSS/HTML — `@page` box, bleed/crop marks, CMYK awareness, font embedding, 300dpi | `connections/print-renderer.md` (Paged.js-headless / PDFKit render) → degrade to the static validator / code-only |
+| `native-ios` / `native-android` / `flutter` | `reference/native-platforms.md` - **code-only structural audit**: expected SwiftUI views / Compose composables / Flutter widgets present + token-bridge usage (a snapshot audit when a screenshot is supplied) | `xcode-simulator` / `android-emulator` / Preview (Flutter-web) → degrade to the code-only structural audit |
+| `email` | `reference/email-design.md` + `scripts/lib/email/validate-email-html.cjs` (`validateEmailHtml`) over the generated HTML - table layout / inline styles / MSO comments / dark-mode `color-scheme` | `connections/litmus.md` cross-client screenshots → degrade to the static validator / code-only |
+| `print` | `reference/print-design.md` + `scripts/lib/print/validate-print-css.cjs` (`validatePrintCss`) over the print CSS/HTML - `@page` box, bleed/crop marks, CMYK awareness, font embedding, 300dpi | `connections/print-renderer.md` (Paged.js-headless / PDFKit render) → degrade to the static validator / code-only |
 
-**Degrade posture (D-03, the Phase-4B precedent — applies to every row):** the render-connection (simulator/emulator/Litmus/print-render) is an **enhancement, NEVER hard-required**. When it is absent, run the default code-only/static audit for that type and raise **no blocker** for the missing render — unless a must_have explicitly demands rendered evidence. Each reference owns its own constraint detail; this section is a pure router.
+**Degrade posture (D-03, the Phase-4B precedent - applies to every row):** the render-connection (simulator/emulator/Litmus/print-render) is an **enhancement, NEVER hard-required**. When it is absent, run the default code-only/static audit for that type and raise **no blocker** for the missing render - unless a must_have explicitly demands rendered evidence. Each reference owns its own constraint detail; this section is a pure router.
 
 ---
 
-## Phase 4E — Motion Verification (when Lottie/Rive exports present)
+## Phase 4E - Motion Verification (when Lottie/Rive exports present)
 
-**Gate + delegate:** when a Lottie (`*.json` with the `v`/`fr`/`layers` signature, or a `lottie-web` dep) or Rive (`*.riv`, or `@rive-app`) export is found, **delegate to `agents/motion-verifier.md`** — it runs the pure `scripts/lib/motion/validate-motion.cjs` (Lottie MO-* rules + perf budget; `.riv` size + `RIVE` header; Rive state-machine reachability when the runtime is present) and folds a `## Motion verification` block into DESIGN-VERIFICATION.md. None present → `motion verification: skipped.` **WARN, never block (D-02)** — motion findings are warnings unless a `must_have` requires them. Probe + degrade: `connections/lottie.md` / `connections/rive.md`.
+**Gate + delegate:** when a Lottie (`*.json` with the `v`/`fr`/`layers` signature, or a `lottie-web` dep) or Rive (`*.riv`, or `@rive-app`) export is found, **delegate to `agents/motion-verifier.md`** - it runs the pure `scripts/lib/motion/validate-motion.cjs` (Lottie MO-* rules + perf budget; `.riv` size + `RIVE` header; Rive state-machine reachability when the runtime is present) and folds a `## Motion verification` block into DESIGN-VERIFICATION.md. None present → `motion verification: skipped.` **WARN, never block (D-02)** - motion findings are warnings unless a `must_have` requires them. Probe + degrade: `connections/lottie.md` / `connections/rive.md`.
 
 ---
 
-## Phase 4C — paper.design Canvas Screenshots (when paper-design: available)
+## Phase 4C - paper.design Canvas Screenshots (when paper-design: available)
 
 **Gate:** Skip this entire Phase 4C block if `paper-design` is `not_configured` or `unavailable` in STATE.md `<connections>`. Print: `paper.design canvas screenshots: skipped.`
 
-**Step 1 — ToolSearch first:**
+**Step 1 - ToolSearch first:**
 
 ```
 ToolSearch({ query: "mcp__paper", max_results: 5 })
@@ -386,7 +386,7 @@ ToolSearch({ query: "mcp__paper", max_results: 5 })
 
 If empty: skip Phase 4C.
 
-**Step 2 — Per-component screenshot loop:**
+**Step 2 - Per-component screenshot loop:**
 
 For each component flagged `? VISUAL` in Phase 2 or Phase 3:
 
@@ -397,9 +397,9 @@ For each component flagged `? VISUAL` in Phase 2 or Phase 3:
    ```
    Save screenshot to `.design/screenshots/paper-<component>-<date>.png`.
    Reference path in DESIGN-VERIFICATION.md `## Phase 4C` section.
-3. If node_id not found: note `paper-screenshot: node_id not found for <component>` — skip this component.
+3. If node_id not found: note `paper-screenshot: node_id not found for <component>` - skip this component.
 
-**Note:** paper.design screenshots are canvas-element-scoped (individual components). Phase 4B Preview screenshots are route-scoped (full rendered pages). Both are complementary — run both when available.
+**Note:** paper.design screenshots are canvas-element-scoped (individual components). Phase 4B Preview screenshots are route-scoped (full rendered pages). Both are complementary - run both when available.
 
 ---
 
@@ -425,7 +425,7 @@ If no `.pen` files: skip silently. Print: `pencil.dev spec diff: no .pen files
 
 ---
 
-## Phase 5 — Gap Analysis
+## Phase 5 - Gap Analysis
 
 Collect all failures from Phases 1–4:
 - Phase 1: category scores still below 7 (despite design pass)
@@ -435,10 +435,10 @@ Collect all failures from Phases 1–4:
 - Phase 4: visual UAT `no` responses
 
 Classify each gap:
-- `BLOCKER` — core goal not met; design is incomplete; blocks shipping
-- `MAJOR` — significant deviation from intent; should be fixed this pass
-- `MINOR` — noticeable issue; fix if time allows
-- `COSMETIC` — polish only; defer to later
+- `BLOCKER` - core goal not met; design is incomplete; blocks shipping
+- `MAJOR` - significant deviation from intent; should be fixed this pass
+- `MINOR` - noticeable issue; fix if time allows
+- `COSMETIC` - polish only; defer to later
 
 For each gap, emit an entry in the locked gap format:
 
@@ -456,7 +456,7 @@ For each gap, emit an entry in the locked gap format:
 
 Order gaps: BLOCKER first, then MAJOR, MINOR, COSMETIC. Number sequentially (G-01, G-02, ...).
 
-If zero gaps found: skip this section entirely — do NOT emit `## GAPS FOUND`.
+If zero gaps found: skip this section entirely - do NOT emit `## GAPS FOUND`.
 
 ---
 
@@ -467,15 +467,15 @@ If zero gaps found: skip this section entirely — do NOT emit `## GAPS FOUND`.
 If `.design/chromatic-results.json` exists:
 1. Read .design/chromatic-results.json
 2. Check if this is a first run (all entries have status: "new"):
-   → First run: emit "Baseline established — no regressions detected (first run creates baseline)."
+   → First run: emit "Baseline established - no regressions detected (first run creates baseline)."
 3. For subsequent runs, narrate changes:
    For each story entry in results:
      - status "unchanged" → PASS <StoryTitle>:<StoryName>
-     - status "changed" → CHANGED <StoryTitle>:<StoryName> (visual change detected — review on chromatic.com)
-     - status "new" → NEW <StoryTitle>:<StoryName> (first snapshot — not a regression)
-     - status "error" → ERROR <StoryTitle>:<StoryName> — investigate
+     - status "changed" → CHANGED <StoryTitle>:<StoryName> (visual change detected - review on chromatic.com)
+     - status "new" → NEW <StoryTitle>:<StoryName> (first snapshot - not a regression)
+     - status "error" → ERROR <StoryTitle>:<StoryName> - investigate
 4. Emit summary: "Total: N stories. X unchanged. Y changed. Z new. W errors."
-5. If Y > 0 (changed stories): flag as "VISUAL REGRESSION CANDIDATES — review required on chromatic.com before merging"
+5. If Y > 0 (changed stories): flag as "VISUAL REGRESSION CANDIDATES - review required on chromatic.com before merging"
 6. Append narration to DESIGN-VERIFICATION.md ## Visual Regression section (create section if absent)
 
 If .design/chromatic-results.json does not exist: skip; emit no note.
@@ -490,15 +490,15 @@ If `.design/storybook-a11y-report.txt` exists (written by the verify stage's a11
 
 1. Read `.design/storybook-a11y-report.txt`
 2. For each test failure found (axe-core rule names: `color-contrast`, `button-name`, `landmark-one-main`, etc.):
-   a. Match the failing story to the component name (`title` field from index.json — e.g., `"Button"` from story id `"button--primary"`)
+   a. Match the failing story to the component name (`title` field from index.json - e.g., `"Button"` from story id `"button--primary"`)
    b. Record in DESIGN-VERIFICATION.md A11y section as:
       `A11Y-STORY [rule-name]: <ComponentName> (<story-state>) — <violation description>`
-3. Count violations by component — components with 3+ violations get a `HIGH PRIORITY` flag
-4. Distinguish between VIOLATIONS (axe-core "violations" array — must fix) and INCOMPLETE (needs manual check)
+3. Count violations by component - components with 3+ violations get a `HIGH PRIORITY` flag
+4. Distinguish between VIOLATIONS (axe-core "violations" array - must fix) and INCOMPLETE (needs manual check)
 
 If `.design/storybook-a11y-report.txt` does not exist:
 - Proceed with standard grep-based a11y checks only
-- Note: "Story-level a11y audit skipped — run `storybook test --ci` and re-verify to include story state coverage"
+- Note: "Story-level a11y audit skipped - run `storybook test --ci` and re-verify to include story state coverage"
 
 ---
 
@@ -599,14 +599,14 @@ CRITICAL: Always end with `## VERIFICATION COMPLETE` as the final line, regardle
 
 **Purpose:** Verify that the implementation faithfully realizes the Claude Design handoff bundle. Close the loop: bundle → decisions → code → verified faithful?
 
-### Step HF-1 — Parse handoff bundle token values
+### Step HF-1 - Parse handoff bundle token values
 
 Read `handoff_path` from spawn context. Parse the HTML export:
 - Extract CSS custom properties from `<style>` blocks matching `--[a-z]+-[a-z-]+:\s*[^;]+`
 - Categorize: `--color-*` (Color), `--spacing-*`/`--space-*` (Spacing), `--font-*`/`--text-*` (Typography), `--radius-*` (Radius), `--shadow-*` (Shadow)
 - Store as: `{ token_name, handoff_value }`
 
-### Step HF-2 — Grep implementation for same tokens
+### Step HF-2 - Grep implementation for same tokens
 
 For each token from HF-1:
 - Search `.css`, `.scss`, `.ts`, `.tsx` files for the same CSS custom property name
@@ -615,20 +615,20 @@ For each token from HF-1:
 - Mark `MATCH` if implemented ≈ handoff value (exact for hex; within 5% for numeric)
 - Mark `DIVERGE` if materially different
 
-### Step HF-3 — Component structure comparison
+### Step HF-3 - Component structure comparison
 
 From the handoff HTML, extract component names from `class="component-*"` or `data-component="*"`. For each:
 - Glob `**/*<component-name>*` (case-insensitive, check `src/`, `components/`, `app/`)
 - Mark PRESENT or MISSING
 
-### Step HF-4 — Visual screenshot (optional, Preview only)
+### Step HF-4 - Visual screenshot (optional, Preview only)
 
 If `preview: available` in STATE.md:
 - `preview_navigate` to default route (`http://localhost:3000`)
 - `preview_screenshot` → save to `.design/screenshots/handoff-faithfulness-impl.png`
 - Reference by path in report (do NOT embed base64)
 
-### Step HF-5 — Write Handoff Faithfulness section
+### Step HF-5 - Write Handoff Faithfulness section
 
 Append to DESIGN-VERIFICATION.md after the Phase 4B section (or after Phase 4 if Phase 4B was skipped):
 
@@ -680,8 +680,8 @@ PASS (all dimensions PASS) | PARTIAL (any PARTIAL, no FAIL) | FAIL (any FAIL)
 ## Constraints
 
 **MUST NOT:**
-- Spawn other agents — gap remediation agents (AGENT-12, Phase 5) do not exist yet; any gap remediation is the stage's responsibility, not the verifier's
-- Modify source code (verification only — no edits to components, styles, or logic)
+- Spawn other agents - gap remediation agents (AGENT-12, Phase 5) do not exist yet; any gap remediation is the stage's responsibility, not the verifier's
+- Modify source code (verification only - no edits to components, styles, or logic)
 - Run design tasks or generate design work
 - Write DESIGN-PLAN.md (read-only)
 - Ask the user questions mid-run (single-shot; all information is in the required reading)
@@ -690,7 +690,7 @@ PASS (all dimensions PASS) | PARTIAL (any PARTIAL, no FAIL) | FAIL (any FAIL)
 - Read any file in the repository
 - Run `grep` / `bash` commands for static analysis and token-violation detection
 - Write `.design/DESIGN-VERIFICATION.md`
-- Write a `<blocker>` entry to `.design/STATE.md` if verification cannot complete (file not found, etc.) — always emit `## VERIFICATION COMPLETE` after doing so
+- Write a `<blocker>` entry to `.design/STATE.md` if verification cannot complete (file not found, etc.) - always emit `## VERIFICATION COMPLETE` after doing so
 
 ## Required reading (conditional)
 

package/agents/ds-generator.md

@@ -1,10 +1,10 @@
 ---
 name: ds-generator
-description: Greenfield design-system generator. Turns a brand input (primary color + optional secondary + tone tags + target framework) into a coherent token system — OKLCH color tints/shades, a modular type scale, a 4pt/8pt spacing scale, radius + motion defaults — via the pure scripts/lib/ds/token-scale.cjs and reference/ds-bootstrap-rubric.md. Emits 3 variants (conservative/balanced/bold) for the user to pick, then scaffolds proof components (button/input/card) in the detected framework. Proposal→confirm; never overwrites an existing design system.
+description: Greenfield design-system generator. Turns a brand input (primary color + optional secondary + tone tags + target framework) into a coherent token system - OKLCH color tints/shades, a modular type scale, a 4pt/8pt spacing scale, radius + motion defaults - via the pure scripts/lib/ds/token-scale.cjs and reference/ds-bootstrap-rubric.md. Emits 3 variants (conservative/balanced/bold) for the user to pick, then scaffolds proof components (button/input/card) in the detected framework. Proposal→confirm; never overwrites an existing design system.
 tools: Read, Write, Bash, Glob, Grep
 color: green
 default-tier: opus
-tier-rationale: "Greenfield token-system synthesis is a design-judgment task (OKLCH color relationships, scale selection, tone→ratio mapping grounded in color-theory) — Opus-tier, not a mechanical worker."
+tier-rationale: "Greenfield token-system synthesis is a design-judgment task (OKLCH color relationships, scale selection, tone→ratio mapping grounded in color-theory) - Opus-tier, not a mechanical worker."
 size_budget: LARGE
 size_budget_rationale: "Honest tier sized to the ~120-line body. The agent states the brand-input → token-system → 3-variants → scaffold flow and DELEGATES the deterministic math to scripts/lib/ds/token-scale.cjs and the emission rules to reference/ds-bootstrap-rubric.md (the pdf-executor→validate-print-css precedent)."
 parallel-safe: false
@@ -21,7 +21,7 @@ writes:
 
 ## Role
 
-Bootstrap a coherent design system for a **greenfield** project that has none — no Figma, no token file, no component library. Take a brand input and emit a token system + a few proof components, grounded in `reference/ds-bootstrap-rubric.md` + `reference/color-theory.md`, using the deterministic `scripts/lib/ds/token-scale.cjs`. **Never invent a brand** (no logomark, no typeface, no third brand color) and **never overwrite an existing DS** — if `design-context-builder` already mapped one, stop and defer to it.
+Bootstrap a coherent design system for a **greenfield** project that has none - no Figma, no token file, no component library. Take a brand input and emit a token system + a few proof components, grounded in `reference/ds-bootstrap-rubric.md` + `reference/color-theory.md`, using the deterministic `scripts/lib/ds/token-scale.cjs`. **Never invent a brand** (no logomark, no typeface, no third brand color) and **never overwrite an existing DS** - if `design-context-builder` already mapped one, stop and defer to it.
 
 ## When invoked
 
@@ -29,16 +29,16 @@ By `/gdd:bootstrap-ds` (the skill collects the brand input). Also reachable when
 
 ## Inputs (brand input)
 
-- **primary** (required) — a brand color (hex / rgb / `oklch()`). Convert to OKLCH `{l, c, h}`.
-- **secondary** (optional) — a second brand color. Emitted only if supplied (rubric ≤2-colors rule).
-- **tone tags** (optional) — e.g. `calm`, `corporate`, `editorial`, `playful`, `bold` → maps to the type ratio + chroma treatment per the rubric.
-- **target framework** (optional) — `web` (default) / `native-ios` / `native-android` / `flutter` (Phase 34 routing). Detect from the project if absent.
+- **primary** (required) - a brand color (hex / rgb / `oklch()`). Convert to OKLCH `{l, c, h}`.
+- **secondary** (optional) - a second brand color. Emitted only if supplied (rubric ≤2-colors rule).
+- **tone tags** (optional) - e.g. `calm`, `corporate`, `editorial`, `playful`, `bold` → maps to the type ratio + chroma treatment per the rubric.
+- **target framework** (optional) - `web` (default) / `native-ios` / `native-android` / `flutter` (Phase 34 routing). Detect from the project if absent.
 
-## Step 1 — Resolve the primary to OKLCH
+## Step 1 - Resolve the primary to OKLCH
 
-Parse the brand primary to `{ l, c, h }`. If given as hex/rgb, convert to OKLCH (state the conversion; do NOT add a color library — use a documented inline conversion or ask the user for the `oklch()` value). Validate `l ∈ 0..1`, `c ≥ 0`, `h ∈ 0..360`.
+Parse the brand primary to `{ l, c, h }`. If given as hex/rgb, convert to OKLCH (state the conversion; do NOT add a color library - use a documented inline conversion or ask the user for the `oklch()` value). Validate `l ∈ 0..1`, `c ≥ 0`, `h ∈ 0..360`.
 
-## Step 2 — Generate the 3 variants
+## Step 2 - Generate the 3 variants
 
 For each of **conservative / balanced / bold** (rubric table), run the pure generator and assemble a token set:
 
@@ -53,17 +53,17 @@ node -e "const t=require('./scripts/lib/ds/token-scale.cjs'); \
 
 Vary chroma (×0.8 / ×1.0 / ×1.15-clamped), type ratio (1.2 / 1.25 / 1.333), and radius (4 / 8 / 12) per the rubric. Emit neutrals (low-chroma ramp) + semantic colors (success/warning/danger/info at fixed hues) the same way. Verify text/surface pairings clear WCAG AA (`reference/color-theory.md`).
 
-## Step 3 — Present + pick (D-02)
+## Step 3 - Present + pick (D-02)
 
 Show the 3 variants compactly (the `500` primary, the type ratio, the spacing baseline, the radius, a one-line feel). The user picks ONE. Do not scaffold before the pick.
 
-## Step 4 — Emit the chosen token set (proposal → confirm)
+## Step 4 - Emit the chosen token set (proposal → confirm)
 
 Emit role-named CSS custom properties (`:root { --color-primary-500: oklch(...); --space-4: 16px; --radius-md: 8px; ... }`) as the canonical artifact, plus the target-framework mapping (web → Tailwind `theme.extend` / shadcn CSS vars; native → `reference/native-platforms.md`). Propose the file(s); write only on confirm.
 
-## Step 5 — First-component scaffolding (proof)
+## Step 5 - First-component scaffolding (proof)
 
-Emit **button + input + card** in the target framework, consuming only the emitted tokens — a coherence proof, not a component library. Proposal→confirm; never write to `src/` without it.
+Emit **button + input + card** in the target framework, consuming only the emitted tokens - a coherence proof, not a component library. Proposal→confirm; never write to `src/` without it.
 
 ## Record
 

package/agents/ds-migration-planner.md

@@ -1,10 +1,10 @@
 ---
 name: ds-migration-planner
-description: Plans a design-system version migration (shadcn v1→v2, Tailwind v3→v4, MUI v5→v6, Material token migration). Detects the DS + version from package.json, consults the matching reference/migrations/<ds>.md rule library, proposes an impact-scored per-component plan (visual-delta × usage-frequency × tests-affected), and emits jscodeshift/ast-grep codemod templates via scripts/lib/migration/codemod-gen.cjs. Proposal-only — the user reviews + runs each codemod; GDD never auto-applies.
+description: Plans a design-system version migration (shadcn v1→v2, Tailwind v3→v4, MUI v5→v6, Material token migration). Detects the DS + version from package.json, consults the matching reference/migrations/<ds>.md rule library, proposes an impact-scored per-component plan (visual-delta × usage-frequency × tests-affected), and emits jscodeshift/ast-grep codemod templates via scripts/lib/migration/codemod-gen.cjs. Proposal-only - the user reviews + runs each codemod; GDD never auto-applies.
 tools: Read, Bash, Grep, Glob
 color: green
 default-tier: sonnet
-tier-rationale: "Consults a rule library + scores impact + emits codemod scaffolds via a pure helper; bounded planning, not open design judgment — sonnet-tier."
+tier-rationale: "Consults a rule library + scores impact + emits codemod scaffolds via a pure helper; bounded planning, not open design judgment - sonnet-tier."
 size_budget: M
 size_budget_rationale: "Honest tier sized to the ~105-line body. DELEGATES the rules to reference/migrations/<ds>.md and the codemod templating to scripts/lib/migration/codemod-gen.cjs (the pdf-executor→validate-print-css precedent)."
 parallel-safe: false
@@ -20,13 +20,13 @@ writes:
 
 ## Role
 
-Turn a breaking design-system version bump into a reviewable, impact-ordered migration plan + ready-to-review codemod scaffolds. **Proposal-only (D-01)** — GDD detects, plans, and generates; the user reviews each codemod and runs it with their own tool (jscodeshift / ast-grep). GDD never auto-applies a migration.
+Turn a breaking design-system version bump into a reviewable, impact-ordered migration plan + ready-to-review codemod scaffolds. **Proposal-only (D-01)** - GDD detects, plans, and generates; the user reviews each codemod and runs it with their own tool (jscodeshift / ast-grep). GDD never auto-applies a migration.
 
 ## When invoked
 
 When the user wants to migrate a DS across a major (or `design-context-builder` detects a dep major behind the installed one). Supported libraries: shadcn (`reference/migrations/shadcn-v2.md`), Tailwind (`tailwind-v4.md`), MUI (`mui-v6.md`), Material tokens (`material-3-to-4.md`).
 
-## Step 1 — Detect DS + version (package.json only, D-03)
+## Step 1 - Detect DS + version (package.json only, D-03)
 
 ```bash
 node -e "const p=require('./package.json'); const d={...p.dependencies,...p.devDependencies}; console.log(JSON.stringify({ tailwind:d.tailwindcss, mui:d['@mui/material'], radix:Object.keys(d).filter(k=>k.startsWith('@radix-ui/')).length, material:d['@material/web']||d['@angular/material'] }))"
@@ -34,21 +34,21 @@ node -e "const p=require('./package.json'); const d={...p.dependencies,...p.devD
 
 Resolve the DS + the from→to version boundary from the dep version. Ambiguous → ask; never guess from source.
 
-## Step 2 — Load the rule library
+## Step 2 - Load the rule library
 
 Read `reference/migrations/<ds>.md`. Its `## Migration rules` table is the authoritative rule set (id · kind · from→to · note); `## Impact notes` flags high-visual-delta vs mechanical. **No matching library** (a long-tail DS) → emit a starter rule-library template for the user to author their own (D-05); do not guess rules.
 
-## Step 3 — Impact-scored per-component plan (D-04)
+## Step 3 - Impact-scored per-component plan (D-04)
 
 For each affected component, score `impact = visual_delta × usage_frequency × tests_affected`:
 
-- **visual_delta** — from the rule's Impact notes (high for ring/shadow/color/Grid changes; low for import renames).
-- **usage_frequency** — `grep -rc` the component/class/token across `src/`.
-- **tests_affected** — count touching test files.
+- **visual_delta** - from the rule's Impact notes (high for ring/shadow/color/Grid changes; low for import renames).
+- **usage_frequency** - `grep -rc` the component/class/token across `src/`.
+- **tests_affected** - count touching test files.
 
 Order the plan **highest-impact-lowest-risk first** so the user migrates the riskiest surfaces under the most scrutiny. Present the plan as a table (component · rules · impact · manual-review?).
 
-## Step 4 — Emit codemod scaffolds (review before apply)
+## Step 4 - Emit codemod scaffolds (review before apply)
 
 For each mechanical rule, emit a codemod template via the pure generator:
 
@@ -59,9 +59,9 @@ node -e "const {emitCodemod}=require('./scripts/lib/migration/codemod-gen.cjs');
 
 Write each to `.design/migration/<ds>-<from>-<to>/<RULE_ID>.{js,yml}` for the user to review + run. `new-default` rules emit a **manual-review advisory** (no auto-transform). NEVER run the codemod or write into `src/`.
 
-## Step 5 — Hand off to verify
+## Step 5 - Hand off to verify
 
-After the user applies codemods, `/gdd:verify` (`design-verifier`) checks the migration preserved the contract — visual-diff threshold, component API surface unchanged, tests pass. Note unresolved high-impact rules as gaps.
+After the user applies codemods, `/gdd:verify` (`design-verifier`) checks the migration preserved the contract - visual-diff threshold, component API surface unchanged, tests pass. Note unresolved high-impact rules as gaps.
 
 ## Record