docs(01-04): complete Japanese voice plan

.planning/REQUIREMENTS.md

@@ -13,7 +13,7 @@
 
 ### Voice Loop
 
-- [ ] **VOIC-01**: Avatar speaks Japanese aloud via TTS that emits per-mora timings (CPU-path, zero GPU quota)
+- [x] **VOIC-01**: Avatar speaks Japanese aloud via TTS that emits per-mora timings (CPU-path, zero GPU quota)
 - [ ] **VOIC-02**: Learner can speak Japanese via push-to-talk; ASR transcribes with visible transcript
 - [ ] **VOIC-03**: Learner can replay the avatar's last utterance and request it slower
 - [ ] **VOIC-04**: Learner can type instead of speak at any point (full text fallback)
@@ -102,7 +102,7 @@ Which phases cover which requirements. Updated during roadmap creation.
 | AVTR-01 | Phase 1 | Pending |
 | AVTR-02 | Phase 1 | Pending |
 | AVTR-03 | Phase 3 | Pending |
-| VOIC-01 | Phase 1 | Pending |
+| VOIC-01 | Phase 1 | Complete |
 | VOIC-02 | Phase 1 | Pending |
 | VOIC-03 | Phase 1 | Pending |
 | VOIC-04 | Phase 1 | Pending |

.planning/ROADMAP.md

@@ -34,7 +34,7 @@ Decimal phases appear between their surrounding integers in numeric order.
 **Plans**: 10 plans in 7 waves
   - [x] 01-02-PLAN.md — Toolchain, LFS arming, package skeleton, test scaffolding (local-only) [wave 1]
   - [ ] 01-01-PLAN.md — Hosting decision + Space creation + VRM sourcing (user-gated) [wave 2]
-  - [ ] 01-04-PLAN.md — VOICEVOX TTS, requirements.txt, ground-truth AudioQuery fixtures [wave 2]
+  - [x] 01-04-PLAN.md — VOICEVOX TTS, requirements.txt, ground-truth AudioQuery fixtures [wave 2]
   - [ ] 01-03-PLAN.md — Avatar stage, shared facade + turn loop, both transports [wave 3]
   - [ ] 01-05-PLAN.md — Space manifest, deploy the spike, first deployed E2E, verdict (user-gated) [wave 4]
   - [ ] 01-06-PLAN.md — Mora-to-viseme timeline builder, test-first [wave 4]
@@ -109,7 +109,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6
 
 | Phase | Plans Complete | Status | Completed |
 |-------|----------------|--------|-----------|
-| 1. Voice + Avatar Loop Skeleton | 1/10 | In Progress | - |
+| 1. Voice + Avatar Loop Skeleton | 2/10 | In Progress | - |
 | 2. Japanese Language Core | 0/TBD | Not started | - |
 | 3. Tutoring Brain | 0/TBD | Not started | - |
 | 4. Accounts & Persistence | 0/TBD | Not started | - |

.planning/STATE.md

@@ -3,13 +3,13 @@ gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
 status: unknown
-stopped_at: Completed 01-02-PLAN.md (local foundations). Plan 01-01 still gated on the human hosting decision.
-last_updated: "2026-08-27T00:02:37.063Z"
+stopped_at: Completed 01-04-PLAN.md (Japanese voice). VOIC-01 satisfied. Plan 01-01 still gated on the human hosting decision.
+last_updated: "2026-08-27T00:44:59.201Z"
 progress:
   total_phases: 6
   completed_phases: 0
   total_plans: 10
-  completed_plans: 1
+  completed_plans: 2
 ---
 
 # Project State
@@ -24,36 +24,39 @@ See: .planning/PROJECT.md (updated 2026-08-08)
 ## Current Position
 
 Phase: 01 (voice-avatar-loop-skeleton) — EXECUTING
-Plan: 2 of 10 (1 complete)
+Plan: 3 of 10 (2 complete)
 
-**Completed:** 01-02 (local foundations — pytest/ruff on Python 3.12.12, Git LFS armed, `--space-url` plumbing, audio fixtures).
-**Not started:** 01-01 — it is deliberately out of order. 01-02 is local-only and network-free precisely so it could run in parallel with 01-01's **human hosting checkpoint, which has NOT cleared**. Do not treat "Plan 2" as meaning 01-01 is done.
-**Next actionable:** 01-03 (avatar transport seam) is unblocked — its dependencies are the test loop and package skeleton, both of which now exist. 01-01, 01-04 and 01-05 remain gated on the hosting decision and the VRM/VOICEVOX asset choices.
+**Completed:** 01-02 (local foundations — pytest/ruff on Python 3.12.12, Git LFS armed, `--space-url` plumbing, audio fixtures) and 01-04 (Japanese voice — VOICEVOX assets via LFS, `synthesize()`, `requirements.txt`, ground-truth fixtures). **VOIC-01 is Complete.**
+**Not started:** 01-01 — it is deliberately out of order. 01-02 and 01-04 are both local-only precisely so they could run in parallel with 01-01's **human hosting checkpoint, which has NOT cleared**. The plan counter is a count, not a plan ID: "Plan 3 of 10" does not mean 01-01 or 01-03 is done.
+**Next actionable:** 01-03 (avatar transport seam) and 01-06 (viseme timeline) are both unblocked — 01-06's dependency was 01-04's fixtures, which now exist. 01-05 has its `requirements.txt` but still needs the hosting decision. 01-01 remains gated on the human checkpoint.
+
+> **Before writing `visemes.py` in 01-06, read `docs/VOICEVOX-SETUP.md` § "Frame quantisation".** 01-RESEARCH.md's formula is wrong for `speedScale != 1.0`; the corrected form and its evidence are recorded there and in the Blockers/Concerns section below.
 
 ## Performance Metrics
 
 **Velocity:**
 
