# 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.

## Gap Analysis and v1.0.0 Roadmap

Baseline: **v0.9.1** (2026-11-02). Three playable venues, tutorial/campaign/checkpoint resume,
difficulty/help, audio/accessibility settings, a 24-NPC budget baseline, a complete
escalation/access/radio loop, shift review, the Blender asset library, 250 headless + 97 Python
tests, a clean screen-design judge and an optional Forward+ Desktop HQ build. This is a strong
release-candidate foundation, not yet a 1.0 product.

### Documentation audit (completed 2026-11-01)

- [x] Make `docs/architecture.md` the single architecture source: asset/content pipeline
      contracts, runtime venue-switch/fallback flows, deployment/version constraints, quality
      requirements, risk register and documentation ownership map.
- [x] Keep command-heavy operational pages separate but subordinate: `docs/asset-tooling.md`,
      `docs/blender-assets.md`, `docs/getting-started.md`, `docs/RELEASING.md` and
      `docs/smoke-checklist.md` link to architecture rather than acting as parallel sources.
- [x] Remove the obsolete `docs/plan-graphics-v0.6.md` and its links; completed graphics work is
      represented by ADR-0013, the asset pipeline section and the changelog.
- [x] Resolve stale claims: README release version/download row, development status
      "Forward+ not implemented", and Blender props "not AO-baked".
- [x] Record the documentation ownership rule in `docs/architecture.md` §12: design intent
      (`PLAN.md`), mechanics (`gameplay.md`), system architecture/contracts (`architecture.md`),
      decisions (ADRs), status (`development-status.md`), roadmap (`TODO.md`), operations
      (tooling/release docs).

### Gap register (remaining to 1.0)

| Area | Current baseline | Remaining gap | Risk | Milestone |
| --- | --- | --- | --- | --- |
| Content and balance | 3 venues with validated 12+ event matrices, recovery events and contextual dialogue | External playtest evidence, balance/fairness pass, event-weight tuning and final content lock | Repetition or unfair outcomes survive into 1.0 | 0.10.0 |
| Dialog/UI | Complete screens and panel art, but copy/button behavior has not had a dedicated audit | Terminology, button states, long-string layout and full screen coverage need a focused pass | Inconsistent UI undermines first-hour clarity | 0.9.2 |
| Animation/presentation | Procedural pose layers, portrait captures, reduced hem clipping | Thorough NPC silhouette/face/gear/pose/LOD optimization before visual QA | Close-up jank reduces perceived quality | 0.9.3 |
| Audio/accessibility | Procedural ambience/SFX, volume controls, captions/reduce-motion settings, searchable Help | Full accessibility/localization acceptance review, audio caption coverage and P0/P1 fixes | Public 1.0 cannot claim accessible play | 0.9.2 / 0.10.0 |
| Localization | English JSON table, validation and input-generated Help | Pseudo-locale/layout audit and translator workflow sign-off | Text expansion/clipping at release | 0.9.2 / 0.10.0 |
| Performance/platform | 24-NPC headless budget (6.9 ms), Compatibility/Web/HQ paths | Target hardware matrix, Web/HQ manual profiling, frame-time/memory evidence | Platform-specific drops or startup failures | 0.9.5 / 0.10.0 |
| Save lifecycle | Settings/campaign/history/checkpoint files, atomic writes | Migration fixtures from 0.8/0.9, fresh-install/upgrade verification, rollback instructions | Player progress loss on upgrade | 0.10.0 |
| QA/CI | Headless suite, smokes, screenshot compare, optional judge | Full visual judge gate, release-candidate smoke matrix, final gallery and release dry run | Regressions escape the release gate | 0.9.5 / 0.10.0 |
| Release/legal | Unsigned desktop/macOS builds, Web/HQ packages | Signing/notarization decision, checksums, AI-asset provenance, credits, privacy/body-camera and rating review | Public release blocked by trust/policy | 0.10.0 |
| Documentation | Architecture/ADR/status/roadmap ownership established | Final README/changelog/status/TODO/smoke-checklist sign-off and known-limitations page | Docs drift at launch | 0.9.5 / 0.10.0 |
| Post-launch | Stable 0.9 feature set | Live replay, more venues, VO/music, image-to-mesh props and seasonal content | Scope creep before launch | Post-1.0 |

## Patch 0.9.2 — Dialog, button and UI polish

