@tekyzinc/gsd-t 2.63.10 → 2.65.10

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [2.65.10] - 2026-04-05
+
+### Changed (page-contract template)
+- **Boundary grep regex tightened** — line-anchored (`^\s*`) + requires opening `{` — avoids false positives on JS identifiers like `donutProps` or property access `obj.donut`. Only matches actual CSS rules. Closes gap P5 from page-tier run 2.
+
+### Added (page-contract template)
+- **Multi-state Page Fixture convention** — for pages whose state swaps widget data, declare one full fixture per state under `__states__` keys, referencing named widget sub-fixtures (`#/fixture-sessions`). Prefer full duplication over override deltas. Closes gap P6.
+- **Inline-stub promotion guidance** — if a page-scope control is used in ≥2 pages, promote to its own widget contract; until then list in Composes Elements (direct) with `(promotion candidate)` tag. Closes gap P7.
+
+## [2.64.10] - 2026-04-05
+
+### Added (page-contract template)
+- **Page Fixture (OPTIONAL)** section — formalizes the composition chain (element → widget → page) by referencing each widget's fixture via `$ref:{widget-name}#/fixture`. Closes gap P2 from page-tier convergence run 1.
+- **Boundary Rules (MANDATORY)** section — explicit rules on what a page may vs may not do (pass data through widget props = OK; declare CSS for widget internal classes = VIOLATION). Adds a grep-based enforcement check. Closes gap P3.
+- **Grid position format** clarification — use `grid[row=N, col=M]` OR named CSS grid areas, consistently within one page. Closes gap P4.
+
+### Changed
+- **Widgets Used** table: renamed "Notes" column → "Layout Notes" with positioning-only guidance (spans/stacking/sticky — NOT widget configuration). Closes gap P1.
+
 ## [2.63.10] - 2026-04-05
 
 ### Added

package/package.json

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

@@ -18,14 +18,52 @@ Top-level assembly of widgets + global layout + routing + data loading. Pages PO
 
 ## Widgets Used
 
-| Position in Grid                 | Widget Contract                 | Notes                        |
+| Position in Grid                 | Widget Contract                 | Layout Notes                 |
 |----------------------------------|---------------------------------|------------------------------|
-| header                           | page-header-widget              | {sticky}                     |
-| sidebar                          | nav-sidebar-widget              | {collapsible at <1024px}     |
-| grid[row=1, cols=1-4]            | stat-strip-widget               | {4 KPI tiles}                |
-| grid[row=2, col=1-2]             | revenue-breakdown-widget        | {spans 2 columns}            |
-| grid[row=2, col=3-4]             | user-growth-widget              | {spans 2 columns}            |
-| grid[row=3, col=1-4]             | recent-activity-table-widget    | {full width}                 |
+| header                           | page-header-widget              | sticky                       |
+| sidebar                          | nav-sidebar-widget              | collapsible at <1024px       |
+| grid[row=1, cols=1-4]            | stat-strip-widget               | full-width row               |
+| grid[row=2, col=1-2]             | revenue-breakdown-widget        | spans 2 columns              |
+| grid[row=2, col=3-4]             | user-growth-widget              | spans 2 columns              |
+| grid[row=3, col=1-4]             | recent-activity-table-widget    | full width                   |
+
+**Grid position format**: use EITHER `grid[row=N, col=M]` / `grid[row=N, cols=M-K]` OR named CSS grid areas (`grid-area: strip`). Be consistent within one page. The **Layout Notes** column documents positioning metadata only (spans, stacking, sticky/fixed) — NOT widget configuration (widget props live in the widget contract).
+
+## Page Fixture (OPTIONAL)
+
+If you want to formalize the composition chain (element → widget → page), declare a page-level fixture that references each widget's fixture by `$ref`:
+
+```json
+{
+  "__fixture_source__": "composed-from-widgets",
+  "strip":  "$ref:stat-strip-widget#/fixture",
+  "donut":  "$ref:revenue-breakdown-widget#/fixture",
+  "bar":    "$ref:user-growth-widget#/fixture"
+}
+```
+
+Skip this section for pages that are pure assembly with no storybook / harness target. Include it when the page has a dedicated demo route or when multiple pages share widget fixtures and you want to document which instance each page references.
+
+**Multi-state pages** (when page state swaps widget data): declare **one full fixture per state**, keyed by the state name. Prefer full duplication over override deltas — it's more verbose but makes each state independently runnable and avoids merge ambiguity.
+
+```json
+{
+  "__fixture_source__": "composed-from-widgets",
+  "__states__": ["Members", "Sessions"],
+  "Members": {
+    "donut": "$ref:donut-chart-card-widget#/fixture",
+    "bar":   "$ref:bar-chart-card-widget#/fixture"
+  },
+  "Sessions": {
+    "donut": "$ref:donut-chart-card-widget#/fixture-sessions",
+    "bar":   "$ref:bar-chart-card-widget#/fixture-sessions"
+  }
+}
+```
+
+Widget contracts that have multiple fixture variants expose them as named sub-fixtures (`#/fixture-sessions`, `#/fixture-q4`, etc.) rather than a single `#/fixture`.
+
+**Inline-stub promotion**: if a page-scope control or chrome element (segmented control, tab bar, breadcrumb) is used in ≥2 pages, promote it to its own widget contract. Until promoted, list the stub in **Composes Elements (direct)** with a `(promotion candidate)` tag and the page paths that use it.
 
 ## Layout
 
@@ -123,6 +161,24 @@ Top-level assembly of widgets + global layout + routing + data loading. Pages PO
 - **Router integration**: {vue-router / react-router / next.js app dir}
 - **Data fetching**: {composable / hook / server component}
 
+## Boundary Rules (MANDATORY)
+
+A page is allowed to:
+- Pass DATA through a widget's documented `defineProps` / public API (titles, subtitles, fixture data — these are the widget's legitimate inputs)
+- Declare page-level layout CSS (grid template, gaps, padding, max-width, background, landmark regions)
+- Manage route-level state and data fetching
+
+A page is **FORBIDDEN** from:
+- Declaring CSS selectors that target a widget's internal classes (`.card-title`, `.donut-segment`, `.legend-dot`) — this is a boundary violation
+- Overriding widget visual spec via `:deep()` selectors or `!important` on widget-owned properties
+- Re-specifying element visual spec (colors, font sizes, radii, paddings owned by elements)
+
+**Enforcement check** (line-anchored CSS-only grep, avoids false positives on JS identifiers):
+```
+grep -En '^\s*(\.card-title|\.donut|\.legend-dot|\.kpi-value|\.chart-wrapper|\.filter-select)[^\w-]*\{' {page-file}
+```
+The leading `^\s*` anchor + trailing `\{` requirement matches ONLY CSS rules at the start of a line, not JS property access (`obj.donut`) or variable names (`donutProps`). If any match is found, move the styling into the widget contract or create a widget variant.
+
 ## Verification Checklist
 
 Page-level verification runs AFTER all widgets pass their own verification. Page verification only checks assembly — widget and element internals are out of scope.