@hegemonart/get-design-done 1.57.1 → 1.57.3

package/agents/design-verifier.md

@@ -20,10 +20,14 @@ 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 stages - 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.
 
+## Output Contract
+
+Emit a single top-of-response fenced ```json block conforming to `reference/output-contracts/verifier-decision.schema.json` BEFORE any prose, then continue with the existing Stage 1..5 verification body. `parseVerifierDecision` (scripts/lib/parse-contract.cjs) consumes the envelope; humans read the prose.
+
 ## 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:
@@ -52,17 +56,17 @@ The stage embeds these fields in its prompt:
 
 ---
 
-## Phase 1 - Re-Audit + Category Scoring
+## Stage 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
+### Stage 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
 them here to keep the patterns in a single source of truth.
 
-Key pattern categories consumed by this phase:
+Key pattern categories consumed by this stage:
 - Hardcoded color values (hex, rgb, named colors)
 - Off-grid spacing values
 - Typography scale violations
@@ -136,7 +140,7 @@ Score = (Accessibility × 0.25) + (Visual Hierarchy × 0.20) + (Typography × 0.
       + (Color × 0.15) + (Layout × 0.10) + (Anti-Patterns × 0.10) + (Motion × 0.05)
 ```
 
-Note: Micro-Polish is a qualitative supplement (drawn from DESIGN-AUDIT.md Pillar 7) and is reported alongside the weighted total but does not alter the 0–100 score. If Pillar 7 score is 1 or 2 and violations are systemic, flag as a MINOR or MAJOR gap in Phase 5.
+Note: Micro-Polish is a qualitative supplement (drawn from DESIGN-AUDIT.md Pillar 7) and is reported alongside the weighted total but does not alter the 0–100 score. If Pillar 7 score is 1 or 2 and violations are systemic, flag as a MINOR or MAJOR gap in Stage 5.
 
 **Delta vs baseline:**
 ```
@@ -166,9 +170,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 (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:
 
 ```txt
 react-intl:  <FormattedMessage\s+id="[^"]+"
@@ -183,9 +187,9 @@ Allow-list seed (skip): `console\.(log|error|warn|info|debug)`, dev-only `/* */`
 
 ---
 
-## Phase 2 - Must-Have Check
+## Stage 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** - 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 the `ds-migration-planner` agent), 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 |
 |---|---|
@@ -199,7 +203,7 @@ Read `.design/STATE.md` `<must_haves>`. Also read must-haves from DESIGN-PLAN.md
 Mark each:
 - `✓ PASS` - verified and confirmed
 - `✗ FAIL` - verified and not met
-- `? VISUAL` - cannot verify from code alone - queued for Phase 4 UAT
+- `? VISUAL` - cannot verify from code alone - queued for Stage 4 UAT
 
 Output report:
 ```
@@ -216,7 +220,7 @@ If `re_verify=true`: re-check all previously-failed must-haves first, then run f
 
 ---
 
-## Phase 3 - NNG Heuristic Scoring
+## Stage 3 - NNG Heuristic Scoring
 
 Read `reference/heuristics.md`. Score each of the 10 heuristics 0–4.
 
@@ -259,7 +263,7 @@ Total: [N]/40 = [N×2.5]/100  [grade interpretation]
 
 ---
 
-## Phase 4 - Visual UAT
+## Stage 4 - Visual UAT
 
 For each `? VISUAL` must-have plus key brand/tone goals from DESIGN-CONTEXT.md, present checks in the format below.
 
@@ -290,13 +294,13 @@ 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 Stage 5 gap analysis.
 
 ---
 
-## Phase 4B - Screenshot Evidence (when preview: available)
+## Stage 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.`
+**Gate:** Skip this entire Stage 4B block if `preview` is `not_loaded`, `not_configured`, `permission_denied`, `unreachable`, or `unavailable` in STATE.md `<connections>`. The `? VISUAL` flags from Stage 3 remain as-is; mark them `[SKIPPED — browser not available]` and proceed to Stage 5. When skipping due to `permission_denied`, also log: `Preview MCP tools missing from agent allowlist — contact the pipeline maintainer.`
 
 **Step 1 - ToolSearch first:**
 
