@tekyzinc/gsd-t 2.70.11 → 2.70.12

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [2.70.12] - 2026-04-06
+
+### Added (design pipeline — element count reconciliation)
+- **Element Count Reconciliation** — new mandatory verification step that runs BEFORE any property or visual comparison. Counts widgets and elements from the Figma decomposition (stored in INDEX.md), counts the built page's widgets and elements via Playwright, and compares. Any mismatch (missing or extra widgets/elements) is a CRITICAL deviation. Added to: `gsd-t-execute` (Step 0 inside Design Verification Agent), `gsd-t-quick` (Step 0), `gsd-t-design-audit` (Step 1.5).
+- **Figma Element Counts table in INDEX.md** — `gsd-t-design-decompose` now writes element/widget/page counts and a per-page element manifest to INDEX.md as the verification anchor. The verification agent reads these counts as ground truth.
+- **5-layer verification model** — design-to-code.md now documents Targets 0-4 in execution order: count reconciliation → contract comparison → Figma comparison → SVG overlay → DOM box model inspection.
+
+### Why
+A missing widget is the most catastrophic deviation but the easiest to miss in a 30+ row comparison table. The agent compares what exists but doesn't notice what's absent. An explicit count gate catches "Figma has 10 widgets, built page has 9 — WHERE IS THE 10TH?" before any property-level work begins.
+
 ## [2.70.11] - 2026-04-06
 
 ### Added (design pipeline — DOM box model inspection + layout arithmetic)

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

@@ -62,6 +62,35 @@ Widget: "Member Segmentation: State"
   CLASSIFICATION: chart-bar-stacked-vertical (two instances side-by-side)
 ```
 
+## Step 1.5: Element Count Reconciliation (MANDATORY)
+
+Before any property comparison, verify the built page has the correct number of elements:
+
+1. **Count from Figma** (from Step 1):
+   - Total widgets/cards identified
+   - Total elements within widgets (charts, legends, stat cards, controls, tables)
+   - Record: `Figma: {N} widgets, {M} total elements`
+
+2. **Count from built page** (open in browser via Playwright):
+   - Count top-level visual groups (cards/widgets)
+   - Count elements within each group
+   - Record: `Built: {N} widgets, {M} total elements`
+
+3. **Compare**:
+   - Widget count match? If NO → ❌ CRITICAL: identify MISSING or EXTRA widgets by name
+   - Element count match per widget? If NO → ❌ CRITICAL: identify MISSING or EXTRA elements
+
+```markdown
+### Element Count Reconciliation
+
+| Level              | Figma | Built | Verdict |
+|--------------------|-------|-------|---------|
+| Widgets (page)     | 10    | 9     | ❌ MISSING: video-playlist-widget |
+| Elements (total)   | 27    | 24    | ❌ MISSING: 3 elements in video-playlist-widget |
+```
+
+A missing widget is the most catastrophic deviation — it means an entire section of the design was silently dropped. Catch it here before spending effort on property-level comparison of widgets that DO exist.
+
 ## Step 2: Capture the Built Screen
 
 Open the built app at the target URL/route. For each widget identified in Step 1:

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

@@ -280,6 +280,25 @@ Write `INDEX.md` as a navigation map:
 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.
+
+## Figma Element Counts (MANDATORY — verification anchor)
+
+These counts are captured from the Figma decomposition and serve as the
+ground truth during verification. Any mismatch between these counts and
+the built output is a CRITICAL deviation.
+
+| Level    | Count | Source                          |
+|----------|-------|---------------------------------|
+| Elements | {N}   | Inventory table (Step 1d)       |
+| Widgets  | {N}   | Widget inventory (Step 3)       |
+| Pages    | {N}   | Page inventory (Step 4)         |
+| Total    | {N}   | Sum of all contracts            |
+
+Per-page element manifest (for verification agent):
+| Page               | Widgets | Elements (including widget-internal) |
+|--------------------|---------|--------------------------------------|
+| {dashboard}        | {N}     | {N} — {list: stat-card ×4, chart-donut ×1, ...} |
+| {analytics}        | {N}     | {N} — {list} |
 ```
 
 ## Step 6.5: Contract-vs-Figma Verification Gate (MANDATORY)

package/commands/gsd-t-execute.md