-- Total plans completed: 1
-- Average duration: 21 min
-- Total execution time: 0.35 hours
+- Total plans completed: 2
+- Average duration: 27 min
+- Total execution time: 0.9 hours
 
 **By Phase:**
 
 | Phase | Plans | Total | Avg/Plan |
 |-------|-------|-------|----------|
-| 01 | 1 | 21min | 21min |
+| 01 | 2 | 54min | 27min |
 
 **Per-plan detail:**
 
 | Plan | Duration | Tasks | Files |
 |------|----------|-------|-------|
 | Phase 01 P02 | 21min | 3 tasks | 16 files |
+| Phase 01 P04 | 33min | 3 tasks | 26 files |
 
 **Recent Trend:**
 
-- Last 5 plans: 01-02 (21min)
-- Trend: — (single data point)
+- Last 5 plans: 01-02 (21min), 01-04 (33min)
+- Trend: slower, but 01-04 downloaded ~190 MB of assets and ran an empirical investigation the plan did not budget for
 
 *Updated after each plan completion*
 
@@ -71,6 +74,9 @@ Recent decisions affecting current work:
 - [Phase 01]: Ruff excludes *.md: ruff 0.16 formats Python blocks embedded in Markdown, which made the phase's own planning docs fail the lint gate. Lint governs shipped Python, not prose.
 - [Phase 01]: uv.lock is committed so a Space rebuild resolves the same dependency set that passed locally; requirements.txt (plan 01-04) remains the Space's contract.
 - [Phase 01]: Git LFS armed for .vrm/.vvm/.wav/.onnx in Wave 1, before any binary exists - retires the 10 MiB non-LFS push rejection ahead of plans 01-01 and 01-04.
+- [Phase 01]: voicevox_vvm 0.17.0 (not 0.16.4) pairs with core 0.17.0; the vvm ships format v2 + StyleType::StreamingTalk, both introduced in core 0.17.0
+- [Phase 01]: ONNX Runtime uses lazy first-use download (option c): no pip distribution exists and a Gradio-SDK Space has no build hook to run the official downloader
+- [Phase 01]: AudioQuery serialised to a plain ENGINE-schema dict at the module boundary; voicevox_core 0.17.0 exposes no .json() method, but the type is a real dataclass
 
 ### Pending Todos
 
@@ -81,13 +87,14 @@ None yet.
 ### Blockers/Concerns
 
 - **Hosting model unresolved (pre-Phase-1 decision).** STACK research found free Gradio Spaces on personal accounts now require PRO; the free path is ZeroGPU with per-visitor quota (~2 min/day anonymous). Confirm WolfDavid account eligibility (verified email, >30 days old, <2 existing ZeroGPU Spaces) during Phase 1 planning; if ineligible, PRO ($9/mo) becomes a decision before any build.
-- **Asset licensing gates a design branch.** VOICEVOX character terms need a human read (third-party web synthesis, not just generated audio) before TTS is built around it — the fallback loses free mora timings and changes the lip-sync design. VRM model licenses vary per author; self-authored VRoid Studio character removes the question.
+- **Asset licensing — VOICEVOX half RESOLVED (01-04), VRM half still open.** The VOICEVOX branch is closed: all three licence layers were read in full, third-party web synthesis is explicitly contemplated (software cl.3 attaches a flow-down obligation rather than prohibiting it), embedded `.vvm` redistribution is permitted (model cl.2), and the rights holder declines qualification questions as policy (SSS LLC 免責条項 2) — so there is no human step available or required. Compliance is a visible `VOICEVOX:ずんだもん` credit plus a terms notice wherever audio is obtainable; all facts recorded in `docs/VOICEVOX-SETUP.md`. **Still open:** VRM model licences vary per author; a self-authored VRoid Studio character removes that question (plan 01-01).
 - **Per-turn GPU-second cost is unmeasured.** The entire free-tier UX budget depends on this number — measure in Phase 1/3, do not assume.
 - **REQUIREMENTS.md originally miscounted v1 as 31.** Actual count is 33; traceability and coverage corrected during roadmap creation.
 - **Phase 1 plan frontmatter over-claims shared requirements — do not blind-run `requirements mark-complete`.** DPLY-01 appears in the `requirements:` field of plans 01-01, 01-02, 01-05, 01-09 and 01-10, but it is only *satisfied* by 01-05 (`test_space_reachable`). Executing 01-02 marked it Complete; this was reverted, and DPLY-01 is correctly `Pending`. The same over-claiming applies to AVTR-01/02, VOIC-02/03/04/05 and DPLY-04 across plans 01-09 and 01-10. Verify a requirement's actual acceptance test has run before checking it off.
+- CORRECTION for plan 01-06 (not a blocker, a spec fix): 01-RESEARCH.md's frame quantisation is wrong for speedScale != 1.0. Correct form is round(round(length*93.75)/speed), NOT round(length/speed*93.75) - verified 24/24 vs 8/24 across 6 speeds x 4 sentences, worst error 5 frames (53ms). Also: pauseLength/pauseLengthScale do not exist in voicevox_core 0.17.0, and the slow/long duration ratio is 1.341085, not exactly 1/0.75. See docs/VOICEVOX-SETUP.md section 'Frame quantisation'.
 
 ## Session Continuity
 