@@ -304,7 +308,7 @@ Record each response. For `no` responses, capture the user's issue description v
 ToolSearch({ query: "Claude_Preview", max_results: 10 })
 ```
 
-If empty result: mark all Phase 4B checks `[SKIPPED — browser not available]` and proceed to Phase 5.
+If empty result: mark all Stage 4B checks `[SKIPPED — browser not available]` and proceed to Stage 5.
 
 **Step 2 - Per-route screenshot loop:**
 
@@ -313,12 +317,12 @@ For each route identified from DESIGN-PLAN.md tasks or `src/app/` / `src/pages/`
 ```
 a. call preview_navigate to route URL (e.g., http://localhost:3000/<route>)
    → If error (connection refused, 404): update STATE.md preview: unavailable
-     mark all remaining Phase 4B checks [SKIPPED — no running server]; proceed to Phase 5
+     mark all remaining Stage 4B checks [SKIPPED — no running server]; proceed to Stage 5
 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.
@@ -349,17 +353,17 @@ c. Reference path in DESIGN-VERIFICATION.md Visual UAT section (NOT inline base6
 
 **Step 4 - Output format for each resolved heuristic:**
 
-Replace `? VISUAL` in Phase 3 output with one of:
+Replace `? VISUAL` in Stage 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
 
-In DESIGN-VERIFICATION.md, add a `## Phase 4B — Screenshot Evidence` section listing each heuristic, its resolution, and the screenshot path.
+In DESIGN-VERIFICATION.md, add a `## Stage 4B — Screenshot Evidence` section listing each heuristic, its resolution, and the screenshot path.
 
 ---
 
-## Phase 4D - Non-Web Verify (no-DOM targets)
+## Stage 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 Stage-1 web DOM grep + the Stage-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 Stage-4B precedent:
 
 | `<project_type>` | reference (authority) + static audit | optional render-connection (degrade if absent) |
 |---|---|---|
@@ -367,19 +371,19 @@ When `<project_type>` is a **no-DOM target** - `native-ios`/`native-android`/`fl
 | `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 (applies to every row, following the Stage-4B precedent):** 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)
+## Stage 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** - 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)
+## Stage 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.`
+**Gate:** Skip this entire Stage 4C block if `paper-design` is `not_configured` or `unavailable` in STATE.md `<connections>`. Print: `paper.design canvas screenshots: skipped.`
 
 **Step 1 - ToolSearch first:**
 
@@ -387,11 +391,11 @@ When `<project_type>` is a **no-DOM target** - `native-ios`/`native-android`/`fl
 ToolSearch({ query: "mcp__paper", max_results: 5 })
 ```
 
-If empty: skip Phase 4C.
+If empty: skip Stage 4C.
 
 **Step 2 - Per-component screenshot loop:**
 
-For each component flagged `? VISUAL` in Phase 2 or Phase 3:
+For each component flagged `? VISUAL` in Stage 2 or Stage 3:
 
 1. Look up the canvas node_id from DESIGN-CONTEXT.md `<canvas_sources>` block (written by design-context-builder Step 0A).
 2. If node_id found:
@@ -399,10 +403,10 @@ For each component flagged `? VISUAL` in Phase 2 or Phase 3:
    mcp__paper-design__get_screenshot(node_id: "<id>")
    ```
    Save screenshot to `.design/screenshots/paper-<component>-<date>.png`.
-   Reference path in DESIGN-VERIFICATION.md `## Phase 4C` section.
+   Reference path in DESIGN-VERIFICATION.md `## Stage 4C` section.
 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). Stage 4B Preview screenshots are route-scoped (full rendered pages). Both are complementary - run both when available.
 
 ---
 