@@ -632,7 +632,28 @@ 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 0: Data-Labels Cross-Check (MANDATORY — run FIRST)
+## Step 0: Element Count Reconciliation (MANDATORY — run BEFORE anything else)
+
+Before any visual or property comparison, verify the built page has the
+correct NUMBER of elements. A missing widget is the easiest deviation to
+miss in a 30+ row comparison table — and the most catastrophic.
+
+1. Read INDEX.md (hierarchical) or design-contract.md (flat) to get the
+   Figma element counts:
+   - Per-page: how many widgets on this page? How many total elements
+     (including widget-internal charts, legends, cards, controls)?
+2. Count the built page's distinct visual elements via Playwright:
+   - Widgets/cards (top-level visual groups)
+   - Charts, tables, stat cards, legends, controls within each widget
+3. Compare:
+   - Figma widget count vs built widget count → mismatch = ❌ CRITICAL
+   - Figma element count vs built element count → mismatch = ❌ CRITICAL
+4. If counts match → proceed to Step 0.5
+   If counts DON'T match → identify WHICH elements are missing or extra:
+   'Figma has {N} widgets, built page has {M}. MISSING: {list}. EXTRA: {list}'
+   Log as CRITICAL deviation — do NOT skip, continue with remaining steps.
+
+## Step 0.5: Data-Labels Cross-Check (MANDATORY)
 
 Before any visual comparison, verify the built UI is rendering the CORRECT
 DATA from the design. This is the most common failure mode: agents use

package/commands/gsd-t-quick.md

@@ -259,7 +259,12 @@ comparison table. You write ZERO feature code.
 
 FAIL-BY-DEFAULT: Every visual element starts as UNVERIFIED. Prove each matches.
 
-STEP 0 (MANDATORY FIRST): Data-labels cross-check.
+STEP 0 (MANDATORY FIRST): Element count reconciliation.
+Read INDEX.md or design-contract.md for Figma element counts (widgets per page,
+total elements per page). Count the built page's widgets and elements via Playwright.
+If counts don't match → CRITICAL DEVIATION: identify which are MISSING or EXTRA.
+
+STEP 0.5: Data-labels cross-check.
 For each element contract (or design-contract.md section), read the Test Fixture.
 Verify EVERY label, value, percentage from the fixture appears verbatim in the
 rendered UI. If any is missing → CRITICAL DEVIATION (wrong data). Wrong data

package/package.json

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

@@ -560,7 +560,12 @@ MANDATORY:
 The verification agent compares the built frontend against **TWO sources** — not just one:
 
 ```
-VERIFICATION TARGETS:
+VERIFICATION TARGETS (run in this order):
+  ├── TARGET 0: ELEMENT COUNT RECONCILIATION (run FIRST)
+  │     Does the built page have the same NUMBER of widgets and elements
+  │     as the Figma design? A missing widget is the most catastrophic
+  │     deviation — catch it before spending effort on property comparison.
+  │
   ├── TARGET 1: Built screen vs DESIGN CONTRACTS
   │     Does the code match the contract's claimed values?
   │     (This is what the 13-task validation proved works — airtight.)
@@ -570,15 +575,19 @@ VERIFICATION TARGETS:
   │     This catches: contracts that were wrong to begin with,
   │     chart type misclassification, hallucinated data, missing elements.
   │
-  └── TARGET 3: SVG STRUCTURAL OVERLAY (MANDATORY)
-        Export Figma frame as SVG → parse element positions/dimensions/colors
-        → compare geometrically against built DOM bounding boxes.
-        This catches: aggregate spacing drift, alignment issues, proportion
-        errors that pass property-level checks but look wrong visually.
-        Mechanical, non-interpretive — no agent reasoning, just geometry.
+  ├── TARGET 3: SVG STRUCTURAL OVERLAY (MANDATORY)
+  │     Export Figma frame as SVG → parse element positions/dimensions/colors
+  │     → compare geometrically against built DOM bounding boxes.
+  │     This catches: aggregate spacing drift, alignment issues, proportion
+  │     errors that pass property-level checks but look wrong visually.
+  │
+  └── TARGET 4: DOM BOX MODEL INSPECTION (fixed-height containers)
+        Evaluate offsetHeight vs scrollHeight per child element.
+        This catches: inflated flex boxes, wrong space distribution,
+        elements growing beyond their content size.
 ```
 
-**Targets 2 and 3 are complementary.** Target 2 catches wrong values (property-level). Target 3 catches wrong placement (geometry-level). Together they cover both "is each value correct?" and "does the whole page look right?"
+**Each target catches a different failure class.** Target 0: missing elements. Target 1: wrong values. Target 2: wrong contracts. Target 3: wrong placement. Target 4: wrong space distribution. All five are needed — no single layer catches everything.
 
 ### Verification agent workflow
 
@@ -652,6 +661,8 @@ Before marking any design implementation task as complete:
 - [ ] Design system / component library identified (or confirmed none) and documented in design contract
 - [ ] Library components mapped to design elements — custom build only where no library match exists
 - [ ] Design source identified and documented in design contract
+- [ ] Element counts recorded in INDEX.md (widgets per page, elements per page)
+- [ ] Built page element count matches Figma element count (no missing/extra widgets)
 - [ ] Stack capability evaluated — all design requirements achievable (or alternatives approved)
 - [ ] All design tokens extracted (colors, typography, spacing, borders, shadows)
 - [ ] Tokens written to `.gsd-t/contracts/design-contract.md`