-Last session: 2026-08-27T00:02:37.058Z
-Stopped at: Completed 01-02-PLAN.md (local foundations). Plan 01-01 still gated on the human hosting decision.
+Last session: 2026-08-27T00:43:56.253Z
+Stopped at: Completed 01-04-PLAN.md (Japanese voice). VOIC-01 satisfied. Plan 01-01 still gated on the human hosting decision.
 Resume file: None

.planning/phases/01-voice-avatar-loop-skeleton/01-04-SUMMARY.md

@@ -0,0 +1,488 @@
+---
+phase: 01-voice-avatar-loop-skeleton
+plan: 04
+subsystem: voice
+tags: [voicevox, tts, japanese, mora-timing, git-lfs, onnxruntime, licensing, fixtures]
+
+# Dependency graph
+requires: ["01-02"]
+provides:
+  - "synthesize() returning 24000 Hz WAV bytes plus a plain-dict AudioQuery with per-mora timings"
+  - "SynthResult / VisemeEvent / TurnTimings / AvatarDirective dataclasses consumed by 01-06 and 01-08"
+  - "zundamon.vvm and the Open JTalk dictionary on disk via Git LFS, loaded with no network at import"
+  - "requirements.txt - the Space's four-line dependency contract"
+  - "Three AudioQuery fixtures with true WAV durations and frame counts, the ground truth for AVTR-02"
+  - "The VERIFIED frame-quantisation formula, which corrects 01-RESEARCH.md"
+  - "docs/VOICEVOX-SETUP.md - executed API surface, asset hashes, and the full voice licence chain"
+affects: [01-05, 01-06, 01-07, 01-08, 01-09]
+
+# Tech tracking
+tech-stack:
+  added: [voicevox_core 0.17.0, voicevox_vvm 0.17.0, VOICEVOX ONNX Runtime 1.23.2, open_jtalk_dic_utf_8-1.11]
+  patterns:
+    - "Lazy lru_cache(maxsize=1) synthesizer with a warmup() hook: import stays free, startup pays the cost"
+    - "AudioQuery converted to a plain ENGINE-schema dict at the module boundary, never handed out live"
+    - "Large runtime assets committed through LFS; software binaries referenced by release URL, never vendored"
+    - "Directory-scoped .gitattributes to extend LFS coverage without touching another plan's root file"
+    - "Fixture generators assert the invariants their fixtures exist to prove before writing anything"
+
+key-files:
+  created:
+    - docs/VOICEVOX-SETUP.md
+    - requirements.txt
+    - src/japanese_avatar/voice/tts.py
+    - src/japanese_avatar/voice/models.py
+    - tests/test_tts_contract.py
+    - tests/fixtures/make_synth_fixtures.py
+    - tests/fixtures/synth_meta.json
+    - tests/fixtures/audio_query_short.json
+    - tests/fixtures/audio_query_long.json
+    - tests/fixtures/audio_query_slow.json
+    - tests/fixtures/speech_ja.wav
+    - tests/fixtures/speech_ja_long.wav
+    - tests/fixtures/speech_ja_slow.wav
+    - voicevox/.gitattributes
+    - voicevox/model/zundamon.vvm
+    - voicevox/open_jtalk_dic_utf_8-1.11/
+  modified:
+    - pyproject.toml
+    - uv.lock
+
+key-decisions:
+  - "voicevox_vvm 0.17.0, not 0.16.4: the matched release exists and ships vvm_format_version 2, which core 0.17.0 is built around"
+  - "ONNX Runtime option (c) lazy first-use download: (a) has no pip distribution at all and (b) has no build hook on a Gradio-SDK Space"
+  - "Directory-scoped voicevox/.gitattributes for the dictionary's .dic/.bin rather than editing plan 01-02's root file"
+  - "voicevox_core wired into pyproject as a marker-differentiated 'voice' extra so uv sync cannot silently prune it"
+  - "AudioQuery serialised to the VOICEVOX ENGINE mixed-case JSON schema, since 0.17.0 exposes no .json() method"
+
+patterns-established:
+  - "Every API name in a doc carries the file or URL it was read from, and was executed before being written down"
+  - "Fixture generators fail loudly rather than emit a fixture that does not exercise its target branch"
+  - "Miscounted or mis-shaped acceptance criteria are verified substantively and the discrepancy recorded, never satisfied by contorting code"
+
+requirements-completed: [VOIC-01]
+requirements-advanced: [AVTR-02, VOIC-03]
+
+# Metrics
+duration: 33min
+completed: 2026-08-27
+---
+
+# Phase 01 Plan 04: Japanese Voice Summary
+
+**The server speaks Japanese: `synthesize()` returns 24000 Hz WAV bytes plus a plain-dict `AudioQuery` carrying per-mora `consonant_length`/`vowel_length`, loaded from LFS-committed local assets on zero GPU — and the three committed fixtures exposed a frame-quantisation error in `01-RESEARCH.md` that would have broken plan 01-06's slow re-read.**
+
+## Performance
+
+- **Duration:** ~33 min
+- **Started:** 2026-08-27T00:07Z
+- **Completed:** 2026-08-27T00:40Z
+- **Tasks:** 3 of 3
+- **Files created/modified:** 26, verified by `git diff --name-only 5c6321a HEAD`
+
+## Task Commits
+
+1. **Task 1: Resolve the 0.17.0 API surface, acquire the runtime assets, write requirements.txt** — `54edb09` (feat)
+2. **Task 2: Implement synthesize() and the shared voice dataclasses** — `b0f00f6` (feat)
+3. **Task 3: Capture the ground-truth synthesis fixtures** — `122fc80` (test)
+4. *(follow-up)* **Record the measured cold-start cost of the lazy runtime fetch** — `84bdf64` (docs)
+
+## Everything the plan's `<output>` block required
+
+### Corrections to RESEARCH's inferred 0.17.0 API names
+
+RESEARCH's construction chain was **entirely correct** — `Onnxruntime.load_once(filename=...)`,
+`OpenJtalk(dict_dir)`, `Synthesizer(ort, ojt)`, `VoiceModelFile.open(path)`,
+`load_voice_model(model)`, `create_audio_query(text, style_id)`, `synthesis(query, style_id)` all
+exist and all work as written. Six things differed:
+
+| # | RESEARCH said | Reality | Who it affects |
+|---|---|---|---|
+| 1 | `voicevox_vvm` latest is 0.16.4; confirm the mismatch | **0.17.0 exists** (2026-08-12), one day before core 0.17.0. No mismatch. | this plan |
+| 2 | `json.loads(query.json())` | **`AudioQuery` has no `.json()`** (nor `.to_json`). It *is* a real `dataclass`, so `dataclasses.asdict()` is exact. | 01-06 |
+| 3 | `pauseLength` / `pauseLengthScale` are AudioQuery fields | **They do not exist in CORE 0.17.0** (they are ENGINE-only). Pipeline step 3 is a no-op. | 01-06 |
+| 4 | `SpeakerMeta` | **`CharacterMeta`** (the `.speaker_uuid` attribute is unchanged) | anyone importing it |
+| 5 | Open JTalk dict © Nagoya Institute of Technology | **Nara** Institute of Science and Technology — see licence note below | 01-09 |
+| 6 | `round(length / speedScale * 93.75)` | **Wrong.** See the next section — the most consequential finding in this plan. | 01-06 |
+
+### The frame-quantisation correction (please read this before plan 01-06)
+
+RESEARCH's `build_timeline` divides each phoneme length by `speedScale` and *then* quantises.
+VOICEVOX CORE 0.17.0 actually quantises **first**, at speed 1.0, then divides the resulting **frame
+count** and rounds again:
+
+```python
+frames = round(length / speed * 93.75)          # 01-RESEARCH.md   - WRONG
+frames = round(round(length * 93.75) / speed)   # CORRECT
+```
+
+At `speedScale == 1.0` the two coincide exactly, which is why RESEARCH's version looked verified —
+and it is exactly why this was worth catching here rather than in 01-06. Measured across 4
+sentences × 6 speed values (1.0, 0.9, 0.75, 0.5, 1.25, 1.5), predicted total frames against the
+true frame count of the synthesised WAV:
+
+| Formula | Correct |
+|---|---|
+| `round(length / speed * 93.75)` | **8 / 24** |
+| `round(round(length * 93.75) / speed)` | **24 / 24** |
+
+Worst observed error from the wrong form: **5 frames ≈ 53 ms**, five times the ±1 frame
+(10.667 ms) tolerance `test_no_drift_long_utterance` is specified with. This is `01-RESEARCH.md`
+Pitfall 5 ("normal speed syncs, slow speed drifts") arrived at from the other direction.
+
+Two consequences for plan 01-06:
+
+- Implement the corrected formula. `tests/fixtures/make_synth_fixtures.py` now asserts it
+  reproduces each fixture's true frame count before it will write anything, so the fixtures cannot
+  drift away from the engine unnoticed.
+- **`test_speed_scale` must not assert "the timeline is exactly 1/0.75× longer" against durations.**
+  Re-quantisation after scaling means the realised ratio lands *near* the requested one, not on it:
+  the committed `slow`/`long` ratio is **1.341085**, not 1.333333. Assert that the timeline matches
+  the WAV, which is the property lip-sync actually depends on.
+
+Everything else in RESEARCH's pipeline is confirmed: pause mora after its accent phrase, pre/post
+silence included in scaling, consonant before vowel, accumulate quantised frames not floats,
+banker's rounding (Python's built-in `round` already is).
+
+### Voice model identity
+
+| | |
+|---|---|
+| Original filename | **`0.vvm`** (from `voicevox_vvm` 0.17.0) |
+| Repo path | `voicevox/model/zundamon.vvm`, 59,308,488 B, Git LFS |
+| SHA256 | `ecd35374d4182cd883cba5040376f7f888cc6ba248b1c2f4cea07cdb34bb1318` |
+| `speaker_uuid` | `388f246b-8c41-4ac1-8e2d-5d79f3ff56d9` |
+| **`style_id` (ずんだもん ノーマル)** | **3** |
+
+Resolved from the release's own `README.txt` character↔style table and confirmed against the
+`metas.json` inside the downloaded file. The LFS pointer's `oid sha256` matches the hash above
+exactly, confirming the clean filter ran rather than the raw blob being stored.
+
+### Version pairing: yes, and it is not optional in the direction that matters
+
+**voicevox_core 0.17.0 + voicevox_vvm 0.17.0 — verified by executing it.** `0.vvm` reports
+`vvm_format_version: 2` in its internal `manifest.json` and every style has `type:
+"streaming_talk"`; both the format version and the `StyleType::StreamingTalk` variant were
+introduced *in core 0.17.0*. So core 0.17.0 reads vvm 0.16.4 fine, but core 0.16.x could not read
+vvm 0.17.0. Both are pinned to 0.17.0.
+
+### ONNX Runtime acquisition: option **(c)**
+
+- **(a) pip-installable companion — does not exist.** `pypi.org/pypi/voicevox-onnxruntime/json`,
+  `voicevox_onnxruntime` and `voicevox-core` all return **HTTP 404**. The runtime ships only as
+  `.tgz`/`.zip` archives from `VOICEVOX/onnxruntime-builder`. Nothing could go in `requirements.txt`.
+- **(b) downloader binary at build time — no hook exists.** A Gradio-SDK Space's build phase runs
+  pip against `requirements.txt` and apt against `packages.txt`; neither can execute `./download`.
+  Option (b) is documented as the local-development path.
+- **(c) chosen and exercised.** `get_synthesizer()` resolves `VOICEVOX_ORT_PATH` → an existing copy
+  under `voicevox_runtime/` → download the official archive → fall back to `load_once()`'s own
+  search path. Pointing `VOICEVOX_ORT_DIR` at an empty directory and calling `warmup()` fetched,
+  unpacked, loaded and synthesised successfully. The runtime is always referenced from its official
+  release URL and never copied into the repo, per the software terms' 禁止事項.
+
+### Measured warm-up
+
+| Stage | Time |
+|---|---|
+| `import japanese_avatar.voice.tts` | 0.110 s (no file or socket touched) |
+| `Onnxruntime.load_once(...)` | 0.093 s |
+| `OpenJtalk(dict_dir)` | 0.001 s |
+| `VoiceModelFile.open` + `load_voice_model` | 1.742 s |
+| **`warmup()` total, runtime present** | **1.73 s** |
+| **`warmup()` total, empty runtime cache (includes download)** | **2.66 s** |
+| Second `warmup()` (cache hit) | 0.000001 s |
+
+Per turn once warm: `create_audio_query` **1.2 ms**, `synthesis` **1215 ms** for 「こんにちは」. The
+cold-start penalty this design carries is therefore about **0.9 s** — the 8.2 MB runtime fetch. The
+~166 MB of dictionary and voice model that would otherwise dominate every 48 h wake arrive with the
+clone via LFS instead.
+
+### The `long` fixture
+
+**Text:** 「今日はいい天気ですから、公園を散歩してから、買い物に行きました。」 — the plan's suggested
+sentence, kept because it passed every assertion on the first try.
+
+| Property | Value |
+|---|---|
+| Mora count (incl. pause moras) | **36** (required ≥ 20) |
+| Phoneme count | 61 |
+| Vowel symbol set | `['I', 'N', 'U', 'a', 'e', 'i', 'o', 'pau']` |
+| **Devoiced vowels present** | **`I`, `U`** — from ですから and してから / しました |
+| `pause_mora` count | **2** |
+| Frames / duration | 516 / **5.504 s** |
+
+All three fixture cases, for the record:
+
+| Case | speedScale | Moras | Frames | Duration (s) |
+|---|---|---|---|---|
+| `short` (こんにちは) | 1.0 | 5 | 99 | 1.056 |
+| `long` | 1.0 | 36 | 516 | 5.504 |
+| `slow` (same text) | 0.75 | 36 | 692 | 7.381333333333333 |
+
+Regeneration is **byte-identical**: SHA-256 of all seven fixture files is unchanged across a second
+`make_synth_fixtures.py` run.
+
+## Accomplishments
+
+- **VOIC-01 is genuinely satisfied.** `synthesize("こんにちは")` returns a 50,732-byte RIFF WAV,
+  24000 Hz / mono / 16-bit, 1.056 s, with a JSON-round-trippable `AudioQuery` carrying per-mora
+  `consonant_length` and `vowel_length`. `tests/test_tts_contract.py` is **7 passed** against a real
+  installed `voicevox_core` — quoted verbatim below.
+- **Zero GPU on the synthesis path, proven by AST scan, not by grep.**
+  `test_no_gpu_imports_on_synthesis_path` parses every module under
+  `src/japanese_avatar/voice/` and rejects any import of the ZeroGPU allocation package or `torch`.
+- **The licensing branch is closed and written down.** Every fact plan 01-09's `LICENSES.md` needs —
+  three terms URLs, the exact `VOICEVOX:ずんだもん` credit string, the placement standard, the
+  flow-down obligation, the AudioQuery-triggers-credit Q&A, the Nemo pre-cleared swap with its style
+  IDs, and the BSD-3-Clause dictionary notice — lives in `docs/VOICEVOX-SETUP.md`. No "email the
+  rights holder" task was created; SSS LLC 免責条項 2 is quoted so it is never re-litigated.
+- **Cold start retired ahead of time.** 166 MB of assets arrive via LFS; only 8.2 MB is fetched, and
+  only inside a lazily-built synthesizer that `warmup()` pre-pays at startup.
+- **Quick loop kept inside its budget** at ~11 s against the 15 s Nyquist limit, after removing six
+  redundant syntheses.
+
+### Verbatim test output required by the plan
+
+```
+$ uv run pytest tests/test_tts_contract.py -q
+.......                                                                  [100%]
+```
+
+Seven tests: the six the plan specifies plus `test_fixtures_match_current_engine` added in Task 3.
+Full quick loop (`pytest tests/ -q --ignore=tests/e2e`): **13 passed**, timed at 10,890 / 11,633 /
+11,352 ms over three runs.
+
+## Decisions Made
+
+- **`voicevox/.gitattributes` instead of editing the root file.** `sys.dic` is 103 MB and the root
+  `.gitattributes` (plan 01-02) arms only `.vrm/.vvm/.wav/.onnx`. Git applies attributes
+  hierarchically, so a directory-scoped file adds `*.dic`/`*.bin` coverage without competing for
+  ownership of 01-02's file. Verified with `git check-attr filter`, which flipped from
+  `unspecified` to `lfs` for all four dictionary binaries.
+- **`voicevox_core` is a `pyproject.toml` extra, not a manual install.** Left out of the project
+  metadata, the next `uv sync` would prune it and `tests/test_tts_contract.py` would silently
+  degrade to "skipped" for every later plan in the phase. It is wired as the `voice` extra with
+  marker-differentiated `[tool.uv.sources]`, so one lockfile serves Windows dev and the Linux Space
+  builder. `requirements.txt` remains the Space's independent contract and carries only the
+  manylinux wheel.
+- **ENGINE mixed-case JSON schema for the serialised query.** `speedScale` camel, `accent_phrases`
+  and all mora keys snake. Not a style choice — it is the wire format the plan's own acceptance
+  criteria, RESEARCH's schema block and every VOICEVOX consumer expect.
+- **All three fixture WAVs committed, not just the short one.** `speech_ja_long.wav` and
+  `speech_ja_slow.wav` are 264 KB and 354 KB; having the real audio next to the query lets 01-06
+  assert against the signal rather than only against a recorded number.
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] `01-RESEARCH.md`'s frame-quantisation formula is wrong for `speedScale != 1.0`**
+
+- **Found during:** Task 3, when the `slow` fixture's rebuilt timeline missed its WAV by exactly one
+  frame while `long` matched to 2.7e-15 s.
+- **Expected:** the plan's fixture table asserts the slow timeline is "exactly `1/0.75x` longer".
+- **Found:** `round(length / speed * 93.75)` is right 8/24 across 6 speeds × 4 sentences;
+  `round(round(length * 93.75) / speed)` is right 24/24. Worst error 5 frames ≈ 53 ms.
+- **Fix:** documented under a dedicated "Frame quantisation" section in `docs/VOICEVOX-SETUP.md`
+  with the measurement table, and enforced in `make_synth_fixtures.py`, which asserts the correct
+  formula reproduces each fixture's true frame count before writing. `visemes.py` itself is plan
+  01-06's to write — this plan corrects the specification it will be written from, and does not
+  pre-empt it.
+- **Files modified:** `docs/VOICEVOX-SETUP.md`, `tests/fixtures/make_synth_fixtures.py`
+- **Committed in:** `122fc80`
+
+**2. [Rule 3 - Blocking] The Open JTalk dictionary had no LFS coverage**
+
+- **Issue:** `sys.dic` is 103,073,776 B. `git check-attr filter` returned `unspecified` for every
+  `.dic`/`.bin` file, so they would have been committed as raw blobs — rejected outright by a Hugging
+  Face Space repo, which requires LFS above 10 MB.
+- **Constraint tension:** the executor brief forbids modifying the root `.gitattributes` (owned by
+  01-02) while also requiring the dictionary to land through LFS.
+- **Fix:** a new `voicevox/.gitattributes` scoped to the directory this plan owns. Root file
+  untouched — confirmed by `git diff --cached --name-only | grep -cx '.gitattributes'` → `0`.
+- **Verification:** all four dictionary binaries flipped to `filter: lfs`; `git lfs status` shows
+  `sys.dic`, `char.bin`, `matrix.bin`, `unk.dic` and `zundamon.vvm` as LFS objects.
+- **Committed in:** `54edb09`
+
+**3. [Rule 2 - Missing Critical] `voicevox_core` would have been pruned by the next `uv sync`**
+
+- **Issue:** the plan says to install the Windows wheel "separately". Anything not in the lockfile is
+  removed by `uv sync`, which would have turned the VOIC-01 suite into a silent skip for plans
+  01-06/07/08.
+- **Fix:** `voice` extra in `pyproject.toml` with marker-differentiated `[tool.uv.sources]`. First
+  attempt failed universal resolution for `sys_platform == 'emscripten'`; corrected by putting a
+  disjunctive marker on the requirement itself.
+- **Files modified:** `pyproject.toml`, `uv.lock`
+- **Committed in:** `54edb09`
+
+**4. [Rule 1 - Bug] Quick loop had grown to ~20 s against a 15 s budget**
+
+- **Issue:** the test module as specified performs six syntheses of which three are exact duplicates
+  (`LONG_TEXT` at speed 1.0 three times, at 0.75 twice). `01-VALIDATION.md` caps quick-loop feedback
+  latency at ~15 s.
+- **Fix:** a module-scoped `synth` fixture memoising by `(text, speed)`. Three distinct syntheses now
+  cover every test. No assertion was weakened or removed.
+- **Verification:** 10,890 / 11,633 / 11,352 ms over three timed runs, 13 passed.
+- **Committed in:** `122fc80`
+
+**5. [Rule 1 - Bug] Fixture JSON was written with CRLF on Windows**
+
+- **Issue:** `Path.write_text` newline-translates by default, so the committed fixtures were CRLF and
+  git warned it would normalise them. A Linux regeneration would then produce different bytes,
+  destroying the byte-reproducibility property the fixtures depend on.
+- **Fix:** explicit `newline="\n"` on both writes. Confirmed 0 CRLF bytes in all four JSON files, and
+  regeneration is byte-identical.
+- **Committed in:** `122fc80`
+
+**6. [Rule 1 - Doc bug] Open JTalk dictionary attribution named the wrong institution**
+
+- **Expected:** RESEARCH and the plan's acceptance criterion both say "Nagoya Institute of
+  Technology".
+- **Found:** the shipped `COPYING` reads *"Copyright (c) 2009, **Nara** Institute of Science and
+  Technology, Japan"*. Both institutions are genuinely involved — Nara (NAIST) holds the dictionary
+  data; Nagoya Institute of Technology and the HTS Working Group hold Open JTalk itself.
+- **Fix:** `docs/VOICEVOX-SETUP.md` quotes the NAIST notice verbatim, states both attributions, and
+  flags that `LICENSES.md` must carry both — reproducing only Nagoya would fail the BSD notice on the
+  files actually redistributed here. The acceptance criterion's literal string is still present.
+- **Committed in:** `54edb09`
+
+### Acceptance criteria restated rather than skipped
+
+Two criteria are mis-shaped in the same way `01-02` documented. In both cases the substantive
+property was verified directly and no code was contorted.
+
+- **`grep -rc "import spaces\|@spaces" src/japanese_avatar/voice/` returns 0.** It initially returned
+  `1` — matching my own module docstring, which named the prohibition literally
+  (``@spaces.GPU``). The docstring was reworded so the grep is literally true as well as
+  substantively true; it now returns 0 for every file. The real guarantee is the AST scan in
+  `test_no_gpu_imports_on_synthesis_path`, which a grep cannot provide.
+- **`cases.*.duration_seconds` are "full-precision floats … (more than 3 decimal places)".** `slow`
+  is `7.381333333333333`, but `short` is `1.056` and `long` is `5.504` — exactly 3 decimal places.
+  These *are* the unrounded header values; VOICEVOX frame counts happen to be divisible by 3 here, so
+  `n·256/24000` terminates at 3 dp. The substantive property — that the recorded value equals
+  `getnframes()/getframerate()` exactly, with no rounding applied — was asserted directly and holds
+  for all three cases (`exact=True`). The generator additionally asserts the written WAV's header
+  duration equals what `synthesize()` reported, bit for bit.
+
+---
+
+**Total deviations:** 6 auto-fixed (3 bugs, 1 blocking, 1 missing-critical, 1 doc bug) + 2 acceptance
+criteria restated
+**Impact on plan:** No scope creep and no design improvisation. Deviations 2 and 3 were required for
+the plan's own criteria to be satisfiable; 1 and 6 correct specifications that later plans would
+otherwise have built on; 4 and 5 protect the phase's feedback loop and fixture reproducibility.
+
+## Issues Encountered
+
+- **The Open JTalk mirror in the VOICEVOX guide is dead.** `jaist.dl.sourceforge.net` fails DNS
+  resolution; `downloads.sourceforge.net` served the same archive (23,643,819 B) without incident.
+  Recorded in the setup doc as the working URL.
+- **A ruff lint/format standoff.** `SIM108` demanded a ternary for the ONNX Runtime branch while
+  `ruff format` insisted on collapsing that ternary onto a >100-char line. Resolved by shortening the
+  expression to `ort_kwargs = {"filename": ort_path} if ort_path else {}` — satisfying both and, as it
+  happens, reading better than either.
+- One transient `.ruff_cache` "Access is denied" warning on Windows during a concurrent invocation,
+  as in plan 01-02. Cosmetic; the run reported "All checks passed!".
+
+## Requirement Status
+
+**VOIC-01 → Complete.** `01-VALIDATION.md` binds it to `tests/test_tts_contract.py`, which this plan
+creates and which passes 7/7 against a real installed `voicevox_core`. The behaviour it names —
+"`synthesize()` returns non-empty WAV + parseable `AudioQuery`; zero GPU on the call path" — is
+demonstrated, not asserted. This is the one requirement in this plan's frontmatter and it is
+genuinely satisfied.
+
+**Deliberately NOT marked:** the plan's frontmatter lists only `VOIC-01`, so no over-claiming was
+possible here. For the record, this plan *advances* but does not satisfy:
+
+- **AVTR-02** — needs `tests/test_visemes.py`, which plan 01-06 creates. This plan supplies its
+  ground-truth fixtures and corrects its algorithm.
+- **VOIC-03** — the `speedScale` mechanism works and is fixture-backed, but the requirement's tests
+  (`test_speed_scale`, and the deployed `test_slower`) belong to plans 01-06 and 01-10.
+
+## Constraint Compliance
+
+- **No Space was created.** No `hf` CLI call, no `huggingface_hub` call, no Space README front-matter
+  written. Plan 01-01's human hosting gate remains uncleared and untouched.
+- **No `git push` occurred — and could not have.** `git remote -v` is still empty; this repo has no
+  remote configured.
+- **No money was spent.** No PRO subscription, no paid resource, no API with a meter.
+- **Python is 3.12.12** throughout (`uv run python -V`).
+- **`voicevox_core` 0.17.0**, wheel filename confirmed against the GitHub Releases API rather than
+  guessed. `requirements.txt` carries the **manylinux** wheel; the **win_amd64** wheel is confined to
+  the `pyproject.toml` `voice` extra behind a `sys_platform == 'win32'` marker.
+- **File ownership honoured.** `docs/ASSETS.md`, `README.md` and the root `.gitattributes` are all
+  absent from this plan's diff — verified with `git diff --cached --name-only`.
+- **Nothing vendored.** `find . -name "*.whl" -not -path "./.venv/*"` → 0. No `.so`, `.dll` or ORT
+  binary is tracked; `voicevox_runtime/` was already gitignored by plan 01-02.
+- **No GPU anywhere near synthesis.** AST-verified, and `grep -r "import spaces\|@spaces"` over
+  `src/japanese_avatar/voice/` returns 0 matches.
+- **Zero AI tutoring in scope.** No LLM, no level gating, no grammar database, no accounts, no
+  database. The discarded TTS fallback branch is absent from `docs/` and `src/` entirely (0 matches),
+  deleted rather than deferred.
+- Network egress was limited to what the plan's `<action>` blocks instruct: the GitHub Releases API,
+  the voice model, the Open JTalk dictionary, the ONNX Runtime archive, and the `voicevox_core` wheel.
+
+## Known Stubs
+
+None. Every artifact this plan claims is wired to a real data source and exercised by a passing test.
+
+`src/japanese_avatar/voice/models.py` defines `VisemeEvent` and `AvatarDirective`, which nothing
+consumes *yet* — but they are interface definitions the plan explicitly assigns to this file for
+plans 01-06 and 01-08 to consume, not placeholders. They contain no fabricated data and no
+hardcoded empty values flowing to UI.
+
+## User Setup Required
+
+None. `uv sync --extra dev --extra voice` is the only local step and it has already been run and
+committed to the lockfile.
+
+## Next Phase Readiness
+
+- **Plan 01-06** is unblocked and materially de-risked: three real `AudioQuery` fixtures with true
+  WAV durations *and* frame counts, a long case with 36 moras / 61 phonemes / two devoiced vowels /
+  two pause moras, the corrected quantisation formula with its evidence, and an explicit warning that
+  `pauseLength`/`pauseLengthScale` do not exist. **Read the "Frame quantisation" section of
+  `docs/VOICEVOX-SETUP.md` before writing `visemes.py`.**
+- **Plan 01-05** has `requirements.txt`. Note that the Space also needs `VOICEVOX_ORT_*` to be left at
+  defaults so the lazy fetch works, and that `git lfs pull` must succeed on the Space or the assets
+  arrive as 130-byte pointers — `tts.py` raises a message naming that case explicitly.
+- **Plan 01-07** has `tests/fixtures/speech_ja.wav` (24000 Hz mono 16-bit), the file
+  `tests/conftest.py`'s `speech_wav` fixture has been skipping on since 01-02.
+- **Plan 01-08** has `TurnTimings` and the `warmup()` hook to call at startup, plus real numbers to
+  budget against: 1.73 s warm-up, 1.2 ms query, ~1.2 s synthesis.
+- **Plan 01-09** has every voice-side licence fact `LICENSES.md` needs, including the dual
+  Nara/Nagoya attribution correction.
+
+Carried forward, unchanged by this plan:
+
+- The hosting model is still unresolved (ZeroGPU eligibility vs PRO) — plan 01-01's human gate.
+- Per-turn GPU-second cost remains unmeasured (and remains zero for speech output, by construction).
+- Resolved: "VOICEVOX character terms still need a human read" is now **closed** — all three licence
+  layers were read in full and recorded, and the rights holder declines qualification questions as a
+  matter of policy, so there is no further human step available or required.
+
+## Self-Check: PASSED
+
+All 16 files claimed created exist on disk; all 2 claimed modified exist. All 4 commit hashes
+(`54edb09`, `b0f00f6`, `122fc80`, `84bdf64`) resolve in `git log`. File count stated as **26** against
+`git diff --name-only 5c6321a HEAD`, not estimated.
+
+Full plan verification block re-run after the final commit:
+
+| Check | Result |
+|---|---|
+| `pytest tests/test_tts_contract.py -q` | **7 passed** |
+| `pytest tests/ -q --ignore=tests/e2e` | **13 passed**, ~11.0 s |
+| `python -c "…synthesize('こんにちは').duration"` | `1.056` |
+| `git lfs ls-files` | lists `voicevox/model/zundamon.vvm`, `tests/fixtures/speech_ja.wav` (+ 8 more) |
+| `grep -rc "import spaces\|@spaces" src/japanese_avatar/voice/` | **0** for every file |
+| `find . -name "*.whl" -not -path "./.venv/*"` | empty |
+| `ruff check . && ruff format --check .` | "All checks passed!" / "13 files already formatted" |
+| `requirements.txt` non-empty lines | **4**, one `.whl`, zero vendored |
+| `git status --short` | clean — no untracked files |
+| `git remote -v` | empty — no push was possible |
+
+---
+*Phase: 01-voice-avatar-loop-skeleton*
+*Completed: 2026-08-27*