@tekyzinc/gsd-t 4.19.11 → 4.19.13

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [4.19.13] - 2026-07-07
+
+### Fixed — `/gsd-t-stories`: reserve label space when a diagram is height-constrained
+
+The aspect-ratio "contain" fit (v4.19.12) set a tall image to the FULL page height, leaving no room for the `Flow Diagram:` label above it — so keep-with-next pushed the whole image to the next page (observed on Newman). The height constraint is now `avail_height = page_height − label_reserve` (label_reserve ≈ 0.5in) instead of full page height, so the label + image always fit on one page. Width-constrained images are unaffected.
+
+- `commands/gsd-t-stories.md`: Step 4b — label-reserved page box (`avail_height`), clamp height to it not full page.
+- `templates/playbooks/tekyz-user-stories-format.md`: same.
+
+## [4.19.12] - 2026-07-07
+
+### Fixed — `/gsd-t-stories` diagrams: deterministic aspect-ratio fit + heading placement + no orphans
+
+Three layout corrections. **(1) Fit-to-page** rewritten from the vague "prefer LR / verify not clipped" heuristic to the deterministic **aspect-ratio "contain"** algorithm: measure the rendered PNG's pixel W×H, compare `img_AR` to the page aspect ratio, and clamp ONLY the constraining dimension (`width = page_width` if the image is wider than the page, else `height = page_height`) — embedded via an HTML `<img>` with a single dimension so it always fits with no clipping or distortion. **(2) Heading placement** — each section label (`Story:`, `Workflow:`, `Flow Diagram:`, `Mapped Test Cases:`) must sit ABOVE its content, never below the block it introduces. **(3) No orphaned headings** — a heading must stay with its first content on the same page (keep-with-next).
+
+- `commands/gsd-t-stories.md`: Step 4b aspect-ratio algorithm + 4c measure/clamp/embed; heading-order + orphan-control rules.
+- `templates/playbooks/tekyz-user-stories-format.md`: same.
+
 ## [4.19.11] - 2026-07-07
 
 ### Fixed — `/gsd-t-stories` diagrams: semantic coloring + fit-to-page

package/README.md

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

@@ -35,6 +35,10 @@ For EACH story, author in EXACTLY this order (per the format reference):
 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.
 
+**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.
+
 **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.
 
 ## Step 3: Scope Summary (§3)
@@ -63,22 +67,35 @@ classDef newfeat   fill:#e2f0fb,stroke:#5b9bd5,color:#1f4e79,stroke-dasharray:4
 - 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)
+### 4b. Fit-to-page by ASPECT-RATIO CONTAIN (MANDATORY — the deterministic method)
+
+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`.
+
+**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.
+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 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.
 
-A long top-down flow overflows the page (the failure the user flagged). Keep EVERY diagram fully on one page:
+**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.
 
-- **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`).
+Never ship a diagram wider or taller than the page (`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.
+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.
+6. Keep the `.mmd` source (editable, version-controllable) alongside the PNG.
 
 ## Step 5: Assemble + Deliver
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "4.19.11",
+  "version": "4.19.13",
   "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,6 +92,15 @@ 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.
 
+### Heading placement + no orphans (MANDATORY)
+
+- Every section label sits ABOVE its content, never below. `Flow Diagram:` precedes its image;
+  `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
+  with at least the first line of its content (keep-with-next). In `.docx`, enforce with
+  `keepNext` on heading paragraphs or an explicit page break before a heading that would strand.
+
 ---
 
 ## §3 — Scope Summary
@@ -125,13 +134,30 @@ Green = go/success/action · Orange = decision · Red = destructive/irreversible
 = 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.
+### Fit-to-page by ASPECT-RATIO CONTAIN (MANDATORY — deterministic)
+
+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`.
+
+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:
+   - `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.
+   - 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.
+
+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.
+Never ship a diagram larger than the page.
 
 ### Render