Goal: make every player-facing screen read consistently and pass the Python
screen-design judge before any model/texture changes. No gameplay rules change.

### Screen and terminology inventory

- [ ] Inventory every screen/panel: start menu, venue menu, tutorial, HUD, pause,
      settings, Help, inspection, wand, radio/emergency, wheel, shift review,
      timeline and campaign/continue screens.
- [ ] Record the canonical terms for admit/deny, allow/refuse, warning/blocking,
      assistance/emergency, body camera, shift/review and campaign; remove synonyms
      that mean the same action.
- [ ] Audit all button labels for verb-first wording, capitalization, ordering,
      destructive-action confirmation and consistent confirm/cancel placement.
- [ ] List every hardcoded player-facing string and route it through
      `content/strings.en.json`; add placeholder validation for new keys.
- [ ] Review NPC/door-staff/radio/tutorial/help/review/campaign dialogue for
      repetition, ambiguity, tone and localization length.

### Button and panel behavior

- [ ] Audit normal/hover/pressed/focus/disabled states on every button, including
      tutorial skip, venue continue, settings apply/cancel/reset, judge/review,
      radio send/emergency hold and Help close.
- [ ] Verify keyboard-only and gamepad-only navigation: focus order, wrapping,
      default focus, confirm/cancel behavior and no focus traps.
- [ ] Verify every modal closes with Esc/right-click where documented, recaptures
      the mouse, and does not leave the guard frozen or the menu visible.
- [ ] Test buttons at minimum/maximum HUD font scale and with 1.5–2× longer
      strings; fix clipping, overflow and overlapping layouts.
- [ ] Test destructive/irreversible actions (campaign reset, tutorial replay,
      emergency send) require the intended confirmation/hold and cannot double-fire.
- [ ] Verify radio normal-send vs emergency hold, inspection/wand allow/deny,
      review continue/retry/menu and Help search/filter behavior end to end.

### Visual and judge verification

- [ ] Update the affected UI art/reference mapping where copy or button order
      changes; keep the no-overwrite image convention.
- [ ] Capture a deterministic screenshot for every dialog/button state that has a
      design reference; add missing capture stages or an explicit coverage gap.
- [ ] Run `tools/check_screenshots.sh` and `python3 tools/screen_designs.py compare`;
      fix all `bad` results.
- [ ] Run `python3 tools/screen_designs.py judge` with `--model auto` (or a pinned
      model); clear every `diff` and record accepted `review` verdicts.
- [ ] Record the judge model, fallback order, spend and evidence in
      `docs/screens/realism/` or the screen-design report.
- [ ] Add a short UI copy/button checklist to `docs/smoke-checklist.md`.
- [ ] Exit: all screens have consistent terminology and button behavior, long
      strings/scale pass, and the Python compare/judge gate has no unexplained
      diff.

## Patch 0.9.3 — NPC visual optimization

Goal: make the eight character variants hold up in portrait, conversation and crowd
views without changing the `npc_base`/`Rig/Head` contract or the skinned/procedural
fallback behavior.

### Reference and acceptance criteria

- [ ] Establish a portrait/contact-sheet baseline for all eight variants: front, three-quarter,
      profile, back, full body and a crowd-distance silhouette.
- [ ] Define acceptance criteria for proportions, face readability, hair, hands, shoes, clothing
      silhouette, gear fit and animation at the gameplay camera height (1.7 m).
- [ ] Record the camera/lighting/background used for comparison so model changes can be judged
      consistently; keep the existing portrait capture path deterministic.
- [ ] Identify the highest-impact gaps from the current portraits (e.g. face depth, hair mass,
      neck/shoulder transition, hand/foot shape, coat/dress hem) and rank them by player visibility.
- [ ] Publish a before/after NPC comparison sheet for review before changing the library.

### Body proportions and silhouette

- [ ] Audit all variants against a shared human proportion guide (head height, shoulder width,
      torso length, hip width, limb length, foot length) and correct the worst outliers.
- [ ] Improve neck, shoulder, torso and hip transitions so the silhouette reads as one body rather
      than stacked primitives; preserve the existing broad/slim/average build variations.
- [ ] Add subtle body-shape variation between variants beyond uniform scaling (shoulder slope,
      torso taper, hip width, limb thickness) while staying inside the triangle/vertex budget.
- [ ] Check the procedural fallback and `npc_base` silhouette against the library so the fallback
      remains a credible offline substitute.
