feat: reweight defense story and presenter notes

2026-07-13 07:55:34 +07:00
parent ab943deed5
commit 18c930449a
15 changed files with 703 additions and 172 deletions
@@ -0,0 +1,79 @@
+# 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.