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

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

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