@tekyzinc/gsd-t 2.56.15 → 2.58.10

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [2.58.10] - 2026-04-05
+
+### Added
+- **Hierarchical design contracts** — `element` → `widget` → `page` contract hierarchy for design-to-code projects. Element contracts are the single source of truth for visual spec (one contract per visual variant, e.g., `chart-bar-stacked-horizontal` and `chart-bar-stacked-vertical` are separate). Widgets compose elements with layout + data binding. Pages compose widgets with routing + grid layout.
+- **Precedence rule**: element > widget > page. Widgets and pages SELECT and POSITION elements but cannot override element visual spec. Structural drift becomes impossible.
+- **New templates**: `templates/element-contract.md`, `templates/widget-contract.md`, `templates/page-contract.md`
+- **New command**: `/user:gsd-t-design-decompose` — surveys a design (Figma/image/prototype), classifies elements (reuse count ≥2 or non-trivial spec → promoted to element contract), identifies widgets and pages, writes the full contract hierarchy under `.gsd-t/contracts/design/{elements,widgets,pages}/` plus an `INDEX.md` navigation map.
+
+### Changed
+- `design-to-code.md` stack rule adds Section 0 explaining flat vs. hierarchical contract modes and detection at execute-time (presence of `.gsd-t/contracts/design/` triggers hierarchical verification: elements first, then widgets, then pages)
+- Command count: 48 GSD-T + 5 utility = 53 total
+
+## [2.57.10] - 2026-04-04
+
+### Added
+- **Design Verification Agent** — dedicated subagent (Step 5.25) spawned after QA and before Red Team when `.gsd-t/contracts/design-contract.md` exists. Opens a browser with both the built frontend AND the original design (Figma/image) side-by-side for direct visual comparison. Produces a 30+ row structured comparison table with MATCH/DEVIATION verdicts. Artifact gate enforces completion — missing table triggers re-spawn.
+- Wired into `gsd-t-execute` (Step 5.25) and `gsd-t-quick` (Step 5.25)
+
+### Changed
+- **Separation of concerns**: Coding agents no longer perform visual verification inline (removed 45-line Step 7 from task subagent prompt). Coding agents write precise code from design tokens; the verification agent proves it matches.
+- `design-to-code.md` Section 15 slimmed from 120 lines to 20 lines — now points to the dedicated agent instead of embedding the full verification loop in the stack rule
+- `CLAUDE-global.md` updated with Design Verification Agent section between QA and Red Team
+- Red Team now runs after Design Verification (previously ran directly after QA)
+- Non-design projects are completely unaffected (gate checks for design-contract.md existence)
+
 ## [2.52.11] - 2026-04-01
 
 ### Added

package/README.md

@@ -17,6 +17,7 @@ A methodology for reliable, parallelizable development using Claude Code with op
 **Token-Aware Orchestration** — `token-budget.js` tracks session token consumption and applies graduated degradation: downgrade model assignments when approaching limits, checkpoint and skip non-essential operations to conserve budget, and halt cleanly with a resume instruction at the ceiling. Wave and execute phases check budget before each subagent spawn.
 **Quality North Star** — projects define a `## Quality North Star` section in CLAUDE.md (1–3 sentences, e.g., "This is a published npm library. Every public API must be intuitive and backward-compatible."). `gsd-t-init` auto-detects preset (library/web-app/cli) from package.json signals; `gsd-t-setup` configures it for existing projects. Subagents read it as a quality lens; absent = silent skip (backward compatible).
 **Design Brief Artifact** — during partition, UI/frontend projects (React, Vue, Svelte, Flutter, Tailwind) automatically get `.gsd-t/contracts/design-brief.md` with color palette, typography, spacing system, component patterns, and tone/voice. Non-UI projects skip silently. User-customized briefs are preserved. Referenced in plan phase for visual consistency.
+**Design Verification Agent** — after QA passes on design-to-code projects, a dedicated verification agent opens a browser with both the built frontend AND the original design (Figma page, design image, or MCP screenshot) side-by-side for direct visual comparison. Produces a structured element-by-element comparison table (30+ rows) with specific design values vs. implementation values and MATCH/DEVIATION verdicts. An artifact gate enforces that the comparison table exists — missing it blocks completion. Separation of concerns: coding agents code, verification agents verify. Wired into execute (Step 5.25) and quick (Step 5.25). Only fires when `.gsd-t/contracts/design-contract.md` exists — non-design projects are unaffected.
 **Exploratory Testing** — after scripted tests pass, if Playwright MCP is registered in Claude Code settings, QA agents get 3 minutes and Red Team gets 5 minutes of interactive browser exploration. All findings tagged `[EXPLORATORY]` and tracked separately in QA calibration. Silent skip when Playwright MCP absent. Wired into execute, quick, integrate, and debug.
 
 ---
