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 0.x Roadmap

Baseline: v0.9.3 (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, 262 headless + 101 Python tests, a 21/21 clean screen-design judge and an optional Forward+ Desktop HQ build. This is a strong release-candidate foundation, not yet a 0.10.0 release candidate.

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

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 the release candidate	0.10.0
Dialog/UI	Audited terminology, copy, button states, focus/navigation, modal close, long strings and all 21 screen captures	Keep the capture/compare/judge gate current as content changes	Low; the remaining risk is drift after new UI is added	Complete (0.9.3)
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.4
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 release cannot claim accessible play	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.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.6 / 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, 21/21 judge	Release-candidate smoke matrix, final gallery and release dry run	Regressions escape the release gate	0.9.6 / 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.6 / 0.10.0
Future 0.x	Stable 0.x feature set	Live replay, more venues, VO/music, image-to-mesh props and seasonal content	Scope creep before release	0.11.0+

Current priority: map optimization, the pre-build NPC revisit and the 0.9.3 UI polish pass are complete (all moved to DONE.md on 2026-11-02). 0.9.4 NPC-detail is active; 0.9.5 texture refinement, 0.9.6 integration and the 0.10.0 release candidate are queued. The source version is now 0.9.3; no release build or tag has been produced for it.

Patch 0.9.4 — 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. (capture_npc_baseline.gd produces 48 frames; sheet_npc_baseline.jpg is committed.)
• Define acceptance criteria for proportions, face readability, hair, hands, shoes, clothing silhouette, gear fit and animation at the gameplay camera height (1.7 m). (Eight criteria in docs/npc-visual-review.md; the current 8,000-triangle/8,000-vertex library contract is explicit; the npc_base fallback remains 6,000/4,000.)
• Record the camera/lighting/background used for comparison so model changes can be judged consistently; keep the existing portrait capture path deterministic. (Neutral studio, fixed orbit cameras, no HUD/crowd/animation; commands recorded in docs/npc-visual-review.md.)
• 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. (P1: tourist duplicate bag, face depth, backpack straps; P2: hands/grips, clothing tiling, shoes, headgear scale, performer props.)
• Publish a before/after NPC comparison sheet for review before changing the library. (sheet_npc_baseline.jpg is the before artifact; tools/npc_baseline.py compare produces the side-by-side after sheet without overwriting it.)

Completed 2026-11-02: 48-frame neutral studio baseline, eight criteria, current fit and triangle/vertex measurements, and ranked P1/P2 gaps are in docs/npc-visual-review.md. The baseline itself changed no character models; the first P1 gear fixes are recorded under Gear and equipment fit.

Body proportions and silhouette

• Raise the per-character library cap from 6,000/5,000 to 8,000 triangles / 8,000 glTF vertices so face, hand-grip and clothing detail is not forced to replace geometry. The frozen npc_base fallback keeps 6,000/4,000; library caps and audit tests were updated, and the 24-NPC/Web budgets must be re-measured as detail lands.

• 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. (tools/npc_proportions.py + docs/npc-proportion-audit.md: all eight pass; no skeleton or mesh rescue was needed. Head and broad-build silhouettes are nearest their upper bounds.)

• Improve the neck and shoulder transition so the silhouette reads as one body rather than a thin post on a hanger. (Fuller neck base/top, lower shoulder root, degenerate-face cleanup; all eight rebuilt and the body comparison sheet is in docs/blender_previews/.)

• Improve the torso and hip transition; preserve the existing broad/slim/average build variations. (Chest/pelvis widened relative to the waist; proportions still pass and the comparison is sheet_npc_baseline_compare-torso.jpg.)

• 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. (Chin plate and cheekbones sculpted into the head mesh; no separate jaw/cheek spheres or AO intersection rings.)
• Improve brow/eye-socket depth and eyelid/iris readability without turning the low-poly face into a noisy mesh. (Recessed sclera, thin upper lid; sheet_npc_baseline_compare-face.jpg.)
• Refine the nose bridge/tip, lips and ear shape; keep the five tint slots and face direction unchanged.
• 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. (Wider palm, two-segment bent fingers with rounded tips, separate thumb; optional --view=hand capture and sheet_npc_hands_compare.jpg.)
• Fix grip alignment for phone, cup, clipboard, camera, sign, flashlight, wand and radio against the new palm/finger geometry. (Several props still occlude the palm or float beside it in the hand capture.)
• 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.
• Hide the tourist's photo-pose camera bag outside photo/film poses; it duplicated the backpack silhouette. (photo_prop_visible_for_pose() plus regression test.)
• Refit the backpack straps as flattened bands that follow the torso instead of rods partly buried in the chest; rebuild the GLB, bake AO and confirm in the before/after sheet.
• Re-fit shoulder bag and SCBA tank against the revised torso/hips; fix remaining 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.

Postponed — Patch 0.9.5 — 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.

Postponed — 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.6 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.

Postponed — 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 minor release after the 0.9.x patch line.

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-0.10 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 future release 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 the 0.10.0 release 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-0.10 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 0.10.0 release candidate.

Future 0.x / 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.