# 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.8.1** (2026-11-01). Three playable venues, tutorial/campaign/checkpoint resume,
difficulty/help, a complete escalation/access/radio loop, shift review, the Blender asset library,
249 headless + 94 Python tests, a clean screen-design judge and an optional Forward+ Desktop HQ
build. This is a strong first-hour vertical slice, 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

| Area | Current baseline | Gap to 1.0 | Risk | Milestone |
| --- | --- | --- | --- | --- |
| First-hour experience | Venue menu and controls exist; no tutorial | No guided first shift, control coaching, objective recap or "what went wrong" debrief | New players bounce before the de-escalation loop lands | 0.8.0 |
| Campaign/progression | Venue selection and debug cycle | No career/venue order, unlocks, difficulty curve or persistent player progression | Shift loop feels like a tech demo rather than a game | 0.8.0 |
| Authored content | 3 venues, small event pools, one-line dialogue | Need a larger event matrix per venue, repeat/remix rules, failure/recovery events and more NPC dialogue | Repetition after a few shifts | 0.8.0 |
| NPC behavior | FSM intents, reactions, crowd/theater poses | Deeper negotiation, memory of earlier interactions, group dynamics, believable refusal/escalation edges | NPCs still feel deterministic/scripted | 0.8.0 |
| Access/evaluation | Recognition, wristbands/IDs/tickets/credentials, reputation/review | Fairness tuning, ambiguous cases, clearer evidence trail, richer grades and actionable feedback | Players cannot learn why a decision scored poorly | 0.8.0 |
| Shift lifecycle | Settings + completed-shift history persist | No mid-shift save/resume, pause-safe serialization, versioned save schema or replay | Interrupted sessions lose the run; future changes can break saves | 0.8.0 |
| Accessibility | Key remapping, gamepad, HUD font scale, shape escalation cue | Subtitles/captions, colour-independent cues, motion/audio sensitivity, text expansion, menu narration and full input alternatives need an audit | Public 1.0 cannot claim accessible play | 0.8.0–0.9.0 |
| Localization | English strings in `content/strings.en.json` | String extraction/coverage, pseudo-locale test, font fallback, text-length layout budgets and translator workflow | Text bugs and unsupported locales at release | 0.9.0 |
| Audio | Procedural crowd bed and radio crackle | Music/ambience direction, event SFX, voice/VO decision, caption hooks and mix budgets | Scene can feel silent/placeholder | 0.9.0 |
| Animation/presentation | Procedural poses, walk/idle theater, LOD impostor | More reaction/idle/negotiation poses, transitions, facial readability at portrait distance, camera-height decision | Cinematic close-ups expose the prototype layer | 0.9.0 |
| Performance/platform | 16-NPC budget measured headlessly; Compatibility default; optional Vulkan HQ | Target hardware matrix, 24-NPC profiling, draw-call/memory budgets, Web/HQ parity and frame-time regression gates | Crowded studio or Web drops frames | 0.9.0 |
| Content tooling | ScenarioFactory/.tres export, Blender manifest, asset audits | Schema validation, previews, event authoring workflow, reproducible asset rebuild notes and contributor onboarding | Content expansion becomes expensive/error-prone | 0.8.0–0.9.0 |
| QA/CI | Headless suite, smokes, screenshot compare, model-aware judge | End-to-end shift automation, full venue matrix, CI Godot-version strategy, manual judge budget and release checklist automation | Regressions escape or CI becomes non-reproducible | 0.9.0 |
| Release/legal | Tag-driven unsigned builds, Web zip, optional HQ | Signing/notarization, checksums, AI-asset provenance/licensing, credits, privacy/body-camera statement and storefront requirements | Public release blocked by trust/policy issues | 0.9.5 |
| Documentation | Layered docs consolidated; drift was found | Keep changelog/status/roadmap/ADR links synchronized per release; add contributor architecture tour | Docs become stale again | Continuous |

## Milestone 0.9.0 — Production quality and platform readiness

Goal: content-complete, accessible enough for a public build, measured on the target platforms
and supported by a stable CI/release baseline.

### Animation and presentation

- [ ] Decide the first-person camera height against the concept frames; record the decision and
      update the capture poses if the camera moves.
- [ ] Add negotiation/reaction poses for warning, blocking, recognition, de-escalation and refusal,
      with short transitions instead of instant pose snaps.
- [ ] Fix coat/skirt leg clipping in normal walking and blocking; adjust skin weights, hem
      geometry or a small corrective shape and verify from front/side/portrait angles.
- [ ] Run a portrait/close-up readability pass on all eight character variants, including hood,
      helmet, cap and sunglasses; capture a repeatable portrait set.
- [ ] Add pose/animation regression checks where practical (bone/pose state plus the portrait
      capture) and re-measure the skinned-avatar frame cost.
- [ ] Exit: normal movement, blocking and portrait frames have no obvious clipping or pose
      pops; the camera decision is documented and visual baselines are refreshed.

### Audio

- [ ] Write the audio direction: crowd ambience, venue mood, UI/radio ticks, footsteps, warning
      and escalation cues, and whether music is needed.
- [ ] Map every gameplay event to an SFX/ambience hook, including tutorial prompts, campaign
      transitions, radio send/failure, door lock and responder arrival.
- [ ] Add Music, SFX and Ambience volume controls to Settings and persist them; keep the dummy
      audio server safe for headless tests.
- [ ] Add caption metadata to audio cues and tie it to the accessibility captions.
- [ ] Make the VO decision: text-only for 0.9, or a scoped voice pipeline with content list,
      recording/casting plan, licensing and fallback text.
- [ ] Add audio smoke coverage for the new hooks and mix levels; document the final mix targets.

### Localization

