# Defense story reweighting implementation plan

> **For agentic workers:** Use subagent-driven development or execute this plan task by task. Follow TDD and request an independent review before completion.

**Goal:** Reweight the 14-scene defense around the thesis contribution, reduce the must-say speech to 750-850 words, and create one structured source for future presenter notes.

**Architecture:** Keep `storyboard.ts` as the audience route and visual catalog. Add a separate typed presenter-note catalog keyed by scene and beat. The catalog owns speech, timing, evidence, warnings, fallback wording, and Q&A links. Audience components must not render presenter-only content.

**Tech stack:** React 19, TypeScript, Vitest, existing presentation state and storyboard models.

## Constraints

- Preserve 14 scenes and current route order.
- Do not add another demo scene.
- Treat Scene 5 as vocabulary and Scene 9 as evidence.
- Describe the later issue-review workflow as an implementation extension, not the thesis's three-node report case study.
- Do not claim production approval, scheduling, broad model performance, arbitrary crash recovery, or live Scene 10-12 rehearsal.
- Submitted replay may use same-run wording. Revision replay must be labeled as a separate prepared recording.
- Keep the main speech between 750 and 850 words, excluding optional notes and Q&A.

## Task 1: Define the presenter-note contract

**Files:**
- Create: `web/apps/console/src/presentation/presenter/presenter-notes.ts`
- Create: `web/apps/console/src/presentation/presenter/presenter-notes.test.ts`
- Read: `docs/runbooks/defense-speech-and-claim-audit.md`

- [x] Define `PresenterBeatNote` with `sceneId`, `beatId`, `targetSeconds`, `mustSay`, `optionalDetail`, `warning`, `fallback`, `evidencePointers`, and `qnaBranchIds`.
- [x] Use explicit nullable fields rather than empty placeholder strings.
- [x] Add helpers for route lookup, scene totals, complete-deck totals, and main-speech word count.
- [x] Test that every storyboard beat has exactly one note, no stale note exists, total target time is at most 780 seconds, and must-say text is 750-850 words.
- [x] Test that every evidence pointer is non-empty and every Q&A ID resolves through `discussionBranchForId`.

Troubleshooting: derive route completeness from `mainScenes`; do not maintain a second route array.

## Task 2: Reweight the speech and scene transitions

**Files:**
- Modify: `web/apps/console/src/presentation/presenter/presenter-notes.ts`
- Modify: `web/apps/console/src/presentation/storyboard.ts`
- Modify: `docs/runbooks/defense-speech-and-claim-audit.md`
- Modify: `docs/runbooks/presentation-rehearsal-matrix.md`
- Test: `web/apps/console/src/presentation/storyboard.test.ts`
- Test: `web/apps/console/src/presentation/presenter/presenter-notes.test.ts`

- [x] Allocate the target time as: Scenes 1-2 90s, Scene 3 45s, Scenes 4-7 195s, Scenes 8-12 180s, Scene 13 120s, Scene 14 75s, and 75s navigation buffer.
- [x] Keep one must-say paragraph per scene. Beat notes after the first should contain only the sentence needed for the visual change.
- [x] Compress Scene 5 to definitions; move the applied lifecycle explanation to Scene 9.
- [x] Give Scene 13 two minutes and include 27 pass, 8 invalid, 1 fail, author audit, changing snapshots, and non-benchmark wording.
- [x] Name the five thesis contributions across Scenes 1, 4, 5, 7, and 13 without reading a five-item list.
- [x] Keep stateful MCP session reuse and the operation/repair/instruction-layer distinction as optional notes or Q&A, not main-path additions.
- [x] Update the Markdown speech so its must-say version matches the typed catalog.

## Task 3: Correct known factual presentation defects

**Files:**
- Modify: `web/apps/console/src/presentation/authoring/authoring-recording.ts`
- Modify: affected authoring tests
- Modify: `web/apps/console/src/presentation/GuidedProductMoment.tsx`
- Modify: affected guided-moment tests
- Modify: `docs/runbooks/defense-presentation.md`
- Modify: `docs/runbooks/defense-qna.md`

- [x] Verify displayed operation labels against the registered JSON-RPC methods. Keep valid `workflow.draft_workspaces.*` labels and avoid inventing shorter aliases for workspace operations.
- [x] Preserve the factual configured source ID `local.lda_docs`.
- [x] Remove unconditional same-run wording from any revision-requested presentation state.
- [x] State that the decision is a typed interrupt/resume contract, not a production approval gate.
- [x] Update replay fallback answers so they distinguish recorded product evidence from rehearsed live evidence.
- [x] Replace stale future-work answers that list already-built presentation UI as the next product priority.

## Task 4: Verify and document

- [x] Run focused storyboard, presenter-note, authoring, guided-moment, and Q&A tests.
- [x] Run `pnpm --dir web typecheck` and `pnpm --dir web build`.
- [x] Run `uv run pytest tests/docs -q`.
- [x] Review the 14-scene route matrix against the final note catalog.
- [x] Update `docs/current_roadmap.md`, archive this plan, and commit the slice.

**Completion gate:** A presenter can read only `mustSay` fields and deliver the argument in under 13 minutes without unsupported claims.