- [ ] Re-measure LOD 0/1/2 silhouettes and ensure the impostor still matches each variant at distance.

### Head, face and hair

- [ ] Refine the head volume and jaw/cheek/chin proportions against the portrait concept; keep the
      face front direction unambiguous for the focus cone and head-turn.
- [ ] Improve brow/eye-socket depth, eyelid/iris readability, nose bridge/tip, lips and ear shape
      without turning the low-poly face into a noisy mesh.
- [ ] Audit hair caps, fringes, side locks, buns and beard silhouettes for gaps, intersections and
      obvious scalp seams; keep hair color in the tintable slot.
- [ ] Verify hats/hoods/sunglasses/helmets still clear the refined brow, ears and hair; update gear
      fit measurements and rebuild any affected gear.
- [ ] Check face readability under day, evening and LATE lighting and at the portrait capture’s
      shallow depth of field.

### Hands, feet and clothing

- [ ] Refine hands and fingers enough to read at conversation distance without exceeding the
      character triangle budget; check grip alignment for phone, cup, clipboard, camera, sign,
      flashlight, wand and radio.
- [ ] Audit shoes/boots for silhouette, grounding and contact with the floor; preserve the
      responder and firefighter footwear language.
- [ ] Improve clothing layer transitions at collars, cuffs, plackets, waistbands, pockets, badges
      and reflective bands; remove obvious z-fighting or floating detail.
- [ ] Add believable fabric folds/wrinkles at elbows, knees, waist and hems where the extra
      geometry pays off in portraits; keep the fixed detail materials and five tint slots intact.
- [ ] Re-check coat/dress/skirt hems during walking, blocking, sitting and turning; eliminate
      visible leg-through-hem clipping and floating hems.
- [ ] Verify outfit tinting on all five contract slots and fixed-colour details (hi-vis, leather,
      steel, patches, plastic, rubber) remains unchanged.

### Gear and equipment fit

- [ ] Run the Blender `fit` report for every character and all head/back/chest/hand gear; record
      head-band, skirt/hip clearance and inner-face clearances.
- [ ] Re-fit caps, beanie, hood, sunglasses and firefighter helmet against the refined face/hair;
      ensure eyebrow/ear clearance and a readable face with the hood up.
- [ ] Re-fit backpack, shoulder bag and SCBA tank against the revised torso/hips; fix strap and
      tank intersections and keep attachments outside the body silhouette.
- [ ] Verify lanyards, radios, phones, cups, clipboards, umbrellas, cameras, protest signs,
      flashlights and wands sit correctly in the hand/grip and do not float.
- [ ] Add regression checks for gear attach parents, head/back silhouette clearance and hand-item
      grip; rebuild affected GLBs, bake AO and re-import.

### Poses, animation and performance

- [ ] Review idle, walk, warning, blocking, recognition, refusal, phone, clipboard, photo, film,
      sit, panic/flee and responder poses for pops, foot sliding, floating props and head-turn
      overshoot.
- [ ] Add or refine short negotiation/reaction transitions (comply, argue, leave, recognize,
      block) without changing the seeded pose/outfit determinism.
- [ ] Re-measure the skinned-avatar frame cost at 16/24 NPCs and the LOD/impostor thresholds;
      record triangle, mesh and draw-call changes before raising any cap.
- [ ] Ensure the procedural fallback still passes the pose, target and crowd behavior tests after
      the model changes.

### Verification and handoff

- [ ] Rebuild the affected Blender assets, AO maps, manifest and review sheets; run
      `blender_assets.py audit`, `fit`, character imports and the full Godot test suite.
- [ ] Recapture the portrait, character gallery and crowd-distance shots; compare old/new and run
      the Python screen-design judge.
- [ ] Update `docs/blender-assets.md`, architecture/status, `MEMORY.md` and the changelog with the
      new budgets, limitations and rebuild commands.
- [ ] Exit: all eight variants pass the portrait/readability criteria, gear and hems no longer
      clip in normal play, the 24-NPC budget remains green, and the visual judge has no unexplained
      regressions.

## Patch 0.9.4 — Texture and material refinement

Goal: improve close-range surface and character texture quality while keeping GL
Compatibility/Web parity, deterministic assets and offline CI.

### Environment textures and materials

