@tekyzinc/gsd-t 4.19.12 → 4.19.13

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 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

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v4.19.12** - 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

@@ -71,16 +71,18 @@ 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. `page_AR = page_width / page_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.
+
+**⚠️ 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** — compare SHAPES, not sizes yet.
+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 page shape) → **width is the constraint → set embedded `width = page_width`** (height scales proportionally, lands ≤ page_height). *Example: a 5-wide × 4-tall image on a 4:3 page → set width = page width.*
-   - **If `img_AR < page_AR`** (image is *taller* than the page shape) → **height is the constraint → set embedded `height = page_height`** (width scales proportionally, lands ≤ page_width). *Example: a 2-wide × 4-tall image on a 4:3 page → set height = page height.*
-   - **If equal** → either dimension works; set width = page_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.
+   - **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.
 
 **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.
 

package/package.json

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

@@ -137,18 +137,23 @@ terminals are round `([...])`; label decision-branch edges (`-->|Yes|`).
 ### 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); `page_AR = page_w / page_h`.
+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:
-   - `img_AR > page_AR` (wider than page) → **set width = page_width** (height scales, fits).
-     e.g. 5w×4h image on a 4:3 page → width = page width.
-   - `img_AR < page_AR` (taller than page) → **set height = page_height** (width scales, fits).
-     e.g. 2w×4h image on a 4:3 page → height = page height.
-   - equal → set width = page_width.
-3. Embed with ONLY the clamped side set (`<img … width>` OR `height`, never both).
+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.