@tekyzinc/gsd-t 4.19.10 → 4.19.11

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [4.19.11] - 2026-07-07
+
+### Fixed — `/gsd-t-stories` diagrams: semantic coloring + fit-to-page
+
+The command's flow diagrams were rendering as flat single-color and overflowing the page. Diagram generation now mandates **role-based semantic coloring** (green=action/go, orange=decision, red=destructive, blue-dashed=new/optional, purple=screen, white=terminal, via a `classDef` block) and **fit-to-page** layout (prefer `flowchart LR` for long linear flows, `subgraph` lanes or a part-1/2 split for large ones, explicit render sizing, and a verify-not-clipped-then-re-render step). Same rules mirrored into the bundled format reference. Also reconciled the backlog (removed 14 shipped/superseded items, renumbered survivors 1..46, fixed 4 number collisions).
+
+- `commands/gsd-t-stories.md`: Step 4 → 4a (semantic coloring) / 4b (fit-to-page) / 4c (render).
+- `templates/playbooks/tekyz-user-stories-format.md`: coloring + fit rules.
+- `.gsd-t/backlog.md`: 55 headings → 46 contiguous items.
+
 ## [4.19.10] - 2026-07-07
 
 ### Added — `/gsd-t-stories`: dev-team handoff user stories in the Tekyz format

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v4.19.10** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v4.19.11** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
 
 **Eliminates context rot** — task-level fresh dispatch (one subagent per task, ~10-20% context each) means compaction never triggers.
 **Compaction-proof debug loops** — `gsd-t headless --debug-loop` runs test-fix-retest cycles as separate `claude -p` sessions. A JSONL debug ledger persists all hypothesis/fix/learning history across fresh sessions. Anti-repetition preamble injection prevents retrying failed hypotheses. Escalation tiers (sonnet → opus → human) and a hard iteration ceiling enforced externally.

package/commands/gsd-t-stories.md

