@tekyzinc/gsd-t 2.70.13 → 2.70.14

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [2.70.14] - 2026-04-06
+
+### Changed (design pipeline — hierarchical execution)
+- **Hierarchical Build Order** — `gsd-t-plan` now detects `.gsd-t/contracts/design/INDEX.md` and auto-generates tasks in strict element → widget → page order (Wave 1/2/3). Each element gets its own focused task with only its element contract. Each widget task imports already-built elements. Each page task imports already-built widgets. ONE CONTRACT = ONE TASK.
+- **No Inline Rebuild Rule** — added to `gsd-t-execute`, `gsd-t-quick`, and `design-to-code.md` stack rules. Widget tasks that rebuild element functionality inline (instead of importing the built element component) are a TASK FAILURE. Same for page tasks rebuilding widgets. The hierarchy exists to prevent this.
+- **Contract Is Authoritative** — when the element contract and Figma screenshot disagree, the contract wins. The contract was written from careful design analysis; screenshots are ambiguous at small sizes.
+- **Per-Wave Design Verification Checkpoints** — `gsd-t-execute` now runs design-specific checks at each wave boundary: element contracts after Wave 1, widget assembly after Wave 2, full Figma comparison after Wave 3.
+- **Design Hierarchy Build Rule in subagent prompt** — task subagents now receive explicit instructions for element/widget/page tasks: what to import, what NOT to rebuild, and that contracts are authoritative over screenshots.
+- **Hierarchical Audit Mode** — `gsd-t-design-audit` now detects hierarchical design contracts and audits bottom-up: Level 1 (element chart types), Level 2 (widget assembly — imports vs inline rebuilds), Level 3 (page composition). Pinpoints exactly where a deviation originates instead of flat page-level comparison.
+
+### Why
+The decomposition (gsd-t-design-decompose) creates a perfect hierarchy — 27 elements → 10 widgets → 1 page. But the plan and execute phases didn't follow it. The planner created monolithic "build the page" tasks, and the builder wrote 700-line inline pages ignoring contracts and existing components. All recent enhancements (v2.70.10-12) targeted post-build verification — catching errors after they were made. This change moves enforcement to the build phase: build each element individually (the subagent can't confuse chart types when it only sees one element contract), verify it, then compose. Inside-out execution matches the decomposition structure.
+
 ## [2.70.13] - 2026-04-06
 
 ### Changed (gsd-t-init, gsd-t-init-scan-setup)

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

@@ -23,6 +23,97 @@ If built app target is missing → check if a dev server is running. If not →
 - Factor into Step 3 comparisons: deviations that match library defaults (not Figma) may indicate "used library default instead of design value" — flag as a distinct deviation category
 - If no → proceed as normal
 