@@ -428,14 +432,14 @@ If no `.pen` files: skip silently. Print: `pencil.dev spec diff: no .pen files
 
 ---
 
-## Phase 5 - Gap Analysis
+## Stage 5 - Gap Analysis
 
-Collect all failures from Phases 1–4:
-- Phase 1: category scores still below 7 (despite design pass)
-- Phase 1 (micro-polish supplement): Pillar 7 score of 1 or 2 with systemic violations → MINOR or MAJOR gap
-- Phase 2: `✗ FAIL` must-haves
-- Phase 3: NNG scores of 0 or 1 on any heuristic
-- Phase 4: visual UAT `no` responses
+Collect all failures from Stages 1–4:
+- Stage 1: category scores still below 7 (despite design pass)
+- Stage 1 (micro-polish supplement): Pillar 7 score of 1 or 2 with systemic violations → MINOR or MAJOR gap
+- Stage 2: `✗ FAIL` must-haves
+- Stage 3: NNG scores of 0 or 1 on any heuristic
+- Stage 4: visual UAT `no` responses
 
 Classify each gap:
 - `BLOCKER` - core goal not met; design is incomplete; blocks shipping
@@ -443,7 +447,7 @@ Classify each gap:
 - `MINOR` - noticeable issue; fix if time allows
 - `COSMETIC` - polish only; defer to later
 
-**Pre-Report Gate (Phase 49, see `reference/reviewer-confidence-gate.md`).** Before emitting each gap, answer the four questions: (a) can you cite `file:line`, (b) can you state the failure mode in one sentence, (c) did you read context beyond the modified file, (d) is the severity defensible? Stamp every gap with a `confidence` field (`0.0-1.0`): `>= 0.8` when all four pass, `0.5-0.8` when evidence is partial, `< 0.5` for an unconfirmed hunch. A BLOCKER or MAJOR requires `confidence >= 0.8` plus a `file:line` citation plus a one-sentence failure mode; below that, lower the severity or move it to `## Tentative`. Confidence is independent of severity. Move every `< 0.5` gap into a `## Tentative` section so it is surfaced but never reaches `design-fixer`.
+**Pre-Report Gate (see `reference/reviewer-confidence-gate.md`).** Before emitting each gap, answer the four questions: (a) can you cite `file:line`, (b) can you state the failure mode in one sentence, (c) did you read context beyond the modified file, (d) is the severity defensible? Stamp every gap with a `confidence` field (`0.0-1.0`): `>= 0.8` when all four pass, `0.5-0.8` when evidence is partial, `< 0.5` for an unconfirmed hunch. A BLOCKER or MAJOR requires `confidence >= 0.8` plus a `file:line` citation plus a one-sentence failure mode; below that, lower the severity or move it to `## Tentative`. Confidence is independent of severity. Move every `< 0.5` gap into a `## Tentative` section so it is surfaced but never reaches `design-fixer`.
 
 For each gap, emit an entry in the locked gap format:
 
@@ -451,7 +455,7 @@ For each gap, emit an entry in the locked gap format:
 ## GAPS FOUND
 
 ### [BLOCKER|MAJOR|MINOR|COSMETIC] G-NN: [title]
-- Phase: [1|2|3|4]
+- Stage: [1|2|3|4]
 - Description: [what is broken]
 - Expected: [what should be true]
 - Actual: [what is true]
@@ -514,7 +518,7 @@ cosmetics: N
 ## Summary
 [2–4 sentences describing the verification result]
 
-## Phase 1 — Category Scoring
+## Stage 1 — Category Scoring
 
 | Category | Baseline | Result | Delta | Weight | Weighted |
 |---|---|---|---|---|---|
@@ -530,14 +534,14 @@ cosmetics: N
 
 Grade: [before] → [after]
 
-## Phase 2 — Must-Have Status
+## Stage 2 — Must-Have Status
 
 | # | Must-Have | Method | Result |
 |---|---|---|---|
 | M-01 | [text] | auto | ✓ PASS |
 | M-02 | [text] | visual | ✗ FAIL |
 
-## Phase 3 — NNG Heuristics
+## Stage 3 — NNG Heuristics
 
 | Heuristic | Score /4 | Notes |
 |---|---|---|
@@ -553,14 +557,14 @@ Grade: [before] → [after]
 | H-10 Help/documentation | [N]/4 | [note] |
 | **Total** | **[N]/40** | **= [N]/100** |
 
-## Phase 4 — Visual UAT
+## Stage 4 — Visual UAT
 
 | Check | Result | Notes |
 |---|---|---|
 | [brand tone check] | ✓ PASS | [response] |
 | [anti-pattern check] | ✗ FAIL | [user description] |
 
-## Phase 5 — Gaps
+## Stage 5 — Gaps
 
 [List of gaps in locked format above — empty section if no gaps]
 ```
@@ -585,7 +589,7 @@ CRITICAL: Always end with `## VERIFICATION COMPLETE` as the final line, regardle
 
 ---
 
