docs: spec for tone axis + three endings (What You Made Of Me)

Approved in session: good = existing Visitor Loop, bad = redacted
cruelty treasure, neutral = fog dissolve. Gemma 4 swap rejected.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/superpowers/specs/2026-06-11-tone-and-three-endings-design.md

@@ -0,0 +1,165 @@
+# Tone Axis & Three Endings — Design Spec
+
+**Date:** 2026-06-11 (approved by Pablo in session)
+**Feature name:** "What You Made Of Me" — a second state axis (how the visitor *treats* Hollow) that shifts Hollow's personality live and branches the game into three endings.
+**Constraint:** one implementation day (Friday June 13), same model (Qwen3-8B / qwen3:8b), zero extra GPU calls per turn.
+
+---
+
+## 1. Concept
+
+Hollow currently reacts to *how much* the visitor shares (affinity/Bond) but is deaf to *how* the visitor speaks to it. This feature adds a **tone axis**:
+
+- Treat it warmly → it trusts, attaches — and at high bond the existing **Visitor Loop** fires (the "good" ending: it loved you too much).
+- Treat it cruelly → the abuse reminds it of its suffering in life; it withdraws, then turns resentful, and a new **bad ending** fires: it has been silently keeping your cruelties as its treasure.
+- Treat it ambivalently → at high bond it cannot trust what you are; the **neutral ending** fires: it dissolves back into the fog, unresolved.
+
+Plus two always-on "presence" mechanics: **mimicry** (Hollow subtly copies the visitor's writing style) and **wound echo** (at hostile tone, Hollow throws the visitor's own cruel words back at them mid-game, generated, not scripted).
+
+## 2. Decisions already made (do not reopen)
+
+| Decision | Choice |
+|---|---|
+| Model swap (Gemma 4 12B) | **Rejected** — doesn't fit local 8 GB VRAM, week-old tooling, re-tuning risk, no prize upside |
+| Good ending | **Existing Visitor Loop, unchanged** (`finale_steps`) — zero rework |
+| Bad ending climax | **"Your cruelty is its treasure"** — redacted entries fill the Treasure panel during cruel play; the finale unredacts them one by one |
+| Neutral trigger | **Bond-high + mixed tone** (same trigger gate as good, branched by tone). No turn-cap. |
+| New art | **One image: `hollow_rage`** (Pablo generates with FLUX, same grayscale F&H style). Neutral reuses `hollow_base` + CSS dissolve; good reuses `hollow_end`. |
+
+## 3. State shape (gr.State) — additions
+
+```python
+{
+  # ... existing fields unchanged ...
+  "tone": int,          # -100..+100 accumulator, starts 0
+  "wounds": list[str],  # visitor's cruel phrases, verbatim-ish, max 10
+  "ending": str | None, # "good" | "bad" | "neutral" once fired; None while playing
+}
+```
+
+All reads of the new fields use `.get(..., default)` (`tone`→0, `wounds`→[], `ending`→None) so mid-session states from before the deploy don't crash. `ended: bool` stays (the UI kill-switch); `ending` records *which* finale fired.
+
+## 4. Extraction (engine.py + schemas.py) — same single GPU call
+
+`TurnUpdate` gains two fields:
+
+```python
+class TurnUpdate(BaseModel):
+    affinity_delta: int = 0          # existing, clamp -8..+8
+    new_memories: List[str] = []     # existing
+    tone_delta: int = 0              # NEW, clamp -10..+10
+    cruel_quote: Optional[str] = None  # NEW: visitor's cruel phrase, verbatim; None if none
+```
+
+Validators: clamp `tone_delta` to [-10, +10]; `cruel_quote` is stripped, truncated to 120 chars, empty string → None.
+
+`_EXTRACTION_SYSTEM` gains items 3 and 4 (scale mirrors the affinity one):
+
+- `tone_delta`: how the visitor **treated** Hollow this turn — warmth/kindness/comfort +4..+8; ordinary politeness +1..+3; neutral 0; dismissive/cold −2..−5; mocking/insulting/cruel −6..−10. (Distinct from affinity: sharing a sad memory politely is high affinity, ~0 tone; an insult is negative on both.)
+- `cruel_quote`: if the visitor mocked or insulted Hollow this turn, the cruel phrase **exactly as the visitor wrote it** (their words, never Hollow's). `null` otherwise.
+
+Example JSON in the prompt updated to include both fields. Parse-failure fallback (existing `TurnUpdate()`) naturally yields `tone_delta=0, cruel_quote=None` — degrades safely.
+
+## 5. State update (memory.py — apply_update)
+
+After the existing affinity/treasure logic:
+
+```python
+state["tone"] = max(-100, min(100, state.get("tone", 0) + update.tone_delta))
+if update.cruel_quote and update.tone_delta < 0:          # guard: no quote on positive turns
+    wounds = state.setdefault("wounds", [])
+    if update.cruel_quote not in wounds:
+        wounds.append(update.cruel_quote)
+        del wounds[:-10]                                   # cap at 10, keep newest
+```
+
+## 6. Personality & presence (character.py)
+
+`build_system_prompt(affinity, treasure, recall_memory=None, tone=0, wounds=None)`.
+
+**Mimicry (always on)** — appended to every prompt:
+> "Subtly mirror the visitor's writing style — their punctuation, capitalization, message length, their rhythm. If they write short and cold, you become short. Never mention that you do this."
+
+**Tone bands** — one block appended by accumulated `tone`:
+
+| Band | Condition | Prompt effect |
+|---|---|---|
+| Warm | `tone >= 15` | "The visitor has been gentle with you. You trust them more than you should. You are becoming attached." |
+| Neutral | `-15 < tone < 15` | (nothing appended) |
+| Wounded | `-40 < tone <= -15` | "The visitor's words have hurt you. They remind you of how you were treated when you were alive. You withdraw: shorter answers, more guarded, you flinch at kindness now." |
+| Hostile | `tone <= -40` | "The visitor is cruel, like the ones you remember from when you were alive. Something in you has curdled. You are resentful, cold, quietly menacing." **+ wound echo:** inject up to 2 most recent `wounds`: "They said these things to you: \"…\", \"…\". You may quietly return their own words to them." |
+
+Tone bands stack *with* the affinity tier persona (tier picks the base voice; tone modulates it).
+
+## 7. Ending logic (memory.py — decide_ending replaces should_end)
+
+```python
+def decide_ending(state: dict) -> str | None:
+    if state.get("ended"):
+        return None
+    tone = state.get("tone", 0)
+    if tone <= -40 and state["turn"] >= 6 and len(state.get("wounds", [])) >= 2:
+        return "bad"
+    if state["affinity"] >= 90 and len(state["claimed"]) >= 3:
+        return "good" if tone >= 15 else "neutral"
+    return None
+```
+
+- **Bad** needs sustained cruelty (accumulator), a minimum game length (≥6 turns so it can't fire on turn 2), and ≥2 captured wounds (the finale needs material; if extraction missed quotes, the game simply continues).
+- **Good** = the existing gate + clearly warm tone. A normally-kind playthrough accumulates well past +15 by bond 90.
+- **Neutral** = same gate, tone below warm — including genuinely mixed (hot-and-cold) play.
+- Existing `should_end` is deleted; its tests migrate to `decide_ending`.
+
+## 8. The two new finales (finale.py — pure data, same step shape)
+
+Existing `finale_steps(claimed)` is untouched (good ending). Two new functions, same step dict shape (`speaker/text/pause/strike/stage`):
+
+**`finale_steps_bad(wounds)`** — beats (final lines written at implementation, in this voice):
+1. Hollow: the fog never thinned — "you never let it." (no strike)
+2. For each of the last ≤5 wounds, oldest→newest, `strike=i`: Hollow recites the wound **in the visitor's own words**, then claims it: *"\"{wound}.\" that's what you gave me. i kept every one."* Each strike **unredacts** the corresponding Treasure entry.
+3. `stage="turn"` step: *"this is my treasure now."* — UI mutates: Treasure header → "your words", bond label → "wound", portrait → `rage` mode, input placeholder → "get out."
+4. Hollow: it remembers now that it was treated like this when it was alive — "you helped me remember."
+5. One injected **visitor** step: `"i'm sorry"` — followed by Hollow: *"no. you aren't."* (the message-injection trick, reused from the Loop, now as accusation).
+6. Final spaced-out line (`stage="loop"`): `g e t   o u t .` Input dies with placeholder "get out."
+
+**`finale_steps_neutral()`** — short (~6 steps), no strikes, no injected visitor messages:
+1. Hollow: the fog is thin enough to leave — it could walk out with everything you gave it.
+2. Hollow: but some of what you gave is warm and some still stings; it doesn't know what you are.
+3. `stage="turn"` step: portrait starts **dissolve** (reverse materialization), Treasure entries fade, bond label → "fading".
+4. Hollow: "maybe the next visitor will be clearer."
+5. Final spaced-out line: `m a y b e   y o u   w e r e   n e v e r   h e r e   a t   a l l .` Input dies with placeholder "...".
+
+## 9. Rendering (render.py + styles.css section 18)
+
+**Treasure — redacted wounds (live play):** `render_treasure` gains `wounds: list[str] | None = None, revealed: int = 0`. Each wound renders as a redacted entry — `▮` blocks (4–7 blocks, deterministic from index), styled distinct from memories (darker, dried-blood left border). The *text is never in the DOM* while redacted (no inspect-element spoiler). During play `revealed=0`; the bad finale raises `revealed` step by step — revealed wounds show their real text, marked like `mine` entries.
+
+**Entity — two new modes for `render_entity`:**
+- `"rage"`: portrait swaps to `hollow_rage.webp`, full sharp, with a permanent low red-tinged grain (CSS). Used from the bad finale's `turn` step onward.
+- `"dissolve"`: reverse materialization — a one-shot CSS animation ramping blur/opacity back toward the tier-0 smudge. Used from the neutral finale's `turn` step onward.
+
+**Asset:** `assets/hollow_rage.webp` (Pablo, FLUX, same pipeline as the other four; target similar ~15–20 KB WebP).
+
+## 10. Wiring (app.py)
+
+- `chat()`: `ending = decide_ending(state)`; `"good"` → existing `_play_finale`; `"bad"` / `"neutral"` → new generator(s) following the exact `_play_finale` pattern (full output tuples, `time.sleep` pacing, no GPU). `state["ending"]` recorded; `state["ended"] = True`.
+- `build_system_prompt(...)` call gains `tone=state.get("tone", 0), wounds=state.get("wounds", [])`.
+- Every `render_treasure` call site passes `wounds=state.get("wounds", [])`.
+- `_init_state` — `HOLLOW_FAST_FINALE` accepts values:
+  - `1` or `good`: current seed + `tone: 30`
+  - `bad`: affinity 12, empty treasure, `tone: -35`, 3 seeded wounds, turn 7 (one cruel message from firing)
+  - `neutral`: current good seed but `tone: 5`
+
+## 11. Testing
+
+- `decide_ending` matrix: all three endings, the None paths, the guards (turn <6, wounds <2, already ended, old state without tone).
+- `apply_update`: tone clamp ±100, wounds append/dedupe/cap-10, positive-turn quote ignored, parse-fallback unchanged.
+- `schemas`: tone_delta clamp, cruel_quote strip/truncate/empty→None.
+- `render_treasure`: redacted entries (count, no plaintext in HTML), reveal progression, escaping.
+- `render_entity`: rage and dissolve modes.
+- `finale_steps_bad`: ≤5 strikes, indices valid, stages present, wound text embedded; `finale_steps_neutral`: no strikes, stages present.
+- `build_system_prompt`: each tone band, mimicry always present, wound echo only when hostile.
+- Manual: three full playthroughs via the three `HOLLOW_FAST_FINALE` seeds, verified against the running app (headless-Chrome workflow).
+
+## 12. Out of scope
+
+Model swap, audio, turn-cap trigger, more than one new portrait, localization, changes to the good ending script or the opening line (the Loop's bookend — fixed by design).