+## Step 0.5: Hierarchical Audit Mode (when design hierarchy exists)
+
+Check if `.gsd-t/contracts/design/INDEX.md` exists. If it does NOT, skip to Step 1 (flat audit mode).
+
+**If it EXISTS**: The design was decomposed hierarchically (elements → widgets → pages). Audit bottom-up — this pinpoints exactly WHERE a deviation originates.
+
+### Level 1 — Element Audit
+
+For each element contract in `.gsd-t/contracts/design/elements/`:
+
+1. Read the element contract — extract visual spec (sizes, colors, spacing, chart type, props)
+2. Find the corresponding built component in the project (`src/components/elements/` or equivalent)
+3. If the component DOES NOT EXIST → ❌ CRITICAL: "Element `{name}` has no built component"
+4. If it EXISTS:
+   a. Render the component in isolation (if a dev route or Storybook exists) or locate it within the full page
+   b. Compare chart type: does the contract say `bar-vertical-grouped`? Is the built component actually vertical bars?
+   c. Compare visual spec: dimensions, colors, spacing, typography per the element contract
+   d. Produce a comparison row: `| {element-name} | {contract chart type} | {built chart type} | {verdict} |`
+
+```markdown
+### Element Audit
+
+| # | Element | Contract Type | Built Type | Key Properties | Verdict |
+|---|---------|--------------|------------|----------------|---------|
+| 1 | chart-donut | donut 192px, 32px stroke | donut 192px, 32px stroke | ✅ | ✅ MATCH |
+| 2 | bar-vertical-grouped | vertical bars, 4 groups | horizontal bars | ❌ wrong axis | ❌ CRITICAL |
+| 3 | bar-vertical-single | vertical bars, single color | donut chart | ❌ wrong chart type | ❌ CRITICAL |
+```
+
+**If ANY element has a chart type mismatch → flag CRITICAL immediately.** This is the exact failure mode that caused the BDS rebuild to fail: the element contract says vertical bars, but a donut was built. No amount of widget or page-level auditing can fix a wrong element.
+
+### Level 2 — Widget Assembly Audit
+
+For each widget contract in `.gsd-t/contracts/design/widgets/`:
+
+1. Read the widget contract — extract "Elements Used" list and layout spec
+2. Find the built widget component (`src/components/widgets/` or equivalent)
+3. If the widget DOES NOT EXIST → ❌ CRITICAL: "Widget `{name}` has no built component"
+4. If it EXISTS:
+   a. Check: does the widget IMPORT its element components, or does it rebuild element functionality inline?
+      - Grep the widget file for imports from `elements/` or `components/elements/`
+      - If the widget contains inline chart/card implementations that duplicate element components → ❌ HIGH: "Widget rebuilds `{element}` inline instead of importing"
+   b. Check: does the widget compose the CORRECT elements per the contract?
+      - Contract says "uses chart-donut, legend-vertical-right" — does the widget import both?
+   c. Check layout: spacing between elements, responsive behavior per widget contract
+
+```markdown
+### Widget Assembly Audit
+
+| # | Widget | Elements (contract) | Elements (built) | Imports elements? | Layout match? | Verdict |
+|---|--------|--------------------|--------------------|-------------------|---------------|---------|
+| 1 | donut-chart-card | chart-donut, legend-vertical-right, card-header | chart-donut, legend-vertical-right, card-header | ✅ imports | ✅ | ✅ MATCH |
+| 2 | bar-chart-card | bar-vertical-grouped, card-header, legend-horizontal | HorizontalBarGroup (inline) | ❌ inline rebuild | ❌ | ❌ HIGH |
+```
+
+### Level 3 — Page Composition Audit
+
+For each page contract in `.gsd-t/contracts/design/pages/`:
+
+1. Read the page contract — extract widget list and grid positions
+2. Find the built page component
+3. Check: does the page IMPORT its widget components, or inline everything?
+4. Check: section ordering, grid layout, responsive breakpoints
+
+```markdown
+### Page Composition Audit
+
+| # | Widget (contract) | Widget (built) | Imports widget? | Position match? | Verdict |
+|---|-------------------|----------------|-----------------|-----------------|---------|
+| 1 | filter-bar-widget | FilterBarWidget | ✅ | ✅ | ✅ MATCH |
+| 2 | kpi-strip-widget | (inline stat cards) | ❌ inline rebuild | ✅ | ❌ HIGH |
+```
+
+### Hierarchy Summary
+
+After all three levels:
+
+```markdown
+### Hierarchy Audit Summary
+
+| Level | Total | Match | Deviations | Critical |
+|-------|-------|-------|------------|----------|
+| Elements | 27 | 24 | 3 | 2 (wrong chart type) |
+| Widgets | 10 | 7 | 3 | 0 (3 inline rebuilds) |
+| Pages | 1 | 0 | 1 | 0 (inline widgets) |
+
+**Root cause**: 2 element-level chart type mismatches. Fix elements first — widget and page deviations may resolve automatically once correct elements are imported.
+```
+
+**After the hierarchy audit, continue to Step 1 for the full Figma comparison.** The hierarchy audit identifies structural issues (wrong types, inline rebuilds). The Figma comparison (Steps 1-4) catches visual property deviations (colors, spacing, sizes).
+
 ## Step 1: Map the Figma Design — Node-Level Decomposition
 
 ### 1a. Get the page tree

package/commands/gsd-t-execute.md

@@ -64,6 +64,18 @@ Before choosing solo or team mode, read the `## Wave Execution Groups` section i
 - Execute wave-by-wave: complete all tasks in Wave 1 before starting Wave 2
 - Within each wave, tasks marked as parallel-safe can run concurrently (team mode) or be interleaved (solo mode)
 - At each wave boundary: run the CHECKPOINT — verify contract compliance — before proceeding
