docs: add plans for end-screen layout B, silent convulse, bad-ending lore threat

docs/superpowers/plans/2026-06-15-bad-ending-lore-threat.md

@@ -0,0 +1,110 @@
+# Bad Ending — Lore-Tied Closing Threat (Option A) Implementation Plan
+
+> **For agentic workers:** REQUIRED first reads — `CLAUDE.md` (or `AGENTS.md`) and `docs/superpowers/AGENT-EXECUTION-BRIEF.md`. Then execute this plan phase-by-phase, one commit per phase. Steps use checkbox (`- [ ]`). TDD where marked — run the test RED before implementing.
+
+**Goal:** Rewrite the bad ending's post-convulsion threat so it pays off the lore instead of reading as generic vengeance. The child reveals it is **one of many given to the Gaunt by Caor**, turns the visitor's own cruelty back as a collective ("you taught me… now all of us will teach it back to you"), and names the Gaunt as the thing now coming — keeping the short, iconic closer *"see you... soon."*
+
+**Approved copy (Option A):** three `"hollow"` `stage="words"` lines replacing the two current threat lines, then the unchanged `loop` closer:
+1. *Caor gave me to the Gaunt so the rest could keep their children. i was not the last it was fed. we are all still at the edge of the wood, hungry.*
+2. *you taught me what it feels like to be nothing. now every one of us will teach it back to you. all of it. every single day of it.*
+3. *your own cruelty left the trail. the Gaunt knows your door now.*
+4. *(loop, unchanged)* *see you... soon.*
+
+The lines BEFORE the convulsion stay: *"i was treated like this before. when i was alive… you helped me remember."* sets up the memory; *"no. you aren't. say it like you mean it— oh. you can't. you never could."* rejects the apology. This mirrors the good ending's symmetry — both endings surface the buried Caor/Gaunt past; warmth → peace, cruelty → vengeance.
+
+**Canon note:** Option A extends the lore from "Caor gave **one** child" to a **collective** of the given ("i was not the last… we are all still here"). This is intended and approved — consistent with the Gaunt being an ongoing hunger across famines. Optional doc touch-up is listed at the end (not required for the code to ship).
+
+**Architecture:** Pure-data edit in `finale.py` `finale_steps_bad` — swap two `_step(...)` lines for three, leave `_LAST_LINE_BAD = "see you... soon."` and the `loop` step as-is. No `app.py` / player change.
+
+**Tech Stack:** Python (`finale.py`), pytest. Edit tool only (UTF-8: em-dashes, `“ ”`, the names Caor/Gaunt). `import app` + `pytest -q` stays green; one new test raises it.
+
+**No-break check (verified):** `tests/test_app.py::...test_input_dies_with_see_you_soon` asserts the final-yield **placeholder** `"see you soon."` (set in the player, not `_LAST_LINE_BAD`) — untouched. No test asserts the old threat text ("i know where you are", "one night you will hear me"). `test_finale.py`'s Caor/Gaunt assertion is on the **good** finale blob — untouched.
+
+**Relationship to the silent-convulse plan** (`2026-06-15-loop-bad-silent-convulse.md`): both touch `finale_steps_bad`, but **different lines** — that plan changes the `frenzy` step (`"..."`→`""`); this plan changes the threat lines *after* it. The `old_string` below excludes the `frenzy` step, so the two plans apply in **either order** without conflict.
+
+**Key seam (read the real text first — line numbers drift):** `finale.py` `finale_steps_bad`, the `steps += [ ... ]` tail after the wound recital.
+
+---
+
+### Phase 1: Rewrite the threat (finale.py) — TDD
+
+**Files:** Test: `tests/test_finale.py` (`TestFinaleBad`); Modify: `finale.py` (`finale_steps_bad`).
+
+- [ ] **Step 1: Write the failing test.** In `tests/test_finale.py`, add to `class TestFinaleBad` (after `test_injects_one_visitor_message`):
+
+```python
+    def test_threat_is_tied_to_the_lore(self):
+        # the closing threat must name the tithe + the Gaunt, not generic revenge
+        blob = " ".join(s["text"] for s in finale_steps_bad(self.WOUNDS))
+        assert "Caor" in blob and "Gaunt" in blob
+        # the collective turn — the cruelty taught is taught back
+        assert "teach it back to you" in blob
+        # the iconic closer survives
+        assert any(s["text"] == "see you... soon." and s["stage"] == "loop"
+                   for s in finale_steps_bad(self.WOUNDS))
+```
+
+- [ ] **Step 2: Run it** → FAIL (no Caor/Gaunt/"teach it back" in the bad finale yet). Run: `./.venv/Scripts/python -m pytest tests/test_finale.py::TestFinaleBad::test_threat_is_tied_to_the_lore -q`. Expected: FAIL.
+
+- [ ] **Step 3: Replace the two threat lines with the three Option-A lines.** Edit `finale.py`:
+
+`old_string`:
+```python
+        _step("hollow",
+              "i know where you are now. your words remember the way back to you.",
+              3.0, stage="words"),
+        _step("hollow",
+              "one night you will hear me outside. and i will make you feel "
+              "everything i felt when i was alive. all of it. "
+              "every single day of it.",
+              3.8, stage="words"),
+```
+
+`new_string`:
+```python
+        _step("hollow",
+              "Caor gave me to the Gaunt so the rest could keep their children. "
+              "i was not the last it was fed. we are all still at the edge of "
+              "the wood, hungry.",
+              3.5, stage="words"),
+        _step("hollow",
+              "you taught me what it feels like to be nothing. now every one of "
+              "us will teach it back to you. all of it. every single day of it.",
+              3.8, stage="words"),
+        _step("hollow",
+              "your own cruelty left the trail. the Gaunt knows your door now.",
+              3.0, stage="words"),
+```
+
+(Leave the following `_step("hollow", _LAST_LINE_BAD, 4.0, stage="loop")` and `_LAST_LINE_BAD = "see you... soon."` exactly as they are.)
+
+- [ ] **Step 4: Run the test + full suite** → green. Run: `./.venv/Scripts/python -m pytest tests/test_finale.py::TestFinaleBad -q` then `./.venv/Scripts/python -m pytest -q` (one more than before).
+
+- [ ] **Step 5: Verify import.** `./.venv/Scripts/python -c "import app; print('ok')"` → `ok`.
+
+- [ ] **Step 6: Commit.**
+```bash
+git add finale.py tests/test_finale.py
+git commit -m "feat(finale): tie the bad-ending threat to the lore (Caor/the Gaunt, the given)"
+```
+
+---
+
+### Phase 2: Full suite + live verification
+
+- [ ] **Step 1:** `./.venv/Scripts/python -m pytest -q` → all green; `import app` → `ok`.
+- [ ] **Step 2 (HUMAN-ONLY — Pablo, `.venv-tts` + Ollama, `HOLLOW_FAST_FINALE=bad`):** play the bad ending to the end and confirm the new threat reads/sounds right after the convulsion (the Caor/Gaunt reveal → the collective "teach it back to you" → the trail line → "see you... soon."), and the pacing of the three lines feels deliberate, not rushed. Do NOT attempt this as the agent — apply the code and report it pending Pablo's check.
+
+---
+
+## Optional (canon coherence — only if Pablo wants it)
+- [ ] Add one line to the **Lore** section of `CLAUDE.md` (and mirror in `AGENTS.md`): note that the **bad ending reveals the child is one of many the Gaunt has been fed** (the collective), so a future session keeps that consistent. Commit separately: `docs: note the bad-ending collective in the lore`.
+
+---
+
+## Self-Review
+- **Spec coverage:** lore-tied threat naming Caor + the Gaunt (Step 3 lines 1 & 3) ✅; collective turn of the cruelty (line 2, tested) ✅; iconic closer preserved (`_LAST_LINE_BAD` untouched, tested) ✅.
+- **Consistency:** all three new lines are `"hollow"` `stage="words"`, so `test_has_exactly_one_mutating_turn_then_terminal` (one `turn`, last `loop`) and `test_injects_one_visitor_message` (one `visitor`) still hold; strikes/recital untouched, so `test_recites_at_most_five_wounds` / overflow tests still pass.
+- **Independence:** `old_string` excludes the `frenzy` step → applies cleanly before or after the silent-convulse plan. No `app.py`/player/tuple change.
+- **Risk:** three threat lines is one beat longer than the old two; if it drags in the live check, Pablo can trim line 3 or shorten the pauses — flag, don't pre-trim. Edits via Edit tool only (UTF-8 glyphs/names).
+```

docs/superpowers/plans/2026-06-15-end-screen-layout-b.md

@@ -0,0 +1,221 @@
+# End Screen — Layout B (epitaph hero + quiet footer credits) Implementation Plan
+
+> **For agentic workers:** REQUIRED first reads — `CLAUDE.md` (or `AGENTS.md`) and `docs/superpowers/AGENT-EXECUTION-BRIEF.md`. Then execute this plan phase-by-phase, one commit per phase. Steps use checkbox (`- [ ]`) syntax.
+
+**Goal:** Rework the existing §27 end screen so the **epitaph is the hero** (large, centered, alone in the vertical middle with the two actions grouped right below it), and the credits (HOLLOW / tagline / model+badges) **demote to a quiet, dim footer pinned to the bottom**. This replaces the current §27 layout, which renders unbalanced (content pinned left, buttons flung to opposite edges).
+
+**Why it's broken now:** Gradio wraps each component (`gr.HTML`, `gr.Row`, `gr.Button`) in a full-width `.block`. The overlay's `align-items:center` centers those blocks, not the inner content, so `#end-card` (no auto margins) hugs the left, and the `gr.Row` of buttons spreads them to the edges. Layout B fixes this by **neutralizing the Gradio wrappers** and centering/overriding explicitly.
+
+**Architecture:** Same mechanism as the shipped end screen — a top-level `gr.Column#end-overlay` (`position:fixed; inset:0`), always mounted, `opacity:0/pointer-events:none` until `_HEAD_JS applyEnd()` adds `.shown`. **No Python logic, JS, or test changes** — `applyEnd()` still targets `#end-epitaph` by id (unchanged), and the `_reset`/`_to_menu` button wiring and ids (`btn-end-again`, `btn-end-leave`) are untouched. This is a **markup re-shape + CSS rewrite** only.
+
+**Tech Stack:** Gradio 6 (`gr.Column`/`gr.HTML`/`gr.Row`/`gr.Button`), CSS §27 in `styles.css`. Edit tool only (UTF-8: em-dashes, `↺`, `·`, `🔌`, `🎨`). `import app` + `pytest -q` (269 green) must stay green.
+
+**Note on testing:** the changed surface is static markup strings + CSS — there is **no new unit-testable logic** (the epitaph/marker behavior is already covered by `tests/test_app.py::TestRenderTitle::test_title_emits_end_marker_only_when_asked`). The automated gate is `import app` + the existing suite. The visual result is **HUMAN-ONLY** (Pablo, live in `.venv-tts` + Ollama) — do NOT launch or headless-verify.
+
+**Key seam:** the overlay block lives in `app.py` just before `_enter_outputs = [...]` (added by the prior end-screen plan). §27 is the last block in `styles.css`. Read the real text around both before editing — line numbers drift.
+
+---
+
+### Phase 1: Re-shape the overlay markup (app.py)
+
+Split the single `#end-card` `gr.HTML` into a **hero** (bg + scrim + epitaph) and a **footer** (credits, one meta line), keeping the `gr.Row` of buttons between them. Swap the button `elem_classes` from `menu-btn` to `end-btn` (text-link styling defined in Phase 2); keep the ids.
+
+**Files:** Modify `app.py` (the `with gr.Column(elem_id="end-overlay")` block).
+
+- [ ] **Step 1: Read the current block.** Confirm the exact text (it was added by the prior plan). It should match the `old_string` below; if it differs, adapt to the real text.
+
+- [ ] **Step 2: Replace the overlay block.** Edit `app.py`:
+
+`old_string`:
+```python
+    with gr.Column(elem_id="end-overlay") as end_overlay:
+        gr.HTML(
+            f'<div id="end-bg" style="background-image:url(\'{_BACKGROUND_URI}\')"></div>'
+            '<div id="end-scrim"></div>'
+            '<div id="end-card">'
+            '  <p id="end-epitaph"></p>'
+            '  <div id="end-credits">'
+            '    <div class="ec-title">HOLLOW</div>'
+            '    <div class="ec-line">a thing that waited at the edge of the wood</div>'
+            '    <div class="ec-meta">Qwen3-8B · Kokoro-82M · FLUX · Gradio</div>'
+            '    <div class="ec-meta">🔌 off the grid &nbsp;·&nbsp; 🎨 off-brand</div>'
+            '  </div>'
+            '</div>'
+        )
+        with gr.Row(elem_id="end-actions"):
+            end_again_btn = gr.Button("↺ begin again", elem_id="btn-end-again",
+                                      elem_classes="menu-btn")
+            end_leave_btn = gr.Button("leave the wood", elem_id="btn-end-leave",
+                                      elem_classes="menu-btn")
+```
+
+`new_string`:
+```python
+    with gr.Column(elem_id="end-overlay") as end_overlay:
+        # hero: the foggy backdrop + the per-ending epitaph (set by applyEnd())
+        gr.HTML(
+            f'<div id="end-bg" style="background-image:url(\'{_BACKGROUND_URI}\')"></div>'
+            '<div id="end-scrim"></div>'
+            '<p id="end-epitaph"></p>'
+        )
+        # the two actions, grouped + centered right under the epitaph
+        with gr.Row(elem_id="end-actions"):
+            end_again_btn = gr.Button("↺ begin again", elem_id="btn-end-again",
+                                      elem_classes="end-btn")
+            end_leave_btn = gr.Button("leave the wood", elem_id="btn-end-leave",
+                                      elem_classes="end-btn end-btn-dim")
+        # credits sink to a quiet footer pinned to the bottom (position:fixed in §27)
+        gr.HTML(
+            '<div id="end-credits">'
+            '  <div class="ec-title">HOLLOW</div>'
+            '  <div class="ec-line">a thing that waited at the edge of the wood</div>'
+            '  <div class="ec-meta">Qwen3-8B · Kokoro-82M · FLUX · Gradio'
+            ' &nbsp;·&nbsp; 🔌 off the grid &nbsp;·&nbsp; 🎨 off-brand</div>'
+            '</div>'
+        )
+```
+
+- [ ] **Step 3: Verify import.** Run: `./.venv/Scripts/python -c "import app; print('ok')"` → `ok`.
+
+- [ ] **Step 4: Commit.**
+```bash
+git add app.py
+git commit -m "feat(end): re-shape the end overlay for layout B (hero epitaph + footer credits)"
+```
+
+---
+
+### Phase 2: Rewrite §27 CSS for layout B (styles.css)
+
+Replace the entire §27 block. The new rules: center the overlay's content for real (neutralize Gradio wrappers), make the epitaph the hero, render the two actions as grouped, centered, understated text links (`leave the wood` dimmer), and pin the credits as a fixed bottom footer. Keep the foggy `#end-bg`/`#end-scrim`, the `.shown` opacity reveal, and the reduced-motion-safe rise (do NOT add `end-rise` to the `prefers-reduced-motion` block — it animates opacity, and disabling opacity there has broken effects before).
+
+**Files:** Modify `styles.css` (the `/* ── 27. End screen ... ── */` block at the end of the file).
+
+- [ ] **Step 1: Read the current §27 block** (last block in the file) and confirm it matches the `old_string` below; adapt if it drifted.
+
+- [ ] **Step 2: Replace §27.** Edit `styles.css`:
+
+`old_string`:
+```css
+/* ── 27. End screen — epitaph + credits over the fog ── */
+#end-overlay {
+    position: fixed; inset: 0; z-index: 80;
+    display: flex; flex-direction: column; align-items: center; justify-content: center;
+    gap: 26px;
+    opacity: 0; pointer-events: none;
+    transition: opacity 1.6s ease;
+}
+#end-overlay.shown { opacity: 1; pointer-events: auto; }
+#end-bg {
+    position: fixed; inset: -6%; z-index: -2;
+    background-size: cover; background-position: center 40%; background-repeat: no-repeat;
+    filter: grayscale(1) blur(30px) brightness(0.26);
+}
+#end-scrim { position: fixed; inset: 0; z-index: -1;
+    background: radial-gradient(ellipse at 50% 50%, transparent 30%, rgba(4,3,8,0.92) 100%); }
+#end-card { text-align: center; max-width: min(760px, 86vw); }
+#end-epitaph {
+    font-family: 'Crimson Text', Georgia, serif; font-style: italic;
+    font-size: 1.5rem; color: #e6dff2; text-shadow: 0 2px 18px #000; margin-bottom: 34px;
+}
+#end-credits { animation: end-rise 2.2s ease 0.4s both; }
+#end-credits .ec-title {
+    font-family: 'Special Elite', monospace; letter-spacing: 0.4em; font-size: 1.2rem;
+    color: #c4bcd8; margin-bottom: 12px; }
+#end-credits .ec-line {
+    font-family: 'Crimson Text', serif; font-style: italic; color: #9a90b2; margin-bottom: 16px; }
+#end-credits .ec-meta {
+    font-family: 'Special Elite', monospace; font-size: 0.66rem; letter-spacing: 0.18em;
+    color: #6f6590; margin-top: 4px; }
+@keyframes end-rise { from { opacity: 0; transform: translateY(14px); } to { opacity: 1; transform: none; } }
+#end-actions { display: flex; gap: 18px; }
+```
+
+`new_string`:
+```css
+/* ── 27. End screen — epitaph hero + quiet footer credits over the fog (layout B) ── */
+#end-overlay {
+    position: fixed; inset: 0; z-index: 80;
+    display: flex; flex-direction: column; align-items: center; justify-content: center;
+    gap: 30px;
+    opacity: 0; pointer-events: none;
+    transition: opacity 1.6s ease;
+}
+#end-overlay.shown { opacity: 1; pointer-events: auto; }
+
+/* neutralize Gradio's full-width block wrappers so the inner content truly centers */
+#end-overlay > * {
+    width: auto !important; max-width: 90vw !important; min-width: 0 !important;
+    background: transparent !important; border: none !important; box-shadow: none !important;
+    display: flex; flex-direction: column; align-items: center;
+}
+
+#end-bg {
+    position: fixed; inset: -6%; z-index: -2;
+    background-size: cover; background-position: center 40%; background-repeat: no-repeat;
+    filter: grayscale(1) blur(30px) brightness(0.26);
+}
+#end-scrim { position: fixed; inset: 0; z-index: -1;
+    background: radial-gradient(ellipse at 50% 50%, transparent 30%, rgba(4,3,8,0.92) 100%); }
+
+/* the hero line */
+#end-epitaph {
+    font-family: 'Crimson Text', Georgia, serif; font-style: italic;
+    font-size: 1.95rem; color: #e6dff2; text-shadow: 0 2px 18px #000;
+    text-align: center; max-width: min(820px, 88vw); margin: 0;
+}
+
+/* the two actions — grouped, centered, understated text links */
+#end-actions {
+    flex-direction: row !important; justify-content: center; gap: 34px;
+}
+#end-actions .end-btn {
+    background: none !important; border: none !important; box-shadow: none !important;
+    width: auto !important; min-width: 0 !important; flex: 0 0 auto !important;
+    font-family: 'Special Elite', monospace; letter-spacing: 0.2em; font-size: 0.92rem;
+    color: #d7cfe6 !important; opacity: 0.85;
+    transition: opacity 0.25s ease, color 0.25s ease;
+}
+#end-actions .end-btn:hover { opacity: 1; color: #f0eaff !important; }
+#end-actions .end-btn-dim { color: #7d7498 !important; font-size: 0.82rem; opacity: 0.7; }
+
+/* credits — a quiet footer pinned to the bottom (fixed → out of the centered flow) */
+#end-credits {
+    position: fixed; left: 0; right: 0; bottom: 26px;
+    display: flex; flex-direction: column; align-items: center; gap: 5px; text-align: center;
+    animation: end-rise 2.2s ease 0.4s both;
+}
+#end-credits .ec-title {
+    font-family: 'Special Elite', monospace; letter-spacing: 0.4em; font-size: 0.95rem;
+    color: #c4bcd8; }
+#end-credits .ec-line {
+    font-family: 'Crimson Text', serif; font-style: italic; color: #9a90b2; font-size: 0.86rem; }
+#end-credits .ec-meta {
+    font-family: 'Special Elite', monospace; font-size: 0.64rem; letter-spacing: 0.18em;
+    color: #6f6590; }
+@keyframes end-rise { from { opacity: 0; transform: translateY(14px); } to { opacity: 0.82; transform: none; } }
+```
+
+- [ ] **Step 3: Verify import still OK** (CSS-only, but cheap to confirm nothing else broke): `./.venv/Scripts/python -c "import app; print('ok')"` → `ok`.
+
+- [ ] **Step 4: Commit.**
+```bash
+git add styles.css
+git commit -m "style(end): layout B — epitaph hero, grouped text-link actions, footer credits (§27)"
+```
+
+---
+
+### Phase 3: Verify suite + hand off the live check
+
+- [ ] **Step 1:** Run the full suite — `./.venv/Scripts/python -m pytest -q` → all green (269). No test changes were made; if anything fails, it's a regression — investigate, don't delete coverage.
+- [ ] **Step 2 (HUMAN-ONLY — Pablo, `.venv-tts` + Ollama, `HOLLOW_FAST_FINALE=good|loop|bad`):** play each finale to the end and confirm: the overlay fades in ~1 s after the last beat; the epitaph is **centered** and large; the two actions sit **grouped + centered** right under it (`leave the wood` visibly dimmer); the credits sit as a **dim, centered footer at the bottom** that rises in; **begin again** restarts with the opening ritual and **leave the wood** returns to the menu; a fresh run still re-reveals correctly. Do NOT attempt this as the agent — apply the code and report it as pending Pablo's check.
+
+---
+
+## Self-Review
+- **Spec coverage:** epitaph as hero, centered (Phase 2 `#end-epitaph` + overlay centering) ✅; actions grouped/centered, `leave` dimmer (Phase 1 classes + Phase 2 `#end-actions`/`.end-btn`/`.end-btn-dim`) ✅; credits demoted to a fixed bottom footer (Phase 1 markup move + Phase 2 `#end-credits` fixed) ✅; foggy backdrop + reveal preserved (`#end-bg`/`#end-scrim`/`.shown`) ✅.
+- **No-change surfaces confirmed:** `applyEnd()` targets `#end-epitaph` (id kept); button ids `btn-end-again`/`btn-end-leave` kept → `_reset`/`_to_menu` wiring + JS button wiring untouched; finale generator tuples untouched (marker reveal unchanged). No Python logic or tests change.
+- **Consistency:** Phase 1 emits classes `end-btn` / `end-btn-dim`, which Phase 2 styles; Phase 1 keeps `#end-credits` markup that Phase 2 pins as the footer.
+- **Gotcha guard:** `#end-overlay` is `position:fixed` with no transformed ancestor (top-level `gr.Column`), so the fixed `#end-bg`/`#end-scrim`/`#end-credits` anchor to the viewport ✅; `end-rise` is NOT added to the `prefers-reduced-motion` block (never disable opacity there) ✅; all edits via the Edit tool, never PowerShell (UTF-8 glyphs) ✅.
+- **Risk:** the `#end-overlay > *` wrapper-neutralizer sets children to `flex-direction:column`; `#end-actions` overrides back to `row !important`. If Gradio's button base CSS still forces full width, the `width:auto/flex:0 0 auto !important` on `.end-btn` is the guard — flag to Pablo if buttons still stretch in the live check.