- [ ] Audit the v2 picks (brick, sidewalk pavers, dry/wet asphalt, awning canvas,
      day/dusk/night skylines) at close range and in the entrance/street shots for
      seams, tiling, scale, contrast and normal-map strength.
- [ ] Refine brick mortar/wear, paver joints/stains, asphalt aggregate/wet response
      and awning weave using the existing image/asset tooling; never overwrite a
      pick, use `-vN` candidates and promote validated results.
- [ ] Check UV scales and material roughness/metallic profiles; keep day/night
      phase behavior and the wet-street transition intact.
- [ ] Review distant skyline haze and foliage/planter surfaces against the concept
      references; fix obvious flatness without regressing readability.

### Character and prop textures

- [ ] Audit NPC skin, cloth, pants, hair and gear albedo/normal/AO maps in portraits;
      refine fabric weave, skin variation and fixed detail materials.
- [ ] Re-bake AO where geometry changes; verify the 256² maps and material wiring.
- [ ] Audit library props and UI/card/icon textures at their actual screen sizes;
      remove blurry/oversized or unused textures where safe.
- [ ] Run texture audits, import, and the full asset test suite; record texture memory
      and triangle/draw-call impact.

### Visual verification

- [ ] Run `python3 tools/scene_concepts.py realism` for the affected stages with the
      judge enabled; record metric gaps and model/spend.
- [ ] Re-run `tools/check_screenshots.sh` and the screen-design judge; clear all
      `diff` verdicts.
- [ ] Capture before/after close-ups for brick, pavement, asphalt, character cloth
      and skyline; document accepted trade-offs.
- [ ] Update asset docs and the changelog/status with the promoted texture versions.

## Patch 0.9.5 — Integration, performance and judge gate

Goal: integrate the UI/model/texture patches, prove the combined build on the
target paths and leave a clean release-candidate handoff.

### Integration and asset rebuild

- [ ] Rebuild all changed Blender/GLB/AO assets, re-import, and verify manifest/fit/
      audit coverage.
- [ ] Run the complete headless suite, Python tooling and smoke matrix; fix any
      regression from the three polish patches.
- [ ] Re-run the 24-NPC budget smoke and record frame time, mesh count and any
      texture-memory change; check Web and Desktop HQ if available.
- [ ] Verify save/campaign/tutorial behavior is unchanged by the visual/UI patches.

### Visual gallery and judge gate

- [ ] Recapture the full gallery, portraits, venue/realsim stages and Desktop HQ A/B
      as needed; no stale screenshots in the release set.
- [ ] Run `tools/check_screenshots.sh`, `screen_designs.py compare` and
      `screen_designs.py judge` on the final captures.
- [ ] Run the realism judge for the affected concepts with a pinned model; record
      model, attempt count, spend and verdicts.
- [ ] Review all `review` verdicts manually; convert unexplained layout/composition
      mismatches into fixes or explicit known limitations.
- [ ] Ensure generated realism folders remain gitignored/local-only and only the
      durable report decisions/docs are committed.

### Release-candidate handoff

- [ ] Update README, architecture, development status, changelog and TODO with the
      final patch-level results and any remaining gaps.
- [ ] Tag/version or otherwise freeze `0.9.4` as the integration checkpoint before
      the `0.10.0` release candidate.
- [ ] Exit: combined build is functionally green, visually reviewed, performance
      measured and ready for the 0.10.0 content-lock/playtest phase.

## Milestone 0.10.0 — Release candidate

Goal: freeze the feature set, prove it with external players, clear release/legal blockers and
verify every distribution path. This is the next shipped version before 1.0.

### Content lock and external playtest

- [ ] Declare a content/feature freeze for 0.10.0; only release-blocking fixes and balance changes
      may land after the freeze.
- [ ] Produce a release-candidate build with the tutorial, campaign, all three venues, Help,
      accessibility settings and checkpoint/resume enabled.
- [ ] 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-1.0 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

- [ ] Define measurable targets for routine compliance, access-decision accuracy, peaceful
      resolution, justified emergency calls and false-positive/false-negative rates.
- [ ] 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.
- [ ] 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

- [ ] 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.
- [ ] Test fresh install → tutorial → campaign → pause → quit → resume → review → next venue on
      an isolated user-data directory.
- [ ] Test corrupt JSON, partial temp files, missing optional fields and a failed atomic rename;
      confirm fallback behavior never destroys a valid save.
- [ ] Verify checkpoint resume after all three venues, after an incident, with NPCs at the door and
      with flashlight/body-camera/door state set.