+- **Design Hierarchy Checkpoint** (when `.gsd-t/contracts/design/INDEX.md` exists):
+  At each wave boundary for design hierarchy waves (elements → widgets → pages):
+  - **After element wave**: For each built element component, verify it renders and matches
+    its element contract (chart type, dimensions, colors, props). Spot-check in a browser
+    or headless render. Any element that doesn't match its contract → fix before widget wave.
+  - **After widget wave**: For each built widget, verify it imports (not rebuilds) its element
+    components and assembles them per the widget contract layout. Check: does the widget
+    import from src/components/elements/? If it contains inline chart/card implementations
+    that duplicate element components → FAIL the checkpoint, fix before page wave.
+  - **After page wave**: Proceed to full Design Verification Agent (Step 5.25) for Figma comparison.
+  These checkpoints are MANDATORY gates — not advisory. The entire point of hierarchical
+  execution is that each layer is correct before the next layer builds on it.
 - File conflict detection: if two tasks in the same wave list the same file in their `scope.md` ownership, move one to the next wave
 
 **If no wave groups are defined** (older plans): fall back to the `Execution Order` list.
@@ -252,9 +264,24 @@ Execute the task above:
 3. Destructive Action Guard: if the task involves DROP TABLE, schema changes that lose
    data, removing working modules, or replacing architecture patterns → write a
    NEEDS-APPROVAL entry to .gsd-t/deferred-items.md, skip the task, stop here
-4. Implement the task
-5. Verify acceptance criteria are met
-6. Write comprehensive tests (MANDATORY — no feature code without test code):
+4. **Design Hierarchy Build Rule** (if this task references a design contract):
+   - If building an ELEMENT: implement ONLY this element's contract. Use exact values —
+     every dimension, color, font size, spacing must trace to the contract or design tokens.
+     No guessed values. Render in isolation to confirm before finishing.
+   - If building a WIDGET: check src/components/elements/ for already-built element
+     components. IMPORT them — do NOT rebuild element functionality inline. If the widget
+     contract says 'uses chart-donut', import the chart-donut element. Building a second
+     donut implementation inline is a TASK FAILURE.
+   - If building a PAGE: check src/components/widgets/ for already-built widget components.
+     IMPORT them — do NOT rebuild widget functionality inline. The page's job is composition
+     and data wiring, not reimplementing widgets.
+   - **Contract is authoritative**: If the element contract says 'bar-vertical-grouped'
+     (vertical bars), build vertical bars — even if the Figma screenshot looks like it
+     could be horizontal. The contract was written from careful design analysis; the
+     screenshot is ambiguous at small sizes. When in doubt, follow the contract.
+5. Implement the task
+6. Verify acceptance criteria are met
+7. Write comprehensive tests (MANDATORY — no feature code without test code):
    - Unit/integration: happy path + edge cases + error cases for every new/changed function
    - Playwright E2E (if UI/routes/flows changed): new specs for new features, cover
      all modes, form validation, empty/loading/error states, common edge cases
@@ -282,26 +309,26 @@ 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 Note** (when design-to-code stack rule is active):
+8. **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":
+9. 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.
    c. If `playwright.config.*` exists → run `npx playwright test` (full suite, not just affected specs)
    d. If E2E tests fail → fix (up to 2 attempts) before proceeding
    e. Report ALL suite results: "Unit: X/Y pass | E2E: X/Y pass" — never report just one
-9. Run Pre-Commit Gate checklist from CLAUDE.md — update all affected docs BEFORE committing
-10. Commit immediately: feat({domain-name}/task-{task-id}): {description}
-11. Update .gsd-t/progress.md — mark this task complete; prefix the Decision Log entry:
+10. Run Pre-Commit Gate checklist from CLAUDE.md — update all affected docs BEFORE committing
+11. Commit immediately: feat({domain-name}/task-{task-id}): {description}
+12. Update .gsd-t/progress.md — mark this task complete; prefix the Decision Log entry:
     - Completed successfully on first attempt → prefix `[success]`
     - Completed after a fix → prefix `[learning]`
     - Deferred to .gsd-t/deferred-items.md → prefix `[deferred]`
     - Failed after 3 attempts → prefix `[failure]`
-12. Spawn QA subagent (model: sonnet) after completing the task:
+13. Spawn QA subagent (model: sonnet) after completing the task:
     'Run ALL configured test suites — detect and run every one:
      a. Unit tests (vitest/jest/mocha): run the full suite, report pass/fail counts
      b. E2E tests: check for playwright.config.* or cypress.config.* — if found, run the FULL E2E suite
@@ -328,7 +355,7 @@ Execute the task above:
      4. If Playwright MCP is not available: skip this section silently
      Note: Exploratory findings do NOT count against the scripted test pass/fail ratio.'
     If QA fails OR shallow tests are found, fix before proceeding. Append issues to .gsd-t/qa-issues.md.
