docs: hand off Phase 01 at the deploy gate

Record where the work stands, why 42 commits are unpushed on purpose, and the
traps that cost real time this session so none of them get re-derived: the two
Gradio 6.22.0 API defects, the ASR q8/WASM incompatibility, and the two spec
corrections that supersede the research doc.

HANDOFF.json is the machine-readable half that resume-work reads first. Its
absence after the earlier crash is what made recovering this plan expensive.

.planning/HANDOFF.json

@@ -0,0 +1,44 @@
+{
+  "created": "2026-08-27",
+  "created_by": "session handoff — user stepping away from the machine",
+  "status": "blocked_on_user",
+  "phase": "01-voice-avatar-loop-skeleton",
+  "plan": "01-05",
+  "task": 1,
+  "total_tasks": 3,
+  "next_action": "Decide whether to run plan 01-05, the user-gated deploy. It is the only thing blocking the rest of Phase 01. Run `/gsd:execute-phase 01` to resume; the orchestrator will pick up at 01-05.",
+  "blockers": [
+    "01-05 Task 1 pushes to the `space` remote, which PUBLISHES the app publicly on the WolfDavid Hugging Face profile. This was deliberately not done autonomously.",
+    "Every remaining plan depends on it: 01-08 depends_on [01-05, 01-06, 01-07]; 01-09 depends_on [01-08]; 01-10 depends_on [01-09]. Nothing else in the phase can proceed.",
+    "The Space's README front-matter (which lives only on the HF side — there is NO README.md in this repo) was auto-generated wrong at Space creation: sdk_version 6.26.0 must become 6.22.0 to match requirements.txt, and python_version '3.12' must become 3.12.12. Plan 01-05 owns writing the corrected README. Pushing BEFORE 01-05 writes it would trigger a public build on the wrong Gradio version."
+  ],
+  "human_actions_pending": [
+    "Approve (or decline) the public deploy in plan 01-05.",
+    "Plan 01-05 Task 3 is a blocking human-verify gate: judge the spike verdict — confirm the inline gr.HTML transport, or take the AVATAR_TRANSPORT=iframe fallback.",
+    "Plan 01-10 re-raises the VRM sourcing gate: keep VRM1_Constraint_Twist_Sample as a permanent asset, or author a bespoke VRoid Studio character. It is currently a TEMPORARY dev asset."
+  ],
+  "completed_tasks": [
+    { "plan": "01-01", "status": "complete", "note": "hosting + VRM gates; both human checkpoints closed" },
+    { "plan": "01-02", "status": "complete", "note": "toolchain, LFS, package skeleton, test scaffolding" },
+    { "plan": "01-03", "status": "complete", "note": "avatar stage + transport seam; resumed from a crash at Task 3 this session" },
+    { "plan": "01-04", "status": "complete", "note": "VOICEVOX TTS, requirements.txt, ground-truth fixtures" },
+    { "plan": "01-06", "status": "complete", "note": "mora-to-viseme timeline builder" },
+    { "plan": "01-07", "status": "complete", "note": "push-to-talk mic gate + tiered browser ASR" },
+    { "plan": "01-05", "status": "not_started", "note": "BLOCKED — user-gated public deploy" },
+    { "plan": "01-08", "status": "not_started", "note": "blocked behind 01-05" },
+    { "plan": "01-09", "status": "not_started", "note": "blocked behind 01-08" },
+    { "plan": "01-10", "status": "not_started", "note": "blocked behind 01-09; user-gated" }
+  ],
+  "uncommitted_files": [],
+  "unpushed_commits": 42,
+  "push_state": "NOTHING PUSHED. The only remote is `space` (the public HF Space) and pushing it IS the gated deploy. Branch `master` has no upstream. There is no GitHub remote for this repo.",
+  "context_notes": [
+    "Working tree is clean. All work is committed locally. 42 commits are unpushed by design, not by omission.",
+    "Verified green at handoff: 82 quick-loop tests in ~12.8s, 15 e2e browser tests, ruff check + format --check clean.",
+    "RUN `pytest tests/e2e/` AS A WHOLE before trusting a green phase. Per-file runs hid two real defects this session — each plan's own verification passed while the full suite failed.",
+    "Gradio 6.22.0 traps found the hard way — copy from src/japanese_avatar/ui/avatar_component.py, NOT from 01-RESEARCH.md: (1) js_on_load cannot use top-level await, it compiles to a non-async Function; use an async IIFE. (2) Custom props are **kwargs, not props={...}.",
+    "ASR traps: dtype 'q8' cannot create an ONNX session on the WASM backend at all — q4 is the only quantisation working on both tiers. A failed WebGPU init poisons the ONNX backend registry for the page, so asr.js probes requestAdapter() first rather than relying on the prescribed fallback.",
+    "Plan frontmatter over-claims shared requirements. AVTR-01, AVTR-02, VOIC-02/03/04/05, DPLY-01 and DPLY-04 appear in plans that do not satisfy them. Never blind-run `requirements mark-complete` — verify the acceptance test actually ran.",
+    "01-VALIDATION.md and plan 01-06 assert the slow timeline is exactly 1/0.75x longer within 2 frames. It measures 1.3410852713178294x, which is 4 frames out. The plan's stated truth was written from a wrong assumption; the measured ratio is correct and corroborates a 01-04 finding. Update 01-VALIDATION.md when 01-10 touches it so the verifier does not read this as an unmet must-have."
+  ]
+}