@@ -29,7 +30,7 @@ A methodology for reliable, parallelizable development using Claude Code with op
 npx @tekyzinc/gsd-t install
 ```
 
-This installs 47 GSD-T commands + 5 utility commands (52 total) to `~/.claude/commands/` and the global CLAUDE.md to `~/.claude/CLAUDE.md`. Works on Windows, Mac, and Linux.
+This installs 48 GSD-T commands + 5 utility commands (53 total) to `~/.claude/commands/` and the global CLAUDE.md to `~/.claude/CLAUDE.md`. Works on Windows, Mac, and Linux.
 
 ### Start Using It
 
@@ -148,6 +149,7 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 | `/user:gsd-t-gap-analysis` | Requirements gap analysis — spec vs. existing code | Manual |
 | `/user:gsd-t-promote-debt` | Convert techdebt items to milestones | Manual |
 | `/user:gsd-t-populate` | Auto-populate docs from existing codebase | Manual |
+| `/user:gsd-t-design-decompose` | Decompose design into element/widget/page contracts | Manual |
 
 ### Milestone Workflow
 
@@ -337,7 +339,7 @@ get-stuff-done-teams/
 ├── LICENSE
 ├── bin/
 │   └── gsd-t.js                       # CLI installer
-├── commands/                          # 51 slash commands
+├── commands/                          # 53 slash commands
 │   ├── gsd-t-*.md                     # 45 GSD-T workflow commands
 │   ├── gsd.md                         # GSD-T smart router
 │   ├── branch.md                      # Git branch helper

package/commands/gsd-t-design-decompose.md

@@ -0,0 +1,241 @@
+# GSD-T: Design Decompose — Hierarchical Contract Extraction
+
+You are the lead agent for decomposing a design (Figma file, image, screenshot, or prototype URL) into a hierarchy of element / widget / page contracts.
+
+**Output**: A tree of contracts — elements at the bottom (atomic, reusable, variant-per-contract), widgets in the middle (element composition + data binding), pages at the top (widget assembly + layout + routing).
+
+**Why hierarchical contracts:** A flat `design-contract.md` makes verification expensive and lets drift accumulate (two donut charts on two pages diverge over time). Hierarchical contracts verify elements in isolation once, then compose — drift is impossible because elements are the single source of truth for visual spec.
+
+**When to use this command:**
+- Starting a design-to-code project with multiple pages sharing components
+- Retrofitting an existing flat `design-contract.md` into reusable parts
+- Adding a new page that reuses existing elements/widgets
+
+If the project is small (single page, ≤10 elements, nothing reusable), use the flat `design-contract.md` template instead and skip this command.
+
+---
+
+## Step 0: Detect Inputs
+
+Run these checks, log results to user inline:
+
+1. **Figma MCP available?**
+   - If yes → log "Figma MCP detected — will extract exact tokens per element"
+   - If no → log "Figma MCP unavailable — using visual analysis (reduced precision)"
+2. **Existing flat contract?**
+   - If `.gsd-t/contracts/design-contract.md` exists → this is a retrofit; read it and use it as input alongside the design source
+   - If not → this is a fresh decomposition from the design source directly
+3. **Design source provided?**
+   - Required: Figma URL, image path, or prototype URL in `$ARGUMENTS`
+   - If missing → ask user: "Provide the design source (Figma URL, image path, or prototype URL)"
+
+## Step 1: Survey the Design
+
+Enumerate every visual element on every page/screen in the design. Use Figma MCP `get_metadata` or `get_design_context` if available; otherwise use visual analysis on the image.
+
+Produce an initial flat inventory table:
+
+| # | Element on Design                  | Appears On Pages       | Visual Variant                       |
+|---|------------------------------------|------------------------|--------------------------------------|
+| 1 | Donut chart with center label      | Overview, Analytics    | chart-donut                          |
+| 2 | Horizontal stacked bar chart       | Analytics              | chart-bar-stacked-horizontal         |
+| 3 | Vertical legend on right           | Overview               | legend-vertical-right                |
+| 4 | KPI tile with delta indicator      | Overview (×4)          | stat-card-with-delta                 |
+| ...
+
+**Rule**: distinct visual variants = distinct rows. A horizontal stacked bar and a vertical stacked bar are TWO rows, not one.
+
+## Step 2: Classify Each Element
+
+For each row in the inventory, assign:
+
+- **Category** — chart / legend / axis / card / table / control / layout / typography / icon / other
+- **Reuse count** — how many times does it appear across the entire design?
+- **Owner layer** — element / widget-internal / page-internal
+
+**Promotion rule**: an item becomes an **element contract** if:
+- It appears ≥2 times across the design, OR
+- It has non-trivial visual spec (≥5 distinct spec properties), OR
+- It has states or interactions beyond "static display"
+
+Otherwise, it stays internal to its widget or page (no contract needed).
+
+## Step 3: Identify Widgets
+
+A **widget** is a reusable composition of elements + data binding that appears as a visual group in the design. Examples: "Revenue Breakdown" (donut + legend + title + filter), "Stat Strip" (4× stat-card-with-delta).
+
+For each visual group in the design, determine:
+- Does it appear on ≥2 pages, OR is it clearly a reusable unit conceptually?
+  - Yes → widget contract
+  - No → page-internal composition (no widget contract needed)
+
+Produce a widget inventory:
+
+| # | Widget Name               | Appears On Pages       | Elements Used                                   |
+|---|---------------------------|------------------------|-------------------------------------------------|
+| 1 | revenue-breakdown-widget  | Overview, Analytics    | chart-donut, legend-vertical-right, heading-h3, select-dropdown |
+| 2 | stat-strip-widget         | Overview               | stat-card-with-delta (×4)                       |
+| ...
+
+## Step 4: Identify Pages
+
+Each page/screen in the design becomes a page contract. Document:
+- Widgets used and grid position
+- Global layout (header, sidebar, main)
+- Route + auth guards
+
+## Step 5: Confirm Decomposition With User
+
+Present the full hierarchy summary:
+
+```
+DECOMPOSITION SUMMARY
+─────────────────────
+Elements: 14 contracts
+  Charts: 4 (chart-donut, chart-bar-stacked-horizontal, chart-line, chart-sparkline)
+  Legends: 2 (legend-vertical-right, legend-horizontal-bottom)
+  Cards: 2 (stat-card, stat-card-with-delta)
+  Tables: 1 (table-dense)
+  Controls: 5 (button-primary, select-dropdown, input-search, tabs-underline, toggle)
+
+Widgets: 6 contracts
+  stat-strip-widget, revenue-breakdown-widget, user-growth-widget,
+  recent-activity-table-widget, page-header-widget, nav-sidebar-widget
+
+Pages: 3 contracts
+  dashboard-overview, analytics-detail, settings
+
+Total: 23 contracts (vs. flat: ~57 elements in single file)
+
+Cost estimate:
+  - Decomposition effort: ~{N} hours to write all contracts
+  - Verification: elements verified once, reused everywhere → no drift
+  - Implementation: widgets become assembly, not reinvention
+```
+
+Ask user: "Proceed with this decomposition? [y/n/edit]"
+- **y** → Step 6
+- **n** → abort
+- **edit** → accept user revisions to the hierarchy, re-present
+
+## Step 6: Write Contracts
+
+Create the directory structure:
+
+```
+.gsd-t/contracts/design/
+├── elements/
+│   ├── chart-donut.contract.md
+│   ├── chart-bar-stacked-horizontal.contract.md
+│   ├── legend-vertical-right.contract.md
+│   └── ... (one file per element)
+├── widgets/
+│   ├── revenue-breakdown-widget.contract.md
+│   └── ... (one file per widget)
+├── pages/
+│   ├── dashboard-overview.contract.md
+│   └── ... (one file per page)
+└── INDEX.md  (hierarchy map + cross-references)
+```
+
+For each element contract:
+1. Copy `templates/element-contract.md` as scaffold
+2. Fill in visual spec from Figma MCP (exact values) or visual analysis (estimated values)
+3. Fill in states, interactions, data binding, accessibility, verification checklist
+4. If Figma MCP available → use `get_design_context` per element node to extract tokens
+
+For each widget contract:
+1. Copy `templates/widget-contract.md` as scaffold
+2. Reference elements by name in the "Elements Used" table
+3. Define layout, data binding, responsive behavior, widget-level verification
+
+For each page contract:
+1. Copy `templates/page-contract.md` as scaffold
+2. Reference widgets in grid positions
+3. Define route, data loading, global states, performance budget
+
+Write `INDEX.md` as a navigation map:
+
+```markdown
+# Design Contracts: {Project Name}
+
+## Elements (14)
+- [chart-donut](elements/chart-donut.contract.md) — used by revenue-breakdown-widget
+- [chart-bar-stacked-horizontal](elements/chart-bar-stacked-horizontal.contract.md) — used by analytics-trend-widget
+- ...
+
+## Widgets (6)
+- [revenue-breakdown-widget](widgets/revenue-breakdown-widget.contract.md) — uses chart-donut, legend-vertical-right
+- ...
+
+## Pages (3)
+- [dashboard-overview](pages/dashboard-overview.contract.md) — uses stat-strip-widget, revenue-breakdown-widget, user-growth-widget, recent-activity-table-widget
+- ...
+
+## Precedence
+element contract > widget contract > page contract
+
+Widgets and pages reference elements by name. They CANNOT override element visual spec. To customize, create a new element variant.
+```
+
+## Step 7: Wire Into Partition
+
+If `.gsd-t/domains/` exists (project is already partitioned), append to relevant domain's `scope.md`:
+
+```markdown
+## Design Contracts
+This domain owns the following design contracts:
+- Elements: chart-donut, legend-vertical-right
+- Widgets: revenue-breakdown-widget
+- Pages: (none — pages owned by page-assembly domain)
+```
+
+If `.gsd-t/domains/` does NOT exist yet, suggest the user run `/user:gsd-t-partition` next, with a note that design contracts should be partitioned into domains:
+- **design-system domain** owns element contracts
+- **widgets domain** owns widget contracts
+- **pages domain** owns page assembly + routing
+
+## Step 8: Update progress.md Decision Log
+
+Append:
+```
+- {YYYY-MM-DD HH:MM}: gsd-t-design-decompose — created {N} element / {N} widget / {N} page contracts under .gsd-t/contracts/design/. Hierarchy: elements are single source of truth for visual spec; widgets compose elements; pages compose widgets.
+```
+
+## Step 9: Next Up Hint
+
+Display:
+
+```
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Partition** — decompose project into domains owning the design contracts
+
+`/user:gsd-t-partition`
+
+**Also available:**
+- `/user:gsd-t-execute` — build element contracts first (they're independently testable)
+- `/user:gsd-t-plan` — plan tasks around the contract hierarchy
+
+───────────────────────────────────────────────────────────────
+```
+
+---
+
+## Document Ripple
+
+After writing contracts, update:
+- `.gsd-t/progress.md` — Decision Log entry (Step 8)
+- `docs/architecture.md` — add "Design Contract Hierarchy" section if not present
+- If existing flat `.gsd-t/contracts/design-contract.md` was retrofitted → mark it with a DEPRECATED header pointing to `design/INDEX.md`
+
+## Pre-Commit Gate
+
+- [ ] All contracts written from templates (element/widget/page)
+- [ ] `INDEX.md` created with full hierarchy + precedence note
+- [ ] Decision Log updated in progress.md
+- [ ] architecture.md updated if this is a new concept for the project
+
+$ARGUMENTS

package/commands/gsd-t-execute.md

@@ -282,53 +282,12 @@ Execute the task above:
         recovers (retry button works, form can be resubmitted, etc.).
      A test that would pass on an empty HTML page with the right element IDs is useless.
      Every assertion must prove the FEATURE WORKS, not that the ELEMENT EXISTS.
-7. **Visual Design Verification** (MANDATORY when design-to-code stack rule is active):
-   If the task involves UI implementation from a design reference, this step is NOT optional.
-   **FAIL-BY-DEFAULT**: Every element is UNVERIFIED until you prove it matches. "Looks close" is not
-   a verdict. "Appears to match" is not a verdict. Assume NOTHING matches.
-   a. **Get the Figma reference screenshot**: If Figma MCP is available, call `get_screenshot` with the
-      relevant nodeId and fileKey from `.gsd-t/contracts/design-contract.md`. Save this as the reference.
-      If no Figma MCP, use the design image/screenshot provided in the contract.
-   b. **Build the element inventory**: Before comparing ANYTHING, enumerate every distinct visual
-      element in the design — walk top-to-bottom, left-to-right. Every chart, label, icon, heading,
-      card, button, spacing boundary, color, and data visualization detail gets its own row.
-      Data visualizations expand into multiple rows: chart type, orientation, axis labels, legend
-      position, bar/segment colors, data labels, grid lines, center text, tooltip style.
-      If a full-page inventory has fewer than 30 elements, you missed items — go back.
-   c. **Open side-by-side browser sessions for direct visual comparison**:
-      Start the dev server if not running. Open TWO views simultaneously:
-      - **View 1 — Built frontend**: Use Claude Preview, Chrome MCP, or Playwright to open the
-        implemented page at the correct URL. Navigate to the exact route/component being verified.
-      - **View 2 — Original design**: If Figma URL → open the Figma page in another browser tab.
-        If design image file → open the image in a browser tab (`file://` path or HTML wrapper).
-        If Figma MCP screenshot → open that screenshot image.
-      Walk through each component with both views visible. Compare element-by-element at matching
-      zoom levels. Capture screenshot pairs (design + implementation) at each target breakpoint:
-        - Mobile: 375px width
-        - Tablet: 768px width
-        - Desktop: 1280px width
-   d. **Structured element-by-element comparison** (MANDATORY FORMAT — no prose comparisons):
-      Produce a table with this exact structure for every element in the inventory:
-      `| # | Section | Element | Design (specific) | Implementation (specific) | Verdict |`
-      Rules:
-        - "Design" column: SPECIFIC values (chart type name, hex color, px size, font weight)
-        - "Implementation" column: SPECIFIC observed values from the screenshot — not code assumptions
-        - Verdict: only ✅ MATCH or ❌ DEVIATION — never "appears to match" or "need to verify"
-        - Data visualizations: chart type, axis orientation, axis labels, legend position, bar colors,
-          data label placement, grid lines, center text — each a SEPARATE row
-        - NEVER lead with "what's working" — the table IS the comparison, start with row 1
-   e. **Fix every ❌ DEVIATION** — fix each row individually, trace to design contract value.
-      Re-render after each batch of fixes. Update verdict only after visual re-verification.
-      Max 3 fix-and-recheck iterations per component.
-   f. **Final table**: After fixes, every row must be ✅ MATCH. Any remaining ❌ → log to
-      `.gsd-t/qa-issues.md` with severity CRITICAL and tag `[VISUAL]`. BLOCKS task completion.
-      Report: "Verified: {N}/{total} elements match at {breakpoints} breakpoints"
-   g. **Log results** in the design contract's Verification Status table.
-   h. **If no browser/preview tools available**: This is a CRITICAL blocker, not a warning.
-      Log to `.gsd-t/qa-issues.md`: "CRITICAL: No browser tools available for visual verification.
-      Install Claude Preview or configure Playwright for visual testing."
-      The task CANNOT be marked complete without visual verification.
-   Skip this step entirely if no design-to-code stack rule was injected.
+7. **Visual Design Note** (when design-to-code stack rule is active):
+   Do NOT perform visual verification yourself — a dedicated Design Verification Agent
+   (Step 5.25) runs after all domain tasks complete and handles the full visual comparison.
+   Your job: write precise code from the design contract tokens. Use exact hex colors,
+   exact spacing values, exact typography. Every CSS value must trace to the design contract.
+   The verification agent will open a browser and prove whether your code matches.
 8. Run ALL test suites — this is NOT optional, not conditional, not "if applicable":
    a. Detect configured test runners: check for vitest/jest config, playwright.config.*, cypress.config.*
    b. Run EVERY detected suite. Unit tests alone are NEVER sufficient when E2E exists.
@@ -649,6 +608,160 @@ A teammate finishes independent tasks and is waiting on a checkpoint:
 2. If not, have the teammate work on documentation, tests, or code cleanup within their domain
 3. Or shut down the teammate and respawn when unblocked
 
+## Step 5.25: Design Verification Agent (MANDATORY when design contract exists)
+
+After all domain tasks complete and QA passes, check if `.gsd-t/contracts/design-contract.md` exists. If it does NOT exist, skip this step entirely.
+
+If it DOES exist — spawn a **dedicated Design Verification Agent**. This agent's ONLY job is to open a browser, compare the built frontend against the original design, and produce a structured comparison table. It writes NO feature code. Separation of concerns: the coding agent codes, the verification agent verifies.
+
+⚙ [{model}] Design Verification → visual comparison of built frontend vs design
+
+**OBSERVABILITY LOGGING (MANDATORY):**
+Before spawning — run via Bash:
+`T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M") && TOK_START=${CLAUDE_CONTEXT_TOKENS_USED:-0} && TOK_MAX=${CLAUDE_CONTEXT_TOKENS_MAX:-200000}`
+
+```
+Task subagent (general-purpose, model: opus):
+"You are the Design Verification Agent. Your ONLY job is to visually compare
+the built frontend against the original design and produce a structured
+comparison table. You write ZERO feature code. Your sole deliverable is
+the comparison table and verification results.
+
+FAIL-BY-DEFAULT: Every visual element starts as UNVERIFIED. You must prove
+each one matches — not assume it does. 'Looks close' is not a verdict.
+'Appears to match' is not a verdict. The only valid verdicts are MATCH
+(with proof) or DEVIATION (with specifics).
+
+## Step 1: Get the Design Reference
+
+Read .gsd-t/contracts/design-contract.md for the source reference.
+- If Figma MCP available → call get_screenshot with nodeId + fileKey from the contract
+- If design image files → locate them from the contract's Source Reference field
+- If no MCP and no images → log CRITICAL blocker to .gsd-t/qa-issues.md and STOP
+You MUST have a reference image before proceeding.
+
+## Step 2: Build the Element Inventory
+
+Before ANY comparison, enumerate every distinct visual element in the design.
+Walk the design top-to-bottom, left-to-right. For each section:
+  - Section title text and icon
+  - Every chart/visualization (type, orientation, labels, legend, series count)
+  - Every data table (columns, row structure, sort indicators)
+  - Every KPI/stat card (value, label, icon, trend indicator)
+  - Every button, toggle, tab, dropdown
+  - Every text element (headings, body, captions, labels)
+  - Every spacing boundary (section gaps, card padding, element margins)
+  - Every color usage (backgrounds, borders, text, chart fills)
+Write each element as a row for the comparison table.
+If the inventory has fewer than 20 elements for a full page, you missed items.
+
+Data visualizations MUST expand into multiple rows:
+  Chart type, chart orientation, axis labels, axis grid lines, legend position,
+  data labels placement, chart colors per series, bar width/spacing,
+  center text (donut/pie), tooltip style — each a SEPARATE element.
+
+## Step 3: Open Side-by-Side Browser Sessions
+
+Start the dev server (npm run dev, or project equivalent).
+Open TWO browser views simultaneously for direct visual comparison:
+
+VIEW 1 — BUILT FRONTEND:
+  Open the implemented page using Claude Preview, Chrome MCP, or Playwright.
+  Navigate to the exact route/component being verified.
+  You MUST see real rendered output — not just read the code.
+
+VIEW 2 — ORIGINAL DESIGN REFERENCE:
+  If Figma URL available → open the Figma page in a browser tab/window.
+    Use the Figma URL from the design contract Source Reference field.
+    Navigate to the specific frame/component being compared.
+  If design image file → open the image in a browser tab/window.
+    Use: file://{absolute-path-to-image} or render in an HTML page.
+  If Figma MCP screenshot was captured → open that screenshot image.
+
+COMPARISON APPROACH:
+  With both views open, walk through each component/section:
+    - Position views side-by-side (or switch between tabs)
+    - Compare each element visually at the same zoom level
+    - Screenshot BOTH views at matching viewport sizes
+  Capture implementation screenshots at each target breakpoint:
+    Mobile (375px), Tablet (768px), Desktop (1280px) minimum.
+  Each breakpoint is a separate screenshot pair (design + implementation).
+
+If Claude Preview, Chrome MCP, and Playwright are ALL unavailable:
+  This is a CRITICAL blocker. Log to .gsd-t/qa-issues.md:
+  'CRITICAL: No browser tools available for visual verification.'
+  STOP — the verification CANNOT proceed without a browser.
+
+## Step 4: Structured Element-by-Element Comparison (MANDATORY FORMAT)
+
+Produce a comparison table with this exact structure. Every element from
+the inventory gets its own row. No summarizing, no grouping, no prose.
+
+| # | Section | Element | Design (specific) | Implementation (specific) | Verdict |
+|---|---------|---------|-------------------|--------------------------|---------|
+| 1 | Summary | Chart type | Horizontal stacked bar | Vertical grouped bar | ❌ DEVIATION |
+| 2 | Summary | Chart colors | #4285F4, #34A853, #FBBC04 | #4285F4, #34A853, #FBBC04 | ✅ MATCH |
+
+Rules:
+- 'Design' column: SPECIFIC values (chart type name, hex color, px size, font weight)
+- 'Implementation' column: SPECIFIC observed values from the SCREENSHOT — not code assumptions
+- Verdict: only ✅ MATCH or ❌ DEVIATION — never 'appears to match' or 'need to verify'
+- NEVER write 'Appears to match' or 'Looks correct' — measure and verify
+- If the table has fewer than 30 rows for a full-page comparison, you skipped elements
+
+## Step 5: Report Deviations
+
+For each ❌ DEVIATION, write a specific finding:
+  'Design: {exact value}. Implementation: {exact value}. File: {path}:{line}'
+
+Write the FULL comparison table to .gsd-t/contracts/design-contract.md
+under a '## Verification Status' section.
+
+Any ❌ DEVIATION → also append to .gsd-t/qa-issues.md with severity HIGH
+and tag [VISUAL]:
+| {date} | gsd-t-execute | Step 5.25 | opus | {duration} | HIGH | [VISUAL] {description} |
+
+## Step 6: Verdict
+
+Count results: '{MATCH_COUNT}/{TOTAL} elements match at {breakpoints} breakpoints'
+
+VERDICT:
+- ALL rows ✅ MATCH → DESIGN VERIFIED
+- ANY rows ❌ DEVIATION → DESIGN DEVIATIONS FOUND ({count} deviations)
+
+Write verdict to .gsd-t/contracts/design-contract.md Verification Status section.
+
+Report back:
+- Verdict: DESIGN VERIFIED | DESIGN DEVIATIONS FOUND
+- Match count: {N}/{total}
+- Breakpoints verified: {list}
+- Deviations: {count with summary of each}
+- Comparison table: {the full table}"
+```
+
+After subagent returns — run via Bash:
+`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && TOK_END=${CLAUDE_CONTEXT_TOKENS_USED:-0} && DURATION=$((T_END-T_START))`
+Compute tokens and compaction:
+- No compaction (TOK_END >= TOK_START): `TOKENS=$((TOK_END-TOK_START))`, COMPACTED=null
+- Compaction detected (TOK_END < TOK_START): `TOKENS=$(((TOK_MAX-TOK_START)+TOK_END))`, COMPACTED=$DT_END
+Append to `.gsd-t/token-log.md`:
+`| {DT_START} | {DT_END} | gsd-t-execute | Design Verify | opus | {DURATION}s | {VERDICT} — {MATCH}/{TOTAL} elements | {TOKENS} | {COMPACTED} | | | {CTX_PCT} |`
+
+**Artifact Gate (MANDATORY):**
+After the Design Verification Agent returns, check `.gsd-t/contracts/design-contract.md`:
+1. Read the file — does it contain a `## Verification Status` section?
+2. Does that section contain a comparison table with rows?
+3. If EITHER is missing → the verification agent failed its job. Log:
+   `[failure] Design Verification Agent did not produce comparison table — re-spawning`
+   Re-spawn the agent (1 retry). If it fails again, log to `.gsd-t/deferred-items.md`.
+
+**If VERDICT is DESIGN DEVIATIONS FOUND:**
+1. Fix all deviations (spawn a fix subagent, model: sonnet, with the deviation list)
+2. Re-spawn the Design Verification Agent to re-verify (max 2 fix-and-verify cycles)
+3. If deviations persist after 2 cycles, log to `.gsd-t/deferred-items.md` and present to user
+
+**If VERDICT is DESIGN VERIFIED:** Proceed to Red Team.
+
 ## Step 5.5: Red Team — Adversarial QA (MANDATORY)
 
 After all domain tasks pass their tests, spawn an adversarial Red Team agent. This agent's sole purpose is to BREAK the code that was just built. It operates with inverted incentives — its success is measured by bugs found, not tests passed.

package/commands/gsd-t-help.md

@@ -60,6 +60,7 @@ UTILITIES                                                              Manual
   audit               Harness self-audit — analyze cost/benefit of enforcement components
   promote-debt        Convert techdebt items to milestones
   populate            Auto-populate docs from existing codebase
+  design-decompose    Decompose design into element/widget/page contracts
   log                 Sync progress Decision Log with recent git activity
   version-update      Update GSD-T package to latest version
   version-update-all  Update GSD-T package + all registered projects
@@ -261,7 +262,7 @@ Use these when user asks for help on a specific command:
 - **Note (M22)**: Task-level fresh dispatch (one subagent per task, ~10-20% context each). Team mode uses worktree isolation (`isolation: "worktree"`) — zero file conflicts. Adaptive replanning between domain completions.
 - **Note (M26)**: Active rule injection — evaluates declarative rules from rules.jsonl before dispatching each domain's tasks. Fires matching rules as warnings in subagent prompts.
 - **Note (M29)**: Stack Rules Engine — auto-detects project tech stack from manifest files and injects mandatory best-practice rules into each task subagent prompt. Universal rules (`_security.md`, `_auth.md`) always apply; stack-specific rules layer on top. Violations are task failures (same weight as contract violations).
-- **Note (M33)**: Design-to-code — activated when design contract, design tokens, Figma config, or Figma MCP in settings.json is detected. Injects pixel-perfect implementation rules: design token extraction, stack capability evaluation, component decomposition. Step 7 (Visual Design Verification) is MANDATORY — renders each screen in a real browser, screenshots at mobile/tablet/desktop, compares pixel-by-pixel against the Figma design via MCP `get_screenshot`. Visual deviations block task completion. Also triggers from Figma MCP being configured in `~/.claude/settings.json`.
+- **Note (M33)**: Design-to-code — activated when design contract, design tokens, Figma config, or Figma MCP in settings.json is detected. Injects pixel-perfect implementation rules: design token extraction, stack capability evaluation, component decomposition. Step 5.25 spawns a **dedicated Design Verification Agent** (model: opus) after QA passes — opens a browser with both the built frontend AND the original design side-by-side, produces a 30+ row structured comparison table, and enforces an artifact gate (missing table = re-spawn). Coding agents code; the verification agent verifies. Visual deviations block completion. Only fires when `.gsd-t/contracts/design-contract.md` exists.
 
 ### test-sync
 - **Summary**: Keep tests aligned with code changes
@@ -382,6 +383,13 @@ Use these when user asks for help on a specific command:
 - **Updates**: `docs/requirements.md`, `docs/architecture.md`, `docs/workflows.md`, `docs/infrastructure.md`, `.gsd-t/progress.md`
 - **Use when**: You have an existing codebase and want to fill docs with real findings instead of placeholders
 
+### design-decompose
+- **Summary**: Decompose a design (Figma/image/prototype) into a hierarchy of element → widget → page contracts
+- **Auto-invoked**: No
+- **Creates**: `.gsd-t/contracts/design/elements/*.contract.md`, `.gsd-t/contracts/design/widgets/*.contract.md`, `.gsd-t/contracts/design/pages/*.contract.md`, `.gsd-t/contracts/design/INDEX.md`
+- **Use when**: Starting a design-to-code project with multiple pages/reusable components, or retrofitting a flat design-contract.md
+- **Precedence rule**: element > widget > page. Widgets and pages cannot override element visual spec.
+
 ### log
 - **Summary**: Sync progress.md Decision Log with recent git activity
 - **Auto-invoked**: No

package/commands/gsd-t-quick.md

@@ -239,6 +239,46 @@ After all scripted tests pass:
 4. If Playwright MCP is not available: skip this section silently
 Note: Exploratory findings do NOT count against the scripted test pass/fail ratio.
 
+## Step 5.25: Design Verification Agent (MANDATORY when design contract exists)
+
+After tests pass, check if `.gsd-t/contracts/design-contract.md` exists. If it does NOT, skip to Step 5.5.
+
+If it DOES exist and this task involved UI changes — spawn the Design Verification Agent. This agent's ONLY job is to open a browser, compare the built frontend against the original design, and produce a structured comparison table. It writes NO feature code.
+
+⚙ [{model}] Design Verification → visual comparison of built frontend vs design
+
+**OBSERVABILITY LOGGING (MANDATORY):**
+Before spawning — run via Bash:
+`T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M") && TOK_START=${CLAUDE_CONTEXT_TOKENS_USED:-0} && TOK_MAX=${CLAUDE_CONTEXT_TOKENS_MAX:-200000}`
+
+```
+Task subagent (general-purpose, model: opus):
+"You are the Design Verification Agent. Your ONLY job is to visually compare
+the built frontend against the original design and produce a structured
+comparison table. You write ZERO feature code.
+
+FAIL-BY-DEFAULT: Every visual element starts as UNVERIFIED. Prove each matches.
+
+1. Read .gsd-t/contracts/design-contract.md for design source reference
+2. Get design reference (Figma MCP screenshot, or design images from contract)
+3. Start dev server, open the built frontend in browser (Claude Preview/Chrome MCP/Playwright)
+4. Open the original design reference in a second browser view
+5. Build element inventory (30+ elements for a full page): every chart, label,
+   icon, heading, card, button, spacing, color — each a separate row
+6. Produce structured comparison table:
+   | # | Section | Element | Design (specific) | Implementation (specific) | Verdict |
+   Only valid verdicts: ✅ MATCH or ❌ DEVIATION (never 'appears to match')
+7. Write results to .gsd-t/contracts/design-contract.md under '## Verification Status'
+8. Any ❌ → append to .gsd-t/qa-issues.md with [VISUAL] tag
+9. Report: DESIGN VERIFIED | DESIGN DEVIATIONS FOUND ({count})"
+```
+
+After subagent returns — run observability Bash and append to token-log.md.
+
+**Artifact Gate:** Read `.gsd-t/contracts/design-contract.md` — if no `## Verification Status` section with a comparison table exists, re-spawn (1 retry).
+
+**If deviations found:** Fix them (max 2 cycles), re-verify. If persistent, log to `.gsd-t/deferred-items.md`.
+
 ## Step 5.5: Red Team — Adversarial QA (MANDATORY)
 
 After tests pass, spawn an adversarial Red Team agent. This agent's sole purpose is to BREAK the code that was just changed. Its success is measured by bugs found, not tests passed.

package/commands/gsd.md

@@ -65,7 +65,8 @@ When the request involves UI implementation from a design (Figma, screenshots, m
 - **If a milestone exists but no domains** → route to `partition` (creates design contract in Step 3.6)
 - **If domains exist but no tasks** → route to `plan`
 - **If tasks exist** → route to `execute` (design-to-code stack rule will inject)
-- The design-to-code stack rule activates automatically when `.gsd-t/contracts/design-contract.md` exists or Figma MCP is configured — but the **partition step must run first** to create the design contract
+- The design-to-code stack rule activates automatically when `.gsd-t/contracts/design-contract.md` OR `.gsd-t/contracts/design/` exists, or Figma MCP is configured — but the **partition step must run first** to create the design contract
+- **For projects with multiple pages or reusable components** (charts, widgets, design system): route to `design-decompose` BEFORE partition to create the hierarchical contract tree (elements → widgets → pages). Single-page/one-off designs can use flat `design-contract.md` created during partition instead.
 
 ## Step 3: Confirm and Execute
 

package/docs/GSD-T-README.md

@@ -90,6 +90,7 @@ GSD-T reads all state files and tells you exactly where you left off.
 | `/user:gsd-t-gap-analysis` | Requirements gap analysis — spec vs. existing code | Manual |
 | `/user:gsd-t-promote-debt` | Convert techdebt items to milestones | Manual |
 | `/user:gsd-t-populate` | Auto-populate docs from existing codebase | Manual |
+| `/user:gsd-t-design-decompose` | Decompose design into element/widget/page contracts | Manual |
 
 ### Milestone Workflow
 
@@ -156,7 +157,9 @@ GSD-T reads all state files and tells you exactly where you left off.
 │                                              │         └──────┐             │
 │                                              │                ▼             │
 │                                              │    ┌───────────────────┐     │
-│                                              │    │  QA + Red Team    │     │
+│                                              │    │  QA + Design      │     │
+│                                              │    │  Verification +   │     │
+│                                              │    │  Red Team         │     │
 │                                              │    │ (after each phase │     │
 │                                              │    │  that writes code)│     │
 │                                              │    └───────────────────┘     │

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.56.15",
+  "version": "2.58.10",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 51 slash commands with headless CI/CD mode, graph-powered code analysis, real-time agent dashboard, execution intelligence, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/templates/CLAUDE-global.md

@@ -63,6 +63,7 @@ PROJECT or FEATURE or SCAN
 | `/user:gsd-t-health` | Validate .gsd-t/ structure, optionally repair |
 | `/user:gsd-t-pause` | Save exact position for reliable resume |
 | `/user:gsd-t-populate` | Auto-populate docs from existing codebase |
+| `/user:gsd-t-design-decompose` | Decompose design into element/widget/page contracts |
 | `/user:gsd-t-log` | Sync progress Decision Log with recent git activity |
 | `/user:gsd-t-resume` | Restore context, continue |
 | `/user:gsd-t-version-update` | Update GSD-T to latest version |
@@ -308,14 +309,36 @@ Report format: 'Unit: X/Y pass | E2E: X/Y pass (or N/A if no config) | Contract:
 
 **QA Calibration Feedback Loop** — If `bin/qa-calibrator.js` exists in the project, the system tracks QA miss-rates (bugs found by Red Team that QA missed) and automatically injects targeted guidance into future QA prompts. Weak-spot categories (error paths, boundary inputs, state transitions) are detected from miss patterns and injected as a preamble before the QA subagent runs. Projects without `qa-miss-log.jsonl` data behave identically to baseline — calibration is fully opt-in and backward compatible.
 
+## Design Verification Agent (Mandatory when design contract exists)
+
+After QA passes, if `.gsd-t/contracts/design-contract.md` exists, a **dedicated Design Verification Agent** is spawned. This agent's ONLY job is to open a browser, compare the built frontend against the original design, and produce a structured element-by-element comparison table. It writes ZERO feature code.
+
+**Why a dedicated agent?** Coding agents consistently skip visual verification — even with detailed instructions — because their incentive is to finish building, not to audit. Separating the verifier from the builder ensures the verification actually happens.
+
+**Design Verification method by command:**
+- `execute` → spawns Design Verification Agent after QA passes (Step 5.25)
+- `quick` → spawns Design Verification Agent after tests pass (Step 5.25)
+- `integrate`, `wave` → Design Verification runs within the execute phase per the rules above
+- Commands without UI work → skipped automatically (no design contract = no verification)
+
+**Key rules:**
+- **FAIL-BY-DEFAULT**: Every visual element starts as UNVERIFIED. Must prove each matches.
+- **Structured comparison table**: 30+ rows minimum for a full page. Each element gets specific design values vs. specific implementation values and a MATCH or DEVIATION verdict.
+- **No vague verdicts**: "Looks close" and "appears to match" are not valid. Only �� MATCH or ❌ DEVIATION with specific values.
+- **Side-by-side browser sessions**: Opens both the built frontend AND the original design (Figma page, design image, or MCP screenshot) for direct visual comparison.
+- **Artifact gate**: Orchestrator checks that `design-contract.md` contains a `## Verification Status` section with a populated comparison table. Missing artifact = re-spawn (1 retry).
+- **Fix cycle**: Deviations are fixed (up to 2 cycles) and re-verified before proceeding.
+
+**Design Verification FAIL blocks phase completion.** Deviations must be fixed or logged to `.gsd-t/deferred-items.md`.
+
 ## Red Team — Adversarial QA (Mandatory)
 
-After QA passes, every code-producing command spawns a **Red Team agent** — an adversarial subagent whose success is measured by bugs found, not tests passed. This inverts the incentive structure: the Red Team's drive toward "task complete" means digging deeper and finding more bugs, not rubber-stamping.
+After QA and Design Verification pass, every code-producing command spawns a **Red Team agent** — an adversarial subagent whose success is measured by bugs found, not tests passed. This inverts the incentive structure: the Red Team's drive toward "task complete" means digging deeper and finding more bugs, not rubber-stamping.
 
 **Red Team method by command:**
-- `execute` → spawns Red Team after all domain tasks pass (Step 5.5)
+- `execute` → spawns Red Team after Design Verification passes (Step 5.5)
 - `integrate` → spawns Red Team after integration tests pass (Step 7.5)
-- `quick` → spawns Red Team after Test & Verify passes (Step 5.5)
+- `quick` → spawns Red Team after Design Verification passes (Step 5.5)
 - `debug` → spawns Red Team after fix verification passes (Step 5.3)
 - `wave` → each phase agent handles Red Team per the rules above
 
@@ -617,7 +640,7 @@ GSD-T auto-detects project tech stack at subagent spawn time and injects mandato
 
 **Stack-specific rules**: Injected only when the matching stack is detected (e.g., `react.md` when `"react"` is in `package.json`).
 
-**Design-to-code**: Activated when `.gsd-t/contracts/design-contract.md`, `design-tokens.json`, `design-tokens/`, `.figmarc`, or `figma.config.json` exists, OR when Figma MCP is configured in `~/.claude/settings.json`. Auto-bootstrapped during partition when Figma URLs or design references are detected in requirements. Enforces pixel-perfect frontend implementation from designs with: Figma MCP auto-detection, design token extraction protocol, stack capability evaluation (recommends alternatives if stack can't achieve the design), component decomposition, responsive breakpoint strategy, and a mandatory visual verification loop — every implemented screen must be rendered in a real browser, screenshotted at mobile/tablet/desktop breakpoints, and compared pixel-by-pixel against the Figma design. Visual deviations block task completion.
+**Design-to-code**: Activated when `.gsd-t/contracts/design-contract.md` (flat), `.gsd-t/contracts/design/` (hierarchical element/widget/page contracts — bootstrap via `/user:gsd-t-design-decompose`), `design-tokens.json`, `design-tokens/`, `.figmarc`, or `figma.config.json` exists, OR when Figma MCP is configured in `~/.claude/settings.json`. Auto-bootstrapped during partition when Figma URLs or design references are detected in requirements. Enforces pixel-perfect frontend implementation from designs with: Figma MCP auto-detection, design token extraction protocol, stack capability evaluation (recommends alternatives if stack can't achieve the design), component decomposition, responsive breakpoint strategy, and a mandatory visual verification loop — every implemented screen must be rendered in a real browser, screenshotted at mobile/tablet/desktop breakpoints, and compared pixel-by-pixel against the Figma design. Visual deviations block task completion.
 
 **Enforcement**: Stack rule violations have the same weight as contract violations — they are task failures, not warnings.
 

package/templates/element-contract.md

@@ -0,0 +1,125 @@
+# Element Contract: {element-name}
+
+Atomic visual unit. One contract per visual variant (e.g., `chart-bar-stacked-horizontal` and `chart-bar-stacked-vertical` are separate contracts). Widgets and pages reference element contracts by name; they CANNOT override the visual spec.
+
+## Metadata
+
+| Field          | Value                                                     |
+|----------------|-----------------------------------------------------------|
+| element        | {e.g., chart-bar-stacked-horizontal}                      |
+| category       | {chart / legend / axis / card / table / control / layout} |
+| variant_of     | {base element name, or `null` if base}                    |
+| version        | {1.0}                                                     |
+| extends        | {[axis-x-numeric, axis-y-categorical] — or []}            |
+| design_source  | {Figma node URL or design file path + node id}            |
+| extracted_via  | {Figma MCP / Visual Analysis / Design Tokens}             |
+| extracted_date | {YYYY-MM-DD}                                              |
+
+## Purpose
+
+{One sentence — what this element is and when to use it. E.g., "Horizontal stacked bar chart for displaying part-to-whole comparisons across categories, with segment labels inside when segment width ≥40px."}
+
+## Visual Spec
+
+| Property      | Value                                                 |
+|---------------|-------------------------------------------------------|
+| {dimension_1} | {exact value, referencing design tokens if available} |
+| {dimension_2} | {exact value}                                         |
+
+*List every measurable visual property: dimensions, spacing, radii, borders, shadows, opacity. Reference design tokens rather than raw values where possible (`tokens.spacing.4` instead of `16px`).*
+
+## Labels / Text (if applicable)
+
+| Property      | Value                                                              |
+|---------------|--------------------------------------------------------------------|
+| font_family   | {tokens.font.family.sans}                                          |
+| font_size     | {tokens.font.size.sm}                                              |
+| font_weight   | {tokens.font.weight.medium}                                        |
+| color         | {tokens.color.text.primary}                                        |
+| position      | {inside-segment-centered / above-bar / below-bar / left / right}   |
+| visibility    | {always / conditional: {rule, e.g., `hide if segment width <40px`}} |
+| alignment     | {left / center / right / start / end}                              |
+| truncation    | {none / ellipsis / tooltip-on-truncate}                            |
+
+## Colors
+
+| Usage       | Token                                |
+|-------------|--------------------------------------|
+| {fill}      | {tokens.color.chart.sequence[0..n]}  |
+| {stroke}    | {tokens.color.chart.border}          |
+| {text}      | {tokens.color.text.onPrimary}        |
+| {hover}     | {tokens.color.chart.hover.overlay}   |
+
+## States
+
+| State       | Visual Change                                                      |
+|-------------|--------------------------------------------------------------------|
+| default     | {base appearance}                                                  |
+| hover       | {e.g., segment opacity 1.0, siblings 0.6, cursor: pointer}         |
+| active      | {e.g., border 2px tokens.color.accent}                             |
+| disabled    | {e.g., opacity 0.4, cursor: not-allowed}                           |
+| focus       | {e.g., outline 2px tokens.color.focus, offset 2px}                 |
+| loading     | {e.g., skeleton shimmer}                                           |
+| empty       | {e.g., placeholder icon + "No data" text}                          |
+
+## Interactions
+
+| Event       | Behavior                                                           |
+|-------------|--------------------------------------------------------------------|
+| hover       | {e.g., show tooltip with {category, series, value, percent}}       |
+| click       | {e.g., emit `onSegmentClick({category, series, value})`}           |
+| keyboard    | {e.g., Tab focuses, Enter activates, Arrow keys navigate segments} |
+
+## Data Binding
+
+**Input shape:**
+```typescript
+{
+  // Define the minimum data contract required to render this element
+  categories: string[];
+  series: { name: string; values: number[]; color?: string }[];
+}
+```
+
+**Invariants:**
+- {e.g., All series arrays MUST have length === categories.length}
+- {e.g., Values MUST be non-negative for stacked variants}
+
+## Responsive Behavior
+
+| Breakpoint | Adaptation                                                    |
+|------------|---------------------------------------------------------------|
+| mobile     | {e.g., labels hidden, tap for tooltip}                        |
+| tablet     | {e.g., reduced label font-size to tokens.font.size.xs}        |
+| desktop    | {full labels as specified}                                    |
+
+## Accessibility
+
+- **Role**: {e.g., `img` with descriptive aria-label, or `figure` with `<figcaption>`}
+- **Keyboard**: {e.g., focusable, arrow-key navigation between segments}
+- **Screen reader**: {e.g., announces category, series, value on focus}
+- **Contrast**: {label text contrast ratio ≥4.5:1 against segment fill}
+
+## Implementation Notes
+
+- **Library**: {e.g., Plotly.js / Recharts / D3 / native SVG}
+- **Component path**: {src/components/charts/BarStackedHorizontal.vue}
+- **Dependencies**: {list of required packages}
+
+## Verification Checklist
+
+Design Verification Agent uses this list. Every item must resolve to ✅ MATCH or ❌ DEVIATION (with specific values) — never "looks close" or "appears to match".
+
+- [ ] {Visual spec property 1 matches design}
+- [ ] {Visual spec property 2 matches design}
+- [ ] Label position/font/color match design
+- [ ] Color sequence matches design tokens
+- [ ] Hover state changes as specified
+- [ ] Focus state visible and correct
+- [ ] Responsive adaptations fire at correct breakpoints
+- [ ] Accessibility attributes present and correct
+
+## Examples
+
+**Used by widgets:** {list widget contracts that reference this element}
+**Used by pages:** {list page contracts that reference this element directly}

package/templates/page-contract.md

@@ -0,0 +1,143 @@
+# Page Contract: {page-name}
+
+Top-level assembly of widgets + global layout + routing + data loading. Pages POSITION widgets in a layout grid; they cannot redefine widget internals or element visual specs.
+
+## Metadata
+
+| Field          | Value                                           |
+|----------------|-------------------------------------------------|
+| page           | {e.g., dashboard-overview}                      |
+| route          | {e.g., /dashboard or /dashboard/overview}       |
+| version        | {1.0}                                           |
+| design_source  | {Figma page URL or image reference}             |
+| extracted_date | {YYYY-MM-DD}                                    |
+
+## Purpose
+
+{One sentence — what this page is for and who uses it. E.g., "Primary landing page after login. Displays KPIs, revenue trends, and recent activity for executives scanning performance at-a-glance."}
+
+## Widgets Used
+
+| Position in Grid                 | Widget Contract                 | Notes                        |
+|----------------------------------|---------------------------------|------------------------------|
+| header                           | page-header-widget              | {sticky}                     |
+| sidebar                          | nav-sidebar-widget              | {collapsible at <1024px}     |
+| grid[row=1, cols=1-4]            | stat-strip-widget               | {4 KPI tiles}                |
+| grid[row=2, col=1-2]             | revenue-breakdown-widget        | {spans 2 columns}            |
+| grid[row=2, col=3-4]             | user-growth-widget              | {spans 2 columns}            |
+| grid[row=3, col=1-4]             | recent-activity-table-widget    | {full width}                 |
+
+## Layout
+
+```
+┌──────────────────────────────────────────────────────┐
+│                  page-header-widget                  │
+├──────────┬───────────────────────────────────────────┤
+│          │  stat-strip-widget                        │
+│   nav-   ├─────────────────────┬─────────────────────┤
+│  sidebar │  revenue-breakdown  │   user-growth       │
+│  -widget │                     │                     │
+│          ├─────────────────────┴─────────────────────┤
+│          │       recent-activity-table-widget        │
+└──────────┴───────────────────────────────────────────┘
+```
+
+| Property            | Value                                          |
+|---------------------|------------------------------------------------|
+| layout_type         | {grid / flex / fixed-sidebar+fluid-content}    |
+| grid_columns        | {4}                                            |
+| grid_column_gap     | {tokens.spacing.6}                             |
+| grid_row_gap        | {tokens.spacing.6}                             |
+| page_padding        | {tokens.spacing.8}                             |
+| max_content_width   | {1440px}                                       |
+| sidebar_width       | {240px (expanded) / 64px (collapsed)}          |
+| header_height       | {64px}                                         |
+| background          | {tokens.color.bg.page}                         |
+
+## Data Loading
+
+**Page-level data requirements:**
+```typescript
+{
+  stats: Stat[];
+  revenue: RevenueData[];
+  userGrowth: GrowthData[];
+  activity: ActivityRow[];
+}
+```
+
+**Loading strategy:**
+- {e.g., Single API call to `/api/dashboard/overview` on mount}
+- {e.g., Parallel fetches per widget; widgets manage own loading states}
+- {e.g., Server-side rendered with incremental hydration}
+
+## Routing & Navigation
+
+- **Route**: {/dashboard/overview}
+- **Guards**: {requires authentication, role: user|admin}
+- **Breadcrumbs**: {Home > Dashboard > Overview}
+- **Nav active state**: {highlights "Dashboard" in nav-sidebar}
+
+## Global States
+
+| State            | Page Behavior                                           |
+|------------------|---------------------------------------------------------|
+| unauthenticated  | Redirect to /login                                      |
+| page_loading     | Skeleton grid with widget placeholders                  |
+| page_error       | Full-page error with retry button                       |
+| partial_error    | Individual widgets show own error states; page persists |
+
+## Responsive Behavior
+
+| Breakpoint | Adaptation                                                     |
+|------------|----------------------------------------------------------------|
+| mobile     | Sidebar becomes drawer; grid collapses to 1 column; stats stack vertically |
+| tablet     | Sidebar collapses to icon-only; grid becomes 2 columns         |
+| desktop    | Full layout as specified                                       |
+
+## Interactions
+
+- {Sidebar toggle persists across sessions (localStorage)}
+- {Widget filter changes do NOT affect other widgets unless explicitly wired}
+- {Clicking KPI tile navigates to detail page}
+
+## Performance Budget
+
+| Metric             | Target                                          |
+|--------------------|-------------------------------------------------|
+| First Contentful Paint | {<1.5s on 4G}                               |
+| Time to Interactive    | {<3.0s on 4G}                               |
+| JS bundle size         | {<200KB gzipped for this route}             |
+
+## Accessibility
+
+- **Landmarks**: `<header>`, `<nav>`, `<main>`, per-widget `<section role="region">`
+- **Skip link**: "Skip to main content" at top, focuses `<main>` on activation
+- **Keyboard order**: header → sidebar → widgets in visual reading order
+- **Page title**: Set via `<title>` per route
+
+## Implementation Notes
+
+- **Component path**: {src/pages/DashboardOverview.vue or src/routes/dashboard/overview.tsx}
+- **Composes**: {list widget imports}
+- **Router integration**: {vue-router / react-router / next.js app dir}
+- **Data fetching**: {composable / hook / server component}
+
+## Verification Checklist
+
+Page-level verification runs AFTER all widgets pass their own verification. Page verification only checks assembly — widget and element internals are out of scope.
+
+- [ ] All widgets present in correct grid positions
+- [ ] Layout dimensions (gaps, padding, max-width) match design
+- [ ] Header / sidebar / main regions correctly landmarked
+- [ ] Sidebar collapse/expand behavior works
+- [ ] Responsive breakpoints rearrange layout as specified
+- [ ] Data loading strategy produces correct widget inputs
+- [ ] Route guards enforce authentication/roles
+- [ ] Performance budget met (measure with Lighthouse)
+- [ ] Keyboard navigation follows visual reading order
+- [ ] Skip-link and page title present
+
+## Composes Elements (direct, not via widgets)
+
+{List any element contracts referenced directly by the page (rare — usually everything goes through widgets). E.g., `button-primary` for a floating action button.}

package/templates/stacks/design-to-code.md

@@ -6,6 +6,35 @@ These rules apply when implementing a visual design as frontend code. The design
 
 ---
 
+## 0. Contract Structure — Flat or Hierarchical
+
+Two contract layouts are supported. Pick the one that fits the project scope:
+
+**Flat** (single file: `.gsd-t/contracts/design-contract.md`)
+- Use when: single page, ≤10 distinct elements, nothing reusable across pages
+- Pros: fast to set up; fine for a landing page or one-off screen
+- Cons: no reuse; visual spec repeats; drift between instances is easy
+
+**Hierarchical** (directory: `.gsd-t/contracts/design/{elements,widgets,pages}/`)
+- Use when: multiple pages, reusable components (charts, cards, legends), design system in play
+- Pros: element contracts are the single source of truth for visual spec — widgets and pages SELECT and POSITION but cannot override. Drift is structurally impossible.
+- Cons: more contracts to write upfront (elements: ~10-20, widgets: ~5-10, pages: N)
+- Bootstrap via: `/user:gsd-t-design-decompose {Figma URL or image path}`
+- Templates: `templates/element-contract.md`, `templates/widget-contract.md`, `templates/page-contract.md`
+
+**Precedence rule (hierarchical only)**:
+```
+element contract  >  widget contract  >  page contract
+```
+A widget that uses `chart-donut` cannot change `chart-donut`'s bar-gap, colors, or label positioning. If customization is needed, create a new element variant (`chart-donut-compact.contract.md`) instead.
+
+**Detection at execute-time**:
+- If `.gsd-t/contracts/design/` exists → hierarchical mode, verify elements first, then widgets, then pages
+- Else if `.gsd-t/contracts/design-contract.md` exists → flat mode
+- Else → bootstrap flat contract during partition
+
+---
+
 ## 1. Design Source Setup
 
 ```
@@ -433,125 +462,25 @@ MANDATORY:
 
 ---
 
-## 15. Visual Verification Loop
+## 15. Visual Verification
 
-**FAIL-BY-DEFAULT RULE**: Every visual element starts as UNVERIFIED. You must prove each one matches — not assume it does. "Looks close" is not a verdict. "Appears to match" is not a verdict. The only valid verdicts are MATCH (with proof) or DEVIATION (with specifics). If you catch yourself writing "looks correct" or "appears right" without element-level proof, you are doing it wrong.
+**Visual verification is handled by a dedicated Design Verification Agent**, spawned automatically by `gsd-t-execute` (Step 5.25) after all domain tasks complete. The verification agent's ONLY job is to open a browser, compare the built frontend against the original design, and produce a structured element-by-element comparison table.
+
+**Your job as the coding agent**: Write precise code from the design contract tokens. Every CSS value must trace to a design contract entry. Use exact hex colors, exact spacing values, exact typography. The verification agent will open a browser and prove whether your code matches.
 
 ```
-MANDATORY:
-  ├── After implementing any design component, you MUST verify it visually.
-  │   Skipping this step is a TASK FAILURE — not optional, not "if tools available".
-  │
-  ├── Step 1: GET THE FIGMA REFERENCE
-  │     If Figma MCP available → call get_screenshot with nodeId + fileKey
-  │     If no MCP → use design image/screenshot from the design contract
-  │     You MUST have a reference image before proceeding
+SEPARATION OF CONCERNS:
+  ├── CODING AGENT (you — Sections 1-14 above):
+  │     Extract tokens → write precise CSS → trace every value to design contract
+  │     Do NOT open a browser or attempt visual comparison yourself
   │
-  ├── Step 2: BUILD THE ELEMENT INVENTORY
-  │     Before ANY comparison, enumerate every distinct visual element in the
-  │     design. Walk the design top-to-bottom, left-to-right. For each section:
-  │       - Section title text and icon
-  │       - Every chart/visualization (type, orientation, labels, legend, series count)
-  │       - Every data table (columns, row structure, sort indicators)
-  │       - Every KPI/stat card (value, label, icon, trend indicator)
-  │       - Every button, toggle, tab, dropdown
-  │       - Every text element (headings, body, captions, labels)
-  │       - Every spacing boundary (section gaps, card padding, element margins)
-  │       - Every color usage (backgrounds, borders, text, chart fills)
-  │     Write each element as a row in the comparison table (Step 4).
-  │     If the inventory has fewer than 20 elements for a full page, you missed items.
-  │
-  ├── Step 3: OPEN SIDE-BY-SIDE BROWSER SESSIONS
-  │     Start the dev server (npm run dev, etc.)
-  │     Open TWO browser views simultaneously for direct visual comparison:
-  │
-  │     VIEW 1 — BUILT FRONTEND:
-  │       Open the implemented page using Claude Preview, Chrome MCP, or Playwright
-  │       Navigate to the exact route/component being verified
-  │       You MUST see real rendered output — not just read the code
-  │
-  │     VIEW 2 — ORIGINAL DESIGN REFERENCE:
-  │       If Figma URL available → open the Figma page in a browser tab/window
-  │         Use the Figma URL from the design contract Source Reference field
-  │         Navigate to the specific frame/component being compared
-  │       If design image file → open the image in a browser tab/window
-  │         Use: file://{absolute-path-to-image} or render in an HTML page
-  │       If Figma MCP screenshot was captured → open that screenshot image
-  │
-  │     COMPARISON APPROACH:
-  │       With both views open, walk through each component/section:
-  │         - Position views side-by-side (or switch between tabs)
-  │         - Compare each element visually at the same zoom level
-  │         - Screenshot BOTH views at matching viewport sizes
-  │       Capture implementation screenshots at each target breakpoint:
-  │         Mobile (375px), Tablet (768px), Desktop (1280px) minimum
-  │       Each breakpoint is a separate screenshot pair (design + implementation)
-  │
-  ├── Step 4: STRUCTURED ELEMENT-BY-ELEMENT COMPARISON (MANDATORY FORMAT)
-  │     You MUST produce a comparison table with this exact structure.
-  │     Every row from the inventory gets its own row. No summarizing, no grouping,
-  │     no "appears to match" prose. Each element gets an individual verdict.
-  │
-  │     | # | Section | Element | Design (specific) | Implementation (specific) | Verdict |
-  │     |---|---------|---------|-------------------|--------------------------|---------|
-  │     | 1 | Summary | Chart type | Horizontal stacked bar | Vertical grouped bar | ❌ DEVIATION |
-  │     | 2 | Summary | Chart colors | #4285F4, #34A853, #FBBC04 | #4285F4, #34A853, #FBBC04 | ✅ MATCH |
-  │     | 3 | Summary | Y-axis labels | Tool names, left-aligned | Tool names, left-aligned | ✅ MATCH |
-  │     | 4 | Summary | Bar label placement | Inside bar, white text | Above bar, black text | ❌ DEVIATION |
-  │     | 5 | KPIs | Font size | 32px semibold | 24px regular | ❌ DEVIATION |
-  │     | ... | ... | ... | ... | ... | ... |
-  │
-  │     Rules for the table:
-  │     - "Design" column must have SPECIFIC values (chart type name, hex color,
-  │       pixel size, font weight name) — not vague descriptions
-  │     - "Implementation" column must have SPECIFIC observed values — not assumptions
-  │       from reading code. You must LOOK at the rendered screenshot.
-  │     - NEVER write "Appears to match" or "Looks correct" — measure and verify
-  │     - NEVER write "Need to verify" — verify it NOW or mark UNVERIFIED
-  │     - Data visualizations get MULTIPLE rows: chart type, axis orientation,
-  │       axis labels, legend position, bar/line/segment colors, data labels,
-  │       grid lines, tooltip style — each is a separate element
-  │     - If the table has fewer than 30 rows for a full-page comparison,
-  │       you skipped elements. Go back to the inventory.
-  │
-  │     DATA VISUALIZATION CHECKLIST (expand into table rows):
-  │       Chart type: bar/stacked-bar/grouped-bar/horizontal-bar/line/area/donut/pie/scatter
-  │       Chart orientation: horizontal vs vertical
-  │       Axis labels: present, position, font, values
-  │       Axis grid lines: present, style, color
-  │       Legend: position (top/bottom/right/inline), format, colors
-  │       Data labels: inside bars/above bars/on segments, font, color
-  │       Chart colors: exact hex per series/segment
-  │       Bar width/spacing: relative proportions
-  │       Center text (donut/pie): present, value, font
-  │       Tooltip style: if visible in design
-  │
-  ├── Step 5: FIX EVERY DEVIATION
-  │     Fix each ❌ row from the table, one by one
-  │     Trace each fix to the design contract value
-  │     Re-render after each batch of fixes
-  │     Update the table: change ❌ to ✅ only after visual re-verification
-  │     Maximum 3 fix-and-recheck iterations
-  │
-  ├── Step 6: FINAL VERIFICATION
-  │     After fixes, take fresh screenshots at all breakpoints
-  │     Produce a FINAL comparison table — every row must be ✅ MATCH
-  │     Any remaining ❌ → CRITICAL finding in .gsd-t/qa-issues.md
-  │     Task is NOT complete until every row shows ✅ MATCH
-  │     Count: "Verified: {N}/{total} elements match at {breakpoints} breakpoints"
-  │
-  ├── NO BROWSER TOOLS = BLOCKER
-  │     If Claude Preview, Chrome MCP, and Playwright are ALL unavailable:
-  │     This is a CRITICAL blocker, not a warning to log and move on
-  │     The task CANNOT be marked complete without visual verification
-  │     Log to .gsd-t/qa-issues.md with severity CRITICAL
-  │
-  └── Log all verification results in the design contract Verification Status table
+  └── DESIGN VERIFICATION AGENT (Step 5.25 of gsd-t-execute):
+        Open browser → screenshot at breakpoints → build element inventory →
+        produce structured comparison table (30+ rows) → report MATCH/DEVIATION
+        per element → fix deviations → re-verify → artifact gate enforces completion
 ```
 
-**BAD** — A vague comparison table with "Appears to match" and "Looks correct" entries. Leading with "What's Working Well" before identifying deviations. Saying "implementation looks very close to the designs" without element-level proof.
-
-**GOOD** — 45-row structured comparison table where every element has specific design values vs. specific implementation values. 12 deviations identified: wrong chart type (horizontal stacked bar → vertical grouped bar), wrong font size (32px → 24px), missing data labels inside bars, etc. Each fixed individually with re-render verification. Final table: 45/45 ✅ MATCH.
+The verification agent enforces the **FAIL-BY-DEFAULT** rule: every visual element starts as UNVERIFIED. The only valid verdicts are MATCH (with proof) or DEVIATION (with specifics). "Looks close" and "appears to match" are not verdicts. An artifact gate in the orchestrator blocks completion if the comparison table is missing or empty.
 
 ---
 

package/templates/widget-contract.md

@@ -0,0 +1,121 @@
+# Widget Contract: {widget-name}
+
+Composition of elements + data binding + layout. Widgets SELECT and POSITION elements; they cannot redefine element visual specs. If a design needs a variant not covered by an existing element, create a new element contract — do not override from the widget.
+
+## Metadata
+
+| Field          | Value                                           |
+|----------------|-------------------------------------------------|
+| widget         | {e.g., revenue-breakdown-widget}                |
+| version        | {1.0}                                           |
+| design_source  | {Figma node URL or image reference}             |
+| extracted_date | {YYYY-MM-DD}                                    |
+
+## Purpose
+
+{One sentence — what this widget shows and why. E.g., "Displays revenue breakdown by product category with donut chart and accompanying legend-table, used on the dashboard Overview page and the Analytics detail page."}
+
+## Elements Used
+
+| Slot             | Element Contract                        | Rationale                          |
+|------------------|-----------------------------------------|------------------------------------|
+| {chart}          | chart-donut                             | {part-to-whole comparison}         |
+| {legend}         | legend-vertical-right                   | {6+ series, needs vertical space}  |
+| {title}          | heading-h3                              | {widget header}                    |
+| {filter}         | select-dropdown                         | {time-range selector}              |
+
+**Rule**: Each slot references an element contract by name. Widget CANNOT override element visual spec. To customize, create a new element variant.
+
+## Layout
+
+```
+┌──────────────────────────────────────────────┐
+│ {title}                        [{filter}]    │
+├──────────────────────────────────────────────┤
+│              │                               │
+│   {chart}    │      {legend}                 │
+│              │                               │
+└──────────────────────────────────────────────┘
+```
+
+| Property           | Value                                               |
+|--------------------|-----------------------------------------------------|
+| container_width    | {100% of parent / fixed 480px}                      |
+| container_height   | {auto / fixed 320px}                                |
+| padding            | {tokens.spacing.6}                                  |
+| gap                | {tokens.spacing.4}                                  |
+| background         | {tokens.color.surface.card}                         |
+| border             | {1px solid tokens.color.border.subtle}              |
+| border_radius      | {tokens.radius.lg}                                  |
+| shadow             | {tokens.shadow.sm}                                  |
+| chart_area_ratio   | {60% of widget width}                               |
+| legend_area_ratio  | {40% of widget width}                               |
+
+## Data Binding
+
+**Widget input shape:**
+```typescript
+{
+  title: string;
+  timeRange: '7d' | '30d' | '90d' | '1y';
+  data: { category: string; value: number; color?: string }[];
+  onFilterChange?: (range: string) => void;
+}
+```
+
+**Element data mapping:**
+| Element    | Receives                                                         |
+|------------|------------------------------------------------------------------|
+| chart      | `{ categories: data.map(d=>d.category), series: [{name:'Revenue', values: data.map(d=>d.value)}]}` |
+| legend     | `data.map(d => ({label: d.category, value: d.value, color: d.color}))` |
+| filter     | `{ value: timeRange, options: ['7d','30d','90d','1y'], onChange: onFilterChange }` |
+
+## States
+
+| State       | Widget Behavior                                                   |
+|-------------|-------------------------------------------------------------------|
+| loading     | Skeleton shimmer replaces chart and legend                        |
+| empty       | Chart shows empty state; legend hidden                            |
+| error       | Error banner replaces chart; filter stays enabled                 |
+
+## Responsive Behavior
+
+| Breakpoint | Adaptation                                                     |
+|------------|----------------------------------------------------------------|
+| mobile     | Legend drops below chart; chart becomes square                 |
+| tablet     | Legend shrinks to 35% width                                    |
+| desktop    | Spec as defined above                                          |
+
+## Interactions
+
+- {Chart segment hover highlights corresponding legend row}
+- {Legend row click toggles segment visibility}
+- {Filter change triggers data refetch via `onFilterChange`}
+
+## Accessibility
+
+- **Landmark role**: `region` with aria-labelledby pointing to title
+- **Keyboard**: Tab order: filter → chart → legend rows
+- **Announcements**: Data updates announced via `aria-live="polite"`
+
+## Implementation Notes
+
+- **Component path**: {src/widgets/RevenueBreakdownWidget.vue}
+- **Composes**: {list element components the widget imports}
+- **State management**: {local state / zustand store / props only}
+
+## Verification Checklist
+
+Widget-level verification runs AFTER all referenced elements pass their own verification. Widget verification only checks composition — element internals are out of scope.
+
+- [ ] All referenced elements present and correctly slotted
+- [ ] Layout dimensions (width, height, padding, gap) match design
+- [ ] Responsive breakpoints adapt as specified
+- [ ] Data binding produces correct element inputs (spot-check with sample data)
+- [ ] Inter-element interactions fire (hover sync, click propagation)
+- [ ] Loading/empty/error states render correctly
+- [ ] Accessibility landmark and keyboard order correct
+
+## Used By
+
+**Pages**: {list page contracts that reference this widget}