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.6 (2026-11-03). 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, 272 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, 8,000/8,000 NPC cap	Thorough NPC silhouette/face/gear/pose/LOD optimization before visual QA	Close-up jank reduces perceived quality	Complete (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.94 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, the 0.9.3 UI polish, 0.9.4 NPC visual optimization, 0.9.5 texture refinement and 0.9.6 integration passes are complete (all moved to DONE.md). The 0.10.0 release candidate is next: content lock, external playtest, balance, save migration and release/legal sign-off. The source version is 0.10.0-rc.1; the v0.9.6 release is published.

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. (Frozen 2026-11-03 after the 0.9.6 integration checkpoint; this pass is limited to release reliability, accessibility, balance evidence and packaging.)
• Produce a release-candidate build with the tutorial, campaign, all three venues, Help, accessibility settings and checkpoint/resume enabled. (Clean worktree a9658ec built 0.10.0-rc.1: Linux 161.5 MB, Windows 197.2 MB, macOS 148.0 MB, Web 97.8 MB and HQ 241.6 MB. The Web/HQ archives include the credits, privacy, accessibility and known-limitations pages; SHA-256 manifests were written; the Linux and HQ binaries launched headless and the Web index/wasm/pck/docs returned HTTP 200. Not published because external playtest and legal approval remain open.)
• 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. (docs/balance-acceptance.md defines cohorts, denominators, 36 matrix cells, seeds, thresholds and matched emergency-first comparisons. Documentation verified; targets are not measured results.)
• 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. Include the type-derived _read_npc_truth() mismatch with observed threats/forced entry; use independently labelled behavior evidence, not the helper as its own oracle.
• 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. (Committed fixtures under src/test/fixtures/saves/; 9 migration/failure tests cover old settings/campaign/history, the 0.9.0 checkpoint, all three venue checkpoint round-trips, clean install, corrupt JSON and a blocked atomic replace. Suite is now 272 tests.)
• Test fresh install → tutorial → campaign → pause → quit → resume → review → next venue on an isolated user-data directory. (Tutorial and campaign smokes shared one isolated XDG_DATA_HOME; tutorial completion/replay/skip then campaign resume/review-continue/help both passed. Pause/menu behavior is covered by smoke_session_shell.gd.)
• Test corrupt JSON, partial temp files, missing optional fields and a failed atomic rename; confirm fallback behavior never destroys a valid save. (Corrupt/partial files fall back to defaults; a blocked temp path reports an error and leaves the prior valid settings intact. _load_json now uses the non-logging JSON instance parser.)
• Verify checkpoint resume after all three venues, after an incident, with NPCs at the door and with flashlight/body-camera/door state set. (The migration suite round-trips a checkpoint for Hollywood, the Joke Shop and the TV Studio with an open incident, one NPC row, flashlight/body-camera/door flags; the campaign smoke resumes a live checkpoint through the real GameManager.)
• Document save locations, schema versions, reset behavior and rollback/export instructions in docs/getting-started.md and the release notes. (getting-started.md now documents the four files, version-1 checkpoint, atomic write/fallback, clean install, reset and backup/rollback.)

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. (Clean worktree a9658ec built the five artifacts listed above; PUBLISH_DRY_RUN=1 produced and printed build/SHA256SUMS-0.10.0-rc.1.txt without touching the API.)
• Smoke-test fresh Linux portable/AppImage, Windows portable/installer, macOS unzip/launch, Web static hosting and Desktop HQ Vulkan fallback on the target matrix. (Linux portable and Desktop HQ launched headless; Web files served over a local static server with HTTP 200. AppImage/installer were not built locally and Windows/macOS launch testing still needs 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. (publish_release.sh checks artifact size/free space, writes SHA-256 checksums, supports PUBLISH_DRY_RUN, rolls back uploaded assets/new releases on failure, and offers opt-in RETAIN_RELEASES pruning; dry-run verified.)
• 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. (Source/version and tag are both 0.9.6; all seven published releases carry 5–7 assets, including the retained v0.8.0/v0.8.1/v0.9.0/v0.9.1 line. publish_release.sh documents opt-in RETAIN_RELEASES pruning and RELEASING.md describes the seven-release policy.)
• 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. (0.10.0 ships unsigned with quarantine instructions; signing/notarization remains an explicit public-release blocker in RELEASING.md and known-limitations.md.)

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. (CREDITS.md records the Blender/OpenRouter toolchain, default model slugs, missing per-file generation metadata and the commercial-rights review as an explicit release blocker.)
• Audit audio/SFX/music licensing (or confirm everything is procedural) and add a credits file. (All runtime audio is procedural; no external music/SFX files are bundled. CREDITS.md records this.)
• Review body-camera/privacy language, mental-health-crisis representation, age/content rating and storefront requirements; fix any release-blocking copy or content. (PRIVACY.md clarifies the simulated body camera/local-only data; the accessibility and known-limitations pages record the remaining mental-health/rating/storefront review as a release blocker rather than claiming approval.)
• Add the player-facing credits, known limitations, accessibility statement and privacy note to the release package/README. (README.md links CREDITS.md, PRIVACY.md, docs/accessibility.md and docs/known-limitations.md; the Web and Desktop HQ package builders copy those documents into the shipped archives.)
• 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.

Milestone 0.11.0 — NPC model variety

Goal: break the eight-character clone effect with four licence-cleared crowd-variety looks while keeping the frozen npc_base bone, tint-slot and gear-attach contract. The procedural generator is the primary path; Quaternius is a reviewed reference and MakeHuman is deferred to a separate local development pipeline. Start only after the 0.10.0 release candidate is published; this milestone must not delay the release.

0.11.1 Source review and decision

• Research free/open-source character sources and evaluate at least three downloads against the existing Blender contract. (Measured Quaternius CC0, Kenney CC0, Khronos CesiumMan/RiggedFigure CC-BY and the MakeHuman CC0 base mesh; none is a drop-in. Results, local preview sheet and SHA-256 provenance are in docs/npc-model-sourcing.md.)
• Review the sourcing research with the project owner and choose Option A (procedural), Option B (Quaternius CC0 intake) or Option C (MakeHuman/MPFB body pipeline); record the decision in an ADR and in MEMORY.md. (2026-11-03: extend the procedural generator as the primary path, keep Quaternius as a reviewed prototype/reference, defer MakeHuman to a separate local pipeline. Recorded in ADR-0015 and MEMORY.md.)
• Add a source licence allow-list and provenance rule: CC0 preferred, CC-BY only with attribution in CREDITS.md, and no service assets whose terms restrict redistribution. (ADR-0015; the CC-BY research previews are attributed in CREDITS.md.)
• Decide whether the external preview sheet stays local under tmp/ or is committed with the required CC-BY attribution. (Committed as docs/blender_previews/sheet_npc_sources_research.jpg with Cesium CC-BY attribution; the project-owned crowd prototype sheet is also committed.)

0.11.2 Intake and validation

• Add a Blender inspect path that imports a GLB, applies node transforms, reports tris/verts, bounds, bones, materials, UVs and skinning, and lists contract failures.
• Add an adapt path for future external assets: scale/ground, weld seams, decimate, map the five tint slots, and either rebuild the contract armature or record an explicit second-rig contract. The Quaternius prototype showed that a contract rebuild needs a proportion warp, so this is not on the 0.11.0 critical path.
• Keep tools/blender_assets.py audit as the single final gate; add a regression test for the intake report/adaptation using a deterministic synthetic or licence-cleared fixture.
• Document the adapter commands and the go/no-go checks in docs/asset-tooling.md.

0.11.3 One-character prototype

• Prototype one Quaternius CC0 variant: weld/decimate to budget and capture Idle/Walk renders. (12,518 imported verts -> 3,199 after weld -> 2,423 / 4,654 tris after a 0.75 decimate; Idle/Walk quality is good. Preview in docs/blender_previews/sheet_npc_sources_research.jpg.)
• Measure the prototype against the npc_casual controls: silhouette, rest pose, body proportions and gear fit. (No-go for a contract rebuild: T-pose 62-bone realistic rig, ~0.96 m hip, ~1.68 m arm span and ~0.153 m shoulder joint do not match the arm-down 13-bone contract. Keep as reference; a second rig/animation path needs its own ADR.)
• Make a go/no-go decision on Option B. (No-go for 0.11.0; proceed with the procedural generator and keep Quaternius as a visual/style reference.)

0.11.4 Roster and runtime

• Approve four crowd-variety looks (build, head silhouette, hair/beard, outer layer and accessory; no clothing that labels the NPC's behaviour). (npc_crowd_a bun/slim/sunglasses, npc_crowd_b bald/broad/beard/shoulder bag, npc_crowd_c coat/umbrella, npc_crowd_d hood/cup; prototype sheet committed.)
• Add the four approved specs to CHARACTERS, build and commit their GLBs/AO maps, and update the manifest with roles and tint data. (Prototype assets are local under tmp/; do not add them to the 0.10.0 release candidate.)
• Replace the fixed character_model_for() mapping with deterministic per-role pools and add tests for repeatability and duplicate avoidance.
• Rebuild and verify gear fit for every new variant (blender_assets.py fit plus the runtime gear checks).

0.11.5 QA and release

• Run the 24-NPC budget smoke, portrait baseline, gear fit, headless suite and a release build with the expanded library.
• Update CREDITS.md, docs/development-status.md, docs/npc-visual-review.md and CHANGELOG.md; record any accepted visual limits.
• Exit: a reviewed 12-character library passes contract audit, portrait/gear acceptance, the 24-NPC budget and licence/provenance review without changing the runtime contract.

0.11.6 Deferred MakeHuman local pipeline

• Evaluate the MakeHuman CC0 base mesh for a later separate local development pipeline. (19,158 verts / 36,972 tris; scaled to 1.82 m; decimate 0.35 -> 3,780 verts / 6,468 tris; UVs present, no normals/material groups/rig. Feasible only with retopology, a custom rig and project-owned clothing; keep out of CI/build.)
• Decide whether body-shape diversity still matters after the 12-character library lands; if yes, prototype the local MPFB/MakeHuman pipeline outside the repo and commit only the final CC0-derived assets with provenance.

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.