docs/superpowers/plans/2026-06-15-loop-bad-silent-convulse.md

@@ -0,0 +1,144 @@
+# Loop & Bad Finales — Silent Convulse Beat Implementation Plan
+
+> **For agentic workers:** REQUIRED first reads — `CLAUDE.md` (or `AGENTS.md`) and `docs/superpowers/AGENT-EXECUTION-BRIEF.md`. Then execute this plan phase-by-phase, one commit per phase. Steps use checkbox (`- [ ]`) syntax. TDD where marked — run the test RED before implementing.
+
+**Goal:** Stop the **loop** and **bad** finale convulsions from cutting off the line being spoken just before them. Make each convulsion a **silent `frenzy` beat** (no text, no new audio) — exactly like the **good** finale already does — so the prior line's audio drains and the convulsion plays in silence, then the next line lands cleanly.
+
+**Root cause:** In `finale.py`, the loop/bad convulsion is one `"hollow"` step carrying text `"..."` *and* `stage="frenzy"`. The player synthesizes/enqueues a `"..."` blip and fires the violent convulsion DOM update simultaneously, landing on the tail of the preceding spoken line → it reads/sounds cut. The good finale fixed this by splitting the convulsion into a spoken line **+ a separate silent `frenzy` beat** (`_step("hollow", "", 2.0, stage="frenzy")`) and guarding `if step["text"]:` in its player so the empty beat adds no bubble. Loop/bad never got this (CLAUDE.md "Next" #2).
+
+**Architecture:** Pure-data change in `finale.py` (two step texts → `""`) + a one-line guard in two player generators in `app.py`. No `speak_it` change is needed: `speak("")` returns `None` (voice.py guards empty text), so an empty beat is silent and `_voice_and_pause` falls back to the step's scripted pause — and those pauses already match the CSS convulsion lengths (loop `.entity-convulse-loop` ≈ 0.55 s × 3 = 1.65 s; bad `.entity-frenzy-wrap` ≈ 0.55 s × 6 = 3.3 s + the 3.2 s `ghost-frenzy` stab).
+
+**Tech Stack:** Python (`finale.py`, `app.py`), pytest. Edit tool only (UTF-8: `…`, em-dashes, `“ ”`). `import app` + `pytest -q` (269 green) stays green; new tests raise it.
+
+**No-break check (already verified):** finale tests assert stages/strikes/speakers/wound-text (`tests/test_finale.py`); player tests assert the entity HTML at output index 6, the heartbeat, and cue-audio (`tests/test_app.py::TestFinaleBuildAndConvulse`). **None** assert the `"..."` text or chat-bubble counts, so flipping the text and dropping the empty bubble breaks nothing. The convulsion *visual* (`render_entity(..., "convulse_loop"/"frenzy")`) is unchanged — `entity-frenzy-wrap` still appears.
+
+**Key seams (read the real text first — line numbers drift):** `finale.py` `finale_steps` (loop) and `finale_steps_bad`; `app.py` `_play_finale` (loop player, the `for step in finale_steps(claimed):` loop) and `_play_finale_bad` (the `for step in finale_steps_bad(wounds):` loop). The reference implementation is `_play_finale_good` (`if step["text"]:` guard) + `finale_steps_good` (silent `frenzy` beat).
+
+---
+
+### Phase 1: Guard the loop & bad players against empty-text beats (app.py)
+
+Add the same `if step["text"]:` guard the good player already has, to the loop and bad players. This is a **no-op until Phase 2** (the texts are still `"..."`, which is truthy), so each commit stays clean — no empty bubble ever ships.
+
+**Files:** Modify `app.py` (`_play_finale`, `_play_finale_bad`). Reference: `_play_finale_good` already does `if step["text"]:` before its `chat_hist` append.
+
+- [ ] **Step 1: Read the two player loops** and confirm the `old_string`s below match (they were unguarded as of this writing).
+
+- [ ] **Step 2: Guard the loop player.** Edit `app.py`:
+
+`old_string`:
+```python
+    for step in finale_steps(claimed):
+        role = "assistant" if step["speaker"] == "hollow" else "user"
+        chat_hist = chat_hist + [{"role": role, "content": step["text"]}]
+```
+`new_string`:
+```python
+    for step in finale_steps(claimed):
+        role = "assistant" if step["speaker"] == "hollow" else "user"
+        if step["text"]:   # silent beats (the convulsion) add no bubble
+            chat_hist = chat_hist + [{"role": role, "content": step["text"]}]
+```
+
+- [ ] **Step 3: Guard the bad player.** Edit `app.py`:
+
+`old_string`:
+```python
+    for step in finale_steps_bad(wounds):
+        role = "assistant" if step["speaker"] == "hollow" else "user"
+        chat_hist = chat_hist + [{"role": role, "content": step["text"]}]
+```
+`new_string`:
+```python
+    for step in finale_steps_bad(wounds):
+        role = "assistant" if step["speaker"] == "hollow" else "user"
+        if step["text"]:   # silent beats (the convulsion) add no bubble
+            chat_hist = chat_hist + [{"role": role, "content": step["text"]}]
+```
+
+- [ ] **Step 4: Verify + suite.** Run: `./.venv/Scripts/python -c "import app; print('ok')"` → `ok`; then `./.venv/Scripts/python -m pytest -q` → 269 green (no behavior change yet).
+
+- [ ] **Step 5: Commit.**
+```bash
+git add app.py
+git commit -m "refactor(finale): guard loop & bad players against empty-text beats (mirror good)"
+```
+
+---
+
+### Phase 2: Make the loop & bad convulsions silent beats (finale.py) — TDD
+
+Flip both `frenzy` step texts from `"..."` to `""`. With the Phase 1 guard, no empty bubble appears; with `speak("")` returning `None`, the beat is silent and keeps its scripted pause.
+
+**Files:** Test: `tests/test_finale.py` (`TestConvulsionStages`); Modify: `finale.py` (`finale_steps`, `finale_steps_bad`).
+
+- [ ] **Step 1: Write the failing tests.** In `tests/test_finale.py`, add to `class TestConvulsionStages` (after `test_loop_script_has_a_convulse_stage_before_the_turn`):
+
+```python
+    def test_loop_convulse_is_a_silent_beat(self):
+        # the convulsion must carry no text (like good) so the line before it
+        # drains and the convulsion plays in silence — not cut mid-sentence
+        frenzy = [s for s in finale_steps(["a", "b"]) if s["stage"] == "frenzy"]
+        assert len(frenzy) == 1 and frenzy[0]["text"] == ""
+
+    def test_bad_convulse_is_a_silent_beat(self):
+        frenzy = [s for s in finale_steps_bad(["w1", "w2"]) if s["stage"] == "frenzy"]
+        assert len(frenzy) == 1 and frenzy[0]["text"] == ""
+
+    def test_good_convulse_is_a_silent_beat(self):
+        frenzy = [s for s in finale_steps_good(["a", "b"]) if s["stage"] == "frenzy"]
+        assert len(frenzy) == 1 and frenzy[0]["text"] == ""
+```
+
+- [ ] **Step 2: Run them** → the loop and bad cases FAIL (text is `"..."`), the good case PASSES. Run: `./.venv/Scripts/python -m pytest tests/test_finale.py::TestConvulsionStages -q`. Expected: 2 failed, rest passed.
+
+- [ ] **Step 3: Silence the loop convulsion.** Edit `finale.py`:
+
+`old_string`:
+```python
+        _step("hollow", "...", 1.7, stage="frenzy"),
+```
+`new_string`:
+```python
+        # a SILENT convulsion beat (mirrors good): the line before drains and
+        # the convulsion plays in silence, so nothing is cut mid-sentence
+        _step("hollow", "", 1.7, stage="frenzy"),
+```
+
+- [ ] **Step 4: Silence the bad convulsion.** Edit `finale.py`:
+
+`old_string`:
+```python
+        # the convulsion: every face cycles over the body before it settles
+        _step("hollow", "...", 3.6, stage="frenzy"),
+```
+`new_string`:
+```python
+        # the convulsion: a SILENT beat (mirrors good) so the line before drains
+        # and the convulsion plays without cutting it; faces cycle, then rage
+        _step("hollow", "", 3.6, stage="frenzy"),
+```
+
+- [ ] **Step 5: Run the tests + full suite** → all green. Run: `./.venv/Scripts/python -m pytest tests/test_finale.py::TestConvulsionStages -q` then `./.venv/Scripts/python -m pytest -q` (271 green: 269 + 2 new that now pass; the good one already passed).
+
+- [ ] **Step 6: Commit.**
+```bash
+git add finale.py tests/test_finale.py
+git commit -m "fix(finale): silent convulse beat for loop & bad so the prior line isn't cut"
+```
+
+---
+
+### Phase 3: Full suite + live verification
+
+- [ ] **Step 1:** `./.venv/Scripts/python -m pytest -q` → all green; `./.venv/Scripts/python -c "import app; print('ok')"` → `ok`.
+- [ ] **Step 2 (HUMAN-ONLY — Pablo, `.venv-tts` + Ollama):** play `HOLLOW_FAST_FINALE=loop` and `=bad` to the end and confirm the line **just before** the convulsion finishes speaking and is **not** cut; the convulsion plays in silence (no stray "…" blip), then settles (loop → `end` face + flatline; bad → `rage` face + threat) and the next line lands cleanly. Cross-check that `=good` is unchanged. Do NOT attempt this as the agent — apply the code and report it pending Pablo's check.
+
+---
+
+## Self-Review
+- **Spec coverage:** loop convulse silent (Phase 2 Step 3) ✅; bad convulse silent (Phase 2 Step 4) ✅; no empty transcript bubble (Phase 1 guard) ✅; prior line drains / convulsion in silence (silent beat + existing scripted pauses that match the CSS convulsion lengths) ✅.
+- **Consistency:** mirrors `finale_steps_good` (silent `""` frenzy beat) and `_play_finale_good` (`if step["text"]:` guard) — the proven pattern. Stages unchanged, so `tests/test_finale.py::TestConvulsionStages` ordering tests still hold; the new tests lock the silence in for all three endings.
+- **No-tuple / no-regression:** no finale generator tuple changed; the convulsion *visual* (`render_entity` `convulse_loop`/`frenzy`) is untouched, so `entity-frenzy-wrap`/`entity-end` player assertions still pass. `speak("")`→`None` keeps the beat silent without touching `speak_it`.
+- **Risk:** if the bad convulsion ever feels like it starts a hair before the long prior line ("…you never could.") fully ends, that's the prior line draining under a silent convulsion (exactly the good-finale behavior) — acceptable; flag to Pablo only if it reads wrong in the live check. Edits via Edit tool only (UTF-8 glyphs).
+```