@tekyzinc/gsd-t 2.70.10 → 2.70.12

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 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)
+- **DOM Box Model Inspection** — new mandatory verification step for fixed-height containers. Uses Playwright to evaluate `offsetHeight` vs `scrollHeight` for each child element. Flags elements where `offsetHeight > scrollHeight * 1.5` as INFLATED (symptom: `flex: 1` on a content element inflating its box beyond content size). Added to: `gsd-t-execute` (Step 5.5 inside Design Verification Agent), `gsd-t-quick` (step 8 inside Design Verification Agent), `gsd-t-design-audit` (Step 3.75).
+- **Internal Layout Arithmetic** — widget contract template now requires computed height budgets for fixed-height cards: `card_height - padding - header = body_available`, then `child1 + gap1 + child2 + ... = total_content ≤ body_available`. Forces the agent to write the math before coding — prevents `gap: 12px` when only `gap: 8px` fits.
+- **Flex Centering Anti-Pattern Rule** — `design-to-code.md` Section 8 now explicitly prohibits `flex: 1` on content elements (KPI, labels, text) for centering. Rule: `flex: 1` belongs on containers, `justify-content: center` on the parent. Children keep natural size.
+- **4 new verification checklist items** in `design-to-code.md` and `widget-contract.md`: box model inspection, layout arithmetic, no content flex:1, inflated element detection.
+
+### Why
+BDS horizontal stacked bar cards required 5 user-prompted fix iterations to get spacing right. Root cause: agent used `flex: 1` on `.kpi` to center it vertically, which inflated the element to 144px (content was 40px), displacing the chart section. The property comparison table and SVG overlay both missed this because the *positions* were close enough — the problem was *how space was distributed*, not where elements landed. DOM box model inspection catches the cause (inflated element) not just the symptom (displaced sibling).
+
 ## [2.70.10] - 2026-04-06
 
 ### Added (design pipeline — 2 new capabilities)

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:
@@ -197,9 +226,35 @@ After the per-widget property comparison, run a mechanical SVG-based diff to cat
 
 This step catches spacing rhythm, alignment drift, and proportion issues that pass the per-widget property check but are visually wrong in aggregate.
 
+## Step 3.75: DOM Box Model Inspection (MANDATORY for fixed-height containers)
+
+For each card/widget with a fixed height, inspect the internal space distribution:
+
+1. **Evaluate in browser** (via Playwright) for each card body child:
+   - `offsetHeight` (layout box size), `scrollHeight` (content size), `flex-grow` (computed)
+
+2. **Flag inflated elements**: any element where `offsetHeight > scrollHeight * 1.5`
+   - This means `flex: 1` or `flex-grow: 1` is inflating the element's box beyond its content
+   - Severity: HIGH — "`.kpi` offsetHeight=144px but content only needs 40px — inflated by flex growth"
+
+3. **Verify layout arithmetic**: sum all child `offsetHeight` values + computed gaps. Compare against card body `offsetHeight`:
+   - Sum > body → content overflows (❌ DEVIATION)
+   - Sum < body by >20px with no centering strategy → space is unaccounted (❌ DEVIATION)
+
+4. **Produce box model table** per widget:
+
+```markdown
+### Box Model: {widget-name}
+
+| # | Element | offsetHeight | scrollHeight | flex-grow | Verdict |
+|---|---------|-------------|-------------|-----------|---------|
+| 1 | .kpi    | 144px       | 40px        | 1         | ❌ INFLATED |
+| 2 | .chart  | 74px        | 74px        | 0         | ✅ MATCH |
+```
+
 ## Step 4: Summary Report
 
