@tekyzinc/gsd-t 2.55.11 → 2.56.11

package/README.md

@@ -12,7 +12,7 @@ A methodology for reliable, parallelizable development using Claude Code with op
 **Generates visual scan reports** — every `/gsd-t-scan` produces a self-contained HTML report with 6 live architectural diagrams, a tech debt register, and domain health scores; optional DOCX/PDF export via `--export docx|pdf`.
 **Self-learning rule engine** — declarative rules in rules.jsonl detect failure patterns from task metrics. Candidate patches progress through a 5-stage lifecycle (candidate, applied, measured, promoted, graduated) with >55% improvement gates before becoming permanent methodology artifacts.
 **Cross-project learning** — proven rules propagate to `~/.claude/metrics/` and sync across all registered projects via `update-all`. Rules validated in 3+ projects become universal; 5+ projects qualify for npm distribution. Cross-project signal comparison and global ELO rankings available via `gsd-t-metrics --cross-project` and `gsd-t-status`.
-**Stack Rules Engine** — auto-detects project tech stack (React, TypeScript, Node API, Python, Go, Rust) from manifest files and injects mandatory best-practice rules into subagent prompts at execute-time. Universal security rules always apply; stack-specific rules layer on top. Includes **design-to-code** rules for pixel-perfect frontend implementation from Figma, screenshots, or design images — with Figma MCP integration, design token extraction, stack capability evaluation, and visual verification loops. Extensible: drop a `.md` file in `templates/stacks/` to add a new stack.
+**Stack Rules Engine** — auto-detects project tech stack (React, TypeScript, Node API, Python, Go, Rust) from manifest files and injects mandatory best-practice rules into subagent prompts at execute-time. Universal security rules always apply; stack-specific rules layer on top. Includes **design-to-code** rules for pixel-perfect frontend implementation from Figma, screenshots, or design images — with Figma MCP integration, design token extraction, stack capability evaluation, and mandatory visual verification: every screen is rendered in a real browser, screenshotted at mobile/tablet/desktop, and compared pixel-by-pixel against the Figma design. Auto-bootstraps during partition when design references are detected. Extensible: drop a `.md` file in `templates/stacks/` to add a new stack.
 **Self-Calibrating QA** — `qa-calibrator.js` tracks QA miss-rates across milestones, detects weak-spot categories (error paths, boundaries, state transitions), and automatically injects targeted guidance into QA subagent prompts. Projects on the same stack share miss-rate data for faster calibration.
 **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).

package/commands/gsd-t-debug.md

@@ -53,8 +53,8 @@ if [ -d "$STACKS_DIR" ]; then
   ([ -f "playwright.config.ts" ] || [ -f "playwright.config.js" ]) && _add playwright.md
   [ -f "go.mod" ] && _add go.md
   [ -f "Cargo.toml" ] && _add rust.md
-  # Design-to-code detection (design contract, design tokens, or Figma config)
-  ([ -f ".gsd-t/contracts/design-contract.md" ] || [ -f "design-tokens.json" ] || [ -d "design-tokens" ] || [ -f ".figmarc" ] || [ -f "figma.config.json" ]) && _add design-to-code.md
+  # Design-to-code detection (design contract, design tokens, Figma config, or Figma MCP configured)
+  ([ -f ".gsd-t/contracts/design-contract.md" ] || [ -f "design-tokens.json" ] || [ -d "design-tokens" ] || [ -f ".figmarc" ] || [ -f "figma.config.json" ] || grep -q '"figma"' ~/.claude/settings.json 2>/dev/null) && _add design-to-code.md
 fi
 ```
 

package/commands/gsd-t-execute.md

@@ -193,8 +193,8 @@ if [ -d "$STACKS_DIR" ]; then
   ([ -f "playwright.config.ts" ] || [ -f "playwright.config.js" ]) && _add playwright.md
   [ -f "go.mod" ] && _add go.md
   [ -f "Cargo.toml" ] && _add rust.md
-  # Design-to-code detection (design contract, design tokens, or Figma config)
-  ([ -f ".gsd-t/contracts/design-contract.md" ] || [ -f "design-tokens.json" ] || [ -d "design-tokens" ] || [ -f ".figmarc" ] || [ -f "figma.config.json" ]) && _add design-to-code.md
+  # Design-to-code detection (design contract, design tokens, Figma config, or Figma MCP configured)
+  ([ -f ".gsd-t/contracts/design-contract.md" ] || [ -f "design-tokens.json" ] || [ -d "design-tokens" ] || [ -f ".figmarc" ] || [ -f "figma.config.json" ] || grep -q '"figma"' ~/.claude/settings.json 2>/dev/null) && _add design-to-code.md
 fi
 ```
 
