# 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.8.0 — First hour and content depth

Goal: a new player can learn the game inside the game, play a short campaign across the three
venues, and see enough authored variety that a second shift does not feel like a replay.

### 0.8.1 First-shift tutorial

- [x] Write the tutorial beat sheet: menu → movement/look → focus and target cycling → action
      wheel → access inspection → polite direction → formal warning/body camera → radio →
      shift review. Eight beats and a safe compliant visitor are specified in
      [`docs/tutorial.md`](docs/tutorial.md).
- [x] Add a tutorial state machine independent of the normal shift FSM. `Tutorial` in
      `src/game/tutorial.gd` owns the eight beats, accepts only the current beat's action,
      supports skip/restart and has deterministic headless tests. GameManager/UI wiring starts
      with the contextual-prompt task.
- [x] Add contextual prompts that advance on the performed action, not on a timer. The
      non-blocking `TutorialOverlay` card updates from `Tutorial.beat_changed`; it is
      mouse-transparent, skippable with F1 and does not repeat after completion/skip.
- [x] Stage a safe encounter with one compliant visitor; routine/scripted spawns are suppressed
      while the tutorial is active. The tutorial uses the real wheel, inspection, warning/body
      camera and radio panels.
- [x] Persist tutorial completion/skip in `settings.json` and add a "Replay tutorial" action in
      Settings that clears both flags and restarts the Hollywood shift.
- [x] Add localized tutorial strings (`tutorial.*` keys) and caption-ready prompt hooks in the
      overlay/state table.
- [x] Add headless tutorial-state tests and `smoke_tutorial.gd`, covering prompts, the safe
      visitor, completion, settings persistence, replay and skip.

Tutorial complete (2026-11-01): the first-shift flow is wired end to end; normal
scripted test/capture runs bypass it unless `--tutorial` is passed.

### 0.8.2 Campaign and session shell

- [ ] Define campaign data separately from `VenueScenario`: venue order, unlock conditions,
      shift number, selected difficulty and completion state.
- [ ] Add a campaign-select/continue screen that shows the next shift, venue, policy summary and
      previous result; keep the existing debug venue cycle separate.
- [ ] Add a "Continue shift" path with an explicit resume point; define whether resume restores
      the exact paused shift or the last safe checkpoint.
- [ ] Add a post-shift screen that names the next objective and offers retry, continue or return
      to the menu. Do not silently reset progression on failure.
- [ ] Persist campaign state and expose a reset-campaign action with confirmation.
- [ ] Add deterministic tests for fresh campaign, resume, completed venue and failed/retried shift.

### 0.8.3 Venue content matrix

- [ ] Add a content matrix per venue with columns for phase, event kind (routine/scripted/edge/
      recovery/threat), NPC type, intent, access artifact, expected escalation ceiling, failure/
      recovery path and spawn weight.
- [ ] Add a validation test that every event references an existing profile, location and phase;
      reject duplicate IDs and unreachable waypoints at load time.
- [ ] Expand each venue toward at least 12 authored events and 6 reusable routine variants,
      covering all four shift phases; prioritize repeatable combinations over one-off set pieces.
- [ ] Add a no-repeat rule and phase-aware weighting so consecutive shifts do not replay the same
      scripted event, while rare threats remain genuinely rare.
- [ ] Add recovery events after player mistakes: a refused authorized guest returns, a manager
      intervention, a crowd-calming opportunity, or a second chance to explain a policy.
- [ ] Add a content preview/debug list showing the next eligible events and why they were chosen.
- [ ] Add tests for phase gating, no-repeat selection, recovery eligibility and event reachability.

### 0.8.4 NPC dialogue and negotiation

- [ ] Define a dialogue data format for intent-specific and context-specific lines: greeting,
      refusal, de-escalation response, recognition callback, group reaction and resolution.
- [ ] Expand `NpcProfile` dialogue beyond one-line replies and select lines deterministically from
      seed, prior interaction and current escalation level; no runtime LLM dependency.
- [ ] Wire Ask/Reason, polite direction, warning, blocking, recognition and inspection outcomes to
      the new lines and log entries, with visible differences between comply, argue and refuse.
- [ ] Add a small set of group reactions so nearby NPCs respond to a raised voice, a warning, a
      responder or a crowd panic without every NPC speaking at once.
- [ ] Add placeholder-safe localized strings and tests for deterministic selection, missing lines
      and dialogue length in the HUD/log.
- [ ] Run a short dialogue readability pass on the three venues and replace repeated phrases.

### 0.8.5 Objective, policy and debrief layer

- [ ] Add a compact venue-policy card (accepted artifacts, door rules, emergency threshold) that
      is available from the help overlay and the shift-review screen.
- [ ] Add an in-shift "current objective" line when the scenario phase changes, without turning
      the HUD into a quest log.
- [ ] After an incident, record and display the evidence checked, the chosen escalation level and
      the reason the response was judged fair, weak or excessive.
- [ ] Add a first-shift completion summary that explains the grade in plain language and points to
      the specific decision(s) that mattered.
- [ ] Add tests for policy-card content, debrief evidence ordering and unknown/missing evidence.

### 0.8.6 Save, resume and settings

- [ ] Define a versioned save schema covering settings, tutorial completion, campaign progress,
      difficulty and resumable shift state; document what is deliberately not serialized.
- [ ] Implement atomic writes, corruption detection and safe fallback to defaults or the last
      completed shift; never overwrite a valid save with a partial one.
- [ ] Add save migration from the current settings/shift-history format and a test fixture for the
      previous schema.
- [ ] Add mid-shift resume that restores RNG state, elapsed time, NPC/incident state and the door
      state consistently; verify a resumed shift can reach its review.
- [ ] Add persistence tests for fresh install, corrupt save, version migration, completed shift and
      resumed shift.

### 0.8.7 Difficulty, pacing and help

- [ ] Add difficulty presets that only adjust spawn rate, tolerance, report strictness and event
      weights; the de-escalation-first rules and emergency rarity must not change.
- [ ] Expose difficulty in the campaign/settings UI with the current build as the default "normal"
      preset and a clear description of each change.
- [ ] Add a new-player help overlay separate from the HUD: controls, focus/wheel flow, access
      evidence, body camera, radio and shift review.
- [ ] Add a searchable/filterable controls reference and keep it synchronized with input bindings.
- [ ] Add a readability pass for first-shift HUD density; hide advanced debug-only information by
      default.
- [ ] Add tests for difficulty defaults, settings persistence and help/controls coverage of every
      named input action.

### 0.8.8 Verification and exit criteria

- [ ] Add headless tests for tutorial progression, campaign state, content-matrix validation,
      dialogue selection, save migration and difficulty defaults.
- [ ] Add windowed/headless smokes for a complete tutorial, a resumed shift, a campaign venue
      transition and the help overlay.
- [ ] Run a manual first-hour test with at least three people unfamiliar with the project; record
      where they get stuck and fix P0/P1 onboarding issues before closing the milestone.
- [ ] Re-run the full headless suite, Python tooling and smoke checklist; update
      `docs/development-status.md`, architecture links, changelog and README where behavior changed.
- [ ] Exit: a first-time player can complete the tutorial and a first real shift without external
      documentation; each venue has a repeatable content matrix; save/resume survives restart;
      the 0.8 test matrix is green.

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