@tekyzinc/gsd-t 4.19.13 → 4.19.14

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [4.19.14] - 2026-07-07
+
+### Changed — `/gsd-t-stories`: pagination, test-case coloring, in-image diagram titles
+
+Four handoff-doc polish items from user feedback. **(1) One-story-per-page pagination:** each Epic starts a new page, its first story flows on that page, every subsequent story in the epic starts a new page (each story ends with its Mapped Test Cases table). **(2) Test-case grid coloring:** purple header row + `Type`-cell tint (Positive=green, Negative=peach, Edge=blue). **(3) In-image diagram title:** each diagram carries its own title banner (story id + title, dark-purple on light-purple) inside the rendered image, so the external `Flow Diagram:` label and footer are dropped. **(4)** Because the diagram is self-titled, it reclaims the FULL page height (the v4.19.13 label-reserve no longer applies to diagrams).
+
+- `commands/gsd-t-stories.md`: pagination rule, Step 4b full-page fit, 4d in-image title, 4e table coloring.
+- `templates/playbooks/tekyz-user-stories-format.md`: same.
+
 ## [4.19.13] - 2026-07-07
 
 ### Fixed — `/gsd-t-stories`: reserve label space when a diagram is height-constrained

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v4.19.13** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v4.19.14** - 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

@@ -32,12 +32,18 @@ For EACH story, author in EXACTLY this order (per the format reference):
 3. **Story:** `*As a <role>, I want <capability>, so that <benefit>.*` (strict template, one sentence.)
 4. **Workflow:** numbered concrete interaction steps (user action → system response), present tense.
 5. **Acceptance Criteria:** bulleted, **grouped by sub-area** with a bold sub-heading per group; include error/edge/recovery groups. Each bullet one testable assertion.