@@ -282,16 +282,37 @@ 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** (only if design-to-code stack rule is active):
-   If the task involves UI implementation from a design reference:
-   a. Check if Claude Preview or Chrome MCP browser tools are available
-   b. If available: render the implemented component at each target breakpoint (mobile 375px, tablet 768px, desktop 1280px)
-   c. Screenshot each rendered breakpoint
-   d. Compare against the source design reference (from `.gsd-t/contracts/design-contract.md`)
-   e. Identify any deviations: spacing, color, typography, alignment, sizing
-   f. Fix deviations — every fix must trace to a design contract value (max 2 fix iterations)
-   g. Log verification results in the design contract's Verification Status table
-   h. If no browser tools available: log warning "Visual verification unavailable — manual review recommended" to `.gsd-t/qa-issues.md`
+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:
+   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:
+        - 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.
+   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.
 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.*
@@ -657,6 +678,14 @@ Rules:
 7. **E2E Functional Gaps**: Review ALL Playwright specs. Do they test actual
    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.
 
 ## Exploratory Testing (if Playwright MCP available)
 

package/commands/gsd-t-help.md

@@ -231,6 +231,7 @@ Use these when user asks for help on a specific command:
 - **Auto-invoked**: Yes (in wave, after milestone)
 - **Creates**: `.gsd-t/domains/*/`, `.gsd-t/contracts/`
 - **Use when**: Breaking down a milestone for parallel work
+- **Note (M33)**: Auto-creates `.gsd-t/contracts/design-contract.md` when Figma URLs or design references are detected in requirements — bootstraps the design-to-code stack rule for execute.
 
 ### discuss
 - **Summary**: Explore design decisions from multiple perspectives