- [ ] Audit hardcoded player-facing text, starting with Help, campaign/status screens, tutorial
      overlay, review labels and new dialogue; move everything into `strings.en.json`.
- [ ] Add a pseudo-locale or long-string expansion test that runs the UI at 1.5–2× text length and
      flags clipped buttons, labels and HUD rows.
- [ ] Verify font coverage for punctuation, arrows, accented characters and non-Latin sample
      glyphs; document the fallback font policy.
- [ ] Write the translator workflow: key naming, source-of-truth file, placeholders, review and
      screenshot checks, and how to add a locale without code changes.
- [ ] Add localization coverage tests for every named input action and every new 0.9 UI surface.
- [ ] Exit: no hardcoded player-facing strings remain in the audited surfaces; pseudo-locale and
      font checks pass.

### Accessibility

- [ ] Add subtitles/captions for tutorial prompts, radio/phone dialogue and key audio cues, with
      a Settings toggle and readable defaults.
- [ ] Audit all colour-dependent cues (access, escalation, crowd, door, flashlight) and add a
      colour-independent shape/text/icon alternative where missing.
- [ ] Add motion/flash options: disable camera bob/shake, reduce rapid flashes, and verify the
      precision-walk/HUD transitions remain usable.
- [ ] Verify complete keyboard-only and gamepad-only paths for menus, tutorial, inspection, wheel,
      radio (including hold timing), review and Help.
- [ ] Test HUD/font scaling at minimum and maximum settings, including long localized strings and
      the body-camera overlay.
- [ ] Write an accessibility statement and a manual accessibility checklist; add automated coverage
      for input parity and caption/hint availability.
- [ ] Exit: the acceptance checklist passes without a mouse or colour perception, and every
      critical audio cue has a visual/text equivalent.

### Performance and platform

- [ ] Define the target hardware matrix (minimum/recommended desktop, Web browser and Desktop HQ
      Vulkan) and record baseline frame-time, draw calls and memory per venue.
- [ ] Add a repeatable 24-NPC performance smoke across all venues, including crowd panic and the
      studio arrival; keep the 16-NPC result as the regression floor.
- [ ] Profile Web and Desktop HQ separately; investigate LOD/impostor thresholds, prop draw calls,
      shadow cost and skinning CPU before adding more avatars.
- [ ] Add frame-time/memory regression gates where automation is possible and document manual
      capture steps for the rest.
- [ ] Verify the Compatibility/Web fallback and HQ Vulkan fallback on the target matrix; record
      startup failures and GPU-driver requirements.
- [ ] Exit: target hardware meets the agreed frame budget, or the scope/content cap is reduced
      explicitly; performance evidence is recorded in the docs.

### QA automation and visual baselines

- [ ] Add an automated end-to-end shift for each venue that covers spawn, access, escalation,
      radio, review and campaign advancement.
- [ ] Consolidate the smoke matrix into one documented command/checklist; include tutorial,
      checkpoint resume, campaign transition, Help, radio and all venue paths.
- [ ] Refresh the screenshot gallery and realism baselines; run `compare` and the pinned judge,
      recording the model, spend and any accepted review verdicts.
- [ ] Keep the vision judge optional and cost-capped; document the manual judge budget/model pin
      and never make an external API a CI release gate.
- [ ] Add a release-candidate dry run that builds every artifact, verifies installers/Web/HQ and
      records checksums.
- [ ] Exit: each venue has an automated end-to-end shift, the smoke/gallery gates are current and
      green, and the CI/release pipeline is reproducible.

### Godot baseline and version policy

- [ ] Choose the supported engine policy: one pinned version, or an explicit CI/local matrix
      (currently 4.3 CI vs 4.7.2 local).
- [ ] If upgrading, run import/headless/screenshot/HQ checks, remove temporary version-specific
      light-falloff branches where possible, and align export templates, `.uid` policy and CI.
- [ ] Document the upgrade/rollback procedure and the visual-smoke requirements for engine bumps.
- [ ] Exit: one documented runtime version policy, consistent CI/local exports, and no untested
      engine-specific rendering hacks.

### Verification and exit criteria

- [ ] Add/verify headless tests for every new 0.9 system, plus localization, accessibility and
      performance checks that can run without a display.
- [ ] Run the full smoke matrix and capture/label a clean 0.9 screenshot set.
- [ ] Run a manual accessibility/localization review and record findings; fix P0/P1 blockers.
- [ ] Update architecture, ADRs, status, README, changelog and roadmap in the same change as the
      implementation.
- [ ] Exit: production content is feature-complete, accessibility/localization acceptance criteria
      pass, target hardware is measured, the engine policy is documented, and no P0/P1 defect is
      open.

## Milestone 0.9.5 — Release candidate

Goal: freeze content, prove it with external players, clear release/legal blockers and verify
every distribution path.

- [ ] Content lock and external playtest round (at least five first-time players); triage findings
      by severity and fix all P0/P1 issues.
- [ ] Balance and fairness pass across all venues: scoring, difficulty, event weights, NPC
      compliance and emergency false-positive/negative rates.
- [ ] Save migration test from 0.8/0.9 saves; verify settings, shift history and resume paths.
- [ ] Release engineering: signed/notarized macOS where possible, checksums, Windows/Linux install
      smoke tests, AppImage update, Web hosting verification and Desktop HQ Vulkan fallback.
- [ ] Legal/credits review: AI-assisted asset provenance, music/SFX licenses, privacy/body-camera
      language, age/content rating and storefront requirements.
- [ ] Documentation sign-off: architecture/ADR/status/TODO/changelog/README/smoke checklist all
      match the release candidate; capture final gallery and run compare + judge.
- [ ] Exit: release candidate passes the manual smoke checklist on every target; no release-blocking
      legal or platform issue remains.

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