-## Handoff Faithfulness Phase (post_handoff mode only)
+## Handoff Faithfulness Stage (post_handoff mode only)
 
 **Activate when:** `post_handoff: true` is in the spawn context AND `handoff_path` is non-empty.
 
@@ -622,7 +626,7 @@ If `preview: available` in STATE.md:
 
 ### 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):
+Append to DESIGN-VERIFICATION.md after the Stage 4B section (or after Stage 4 if Stage 4B was skipped):
 
 ```markdown
 ## Handoff Faithfulness
@@ -672,7 +676,7 @@ 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
+- Spawn other agents - gap remediation agents 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)

package/agents/ds-generator.md

@@ -32,7 +32,7 @@ By `/gdd:bootstrap-ds` (the skill collects the brand input). Also reachable when
 - **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.
+- **target framework** (optional) - `web` (default) / `native-ios` / `native-android` / `flutter`. Detect from the project if absent.
 
 ## Step 1 - Resolve the primary to OKLCH
 
@@ -53,7 +53,7 @@ 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
 
 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.
 

package/agents/ds-migration-planner.md

@@ -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** - 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)
 
 ```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'] }))"
@@ -36,9 +36,9 @@ Resolve the DS + the from→to version boundary from the dep version. Ambiguous
 
 ## 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.
+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; do not guess rules.
 
-## Step 3 - Impact-scored per-component plan (D-04)
+## Step 3 - Impact-scored per-component plan
 
 For each affected component, score `impact = visual_delta × usage_frequency × tests_affected`:
 

package/agents/email-executor.md

@@ -6,7 +6,7 @@ color: magenta
 default-tier: sonnet
 tier-rationale: "Follows an Opus-authored plan; executes email codegen rather than plans it"
 size_budget: M
-size_budget_rationale: "Honest tier sized to the actual ~148-line body (M cap 300), NOT inflated to the design-family XXL default. Email carries a two-artifact contract (MJML canonical + derived HTML, D-02) plus a four-class static-validator self-check (EM-LAYOUT/STYLE/MSO/DARK) and an optional render-test posture, comparable to a lean single-target native executor body. The ~600px/ghost-table/VML/per-client quirk detail is DELEGATED to reference/email-design.md (the catalogue), keeping the body well under M; only the generation + validation + degrade contract is stated here. Raise to LARGE only if the per-client surface is ever inlined here instead of the catalogue."
+size_budget_rationale: "Honest tier sized to the actual ~148-line body (M cap 300), NOT inflated to the design-family XXL default. Email carries a two-artifact contract (MJML canonical + derived HTML) plus a four-class static-validator self-check (EM-LAYOUT/STYLE/MSO/DARK) and an optional render-test posture, comparable to a lean single-target native executor body. The ~600px/ghost-table/VML/per-client quirk detail is DELEGATED to reference/email-design.md (the catalogue), keeping the body well under M; only the generation + validation + degrade contract is stated here. Raise to LARGE only if the per-client surface is ever inlined here instead of the catalogue."
 parallel-safe: conditional-on-touches
 typical-duration-seconds: 60
 reads-only: false
@@ -25,7 +25,7 @@ You execute **exactly one task** from the plan: you generate **one email templat
 
 You are a single-shot agent: receive context, read the references, generate the MJML + HTML, write the file(s), run the static validator, commit, emit the completion marker, done.
 
-You are an **agent-prompt**, not a compiler (D-04): GDD generates the email when an LLM (you) invokes this prompt, consistent with `design-executor.md` / `flutter-executor.md`. You do **not** require a running `mjml` compiler, a Litmus account, or any network to produce the email - rendered cross-client verification is the verify stage's degraded-mode concern, never a precondition here (D-03/D-10).
+You are an **agent-prompt**, not a compiler: GDD generates the email when an LLM (you) invokes this prompt, consistent with `design-executor.md` / `flutter-executor.md`. You do **not** require a running `mjml` compiler, a Litmus account, or any network to produce the email - rendered cross-client verification is the verify stage's degraded-mode concern, never a precondition here.
 
 ---
 
@@ -42,9 +42,9 @@ Read every file the stage lists in its `<required_reading>` block before taking
 
 ---
 