- [ ] Document save locations, schema versions, reset behavior and rollback/export instructions in
      `docs/getting-started.md` and the release notes.

### Release engineering and distribution

- [ ] Run `tools/build_releases.sh` from a clean checkout and verify Linux/Windows/macOS/Web/HQ
      artifact names, sizes and checksums.
- [ ] Smoke-test fresh Linux portable/AppImage, Windows portable/installer, macOS unzip/launch,
      Web static hosting and Desktop HQ Vulkan fallback on the target matrix.
- [ ] Add a disk-space preflight and retention policy to the release/publish scripts so a full
      Gitea host cannot leave a partially uploaded release.
- [ ] 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.
- [ ] Decide and document whether macOS signing/notarization is required for 0.10.0 or explicitly
      remains a 1.0 blocker; record the quarantine instructions either way.

### Legal, credits and platform policy

- [ ] Audit AI-assisted asset provenance and licenses; record source/model usage and any
      redistribution constraints for textures, characters, props and UI art.
- [ ] Audit audio/SFX/music licensing (or confirm everything is procedural) and add a credits file.
- [ ] Review body-camera/privacy language, mental-health-crisis representation, age/content rating
      and storefront requirements; fix any release-blocking copy or content.
- [ ] Add the player-facing credits, known limitations, accessibility statement and privacy note to
      the release package/README.
- [ ] Mark external legal/storefront approval as complete or explicitly block 1.0 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/smoke-checklist.md`, `CHANGELOG.md` and this roadmap.
- [ ] Regenerate the full screenshot gallery and realism baselines after content lock; run
      `check_screenshots.sh` and the pinned vision judge, recording model/spend/verdicts.
- [ ] 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.
- [ ] Remove or archive stale plans/notes and confirm no contradictory version/status claims remain.

### 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-1.0 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 final stepping stone to 1.0.0.

## Milestone 1.0.0 — Launch

Goal: publish a stable, documented and supportable 1.0 build.

- [ ] Freeze content and version, run full final QA on Windows/Linux/macOS/Web/Desktop HQ, and
      verify fresh installs plus upgrade paths.
- [ ] Publish store/release notes, credits, known limitations, accessibility statement and
      controls; verify every download link and artifact checksum.
- [ ] Tag `v1.0.0`, publish through CI, verify the release page and post-launch patch policy.
- [ ] Definition of 1.0: three complete venues with campaign/tutorial, stable save/resume,
      accessibility/localization acceptance, measured performance on the target matrix, signed
      release artifacts where platform rules require it, and documentation synchronized with the
      build.

## Post-1.0 / non-blocking candidates

- [ ] Live 3D body-camera replay.
- [ ] Additional venues or seasonal events.
- [ ] Real voice/dialogue audio.
- [ ] Image-to-mesh prop pipeline.
- [ ] Rare easter eggs/cameos (e.g. Bob Dobbs) only after core content and QA are stable.

## 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.
- Keep the de-escalation-first rules and rare-emergency design unchanged while adding progression,
      difficulty and feedback.

## Realism follow-ups (deferred)

- [x] Re-run the screen-design judge for `12-joke-shop`, `13-studio-arrival` and the
      Forward+ A/B with the valid key: **13/13 match, 0 diff**; the HQ A/B is in the report.
- [ ] Capture a hooded/winter NPC close-up once a scenario spawns types 5-7 (the explicit
      `--portrait-type` override is already in `capture_realism.gd`).
- [ ] Human-authored tree/hedge silhouettes: the whole scene now reads well except the foliage,
      which is still flat-shaded clumps (`_shrub()`/`_tree()` in `tools/blender_assets.py`).
      Only worth doing if a higher-poly organic builder is added to the library.
- [ ] Camera height: the concept frames are shot at ~1.55 m with a slightly wider lens; the game
      camera sits at 1.7 m. Decide whether the first-person height should match the art direction
      or stay at the current gameplay value.

## Future ideas (optional, not scheduled)

- [ ] Live 3D body-camera replay (the timeline is text-only today).
- [ ] Additional venues or seasonal events authored from the new `.tres` files.
- [ ] Real voice/dialogue audio (the crowd bed and radio crackle are procedural).
- [ ] Swap the primitive prop builder for an image-to-mesh model API behind the same
      `assets/models/generated/<prop>.glb` contract.