# 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.7.2** (2026-11-01). Three playable venues, a complete escalation/access/radio
loop, shift review, a Blender character/gear/prop library, 231 headless + 94 Python tests, a
13/13 clean screen-design judge and an optional Forward+ Desktop HQ build. This is a strong
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/presentation pass: negotiation/reaction poses and transitions, readable faces in
      portrait, resolved camera height, and no coat/skirt leg clipping in normal movement.
- [ ] Audio pass: music/ambience direction, event SFX, radio/crowd mix, caption hooks and a VO
      decision with production scope.
- [ ] Localization pass: all player-facing strings externalized, pseudo-locale layout test, font
      fallback and a contributor translation workflow.
- [ ] Accessibility pass: subtitles/captions, colour-independent access/escalation cues, motion
      and flash options, full keyboard/gamepad parity and documented assist options.
- [ ] Performance pass: profile 24 live NPCs, all venues, Web and Desktop HQ; record frame-time,
      draw-call and memory budgets; add regression checks where automation is possible.
- [ ] QA pass: automated end-to-end shift for each venue, full smoke matrix, screenshot/judge
      baselines, and a documented manual judge budget/model pin.
- [ ] Resolve the Godot baseline: choose one supported version (or an explicit 4.3-CI/4.7-local
      matrix), align export templates and visual smoke results, and document the policy.
- [ ] Exit: production content is feature-complete, accessibility/localization acceptance criteria
      pass, target hardware matrix is measured, and no P0/P1 defect remains 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.