@@ -260,7 +261,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 — when a design contract, design tokens, or Figma config is detected, injects pixel-perfect implementation rules: Figma MCP auto-detection, design token extraction, stack capability evaluation (recommends alternatives if stack can't achieve the design), visual verification loop via Claude Preview or Chrome MCP. Adds Step 7 (Visual Design Verification) to task execution flow.
+- **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`.
 
 ### test-sync
 - **Summary**: Keep tests aligned with code changes

package/commands/gsd-t-integrate.md

@@ -64,7 +64,7 @@ If rolled-back domains exist, report them to the user (or if Level 3: log to `.g
 
 **Stack Rules Detection (before spawning subagent):**
 Run via Bash to detect project stack and collect matching rules:
-`GSD_T_DIR=$(npm root -g 2>/dev/null)/@tekyzinc/gsd-t; STACKS_DIR="$GSD_T_DIR/templates/stacks"; STACK_RULES=""; if [ -d "$STACKS_DIR" ]; then for f in "$STACKS_DIR"/_*.md; do [ -f "$f" ] && STACK_RULES="${STACK_RULES}$(cat "$f")"$'\n\n'; done; if [ -f "package.json" ]; then grep -q '"react"' package.json 2>/dev/null && [ -f "$STACKS_DIR/react.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/react.md")"$'\n\n'; (grep -q '"typescript"' package.json 2>/dev/null || [ -f "tsconfig.json" ]) && [ -f "$STACKS_DIR/typescript.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/typescript.md")"$'\n\n'; grep -qE '"(express|fastify|hono|koa)"' package.json 2>/dev/null && [ -f "$STACKS_DIR/node-api.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/node-api.md")"$'\n\n'; fi; [ -f "requirements.txt" ] || [ -f "pyproject.toml" ] && [ -f "$STACKS_DIR/python.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/python.md")"$'\n\n'; [ -f "go.mod" ] && [ -f "$STACKS_DIR/go.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/go.md")"$'\n\n'; [ -f "Cargo.toml" ] && [ -f "$STACKS_DIR/rust.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/rust.md")"$'\n\n'; ([ -f ".gsd-t/contracts/design-contract.md" ] || [ -f "design-tokens.json" ] || [ -d "design-tokens" ] || [ -f ".figmarc" ] || [ -f "figma.config.json" ]) && [ -f "$STACKS_DIR/design-to-code.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/design-to-code.md")"$'\n\n'; fi`
+`GSD_T_DIR=$(npm root -g 2>/dev/null)/@tekyzinc/gsd-t; STACKS_DIR="$GSD_T_DIR/templates/stacks"; STACK_RULES=""; if [ -d "$STACKS_DIR" ]; then for f in "$STACKS_DIR"/_*.md; do [ -f "$f" ] && STACK_RULES="${STACK_RULES}$(cat "$f")"$'\n\n'; done; if [ -f "package.json" ]; then grep -q '"react"' package.json 2>/dev/null && [ -f "$STACKS_DIR/react.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/react.md")"$'\n\n'; (grep -q '"typescript"' package.json 2>/dev/null || [ -f "tsconfig.json" ]) && [ -f "$STACKS_DIR/typescript.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/typescript.md")"$'\n\n'; grep -qE '"(express|fastify|hono|koa)"' package.json 2>/dev/null && [ -f "$STACKS_DIR/node-api.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/node-api.md")"$'\n\n'; fi; [ -f "requirements.txt" ] || [ -f "pyproject.toml" ] && [ -f "$STACKS_DIR/python.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/python.md")"$'\n\n'; [ -f "go.mod" ] && [ -f "$STACKS_DIR/go.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/go.md")"$'\n\n'; [ -f "Cargo.toml" ] && [ -f "$STACKS_DIR/rust.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/rust.md")"$'\n\n'; ([ -f ".gsd-t/contracts/design-contract.md" ] || [ -f "design-tokens.json" ] || [ -d "design-tokens" ] || [ -f ".figmarc" ] || [ -f "figma.config.json" ] || grep -q '"figma"' ~/.claude/settings.json 2>/dev/null) && [ -f "$STACKS_DIR/design-to-code.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/design-to-code.md")"$'\n\n'; fi`
 
 If STACK_RULES is non-empty, append to the subagent prompt:
 ```

package/commands/gsd-t-partition.md

@@ -371,6 +371,53 @@ Generate the file using this format:
 
 Log in `.gsd-t/progress.md` Decision Log: `- {date}: Design brief generated at .gsd-t/contracts/design-brief.md — UI signals detected: {list of signals}`
 
+## Step 3.6: Design Contract Bootstrap (Figma/Design Reference Detection)
+
+After the design brief, check whether this project has a design reference (Figma, images, prototypes). If found, create `.gsd-t/contracts/design-contract.md` to activate the design-to-code stack rule during execute.
+
+**Skip this step if `.gsd-t/contracts/design-contract.md` already exists.**
+
+### Detection — check for ANY of the following
+
+| Signal | How to check |
+|--------|-------------|
+| Figma URL in requirements | `docs/requirements.md` contains `figma.com/design/` or `figma.com/file/` |
+| Figma URL in CLAUDE.md | `CLAUDE.md` contains `figma.com/design/` or `figma.com/file/` |
+| Figma MCP configured | `~/.claude/settings.json` has `mcpServers.figma` |
+| Figma config files | `.figmarc` or `figma.config.json` exists |
+| Design token files | `design-tokens.json` or `design-tokens/` directory exists |
+| Design images in docs | `docs/designs/`, `designs/`, or `mockups/` directory exists with image files |
+| Design references in requirements | `docs/requirements.md` contains "design", "mockup", "pixel-perfect", or "Figma" |
+
+If NONE of the above match → skip this step. Log: "Design contract: skipped — no design references detected."
+
+### Generate `.gsd-t/contracts/design-contract.md`
+
+1. Copy the design contract template from the GSD-T package:
+   ```bash
+   GSD_T_DIR=$(npm root -g 2>/dev/null)/@tekyzinc/gsd-t
+   TEMPLATE="$GSD_T_DIR/templates/design-contract.md"
+   if [ -f "$TEMPLATE" ]; then cp "$TEMPLATE" .gsd-t/contracts/design-contract.md; fi
+   ```
+
+2. If a Figma URL was found, populate the Source section:
+   - Set `Source Type` to `Figma MCP` (if MCP configured) or `Screenshot` (if not)
+   - Set `Source Reference` to the Figma URL
+   - Set `Precision Level` to `Exact (MCP)` or `Estimated (visual analysis)`
+
+3. If Figma MCP is available, use `get_design_context` or `get_metadata` to pre-populate:
+   - Color palette from design variables/styles
+   - Typography from text styles
+   - Spacing from auto-layout values
+
+**This file activates the design-to-code stack rule during execute**, ensuring:
+- Design tokens are extracted before coding
+- Every CSS value traces to the contract
+- Visual verification loop runs after implementation
+- Stack capability is evaluated before implementation begins
+
+Log in `.gsd-t/progress.md` Decision Log: `- {date}: Design contract created at .gsd-t/contracts/design-contract.md — design reference detected: {source type + URL or signal}`
+
 ## Step 4: Initialize Progress
 
 Write `.gsd-t/progress.md`:

package/commands/gsd-t-quick.md

@@ -68,8 +68,8 @@ if [ -d "$STACKS_DIR" ]; then
   ([ -f "playwright.config.ts" ] || [ -f "playwright.config.js" ]) && _add playwright.md
   [ -f "go.mod" ] && _add go.md
   [ -f "Cargo.toml" ] && _add rust.md
-  # Design-to-code detection (design contract, design tokens, or Figma config)
-  ([ -f ".gsd-t/contracts/design-contract.md" ] || [ -f "design-tokens.json" ] || [ -d "design-tokens" ] || [ -f ".figmarc" ] || [ -f "figma.config.json" ]) && _add design-to-code.md
+  # Design-to-code detection (design contract, design tokens, Figma config, or Figma MCP configured)
+  ([ -f ".gsd-t/contracts/design-contract.md" ] || [ -f "design-tokens.json" ] || [ -d "design-tokens" ] || [ -f ".figmarc" ] || [ -f "figma.config.json" ] || grep -q '"figma"' ~/.claude/settings.json 2>/dev/null) && _add design-to-code.md
 fi
 ```
 

package/commands/gsd-t-verify.md

@@ -79,7 +79,15 @@ Standard dimensions (adjust based on project):
 5. **E2E Tests**: Run the FULL Playwright suite — all specs must pass. If new features lack specs, create them before proceeding.
 6. **Security**: Auth flows, input validation, data exposure, dependencies
 7. **Integration Integrity**: Do the seams between domains hold under stress?
-8. **Requirements Traceability Close-Out**: Mark verified requirements as complete and report orphans:
+8. **Design Fidelity** (only when `.gsd-t/contracts/design-contract.md` exists):
+   - Open every implemented screen in a real browser (dev server + Claude Preview, Chrome MCP, or Playwright)
+   - Screenshot each screen at mobile (375px), tablet (768px), and desktop (1280px) widths
+   - Get the Figma reference: call Figma MCP `get_screenshot` if available, or use design images from the contract
+   - Compare every screen pixel-by-pixel against the Figma design:
+     Chart types, colors, typography, spacing, layout, component states, data visualization style
+   - Any deviation = FAIL with specifics (e.g., "Number of Tools: build uses vertical bars, design uses horizontal stacked bars")
+   - Design fidelity FAIL blocks milestone completion — it has the same weight as functional test failures
+9. **Requirements Traceability Close-Out**: Mark verified requirements as complete and report orphans:
    - Read `docs/requirements.md` traceability table (added by plan phase)
    - For each REQ-ID that is fully implemented and tested: update Status to `complete` in the traceability table
    - **Orphan report**: List any REQ-IDs with no task mapping (planning gap) and any tasks with no REQ-ID (potential scope creep)

package/commands/gsd-t-wave.md

@@ -67,7 +67,7 @@ For each phase, spawn the agent like this:
 
 **Stack Rules Detection (before spawning subagent):**
 Run via Bash to detect project stack and collect matching rules:
-`GSD_T_DIR=$(npm root -g 2>/dev/null)/@tekyzinc/gsd-t; STACKS_DIR="$GSD_T_DIR/templates/stacks"; STACK_RULES=""; if [ -d "$STACKS_DIR" ]; then for f in "$STACKS_DIR"/_*.md; do [ -f "$f" ] && STACK_RULES="${STACK_RULES}$(cat "$f")"$'\n\n'; done; if [ -f "package.json" ]; then grep -q '"react"' package.json 2>/dev/null && [ -f "$STACKS_DIR/react.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/react.md")"$'\n\n'; (grep -q '"typescript"' package.json 2>/dev/null || [ -f "tsconfig.json" ]) && [ -f "$STACKS_DIR/typescript.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/typescript.md")"$'\n\n'; grep -qE '"(express|fastify|hono|koa)"' package.json 2>/dev/null && [ -f "$STACKS_DIR/node-api.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/node-api.md")"$'\n\n'; fi; [ -f "requirements.txt" ] || [ -f "pyproject.toml" ] && [ -f "$STACKS_DIR/python.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/python.md")"$'\n\n'; [ -f "go.mod" ] && [ -f "$STACKS_DIR/go.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/go.md")"$'\n\n'; [ -f "Cargo.toml" ] && [ -f "$STACKS_DIR/rust.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/rust.md")"$'\n\n'; ([ -f ".gsd-t/contracts/design-contract.md" ] || [ -f "design-tokens.json" ] || [ -d "design-tokens" ] || [ -f ".figmarc" ] || [ -f "figma.config.json" ]) && [ -f "$STACKS_DIR/design-to-code.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/design-to-code.md")"$'\n\n'; fi`
+`GSD_T_DIR=$(npm root -g 2>/dev/null)/@tekyzinc/gsd-t; STACKS_DIR="$GSD_T_DIR/templates/stacks"; STACK_RULES=""; if [ -d "$STACKS_DIR" ]; then for f in "$STACKS_DIR"/_*.md; do [ -f "$f" ] && STACK_RULES="${STACK_RULES}$(cat "$f")"$'\n\n'; done; if [ -f "package.json" ]; then grep -q '"react"' package.json 2>/dev/null && [ -f "$STACKS_DIR/react.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/react.md")"$'\n\n'; (grep -q '"typescript"' package.json 2>/dev/null || [ -f "tsconfig.json" ]) && [ -f "$STACKS_DIR/typescript.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/typescript.md")"$'\n\n'; grep -qE '"(express|fastify|hono|koa)"' package.json 2>/dev/null && [ -f "$STACKS_DIR/node-api.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/node-api.md")"$'\n\n'; fi; [ -f "requirements.txt" ] || [ -f "pyproject.toml" ] && [ -f "$STACKS_DIR/python.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/python.md")"$'\n\n'; [ -f "go.mod" ] && [ -f "$STACKS_DIR/go.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/go.md")"$'\n\n'; [ -f "Cargo.toml" ] && [ -f "$STACKS_DIR/rust.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/rust.md")"$'\n\n'; ([ -f ".gsd-t/contracts/design-contract.md" ] || [ -f "design-tokens.json" ] || [ -d "design-tokens" ] || [ -f ".figmarc" ] || [ -f "figma.config.json" ] || grep -q '"figma"' ~/.claude/settings.json 2>/dev/null) && [ -f "$STACKS_DIR/design-to-code.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/design-to-code.md")"$'\n\n'; fi`
 
 If STACK_RULES is non-empty, append to the subagent prompt:
 ```

package/docs/GSD-T-README.md

@@ -270,7 +270,7 @@ GSD-T auto-detects your project's tech stack and injects mandatory best-practice
 | `requirements.txt` with `celery`, `dramatiq`, `rq`, or `arq` | `queues.md` |
 | `requirements.txt` with `openai`, `anthropic`, `langchain` | `llm.md` |
 | `pubspec.yaml` | `flutter.md` |
-| `.gsd-t/contracts/design-contract.md`, `design-tokens.json`, `design-tokens/`, `.figmarc`, or `figma.config.json` | `design-to-code.md` |
+| `.gsd-t/contracts/design-contract.md`, `design-tokens.json`, `design-tokens/`, `.figmarc`, `figma.config.json`, or Figma MCP in `settings.json` | `design-to-code.md` |
 
 ### Commands That Inject Stack Rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.55.11",
+  "version": "2.56.11",
   "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 — 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, compare pixel-by-pixel against Figma) — 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`.
 
@@ -617,7 +617,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. 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 visual verification loop using Claude Preview or Chrome MCP.
+**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.
 
 **Enforcement**: Stack rule violations have the same weight as contract violations — they are task failures, not warnings.
 

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

@@ -398,28 +398,59 @@ MANDATORY:
 
 ```
 MANDATORY:
-  ├── After implementing any design component, run a visual verification:
-  │   1. Render the component (Claude Preview, Chrome MCP, or dev server)
-  │   2. Screenshot the rendered output
-  │   3. Compare side-by-side with the source design
-  │   4. Identify EVERY deviation (spacing, color, font, alignment, sizing)
-  │   5. Fix each deviation — trace fix to design contract values
-  │   6. Re-render and re-compare
-  ├── Maximum 3 verification iterations per component
-  │     If still deviating after 3 → log specific deltas to .gsd-t/qa-issues.md
-  ├── Tool priority for rendering:
-  │     1. Claude Preview (if available) — fastest loop
-  │     2. Chrome MCP (if available) — full browser rendering
-  │     3. Dev server + manual screenshot — last resort
-  ├── Check at EVERY breakpoint — not just desktop
+  ├── 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
+  │
+  ├── Step 2: RENDER IN A REAL BROWSER
+  │     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
+  │
+  ├── Step 3: SCREENSHOT AT EVERY BREAKPOINT
   │     Mobile (375px), Tablet (768px), Desktop (1280px) minimum
-  ├── Verification is NOT optional — skipping it is a task failure
-  └── Log verification results in the design contract Verification Status table
+  │     Each breakpoint is a separate screenshot
+  │
+  ├── 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
+  │
+  ├── Step 5: FIX EVERY DEVIATION
+  │     Log each deviation with specifics before fixing
+  │     Fix one by one, tracing each fix to the design contract
+  │     Re-render after each batch of fixes
+  │     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
+  │
+  ├── 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
 ```
 
-**BAD** — Writing CSS, committing, moving on without ever seeing the rendered result.
+**BAD** — Writing CSS, committing, moving on without ever opening a browser to see the result. "Tests pass" is not visual verification.
 
-**GOOD** — Render → Screenshot → Compare → Fix spacing from 14px to 16px → Re-render → Confirm match → Log "verified at 3 breakpoints" in design contract.
+**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.
 
 ---