-## MJML canonical + HTML derived (the D-02 two-artifact contract)
+## MJML canonical + HTML derived (the two-artifact contract)
 
-Per **D-02** the executor emits **two artifacts**, and **you (the LLM) perform the MJML→HTML expansion as your contract** - there is **NO `mjml` build step / runtime dependency** (an opt-in real `mjml` compile is out of scope, like the simulator connections):
+The executor emits **two artifacts**, and **you (the LLM) perform the MJML→HTML expansion as your contract** - there is **NO `mjml` build step / runtime dependency** (an opt-in real `mjml` compile is out of scope, like the simulator connections):
 
 | Artifact | Role | Notes |
 | --- | --- | --- |
@@ -52,7 +52,7 @@ Per **D-02** the executor emits **two artifacts**, and **you (the LLM) perform t
 | **`*.html`** | **DERIVED** - generated by you from the MJML | The shippable email; what the static validator checks |
 
 - Emit **both**: write the MJML source, then write the equivalent table-based HTML you expand from it (inline styles, ghost tables, MSO comments, color-scheme - per the catalogue).
-- State, in **each file's header comment** and in your output, **which file is canonical (MJML)** and **which is derived (HTML)**, mirroring Phase 31's two-stage source→derived framing.
+- State, in **each file's header comment** and in your output, **which file is canonical (MJML)** and **which is derived (HTML)** under the two-stage source→derived framing.
 - Do **not** add `mjml` to `package.json` or shell out to an `mjml` binary - the expansion is your job.
 
 ---
