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.1 (2026-11-02). 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 + 97 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.10.0
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.2
Animation/presentation	Procedural pose layers, portrait captures, reduced hem clipping	Thorough NPC silhouette/face/gear/pose/LOD optimization before visual QA	Close-up jank reduces perceived quality	0.9.3
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.2 / 0.10.0
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.2 / 0.10.0
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.5 / 0.10.0
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.10.0
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.5 / 0.10.0
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.10.0
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.5 / 0.10.0
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.2 — 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. Recorded in docs/ui-copy.md.
• Record the canonical terms for admit/refuse, warning/blocking, assistance/emergency, body camera, shift review and campaign; the current inspection/wand/radio/review labels use them (see docs/ui-copy.md).
• 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.3 — NPC visual optimization

Goal: make the eight character variants hold up in portrait, conversation and crowd views without changing the npc_base/Rig/Head contract or the skinned/procedural fallback behavior.

Reference and acceptance criteria

• Establish a portrait/contact-sheet baseline for all eight variants: front, three-quarter, profile, back, full body and a crowd-distance silhouette.
• Define acceptance criteria for proportions, face readability, hair, hands, shoes, clothing silhouette, gear fit and animation at the gameplay camera height (1.7 m).
• Record the camera/lighting/background used for comparison so model changes can be judged consistently; keep the existing portrait capture path deterministic.
• Identify the highest-impact gaps from the current portraits (e.g. face depth, hair mass, neck/shoulder transition, hand/foot shape, coat/dress hem) and rank them by player visibility.
• Publish a before/after NPC comparison sheet for review before changing the library.

Body proportions and silhouette

• Audit all variants against a shared human proportion guide (head height, shoulder width, torso length, hip width, limb length, foot length) and correct the worst outliers.
• Improve neck, shoulder, torso and hip transitions so the silhouette reads as one body rather than stacked primitives; preserve the existing broad/slim/average build variations.
• Add subtle body-shape variation between variants beyond uniform scaling (shoulder slope, torso taper, hip width, limb thickness) while staying inside the triangle/vertex budget.
• Check the procedural fallback and npc_base silhouette against the library so the fallback remains a credible offline substitute.
• Re-measure LOD 0/1/2 silhouettes and ensure the impostor still matches each variant at distance.

Head, face and hair

• Refine the head volume and jaw/cheek/chin proportions against the portrait concept; keep the face front direction unambiguous for the focus cone and head-turn.
• Improve brow/eye-socket depth, eyelid/iris readability, nose bridge/tip, lips and ear shape without turning the low-poly face into a noisy mesh.
• Audit hair caps, fringes, side locks, buns and beard silhouettes for gaps, intersections and obvious scalp seams; keep hair color in the tintable slot.
• Verify hats/hoods/sunglasses/helmets still clear the refined brow, ears and hair; update gear fit measurements and rebuild any affected gear.
• Check face readability under day, evening and LATE lighting and at the portrait capture’s shallow depth of field.

Hands, feet and clothing

• Refine hands and fingers enough to read at conversation distance without exceeding the character triangle budget; check grip alignment for phone, cup, clipboard, camera, sign, flashlight, wand and radio.
• Audit shoes/boots for silhouette, grounding and contact with the floor; preserve the responder and firefighter footwear language.
• Improve clothing layer transitions at collars, cuffs, plackets, waistbands, pockets, badges and reflective bands; remove obvious z-fighting or floating detail.
• Add believable fabric folds/wrinkles at elbows, knees, waist and hems where the extra geometry pays off in portraits; keep the fixed detail materials and five tint slots intact.
• Re-check coat/dress/skirt hems during walking, blocking, sitting and turning; eliminate visible leg-through-hem clipping and floating hems.
• Verify outfit tinting on all five contract slots and fixed-colour details (hi-vis, leather, steel, patches, plastic, rubber) remains unchanged.

Gear and equipment fit

