@tekyzinc/gsd-t 2.59.10 → 2.60.10

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [2.60.10] - 2026-04-05
+
+### Added
+- **Shared Templates installer** — `installSharedTemplates()` in `bin/gsd-t.js` copies design-chart-taxonomy.md, element-contract.md, widget-contract.md, page-contract.md, design-contract.md, and shared-services-contract.md into `~/.claude/templates/` on install/update. Fresh-context workers (including Terminal 2 subprocesses) can now reference these at a predictable path instead of hunting through npx caches. Closes framework gap #1 surfaced by v2.59.10 convergence run 1.
+
+### Changed
+- **Element template `Test Fixture`** now documents a **Fixture Resolution Order** for Figma designs that use template tokens like `{num}%`: (1) concrete Figma text, (2) existing flat contract, (3) requirements sample data, (4) engineered stub matching visible proportions. Adds mandatory `__fixture_source__` and `__figma_template__` fields so verifiers distinguish extracted-from-design vs engineered-to-match-visual. Closes gap #4.
+- **Element template** adds a **Verification Harness** subsection clarifying what card chrome / controls to include vs strip when rendering the element on `/design-system/{name}`. Closes gap #5 ("element-only, no widget chrome" ambiguity).
+
 ## [2.59.10] - 2026-04-05
 
 ### Added

package/bin/gsd-t.js

@@ -26,6 +26,7 @@ const debugLedger = require(path.join(__dirname, "debug-ledger.js"));
 const CLAUDE_DIR = path.join(os.homedir(), ".claude");
 const COMMANDS_DIR = path.join(CLAUDE_DIR, "commands");
 const SCRIPTS_DIR = path.join(CLAUDE_DIR, "scripts");
+const CLAUDE_TEMPLATES_DIR = path.join(CLAUDE_DIR, "templates");
 const GLOBAL_CLAUDE_MD = path.join(CLAUDE_DIR, "CLAUDE.md");
 const SETTINGS_JSON = path.join(CLAUDE_DIR, "settings.json");
 const VERSION_FILE = path.join(CLAUDE_DIR, ".gsd-t-version");
@@ -748,6 +749,38 @@ function installCgc() {
 
 // ─── Commands ────────────────────────────────────────────────────────────────
 
+// Shared templates that slash-command prompts reference by predictable path.
+// Terminal-2 workers should find these at ~/.claude/templates/ without hunting
+// through npx caches. Keep this list tight — only templates that commands cite
+// via absolute path belong here.
+const SHARED_TEMPLATES = [
+  "design-chart-taxonomy.md",
+  "element-contract.md",
+  "widget-contract.md",
+  "page-contract.md",
+  "design-contract.md",
+  "shared-services-contract.md",
+];
+
+function installSharedTemplates() {
+  ensureDir(CLAUDE_TEMPLATES_DIR);
+  let installed = 0, skipped = 0;
+  for (const file of SHARED_TEMPLATES) {
+    const src = path.join(PKG_TEMPLATES, file);
+    const dest = path.join(CLAUDE_TEMPLATES_DIR, file);
+    if (!fs.existsSync(src)) continue;
+    if (fs.existsSync(dest) &&
+        normalizeEol(fs.readFileSync(src, "utf8")) === normalizeEol(fs.readFileSync(dest, "utf8"))) {
+      skipped++;
+      continue;
+    }
+    fs.copyFileSync(src, dest);
+    installed++;
+  }
+  if (skipped > 0) info(`${skipped} templates unchanged`);
+  success(`${installed + skipped} shared templates → ~/.claude/templates/`);
+}
+
 function installCommands(isUpdate) {
   heading("Slash Commands");
   const commandFiles = getCommandFiles();
@@ -873,6 +906,9 @@ function doInstall(opts = {}) {
   heading("Figma MCP (Design-to-Code)");
   configureFigmaMcp();
 
+  heading("Shared Templates");
+  installSharedTemplates();
+
   heading("Utility Scripts");
   installUtilityScripts();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.59.10",
+  "version": "2.60.10",
   "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/element-contract.md

@@ -89,6 +89,20 @@ Atomic visual unit. One contract per visual variant (e.g., `chart-bar-stacked-ho
 
 This is the EXACT data from the design source. Verification compares the built component rendered with this fixture against the Figma design. Placeholder data (Lorem, foo/bar, Calculator/Planner) is FORBIDDEN here — the verifier must be able to compare actual labels and values side-by-side.
 
+### Fixture Resolution Order (when the design has no concrete data)
+
+Figma designs frequently contain template tokens like `{num}%`, `{value}`, `$X,XXX` where concrete numbers are never encoded. When you hit this, follow this order — DO NOT invent unrelated placeholder labels:
+
+1. **Concrete values in Figma text nodes** → use them verbatim (highest priority).
+2. **Existing flat `design-contract.md` in the project** → if the card/chart was previously documented with numbers, inherit those numbers.
+3. **`docs/requirements.md` sample data** → if requirements specify example values, use them.
+4. **Engineered stub that visually matches the Figma render** → measure segment pixel widths (stacked) or relative heights (bar/column) and synthesise values summing to 100% (percentage variants) or matching the visible proportions (absolute variants).
+5. Record the resolution choice in a `__fixture_source__` field so verifiers can distinguish "extracted from design" vs "engineered to match visual".
+
+If the design uses template tokens, ALSO record them verbatim in a `__figma_template__` field. This lets the verifier compare both representations — e.g., "design shows `{num}%` placeholder, fixture supplies `27%`, built UI shows `27%`" is a MATCH, not a deviation.
+
+**Labels (category names, series names, legend items) must ALWAYS be extracted verbatim from Figma** — never substituted. Only numeric values fall back through the resolution order above.
+
 ```json
 {
   "__source__": "{Figma node URL or image file + node id}",
@@ -105,12 +119,25 @@ This is the EXACT data from the design source. Verification compares the built c
 
   "center_value": "{exact value shown in donut center, if applicable}",
   "center_sublabel": "{exact sublabel, if applicable}",
-  "percentages_shown": [{30}, {21}, {20}, {15}, {14}]
+  "percentages_shown": [{30}, {21}, {20}, {15}, {14}],
+
+  "__fixture_source__": "{extracted-from-figma | inherited-from-flat-contract | requirements-sample | engineered-to-match-visual}",
+  "__figma_template__": "{if design uses tokens: record them verbatim, e.g. '{num}%'. Omit if design has concrete values.}"
 }
 ```
 
 **Verification rule**: when the component is rendered with THIS fixture, every label, every value, every percentage shown in the built UI MUST match the design. Any substitution is a DEVIATION.
 
+### Verification Harness (how to render the element in isolation)
+
+When building an element for verification, render it on a dedicated `/design-system/{element-name}` route with **only** the visual context needed to compare it side-by-side against Figma:
+
+- **Always include**: the element itself, its data labels, its legend (if owned by the element).
+- **Include if the Figma reference shows them adjacent to the element**: card chrome (title, subtitle, KPI header) — but mark these in the page wrapper as `<!-- harness-only: belongs to widget contract -->` so future readers don't mistake them for part of this element contract.
+- **Never include**: widget-level controls (dropdowns, date-pickers, header action buttons), surrounding page layout, navigation, filters.
+
+Rule of thumb: if removing an element from the harness would make the Figma↔built comparison impossible (e.g., can't tell which chart the KPI "2.4" refers to), keep it. If it would just make the page look like the real app, strip it.
+
 ## Responsive Behavior
 
 | Breakpoint | Adaptation                                                    |