@@ -45,8 +45,37 @@ A table mapping every story → phase → epic: `| Story ID | Title | Phase | Ep
 
 Per the standing directive, diagrams are authored as Mermaid but **embedded as rendered images** (matching the sample's `<img>` flow charts) — NOT left as raw Mermaid text.
 
-1. Write each diagram's Mermaid source to `.gsd-t/user-stories/diagrams/<name>.mmd` (app-flow = `app-flow`, per-story = `<PREFIX>-NNN-flow`).
-2. Render each to PNG beside the deliverable: `mmdc -i <src>.mmd -o share/media/<name>.png` (Mermaid CLI `@mermaid-js/mermaid-cli`; fall back to `npx @mermaid-js/mermaid-cli -i … -o …`).
+### 4a. Semantic coloring (MANDATORY — never flat single-color)
+
+Every diagram MUST use **intelligent, role-based coloring** — NOT mermaid's default flat purple. Assign each node a `class` by its ROLE and define matching `classDef`s. Standard palette (green=go/success, orange=decision, red=destructive, blue=new/optional, purple=screen/state, grey=terminal):
+
+```mermaid
+%% put at the TOP of every flowchart:
+classDef start     fill:#fff,stroke:#333,color:#000;                         %% start/end terminals (ellipse)
+classDef decision  fill:#fdebc8,stroke:#e8a33d,color:#7a4f00;               %% decisions (diamonds)
+classDef screen    fill:#ece9fb,stroke:#8b7fd6,color:#2d2160;              %% screens / states
+classDef action    fill:#d4f4dd,stroke:#4caf72,color:#0f5132;             %% success / go / user actions
+classDef destructive fill:#fde2e2,stroke:#e06666,color:#7a1f1f;           %% end / delete / irreversible
+classDef newfeat   fill:#e2f0fb,stroke:#5b9bd5,color:#1f4e79,stroke-dasharray:4 3; %% NEW / optional (dashed)
+```
+
+- **Decisions** are diamonds `{...}` classed `decision`; **terminals** (start/end) are stadium/round `([...])` classed `start`; **screens/states** classed `screen`; **success/go paths** classed `action`; **destructive/irreversible** (End, Delete) classed `destructive`; **new/optional** classed `newfeat` (dashed).
+- Label decision-branch edges (`-->|Yes|`, `-->|Returning User|`).
+- Reference the sample styling in `~/.claude/playbooks/tekyz-user-stories-format.md`.
+
+### 4b. Fit-to-page (MANDATORY — the whole diagram must fit)
+
+A long top-down flow overflows the page (the failure the user flagged). Keep EVERY diagram fully on one page:
+
+- **Prefer `flowchart LR`** (left-to-right) for long linear flows — wide pages fit more than tall ones. Use `TD` only for short (≤6-node) flows.
+- For a flow with many nodes, **break into logical lanes with `subgraph`s**, or split into a "part 1 / part 2" pair of diagrams rather than one that runs off-page.
+- Render with an explicit width/scale and padding so nothing is clipped: `mmdc -i <src>.mmd -o share/media/<name>.png --width 1600 --backgroundColor white --scale 2 --padding 20` (a mermaid config `{ "flowchart": { "useMaxWidth": true } }` via `-c` also helps).
+- **After rendering, VERIFY the image isn't clipped** — check the PNG's dimensions are sane and, if a node count is high, that the layout direction kept it on-page. If a diagram still overflows, switch direction (`TD`→`LR`) or split it, and re-render. Do NOT ship a clipped diagram (`feedback_no_silent_degradation`).
+
+### 4c. Render pipeline
+
+1. Write each diagram's Mermaid source (with the `classDef` block + role classes + fit-appropriate direction) to `.gsd-t/user-stories/diagrams/<name>.mmd` (app-flow = `app-flow`, per-story = `<PREFIX>-NNN-flow`).
+2. Render each to PNG: `mmdc -i <src>.mmd -o share/media/<name>.png --width 1600 --backgroundColor white --scale 2 --padding 20` (Mermaid CLI `@mermaid-js/mermaid-cli`; fall back to `npx @mermaid-js/mermaid-cli …`).
 3. **If `mmdc` is unavailable → HALT** and tell the user to install it (`npm i -g @mermaid-js/mermaid-cli`). Do NOT silently ship raw Mermaid where an embedded image is expected (`feedback_no_silent_degradation`).
 4. Embed each rendered PNG in the markdown at its `Flow Diagram:` / §1 position: `![Flow Diagram](media/<name>.png)`.
 5. Keep the `.mmd` source (editable, version-controllable) alongside the PNG.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "4.19.10",
+  "version": "4.19.11",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/templates/playbooks/tekyz-user-stories-format.md

@@ -107,11 +107,40 @@ A table mapping every story to its phase + epic, so a team sees MVP vs later-pha
 Per the user directive, diagrams are **authored as Mermaid but EMBEDDED as rendered images**
 (like the sample's `<img>` flow charts) — not left as raw Mermaid text.
 
-1. Write each diagram's Mermaid source to `.gsd-t/user-stories/diagrams/<name>.mmd`.
-2. Render to PNG with the Mermaid CLI: `mmdc -i <name>.mmd -o media/<name>.png` (installed:
-   `@mermaid-js/mermaid-cli`; fall back to `npx @mermaid-js/mermaid-cli`). If `mmdc` is
-   unavailable, HALT and tell the user to install it — do NOT silently ship raw Mermaid where
-   an embedded image is expected (no-silent-degradation).
+### Semantic coloring (MANDATORY — never flat single-color)
+
+Every diagram uses **role-based coloring**, never mermaid's default flat purple. Put a
+`classDef` block at the top of each flowchart and class each node by ROLE:
+
+```
+classDef start       fill:#fff,stroke:#333,color:#000;                            %% start/end terminal
+classDef decision    fill:#fdebc8,stroke:#e8a33d,color:#7a4f00;                  %% decision diamond
+classDef screen      fill:#ece9fb,stroke:#8b7fd6,color:#2d2160;                 %% screen / state
+classDef action      fill:#d4f4dd,stroke:#4caf72,color:#0f5132;                %% success / go / action
+classDef destructive fill:#fde2e2,stroke:#e06666,color:#7a1f1f;               %% end / delete / irreversible
+classDef newfeat     fill:#e2f0fb,stroke:#5b9bd5,color:#1f4e79,stroke-dasharray:4 3; %% NEW / optional (dashed)
+```
+
+Green = go/success/action · Orange = decision · Red = destructive/irreversible · Blue(dashed)
+= new/optional · Purple = screen/state · White = terminal. Decisions are diamonds `{...}`;
+terminals are round `([...])`; label decision-branch edges (`-->|Yes|`).
+
+### Fit-to-page (MANDATORY — the whole diagram must fit)
+
+A long top-down flow overflows the page. Keep EVERY diagram fully on one page:
+- Prefer `flowchart LR` (left-to-right) for long linear flows; use `TD` only for ≤6-node flows.
+- For many nodes, break into `subgraph` lanes or split into part-1/part-2 diagrams.
+- Render with explicit sizing so nothing clips, then VERIFY the PNG isn't clipped; if it is,
+  switch direction or split and re-render. Never ship a clipped diagram.
+
+### Render
+
+1. Write each diagram's Mermaid source (classDef block + role classes + fit-appropriate
+   direction) to `.gsd-t/user-stories/diagrams/<name>.mmd`.
+2. Render to PNG: `mmdc -i <name>.mmd -o media/<name>.png --width 1600 --backgroundColor white
+   --scale 2 --padding 20` (`@mermaid-js/mermaid-cli`; fall back to `npx @mermaid-js/mermaid-cli`).
+   If `mmdc` is unavailable, HALT and tell the user to install it — do NOT silently ship raw
+   Mermaid where an embedded image is expected (no-silent-degradation).
 3. Embed the PNG in the markdown: `![Flow Diagram](media/<name>.png)`.
 4. On `.docx` conversion, pandoc embeds these PNGs as real Word images — matching the sample.