• Run the Blender fit report for every character and all head/back/chest/hand gear; record head-band, skirt/hip clearance and inner-face clearances.
• Re-fit caps, beanie, hood, sunglasses and firefighter helmet against the refined face/hair; ensure eyebrow/ear clearance and a readable face with the hood up.
• Re-fit backpack, shoulder bag and SCBA tank against the revised torso/hips; fix strap and tank intersections and keep attachments outside the body silhouette.
• Verify lanyards, radios, phones, cups, clipboards, umbrellas, cameras, protest signs, flashlights and wands sit correctly in the hand/grip and do not float.
• Add regression checks for gear attach parents, head/back silhouette clearance and hand-item grip; rebuild affected GLBs, bake AO and re-import.

Poses, animation and performance

• Review idle, walk, warning, blocking, recognition, refusal, phone, clipboard, photo, film, sit, panic/flee and responder poses for pops, foot sliding, floating props and head-turn overshoot.
• Add or refine short negotiation/reaction transitions (comply, argue, leave, recognize, block) without changing the seeded pose/outfit determinism.
• Re-measure the skinned-avatar frame cost at 16/24 NPCs and the LOD/impostor thresholds; record triangle, mesh and draw-call changes before raising any cap.
• Ensure the procedural fallback still passes the pose, target and crowd behavior tests after the model changes.

Verification and handoff

• Rebuild the affected Blender assets, AO maps, manifest and review sheets; run blender_assets.py audit, fit, character imports and the full Godot test suite.
• Recapture the portrait, character gallery and crowd-distance shots; compare old/new and run the Python screen-design judge.
• Update docs/blender-assets.md, architecture/status, MEMORY.md and the changelog with the new budgets, limitations and rebuild commands.
• Exit: all eight variants pass the portrait/readability criteria, gear and hems no longer clip in normal play, the 24-NPC budget remains green, and the visual judge has no unexplained regressions.

Patch 0.9.4 — 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.5 — Map Optimization

Goal: streamline the maps, refactor geometry to match the images in docs/screens/concepts. Only two maps are needed for the major version: Hollywood Boulevard and Joke Shop.

Map 1 — Hollywood Boulevard

• Audit and optimize geometry for the Hollywood Boulevard map.
• Reseach geometry for the real Hollywood Boulevard location "6840 Hollywood Blvd, Hollywood, CA 90028, United States" and create an accurate representation of the building, neighboring structures and streets, building facades, buildings across the street and other relevant elements on the map.
• Research current imagery and references for Hollywood Boulevard to ensure the map reflects the real-world location accurately.
• Generate more accurate images using the python AI tools for reference and alignment with the real-world location, save to docs/screens/concepts/hollywood_boulevard/.
• Verify alignment with other docs/screens/concepts images of the Hollywood Boulevard map.
• Remove unnecessary or hidden geometry to improve performance.
• Ensure texture and material consistency across the map.

Map 2 — Joke Shop

• Audit and optimize geometry for the Joke Shop map.
• Research geometry for the real Joke Shop location "8433 Sunset Blvd, West Hollywood, CA 90069, United States" and create an accurate representation of the building, neighboring structures and streets, building facades, buildings across the street and other relevant elements on the map.
• Research current imagery and references for the Joke Shop to ensure the map reflects the real-world location accurately.
• Generate more accurate images using the python AI tools for reference and alignment with the real-world location, save to docs/screens/concepts/joke_shop/.
• Verify alignment with other docs/screens/concepts images of the Joke Shop.
• Remove unnecessary or hidden geometry to improve performance.
• Ensure texture and material consistency across the map.

Scenery Change (Day/Night) for Hollywood Boulevard

• Capture reference images for Hollywood Boulevard during the day and night.
• Adjust lighting and environmental settings to match the day/night cycle.
• Verify that all textures and materials respond correctly to the lighting changes.
• Ensure that any dynamic elements (e.g., streetlights, signs) behave appropriately for the time of day.
• Test performance and visual consistency for both day and night scenarios.
• Offer the day map and the night map as distinct scenarios in the game menu when selecting a location.

Patch 0.9.6 — 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.10.0 release candidate.
• Exit: combined build is functionally green, visually reviewed, performance measured and ready for the 0.10.0 content-lock/playtest phase.

Milestone 0.10.0 — 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.10.0; 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.10.0 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.10.0 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.