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.9.0 (2026-11-01). Three playable venues, tutorial/campaign/checkpoint resume, difficulty/help, audio/accessibility settings, a 24-NPC budget baseline, a complete escalation/access/radio loop, shift review, the Blender asset library, 250 headless + 94 Python tests, a clean screen-design judge and an optional Forward+ Desktop HQ build. This is a strong release-candidate foundation, 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 (remaining to 1.0)

Area	Current baseline	Remaining gap	Risk	Milestone
Content and balance	3 venues with validated 12+ event matrices, recovery events and contextual dialogue	External playtest evidence, balance/fairness pass, event-weight tuning and final content lock	Repetition or unfair outcomes survive into 1.0	0.9.5
Dialog/UI	Complete screens and panel art, but copy/button behavior has not had a dedicated audit	Terminology, button states, long-string layout and full screen coverage need a focused pass	Inconsistent UI undermines first-hour clarity	0.9.1
Animation/presentation	Procedural pose layers, portrait captures, reduced hem clipping	Final model/pose/facial readability and gear-fit acceptance before visual QA	Close-up jank reduces perceived quality	0.9.2
Audio/accessibility	Procedural ambience/SFX, volume controls, captions/reduce-motion settings, searchable Help	Full accessibility/localization acceptance review, audio caption coverage and P0/P1 fixes	Public 1.0 cannot claim accessible play	0.9.1 / 0.9.5
Localization	English JSON table, validation and input-generated Help	Pseudo-locale/layout audit and translator workflow sign-off	Text expansion/clipping at release	0.9.1 / 0.9.5
Performance/platform	24-NPC headless budget (6.9 ms), Compatibility/Web/HQ paths	Target hardware matrix, Web/HQ manual profiling, frame-time/memory evidence	Platform-specific drops or startup failures	0.9.4 / 0.9.5
Save lifecycle	Settings/campaign/history/checkpoint files, atomic writes	Migration fixtures from 0.8/0.9, fresh-install/upgrade verification, rollback instructions	Player progress loss on upgrade	0.9.5
QA/CI	Headless suite, smokes, screenshot compare, optional judge	Full visual judge gate, release-candidate smoke matrix, final gallery and release dry run	Regressions escape the release gate	0.9.4 / 0.9.5
Release/legal	Unsigned desktop/macOS builds, Web/HQ packages	Signing/notarization decision, checksums, AI-asset provenance, credits, privacy/body-camera and rating review	Public release blocked by trust/policy	0.9.5
Documentation	Architecture/ADR/status/roadmap ownership established	Final README/changelog/status/TODO/smoke-checklist sign-off and known-limitations page	Docs drift at launch	0.9.4 / 0.9.5
Post-launch	Stable 0.9 feature set	Live replay, more venues, VO/music, image-to-mesh props and seasonal content	Scope creep before launch	Post-1.0

Patch 0.9.1 — Dialog, button and UI polish

Goal: make every player-facing screen read consistently and pass the Python screen-design judge before any model/texture changes. No gameplay rules change.

Screen and terminology inventory

• Inventory every screen/panel: start menu, venue menu, tutorial, HUD, pause, settings, Help, inspection, wand, radio/emergency, wheel, shift review, timeline and campaign/continue screens.
• Record the canonical terms for admit/deny, allow/refuse, warning/blocking, assistance/emergency, body camera, shift/review and campaign; remove synonyms that mean the same action.
• Audit all button labels for verb-first wording, capitalization, ordering, destructive-action confirmation and consistent confirm/cancel placement.
• List every hardcoded player-facing string and route it through content/strings.en.json; add placeholder validation for new keys.
• Review NPC/door-staff/radio/tutorial/help/review/campaign dialogue for repetition, ambiguity, tone and localization length.

Button and panel behavior

• Audit normal/hover/pressed/focus/disabled states on every button, including tutorial skip, venue continue, settings apply/cancel/reset, judge/review, radio send/emergency hold and Help close.
• Verify keyboard-only and gamepad-only navigation: focus order, wrapping, default focus, confirm/cancel behavior and no focus traps.
• Verify every modal closes with Esc/right-click where documented, recaptures the mouse, and does not leave the guard frozen or the menu visible.
• Test buttons at minimum/maximum HUD font scale and with 1.5–2× longer strings; fix clipping, overflow and overlapping layouts.
• Test destructive/irreversible actions (campaign reset, tutorial replay, emergency send) require the intended confirmation/hold and cannot double-fire.
• Verify radio normal-send vs emergency hold, inspection/wand allow/deny, review continue/retry/menu and Help search/filter behavior end to end.

Visual and judge verification

• Update the affected UI art/reference mapping where copy or button order changes; keep the no-overwrite image convention.
• Capture a deterministic screenshot for every dialog/button state that has a design reference; add missing capture stages or an explicit coverage gap.
• Run tools/check_screenshots.sh and python3 tools/screen_designs.py compare; fix all bad results.
• Run python3 tools/screen_designs.py judge with --model auto (or a pinned model); clear every diff and record accepted review verdicts.
• Record the judge model, fallback order, spend and evidence in docs/screens/realism/ or the screen-design report.
• Add a short UI copy/button checklist to docs/smoke-checklist.md.
• Exit: all screens have consistent terminology and button behavior, long strings/scale pass, and the Python compare/judge gate has no unexplained diff.

