docs: agent execution brief (context + practices + gotchas for plan execution)

docs/superpowers/AGENT-EXECUTION-BRIEF.md

@@ -0,0 +1,38 @@
+# Agent Execution Brief — Hollow
+
+You are implementing an approved plan for **Hollow**, a horror NPC chatbot (Gradio). Read this brief in full, then get into context, then execute the plan named at the bottom — task by task, each as its own commit.
+
+## Step 0 — Get into context BEFORE writing any code
+1. **Read `CLAUDE.md` (repo root) completely.** It is the project's source of truth: current state (branch `feat/child-redesign`, ~268 tests, the 3b scene redesign, the Caor/the Gaunt lore), the stack, the file map, the state shape, and a long **Gotchas** section. Everything below assumes you've read it.
+2. **Read the plan file** (path at the bottom) in full. It contains concrete code for every step.
+3. **Read the actual current code around each seam before editing** — line numbers in the plan drift because the files change often. Match the real text, real function signatures, and real output-tuple order. Never retype a list "from memory"; copy it from the live code (e.g., the `_reset` outputs).
+
+## How we work here (good practices — follow them)
+- **One task at a time, in order. One commit per task**, using the EXACT commit message the plan gives, plus the trailer:
+  `Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>`
+  (use the model you actually are).
+- **TDD where the plan says so:** write the failing test → run it red → implement → run it green. Don't skip the red step.
+- **Keep the suite green.** Run `./.venv/Scripts/python -m pytest -q` after each task. It's at 268 now; new tests raise it. If a pre-existing test asserts old content (e.g., old fragment text/counts), update it to match the plan's intent — don't delete coverage.
+- **Edit tool ONLY for file changes. NEVER PowerShell/sed string ops on `.py`/`.css`/`.md`.** It mangles UTF-8 — and this project's strings are full of em-dashes and glyphs (`↺ · 🔌 🎨 ❯ “`). PowerShell editing has corrupted files here before.
+- **Python is `./.venv/Scripts/python`** (run from repo root via the Bash tool). `import app` must stay OK after every task.
+- **No scope creep.** Implement exactly what the plan specifies. If the plan is wrong or ambiguous, STOP and report — don't improvise extra features or refactors.
+
+## What you must NOT do (mistakes already paid for — don't repeat them)
+- **Do NOT launch the app or use headless Chrome to "verify" visuals/audio.** It's unreliable in this shell and wastes time. You apply the concrete code; **the human does the live playthrough** (`.venv-tts` + Ollama). Any "play the game and confirm" step in the plan is HUMAN-ONLY — do it not, just flag it for the human in your report.
+- **Layout is `position:fixed`, and a `transform`/`filter` on ANY ancestor traps fixed children** into Gradio's flow. Don't add transforms to scene ancestors. (`#game-stage` is `transform:none`; `#game-entity` centers via `left:calc(...)`, not translate, so the full-screen finale stab isn't trapped.)
+- **Do NOT darken scene edges with a heavy full-viewport inset shadow** — it creates a bright-center rectangle (a visible "cut"). This exact attempt was reverted.
+- **Finale one-shot audio (sigh/flatline/sting) must route through the client voice queue** (`class="cue-audio"`, NOT `autoplay`) so it doesn't talk over the playing line; the looping heartbeat stays `autoplay`.
+- **The sent message is stashed in `state["_pending_msg"]` and popped in `chat()`** — do NOT recover the user's message from the chatbot history: Gradio normalizes message `content` to a list, which crashes (`'list' has no attribute 'strip'`).
+- **The opening always renders the base face** (`render_entity(20)`), never the seeded tier.
+- **Don't break the marker pattern:** `render_entity`/`_render_title` emit hidden `.tone-now` / `.cue-now` / `ended-now` markers; `_HEAD_JS` polls and lifts state onto `#game-view` / reveals overlays. Markers are siblings of `#game-bg`, not ancestors — that's why the JS lifts them. Reuse `openingRitual()` etc.; don't redefine existing JS functions.
+- **Finale/flash overlay images use `object-fit:contain` + bottom** like the base silhouette, or they balloon past the frame.
+- **Don't add a new output to the finale generators' tuples casually** — every `yield` must then supply it (tuple-desync hazard). Prefer the marker+JS pattern the plan uses.
+
+## Verification & hand-off
+- After ALL tasks: `import app` OK, full `pytest -q` green, then `git log --oneline -N` and `git status` (tree clean except pre-existing untracked files).
+- **Report facts only**, per task: done + any seam/signature/output-order you had to adapt and why. State clearly which steps were HUMAN-ONLY (the live playthrough) and were NOT performed by you. Flag anything you were unsure about (especially scope, Gradio component scope, or a selector/output list you couldn't confirm).
+
+---
+
+## The plan to execute
+`docs/superpowers/plans/2026-06-15-end-screen.md`