-12. Write task summary to .gsd-t/domains/{domain-name}/task-{task-id}-summary.md:
+14. Write task summary to .gsd-t/domains/{domain-name}/task-{task-id}-summary.md:
     ## Task {task-id} Summary — {domain-name}
     - **Status**: PASS | FAIL
     - **Files modified**: {list}

package/commands/gsd-t-plan.md

@@ -78,6 +78,84 @@ For each domain, write `.gsd-t/domains/{domain-name}/tasks.md`:
   - {specific testable outcome}
 ```
 
+### Design Hierarchy Task Generation (when hierarchical design contracts exist)
+
+If `.gsd-t/contracts/design/INDEX.md` exists, the design was decomposed into a hierarchy: **elements → widgets → pages**. This hierarchy IS the execution plan. Each level must be built and verified before the next level composes it.
+
+**Detection**: Check for `.gsd-t/contracts/design/INDEX.md`. If it does NOT exist, skip this section entirely — use standard task generation above.
+
+**If it EXISTS**: Read INDEX.md to extract the element, widget, and page contract lists. Then generate tasks in strict build order:
+
+**Wave 1 — Elements (one task per element contract, all parallel-safe):**
+
+Read each contract file in `.gsd-t/contracts/design/elements/`. For each element:
+
+```markdown
+### Task {N}: Build {element-name} element
+- **Files**: src/components/elements/{element-name}.{ext}
+- **Contract refs**: design/elements/{element-name}.contract.md
+- **Dependencies**: NONE
+- **Acceptance criteria**:
+  - Component renders matching ALL visual specs in the element contract (sizes, colors, spacing, typography)
+  - Props/API matches the contract's interface section exactly
+  - Every CSS value traces to a design token or explicit contract value — no guessed/approximated values
+  - Component is importable and reusable (no page-specific logic baked in)
+  - Render the component in isolation (Storybook, test page, or dev route) and visually confirm it matches the contract spec
+```
+
+Elements have no inter-dependencies — all can run in parallel within Wave 1.
+
+**CHECKPOINT after Wave 1**: Verify each built element renders correctly against its contract. Spot-check a sample (or all, if <15 elements) in a browser. Any element that doesn't match its contract gets fixed before Wave 2 starts.
+
+**Wave 2 — Widgets (one task per widget contract):**
+
+Read each contract file in `.gsd-t/contracts/design/widgets/`. For each widget:
+
+```markdown
+### Task {N}: Assemble {widget-name} widget
+- **Files**: src/components/widgets/{widget-name}.{ext}
+- **Contract refs**: design/widgets/{widget-name}.contract.md
+- **Dependencies**: BLOCKED by Wave 1 (all element tasks)
+- **Acceptance criteria**:
+  - Widget IMPORTS already-built element components from Wave 1 — do NOT rebuild element functionality inline. If element X exists in src/components/elements/, you MUST import it.
+  - Layout, spacing, and responsive behavior match the widget contract exactly
+  - Internal element composition matches the contract's element list (correct elements, correct arrangement)
+  - All element props are wired correctly per the widget contract
+  - Render the widget in isolation and visually confirm the assembly matches the contract
+```
+
+Widgets that share no elements can run in parallel. Widgets that compose the same elements should be sequenced to avoid merge conflicts.
+
+**CHECKPOINT after Wave 2**: Verify each built widget assembles its elements correctly. Open each widget in a browser — the composition should match the widget contract's layout spec. Any widget that doesn't match gets fixed before Wave 3 starts.
+
+**Wave 3 — Pages (one task per page contract):**
+
+Read each contract file in `.gsd-t/contracts/design/pages/`. For each page:
+
+```markdown
+### Task {N}: Compose {page-name} page
+- **Files**: src/pages/{page-name}.{ext}
+- **Contract refs**: design/pages/{page-name}.contract.md
+- **Dependencies**: BLOCKED by Wave 2 (all widget tasks)
+- **Acceptance criteria**:
+  - Page IMPORTS already-built widget components from Wave 2 — do NOT rebuild widget functionality inline
+  - Section ordering, page layout, and responsive breakpoints match the page contract exactly
+  - All widget instances are wired with correct data/props per the page contract
+  - Full page renders correctly at all breakpoints specified in the design contracts
+```
+
+**CHECKPOINT after Wave 3**: Full Design Verification Agent comparison against Figma (Step 5.25 in execute). This is where the pixel-perfect validation happens — but by this point, each element and widget has already been verified individually, so page-level deviations should be limited to composition/layout issues.
+
+**Critical rules for design hierarchy tasks:**
+- **ONE CONTRACT = ONE TASK**: Never merge multiple element or widget contracts into one task. Each gets its own focused subagent with only its own contract in context.
+- **NO INLINE REBUILDS**: This is the single most important rule. A widget task that rebuilds an element's functionality inline (instead of importing the element component) is a **TASK FAILURE** — not a style preference, a failure. Same for page tasks rebuilding widgets inline. The entire hierarchy exists to prevent this.
+- **VERIFY BEFORE COMPOSING**: No Wave 2 task starts until Wave 1 is verified. No Wave 3 task starts until Wave 2 is verified. The checkpoint gates are mandatory, not advisory.
+- **ELEMENT CONTRACT IS AUTHORITATIVE**: If the element contract says `bar-vertical-grouped` (vertical bars), the widget that composes it gets vertical bars — period. The Figma screenshot is reference material; the contract is the spec. When they disagree, the contract wins (and flag the discrepancy for review).
+
+**Combining with non-design tasks**: If the milestone has both design tasks and non-design tasks (API, data layer, auth), the non-design tasks can run in parallel with Wave 1 elements. Map dependencies normally — a widget that needs API data is BLOCKED by both its elements AND the API task.
+
+---
+
 ### Task Design Rules:
 0. **UI tasks — reference the design brief**: If `.gsd-t/contracts/design-brief.md` exists, UI task descriptions must reference it. Include a note like: "Follow the color palette, typography, spacing, and component patterns defined in `.gsd-t/contracts/design-brief.md`." This ensures visual consistency without repeating spec details in every task.
 1. **Atomic**: Each task produces a working, testable increment

package/commands/gsd-t-quick.md

@@ -153,9 +153,14 @@ When you encounter unexpected situations:
 1. Identify exactly which files need to change
 2. **Destructive Action Guard**: Check if this task involves destructive or structural changes (DROP TABLE, removing columns, deleting data, replacing architecture patterns, removing working modules, changing schema in ways that conflict with existing data). If YES → STOP and present the change to the user with what exists today, what will change, what will break, and a safe migration path. Wait for explicit approval.
 3. If a contract exists for the relevant interface, implement to match it
-4. Make the change — **adapt new code to existing structures**, not the other way around
-5. Verify it works
-6. Commit: `[quick] {description}`
+4. **Design Hierarchy Build Rule** (if touching design components):
+   - If building/modifying an ELEMENT: implement ONLY from the element contract. Every value must trace to the contract or design tokens.
+   - If building/modifying a WIDGET: IMPORT existing element components — do NOT rebuild element functionality inline. If `chart-donut` exists in `src/components/elements/`, import it.
+   - If building/modifying a PAGE: IMPORT existing widget components — do NOT rebuild widget functionality inline.
+   - **Contract is authoritative**: Follow the contract spec, not the Figma screenshot, when they appear to disagree.
+5. Make the change — **adapt new code to existing structures**, not the other way around
+6. Verify it works
+7. Commit: `[quick] {description}`
 
 ## Step 3.5: Emit Task Metrics
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.70.13",
+  "version": "2.70.14",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 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/stacks/design-to-code.md

@@ -28,6 +28,30 @@ 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.
 
+**Hierarchical Execution Order (MANDATORY when hierarchical contracts exist)**:
+```
+BUILD ORDER:
+  Wave 1: Elements   — build each element in isolation from its element contract
+                        ONE task per element. Verify each against its contract.
+  Wave 2: Widgets    — IMPORT built elements, compose per widget contract
+                        ONE task per widget. Verify assembly matches contract.
+  Wave 3: Pages      — IMPORT built widgets, compose per page contract
+                        ONE task per page. Full Design Verification Agent runs here.
+
+NO INLINE REBUILDS:
+  Widget tasks MUST import element components. If chart-donut exists in
+  src/components/elements/, you MUST import it — not build a second donut.
+  Page tasks MUST import widget components. The page's job is composition
+  and data wiring, not reimplementing widgets.
+  Rebuilding a lower-level component inline is a TASK FAILURE.
+
+CONTRACT IS AUTHORITATIVE:
+  If the element contract says 'bar-vertical-grouped' (vertical bars),
+  build vertical bars — even if the Figma screenshot looks ambiguous.
+  The contract was written from careful design analysis. When in doubt,
+  follow the contract, not the screenshot.
+```
+
 **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