RESUME.md

@@ -0,0 +1,121 @@
+# Resume here — Japanese Learning Avatar
+
+**Written 2026-08-27, stepping away from the machine.**
+Working tree is clean. Everything is committed. Nothing is pushed, deliberately — see below.
+
+To pick back up, run `/gsd:resume-work` in this directory. It reads `.planning/HANDOFF.json`
+first, which carries the same state in machine-readable form.
+
+---
+
+## One-line status
+
+Phase 01 is **6 of 10 plans complete and hard-blocked on a decision only you can make**:
+whether to publicly deploy the Hugging Face Space.
+
+---
+
+## Why nothing was pushed
+
+This repo's **only** git remote is `space` — the public Hugging Face Space at
+`WolfDavid/japanese-learning-avatar`. There is no GitHub remote. Branch `master` has no upstream.
+
+So `git push` here does not mean "back up my work." It means **publish the app publicly and
+trigger a Space rebuild** — which is precisely plan 01-05 Task 1, the gate that is waiting on you.
+
+Pushing right now would also produce a **broken** public build. There is no `README.md` in this
+repo; the Space's front-matter lives only on the HF side and was auto-generated wrong when the
+Space was created:
+
+| Front-matter key | Currently on HF | Must become | Why |
+|---|---|---|---|
+| `sdk_version` | `6.26.0` | `6.22.0` | must match `gradio==6.22.0` in `requirements.txt` |
+| `python_version` | `'3.12'` | `3.12.12` | ZeroGPU provides only 3.10.13 and 3.12.12 |
+
+Writing that corrected README is part of plan 01-05. Push after 01-05 runs, not before.
+
+**42 commits are unpushed by design, not by omission.**
+
+If what you actually want is an off-machine backup, that is a *different* action from deploying:
+add a private GitHub remote and push there. That was not done unprompted because the standing
+rule for this account is to ask before pushing nested repos.
+
+---
+
+## Where the work stands
+
+| Plan | What it is | State |
+|---|---|---|
+| 01-01 | Hosting decision + Space creation + VRM sourcing | Complete |
+| 01-02 | Toolchain, Git LFS, package skeleton, test scaffolding | Complete |
+| 01-03 | Avatar stage, shared facade + turn loop, both transports | Complete (resumed from the crash) |
+| 01-04 | VOICEVOX TTS, `requirements.txt`, ground-truth fixtures | Complete |
+| 01-06 | Mora-to-viseme timeline builder | Complete |
+| 01-07 | Push-to-talk mic gate + tiered browser ASR | Complete |
+| **01-05** | **Space manifest, deploy the spike, verdict** | **BLOCKED — your call** |
+| 01-08 | Turn-loop wiring — closes the round trip | Blocked behind 01-05 |
+| 01-09 | Full deployed E2E suite + `LICENSES.md` | Blocked behind 01-08 |
+| 01-10 | Vendor modules, latency harness (user-gated) | Blocked behind 01-09 |
+
+The dependency chain is real, not a preference: `01-08 depends_on [01-05, 01-06, 01-07]`,
+`01-09 depends_on [01-08]`, `01-10 depends_on [01-09]`. Nothing proceeds until 01-05 does.
+
+### Verified green at handoff
+
+- 82 quick-loop tests in ~12.8 s
+- 15 end-to-end browser tests
+- `ruff check .` and `ruff format --check .` both clean
+
+**Run `pytest tests/e2e/` as a whole before trusting a green phase.** Per-file runs hid two real
+defects this session — each plan's own verification passed while the full suite failed.
+
+---
+
+## What deploying would actually test
+
+The risky part is already retired. three.js + `@pixiv/three-vrm` render inside a real
+Gradio 6.22.0 `gr.HTML` component locally, with `threeInstanceCount === 1` and
+`mountCount === 1`, and the iframe fallback boots identically under `AVATAR_TRANSPORT=iframe`.
+
+What remains genuinely deployment-specific: CDN reach from `*.hf.space`, `set_static_paths`
+behind the Space proxy, cold-start behaviour, and mobile.
+
+Also note: **1 of 2 free ZeroGPU slots is already consumed** by this Space. The remaining slot is
+the last free Gradio Space this account can create without PRO — budget it against the other
+HF-profile projects. `cpu-basic` is not a fallback; it returns HTTP 402 for Gradio Spaces.
+
+---
+
+## Traps found the hard way — do not re-derive these
+
+`01-RESEARCH.md` is **wrong** on these points. Copy from
+`src/japanese_avatar/ui/avatar_component.py` and `avatar/asr.js` instead.
+
+1. **`js_on_load` cannot use top-level `await`.** Gradio 6.22.0 compiles it into a plain
+   non-async `Function`, so the documented snippet throws `SyntaxError` and `window.Avatar`
+   never exists. Use an async IIFE with its own `.catch`.
+2. **Custom props are `**kwargs`, not `props={...}`.** The dict form creates one prop literally
+   named `props`, so `props.vrmUrl` comes back `undefined`.
+3. **ASR `dtype:'q8'` cannot create an ONNX session on the WASM backend at all** — for every
+   Whisper size tested. It works on WebGPU, so the prescribed default would ship green on a dev
+   machine and dead on exactly the browsers the WASM tier exists to serve. **`q4` is the only
+   quantisation working on both tiers.**
+4. **The prescribed WebGPU→WASM fallback does not fall back.** A failed WebGPU init poisons the
+   ONNX Runtime Web backend registry for the whole page. `avatar/asr.js` probes
+   `requestAdapter()` first so the doomed call is never issued.
+
+## Two spec corrections carried forward
+
+- **Frame quantisation:** the correct form is `round(round(sec * 93.75) / speed)`, **not**
+  `round(sec / speed * 93.75)`. Measured 24/24 correct vs 8/24. Already shipped in `visemes.py`.
+- **The slow/long duration ratio is 1.3410852713178294, not exactly 1/0.75** — 4 frames out from
+  what `01-VALIDATION.md` and plan 01-06 assert. The plan's stated truth was written from a wrong
+  assumption. **Update `01-VALIDATION.md` when 01-10 touches it**, so the phase verifier does not
+  read this as an unmet must-have.
+
+## Standing warning about requirements
+
+Phase 1 plan frontmatter **over-claims shared requirements**. AVTR-01, AVTR-02, VOIC-02/03/04/05,
+DPLY-01 and DPLY-04 all appear in the `requirements:` field of plans that do not actually satisfy
+them. Never blind-run `requirements mark-complete` — verify the acceptance test has really run.
+Three executors this session correctly declined to mark requirements complete for this reason.