From 140a7ada0fe98bed8a94463fc41d5764e078abe8 Mon Sep 17 00:00:00 2001 From: Zwitschi Date: Fri, 6 Nov 2026 09:40:28 +0100 Subject: [PATCH] Plan the 0.9.9-1.0.0 roadmap and re-evaluate the NPC base Move the gap analysis and risks into PLAN.md, version the character track (0.9.9 rig correction, 0.9.10 roster) and split 0.9.11-0.9.12 polish and verification out of the old 0.10.0 milestone. Add roadmaps to 0.10.0, 0.11.0 and 1.0.0, record the Quaternius face-fidelity gate and the rest-relative pose finding in MEMORY.md, and move the completed 0.9.7 and pose-harness sections to DONE.md. --- AGENTS.md | 18 +- DONE.md | 49 +++ MEMORY.md | 53 ++- PLAN.md | 204 ++++++++- README.md | 15 +- TODO.md | 859 ++++++++++++++++++++----------------- docs/development-status.md | 7 +- 7 files changed, 760 insertions(+), 445 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 27d7923..f7f7f1c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -90,14 +90,16 @@ specialists the task needs: ### Project rules that override a skill -1. **The project contract wins.** `npc_base` mesh node, the 13 required core bones at their rest - positions, five tint slots, front on Blender −Y / Godot +Z, grounded feet, 24,000 - triangles / 24,000 glTF vertices per character, 1,500 per gear, 4,000 per prop. Optional - extra bones (fingers, face, toes) are allowed if they do not move the core rest positions. The - Quaternius 62-joint source rig is authoring-only and bakes to this 13-core contract - (ADR-0017); it is not a runtime dependency. A skill may recommend another topology, naming or - budget scheme; do not adopt it unless the change is explicitly planned and the contract, tests - and docs are updated together. +1. **The project contract wins.** `npc_base` mesh node, five tint slots, front on Blender −Y / + Godot +Z, grounded feet, 24,000 triangles / 24,000 glTF vertices per character, 1,500 per + gear, 4,000 per prop. The shipped procedural library uses the 13 required core bones at their + rest positions; optional extra bones (fingers, face, toes) are allowed if they do not move the + core rest positions. The one documented exception is the accepted Quaternius runtime path + ([ADR-0018](docs/adr/0018-quaternius-stage2-runtime-rig.md)): it keeps the 62-joint source rig + at runtime while the 0.9.9 face/silhouette gate is open, and it must still supply the five tint + slots, valid gear attach points and the same budgets. Both paths stay tested until that gate + closes. A skill may recommend another topology, naming or budget scheme; do not adopt it unless + the change is explicitly planned and the contract, tests and docs are updated together. 2. **Blender MCP is optional interactive tooling.** The headless flatpak scripts (`tools/blender_assets.py`, `tools/npc_pipeline.py`) remain authoritative. MCP may be used for local part exploration; setup and safety are in [`docs/asset-tooling.md#optional-interactive-blender-mcp`](docs/asset-tooling.md#optional-interactive-blender-mcp). diff --git a/DONE.md b/DONE.md index 5178f96..0c81e53 100644 --- a/DONE.md +++ b/DONE.md @@ -2143,3 +2143,52 @@ must inherit the reviewed face/hand/gear baseline instead of multiplying whateve project-owned clothing; keep out of CI/build.) - [x] Body-shape diversity decision (2026-11-04, owner): **yes** — use MakeHuman for the next character pass. Promoted to the **MakeHuman character pipeline** track. + +## NPC pose harness (v0.9.8) + +Completed 2026-11-04. The pose harness bug that made every staged capture save a rest frame +was found and fixed; it unblocked the weights/pose evidence and the seated/walking deformation +fixes. User-facing changes are recorded under 0.9.7 and 0.9.8 in `CHANGELOG.md`. + +Goal: `src/test/capture_npc_pose.gd` reports a pose but saves rest frames; the root cause is +narrowed to the skinned mesh ignoring its `Rig` parent transform. Fixing it unblocks the +weights/pose column of the 3D review; the evidence now feeds the Quaternius base bake. + +*Skill route: `rigging`; evidence in `docs/3d-model-review.md` §"Pose evidence is blocked".* + +- [x] Root cause found (2026-11-04): the harness never disabled the avatar's `_physics_process`, + so `_advance_fsm` + `_move_toward_target` ran every tick and reset `arrived`/velocity, which + made `theater_pose()` return "idle" and reverted the pose to rest. (The earlier "moving the + `Rig` child does not render" probe was a red herring: it set `rig.position.y` inside `_shoot()` + in the same frame as `root.get_texture().get_image()`, so it never got a rendered frame.) +- [x] Harness rebuilt: `capture_npc_pose.gd` now calls `set_physics_process(false)`/ + `set_process(false)` after staging the avatar; the pose survives because only the direct + `_animate()` ticks drive it. Verified: sit vs idle diff 5.63, walk vs idle diff 2.29, and the + vision judge confirms the seated frame reads as crouched. +- [x] Captured all poses for all 12 variants (idle / walk_contact / walk_pass / sit × full + + shoulder views = 96 frames) and built `sheet_pose.jpg`/`sheet_shoulder.jpg` under `tmp/`. + (No separate "wave" theater pose exists; the escalation raise-hand gesture is not a distinct + capture in this harness.) + +## Milestone 0.9.7 — Character development (patch) + +Completed 2026-11-04 and published as v0.9.7. The detailed character-development record already +lives under "Character development" above; this milestone checklist is kept verbatim for the +release record. + +Goal: release the finished procedural character development — the realistic face on all eight +variants, the four crowd-variety characters and the per-role pools — as a **patch** on top of +0.9.6. This keeps the 3D model and map improvements out of the patch; they land together in the +0.10.0 minor. + +- [x] Rig pose harness fixed and the weights/pose evidence captured (see the top track). +- [x] Character work done: 12-character library, realistic face, crowd variants, per-role pools, + 24-NPC budget 6.94 ms (152,464 tris / 168 meshes). +- [x] QA + local build for 0.9.7: Godot 277/277, Python 161/161, audit 49 OK, fit/proportions + 12/12, release smoke matrix green, gallery 21/0, clean worktree build (Linux 172 MB, + Windows 206 MB, macOS 159 MB, Web 111 MB, HQ 266 MB), checksums verified, Linux binary + launches headless. Tagged `v0.9.7` (CI build/publish follows). + +**Exit:** met — 0.9.7 ships the 12-character library (face realism + crowd variety) with the pose +harness fixed; the runtime contract is unchanged. The Quaternius NPC base and the map rebuild are +not in this patch (they target 0.10.0). diff --git a/MEMORY.md b/MEMORY.md index ee54f31..11f616b 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -107,6 +107,26 @@ canonical implemented-features list in `docs/development-status.md`. cleared, storefront/rating approval pending, external playtests and full hardware matrix pending. Recorded in `CREDITS.md`, `PRIVACY.md`, `docs/accessibility.md`, `docs/known-limitations.md`. +- **Release roadmap (2026-11-05, owner):** `0.9.9` Quaternius pilot base (rig/export fix, + rest-relative pose math, owner face/silhouette gate), `0.9.10` 12-role roster, `0.9.11` + scheduled venue/prop/lighting polish, `0.9.12` performance/Web/accessibility verification, + `0.10.0` public-readiness minor, then `0.10.1`–`0.10.3` fixes, `0.11.0` replay + fourth venue + + localization foundation, `0.12.0` signed/storefront builds + save v2, `0.13.x` content complete + and release candidates, `1.0.0` stable. The full gap analysis and roadmap live in `PLAN.md`; the + character track is versioned now, so a blocked rig cannot block the release. Planning only — + none of these versions is built yet. +- **Quaternius face/readability gate (2026-11-05):** the base is 6.2k tris total and replaces a + library with a sculpted realistic face, so the 0.9.9 gate is a product decision, not just an + art check. Owner picks full swap / crowd-only / extra head detail. Do not lower character + fidelity silently. +- **Pose composition is rest-relative (2026-11-05, hypothesis to verify at 0.9.9):** Godot's + `set_bone_pose_rotation` offsets from the bone rest, so `rest * Quaternion(axis, angle)` only + equals the target when the rest is ±identity (the old 180° rig). The candidate fix is + `rest.inverse() * target`, proven with measured global bone transforms. +- **One character source, one fallback:** no new NPC source without an ADR. MPFB body work stays + closed, the Stage-1 proportion warp is not reopened, and the procedural `npc_base` + MakeHuman + head stay tested until the Quaternius base passes its gate. + ## Gotchas / Known Issues - **Two character builders — do not confuse them.** `tools/blender_assets.py` is the real builder @@ -132,6 +152,8 @@ canonical implemented-features list in `docs/development-status.md`. bind matrices (Godot renders A-pose even though the rest is arm-down). The runtime `_pose_bone` `rest * Quaternion(axis, angle)` only cancels when `rest² = identity` (old rig's 180° rest); the Quaternius ~76° rest does not, so the pose formula must be re-derived for a non-180° rest. + Godot's bone pose rotation is relative to the bone rest, not absolute: treat + `rest.inverse() * target` as the candidate and verify with measured global bone transforms. - Image models have per-model size floors/caps (Seedream needs 1920+; `GEN_SIZE=2048`, do not lower; gpt-5-image-mini caps lower). `generate_image` applies model-specific sizing; concept generation defaults to `--request-size 1536`. @@ -205,20 +227,27 @@ canonical implemented-features list in `docs/development-status.md`. ## Open Questions - Whether the responder avatar should be playable/controllable or purely scripted. -- Localization target languages beyond English. -- macOS notarization approach for broad distribution. +- Quaternius scope: full 12-role swap, crowd-only, or extra head detail (owner decision at 0.9.9). +- Localization target languages beyond English (0.11.0/0.12.0). +- macOS notarization approach for broad distribution (0.12.0). +- Fourth-venue choice for 0.11.0 (candidate: TCL Chinese Theatre forecourt). ## Current State -The playable build covers the three venues, tutorial/campaign/checkpoints, the 0.9.3–0.9.6 -polish/texture/integration passes and the Blender + realism asset pipeline (see `DONE.md` and -`CHANGELOG.md`). The 12-character library (realistic face + four crowd variants) and the -Comedy Store map rebuild are complete. **Priority (2026-11-05, owner):** 1) the **Quaternius NPC -base migration** (bake the CC0 Quaternius character to the runtime contract), 2) the 3D model and -map improvements, 3) ship it all together in the **0.10.0 minor**. The 0.9.7/0.9.8 -character patches are published; `TODO.md` is the priority source. The active implementation is -the Quaternius base migration (ADR-0017); planning/docs were rewritten and `tmp/` cleaned on -2026-11-05, but no character GLB has been rebuilt yet. Test counts as of 2026-11-05: Python -167/167 (last run), Godot 277/277 (last run before the docs-only pivot), `check_docs` OK. +v0.9.8 is published. The build covers the three venues, the shift loop, tutorial/campaign/ +checkpoints, the 0.9.3–0.9.8 polish/texture/integration/character passes and the Blender + +realism asset pipeline (see `DONE.md` and `CHANGELOG.md`). The 12-character procedural library +(realistic face + four crowd variants) and the Comedy Store map rebuild are complete. + +**Planning pivot (2026-11-05, owner):** the character and map work was re-sequenced into +patches (`0.9.9`–`0.9.12`) with `0.10.0` as the public-readiness minor. The gap analysis and the +three release roadmaps now live in `PLAN.md`; `TODO.md` is the executable task list. ADR-0017 +Stage 1 (proportion warp) is dead; ADR-0018 option 2 (62-joint runtime) is accepted. The +`quaternius_base.glb`, joint map, slot map and `NpcAvatar` name mapping exist, but the arm-down +skin export and the pose composition are still wrong — no Quaternius character has rendered +correctly in Godot yet, and no character GLB has been rebuilt since the pivot. + +Test counts as of 2026-11-05: Python 167/167 (last run), Godot 277/277 (last run before the +docs-only pivot), `check_docs` OK. diff --git a/PLAN.md b/PLAN.md index e679a00..8210fc7 100644 --- a/PLAN.md +++ b/PLAN.md @@ -16,22 +16,91 @@ The game is about **judgment, communication, access verification, and proportion ## Development Priorities -The active planning order is set in [`TODO.md`](TODO.md) and in `AGENTS.md`: +The active task order is in [`TODO.md`](TODO.md); the gap analysis and the release roadmap are +below. The current order is: -1. **Quaternius NPC base (unversioned).** Use the CC0 **Quaternius Ultimate Modular - Characters** as the primary NPC mesh and animation source. Bake a canonical Quaternius base - onto the runtime `npc_base` contract (13 core bones, five tint slots, 24,000/24,000) so the - existing gear, `NpcAvatar` and gameplay poses keep working. If the proportion warp fails the - silhouette gate, stop and decide on the 62-joint source rig in a new ADR. See - [ADR-0017](docs/adr/0017-quaternius-npc-base.md) and - [`docs/npc-model-sourcing.md`](docs/npc-model-sourcing.md). MakeHuman/MPFB body work is closed. -2. **Local map development (unversioned).** Move beyond stylized venue reconstruction with - licensed OpenStreetMap and 3D building data, downloaded reference imagery for photoreal - facades, AI-assisted composition, and a Gaussian-splatting evaluation that stays in the - development pipeline unless it proves runtime-safe. -3. **Versioned release hardening.** The 0.10.0 release candidate and later semantic versions come - after the unversioned development tracks in planning order. Versions are assigned only when a - track's scope is accepted into a release. +1. **0.9.9–0.9.12 patches.** Finish the character base (the accepted Quaternius 62-joint runtime), + roll it out to the 12 roles, close the scheduled venue/prop/lighting polish, and verify + performance, Web and accessibility. +2. **0.10.0 minor.** Public readiness: external playtests, balance acceptance, legal/storefront + approval, the platform matrix and the documentation/picture lock. +3. **0.10.x patches → 0.11.0.** Content and systems depth: live body-camera replay, a fourth + venue and the localization foundation. +4. **0.12.0 → 1.0.0.** Platform/distribution, content complete, release candidates and the stable + release. + +Versions are assigned only when a track's scope is accepted into a release (see +[Release Roadmap](#release-roadmap)). Unversioned tracks — the 3D review evidence base, +maintenance and the Gaussian-splatting study — do not receive a placeholder version. + +## Plan Evaluation (2026-11-05) + +The game plan itself is sound and largely built: three venues, the escalation ladder, access +artifacts, the radio/report system, the shift review and the campaign loop all exist and are +tested. What needed fixing was the **delivery plan**, not the design. + +- **Character sourcing churned.** The project moved procedural → MakeHuman → Quaternius, and the + Quaternius Stage-1 warp failed its own gate. That leaves a correct decision (ADR-0018) with a + half-finished implementation. The plan now makes the rig correction one small version, gates the + roster behind a face/readability decision, and keeps exactly one fallback. +- **One milestone carried too much.** The old 0.10.0 mixed character work, map work and every + public-release gate, so one blocked export blocked the release. Character and venue polish are + now patches; 0.10.0 is only the release gate. +- **Unversioned work had no deadline.** The 3D review backlog could grow without bound. It is now + capped: the ranked venue/prop/lighting items are scheduled into 0.9.11, the budget checks into + 0.9.12, and everything else is an explicit accept or deferred. Gaussian splatting stays + unscheduled because no product need justifies its risk yet. +- **Legal, signing and storefront work is release work, not polish.** It now has named checkboxes + in 0.10.0 and 1.0.0 instead of living in prose. +- **What is deliberately not planned:** new genres or mechanics, a live-service model, or a + runtime splat renderer. The de-escalation-first, rare-emergency design stays frozen. + +Feasibility: the remaining character work is small in geometry terms (6.2k triangles against a +24k cap) and larger in rig/export terms; the venue work is polish; most release gates are +evidence gathering rather than engineering. The main schedule risk is external review and +approval, not code. + +## Character Creation Re-Evaluation (2026-11-05) + +**Where it stands.** The shipped library is 12 procedural Blender variants (4.7k–5.8k triangles +each) with a sculpted face, five tint slots and 18 gear pieces. The owner then chose the CC0 +**Quaternius Ultimate Modular Characters** as the primary source. Stage 1 (warp the Quaternius +mesh onto the 13-core contract) failed its silhouette gate — arm ×1.63, leg ×0.74, torso ×1.61, +judged distorted. [ADR-0018](docs/adr/0018-quaternius-stage2-runtime-rig.md) therefore adopts the +source **62-joint rig at runtime**: no warp, source LOD (3,199 verts / 6,206 tris), source +Idle/Walk clips, and gear pivots re-derived from the Quaternius skeleton. + +**What is already built.** The canonical `quaternius_base.glb` (welded, grounded, arm-down rest), +the 62→13 joint map, the material→five-slot map, the clip inventory (24 clips; Idle and Walk in +scope) and the `NpcAvatar` joint-name mapping with rest-derived gear pivots. + +**What actually blocks it.** Two technical items about the export and the pose math, not the art: + +1. the arm-down GLB renders in A-pose in Godot because the bake writes wrong inverse bind + matrices; and +2. `_pose_bone()` composes rotations as `rest * Quaternion(axis, angle)`, which only cancels for + the old 180° rest, not the Quaternius ~76° rest. + +**Re-evaluation findings.** + +- Triangle budget is not the problem (6.2k against a 24k cap). Do not decimate the source. +- **Face fidelity is the real risk.** The 0.9.7 library has a sculpted realistic face; the + Quaternius head is low-poly. A blanket swap would regress every close-up. The plan therefore + makes the owner choose at 0.9.9 between (a) a full swap, (b) Quaternius for crowd roles with the + procedural library for named roles, or (c) extra head subdivision/hair cards on the Quaternius + head. +- **Animation** becomes clip-driven, which removes the hand-built pose composition as the main + path. Poses the clips do not cover (seated, raise-hand, head turn) must be decided explicitly + rather than patched per scene. +- **One fallback, no third source.** The procedural `npc_base` and the MakeHuman head stay tested + until the new base passes the gate. MPFB body work stays closed and the Stage-1 warp is not + reopened. A new character source needs a new ADR. +- **Sequence matters.** Fix the rig first (0.9.9), then the roster (0.9.10). Rolling a broken rig + across 12 variants would waste the whole pass. + +**Reversal condition.** If the skin cannot be exported correctly without a new exporter path, or +if the owner rejects the low-poly face in every option, the plan falls back to the procedural +library and retires Quaternius with a recorded ADR. That decision is made at 0.9.9, not later. ## Core Gameplay Loop @@ -171,7 +240,7 @@ The action wheel prioritizes de-escalation: Stop, Look, Point, No, Ask, Inspect, The visual direction is readable stylized realism: -- **Character direction:** 12 skinned NPC variants, 18 gear pieces and 20 street/venue props. The active character track is the Quaternius base migration ([ADR-0017](docs/adr/0017-quaternius-npc-base.md)): use the CC0 Quaternius mesh/animation source, bake it to the runtime contract, and retire the bespoke procedural body work. +- **Character direction:** 12 skinned NPC variants, 18 gear pieces and 20 street/venue props. The active character track is the Quaternius base at runtime ([ADR-0018](docs/adr/0018-quaternius-stage2-runtime-rig.md)): the CC0 source mesh keeps its proportions on the 62-joint rig, Idle/Walk run as clips, and the procedural library stays as the tested fallback until the face/silhouette gate passes. See [Character Creation Re-Evaluation](#character-creation-re-evaluation-2026-11-05). - **Realism pass:** AI-assisted per-phase skyline panoramas, v2 surface tiles with normal maps, wet asphalt at night, a warm day haze, phase-specific sun/exposure/fog, a tight flashlight spot (no beam geometry), and denser foliage. - **Local map direction:** the venues are currently stylized reconstructions. The local-map track evaluates licensed OpenStreetMap/3D building data, licensed reference photography, AI-assisted composition and Gaussian splatting as a development tool; online data and splat rendering are not runtime dependencies. - **References and QA:** runtime UI art lives in `assets/images/ui/`; reference/art-direction sets live in `docs/screens/designs/` and `docs/screens/concepts/`; captures live in `docs/screenshots/`; realism runs live in `docs/screens/realism/`. `screen_designs.py compare/judge` and `tools/check_screenshots.sh` guard drift. @@ -198,6 +267,106 @@ Primary decisions: [ADR-0007](docs/adr/0007-locomotion-and-input-layers.md), [AD `config/version` in `project.godot` is the single version source (currently `0.9.8`). Releases are tagged `v`; the CI pipeline builds and publishes the standard artifacts plus the optional Desktop HQ zip. Version bumps follow [Semantic Versioning](https://semver.org/): every major, minor and patch increment needs a changelog entry, a local `tools/build_releases.sh` build, and artifact/checksum verification before tagging. Unversioned development tracks do not receive a version until their scope enters a release. See [`docs/RELEASING.md`](docs/RELEASING.md) and [`README.md`](README.md) for commands. +## Gap Analysis + +**Published baseline:** v0.9.8 (2026-11-04) — three playable venues, tutorial/campaign/checkpoint +resume, the access/radio/escalation loop, shift review, the 12-character Blender library, 277 +Godot + 162 Python tests, a 21/21 screen-design judge and Compatibility/Web/Desktop HQ builds. + +**Current source:** 0.9.8. The 0.10.0-rc.1 package built on 2026-11-03 is stale and is superseded +by the patch sequence below; it is not a published release. + +| Area | Remaining gap | Milestone | +| --- | --- | --- | +| Character base | Quaternius arm-down skin export, rest-relative pose composition, face/silhouette acceptance | 0.9.9 | +| Character roster | 12-role mapping, modular outfits, gear fit, AO/texels, budget evidence | 0.9.10 | +| Venue and asset polish | Ranked prop/foliage/lighting/set-dressing fixes, collider verification | 0.9.11 | +| Performance and Web | Frame/memory/load evidence after the content changes, LOD/impostor verification | 0.9.12 | +| Onboarding and balance | External first-time-player evidence, balance sweeps/tuning, content lock | 0.10.0 | +| Accessibility and localization | Acceptance pass, caption coverage, pseudo-locale/length checks | 0.9.12 / 0.10.0 | +| QA and release engineering | Full smoke matrix, clean build/checksum verification, target-matrix launches | 0.10.0 | +| Legal, signing, storefront | macOS signing/notarization, AI-provider rights, storefront/rating approval, privacy sign-off | 0.10.0 / 0.12.0 | +| Systems and content depth | Live incident replay, fourth venue, localization foundation | 0.11.0 | +| Distribution | Signed storefront builds, frozen save contract, launch languages, hardware matrix | 0.12.0 | +| Stable release | Content complete, accessibility audit, release candidates, 1.0.0 decision | 0.13.0 / 1.0.0 | +| Future | More venues/seasonal content, image-to-mesh props, other deferred ideas | Unscheduled | + +The 0.9.3 UI, 0.9.4 animation, 0.9.5 texture, 0.9.6 integration, 0.9.7 character development and +0.9.8 deformation fixes are complete in [`DONE.md`](DONE.md); they are not remaining gaps. The +2026-11-01 documentation audit is also closed. + +## Release Roadmap + +Every version below follows the release procedure in `AGENTS.md`. Patch versions contain fixes and +polish; minor versions add user-facing features; the major version is the stable release with a +compatibility promise. Each version's executable checklist is in [`TODO.md`](TODO.md). + +### Roadmap to 0.10.0 + +The goal of this line is to finish the character and venue work and clear every public-release +gate. The character track is versioned rather than unversioned so a blocked rig cannot hold the +whole release. + +| Version | Type | Scope | Exit criterion | +| --- | --- | --- | --- | +| 0.9.9 | patch | Quaternius pilot: correct skin export, rest-relative pose math, Idle/Walk verification, owner face/silhouette gate, one-role (or crowd-only) rollout | A Quaternius NPC renders and animates correctly and ships behind a tested procedural fallback | +| 0.9.10 | patch | 12-role roster, modular outfits, five slots, AO/texels, gear fit, 12×6 baseline | The full roster passes contract, gear, budget and owner-baseline gates | +| 0.9.11 | patch | Scheduled 3D review fixes: props/foliage, gear silhouette, venue shape language, lighting, set dressing, colliders | Every scheduled P1/P2 item is fixed or accepted with a measurement | +| 0.9.12 | patch | Performance/Web/LOD/memory verification plus accessibility and pseudo-locale checks | No regression against the pre-character baselines | +| 0.10.0 | minor | Public readiness: external playtests, balance acceptance, legal/storefront/signing decisions, platform matrix, docs and picture lock | 0.10.0 is content-locked, externally played, legally reviewed, documented and reproducibly built | + +### Roadmap to 0.11.0 + +This line turns a stable 0.10.x into a deeper game: the incident timeline becomes a live replay, a +fourth venue enters the campaign, and the text catalogue becomes a real localization pipeline. + +| Version | Type | Scope | Exit criterion | +| --- | --- | --- | --- | +| 0.10.1 | patch | Onboarding and accessibility issues deferred from the 0.10.0 playtests | First-hour and accessibility defects closed | +| 0.10.2 | patch | Balance/fairness sweeps, review-text and difficulty-progression tuning | Every balance-acceptance cell is in target or explicitly accepted | +| 0.10.3 | patch | Save/checkpoint edge cases, gamepad/remap, pause/resume, small quality-of-life fixes | No known P1 stability defect remains | +| 0.11.0 | minor | Live body-camera replay, fourth venue (candidate: TCL Chinese Theatre forecourt), localization foundation with one secondary language | The new systems ship without regressing performance, accessibility or balance | + +### Roadmap to 1.0.0 + +This line is about distribution, contracts and completeness: signed builds on the launch stores, a +frozen save format, finished content and release candidates. + +| Version | Type | Scope | Exit criterion | +| --- | --- | --- | --- | +| 0.11.1 | patch | Replay/venue/localization fixes from wider play | No P1 defect in the 0.11.0 feature set | +| 0.11.2 | patch | New-venue balance, campaign pacing and content readability | The 0.11.x line is stable enough to freeze its contracts | +| 0.12.0 | minor | macOS signing/notarization, storefront packages/metadata/ratings, save-format v2 freeze, hardware matrix, launch languages | Signed, storefront-ready builds exist on every launch platform | +| 0.12.1 | patch | Signing, installer, metadata and save-migration fixes from storefront dry runs | Every storefront build installs, launches and migrates cleanly | +| 0.13.0 | minor | Content complete: all planned venues/events/dialogue, audio decision, final tutorial, accessibility audit, balance freeze | All planned content is implemented and frozen | +| 0.13.1 | patch | Release candidate 1: full smoke/performance/save/accessibility matrix | A candidate passes every gate except final approval | +| 0.13.2 | patch | Release candidate 2: verify fixes, freeze release notes/credits/privacy/known limitations | The final candidate is reproducible and documented | +| 1.0.0 | major | Stable release: legal/storefront/rating approval, hardware/accessibility/localization sign-off, no P0/P1, publish on every platform | 1.0.0 is published with verified checksums and no open blocker | + +## Roadmap Dependencies and Risks + +- Content volume is the largest schedule risk; tutorial and campaign work must not outrun the + event/dialogue matrix. +- The vision judge is a dev-time aid with an external key and budget; CI must never make it a hard + gate. +- Godot engine changes can alter lighting and imports; do not combine an engine baseline move with + a content or feature milestone. +- Signed macOS builds, AI provenance and storefront approval are release blockers, not polish. +- The character pipeline is the current critical path. The rig/export fix must be proven on one + variant before the roster rollout; otherwise 0.9.10 multiplies a defect. +- Photo-derived map assets add a provenance risk: downloaded or user-supplied photos can carry + unclear licences, identifiable people, plates and property restrictions. No photo- or + splat-derived asset ships without a completed sidecar, consent/licence review and redaction. +- Gaussian-splat training is GPU/disk-heavy and the toolchain churns; keep it offline, + version-pinned and outside CI, and never make a runtime splat renderer a release dependency. +- The Blender skill pack is local, unversioned guidance; it can drift from the project contract or + assume Blender MCP. Re-verify every adopted technique with `inspect`/`audit`/`fit` and never make + a skill, asset pack or tool version a build or CI dependency. +- The 3D re-evaluation can expand without bound. Cap it with the scorecard ranking: P0/P1 only, one + asset family per commit, and an explicit accept for everything else. +- Keep the de-escalation-first rules and rare-emergency design unchanged while adding progression, + difficulty and feedback. + ## Design Direction The game should feel like a tense workplace simulation with occasional crisis moments. The most satisfying outcome is not overpowering an NPC; it is recognizing the situation early and resolving it calmly. @@ -208,4 +377,5 @@ The game should feel like a tense workplace simulation with occasional crisis mo - A rare Bob Dobbs cameo (Easter-egg appearance; placement note in `MEMORY.md`). - Specific unusual NPC behaviors, such as slapping their own face, using hands as scissors, or interacting with props unexpectedly. -- Live 3D body-camera replay; additional venues or seasonal events; real voice/dialogue audio; an image-to-mesh prop pipeline. +- A fifth venue or seasonal events after the 0.11.0 fourth venue proves the venue pipeline. +- Real voice/dialogue audio if the 0.13.0 audio decision does not fund it; an image-to-mesh prop pipeline remains unscheduled. diff --git a/README.md b/README.md index 5a32a9d..fb66e61 100644 --- a/README.md +++ b/README.md @@ -8,11 +8,12 @@ The central design goal is simple: ## Development Priorities -The active planning order lives in [`TODO.md`](TODO.md) and [`AGENTS.md`](AGENTS.md): +The active planning order lives in [`PLAN.md`](PLAN.md) (gap analysis and release roadmap), [`TODO.md`](TODO.md) (executable checklist) and [`AGENTS.md`](AGENTS.md): -1. **3D model and local map re-evaluation** — score every shipped asset, then evaluate licensed OpenStreetMap/3D data, reference-derived photoreal facades, AI-assisted composition and a Gaussian-splatting development evaluation. -2. **Quaternius NPC base** — use the CC0 Quaternius Ultimate Modular character as the primary mesh and animation source, baked to the existing runtime contract. Source evaluation and the licence decision are in [`docs/npc-model-sourcing.md`](docs/npc-model-sourcing.md) and [ADR-0017](docs/adr/0017-quaternius-npc-base.md). -3. **Versioned release hardening** — the 0.10.0 release candidate and later semantic versions follow the unversioned development tracks. +1. **`0.9.9`–`0.9.12` patches** — finish the Quaternius NPC base on the accepted 62-joint runtime, roll it out to the 12 roles, close the scheduled venue/prop/lighting polish, then verify performance, Web and accessibility. +2. **`0.10.0` minor** — public readiness: external playtests, balance acceptance, legal/storefront/signing decisions, the platform matrix and the documentation/picture lock. +3. **`0.10.x` → `0.11.0`** — live incident replay, a fourth venue and the localization foundation. +4. **`0.12.0` → `1.0.0`** — signed storefront builds, a frozen save contract, content complete, release candidates and the stable release. Versions are assigned only when a track's scope is accepted into a release. Every major, minor and patch version requires a changelog entry, a local release build and artifact verification before tagging. @@ -191,9 +192,9 @@ v0.9.8 is the current source version: the character-development patch with the and save-migration/release hardening. It sits on the 0.9.6 integration checkpoint, 0.9.5 texture refinement, 0.9.4 NPC visual optimization, 0.9.3 UI/accessibility polish, 0.9.2 Hollywood/Joke Shop maps and the 0.9.x engine -baseline. The active priorities are the Quaternius NPC base migration and the 3D -model/map re-evaluation; the 0.10.0 release -candidate follows those tracks. See +baseline. The active work is the `0.9.9`–`0.9.12` patch line (Quaternius NPC +base, roster, venue/asset polish, performance) followed by the `0.10.0` +public-readiness minor. See [`docs/development-status.md`](docs/development-status.md) for the implemented list and [`TODO.md`](TODO.md) for the priority-ordered roadmap. Manual verification uses [`docs/release-qa.md`](docs/release-qa.md). diff --git a/TODO.md b/TODO.md index 41d967e..5388a3d 100644 --- a/TODO.md +++ b/TODO.md @@ -1,156 +1,43 @@ # TODO -Work is grouped by theme. Each item should be small enough to complete and verify on its own; -see `AGENTS.md` for the workflow and `MEMORY.md` for the decisions behind these plans. +Active task list. Work is grouped by milestone and workstream; every item is small enough to +complete and verify on its own. The product plan, gap analysis and release roadmap live in +[`PLAN.md`](PLAN.md); durable decisions and gotchas live in [`MEMORY.md`](MEMORY.md); +[`AGENTS.md`](AGENTS.md) defines the workflow. -**Priority order (2026-11-05, owner):** 1) **Quaternius NPC base migration** — use the CC0 -Quaternius character as the mesh/animation source and bake it to the runtime contract; 2) the 3D -model and local map improvements; 3) ship it together in the **0.10.0 minor**. The 0.9.7/0.9.8 -character patches are published. See `AGENTS.md` §Priority and Versioning and §Local Blender skills. +**Current state (2026-11-05):** v0.9.8 is published. Three venues, the shift loop, the +tutorial/campaign, the access/escalation system and the 12-character procedural library are +shipped. The character plan changed twice and landed on the CC0 Quaternius base; the owner +accepted the 62-joint runtime rig ([ADR-0018](docs/adr/0018-quaternius-stage2-runtime-rig.md)), +but the base does not yet render or animate correctly in Godot. + +**Roadmap (detail in [`PLAN.md`](PLAN.md#release-roadmap)):** + +| Version | Type | Scope | +| --- | --- | --- | +| `0.9.9` | patch | Quaternius pilot base: rig/export fix, pose composition, face/silhouette gate | +| `0.9.10` | patch | 12-role roster on the approved base, gear fit, budget evidence | +| `0.9.11` | patch | Scheduled venue, prop, foliage, lighting and set-dressing polish | +| `0.9.12` | patch | Performance/Web/accessibility verification before the minor | +| `0.10.0` | minor | Public-readiness release: playtests, balance, legal, platform matrix, docs | +| `0.10.1`–`0.10.3` | patch | Onboarding, balance and stability follow-ups | +| `0.11.0` | minor | Live body-camera replay, fourth venue, localization foundation | +| `0.12.0` | minor | Signed/storefront builds, frozen save contract, launch languages | +| `0.13.0` | minor | Content complete and feature freeze for 1.0.0 | +| `0.13.1`–`0.13.2` | patch | Release candidates | +| `1.0.0` | major | Stable release with a documented compatibility promise | + +**Priority now:** the `0.9.9` rig-and-export correction. Do not start the 12-role roster +(`0.9.10`) before the single-variant pilot renders, animates and passes the owner face gate. + +The unversioned tracks (3D review evidence, maintenance, Gaussian splatting) stay at the top of +this file because their work is not release-scoped; each milestone below is versioned and must +follow the release procedure in `AGENTS.md`. The MIT Blender skill pack lives locally at `.agents/skills/blender-skills/` (gitignored). Every 3D workstream below names the skills to load; they are guidance only, and the project contract, `blender_assets.py audit`/`fit`/`inspect` and the capture gates stay authoritative. -## Quaternius NPC base migration (top priority) - -Goal: replace the generator-first NPC base with the CC0 **Quaternius Ultimate Modular -Characters** as the primary mesh and animation source, while keeping one committed -`npc_base` skinned mesh, the five tint slots and a runtime contract that Godot, gear -and tests can consume. The detailed decision is [ADR-0017](docs/adr/0017-quaternius-npc-base.md); -it supersedes the generator-first sourcing decision in ADR-0015. - -**Why:** the research pack already has a coherent low-poly human silhouette, 21 modular -outfits and 24 animations. The current procedural body needs a separate head, hands, neck -and shoe pipeline to look human; using Quaternius as the base removes that bespoke body work. - -**Default path (Stage 1):** retarget and proportion-warp the Quaternius mesh onto the -existing 13-core contract, so `NpcAvatar`, gear attach points and the current animation -composition keep working. The 62-joint Quaternius rig and its 24 clips are an authoring -source, not a new runtime dependency. - -**Stage 2 gate:** if the proportion warp cannot preserve the Quaternius silhouette and -deformation at an acceptable level, stop the rollout and write a new ADR for adopting the -62-joint rig at runtime. Do not ship a hybrid rig or silently change `NpcAvatar`. - -**Exit:** one committed Quaternius-derived source GLB produces all 12 variants inside -24,000 tris / 24,000 glTF vertices, with five slots, gear fit, Idle/Walk deformation, -`audit`/`fit`/`inspect` clean, the 24-NPC budget measured, and an owner-approved 12 × 6 -baseline sheet. - -### 1. Intake and canonical base - -- [x] Keep the three researched CC0 GLBs (`Casual`, `Casual_Hoodie`, `Worker`) plus the - licence/mirror notes in `tmp/npc-research/quaternius/`; record the source URL, - licence, SHA-256 and download date in `docs/npc-model-sourcing.md`. - Verified: the three GLBs are in `tmp/npc-research/quaternius/`, SHA-256 re-hash matches the - recorded table, the mirror HTML/README are retained next to the folder, and the download - date (2026-11-03) is now recorded. -- [x] Inventory the four meshes, 62 joints, 24 clips and material names in each GLB; map - Quaternius materials to the five project slots (`skin`, `cloth`, `pants`, `accessory`, - `hair`). - Recorded in `docs/npc-model-sourcing.md` §Quaternius GLB inventory: 4 meshes per GLB - (Body/Feet/Head/Legs, 10.5k–13.0k verts), 62 joints (8 spine + 8 arm + 2 PT + 30 finger + - 6 leg), 24 shared clips (retarget scope: Idle + Walk), and the material→slot map by mesh - region (Skin→skin; head hair→hair; body→cloth; legs→pants; feet→accessory). -- [x] Choose the initial outfit scope: build the three full GLBs first; only use the 21-part - modular builder if the three looks cannot cover the 12 roles. - Decided: the three full GLBs are the canonical-base + silhouette-gate scope. They cover - ~3 of 12 roles (casual, hood, vest); jacket/coat/dress/responder/guard need the 21-part - modular builder or new clothing at §4. Recorded in `docs/npc-model-sourcing.md`. -- [x] Build a canonical `quaternius_base.glb`: one welded, triangulated, grounded 1.81 m - humanoid with front on Blender −Y, no animation, and a documented bone/part inventory. - Built from `Casual_Hoodie.glb` via `tmp/npc-research/build_quaternius_base.py`: one `npc_base` - mesh (3,199 welded verts / 6,206 tris), 62 joints, skinned, 1.81 m grounded, T-pose, no - clips, `inspect` clean. Inventory in `docs/npc-model-sourcing.md` §Canonical base. - -### 2. Contract bake and animation - -- [x] Author the 62-joint → 13-core joint map, including optional finger/face extras if - they survive within 24,000 vertices; record it in `docs/npc-model-sourcing.md`. - Map recorded: Hips←Hips (Root+Body collapse), Spine←Abdomen/Torso/Chest, Neck←Neck, - Head←Head, Shoulder←UpperArm (collar collapses), Elbow←LowerArm, Hand←Wrist, - Hip←UpperLeg, Knee←LowerLeg. Optional: 30 finger bones + Foot.L/R (toe); dropped: PT.L/R - pole targets. Quaternius hierarchy measured (Foot is a child of Root, not LowerLeg). -- [x] Bake the rest pose and proportion warp to the contract hip, knee, shoulder, elbow, - wrist and head positions. Measure the warp at every joint and record the silhouette - deltas; do not accept a distorted deltoid or shortened arm. - Arm-down bake works (`warp_full.py`: pose-rotate UpperArm −90° + modifier-apply + - `armature_apply`). Warp deltas recorded in `docs/npc-model-sourcing.md`: arm ×1.63, - leg ×0.74, torso ×1.61, hip −0.249, shoulder +0.122. Vision-judged as distorted - (paddle hands, lost forearms, stretched shins). **Gate fails — Stage 2 (62-joint runtime - ADR) indicated; do not rebuild on the warped base.** -- [-] Skin the Quaternius mesh and verify Idle, Walk, seated and arm-down poses. The old - MPFB/arm-retarget warps are not a reference; judge the Quaternius result directly. - (Direction set: ADR-0018 option 2 — 62-joint runtime. `NpcAvatar` maps the Quaternius - names + derives proxy pivots from `get_bone_global_rest` (commits `271f10a`/`0cd12af`). - Two blockers remain: (1) the arm-down GLB's **skinning** renders A-pose in Godot even - though its rest is arm-down — the `armature_apply` + `export_apply=True` bake writes - wrong inverse bind matrices, so fix the Blender export first; (2) `_pose_bone` uses - `rest * Quaternion(axis, angle)`, which only cancels when `rest² = identity` (the old rig's - 180° rest); the Quaternius ~76° rest does not, so the pose formula must be derived from the - actual `set_bone_pose_rotation` semantics for a non-180° rest.) -- [ ] Retarget Idle and Walk from the 24 Quaternius clips to the contract rig; discard - combat, gun and sword clips. Verify looping, foot contact and frame rate in Godot. - (Direction set: no retarget needed — the clips are authored for the 62-joint rig; only - verify looping/foot contact in Godot.) -- [ ] Map the five slots, unwrap per slot, bake 256² AO/albedo/normal/ORM maps and check - texel density before any roster build. - -### 3. Silhouette gate - -- [ ] Render the base at 1.5 m and 1.85 m in front, three-quarter and profile; compare - against the Quaternius source and the current `npc_casual`. Use the vision judge for a - written verdict, but the owner decides. -- [ ] Confirm gear attach points (head, hand, back, chest) and test cap, helmet, backpack, - shoulder bag, lanyard, clipboard and firefighter tank against the new shoulders/hips. -- [ ] Go/no-go: if the warp fails the silhouette gate, stop and write the 62-joint runtime - ADR (Stage 2). Do not start the 12-variant rebuild. - -### 4. Roster and rollout - -- [ ] Map the 12 roles to Quaternius outfits/parts, build them in asset-family batches, - and keep every variant inside the 24,000/24,000 cap. -- [ ] Run `audit`, `fit`, `inspect`, `texels` and `npc_proportions.py report`; record the - 12-variant table and the warp measurements. -- [ ] Re-run the 24-NPC budget smoke and the Web/Compatibility capture; record frame time - before and after the base swap. -- [ ] Capture the 12 × 6 baseline (`capture_npc_baseline.gd` → `npc_baseline.py sheet`) and - get owner approval before replacing the committed character GLBs. -- [ ] Rebuild AO maps, manifest entries, credits and review docs; commit one asset family per - change and never run a no-op full-library rebuild. - -### 5. Retire the old character tracks - -- [x] Remove the MPFB/MakeHuman development scripts, renders and review directories from - `tmp/` (done 2026-11-05). Keep only the Quaternius source pack and its licence notes. -- [x] Keep the committed `makehuman_head.glb` and the procedural `npc_base` only as tested - fallbacks until the Quaternius rollout is complete; do not add new MPFB work. -- [ ] Update `docs/development-status.md`, `CHANGELOG.md` and `CREDITS.md` when the new base - ships. MPFB must never become a CI, build or runtime dependency. - -## Fix the Rig pose harness - -Goal: `src/test/capture_npc_pose.gd` reports a pose but saves rest frames; the root cause is -narrowed to the skinned mesh ignoring its `Rig` parent transform. Fixing it unblocks the -weights/pose column of the 3D review; the evidence now feeds the Quaternius base bake. - -*Skill route: `rigging`; evidence in `docs/3d-model-review.md` §"Pose evidence is blocked".* - -- [x] Root cause found (2026-11-04): the harness never disabled the avatar's `_physics_process`, - so `_advance_fsm` + `_move_toward_target` ran every tick and reset `arrived`/velocity, which - made `theater_pose()` return "idle" and reverted the pose to rest. (The earlier "moving the - `Rig` child does not render" probe was a red herring: it set `rig.position.y` inside `_shoot()` - in the same frame as `root.get_texture().get_image()`, so it never got a rendered frame.) -- [x] Harness rebuilt: `capture_npc_pose.gd` now calls `set_physics_process(false)`/ - `set_process(false)` after staging the avatar; the pose survives because only the direct - `_animate()` ticks drive it. Verified: sit vs idle diff 5.63, walk vs idle diff 2.29, and the - vision judge confirms the seated frame reads as crouched. -- [x] Captured all poses for all 12 variants (idle / walk_contact / walk_pass / sit × full + - shoulder views = 96 frames) and built `sheet_pose.jpg`/`sheet_shoulder.jpg` under `tmp/`. - (No separate "wave" theater pose exists; the escalation raise-hand gesture is not a distinct - capture in this harness.) - ## 3D model and local map re-evaluation Goal: re-judge every shipped 3D asset against the newly available Blender skill guidance, rank @@ -159,14 +46,15 @@ venues against licensed real-world data — OSM footprints and building massing, photoreal facades and the photo-driven geometry pipeline (sections H–M). Evidence comes from three separate sources: licensed real-location photos, generated concept boards, and build captures. This is an unversioned development track: it must not change the `npc_base` contract, the renderer or -the 0.10.0 release candidate. +the public 0.10.0 release. -**Sequencing (2026-11-03, owner):** the asset-review fixes (A–G, notably the character P0/P1 -rebuilds and the face/foliage prototypes) stay **blocked** until the full local map rebuild -(H–M) is done **and** a fresh 3D model review runs against the new maps. The measurements and -scorecard in `docs/3d-model-review.md` stand as the pre-rebuild baseline, not a go-ahead to start -character work now. (Character development has since shipped — see `DONE.md` — and the next -character pass is the Quaternius base above.) +**Sequencing (updated 2026-11-05):** the old block is cleared. The local map rebuild (H–M) is +done, the 96/96 review ran against the new maps, and character work moved to the versioned +`0.9.9`/`0.9.10` milestones. This section is now the **evidence, scorecard and measurement +source**, not an open-ended backlog: the venue/prop/lighting fixes are scheduled into +`0.9.11`, the budget/LOD checks into `0.9.12`, and the character items (C) are superseded by +`0.9.9`/`0.9.10`. Fixes are made from the milestone checklists; the scorecard keeps the +measurements and verdicts. **Map rebuild status (2026-11-03):** H–M are complete — the Joke Shop is now a 6.0 m low hall (dark stucco, white signature fascia, tied-back curtains, hotel tower) and Hollywood/TV Studio @@ -253,7 +141,14 @@ licence-free zone only. per item; record the decision and the reason in the review document. **Deferred until the full map rebuild (H–M) lands and a fresh 3D review runs against the new maps.** -### C. Character re-evaluation (8 variants + fallback) +### C. Character re-evaluation (superseded 2026-11-05) + +The procedural character review is complete and its evidence stays in +`docs/3d-model-review.md`. The next character pass is the Quaternius base in +[`Milestone 0.9.9`](#milestone-099--quaternius-npc-base-swap-patch) and +[`Milestone 0.9.10`](#milestone-0910--npc-roster-rollout-patch); the open items below are kept +as evidence for what the new base must not regress (face read, hands, weights, cloth, texel +density, crowd variety). *Skill route: `character-artist`, `retopology`, `rigging`, `uv-workflow`, `texture-workflow`, `materials`, `hair-groom`, `asset-optimization`, `lookdev`, `qa-review`.* @@ -291,8 +186,8 @@ licence-free zone only. plus stride scaling are the accepted approach; a baked cloth-sim pipeline would only be reconsidered if a later close-up shows visible hem/coat stiffness. - [ ] Fix only the ranked P0/P1s, one asset family per commit; refresh the comparison sheet and - re-run `inspect`, `audit`, `fit` and `npc_proportions.py` after each fix. **Blocked until - the map rebuild + second 3D review (see the track's sequencing note).** + re-run `inspect`, `audit`, `fit` and `npc_proportions.py` after each fix. **Scheduled: the + remaining character items are covered by Milestone 0.9.9/0.9.10; this row is evidence only.** - [x] Crowd-variety reference: five licence-cleared Commons photos fetched to `tmp/research/crowd-variety/` (CC0 ×2, CC BY 2.0, CC BY 3.0, PD) covering umbrella/dense crowds and a pedestrian mall — general build/hair/outer-layer variety context, reference @@ -701,11 +596,11 @@ pass. The current `_build_comedy_store_building()` stays as the fallback.* Unversioned housekeeping that keeps the planning sources trustworthy. Do these when they block a task, not on a schedule. -**Status (2026-11-03):** v0.10.0-rc.1 source; three venues; 277 headless + 161 Python tests; the +**Status (2026-11-05):** v0.9.8 published; three venues; 277 headless + 162 Python tests; the Hollywood and Joke Shop facade-realism passes landed (`limestone_ashlar`, `dark_stucco`, banner night emissive, marquee emissive test); reference boards (`hollywood`, `joke-shop`) with sidecars; three-up boards; `tools/refboard.py` + reference-anchored generation (`--reference`, `anchor`) + -`tools/three_up.py`. Gaussian splatting is deferred to the end of this file. +`tools/three_up.py`. Gaussian splatting stays deferred at the end of this file. ### Memory and status accuracy @@ -720,8 +615,8 @@ three-up boards; `tools/refboard.py` + reference-anchored generation (`--referen contradiction and the old 272/108 counts.) - [x] Fix stale status claims as they are found; add a documentation check or grep note only if the same class of drift returns. (Counts and the sign-in state corrected on 2026-11-03.) -- [x] Keep the Gap Analysis baseline and the README status line in sync when a test count, version - or feature milestone changes (the baseline was bumped to 277/161 on 2026-11-03). +- [x] Keep the `PLAN.md` gap-analysis baseline and the README status line in sync when a test count, + version or feature milestone changes (baseline bumped to 277/162 on 2026-11-05). ### Imagery and provenance upkeep @@ -763,245 +658,6 @@ three-up boards; `tools/refboard.py` + reference-anchored generation (`--referen - [ ] Prune the skill routes in `AGENTS.md` if a skill stops matching the project (for example if a future second-rig path makes `rigging`/`animation` guidance authoritative). -## Gap Analysis and 0.x Roadmap - -**Published baseline:** v0.9.6 (2026-11-03) — three playable venues, tutorial/campaign/checkpoint -resume, access/radio/escalation loop, shift review, the Blender asset library, 277 Godot + 161 -Python tests, a 21/21 screen-design judge and Compatibility/Web/Desktop HQ builds. -**Current source:** 0.10.0-rc.1. Its clean release-candidate build is verified, but it is not -published while the gates below remain open. - -### Open gaps - -| Area | Remaining gap | Milestone | -| --- | --- | --- | -| 3D model and local map re-evaluation | Skill-guided asset scorecard/repairs; OSM/3D data, reference-derived facades, AI-assisted composition and map QA | Unversioned | -| Character development | Complete (moved to `DONE.md`); the Quaternius NPC base migration is the next character pass | 0.10.0 | -| Content and balance | External first-time-player evidence, balance sweeps/tuning and content lock | 0.10.0 | -| Audio, accessibility and localization | Accessibility/localization acceptance, caption coverage and pseudo-locale/layout sign-off | 0.10.0 | -| Performance and platform | Target-hardware matrix, Web/Desktop HQ profiling and frame/memory evidence | 0.10.0 | -| QA and release engineering | Final smoke matrix, clean build/checksum verification and target-matrix launch tests | 0.10.0 | -| Legal, signing and storefront | macOS signing/notarization, AI-provider rights, storefront/rating approval and privacy sign-off | 0.10.0 | -| Documentation and sign-off | Final README/status/TODO/manual evidence and known-limitations sign-off | 0.10.0 | -| Future 0.x | Live replay, more venues, VO/music, image-to-mesh props and seasonal content | Unscheduled | - -The 0.9.3 UI, 0.9.4 animation, 0.9.5 texture, 0.9.6 integration and save-migration work are -complete in `DONE.md`; they are not remaining gaps. The 2026-11-01 documentation audit -(architecture ownership, stale-claim cleanup and obsolete-plan removal) is also closed. - -**Priority (2026-11-05):** finish the `Rig` pose harness, then the Quaternius NPC base -migration, then re-evaluate the 3D models, then ship the **0.10.0** minor release. The 0.10.0 candidate -still accepts only release-blocking fixes until its external-playtest, legal/storefront, signing -and platform gates clear. - -## Milestone 0.10.0 — 3D model and map improvements (minor) - -Goal: ship all 3D model and map improvements together as the **0.10.0 minor** — the Quaternius -NPC base bake (contract armature + five slots), the rebuilt Comedy Store/Hollywood maps, -and the re-evaluated 3D scorecard — plus the external playtest, legal/storefront, signing and -platform gates from the old release candidate. The character-development patch (0.9.7) ships -first; this minor contains the model/map work. - -### Content lock and external playtest - -### Content lock and external playtest - -- [x] Declare a content/feature freeze for 0.10.0; only release-blocking fixes and balance changes - may land after the freeze. (Frozen 2026-11-03 after the 0.9.6 integration - checkpoint; this pass is limited to release reliability, accessibility, - balance evidence and packaging.) -- [x] Produce a release-candidate build with the tutorial, campaign, all three venues, Help, - accessibility settings and checkpoint/resume enabled. (Clean worktree - `a9658ec` built `0.10.0-rc.1`: Linux 161.5 MB, Windows 197.2 MB, macOS - 148.0 MB, Web 97.8 MB and HQ 241.6 MB. The Web/HQ archives include the - credits, privacy, accessibility and known-limitations pages; SHA-256 - manifests were written; the Linux and HQ binaries launched headless and the - Web index/wasm/pck/docs returned HTTP 200. Not published because external - playtest and legal approval remain open.) -- [ ] Run at least five first-time-player sessions covering the tutorial and one full venue shift; - record where players get stuck, misunderstand evidence or choose disproportionate escalation. -- [ ] Triage findings by severity (P0/P1/P2) and fix every P0/P1 onboarding/accessibility issue; - keep the rest as explicit known limitations or post-0.10 items. -- [ ] Re-run the affected tutorial/campaign smokes after each fix and capture a fresh first-hour - walkthrough for the release notes. - -### Balance and fairness pass - -- [x] Define measurable targets for routine compliance, access-decision accuracy, peaceful - resolution, justified emergency calls and false-positive/false-negative rates. - (`docs/release-qa.md#balance-acceptance` defines cohorts, denominators, 36 matrix cells, - seeds, thresholds and matched emergency-first comparisons. Documentation verified; - targets are not measured results.) -- [ ] Run scripted venue sweeps across easy/normal/hard and all four phases; compare outcomes and - tune event weights, reaction tables, compliance and report strictness where targets fail. -- [ ] Review emergency calls against actual danger: no routine behavior should make emergency the - dominant winning move, and genuine threats must remain answerable. Include the - type-derived `_read_npc_truth()` mismatch with observed threats/forced entry; - use independently labelled behavior evidence, not the helper as its own oracle. -- [ ] Verify the reputation grades, debrief explanations and campaign progression still communicate - the de-escalation-first design after tuning. -- [ ] Record the balance evidence and any deliberate exceptions in `docs/development-status.md` - or `MEMORY.md`. - -### Save migration and session reliability - -- [x] Add fixtures for a 0.8-era settings/campaign/history save and a 0.9.0 checkpoint; verify - migration/default-filling and a clean first launch with no files. (Committed - fixtures under `src/test/fixtures/saves/`; 9 migration/failure tests cover - old settings/campaign/history, the 0.9.0 checkpoint, all three venue - checkpoint round-trips, clean install, corrupt JSON and a blocked atomic - replace. Suite is now 272 tests.) -- [x] Test fresh install → tutorial → campaign → pause → quit → resume → review → next venue on - an isolated user-data directory. (Tutorial and campaign smokes shared one - isolated `XDG_DATA_HOME`; tutorial completion/replay/skip then campaign - resume/review-continue/help both passed. Pause/menu behavior is covered by - `smoke_session_shell.gd`.) -- [x] Test corrupt JSON, partial temp files, missing optional fields and a failed atomic rename; - confirm fallback behavior never destroys a valid save. (Corrupt/partial files - fall back to defaults; a blocked temp path reports an error and leaves the - prior valid settings intact. `_load_json` now uses the non-logging JSON - instance parser.) -- [x] Verify checkpoint resume after all three venues, after an incident, with NPCs at the door and - with flashlight/body-camera/door state set. (The migration suite round-trips a - checkpoint for Hollywood, the Joke Shop and the TV Studio with an open - incident, one NPC row, flashlight/body-camera/door flags; the campaign smoke - resumes a live checkpoint through the real `GameManager`.) -- [x] Document save locations, schema versions, reset behavior and rollback/export instructions in - `docs/getting-started.md` and the release notes. (`getting-started.md` now - documents the four files, version-1 checkpoint, atomic write/fallback, - clean install, reset and backup/rollback.) - -### Release engineering and distribution - -- [x] Run `tools/build_releases.sh` from a clean checkout and verify Linux/Windows/macOS/Web/HQ - artifact names, sizes and checksums. (Clean worktree `a9658ec` built the - five artifacts listed above; `PUBLISH_DRY_RUN=1` produced and printed - `build/SHA256SUMS-0.10.0-rc.1.txt` without touching the API.) -- [ ] Smoke-test fresh Linux portable/AppImage, Windows portable/installer, macOS unzip/launch, - Web static hosting and Desktop HQ Vulkan fallback on the target matrix. - (Linux portable and Desktop HQ launched headless; Web files served over a - local static server with HTTP 200. AppImage/installer were not built locally - and Windows/macOS launch testing still needs the target matrix.) -- [x] Add a disk-space preflight and retention policy to the release/publish scripts so a full - Gitea host cannot leave a partially uploaded release. (`publish_release.sh` - checks artifact size/free space, writes SHA-256 checksums, supports - `PUBLISH_DRY_RUN`, rolls back uploaded assets/new releases on failure, and - offers opt-in `RETAIN_RELEASES` pruning; dry-run verified.) -- [x] Verify release metadata, tag/version consistency, asset counts and download links; retain - at least the latest 0.8/0.9 releases and document older-asset pruning. - (Source/version and tag are both 0.9.6; all seven published releases carry - 5–7 assets, including the retained v0.8.0/v0.8.1/v0.9.0/v0.9.1 line. - `publish_release.sh` documents opt-in `RETAIN_RELEASES` pruning and - `RELEASING.md` describes the seven-release policy.) -- [x] Decide and document whether macOS signing/notarization is required for 0.10.0 or explicitly - remains a future release blocker; record the quarantine instructions either way. - (0.10.0 ships unsigned with quarantine instructions; signing/notarization - remains an explicit public-release blocker in `RELEASING.md` and - `known-limitations.md`.) - -### Legal, credits and platform policy - -- [x] Audit AI-assisted asset provenance and licenses; record source/model usage and any - redistribution constraints for textures, characters, props and UI art. - (`CREDITS.md` records the Blender/OpenRouter toolchain, default model slugs, - missing per-file generation metadata and the commercial-rights review as an - explicit release blocker.) -- [x] Audit audio/SFX/music licensing (or confirm everything is procedural) and add a credits file. - (All runtime audio is procedural; no external music/SFX files are bundled. - `CREDITS.md` records this.) -- [x] Review body-camera/privacy language, mental-health-crisis representation, age/content rating - and storefront requirements; fix any release-blocking copy or content. - (`PRIVACY.md` clarifies the simulated body camera/local-only data; the - accessibility and known-limitations pages record the remaining - mental-health/rating/storefront review as a release blocker rather than - claiming approval.) -- [x] Add the player-facing credits, known limitations, accessibility statement and privacy note to - the release package/README. (`README.md` links `CREDITS.md`, `PRIVACY.md`, - `docs/accessibility.md` and `docs/known-limitations.md`; the Web and Desktop - HQ package builders copy those documents into the shipped archives.) -- [ ] Mark external legal/storefront approval as complete or explicitly block the 0.10.0 release on it. - -### Documentation and visual sign-off - -- [ ] Update `README.md`, `PLAN.md`, `docs/architecture.md`, ADRs, `docs/development-status.md`, - `docs/getting-started.md`, `docs/release-qa.md#manual-smoke-checklist`, `CHANGELOG.md` and this roadmap. -- [ ] Regenerate the full screenshot gallery and realism baselines from the release-candidate - build (not the dev tree) after content lock; run `check_screenshots.sh` and the pinned vision - judge, recording model/spend/verdicts, and refresh the README and venue-doc images. -- [ ] Include the reference/concept boards and the updated asset sheets in the release docs, and - verify every README and docs-page image resolves from the tagged build. -- [ ] Run the manual smoke checklist on every target and attach/link the release-candidate evidence. -- [ ] Verify the tutorial/campaign/help text at maximum font scale and with the longest strings. -- [x] Remove or archive stale plans/notes and confirm no contradictory version/status claims remain. -- [x] Document the character development toolchain in `docs/architecture.md`: base vs library - sources, tool/artifact/gate table, runtime attach/animation contracts and rebuild discipline. - (Added §5 "Character development tooling" plus risk and ownership-map updates; - documentation check passed.) - -### Release-candidate QA and exit - -- [ ] Run the complete headless suite, Python tooling, tutorial/campaign/session/scenario smokes, - 24-NPC budget smoke and release build from a clean checkout. -- [ ] Run the manual QA matrix: fresh install, upgrade, offline launch, gamepad, accessibility - settings, pause/resume, all venues and Desktop HQ fallback. -- [ ] Confirm no P0/P1 defects remain; P2 items must be documented as known limitations or - post-0.10 work. -- [ ] Create the `v0.10.0` version bump, changelog entry and tag; build/publish the release and - verify all assets and download links. -- [ ] Exit: the release candidate is content-locked, externally played, legally reviewed, - documented, reproducibly built, and approved as the 0.10.0 release candidate. - -## Milestone 0.9.7 — Character development (patch) - -Goal: release the finished procedural character development — the realistic face on all eight -variants, the four crowd-variety characters and the per-role pools — as a **patch** on top of -0.9.6. This keeps the 3D model and map improvements out of the patch; they land together in the -0.10.0 minor. - -- [x] Rig pose harness fixed and the weights/pose evidence captured (see the top track). -- [x] Character work done: 12-character library, realistic face, crowd variants, per-role pools, - 24-NPC budget 6.94 ms (152,464 tris / 168 meshes). -- [x] QA + local build for 0.9.7: Godot 277/277, Python 161/161, audit 49 OK, fit/proportions - 12/12, release smoke matrix green, gallery 21/0, clean worktree build (Linux 172 MB, - Windows 206 MB, macOS 159 MB, Web 111 MB, HQ 266 MB), checksums verified, Linux binary - launches headless. Tagged `v0.9.7` (CI build/publish follows). - -**Exit:** met — 0.9.7 ships the 12-character library (face realism + crowd variety) with the pose -harness fixed; the runtime contract is unchanged. The Quaternius NPC base and the map rebuild are -not in this patch (they target 0.10.0). - -## Roadmap dependencies and risks - -- Content volume is the largest schedule risk; tutorial and campaign work must not outrun the - event/dialogue matrix. -- The vision judge is a dev-time aid with an external key/budget; CI must never make it a hard gate. -- Godot version changes can alter lighting/imports; do not combine an engine baseline move with a - content/feature milestone. -- Signed macOS builds and legal/AI provenance are release blockers, not polish. -- Photo-derived map assets add a second provenance risk: downloaded or user-supplied photos can - carry unclear licences, identifiable people, plates and property restrictions. No photo or - splat-derived asset ships without a completed sidecar, consent/licence review and redaction. -- Gaussian-splat training is GPU/disk-heavy and the toolchain churns quickly; keep it offline, - version-pinned and outside CI, and never make a runtime splat renderer a release dependency. -- Keep the de-escalation-first rules and rare-emergency design unchanged while adding progression, - difficulty and feedback. - -- The Blender skill pack is local, unversioned guidance; it can drift from the project contract or - assume Blender MCP. Re-verify every adopted technique with `inspect`/`audit`/`fit` and never - make a skill, asset pack or tool version a build or CI dependency. -- The 3D re-evaluation can expand without bound (retopo every head, rig every finger). Cap it with - the scorecard ranking: P0/P1 only, one asset family per commit, and an explicit accept for - everything else. - -## Future / deferred (not scheduled) - -- [ ] Live 3D body-camera replay; the timeline is text-only today. -- [ ] Additional venues or seasonal events authored from the `content/venues/` resources. -- [ ] Real voice/dialogue audio; ambience, cues and radio crackle are procedural. -- [ ] Swap the primitive prop builder for an image-to-mesh model API behind the same - `assets/models/generated/.glb` contract. -- [ ] Rare easter eggs/cameos (e.g. Bob Dobbs) only after core content and QA are stable. - ## Gaussian splatting evaluation (deferred) Postponed for further development on 2026-11-03. The local-map track ships the facade kit and @@ -1098,3 +754,410 @@ reference-image licence and privacy gates above rather than replacing them. - [ ] Exit: one licensed photo capture measurably improves a venue through a documented path and passes visual, performance and provenance review; or the approach is rejected with reproducible findings and removed from the release path. + +## Milestone 0.9.9 — Quaternius NPC base swap (patch) + +Goal: make one Quaternius-derived NPC render and animate correctly in Godot and ship it as the +pilot base, with the procedural library still selectable as the fallback. This is the first +versioned character milestone; it contains the rig correction that has been blocking the +ADR-0018 rollout. + +**Why this is a patch:** it changes character presentation and animation quality but adds no new +player-facing system. The 0.10.0 minor is reserved for the release gates (see below), so a +blocked rig can no longer block the whole release. + +### Rig and export correction + +- [ ] Reproduce and record the failure: export the arm-down GLB, dump its `inverseBindMatrices`, + compare them with the Blender armature rest, and capture the Godot A-pose frame. +- [ ] Fix the arm-down bake so the exported skin matches the rest. Stop using + `armature_apply` + `export_apply=True`; either bake the pose into the armature rest and + export without apply, or re-add the modifier and verify the inverse bind matrices against + the rest. Do not ship a hybrid or hand-patched GLB. +- [ ] Re-derive the pose composition for a non-180° rest. Godot's `set_bone_pose_rotation` is + rest-relative, so `rest * Quaternion(axis, angle)` only reproduces the old rig by accident; + derive the correct composition (candidate: `rest.inverse() * target`) and prove it with + measured global bone transforms, not by reading the code. +- [ ] Add regression tests: a bone with a ~76° rest reaches a known global orientation; the + Quaternius joint map resolves; the 13-core fallback poses exactly as it does today. +- [ ] Verify Idle and Walk on the 62-joint rig: loop seam, foot contact, root motion and frame + rate. Record which of the 24 clips are in scope and which stay unused. +- [ ] Decide and record how poses the clips do not cover (seated, raise-hand, head turn) are + driven at runtime. +- [ ] Keep the fallback tested: `npc_base`, the MakeHuman head and `_build_body()` remain + selectable; no MPFB work is reopened and no Stage-1 proportion warp returns. + +### Silhouette and face gate (owner) + +- [ ] Re-run the silhouette gate at gameplay distance and in portrait against the current + `npc_casual`, front / three-quarter / profile. This is a new gate: ADR-0018 removed the + proportion warp, so source proportions are now accepted by definition. +- [ ] Face-fidelity comparison. The Quaternius head is low-poly (≈6.2k tris for the whole body); + the 0.9.7 library has a sculpted realistic face. Capture both heads and let the owner pick: + (a) full swap, (b) Quaternius for crowd roles with the procedural library for named roles, + or (c) add head subdivision/hair cards to the Quaternius head. +- [ ] Apply the chosen face path within 24,000 tris / 24,000 glTF vertices and re-run the gate. +- [ ] Record the decision and its consequence in `MEMORY.md`, `docs/npc-model-sourcing.md` and + (if it changes the contract) a new ADR. Do not silently lower character fidelity. + +### Pilot rollout + +- [ ] Map the five tint slots onto the Quaternius materials; unwrap per slot; bake 256² + AO/albedo/normal/ORM and check texel density. +- [ ] Re-fit gear attach points against the Quaternius skeleton and test cap, helmet, backpack, + shoulder bag, lanyard, clipboard and firefighter tank. +- [ ] Wire the approved base into one role (or the crowd roles if option b is chosen) with the + procedural model as an instant fallback; no runtime download or optional dependency. +- [ ] Run `blender_assets.py inspect`/`audit`/`fit`, `npc_proportions.py`, the 24-NPC budget smoke + and the capture gate; record the measurements before/after. +- [ ] Release `0.9.9`: update the version source in `project.godot` (`config/version`), write the + `CHANGELOG.md` entry, run `tools/build_releases.sh`, verify checksums, commit, tag and push. + +**Exit:** one committed Quaternius GLB renders arm-down with correct skinning, plays Idle and +Walk on the 62-joint rig, poses correctly under the new composition, passes the owner face and +silhouette gate, fits the 18 gear pieces, stays inside budget, and ships as `0.9.9` with the +procedural library still available as a fallback. + +## Milestone 0.9.10 — NPC roster rollout (patch) + +Goal: extend the approved base to the full 12-role roster in asset-family batches, without +regressing gear fit, budget or readability. + +### Roster build + +- [ ] Map the 12 roles to Quaternius outfits/parts; mark the roles that need the 21-part modular + builder instead of the three full GLBs, and the roles that keep a procedural look under the + 0.9.9 option-b decision. +- [ ] Build one asset family per commit, AO-baked and re-imported; never run a no-op full-library + rebuild. Use the concept + vision-judge loop for head/outfit decisions and record model, + prompt and spend. +- [ ] Keep every variant inside 24,000 tris / 24,000 glTF vertices and the five tint slots; no + new bone beyond the accepted 62-joint set without an ADR. +- [ ] Refresh `CHARACTERS`, the manifest roles/tint data, `CREDITS.md` and the review doc rows as + each family lands. + +### Gates and rollout + +- [ ] Re-bake AO per rebuilt GLB and refresh the stale `.godot` import cache (scratch-copy + import) before judging any face or body change. +- [ ] Run `inspect`/`audit`/`fit`/`texels` and `npc_proportions.py report`; record the + 12-variant measurement table. +- [ ] Capture the 12 × 6 baseline and get owner approval before replacing the committed GLBs. +- [ ] Re-run the 24-NPC budget smoke and the Web/Compatibility capture; record frame time, + mesh/triangle counts and Web load before/after. +- [ ] Retire the procedural variants that are no longer used, keeping one tested fallback; update + `docs/development-status.md`, `docs/3d-model-review.md`, `docs/blender-previews` sheets and + the README character row. +- [ ] Release `0.9.10` with the full procedure (version, changelog, local build, checksums, tag). + +**Exit:** all 12 roles use the approved base or an explicitly kept fallback, every variant passes +the contract and gear gates, the 24-NPC and Web budgets are measured and documented, and the +baseline sheet is owner-approved. + +## Milestone 0.9.11 — Venue, prop and lighting polish (patch) + +Goal: close the scheduled subset of the unversioned 3D review backlog. Only ranked P1/P2 items +whose fix is visible at gameplay distance are in scope; the review doc stays the evidence and +scorecard source, this milestone is the actionable list. + +### Props, gear and foliage + +- [ ] Rebuild the ranked prop candidates from §D: the foliage-language P1 + (`planter_box`/`round_planter` foliage, `street_tree`/`palm_tree`), plus the + `newspaper_box` slot and `bollard` collar if the budget allows. +- [ ] Replace the flat `_shrub()`/`_tree()` clumps with carded clusters and keep the 60k + library triangle budget; measure before/after. +- [ ] Review the 18 gear pieces for silhouette and strap/buckle readability and rebuild only what + fails; re-run `fit` after every change. +- [ ] Verify prop colliders and navigation obstacles against the final silhouettes. + +### Venue, lighting and set dressing + +- [ ] Joke Shop / Hollywood shape language: fix the ranked remaining items (west rounded corner, + canopy pitch, facade reveal depth) only where a capture shows a readable gain. +- [ ] `lighting`/`lookdev` pass: flashlight cone/energy for the `06-night-flashlight` stage, + marquee/event-banner emissive read under the Compatibility renderer, street-lamp pools. +- [ ] Set dressing: fix the Joke Shop queue story (podium/stanchion line at the door), rope + barrier thickness, the west palm overlap and the empty sidewalk light pool; apply the same + review to Hollywood and the TV Studio. +- [ ] Build one real-photo comparison for street furniture and record the accepted mismatches. + +### Evidence and release + +- [ ] Refresh `sheet_props.jpg`, `sheet_npc_gear.jpg`, the three-up boards, the affected venue + captures and the README asset rows. +- [ ] Re-run `tools/check_screenshots.sh` and `python3 tools/check_docs.py`; record both results. +- [ ] Release `0.9.11` with the full procedure. + +**Exit:** every scheduled P1/P2 item is fixed or explicitly accepted with a measurement, the +capture gallery and asset sheets are current, and no unreviewed asset remains in the shipped +catalogue. + +## Milestone 0.9.12 — Performance, Web and accessibility (patch) + +Goal: prove the new character and venue content still meets the frame, memory, load and +accessibility targets on every target before the minor release. + +### Performance and platform + +- [ ] Profile the 24-NPC budget scene on Compatibility/Web and Desktop HQ; record frame time, + draw calls, texture memory and pck size against the pre-character baselines. +- [ ] Verify LOD/impostor thresholds, the 60k library and 150k/700 venue budgets, and the Web + load time after the character and texture changes. +- [ ] Confirm the Compatibility/Web build still avoids compute shaders and Vulkan-only features; + spot-check the HQ fallback message. +- [ ] Re-run the save/session regression suite on an isolated user-data directory after the + content changes. + +### Accessibility and localization readiness + +- [ ] Verify font scaling at maximum, the longest strings, caption coverage, reduced motion, + colour-independent escalation cues and the hold-to-confirm emergency path. +- [ ] Run the string catalogue through a pseudo-locale/length check; move remaining hardcoded UI + strings into `content/strings.en.json`. +- [ ] Fix only the issues the checks expose; new accessibility features are 0.11.0 scope. + +### Release + +- [ ] Regenerate the full capture gallery and the screen-design judge from the current build; + record model, spend and verdict. +- [ ] Release `0.9.12` with the full procedure. + +**Exit:** the character and venue changes do not regress frame time, memory, Web load, +save/session reliability or accessibility behaviour, and both automated gates are green. + +## Milestone 0.10.0 — Public-readiness release (minor) + +Goal: ship the new characters, the polished venues and the public-readiness gates as the +**0.10.0 minor**, after the patch milestones above have landed. Content is frozen at 0.9.12; +only release-blocking fixes and balance changes may land here. + +### External playtest and onboarding + +- [ ] Run at least five first-time-player sessions covering the tutorial and one full venue + shift; record where players get stuck, misread evidence or over-escalate. +- [ ] Triage by severity and fix every P0/P1 onboarding, evidence or accessibility issue; record + the rest as known limitations or post-0.10 work. +- [ ] Re-run the tutorial/campaign smokes after each fix and capture a first-hour walkthrough. + +### Balance and fairness + +- [ ] Run the scripted venue sweeps across easy/normal/hard and all four phases using the + `docs/release-qa.md#balance-acceptance` targets; tune event weights, reaction tables, + compliance and report strictness where targets fail. +- [ ] Review emergency calls against independent behaviour labels, not `_read_npc_truth()` as its + own oracle; no routine behaviour may make emergency the dominant winning move. +- [ ] Verify reputation grades, debrief text and campaign progression still teach + de-escalation-first after tuning; record the evidence and deliberate exceptions. + +### Legal, signing and storefront + +- [ ] Resolve the macOS signing/notarization decision and record the quarantine instructions. +- [ ] Clear or explicitly block on AI-provider commercial rights, storefront/rating approval and + the privacy/mental-health representation review. +- [ ] Confirm every shipped image, texture, character and audio asset has provenance and credits. + +### Platform and release engineering + +- [ ] Smoke-test the target matrix: Linux portable/AppImage, Windows portable/installer, macOS + unzip/launch, Web static hosting and the Desktop HQ Vulkan fallback. +- [ ] Run `tools/build_releases.sh` from a clean checkout, verify artifact names, sizes, checksums + and download links, and do a `PUBLISH_DRY_RUN`. +- [ ] Run the complete headless suite, Python tooling tests, tutorial/campaign/session/scenario + smokes and the 24-NPC budget smoke. +- [ ] Confirm no P0/P1 defects remain; document P2 items as known limitations. + +### Documentation and visual sign-off + +- [ ] Update `README.md`, `PLAN.md`, `docs/architecture.md`, the ADRs, `docs/development-status.md`, + `docs/getting-started.md`, `docs/release-qa.md`, `CHANGELOG.md` and this roadmap. +- [ ] Regenerate the gallery and realism baselines from the release-candidate build, not the dev + tree; verify every README/docs image resolves from the tagged build. +- [ ] Run the manual smoke checklist on every target and link the evidence. +- [ ] Release `0.10.0`: version, changelog, clean build, checksums, tag, push and post-release + record. + +**Exit:** 0.10.0 is content-locked, externally played, legally reviewed, documented, +reproducibly built and approved for public download. + +## Milestone 0.10.1 — Onboarding and accessibility fixes (patch) + +- [ ] Fix the onboarding, tutorial and evidence-reading issues deferred from the 0.10.0 playtests + that are cheap and non-structural. +- [ ] Fix accessibility issues found at maximum font scale, in captions or in the colour-blind + cue set. +- [ ] Re-run the manual smoke checklist on the affected paths and release `0.10.1`. + +**Exit:** first-hour comprehension and accessibility defects from the 0.10.0 evidence are closed. + +## Milestone 0.10.2 — Balance and fairness follow-up (patch) + +- [ ] Re-run the venue sweeps against the 0.10.0 targets and tune the remaining failing cells. +- [ ] Review shift-review explanations, reputation grades and campaign difficulty progression. +- [ ] Record the balance evidence and release `0.10.2`. + +**Exit:** every balance-acceptance cell is inside target or explicitly accepted with a reason. + +## Milestone 0.10.3 — Stability and quality-of-life (patch) + +- [ ] Fix save/checkpoint edge cases, UI focus traps, gamepad remapping and pause/resume defects + reported after 0.10.0. +- [ ] Add the small quality-of-life items that need no new system (default focus, key hints, + settings persistence). +- [ ] Release `0.10.3` with the full procedure. + +**Exit:** no known P1 stability defect remains before the 0.11.0 feature work starts. + +## Milestone 0.11.0 — Systems and content depth (minor) + +Goal: add the first post-1.0-track feature set on top of a stable 0.10.x line: a live incident +replay, a fourth venue and the localization foundation. + +### Live body-camera replay + +- [ ] Replace the text-only incident timeline with a replay of recorded positions, actions and + timestamps; define the recording format, memory cap and deterministic playback. +- [ ] Keep the replay review-only (no new escalation mechanics) and verify it on Compatibility/Web. +- [ ] Add a skip path and a captioned summary so replay is never a hard gate on the shift review. + +### Fourth venue + +- [ ] Evaluate and select the fourth real-site venue (candidate: the TCL Chinese Theatre + forecourt at 6925 Hollywood Blvd) in an ADR covering layout, access policy, gameplay + distinctness and asset budget. +- [ ] Build the venue under `content/venues/` with licensed reference, sidecar provenance and the + three-up board; enter it from venue selection and the campaign. +- [ ] Add venue-specific events, access artifacts and escalation cases; extend the balance matrix + to the new cells. + +### Localization foundation + +- [ ] Extract every remaining hardcoded string into the JSON catalogue and make the pseudo-locale + length check a CI gate. +- [ ] Add one full secondary language (text, layout, font coverage) with the translation workflow + documented; no machine-translated release without review. +- [ ] Verify layout at maximum font scale in both languages. + +### Release + +- [ ] Re-run the capture gallery, screen-design judge, budget and platform smokes for the new + content; release `0.11.0` with the full procedure. + +**Exit:** the replay, the fourth venue and one secondary language ship without regressing the +0.10.x performance, accessibility or balance baselines. + +## Milestone 0.11.1 — Replay and venue fixes (patch) + +- [ ] Fix the replay, new-venue and localization defects found in wider play. +- [ ] Re-run the new venue's balance cells and the replay capture gate; release `0.11.1`. + +**Exit:** no P1 defect remains in the 0.11.0 feature set. + +## Milestone 0.11.2 — Content and balance polish (patch) + +- [ ] Tune the new venue events and the campaign pacing; fix the remaining content readability + issues. +- [ ] Refresh the affected captures, boards and asset rows; release `0.11.2`. + +**Exit:** the 0.11.x line is stable enough to freeze its contracts. + +## Milestone 0.12.0 — Platform and distribution (minor) + +Goal: make the game distributable on the launch platforms with signed builds, a frozen save +contract and complete localization. + +### Signing and storefronts + +- [ ] Sign and notarize the macOS build; record the exact commands and certificate handling. +- [ ] Produce the storefront packages and metadata (rating, privacy, credits, screenshots) for the + chosen stores; complete the AI-provenance and commercial-rights review. +- [ ] Add the storefront-facing extras that are in scope (achievements, cloud-save decision, + controller/Steam Deck verification) behind explicit feature flags. + +### Contracts and hardware + +- [ ] Freeze the save/checkpoint format as version 2 with export/import and forward-migration + tests; document the compatibility promise. +- [ ] Verify the target-hardware matrix (minimum GPU, Steam Deck, Web browsers, integrated + graphics) and publish the measured results. +- [ ] Finish the launch languages and the accessibility statement for the shipped feature set. + +### Release + +- [ ] Release `0.12.0` with the full procedure and the storefront artifacts. + +**Exit:** signed, storefront-ready builds exist for every launch platform with a frozen save +contract, complete localization and measured hardware support. + +## Milestone 0.12.1 — Distribution fixes (patch) + +- [ ] Fix signing, installer, storefront-metadata and save-migration defects found in the + storefront dry runs; release `0.12.1`. + +**Exit:** every storefront build installs, launches and migrates saves cleanly. + +## Milestone 0.13.0 — Content complete (minor) + +Goal: finish the planned content and lock it for the 1.0.0 release candidate. + +### Content and presentation + +- [ ] Finalise all planned venues, events, dialogue and access artifacts; close the content + backlog with an explicit accept list. +- [ ] Complete recorded audio (VO and music) if the 0.11.0 audio decision funded it; otherwise + record the accepted procedural-only direction. +- [ ] Finalise the tutorial and first-hour flow against the playtest evidence. + +### Release candidate preparation + +- [ ] Run a full accessibility audit against the shipped features and fix the remaining issues. +- [ ] Run the balance acceptance protocol one final time and freeze the tuning. +- [ ] Declare content and feature freeze; only release-blocking fixes may land after this point. +- [ ] Release `0.13.0` as the content-complete milestone. + +**Exit:** all planned content is implemented and frozen, and no known P0/P1 feature gap remains. + +## Milestone 0.13.1 — Release candidate 1 (patch) + +- [ ] Build release candidates on every platform from a clean worktree; run the complete smoke + matrix, save migration, performance and accessibility checks. +- [ ] Fix release-blocking defects only; release `0.13.1`. + +**Exit:** a release candidate exists that passes every gate except final legal/storefront +approval. + +## Milestone 0.13.2 — Release candidate 2 (patch) + +- [ ] Verify the 0.13.1 fixes on the target matrix and re-run the full gallery and judge. +- [ ] Freeze the release notes, credits, privacy and known-limitations documents; release + `0.13.2` as the final candidate. + +**Exit:** the candidate is build-reproducible, documented and awaiting only the final 1.0.0 +release decision. + +## Milestone 1.0.0 — Release (major) + +Goal: publish the first stable release with a documented compatibility promise. + +- [ ] Confirm legal, privacy, rating and storefront approval is complete in writing. +- [ ] Confirm the hardware matrix, accessibility audit and localization sign-off are complete. +- [ ] Confirm no P0/P1 defects remain and every P2 is a documented known limitation. +- [ ] Update `README.md`, `PLAN.md`, `docs/development-status.md`, `CHANGELOG.md`, `CREDITS.md`, + `PRIVACY.md` and the release notes for 1.0.0. +- [ ] Run the full release procedure: version 1.0.0, changelog, clean build, checksum + verification, tag, push and publish. +- [ ] Record the post-release state in `MEMORY.md` and open the 1.0.x maintenance list. + +**Exit:** 1.0.0 is published on every launch platform with complete documentation, verified +checksums and no open release blocker. + +## Future / deferred (not scheduled) + +- [ ] Seasonal events or a fifth venue after the 0.11.0 fourth venue proves the venue pipeline. +- [ ] Real voice/dialogue audio if the 0.13.0 audio decision does not fund it; ambience, cues and + radio crackle stay procedural until then. +- [ ] Swap the primitive prop builder for an image-to-mesh model API behind the same + `assets/models/generated/.glb` contract. +- [ ] Rare easter eggs/cameos (e.g. Bob Dobbs) only after core content and QA are stable. +- [ ] A second Chinese Theatre/forecourt style venue if the fourth venue is not enough. + diff --git a/docs/development-status.md b/docs/development-status.md index 776a7ff..fb7fcce 100644 --- a/docs/development-status.md +++ b/docs/development-status.md @@ -34,9 +34,10 @@ and the active order/gaps in [`TODO.md`](../TODO.md). ## Known gaps - External first-time-player sessions and balance sweeps are not completed. -- The Quaternius NPC base migration is planned, not shipped. The current 12-character - procedural library and the MakeHuman head remain fallbacks until the Quaternius - 12-variant baseline passes review. +- The Quaternius NPC base migration is planned, not shipped: the arm-down skin export and the + rest-relative pose composition are the open blockers (`0.9.9`), and the roster rollout is + `0.9.10`. The current 12-character procedural library and the MakeHuman head remain the + tested fallbacks until the face/silhouette gate is approved. - Accessibility/localization acceptance, target-hardware profiling, macOS signing/notarization and AI/storefront legal approval remain open. - Live 3D replay, recorded VO/music, more venues and seasonal content are future