@tekyzinc/gsd-t 2.56.13 → 2.56.15

package/commands/gsd-t-execute.md

@@ -283,31 +283,46 @@ Execute the task above:
      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:
+   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. **Render the built component in a real browser**: Start the dev server if not running.
-      Use Claude Preview, Chrome MCP, or Playwright to open the page at the correct URL.
-      Capture screenshots at each target breakpoint:
+   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
-   c. **Pixel-by-pixel comparison**: Place the Figma screenshot and browser screenshot side-by-side.
-      Systematically compare every element:
-        - Chart types (bar vs stacked bar vs donut — exact match required)
-        - Colors (exact hex match — #1A73E8 is not #1A74E9)
-        - Typography (font family, weight, size, line-height, letter-spacing)
-        - Spacing (padding, margins, gaps — exact pixel match)
-        - Layout (grid structure, alignment, element positioning)
-        - Component states (toggles, active states, expanded/collapsed sections)
-        - Data visualization style (chart axis, labels, legends, distribution bars)
-   d. **Log every deviation** with specifics: "Donut chart missing center text '485 Total Interactions',
-      Number of Tools uses vertical bars but design shows horizontal stacked bar"
-   e. **Fix ALL deviations** — max 3 fix-and-recheck iterations per component.
-      After each fix, re-render and re-compare. Every fix must trace to a design contract value.
-   f. **If deviations remain after 3 iterations**: log to `.gsd-t/qa-issues.md` with severity CRITICAL
-      and tag `[VISUAL]`. This BLOCKS task completion — the task is NOT done.
+   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.
@@ -679,13 +694,27 @@ Rules:
    behavior (state changes, data loaded, navigation works) or just check
    that elements exist? Flag and rewrite any shallow/layout tests.
 8. **Design Fidelity** (if .gsd-t/contracts/design-contract.md exists):
-   Open every implemented screen in a real browser. Screenshot at mobile
-   (375px), tablet (768px), desktop (1280px). Get Figma reference via
-   Figma MCP get_screenshot (or design contract images). Compare every
-   element: chart types, colors, typography, spacing, layout, component
-   states, data visualization style. Any visual deviation from the design
-   is a CRITICAL bug. 'Build shows vertical bars but design shows horizontal
-   stacked bars' is a real bug, not a style opinion.
+   FAIL-BY-DEFAULT: assume NOTHING matches. Prove each element individually.
+   a. Open every implemented screen in a real browser. Screenshot at mobile
+      (375px), tablet (768px), desktop (1280px). Get Figma reference via
+      Figma MCP get_screenshot (or design contract images).
+   b. Build an element inventory: enumerate every distinct visual element
+      in the design top-to-bottom. Every chart, label, icon, heading, card,
+      spacing boundary, and color. Data visualizations expand: chart type,
+      orientation, axis labels, legend position, bar colors, data labels,
+      grid lines, center text — each a separate item.
+   c. Produce a structured comparison table (MANDATORY):
+      | # | Section | Element | Design (specific) | Implementation (specific) | Verdict |
+      Every element gets specific values in both columns (hex colors, chart
+      type names, px sizes, font weights — never vague descriptions).
+      Only valid verdicts: ✅ MATCH or ❌ DEVIATION.
+      NEVER write "appears to match" or "looks correct."
+   d. Any ❌ DEVIATION is a CRITICAL bug with full reproduction:
+      'Design: horizontal stacked bar with % labels inside bars.
+       Build: vertical grouped bar with labels above bars.' — this is a bug.
+      'Design: 32px Inter SemiBold. Build: 24px Inter Regular.' — this is a bug.
+   e. If the comparison table has fewer than 30 rows for a full page, the
+      audit is incomplete — go back and find the missing elements.
 
 ## Exploratory Testing (if Playwright MCP available)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.56.13",
+  "version": "2.56.15",
   "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

@@ -322,7 +322,7 @@ After QA passes, every code-producing command spawns a **Red Team agent** — an
 **Key Red Team rules:**
 - **Inverted incentive**: More bugs found = more value. Zero bugs requires exhaustive proof of thoroughness.
 - **False positive penalty**: Reporting non-bugs destroys credibility. Every bug must be reproduced with proof.
-- **Exhaustive categories**: Contract violations, boundary inputs, state transitions, error paths, missing flows, regression, E2E functional gaps, design fidelity (when design contract exists: render in browser, screenshot, compare pixel-by-pixel against Figma) — all must be attempted.
+- **Exhaustive categories**: Contract violations, boundary inputs, state transitions, error paths, missing flows, regression, E2E functional gaps, design fidelity (when design contract exists: render in browser, screenshot, build element inventory, produce structured comparison table with per-element MATCH/DEVIATION verdicts — never "looks close") — all must be attempted.
 - **VERDICT**: `FAIL` (bugs found — blocks completion) or `GRUDGING PASS` (exhaustive search, nothing found).
 - **Report**: Written to `.gsd-t/red-team-report.md`; bugs also appended to `.gsd-t/qa-issues.md`.
 

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

@@ -435,6 +435,8 @@ MANDATORY:
 
 ## 15. Visual Verification Loop
 
+**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.
+
 ```
 MANDATORY:
   ├── After implementing any design component, you MUST verify it visually.
@@ -445,38 +447,98 @@ MANDATORY:
   │     If no MCP → use design image/screenshot from the design contract
   │     You MUST have a reference image before proceeding
   │
-  ├── Step 2: RENDER IN A REAL BROWSER
+  ├── 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 the page using Claude Preview, Chrome MCP, or Playwright
-  │     You MUST see real rendered output — not just read the code
+  │     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 |
+  │     | ... | ... | ... | ... | ... | ... |
   │
-  ├── Step 3: SCREENSHOT AT EVERY BREAKPOINT
-  │     Mobile (375px), Tablet (768px), Desktop (1280px) minimum
-  │     Each breakpoint is a separate screenshot
+  │     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.
   │
-  ├── Step 4: PIXEL-BY-PIXEL COMPARISON
-  │     Place Figma screenshot and browser screenshot side-by-side
-  │     Check EVERY element systematically:
-  │       Chart types — bar vs stacked bar vs donut (exact type match)
-  │       Colors — exact hex values, not "close enough"
-  │       Typography — font family, weight, size, line-height, letter-spacing
-  │       Spacing — padding, margins, gaps (exact pixel match)
-  │       Layout — grid structure, alignment, positioning
-  │       Component states — toggle active/inactive, expanded/collapsed
-  │       Data visualization — axis labels, legends, chart orientation
-  │       Icons and imagery — correct icon set, correct sizes
+  │     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
-  │     Log each deviation with specifics before fixing
-  │     Fix one by one, tracing each fix to the design contract
+  │     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
-  │     Confirm every deviation is resolved
-  │     If deviations remain → CRITICAL finding in .gsd-t/qa-issues.md
-  │     Task is NOT complete until visual match is confirmed
+  │     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:
@@ -487,9 +549,9 @@ MANDATORY:
   └── Log all verification results in the design contract Verification Status table
 ```
 
-**BAD** — Writing CSS, committing, moving on without ever opening a browser to see the result. "Tests pass" is not visual verification.
+**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** — Render at 375px → Screenshot → Compare to Figma → "Donut chart missing center text, stacked bars rendered as vertical bars" → Fix chart type → Fix center text → Re-render → Confirm match → Repeat at 768px and 1280px → All match → Log "verified at 3 breakpoints" in design contract.
+**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.
 
 ---