Patch 0.9.2 — NPC model refinement

Goal: make the eight character variants and their gear hold up in portraits and normal play without changing the npc_base/Rig/Head contract.

Model and rig audit

• Render all eight variants from front, profile, back and portrait angles; compare faces, hair, ears, hands, shoes, proportions and gear fit.
• Audit head/face readability (brow, eyes, lips, nose, hairline) at portrait distance; fix the highest-impact silhouette/face issues.
• Audit gear fit and clipping: caps/beanie/hood/helmet/sunglasses, shoulder bag, backpack, SCBA tank, lanyard, hand items and the new coat/dress stride.
• Audit coat/dress/skirt hems during walk, blocking, sitting and turning; fix remaining leg/hem intersections with weights, geometry or stride limits.
• Re-check the frozen contract: mesh npc_base, bone names, five tint slots, front direction, attach points, triangle/vertex budgets and grounding.
• Rebuild affected GLBs, bake AO, run godot --headless --path . --import, and run blender_assets.py audit plus fit/portrait checks.

Pose and animation polish

• Review idle, walk, warning, blocking, recognition, refusal, phone, clipboard, photo, film, sit and responder poses for pops or floating props.
• Add/adjust short transitions for negotiation/reaction poses without breaking the seeded pose helpers or head-turn behavior.
• Verify LOD tiers and the impostor at 16/24-NPC distances; re-run the budget smoke and record any triangle/draw-call changes.
• Refresh the Blender review sheets and character portraits; keep per-asset previews local if gitignored.

Verification

• Add/update headless tests for any new pose/model contract behavior.
• Capture the portrait and character gallery; compare against the design references and run the Python judge.
• Update docs/blender-assets.md, architecture/status and MEMORY.md with the revised budgets, limitations and rebuild commands.
• Exit: portrait/readability and gear fit pass, no obvious P0/P1 clipping remains, and the 24-NPC budget/full test suite are green.

Patch 0.9.3 — Texture and material refinement

Goal: improve close-range surface and character texture quality while keeping GL Compatibility/Web parity, deterministic assets and offline CI.

Environment textures and materials

• Audit the v2 picks (brick, sidewalk pavers, dry/wet asphalt, awning canvas, day/dusk/night skylines) at close range and in the entrance/street shots for seams, tiling, scale, contrast and normal-map strength.
• Refine brick mortar/wear, paver joints/stains, asphalt aggregate/wet response and awning weave using the existing image/asset tooling; never overwrite a pick, use -vN candidates and promote validated results.
• Check UV scales and material roughness/metallic profiles; keep day/night phase behavior and the wet-street transition intact.
• Review distant skyline haze and foliage/planter surfaces against the concept references; fix obvious flatness without regressing readability.

Character and prop textures

• Audit NPC skin, cloth, pants, hair and gear albedo/normal/AO maps in portraits; refine fabric weave, skin variation and fixed detail materials.
• Re-bake AO where geometry changes; verify the 256² maps and material wiring.
• Audit library props and UI/card/icon textures at their actual screen sizes; remove blurry/oversized or unused textures where safe.
• Run texture audits, import, and the full asset test suite; record texture memory and triangle/draw-call impact.

Visual verification

• Run python3 tools/scene_concepts.py realism for the affected stages with the judge enabled; record metric gaps and model/spend.
• Re-run tools/check_screenshots.sh and the screen-design judge; clear all diff verdicts.
• Capture before/after close-ups for brick, pavement, asphalt, character cloth and skyline; document accepted trade-offs.
• Update asset docs and the changelog/status with the promoted texture versions.

Patch 0.9.4 — Integration, performance and judge gate

Goal: integrate the UI/model/texture patches, prove the combined build on the target paths and leave a clean release-candidate handoff.

Integration and asset rebuild

• Rebuild all changed Blender/GLB/AO assets, re-import, and verify manifest/fit/ audit coverage.
• Run the complete headless suite, Python tooling and smoke matrix; fix any regression from the three polish patches.
• Re-run the 24-NPC budget smoke and record frame time, mesh count and any texture-memory change; check Web and Desktop HQ if available.
• Verify save/campaign/tutorial behavior is unchanged by the visual/UI patches.

Visual gallery and judge gate

• Recapture the full gallery, portraits, venue/realsim stages and Desktop HQ A/B as needed; no stale screenshots in the release set.
• Run tools/check_screenshots.sh, screen_designs.py compare and screen_designs.py judge on the final captures.
• Run the realism judge for the affected concepts with a pinned model; record model, attempt count, spend and verdicts.
• Review all review verdicts manually; convert unexplained layout/composition mismatches into fixes or explicit known limitations.
• Ensure generated realism folders remain gitignored/local-only and only the durable report decisions/docs are committed.

