@tekyzinc/gsd-t 2.70.11 → 2.70.13

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [2.70.13] - 2026-04-06
+
+### Changed (gsd-t-init, gsd-t-init-scan-setup)
+- **Auto-create project directory + GitHub repo** — both `gsd-t-init` and `gsd-t-init-scan-setup` now create the project directory under a configurable base path and auto-create a private GitHub repo via `gh` CLI when a project name is provided as an argument.
+- **Configurable base directory** — `~/.claude/.gsd-t-config` stores `projects_dir` (e.g., `/Users/david/projects`). Set once, never asked again. New projects are created at `{projects_dir}/{project-name}`.
+- **Configurable GitHub org** — `~/.claude/.gsd-t-config` stores `github_org` (e.g., `Tekyz-Inc`). When set, repos are created under the org (`gh repo create {org}/{name}`). When not set, repos are created under the user's personal account.
+- Existing project detection: if the current directory already has code/config files, Step 0 is skipped entirely — no behavior change for existing projects.
+
+## [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-init-scan-setup.md

@@ -6,27 +6,54 @@ Can be run from anywhere — does not require being in the project folder first.
 
 ## Step 1: Project Directory
 
-First, ask: **"Is `{current directory name}` your project root folder?"**
+### 1a. Resolve the base projects directory (for new projects)
 
-- **Yes** → Stay here and continue to Step 2
-- **No** → Ask: "What's the project folder name?" (or use `$ARGUMENTS` if provided)
-  1. Check if the folder exists in the current directory
-     - **Exists** → `cd` into it
-     - **Does not exist** → Create it, then `cd` into it
+If `$ARGUMENTS` includes a project name:
 
-If `$ARGUMENTS` includes a folder/project name, skip the question and use it directly.
+1. Check `~/.claude/.gsd-t-config` for settings:
+   ```
+   # ~/.claude/.gsd-t-config format (one key=value per line):
+   projects_dir=/Users/username/projects
+   github_org=MyOrg
+   ```
+   - If `projects_dir` is set → use `{projects_dir}/{project-name}` as the target
+   - If not set → ask: "Where should new projects be created? (e.g., /Users/you/projects)"
+     Save their answer to `~/.claude/.gsd-t-config` as `projects_dir={path}`
+
+2. Check if the target directory exists:
+   - **Exists with files** → `cd` into it (existing project)
+   - **Exists but empty** → `cd` into it (new project)
+   - **Does not exist** → `mkdir -p {target}` then `cd` into it (new project)
+
+If NO `$ARGUMENTS` provided, ask: **"Is `{current directory name}` your project root folder?"**
+- **Yes** → Stay here
+- **No** → Ask for the project name, then apply the resolution above
 
 All subsequent steps run from inside the project directory.
 
-## Step 2: Git Repository Check
+## Step 2: Git Repository + GitHub Setup
 
 1. Check if the directory is inside a git repo: `git rev-parse --is-inside-work-tree`
-   - **Not a git repo** → Run `git init`
+   - **Not a git repo** → Run `git init && git checkout -b main`
 2. Check for an existing remote: `git remote -v`
-   - **No remote found** → Ask the user for the GitHub repository URL, then run:
-     ```
-     git remote add origin {url}
-     ```
+   - **No remote found** → Try to create one automatically:
+     - Check if `gh` CLI is available and authenticated: `gh auth status`
+     - If YES:
+       - Check `~/.claude/.gsd-t-config` for `github_org` setting
+       - If `github_org` is set:
+         ```bash
+         gh repo create {github_org}/{project-name} --private --source=. --push
+         ```
+         Log: "Created GitHub repo: {github_org}/{project-name} (private)"
+       - If `github_org` is NOT set:
+         ```bash
+         gh repo create {project-name} --private --source=. --push
+         ```
+         Log: "Created GitHub repo: {user}/{project-name} (private)"
+     - If NO → ask the user for the GitHub repository URL, then run:
+       ```
+       git remote add origin {url}
+       ```
    - **Remote exists** → Log it and continue
 3. **Pull existing code from remote** (if any):
    - Run `git fetch origin` to get remote refs

package/commands/gsd-t-init.md

@@ -2,6 +2,70 @@
 
 You are setting up a new project (or converting an existing one) to use the GSD-T contract-driven workflow.
 
+## Step 0: Project Directory + Git + GitHub (new projects only)
+
+If `$ARGUMENTS` contains a project name AND the current directory is NOT already a project directory (no `package.json`, `pyproject.toml`, `Cargo.toml`, `src/`, or `CLAUDE.md`), this is a NEW project. Set it up from scratch:
+
+### 0a. Resolve the base projects directory
+
+Check `~/.claude/.gsd-t-config` for settings:
+```
+# ~/.claude/.gsd-t-config format (one key=value per line):
+projects_dir=/Users/username/projects
+github_org=MyOrg
+```
+
+- If `projects_dir` is set → use that path
+- If not → ask user: "Where should new projects be created? (e.g., /Users/you/projects)"
+  - Save their answer to `~/.claude/.gsd-t-config` as `projects_dir={path}` so they're never asked again
+
+### 0b. Create the project directory
+
+```bash
+mkdir -p {projects_dir}/{project-name}
+cd {projects_dir}/{project-name}
+```
+
+If the directory already exists and has files → treat as an existing project, skip to Step 1.
+
+### 0c. Initialize git
+
+```bash
+git init
+git checkout -b main
+```
+
+### 0d. Create GitHub repo
+
+Check if `gh` CLI is available and authenticated:
+```bash
+gh auth status
+```
+
+- If `gh` is available and authenticated:
+  - Check `~/.claude/.gsd-t-config` for `github_org` setting
+  - If `github_org` is set:
+    ```bash
+    gh repo create {github_org}/{project-name} --private --source=. --push
+    ```
+    Log: "Created GitHub repo: {github_org}/{project-name} (private)"
+  - If `github_org` is NOT set (personal repos):
+    ```bash
+    gh repo create {project-name} --private --source=. --push
+    ```
+    Log: "Created GitHub repo: {user}/{project-name} (private)"
+- If `gh` is not available or not authenticated:
+  Log: "GitHub CLI not available — skipping repo creation. Create manually and run: `git remote add origin {url}`"
+
+### 0e. Continue with init
+
+All subsequent steps run from inside `{projects_dir}/{project-name}`.
+
+**Skip Step 0 entirely if:**
+- No project name in `$ARGUMENTS`, OR
+- Current directory already looks like a project (has code/config files), OR
+- Current directory is already inside a git repo with files
+
 ## Step 1: Assess Current State
 
 Check what exists:

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.13",
   "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`