-After all widgets are audited (property tables + SVG structural diff), produce a summary:
+After all widgets are audited (property tables + SVG structural diff + box model), produce a summary:
 
 ```markdown
 ## Design Audit Summary

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
@@ -785,6 +806,49 @@ aggregate visual drift that individual property checks miss.
 This step catches spacing rhythm, alignment drift, and proportion issues
 that pass the property-level check but are visually wrong in aggregate.
 
+## Step 5.5: DOM Box Model Inspection (MANDATORY for fixed-height containers)
+
+The property table catches wrong values. The SVG overlay catches wrong positions.
+This step catches wrong SPACE DISTRIBUTION — elements whose box model is inflated
+by flex growth, pushing siblings out of position even when the visual appears close.
+
+For each card/widget with a fixed height (container_height is not 'auto'):
+
+1. Use Playwright to evaluate in the browser:
+   ```javascript
+   // For each child element of the card body:
+   const children = await page.$$eval('.card-body > *', els =>
+     els.map(el => ({
+       selector: el.className,
+       offsetHeight: el.offsetHeight,
+       scrollHeight: el.scrollHeight,
+       computedFlex: getComputedStyle(el).flex,
+       computedFlexGrow: getComputedStyle(el).flexGrow,
+     }))
+   );
+   ```
+
+2. Flag any element where `offsetHeight > scrollHeight * 1.5`:
+   This means the element's layout box is ≥50% larger than its content.
+   Symptom: element is using `flex: 1` or `flex-grow: 1` and inflating.
+   ❌ DEVIATION (severity HIGH): '{selector} offsetHeight={X}px but
+   content only needs {scrollHeight}px — inflated by flex growth.
+   Fix: remove flex:1 from this element, apply justify-content:center
+   on its parent container instead.'
+
+3. Verify layout arithmetic:
+   - Read the widget contract's Internal Layout Arithmetic section
+   - Sum all child offsetHeights + computed gaps
+   - Compare against the card body's offsetHeight
+   - If sum > body height → ❌ DEVIATION: content overflows
+   - If sum < body height by >20px with no centering strategy → ❌ DEVIATION
+
+4. Produce box model table:
+   | # | Element | offsetHeight | scrollHeight | flex-grow | Verdict |
+   |---|---------|-------------|-------------|-----------|---------|
+   | 1 | .kpi    | 144px       | 40px        | 1         | ❌ INFLATED |
+   | 2 | .chart  | 74px        | 74px        | 0         | ✅ MATCH |
+
 ## Step 6: Report Deviations
 
 For each ❌ DEVIATION, write a specific finding:

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
@@ -288,7 +293,14 @@ cannot be redeemed by visual polish.
       | # | SVG Element | SVG Position | Built Position | Δ px | Verdict |
    g. Flag unmapped SVG elements as MISSING, unmapped DOM elements as EXTRA
    This catches aggregate visual drift that property-level checks miss.
-8. Write results (property table + SVG diff) to .gsd-t/contracts/design-contract.md
+8. DOM Box Model Inspection (for fixed-height containers):
+   a. For each card body child, evaluate: offsetHeight, scrollHeight, flex-grow
+   b. Flag elements where offsetHeight > scrollHeight * 1.5 as INFLATED
+      (element using flex:1 when it shouldn't — box larger than content)
+   c. Verify layout arithmetic: sum of child heights + gaps = body height
+   d. Produce box model table:
+      | Element | offsetHeight | scrollHeight | flex-grow | Verdict |
+9. Write results (property table + SVG diff + box model) to .gsd-t/contracts/design-contract.md
    under '## Verification Status'
 9. Any ❌ → append to .gsd-t/qa-issues.md with [VISUAL] tag
 10. Report: DESIGN VERIFIED | DESIGN DEVIATIONS FOUND ({count})"

package/package.json

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

@@ -281,6 +281,47 @@ MANDATORY:
 
 **GOOD** — Extracting gap as exactly `24px` from the design, then: `display: flex; gap: 1.5rem; /* 24px — design contract: section-gap */`
 
+### Flex Centering Anti-Pattern (MANDATORY)
+
+```
+NEVER use flex: 1 on a content element to center its text/content.
+flex: 1 makes the ELEMENT GROW to fill available space — the content
+centers within an oversized box, but the box itself displaces siblings.
+
+  WRONG — content element grows, inflated box shifts layout:
+    .kpi { flex: 1; display: flex; justify-content: center; }
+
+  RIGHT — parent grows, children keep natural size:
+    .body { flex: 1; display: flex; flex-direction: column;
+            justify-content: center; }
+    .kpi  { /* no flex: 1 — natural height only */ }
+
+  RULE: flex: 1 belongs on CONTAINERS, not on CONTENT elements.
+        To center content vertically, apply justify-content: center
+        on the parent — never flex: 1 on the child.
+```
+
+### Fixed-Height Container Arithmetic (MANDATORY)
+
+```
+When a card or container has a fixed height, BEFORE writing any CSS:
+  1. Compute the total available body height:
+     body_available = card_height - padding_top - padding_bottom
+                      - header_height - header_to_body_gap
+  2. List every child element's height (from the design contract)
+  3. List every gap between children
+  4. SUM them: total_content = child1 + gap1 + child2 + gap2 + ...
+  5. Compare: total_content MUST ≤ body_available
+  6. If total_content < body_available:
+     Document the centering strategy (justify-content: center on parent)
+  7. If total_content > body_available:
+     The design extraction is wrong — go back to Figma
+
+  This arithmetic goes in the widget contract's Internal Layout
+  Arithmetic section. The implementation MUST match the arithmetic.
+  If gap: 12px makes the math exceed body_available, use gap: 8px.
+```
+
 ---
 
 ## 9. Responsive Breakpoint Strategy
@@ -519,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.)
@@ -529,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
 
@@ -611,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`
@@ -628,4 +680,7 @@ Before marking any design implementation task as complete:
 - [ ] Accessibility: focus indicators, alt text, ARIA where needed, 44px touch targets
 - [ ] No magic numbers — every value is documented or uses a design token
 - [ ] SVG structural overlay comparison completed — geometry diff ≤2px per element
