@tekyzinc/gsd-t 5.14.11 → 5.16.11

package/CHANGELOG.md

@@ -2,6 +2,182 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.16.11] - 2026-08-27
+
+### Fixed — the voice fix was the wrong fix, and the gate was measuring the wrong thing
+
+Both corrections came from running the shipped pipeline against real work, and
+both invalidate advice published hours earlier in 5.16.10.
+
+**Pick a text-to-speech service whose voice is a fixed trained speaker.** The
+source run had fought drift with batching — 8 sentences per request so one
+request meant one performance, audio split back apart on silences, splits
+verified, whole takes re-rendered when they measured as drifted. All of that was
+mitigation for a property of the wrong kind of service. A language model's audio
+output treats a voice name as a style hint it re-interprets on every request, so
+the narrator genuinely changes part-way through a video; batching reduces how
+often that happens and cannot stop it, because a batch boundary is still a
+boundary between two readings. Moving to a dedicated speech service, where a
+voice id is a fixed trained speaker, ended it in one change — and took batch
+boundaries, silence splitting, miscut clips and per-model daily quotas with it.
+One sentence per request became both the simple thing and the correct thing. The
+batching guidance is kept, demoted to what to do when you cannot switch.
+
+**Gate on mean pitch, not within-video pitch spread.** The published gate failed
+**nine of the twelve videos its own project had already shipped** — every one
+confirmed by ear as a single steady narrator. A ±35 Hz spread threshold is right
+for a language-model TTS, where a wide spread means a different reading, and
+wrong for a fixed speaker, where it measures ordinary sentence intonation: a
+question rising, a list falling, a short line sitting higher. Flattening that
+would make the narration robotic. The speaker-identity signal is the mean, which
+across those twelve videos sat inside a 7 Hz band. So the gate now checks the
+mean against a calibrated band and reports the spread without gating it — ten of
+twelve pass, and the two that still fail do so on volume, which is real.
+
+The rule this produces, now in the command: **calibrate a gate against output a
+human has already approved before trusting it.** A gate that fails most of your
+known-good work is measuring the wrong thing, and believing it costs you
+re-rendering audio that was already correct.
+
+**Narration lines must be full sentences of 8 words or more.** Integrated
+loudness needs enough audio to measure against; a two-word clip ("Create
+Curriculum.") lands off target, blows the video's volume spread and trips the
+miscut check. This cost two full render cycles before it was diagnosed. When a
+step needs an action the narration does not describe, run it untimed rather than
+inventing a stub line.
+
+**Templates:** `choose()` opens a dropdown, holds it open long enough to read,
+and picks — the choice is the most informative moment in a create-flow, and a
+highlighted select shows the viewer nothing. `enter()` types a value visibly
+rather than filling it instantly. `act()` performs either outside a narrated
+beat, because both only build an action and a bare `await` on one silently does
+nothing. New `cast.mjs` carries every name said aloud in one place.
+
+**Narration guidance rewritten around two woven stories** — the operator's, told
+in their own voice and shown on screen, and the customer's, which is why every
+value typed is that value. The test: a sentence that survives with the names
+removed is explaining the software, not telling the story.
+
+- `commands/gsd-t-demo-videos.md`: Stage 1 rewritten; cast step gains the
+  two-story weave, the products/pricing rule and the dropdown mandate
+- `templates/demo-videos/e2e/cast.mjs`: new
+- `templates/demo-videos/e2e/runtime.ts`: `enter()`, `choose()`, `act()`
+- `templates/demo-videos/e2e/example.{lines.mjs,spec.ts}`: rewritten as a story
+
+## [5.16.10] - 2026-08-27
+
+### Added — `/gsd-t-demo-videos`, narrated walkthrough videos of a running app
+
+Distilled from a real production run that shipped twelve narrated walkthroughs
+of a live application over two long sessions. Nearly every re-record in that run
+traced back to one of ten mistakes, so each is now a gate rather than a lesson
+to be re-learned.
+
+**Narration is the master clock.** A step lasts exactly as long as its measured
+spoken sentence — never a constant, never an estimate. The first version of that
+pipeline gave every step a fixed five seconds, and that single number is why the
+words drifted away from the picture. It also assembled the video from per-screen
+clips and stills, which cannot show a transition or how the interface actually
+behaves. One continuous recording per walkthrough, clipped afterward.
+
+**The voice was the expensive problem, and its cause was confirmed.** The
+narrator audibly changed tone and volume partway through a video because every
+sentence was a separate API call, so the model re-decided its delivery dozens of
+times. Describing the speaker in the prompt did not fix it. Two deterministic
+fixes replace it:
+
+- **Batched.** Eight sentences per request, numbered, with an instruction to
+  leave two seconds of silence between them; the audio is cut back apart on
+  those silences and the split is verified, never assumed. Eight is measured:
+  the same eighteen-line script rendered as a single take spread 46 Hz of pitch,
+  and in eight-line batches spread 16 Hz — the narrator holds around 100-115 Hz
+  for a dozen lines and then slips to 140, losing the persona the further it
+  gets from the instruction.
+- **Normalised.** Every clip goes through a two-pass loudnorm to the same target
+  loudness. Within-video volume drift went from as much as 7.5 dB to about
+  0.5 dB, and every video now sits at the same level as the others.
+
+**The check is the gate, not the report.** Loudness, pitch and speaking rate are
+measured per clip and the spread reported across the video, along with miscut
+clips whose length does not match what their sentence should take to say. A take
+that drifts is thrown away and re-rendered, up to three times, then halts rather
+than shipping. This is not theoretical — one video's first take came back at
+46 Hz and was discarded for a 15 Hz one. It exists because two renders of the
+same prompt genuinely differ: a "persona anchor" prompt looked like a large win
+on one A/B run and reversed on the next.
+
+**Other gates, each from a failure it would have prevented:**
+
+- A preflight walks every selector without recording. One bad selector used to
+  fail a whole six-minute recording at the first sentence whose target was
+  missing, so three bad selectors cost three recordings to find.
+- The runtime throws when a narrated sentence has no visible target, and asserts
+  the page as well. Narration had repeatedly described screens the spec never
+  opened, and a failed click produced confident narration about a screen that
+  was never on camera.
+- Silence removal is mandatory after every mux. Page loads left 20-60 seconds of
+  dead air per video — 7.4 minutes across twelve.
+- When a recording fails, look at the failure screenshot the run already saved.
+  Every wrong theory in the source run came from reasoning about the DOM
+  instead; one three-recording failure was diagnosed twice-wrongly before the
+  screenshot showed the answer immediately.
+- Coverage is planned against the running app, not the code. The first nine
+  videos covered about 25 of 55 populated screens, and probing the live site
+  reversed four of five "this screen is empty" verdicts that had been written
+  from the seed scripts.
+- Seeders drive the real forms as a real user, and report a refusal instead of
+  working around it. One such refusal turned out to be a genuine app bug: an
+  enabled button whose click handler was inert.
+
+**The pipeline ships as templates**, not as prose to re-implement:
+`templates/demo-videos/` carries the seven scripts and six test files with the
+reasoning for every threshold in their headers. The command resolves them
+through the installed package directory and halts if they are absent.
+
+## [5.15.10] - 2026-08-27
+
+### Added — open questions, a fourth build status, and a fallbacks column
+
+Four corrections from running the client-deliverable gap analysis live on a
+second project.
+
+**Open questions.** Column D now ends with an `OPEN QUESTIONS:` block: the
+decisions someone must make before the work can be built or priced — which
+settings are non-overridable, whether a mid-enrollment version change moves the
+student. Six of eight rows on the proven sheet carry one. A row without the
+block is asserting there are no unknowns, which is usually false; the test is
+whether two reasonable people could build the row differently from what it
+says. Questions are never invented to fill the block and never self-answered —
+an unknown resolved by assumption is an assumption, and belongs in the
+requirement bullets.
+
+**A fourth build status, and a colour for it.** The status list carried four
+values inherited from report mode while only three had colours, so `Incorrect`
+rendered plain. Now green Implemented, yellow Partial, light-blue Incorrect,
+red Not Implemented. Incorrect is not a shade of Partial: Partial needs
+finishing, Incorrect needs undoing first, and pricing them alike understates
+the second. Both must name specifics.
+
+**Fallbacks in the shipped code (column P).** For every feature with code, the
+places that code continues after a failure — the branches that make a system do
+something quietly wrong instead of stopping. Reuses the existing detector.
+Three states, not two: **approved** (recorded with a written reason),
+**pre-existing** (grandfathered when the rule was adopted — not approved,
+merely old, and still a finding for a client), and **unapproved**. A fallback
+that contradicts the row's own requirements is the strongest finding on the
+sheet; the requirements already ban several by name. A feature with no code
+gets a blank cell, never "none", which reads as a clean result.
+
+**Column layout.** Fallbacks take P, where an earlier sheet held Scope and then
+hardening tasks; hardening moves to Q. Columns A, B and C are the reading
+columns and are now specified exactly — bold feature name, blank line, italic
+purpose — with the purpose verb tracking build status, conditional on an
+unbuilt row and present tense on a built one. A column map under the mode table
+states the layout once instead of restating it per step.
+
+- `commands/gsd-t-gap-analysis.md`
+- `.gsd-t/pseudocode/PseudoCode-GapAnalysis.md`
+
 ## [5.14.11] - 2026-08-25
 
 ### Fixed — gap analysis harvests the tracker instead of asking for a spec

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v5.14.11** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v5.16.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.
@@ -186,6 +186,7 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 | `/gsd-t-promote-debt` | Convert techdebt items to milestones | Manual |
 | `/gsd-t-estimate` | Turn any work doc (scan, requirements, feature/app spec) into a Tekyz client estimate (Google Sheet: T-Shirt Size + Team Mix) + matching PRD — supervised, with an operator-arbitrated Estimate Red Team | Manual |
 | `/gsd-t-stories` | Generate a dev-team handoff doc in the Tekyz user-stories format (stories + workflows + acceptance criteria + Mermaid flow diagrams + mapped test cases) from any source | Manual |
+| `/gsd-t-demo-videos` | Narrated screen-recording walkthroughs of a running app — coverage plan, UI-driven seeding, batched TTS with a measured one-voice gate, continuous recording, mux, silence trim | Manual |
 | `/gsd-t-populate` | Auto-populate docs from existing codebase | Manual |
 | `/gsd-t-design-decompose` | Decompose design into element/widget/page contracts | Manual |