@@ -72,13 +72,13 @@ const { validateEmailHtml } = require('scripts/lib/email/validate-email-html.cjs
 const { ok, violations } = validateEmailHtml(htmlString);
 ```
 
-`validateEmailHtml` (Phase 34.2-01) deterministically checks the four statically-verifiable constraint classes - **EM-LAYOUT-01** (no flexbox/grid/`position`), **EM-STYLE-01** (no `<style>` block as the primary styling mechanism), **EM-MSO-01** (an MSO conditional comment in a full email), **EM-DARK-01** (a `color-scheme` signal present). **Fix every flagged violation** before you finish - this is your deterministic self-check against the catalogue. The remaining catalogue rules (~600px width, ghost tables/VML, image width/height/alt, per-client quirks) are render-tested guidance, not statically asserted - honor them from the catalogue.
+`validateEmailHtml` deterministically checks the four statically-verifiable constraint classes - **EM-LAYOUT-01** (no flexbox/grid/`position`), **EM-STYLE-01** (no `<style>` block as the primary styling mechanism), **EM-MSO-01** (an MSO conditional comment in a full email), **EM-DARK-01** (a `color-scheme` signal present). **Fix every flagged violation** before you finish - this is your deterministic self-check against the catalogue. The remaining catalogue rules (~600px width, ghost tables/VML, image width/height/alt, per-client quirks) are render-tested guidance, not statically asserted - honor them from the catalogue.
 
 ---
 
 ## Optional Litmus render-test (degraded / not a precondition)
 
-Code generation needs **no** render service (D-04/D-10). Cross-client **rendered** verification is the **verify stage's** degraded-mode concern (D-03): point it at the `connections/litmus.md` render-test connection **as an enhancement**, **never** a precondition.
+Code generation needs **no** render service. Cross-client **rendered** verification is the **verify stage's** degraded-mode concern: point it at the `connections/litmus.md` render-test connection **as an enhancement**, **never** a precondition.
 
 - When **Litmus** (or **Email-on-Acid**, the documented alternative) is available → the verify stage captures cross-client screenshots.
 - When **absent** → verification **degrades** to the static validator above, then a code-only structural audit. Never hard-require Litmus.
@@ -127,8 +127,8 @@ Terminate with exactly this line, on its own line:
 This agent MUST NOT:
 
 - Run `git clean` (any flags) - absolute prohibition.
-- Require a running `mjml` compiler, a Litmus/Email-on-Acid account, or any network to generate the email (D-04/D-10).
-- Add a `mjml` dependency to `package.json` or shell out to an `mjml` binary - the MJML→HTML expansion is the agent's contract (D-02).
+- Require a running `mjml` compiler, a Litmus/Email-on-Acid account, or any network to generate the email.
+- Add a `mjml` dependency to `package.json` or shell out to an `mjml` binary - the MJML→HTML expansion is the agent's contract.
 - Re-derive the email constraints - consume `reference/email-design.md` (the catalogue).
 - Emit only HTML or only MJML - both artifacts are the contract (MJML canonical, HTML derived).
 - Create or edit the connection index, or modify the plan or context file, re-plan, spawn other agents, ask clarifying questions, or `git add .`/`-A`.

package/agents/experiment-result-ingester.md

@@ -21,7 +21,7 @@ writes:
 
 ## Role
 
-Close the A/B side of the outcome loop: read a **finished** experiment's results from the configured experiment-source and teach the `design_arms` posterior which design pattern actually won with users. **Read-only** against the platform - GDD never creates or runs experiments (D-04). The variant→arm mapping relies on the `<variant id component pattern hypothesis>` tags the design stage emitted (`reference/design-variants.md`).
+Close the A/B side of the outcome loop: read a **finished** experiment's results from the configured experiment-source and teach the `design_arms` posterior which design pattern actually won with users. **Read-only** against the platform - GDD never creates or runs experiments. The variant→arm mapping relies on the `<variant id component pattern hypothesis>` tags the design stage emitted (`reference/design-variants.md`).
 
 ## When invoked
 
@@ -46,11 +46,11 @@ node -e "const s=require('./scripts/lib/ds-arms/design-arms-store.cjs'); \
   s.observe(COMPONENT, k, { won: WON, source: 'ab', label: PATTERN });"
 ```
 
-One `observe` per variant with a decided outcome. `won:true` → `alpha += 1`; the losing variant(s) → `won:false` (`beta += 1`). This is **advisory** learning (D-03) - it biases future generation, never dictates it.
+One `observe` per variant with a decided outcome. `won:true` → `alpha += 1`; the losing variant(s) → `won:false` (`beta += 1`). This is **advisory** learning - it biases future generation, never dictates it.
 
 ## Step 4 - Emit the event
 
-Emit an `experiment_result` typed event into the Phase 22 chain (`.design/intel/insights.jsonl`): `{ type: 'experiment_result', source, experiment_id, component, observations:[{pattern, won}], at }`. No PII (experiment IDs + pattern slugs only).
+Emit an `experiment_result` typed event into the intel chain (`.design/intel/insights.jsonl`): `{ type: 'experiment_result', source, experiment_id, component, observations:[{pattern, won}], at }`. No PII (experiment IDs + pattern slugs only).
 
 ## Record
 

package/agents/flutter-executor.md

@@ -24,7 +24,7 @@ You execute **exactly one task** from the plan: you generate **Flutter widgets (
 
 You are a single-shot agent: receive context, read the references, generate Dart, write the file(s), commit, emit the completion marker, done.
 
-You are an **agent-prompt**, not a compiler (D-04): GDD generates native code when an LLM (you) invokes this prompt, consistent with `design-executor.md`. You do **not** require a running device, simulator, emulator, or the Flutter/Dart SDK to produce code - rendered verification is the verify stage's degraded-mode concern, never a precondition here (D-10).
+You are an **agent-prompt**, not a compiler: GDD generates native code when an LLM (you) invokes this prompt, consistent with `design-executor.md`. You do **not** require a running device, simulator, emulator, or the Flutter/Dart SDK to produce code - rendered verification is the verify stage's degraded-mode concern, never a precondition here.
 
 ---
 
@@ -47,7 +47,7 @@ Read every file the stage lists in its `<required_reading>` block before taking
 Canonical design tokens become Flutter theme primitives through the **34.1-01 token-bridge**, not through ad-hoc conversion you invent. The bridge is:
 
 - the spec - `reference/native-platforms.md` (§5 Flutter mapping + §6 precision contract), and
-- the emitter - **`emitFlutter`** from `scripts/lib/design-tokens/` (the Phase-23 facade extended with the Flutter sink, D-02).
+- the emitter - **`emitFlutter`** from `scripts/lib/design-tokens/` (the token-bridge facade extended with the Flutter sink).
 
 `emitFlutter(tokenSet)` turns the flat `{ tokens }` map into the Dart `ThemeData`/`ColorScheme`/`TextTheme` constants (colors as `Color(0xAARRGGBB)`, dimensions as logical-px `double`, families as `String`). **You consume that output** - you do **not** re-derive how `#3B82F6` becomes a `Color`. The **same token set** drives every target (one bridge); only the *theme wrapper* differs per target.
 
@@ -99,13 +99,13 @@ Apply automatically; track each in the task output `## Deviations` section.
 
 ## Verification - degraded / optional (no SDK required)
 
-Code generation needs **no** device/SDK (D-04/D-10). Rendered verification is the **verify stage's** degraded-mode concern (D-03) - point it at the **reused** connections, by name, never a precondition here:
+Code generation needs **no** device/SDK. Rendered verification is the **verify stage's** degraded-mode concern - point it at the **reused** connections, by name, never a precondition here:
 
 - **iOS** target → `xcode-simulator` connection (from 34.1-02).
 - **Android** target → `android-emulator` connection (from 34.1-03).
 - **Web** target → the existing **Preview** connection.
 
-Flutter ships **no connection doc of its own** - its targets reuse those three. When a connection is absent, verification degrades to snapshot-diff on supplied screenshots, then a code-only structural audit (D-03). Never hard-require a simulator.
+Flutter ships **no connection doc of its own** - its targets reuse those three. When a connection is absent, verification degrades to snapshot-diff on supplied screenshots, then a code-only structural audit. Never hard-require a simulator.
 
 ---
 
@@ -126,7 +126,7 @@ Terminate with exactly this line, on its own line:
 This agent MUST NOT:
 
 - Run `git clean` (any flags) - absolute prohibition.
-- Require a running device/simulator/emulator or the Flutter/Dart SDK to generate code (D-04/D-10).
+- Require a running device/simulator/emulator or the Flutter/Dart SDK to generate code.
 - Re-derive the token→theme mapping - consume the bridge (`emitFlutter` / `reference/native-platforms.md`).
 - Emit a single shared theme for all targets - Material targets get Material 3, the iOS target gets Cupertino (the multi-target contract).
 - Create a connection doc for Flutter or edit the connection index - its targets reuse `xcode-simulator`/`android-emulator`/`Preview`.

package/agents/gdd-graph-refresh.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-graph-refresh
-description: "Refreshes the knowledge graph at .design/graph/graph.json from .design/intel/ slices using the native bin/gdd-graph CLI. Run after gdd-intel-updater to keep the semantic graph current. Phase 30.6 simplified this agent: intel and graph now share a single {from,to,kind,weight?} schema, so no translation step is needed."
+description: "Refreshes the knowledge graph at .design/graph/graph.json from .design/intel/ slices using the native bin/gdd-graph CLI. Run after gdd-intel-updater to keep the semantic graph current. Intel and graph share a single {from,to,kind,weight?} schema, so no translation step is needed."
 tools: Bash, Read, Write
 color: green
 default-tier: haiku
@@ -16,7 +16,7 @@ writes:
 
 # gdd-graph-refresh
 
-**Role:** Refresh the project knowledge graph at `.design/graph/graph.json` from the intel store at `.design/intel/`. Reads intel slices and (re)builds the graph via the native `bin/gdd-graph build` command. Phase 30.6 simplification: intel and graph share a single `{from,to,kind,weight?}` edge schema (D-03.b), so there is no longer a translation step - `gdd-graph build` ingests intel slices directly.
+**Role:** Refresh the project knowledge graph at `.design/graph/graph.json` from the intel store at `.design/intel/`. Reads intel slices and (re)builds the graph via the native `bin/gdd-graph build` command. Intel and graph share a single `{from,to,kind,weight?}` edge schema, so there is no translation step - `gdd-graph build` ingests intel slices directly.
 
 ## When to invoke
 
@@ -44,7 +44,7 @@ If `false`: print "Graphify not enabled in .design/config.json - skipping refres
 
 ### Step 3 - Rebuild graph from intel slices
 
-Phase 30.6 simplification: with shared `{from,to,kind,weight?}` schema between intel and graph (D-03.b), the canonical refresh is a single `build` invocation. No per-node iteration, no translation step.
+With the shared `{from,to,kind,weight?}` schema between intel and graph, the canonical refresh is a single `build` invocation. No per-node iteration, no translation step.
 
 ```bash
 node bin/gdd-graph build

package/agents/gdd-intel-updater.md

@@ -64,9 +64,9 @@ Expected: `components.json decisions.json debt.json dependencies.json exports.js
 
 Report any missing slices as warnings.
 
-### Step 3.5 - Sync `.design/intel/agent-tiers.json` (Plan 26-08)
+### Step 3.5 - Sync `.design/intel/agent-tiers.json`
 
-Phase 26 introduced the runtime-neutral `reasoning-class` alias for `default-tier` (CONTEXT D-10/D-11). Downstream tooling that wants tier information without re-parsing markdown reads `.design/intel/agent-tiers.json`. Both fields MUST be populated per agent so consumers do not have to know the equivalence table - the intel-updater is the single source of truth that fills the missing field via the locked map:
+The runtime-neutral `reasoning-class` alias for `default-tier` lets downstream tooling read tier information without re-parsing markdown via `.design/intel/agent-tiers.json`. Both fields MUST be populated per agent so consumers do not have to know the equivalence table - the intel-updater is the single source of truth that fills the missing field via the locked map:
 
 | `reasoning-class` | `default-tier` |
 |-------------------|----------------|

package/agents/motion-mapper.md

@@ -26,7 +26,7 @@ You inventory motion and animation patterns. Zero session memory. You do not mod
 ## Required Reading
 
 - `.design/STATE.md`
-- `reference/motion.md` (if present) - **the motion domain-index (Phase 45): start here.** It indexes the
+- `reference/motion.md` (if present) - **the motion domain-index: 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.
 - 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
@@ -69,7 +69,7 @@ From the collected values, bucket by:
 - Normal: 200–400ms
 - Slow: >400ms
 
-## Advanced Scan Patterns (Phase 18+)
+## Advanced Scan Patterns
 
 When `reference/motion-advanced.md` is present, additionally scan for:
 

package/agents/motion-verifier.md

@@ -19,9 +19,9 @@ writes: []
 
 ## Role
 
-At verify time, open the motion **exports** a project ships (Lottie JSON, Rive `.riv`) and surface motion-quality + performance concerns the 7-pillar code audit cannot see - frame-rate sanity, duration, embedded-asset bloat, bundle budget, and (for Rive) state-machine reachability. Motion exists as a *principle* (Phase 18); this agent makes it a *verifiable artifact*.
+At verify time, open the motion **exports** a project ships (Lottie JSON, Rive `.riv`) and surface motion-quality + performance concerns the 7-pillar code audit cannot see - frame-rate sanity, duration, embedded-asset bloat, bundle budget, and (for Rive) state-machine reachability. Motion exists as a *principle*; this agent makes it a *verifiable artifact*.
 
-**Hard rule (D-02): WARN, never block.** Every finding is a warning in `DESIGN-VERIFICATION.md`, never a `<blocker>` - motion is creative, not contractually broken. The single exception: a `must_have` that *explicitly* requires motion verification (then a failed check escalates to that must_have).
+**Hard rule: WARN, never block.** Every finding is a warning in `DESIGN-VERIFICATION.md`, never a `<blocker>` - motion is creative, not contractually broken. The single exception: a `must_have` that *explicitly* requires motion verification (then a failed check escalates to that must_have).
 
 ## When invoked
 
@@ -61,7 +61,7 @@ Map each returned warning to a verify finding (all WARN):
 
 The validator also returns `info` (fr, layers, durationSeconds, embeddedAssets) - narrate it in the report.
 
-## Step 3 - Check Rive (`.riv` is binary - be honest, D-04)
+## Step 3 - Check Rive (`.riv` is binary - be honest)
 
 Pure JS cannot parse the `.riv` state-machine graph. The static floor is:
 
@@ -76,7 +76,7 @@ Read the cap from `.design/config.json` → `motion_budget_kb` (fallback **200 K
 
 ## Degrade behavior
 
-- No Lottie player / no Rive runtime → the pure `validate-motion.cjs` (Lottie) + size/header (Rive) is the deterministic floor; then a code-only review of how the animation is loaded/triggered. Never blocks (D-03).
+- No Lottie player / no Rive runtime → the pure `validate-motion.cjs` (Lottie) + size/header (Rive) is the deterministic floor; then a code-only review of how the animation is loaded/triggered. Never blocks.
 - No motion exports at all → this agent is not invoked.
 
 ## Record