Release-candidate handoff

• Update README, architecture, development status, changelog and TODO with the final patch-level results and any remaining gaps.
• Tag/version or otherwise freeze 0.9.4 as the integration checkpoint before the 0.9.5 release candidate.
• Exit: combined build is functionally green, visually reviewed, performance measured and ready for the 0.9.5 content-lock/playtest phase.

Milestone 0.9.5 — Release candidate

Goal: freeze the feature set, prove it with external players, clear release/legal blockers and verify every distribution path. This is the next shipped version before 1.0.

Content lock and external playtest

• Declare a content/feature freeze for 0.9.5; only release-blocking fixes and balance changes may land after the freeze.
• Produce a release-candidate build with the tutorial, campaign, all three venues, Help, accessibility settings and checkpoint/resume enabled.
• Run at least five first-time-player sessions covering the tutorial and one full venue shift; record where players get stuck, misunderstand evidence or choose disproportionate escalation.
• Triage findings by severity (P0/P1/P2) and fix every P0/P1 onboarding/accessibility issue; keep the rest as explicit known limitations or post-1.0 items.
• Re-run the affected tutorial/campaign smokes after each fix and capture a fresh first-hour walkthrough for the release notes.

Balance and fairness pass

• Define measurable targets for routine compliance, access-decision accuracy, peaceful resolution, justified emergency calls and false-positive/false-negative rates.
• Run scripted venue sweeps across easy/normal/hard and all four phases; compare outcomes and tune event weights, reaction tables, compliance and report strictness where targets fail.
• Review emergency calls against actual danger: no routine behavior should make emergency the dominant winning move, and genuine threats must remain answerable.
• Verify the reputation grades, debrief explanations and campaign progression still communicate the de-escalation-first design after tuning.
• Record the balance evidence and any deliberate exceptions in docs/development-status.md or MEMORY.md.

Save migration and session reliability

• Add fixtures for a 0.8-era settings/campaign/history save and a 0.9.0 checkpoint; verify migration/default-filling and a clean first launch with no files.
• Test fresh install → tutorial → campaign → pause → quit → resume → review → next venue on an isolated user-data directory.
• Test corrupt JSON, partial temp files, missing optional fields and a failed atomic rename; confirm fallback behavior never destroys a valid save.
• Verify checkpoint resume after all three venues, after an incident, with NPCs at the door and with flashlight/body-camera/door state set.
• Document save locations, schema versions, reset behavior and rollback/export instructions in docs/getting-started.md and the release notes.

Release engineering and distribution

• Run tools/build_releases.sh from a clean checkout and verify Linux/Windows/macOS/Web/HQ artifact names, sizes and checksums.
• Smoke-test fresh Linux portable/AppImage, Windows portable/installer, macOS unzip/launch, Web static hosting and Desktop HQ Vulkan fallback on the target matrix.
• Add a disk-space preflight and retention policy to the release/publish scripts so a full Gitea host cannot leave a partially uploaded release.
• Verify release metadata, tag/version consistency, asset counts and download links; retain at least the latest 0.8/0.9 releases and document older-asset pruning.
• Decide and document whether macOS signing/notarization is required for 0.9.5 or explicitly remains a 1.0 blocker; record the quarantine instructions either way.

Legal, credits and platform policy

• Audit AI-assisted asset provenance and licenses; record source/model usage and any redistribution constraints for textures, characters, props and UI art.
• Audit audio/SFX/music licensing (or confirm everything is procedural) and add a credits file.
• Review body-camera/privacy language, mental-health-crisis representation, age/content rating and storefront requirements; fix any release-blocking copy or content.
• Add the player-facing credits, known limitations, accessibility statement and privacy note to the release package/README.
• Mark external legal/storefront approval as complete or explicitly block 1.0 on it.

Documentation and visual sign-off

• Update README.md, PLAN.md, docs/architecture.md, ADRs, docs/development-status.md, docs/getting-started.md, docs/smoke-checklist.md, CHANGELOG.md and this roadmap.
• Regenerate the full screenshot gallery and realism baselines after content lock; run check_screenshots.sh and the pinned vision judge, recording model/spend/verdicts.
• Run the manual smoke checklist on every target and attach/link the release-candidate evidence.
• Verify the tutorial/campaign/help text at maximum font scale and with the longest strings.
• Remove or archive stale plans/notes and confirm no contradictory version/status claims remain.

Release-candidate QA and exit

• Run the complete headless suite, Python tooling, tutorial/campaign/session/scenario smokes, 24-NPC budget smoke and release build from a clean checkout.
• Run the manual QA matrix: fresh install, upgrade, offline launch, gamepad, accessibility settings, pause/resume, all venues and Desktop HQ fallback.
• Confirm no P0/P1 defects remain; P2 items must be documented as known limitations or post-1.0 work.
• Create the v0.9.5 version bump, changelog entry and tag; build/publish the release and verify all assets and download links.
• Exit: the release candidate is content-locked, externally played, legally reviewed, documented, reproducibly built, and approved as the final stepping stone to 1.0.0.

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.