-6. **Flow Diagram:** a per-story Mermaid flowchart of THIS story's workflow → rendered PNG → embedded (Step 4).
-7. **Mapped Test Cases:** table `TC ID | Type | Test Title | Expected Result`. `TC-NNN` sequential across the whole doc; `Type` ∈ {Positive, Negative, Edge}; cover happy-path + failure + boundary; every acceptance-criteria group represented by ≥1 test case.
+6. **Flow Diagram** (the LAST-but-one section; the diagram carries its OWN title banner INSIDE the image — see Step 4d — so there is NO external `Flow Diagram:` markdown label and NO footer label): a per-story Mermaid flowchart of THIS story's workflow → rendered PNG (with in-image title) → embedded (Step 4).
+7. **Mapped Test Cases** (the LAST section of every story — each story ENDS here): a colored table `TC ID | Type | Test Title | Expected Result` (styling in Step 4e). `TC-NNN` sequential across the whole doc; `Type` ∈ {Positive, Negative, Edge}; cover happy-path + failure + boundary; every acceptance-criteria group represented by ≥1 test case.
+
+**Pagination (MANDATORY — hard rule, exactly as stated):**
+- **Each Epic (`EP-NN`) starts a NEW PAGE** (page-break BEFORE the epic heading).
+- **The FIRST story of that epic flows on the SAME page** as the epic heading (no break between them).
+- **Each SUBSEQUENT story in the same epic starts a NEW PAGE** (page-break BEFORE that story's `PREFIX-NNN` heading).
+- Because every story ENDS with its Mapped Test Cases table, a page thus contains exactly one story (or epic-heading + first story). Enforce in `.docx` via page-break-before on epic headings and on every non-first story heading.
 
 **Heading placement + no orphans (MANDATORY layout rules):**
-- **Each section label sits ABOVE the content it introduces — never below it.** The `Flow Diagram:` label immediately PRECEDES its image; `Mapped Test Cases:` immediately PRECEDES its table; `Workflow:` precedes its steps. A label rendered after/below its block is a defect. In markdown, ensure the label line comes on the line(s) directly before the block with no intervening content.
-- **Headings must NOT be orphaned across a page break.** A section label (`Flow Diagram:`, `Mapped Test Cases:`, a story `PREFIX-NNN` title, an epic `EP-NN`) must stay on the same page as at least the first line of its content (keep-with-next). To enforce this in the `.docx` conversion, apply pandoc's page-break control: use a paragraph style / raw-openxml `keepNext` on heading paragraphs, OR insert an explicit page break BEFORE a heading that would otherwise strand at a page bottom, so the heading travels with its content. Never leave a heading alone at the foot of a page with its table/diagram/steps starting on the next.
+- **Each section label sits ABOVE the content it introduces — never below it.** `Mapped Test Cases:` immediately PRECEDES its table; `Workflow:` precedes its steps; `Acceptance Criteria:` precedes its bullets. A label rendered after/below its block is a defect. (The Flow Diagram is the EXCEPTION — it has NO external label; its title is baked into the image, Step 4d.)
+- **Headings must NOT be orphaned across a page break.** A section label (`Mapped Test Cases:`, a story `PREFIX-NNN` title, an epic `EP-NN`) must stay on the same page as at least the first line of its content (keep-with-next). Enforce with `keepNext` on heading paragraphs in the `.docx` conversion. With the pagination rule above (one story per page), orphaning is largely prevented structurally, but keep-with-next remains the backstop.
 
 **No confabulation** (`feedback_no_confabulated_examples`): every story, workflow step, and test case must trace to something in the actual input source. If the source is silent on a needed detail, mark it a `[TODO: confirm with client]` — never invent product specifics.
 
@@ -71,18 +77,16 @@ classDef newfeat   fill:#e2f0fb,stroke:#5b9bd5,color:#1f4e79,stroke-dasharray:4
 
 The whole diagram MUST fit inside the page's visible area. **Compare aspect ratios first, then clamp ONLY the constraining dimension** — this is the standard "contain" fit; it guarantees no clipping and no distortion. Do NOT eyeball it or rely on layout luck.
 
-**Page dimensions** (the visible printable area) default to **US Letter portrait content box ≈ 6.5in × 9in** (W×H, i.e. 8.5×11 minus 1in margins) unless the deliverable specifies otherwise.
-
-**⚠️ RESERVE LABEL SPACE — critical.** Every diagram has a heading label ABOVE it (`Flow Diagram:`) that must sit on the SAME page (4b keep-with-next). If the image is set to the FULL page height, there is no room for the label → keep-with-next pushes the whole image to the next page (the Newman failure). So the height the image may occupy is **`avail_height = page_height − label_reserve`**, where `label_reserve ≈ 0.5in` (heading line + gap). Use `avail_height` — NOT the full `page_height` — as the height constraint. Width is unaffected (`avail_width = page_width`). `page_AR = avail_width / avail_height`.
+**Page dimensions** (the visible printable area) default to **US Letter portrait content box ≈ 6.5in × 9in** (W×H, i.e. 8.5×11 minus 1in margins) unless the deliverable specifies otherwise. Because the diagram carries its OWN title banner INSIDE the image (Step 4d) — there is NO external label above it — the image may use the FULL page box: `avail_width = page_width`, `avail_height = page_height`. `page_AR = avail_width / avail_height`. (The one-story-per-page pagination rule means the diagram owns its page.)
 
 **Algorithm — run per rendered diagram:**
 1. **Render** the Mermaid to PNG (Step 4c), then **measure its actual pixel dimensions** `img_w × img_h` (e.g. via `sips -g pixelWidth -g pixelHeight <png>` on macOS, or `mmdc` output metadata). `img_AR = img_w / img_h`.
-2. **Compute both aspect ratios** against the **label-reserved** page box — compare SHAPES, not sizes yet.
+2. **Compute both aspect ratios** — compare SHAPES, not sizes yet.
 3. **Clamp the constraining dimension:**
-   - **If `img_AR > page_AR`** (image is *wider* than the available box) → **width is the constraint → set embedded `width = avail_width` (= page_width)** (height scales proportionally, lands ≤ avail_height). *Example: a 5-wide × 4-tall image → set width = page width.*
-   - **If `img_AR < page_AR`** (image is *taller* than the available box) → **height is the constraint → set embedded `height = avail_height` (= page_height − label_reserve, NOT full page height)** (width scales proportionally). This is what leaves room for the label above. *Example: a 2-wide × 4-tall image → set height = page_height − 0.5in.*
+   - **If `img_AR > page_AR`** (image is *wider* than the page box) → **width is the constraint → set embedded `width = avail_width` (= page_width)** (height scales proportionally, lands ≤ avail_height). *Example: a 5-wide × 4-tall image → set width = page width.*
+   - **If `img_AR < page_AR`** (image is *taller* than the page box) → **height is the constraint → set embedded `height = avail_height` (= page_height)** (width scales proportionally). *Example: a 2-wide × 4-tall image → set height = page height.*
    - **If equal** → either works; set width = avail_width.
-4. **Embed at that ONE clamped dimension** so the renderer scales the other proportionally. In markdown, use an HTML `<img>` with only the clamped side set (e.g. `<img src="media/<name>.png" width="…" />` or `height="…"`) — never set both (that distorts). For `.docx`, pandoc honors the single dimension. The label + image together now fit on one page.
+4. **Embed at that ONE clamped dimension** so the renderer scales the other proportionally. In markdown, use an HTML `<img>` with only the clamped side set (e.g. `<img src="media/<name>.png" width="…" />` or `height="…"`) — never set both (that distorts). For `.docx`, pandoc honors the single dimension.
 
 **Layout still matters as an INPUT to the ratio** (not a substitute for it): choose `flowchart LR` for long linear flows and `TD` for short ones so the rendered `img_AR` is closer to the page shape *before* clamping — this maximizes the final on-page size. But the aspect-ratio clamp above is what GUARANTEES the fit; the direction choice only optimizes how much of the page it fills.
 
@@ -94,9 +98,20 @@ Never ship a diagram wider or taller than the page (`feedback_no_silent_degradat
 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. **Measure + clamp per the 4b aspect-ratio algorithm:** read the rendered PNG's pixel `img_w × img_h` (`sips -g pixelWidth -g pixelHeight share/media/<name>.png`), compute `img_AR` vs `page_AR`, and pick the ONE clamped dimension (width=page_width if wider, else height=page_height).
-5. Embed each rendered PNG at that clamped dimension using an HTML `<img>` with only the constraining side set — e.g. `<img src="media/<name>.png" width="6.5in" />` OR `<img src="media/<name>.png" height="9in" />` (never both). Place it at the `Flow Diagram:` / §1 position.
+5. Embed each rendered PNG at that clamped dimension using an HTML `<img>` with only the constraining side set — e.g. `<img src="media/<name>.png" width="6.5in" />` OR `<img src="media/<name>.png" height="9in" />` (never both). Place it directly where the story's diagram belongs — with NO external `Flow Diagram:` label and NO footer label (the title is in the image, Step 4d).
 6. Keep the `.mmd` source (editable, version-controllable) alongside the PNG.
 
+### 4d. In-image title banner (MANDATORY — replaces the external Flow Diagram label)
+
+Each per-story diagram carries its OWN title INSIDE the rendered image — a filled banner at the TOP showing the story id + title (matching the sample: `NWMN-003` bold on line 1, the story title on line 2, on a light-purple fill). This lets the doc DROP the external `Flow Diagram:` markdown label AND any footer label. Implement as the first node(s) of the flowchart, styled as the banner (a full-width `screen`-class node with the two lines), OR via a mermaid `title`/subgraph header styled to match. Font: bold id line + regular title line, dark-purple text (`#2d2160`) on light-purple fill (`#ece9fb`) — the `screen` classDef. The app-flow chart (§1) gets a matching banner with the product name.
+
+### 4e. Mapped Test Cases table coloring (MANDATORY)
+
+The test-case table is COLORED, not plain (matching the sample):
+- **Header row:** white bold text on a **purple gradient / solid purple fill** (`#7c5cfc`-ish), all four columns.
+- **`Type` cell tinted by value:** **Positive → green** (`#e6f4ea` fill, green text) · **Negative → peach/orange** (`#fdecd8` fill, amber text) · **Edge → blue** (`#e2eefb` fill, blue text). Only the Type cell is tinted; other cells stay white with normal text.
+- Markdown tables can't carry cell fills, so for the `.docx` this coloring is applied at conversion (a pandoc pipeline / post-process on the table), OR the table is authored as raw HTML with inline styles that pandoc converts to Word table shading. Keep the plain-markdown table as the editable source; apply the color styling in the rendered/delivered output.
+
 ## Step 5: Assemble + Deliver
 
 1. Assemble front matter (product, "Prepared by Tekyz Inc.", version, source-of-truth note; SAMPLE disclaimer only if illustrative) + §1 + §2 + §3.

package/package.json

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

@@ -92,9 +92,30 @@ embedded (`![Flow Diagram](media/<PREFIX>-NNN-flow.png)`) — matching the sampl
 - Cover the happy path (Positive), failure modes (Negative), and boundaries (Edge). Every
   acceptance-criteria group should be represented by at least one test case.
 
+### Pagination (MANDATORY — hard rule)
+
+- Each Epic (`EP-NN`) starts a NEW PAGE (page-break before the epic heading).
+- The FIRST story of that epic flows on the SAME page as the epic heading.
+- Each SUBSEQUENT story in the same epic starts a NEW PAGE.
+- Every story ENDS with its Mapped Test Cases table → one story per page (or epic-head + first story).
+  Enforce in `.docx` with page-break-before on epic headings + every non-first story heading.
+
+### Diagram carries its own in-image title (MANDATORY)
+
+Each per-story diagram has a TITLE BANNER inside the rendered image (story id bold + title, dark-purple
+on light-purple `screen`-class fill) — matching the sample. So there is NO external `Flow Diagram:`
+label and NO footer label; the diagram is self-titled. The §1 app-flow chart gets a matching banner
+with the product name. Because the image is self-titled, it may use the FULL page box (no label-reserve).
+
+### Mapped Test Cases coloring (MANDATORY)
+
+Header row = white bold on purple fill (all 4 cols). `Type` cell tinted by value: Positive→green,
+Negative→peach, Edge→blue (only the Type cell). Keep the plain-markdown table as editable source;
+apply cell shading in the delivered `.docx` (raw-HTML table or pandoc post-process).
+
 ### Heading placement + no orphans (MANDATORY)
 
-- Every section label sits ABOVE its content, never below. `Flow Diagram:` precedes its image;
+- Every non-diagram section label sits ABOVE its content, never below.
   `Mapped Test Cases:` precedes its table; `Workflow:` precedes its steps. A label below the
   block it introduces is a defect.
 - A heading must NOT be orphaned at a page bottom with its content on the next page — it stays
@@ -139,21 +160,18 @@ terminals are round `([...])`; label decision-branch edges (`-->|Yes|`).
 Compare aspect ratios FIRST, then clamp only the constraining dimension (standard "contain" fit —
 no clipping, no distortion). Page = visible content box, default US Letter portrait ≈ 6.5in × 9in (W×H).
 
-**RESERVE LABEL SPACE:** each diagram's `Flow Diagram:` label sits above it on the same page. If the
-image is set to FULL page height, no room is left for the label and keep-with-next pushes the image to
-the next page (the Newman bug). So use `avail_height = page_height − label_reserve` (label_reserve ≈
-0.5in) as the height constraint, NOT full page_height. `avail_width = page_width`;
-`page_AR = avail_width / avail_height`.
+**FULL page box** — the diagram is self-titled (in-image banner, no external label), so it uses the
+full page: `avail_width = page_width`, `avail_height = page_height` (no label-reserve). `page_AR =
+avail_width / avail_height`. *(A label-reserve was needed only when an external `Flow Diagram:` label
+sat above the image — the in-image title removed that need.)*
 
 1. Render to PNG, then MEASURE its pixels `img_w × img_h` (`sips -g pixelWidth -g pixelHeight`);
    `img_AR = img_w / img_h`.
-2. Compare shapes against the label-reserved box:
+2. Compare shapes:
    - `img_AR > page_AR` (wider) → **set width = avail_width (= page_width)** (height scales, fits).
-   - `img_AR < page_AR` (taller) → **set height = avail_height (= page_height − 0.5in, NOT full page)**
-     (width scales) — this leaves room for the label above.
+   - `img_AR < page_AR` (taller) → **set height = avail_height (= page_height)** (width scales, fits).
    - equal → set width = avail_width.
-3. Embed with ONLY the clamped side set (`<img … width>` OR `height`, never both). Label + image fit
-   on one page.
+3. Embed with ONLY the clamped side set (`<img … width>` OR `height`, never both).
 
 Direction (`LR` for long flows, `TD` for short) is chosen to bring `img_AR` closer to `page_AR`
 BEFORE clamping (maximizes final on-page size) — but the ratio clamp is what guarantees the fit.
@@ -167,7 +185,8 @@ Never ship a diagram larger than the page.
    --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)`.
+3. Embed the PNG with an `<img>` at the clamped dimension, NO external label (title is in-image):
+   `<img src="media/<name>.png" width="…" />` or `height="…"`.
 4. On `.docx` conversion, pandoc embeds these PNGs as real Word images — matching the sample.
 
 Keep the `.mmd` source (version-controllable, editable) alongside the rendered PNG.