Restructure the v1.0 roadmap around milestone sections

Promote every milestone to a level-2 section and expand 0.8.0 into detailed
workstreams for tutorial, campaign, content matrix, dialogue, debrief, save/
resume, difficulty/help and verification. Keep later milestones broad and
preserve the deferred realism/future lists.

TODO.md

@@ -6,18 +6,18 @@ see `AGENTS.md` for the workflow and `MEMORY.md` for the decisions behind these
 ## Gap Analysis and v1.0.0 Roadmap
 
 Baseline: **v0.7.2** (2026-11-01). Three playable venues, a complete escalation/access/radio
-loop, shift review, Blender character/gear/prop library, 231 headless + 94 Python tests, a
-13/13 clean screen-design judge and an optional Forward+ Desktop HQ build. This baseline is a
-strong vertical slice, not yet a 1.0 product.
+loop, shift review, a Blender character/gear/prop library, 231 headless + 94 Python tests, a
+13/13 clean screen-design judge and an optional Forward+ Desktop HQ build. This is a strong
+vertical slice, not yet a 1.0 product.
 
 ### Documentation audit (completed 2026-11-01)
 
-- [x] Make `docs/architecture.md` the single architecture source: added the asset/content
-      pipeline contracts, runtime venue-switch/fallback flows, deployment/version constraints,
-      quality requirements, risk register and a documentation ownership map.
+- [x] 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.
 - [x] 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` now link to architecture rather than acting as parallel sources.
+      `docs/smoke-checklist.md` link to architecture rather than acting as parallel sources.
 - [x] 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.
 - [x] Resolve stale claims: README release version/download row, development status
@@ -31,43 +31,144 @@ strong vertical slice, not yet a 1.0 product.
 
 | Area | Current baseline | Gap to 1.0 | Risk | Milestone |
 | --- | --- | --- | --- | --- |
-| First-hour experience | Venue menu and controls exist; no tutorial | No guided first shift, control coaching, objective recap or "what went wrong" debrief | New players bounce before the de-escalation loop lands | 0.8 |
-| Campaign/progression | Venue selection and debug cycle | No career/venue order, unlocks, difficulty curve or persistent player progression | Shift loop feels like a tech demo rather than a game | 0.8 |
-| Authored content | 3 venues, small event pools, one-line dialogue | Need a larger event matrix per venue, repeat/remix rules, failure/recovery events and more NPC dialogue | Repetition after a few shifts | 0.8 |
-| NPC behavior | FSM intents, reactions, crowd/theater poses | Deeper negotiation, memory of earlier interactions, group dynamics, believable refusal/escalation edges | NPCs still feel deterministic/scripted | 0.8 |
-| Access/evaluation | Recognition, wristbands/IDs/tickets/credentials, reputation/review | Fairness tuning, ambiguous cases, clearer evidence trail, richer grades and actionable feedback | Players cannot learn why a decision scored poorly | 0.8 |
-| Shift lifecycle | Settings + completed-shift history persist | No mid-shift save/resume, pause-safe serialization, versioned save schema or replay | Interrupted sessions lose the run; future changes can break saves | 0.8 |
-| Accessibility | Key remapping, gamepad, HUD font scale, shape escalation cue | Subtitles/captions, colour-independent cues, motion/audio sensitivity, text expansion, menu narration and full input alternatives need an audit | Public 1.0 cannot claim accessible play | 0.8–0.9 |
-| Localization | English strings in `content/strings.en.json` | String extraction/coverage, pseudo-locale test, font fallback, text-length layout budgets and translator workflow | Text bugs and unsupported locales at release | 0.9 |
-| Audio | Procedural crowd bed and radio crackle | Music/ambience direction, event SFX, voice/VO decision, caption hooks and mix budgets | Scene can feel silent/placeholder | 0.9 |
-| Animation/presentation | Procedural poses, walk/idle theater, LOD impostor | More reaction/idle/negotiation poses, transitions, facial readability at portrait distance, camera-height decision | Cinematic close-ups expose the prototype layer | 0.9 |
-| Performance/platform | 16-NPC budget measured headlessly; Compatibility default; optional Vulkan HQ | Target hardware matrix, 24-NPC profiling, draw-call/memory budgets, Web/HQ parity and frame-time regression gates | Crowded studio or Web drops frames | 0.9 |
-| Content tooling | ScenarioFactory/.tres export, Blender manifest, asset audits | Schema validation, previews, event authoring workflow, reproducible asset rebuild notes and contributor onboarding | Content expansion becomes expensive/error-prone | 0.8–0.9 |
-| QA/CI | Headless suite, smokes, screenshot compare, model-aware judge | End-to-end shift automation, full venue matrix, CI Godot-version strategy, manual judge budget and release checklist automation | Regressions escape or CI becomes non-reproducible | 0.9 |
+| First-hour experience | Venue menu and controls exist; no tutorial | No guided first shift, control coaching, objective recap or "what went wrong" debrief | New players bounce before the de-escalation loop lands | 0.8.0 |
+| Campaign/progression | Venue selection and debug cycle | No career/venue order, unlocks, difficulty curve or persistent player progression | Shift loop feels like a tech demo rather than a game | 0.8.0 |
+| Authored content | 3 venues, small event pools, one-line dialogue | Need a larger event matrix per venue, repeat/remix rules, failure/recovery events and more NPC dialogue | Repetition after a few shifts | 0.8.0 |
+| NPC behavior | FSM intents, reactions, crowd/theater poses | Deeper negotiation, memory of earlier interactions, group dynamics, believable refusal/escalation edges | NPCs still feel deterministic/scripted | 0.8.0 |
+| Access/evaluation | Recognition, wristbands/IDs/tickets/credentials, reputation/review | Fairness tuning, ambiguous cases, clearer evidence trail, richer grades and actionable feedback | Players cannot learn why a decision scored poorly | 0.8.0 |
+| Shift lifecycle | Settings + completed-shift history persist | No mid-shift save/resume, pause-safe serialization, versioned save schema or replay | Interrupted sessions lose the run; future changes can break saves | 0.8.0 |
+| Accessibility | Key remapping, gamepad, HUD font scale, shape escalation cue | Subtitles/captions, colour-independent cues, motion/audio sensitivity, text expansion, menu narration and full input alternatives need an audit | Public 1.0 cannot claim accessible play | 0.8.0–0.9.0 |
+| Localization | English strings in `content/strings.en.json` | String extraction/coverage, pseudo-locale test, font fallback, text-length layout budgets and translator workflow | Text bugs and unsupported locales at release | 0.9.0 |
+| Audio | Procedural crowd bed and radio crackle | Music/ambience direction, event SFX, voice/VO decision, caption hooks and mix budgets | Scene can feel silent/placeholder | 0.9.0 |
+| Animation/presentation | Procedural poses, walk/idle theater, LOD impostor | More reaction/idle/negotiation poses, transitions, facial readability at portrait distance, camera-height decision | Cinematic close-ups expose the prototype layer | 0.9.0 |
+| Performance/platform | 16-NPC budget measured headlessly; Compatibility default; optional Vulkan HQ | Target hardware matrix, 24-NPC profiling, draw-call/memory budgets, Web/HQ parity and frame-time regression gates | Crowded studio or Web drops frames | 0.9.0 |
+| Content tooling | ScenarioFactory/.tres export, Blender manifest, asset audits | Schema validation, previews, event authoring workflow, reproducible asset rebuild notes and contributor onboarding | Content expansion becomes expensive/error-prone | 0.8.0–0.9.0 |
+| QA/CI | Headless suite, smokes, screenshot compare, model-aware judge | End-to-end shift automation, full venue matrix, CI Godot-version strategy, manual judge budget and release checklist automation | Regressions escape or CI becomes non-reproducible | 0.9.0 |
 | Release/legal | Tag-driven unsigned builds, Web zip, optional HQ | Signing/notarization, checksums, AI-asset provenance/licensing, credits, privacy/body-camera statement and storefront requirements | Public release blocked by trust/policy issues | 0.9.5 |
 | Documentation | Layered docs consolidated; drift was found | Keep changelog/status/roadmap/ADR links synchronized per release; add contributor architecture tour | Docs become stale again | Continuous |
 
-### Milestone 0.8.0 — First hour and content depth
+## Milestone 0.8.0 — First hour and content depth
 
-- [ ] Add a skippable first-shift tutorial: movement/look, focus, action wheel, access check,
-      warning, body camera, radio and shift review; teach by doing, not a wall of text.
-- [ ] Add a persistent campaign shell: venue order/unlocks, selected difficulty, shift summaries
-      and a clear "next shift" path. Keep debug venue cycling separate.
-- [ ] Add an objective/recap layer: current venue policy, shift phase and a post-incident recap of
-      what evidence was checked and why the outcome was judged fair/unfair.
-- [ ] Define a content matrix for each venue (routine, scripted, edge, recovery and rare-threat
-      events) and fill the largest holes; target meaningful variety across all four phases.
-- [ ] Expand NPC dialogue beyond one-line intent replies: refusal reasons, de-escalation responses,
-      recognition callbacks and group reactions, all localized and deterministic under seed.
-- [ ] Add mid-shift save/resume with a versioned schema and migration test; keep completed-shift
-      history and settings compatible.
-- [ ] Add difficulty/pacing options (spawn rate, tolerance, report strictness) without changing the
-      de-escalation-first rules; expose them in Settings with defaults matching the current build.
-- [ ] Add a new-player help overlay and a searchable controls reference distinct from the HUD legend.
-- [ ] Exit: a new player can complete a first shift without the README; each venue has enough
-      content for repeated shifts; save/resume survives restart; 0.8 test matrix is green.
+Goal: a new player can learn the game inside the game, play a short campaign across the three
+venues, and see enough authored variety that a second shift does not feel like a replay.
 
-### Milestone 0.9.0 — Production quality and platform readiness
+### 0.8.1 First-shift tutorial
+
+- [ ] Write the tutorial beat sheet: menu → movement/look → focus and target cycling → action
+      wheel → access inspection → polite direction → formal warning/body camera → radio →
+      shift review. Keep it to 6–8 beats and one safe, compliant NPC.
+- [ ] Add a tutorial state machine independent of the normal shift FSM. It must be skippable,
+      restartable and deterministic, and must not change the outcome of the live shift.
+- [ ] Add contextual prompts that advance on the performed action, not on a timer. Prompts must
+      not block normal input or repeat after the player has learned the control.
+- [ ] Stage a safe encounter with one compliant visitor; no emergency, threat or crowd panic in
+      the tutorial. Reuse the real inspection/wheel/radio panels rather than a fake UI.
+- [ ] Persist tutorial completion in settings and add a "Replay tutorial" entry to the help/settings
+      screen.
+- [ ] Add localized tutorial strings and caption-ready prompt hooks.
+- [ ] Add a headless tutorial-state test and a windowed smoke test covering skip, replay and
+      completion.
+
+### 0.8.2 Campaign and session shell
+
+- [ ] Define campaign data separately from `VenueScenario`: venue order, unlock conditions,
+      shift number, selected difficulty and completion state.
+- [ ] Add a campaign-select/continue screen that shows the next shift, venue, policy summary and
+      previous result; keep the existing debug venue cycle separate.
+- [ ] Add a "Continue shift" path with an explicit resume point; define whether resume restores
+      the exact paused shift or the last safe checkpoint.
+- [ ] Add a post-shift screen that names the next objective and offers retry, continue or return
+      to the menu. Do not silently reset progression on failure.
+- [ ] Persist campaign state and expose a reset-campaign action with confirmation.
+- [ ] Add deterministic tests for fresh campaign, resume, completed venue and failed/retried shift.
+
+### 0.8.3 Venue content matrix
+
+- [ ] Add a content matrix per venue with columns for phase, event kind (routine/scripted/edge/
+      recovery/threat), NPC type, intent, access artifact, expected escalation ceiling, failure/
+      recovery path and spawn weight.
+- [ ] Add a validation test that every event references an existing profile, location and phase;
+      reject duplicate IDs and unreachable waypoints at load time.
+- [ ] Expand each venue toward at least 12 authored events and 6 reusable routine variants,
+      covering all four shift phases; prioritize repeatable combinations over one-off set pieces.
+- [ ] Add a no-repeat rule and phase-aware weighting so consecutive shifts do not replay the same
+      scripted event, while rare threats remain genuinely rare.
+- [ ] Add recovery events after player mistakes: a refused authorized guest returns, a manager
+      intervention, a crowd-calming opportunity, or a second chance to explain a policy.
+- [ ] Add a content preview/debug list showing the next eligible events and why they were chosen.
+- [ ] Add tests for phase gating, no-repeat selection, recovery eligibility and event reachability.
+
+### 0.8.4 NPC dialogue and negotiation
+
+- [ ] Define a dialogue data format for intent-specific and context-specific lines: greeting,
+      refusal, de-escalation response, recognition callback, group reaction and resolution.
+- [ ] Expand `NpcProfile` dialogue beyond one-line replies and select lines deterministically from
+      seed, prior interaction and current escalation level; no runtime LLM dependency.
+- [ ] Wire Ask/Reason, polite direction, warning, blocking, recognition and inspection outcomes to
+      the new lines and log entries, with visible differences between comply, argue and refuse.
+- [ ] Add a small set of group reactions so nearby NPCs respond to a raised voice, a warning, a
+      responder or a crowd panic without every NPC speaking at once.
+- [ ] Add placeholder-safe localized strings and tests for deterministic selection, missing lines
+      and dialogue length in the HUD/log.
+- [ ] Run a short dialogue readability pass on the three venues and replace repeated phrases.
+
+### 0.8.5 Objective, policy and debrief layer
+
+- [ ] Add a compact venue-policy card (accepted artifacts, door rules, emergency threshold) that
+      is available from the help overlay and the shift-review screen.
+- [ ] Add an in-shift "current objective" line when the scenario phase changes, without turning
+      the HUD into a quest log.
+- [ ] After an incident, record and display the evidence checked, the chosen escalation level and
+      the reason the response was judged fair, weak or excessive.
+- [ ] Add a first-shift completion summary that explains the grade in plain language and points to
+      the specific decision(s) that mattered.
+- [ ] Add tests for policy-card content, debrief evidence ordering and unknown/missing evidence.
+
+### 0.8.6 Save, resume and settings
+
+- [ ] Define a versioned save schema covering settings, tutorial completion, campaign progress,
+      difficulty and resumable shift state; document what is deliberately not serialized.
+- [ ] Implement atomic writes, corruption detection and safe fallback to defaults or the last
+      completed shift; never overwrite a valid save with a partial one.
+- [ ] Add save migration from the current settings/shift-history format and a test fixture for the
+      previous schema.
+- [ ] Add mid-shift resume that restores RNG state, elapsed time, NPC/incident state and the door
+      state consistently; verify a resumed shift can reach its review.
+- [ ] Add persistence tests for fresh install, corrupt save, version migration, completed shift and
+      resumed shift.
+
+### 0.8.7 Difficulty, pacing and help
+
+- [ ] Add difficulty presets that only adjust spawn rate, tolerance, report strictness and event
+      weights; the de-escalation-first rules and emergency rarity must not change.
+- [ ] Expose difficulty in the campaign/settings UI with the current build as the default "normal"
+      preset and a clear description of each change.
+- [ ] Add a new-player help overlay separate from the HUD: controls, focus/wheel flow, access
+      evidence, body camera, radio and shift review.
+- [ ] Add a searchable/filterable controls reference and keep it synchronized with input bindings.
+- [ ] Add a readability pass for first-shift HUD density; hide advanced debug-only information by
+      default.
+- [ ] Add tests for difficulty defaults, settings persistence and help/controls coverage of every
+      named input action.
+
+### 0.8.8 Verification and exit criteria
+
+- [ ] Add headless tests for tutorial progression, campaign state, content-matrix validation,
+      dialogue selection, save migration and difficulty defaults.
+- [ ] Add windowed/headless smokes for a complete tutorial, a resumed shift, a campaign venue
+      transition and the help overlay.
+- [ ] Run a manual first-hour test with at least three people unfamiliar with the project; record
+      where they get stuck and fix P0/P1 onboarding issues before closing the milestone.
+- [ ] Re-run the full headless suite, Python tooling and smoke checklist; update
+      `docs/development-status.md`, architecture links, changelog and README where behavior changed.
+- [ ] Exit: a first-time player can complete the tutorial and a first real shift without external
+      documentation; each venue has a repeatable content matrix; save/resume survives restart;
+      the 0.8 test matrix is green.
+
+## Milestone 0.9.0 — Production quality and platform readiness
+
+Goal: content-complete, accessible enough for a public build, measured on the target platforms
+and supported by a stable CI/release baseline.
 
 - [ ] Animation/presentation pass: negotiation/reaction poses and transitions, readable faces in
       portrait, resolved camera height, and no coat/skirt leg clipping in normal movement.
@@ -86,7 +187,10 @@ strong vertical slice, not yet a 1.0 product.
 - [ ] Exit: production content is feature-complete, accessibility/localization acceptance criteria
       pass, target hardware matrix is measured, and no P0/P1 defect remains open.
 
-### Milestone 0.9.5 — Release candidate
+## Milestone 0.9.5 — Release candidate
+
+Goal: freeze content, prove it with external players, clear release/legal blockers and verify
+every distribution path.
 
 - [ ] Content lock and external playtest round (at least five first-time players); triage findings
       by severity and fix all P0/P1 issues.
@@ -102,7 +206,9 @@ strong vertical slice, not yet a 1.0 product.
 - [ ] Exit: release candidate passes the manual smoke checklist on every target; no release-blocking
       legal or platform issue remains.
 
-### Milestone 1.0.0 — Launch
+## 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.
@@ -114,7 +220,7 @@ strong vertical slice, not yet a 1.0 product.
       release artifacts where platform rules require it, and documentation synchronized with the
       build.
 
-### Explicit post-1.0 / non-blocking candidates
+## Post-1.0 / non-blocking candidates
 
 - [ ] Live 3D body-camera replay.
 - [ ] Additional venues or seasonal events.
@@ -122,7 +228,7 @@ strong vertical slice, not yet a 1.0 product.
 - [ ] 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
+## Roadmap dependencies and risks
 
 - Content volume is the largest schedule risk; tutorial and campaign work must not outrun the
       event/dialogue matrix.