security-game/TODO.md

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)

• 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.
• 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.
• 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.
• Resolve stale claims: README release version/download row, development status "Forward+ not implemented", and Blender props "not AO-baked".
• 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

• 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.
• 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.
• 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.
• 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.
• Persist tutorial completion/skip in settings.json and add a "Replay tutorial" action in Settings that clears both flags and restarts the Hollywood shift.
• Add localized tutorial strings (tutorial.* keys) and caption-ready prompt hooks in the overlay/state table.
• 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)

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