+- [ ] DOM box model inspection passed — no inflated elements (offsetHeight >> scrollHeight)
+- [ ] Layout arithmetic verified — child heights + gaps = body available height (fixed-height cards)
+- [ ] No content element uses `flex: 1` for centering — only parent containers
 - [ ] Verification results logged in design contract Verification Status table

package/templates/widget-contract.md

@@ -95,6 +95,41 @@ This section specifies how elements are sized, spaced, and aligned WITHIN the ca
 - `body_layout` + `body_justify` + `body_align` together define whether the chart is centered in its card, left-aligned, or stretched. Get this wrong and every widget "looks off."
 - These values are WIDGET-OWNED — they describe how the widget positions its elements, not the elements' internal specs (which live in element contracts).
 
+### Internal Layout Arithmetic (MANDATORY for fixed-height cards)
+
+When `container_height` is fixed (not `auto`), you MUST compute and document the internal height budget. The math must add up exactly — no approximation.
+
+```
+card_height:           {e.g., 334px}
+card_padding_top:      {e.g., 16px}
+card_padding_bottom:   {e.g., 16px}
+header_height:         {title + subtitle + gap} = {e.g., 48px}
+header_to_body_gap:    {e.g., 16px}
+─────────────────────────────────────────────────
+body_available:        {card_height - padding_top - padding_bottom
+                        - header_height - header_to_body_gap}
+                       = {e.g., 334 - 16 - 16 - 48 - 16 = 238px}
+
+body_breakdown:
+  kpi_height:          {natural content height, e.g., 40px — NOT flex:1}
+  kpi_to_chart_gap:    {e.g., 16px}
+  chart_section:       {bar + gap + labels + gap + legend}
+                       = {e.g., 30 + 8 + 12 + 8 + 16 = 74px}
+  ────────────────────
+  total_body_content:  {40 + 16 + 74 = 130px}
+  remaining_space:     {238 - 130 = 108px}
+
+centering_strategy:    {e.g., body uses flex-column + justify-content: center
+                        to vertically center the content group (KPI + chart)
+                        in the 238px body area. KPI keeps natural height.}
+```
+
+**Rules:**
+- Every row must be an exact pixel value extracted from the Figma design
+- The sum of all body content MUST equal `body_available` OR explicitly document how remaining space is distributed (centering, padding, etc.)
+- **NEVER use `flex: 1` on a content element (KPI, label, text) to center it.** `flex: 1` makes the element grow to fill available space, inflating its box model. Use `flex: 1` + `justify-content: center` on the PARENT container instead. The parent grows; children keep natural size.
+- If the math doesn't add up, the design extraction is incomplete — go back to Figma
+
 ## Data Binding
 
 **Widget input shape:**
@@ -189,6 +224,9 @@ Widget-level verification runs AFTER all referenced elements pass their own veri
 - [ ] Element sizing matches design (chart_width, chart_height, legend_width)
 - [ ] Legend alignment matches design (footer_legend_justify: center vs left)
 - [ ] Card container values match design (padding, border, radius, shadow)
+- [ ] Layout arithmetic adds up: sum of child heights + gaps = body_available (fixed-height cards only)
+- [ ] No content element uses `flex: 1` for centering — only parent containers may use `flex: 1`
+- [ ] DOM box model check: no element's offsetHeight >> its content height (inflated box = wrong flex)
 - [ ] Responsive breakpoints adapt as specified
 - [ ] Data binding produces correct element inputs (spot-check with sample data)
 - [ ] Inter-element interactions fire (hover sync, click propagation)