docs: plan audited defense presentation follow-ups
This commit is contained in:
@@ -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`
|
||||
|
||||
- [ ] Define `PresenterBeatNote` with `sceneId`, `beatId`, `targetSeconds`, `mustSay`, `optionalDetail`, `warning`, `fallback`, `evidencePointers`, and `qnaBranchIds`.
|
||||
- [ ] Use explicit nullable fields rather than empty placeholder strings.
|
||||
- [ ] Add helpers for route lookup, scene totals, complete-deck totals, and main-speech word count.
|
||||
- [ ] 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.
|
||||
- [ ] 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`
|
||||
|
||||
- [ ] 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.
|
||||
- [ ] Keep one must-say paragraph per scene. Beat notes after the first should contain only the sentence needed for the visual change.
|
||||
- [ ] Compress Scene 5 to definitions; move the applied lifecycle explanation to Scene 9.
|
||||
- [ ] Give Scene 13 two minutes and include 27 pass, 8 invalid, 1 fail, author audit, changing snapshots, and non-benchmark wording.
|
||||
- [ ] Name the five thesis contributions across Scenes 1, 4, 5, 7, and 13 without reading a five-item list.
|
||||
- [ ] Keep stateful MCP session reuse and the operation/repair/instruction-layer distinction as optional notes or Q&A, not main-path additions.
|
||||
- [ ] 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`
|
||||
|
||||
- [ ] Replace stale `workflow.draft_workspaces.*` labels with the actual `workflow.drafts.*` namespace, or label composite CLI actions without pretending they map to one JSON-RPC method.
|
||||
- [ ] Preserve the factual configured source ID `local.lda_docs`.
|
||||
- [ ] Remove unconditional same-run wording from any revision-requested presentation state.
|
||||
- [ ] State that the decision is a typed interrupt/resume contract, not a production approval gate.
|
||||
- [ ] Update replay fallback answers so they distinguish recorded product evidence from rehearsed live evidence.
|
||||
- [ ] Replace stale future-work answers that list already-built presentation UI as the next product priority.
|
||||
|
||||
## Task 4: Verify and document
|
||||
|
||||
- [ ] Run focused storyboard, presenter-note, authoring, guided-moment, and Q&A tests.
|
||||
- [ ] Run `pnpm --dir web typecheck` and `pnpm --dir web build`.
|
||||
- [ ] Run `uv run pytest tests/docs -q`.
|
||||
- [ ] Review the 14-scene route matrix against the final note catalog.
|
||||
- [ ] 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.
|
||||
@@ -0,0 +1,75 @@
|
||||
# Read-only presenter route implementation plan
|
||||
|
||||
> **Dependency:** Execute after the story reweighting and Scenes 3-6 choreography plans.
|
||||
|
||||
**Goal:** Add a calm, readable `/presenter` route containing the current speech, evidence, warnings, fallbacks, and Q&A without controlling or synchronizing `/present`.
|
||||
|
||||
**Architecture:** `/presenter` reads the typed presenter-note catalog and existing storyboard/Q&A definitions. It owns no presentation state, RPC calls, replay state, BroadcastChannel, or remote-control behavior. Hash navigation selects a note inside `/presenter`; links may open the matching `/present` route in another tab.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Read-only first. No cross-window or cross-machine synchronization.
|
||||
- Do not duplicate speech or Q&A strings in React components.
|
||||
- Remove presenter-only comments and dead markup from audience components.
|
||||
- Optimize for a tired presenter on a 1080p laptop: large type, short lines, stable regions, minimal chrome.
|
||||
- Preserve `/`, `/console`, and `/present` behavior.
|
||||
|
||||
## Task 1: Add route and presenter navigation model
|
||||
|
||||
**Files:**
|
||||
- Create: `web/apps/console/src/presentation/presenter/presenter-navigation.ts`
|
||||
- Create: associated tests
|
||||
- Create: `web/apps/console/src/presentation/presenter/PresenterRoute.tsx`
|
||||
- Modify: `web/apps/console/src/app/AppRoutes.tsx`
|
||||
- Modify: route tests
|
||||
|
||||
- [ ] Add `/presenter` without redirecting existing routes.
|
||||
- [ ] Support `#scene/<scene>/<beat>` and `#discuss/<branch>` inside the presenter route using the existing route vocabulary.
|
||||
- [ ] Invalid hashes fail closed to the first presenter note.
|
||||
- [ ] Expose previous, current, and next note metadata without mutating `/present`.
|
||||
- [ ] Provide an “Open audience slide” link targeting the corresponding `/present#scene/...` route.
|
||||
|
||||
## Task 2: Build the reading layout
|
||||
|
||||
**Files:**
|
||||
- Create: `PresenterShell.tsx`, `PresenterNote.tsx`, `PresenterSidebar.tsx`, and `presenter.css`
|
||||
- Create component tests
|
||||
|
||||
- [ ] Use a restrained two-column layout: compact scene index and a 60-72 character reading column.
|
||||
- [ ] Show scene/beat, elapsed target, current must-say text, optional detail, claim warning, fallback, evidence pointers, and linked Q&A.
|
||||
- [ ] Place the next beat preview below the current note, not beside it.
|
||||
- [ ] Collapse optional detail, evidence, and Q&A by default using accessible disclosure controls.
|
||||
- [ ] Typeset must-say text at 20-24px with at least 1.5 line height.
|
||||
- [ ] Use distinct but quiet treatments for `Say`, `Optional`, `Warning`, `Fallback`, and `Evidence`; avoid dashboard cards around every paragraph.
|
||||
- [ ] Add a print stylesheet that produces a readable speech outline.
|
||||
|
||||
## Task 3: Move presenter-only discussion content out of the audience panel
|
||||
|
||||
**Files:**
|
||||
- Modify: `web/apps/console/src/presentation/DiscussionPanel.tsx`
|
||||
- Modify: `web/apps/console/src/presentation/DiscussionPanel.test.tsx`
|
||||
- Modify: presenter Q&A components and tests
|
||||
|
||||
- [ ] Delete the commented `speakerHint` block from `DiscussionPanel.tsx`.
|
||||
- [ ] Render `speakerHint` only in `/presenter` as presenter guidance.
|
||||
- [ ] Keep the audience discussion panel limited to question, answer, context, and evidence.
|
||||
- [ ] Verify every prioritized Q&A branch has a short answer and evidence pointer; show missing expanded answers as absent, not placeholders.
|
||||
|
||||
## Task 4: Add static timing and rehearsal affordances
|
||||
|
||||
- [ ] Show target time per note and cumulative target time.
|
||||
- [ ] Add a local-only manual “mark covered” checkbox state if it can remain component-local; do not persist or synchronize it in this slice.
|
||||
- [ ] Add keyboard navigation within `/presenter` only, with a visible help summary.
|
||||
- [ ] Do not add an automatic timer until presenter behavior is rehearsed.
|
||||
|
||||
## Task 5: Verification and documentation
|
||||
|
||||
- [ ] Test route isolation, hash parsing, note completeness, Q&A rendering, keyboard navigation, and audience links.
|
||||
- [ ] Run React Doctor after focused tests.
|
||||
- [ ] Run full console tests, typecheck, and build.
|
||||
- [ ] Capture `/presenter` at `1920x1080`, `1280x720`, and `1024x768`.
|
||||
- [ ] Confirm no audience-only RPC or replay effects run on `/presenter`.
|
||||
- [ ] Update `web/README.md`, `docs/runbooks/defense-presentation.md`, and `docs/current_roadmap.md`.
|
||||
- [ ] Archive this plan and commit.
|
||||
|
||||
**Completion gate:** `/presenter` is usable as a standalone rehearsal and defense aid, while `/present` remains unchanged and audience-clean.
|
||||
@@ -0,0 +1,135 @@
|
||||
# Interactive graphs and Scenes 3-6 choreography implementation plan
|
||||
|
||||
> **Dependency:** Execute after `2026-07-13-defense-story-reweighting.md`.
|
||||
|
||||
**Goal:** Give Scenes 3-5 restrained beat-to-beat motion, rebuild Scene 6 as a readable interactive architecture explorer, and improve the long prepared-run graph and its node inspector without adding unsupported evidence.
|
||||
|
||||
**Architecture:** Reuse the editorial canvas, Motion dependency, and React Flow figure system. Scene 6 keeps semantic zoom, but each subsystem uses the topology that explains it: layered overview, fan-in client surface, branched core loop, provider grouping, or NodeUse sequence. The prepared-run graph remains visible when its node inspector opens. Do not force every relationship into a horizontal chain.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Keep one editorial light theme and remove non-demo blue dominance.
|
||||
- Preserve simultaneous visibility for comparisons that require it.
|
||||
- Use existing CSS tokens and icons.
|
||||
- Respect `prefers-reduced-motion` and the presentation motion-disabled state.
|
||||
- Do not add hand-positioned connectors or a second graph renderer.
|
||||
- Use React Flow pan, zoom, fit-view, and layout inputs rather than CSS scaling around the graph.
|
||||
- Use icons and conventional state/flow shapes where they improve scanning; do not render every node as the same rounded rectangle.
|
||||
- Keep graph labels at least 18px at `1280x720`; prefer 20-22px for active nodes.
|
||||
- Keep the current scene IDs and deep-link behavior unless a migration updates every live reference and test.
|
||||
|
||||
## Task 1: Pin visual contracts before restyling
|
||||
|
||||
**Files:**
|
||||
- Modify tests for `PositioningScene`, `BoundaryScene`, `LifecycleScene`, and `ArchitectureScene`
|
||||
- Modify route tests for Scenes 3-6
|
||||
|
||||
- [ ] Assert one primary visual region per beat through `data-visual-role="primary"`.
|
||||
- [ ] Assert reduced-motion behavior and stable accessible headings.
|
||||
- [ ] Assert Scene 6 exposes public surface, kernel loop, state/trace/routing, and provider boundary concepts across its four beats.
|
||||
- [ ] Assert architecture figures declare a topology appropriate to their subject rather than four repeated linear flows.
|
||||
- [ ] Assert the prepared-run graph preserves ten displayed action/boundary/outcome nodes, readable labels, pan/zoom, and a factual node inspector.
|
||||
- [ ] Capture baseline screenshots at `1280x720` and `1024x768` before implementation.
|
||||
|
||||
## Task 2: Add restrained motion to Scene 3 positioning
|
||||
|
||||
**Files:**
|
||||
- Modify: positioning scene component in `SceneBody.tsx` or extract a focused module
|
||||
- Modify: `presentation.css`
|
||||
- Modify: focused tests
|
||||
|
||||
- [ ] Keep the existing information architecture and add one shared layout transition between the two beats.
|
||||
- [ ] On `landscape`, keep the related-system map as the complete comparison.
|
||||
- [ ] On `lda-position`, enlarge the typed-substrate position and shift the surrounding systems enough to make the focus obvious without hiding the comparison axis.
|
||||
- [ ] Use position and scale before opacity; one clear transform is enough.
|
||||
- [ ] Keep titles, category labels, and evidence readable at both target viewports.
|
||||
|
||||
## Task 3: Add restrained motion to Scene 4 planner/runtime ownership
|
||||
|
||||
- [ ] Preserve the current three-pane comparison.
|
||||
- [ ] On `planner`, enlarge the planner pane while retaining runtime destination context.
|
||||
- [ ] On `runtime`, let the runtime pane grow into the released space.
|
||||
- [ ] On `boundary`, restore both sides and enlarge the typed CLI/JSON-RPC seam.
|
||||
- [ ] Animate position and width between states; do not change color theme between beats.
|
||||
- [ ] Keep the spoken claim exact: planner proposes; runtime owns validation, state, execution, trace, and explicit resume.
|
||||
|
||||
## Task 4: Add restrained motion to Scene 5 lifecycle vocabulary
|
||||
|
||||
- [ ] Preserve the four-record lifecycle rail and its order.
|
||||
- [ ] For each beat, grow the active record into the available space while the other records compress but remain readable.
|
||||
- [ ] Keep arrows and order visible so the audience does not mistake the records for independent cards.
|
||||
- [ ] Show raw-plan-to-artifact as optional visual evidence without implying Draft is mandatory.
|
||||
- [ ] Avoid replaying the prepared example; Scene 9 owns applied evidence.
|
||||
|
||||
## Task 5: Rebuild Scene 6 as an interactive semantic zoom
|
||||
|
||||
**Files:**
|
||||
- Modify: `web/apps/console/src/presentation/scenes/ArchitectureScene.tsx`
|
||||
- Modify: `web/apps/console/src/presentation/figures/architecture-catalog.ts`
|
||||
- Modify: `web/apps/console/src/presentation/figures/model.ts`
|
||||
- Modify: `web/apps/console/src/presentation/figures/layout.ts`
|
||||
- Modify: `web/apps/console/src/presentation/figures/InteractiveFigure.tsx` only if required by an existing figure contract
|
||||
- Modify: associated tests and CSS
|
||||
|
||||
- [ ] Base the root figure on the thesis Architecture Spine, not an invented package map: workflow owner and external agent enter through CLI/JSON-RPC, `WorkflowServer` composes the API, records, inventory, and `wf_core`, then status/output/trace return through the public surface.
|
||||
- [ ] Keep providers as one compact input into capability inventory at the root. Provider-family detail is optional drill-down, not one quarter of the main architecture story.
|
||||
- [ ] Keep click-to-focus and breadcrumb navigation. A node with `childFigureId` zooms into its subsystem; a leaf node opens evidence/details without replacing the whole figure.
|
||||
- [ ] Give the client surface a fan-in topology, with human/external agent clients and the web console converging on CLI or JSON-RPC and then WorkflowApi.
|
||||
- [ ] Give the WorkflowApi zoom a lifecycle-operation surface: capabilities, drafts, artifacts, deployments, and runs surrounding the API boundary. Use compact HTML operation receipts or method groups inside graph nodes when they communicate more than another label box.
|
||||
- [ ] Add a core-runtime child figure based on the thesis flowchart at `system-design-implementation.md:626`: select frame, branch by step kind, trace and route loop, interrupt/resume branch, and terminal output.
|
||||
- [ ] Represent node, condition, foreach, join, subgraph, interrupt, and end with icons or conventional shapes. Explicitly exclude general fork/gather.
|
||||
- [ ] Make `NodeUse` inside the core loop clickable. Its child figure follows the thesis sequence diagram: Runtime, Binding Resolver, NodeDef Handler, State Reducers, and Trace Store. Use participant lanes, message arrows, and small factual state/result panels instead of six identical nodes.
|
||||
- [ ] Allow further click-through from important core nodes where useful: interrupt opens request/resume contract evidence; trace opens a representative trace frame; step dispatch opens the supported-step palette. Do not create drill-down merely because a node exists.
|
||||
- [ ] Group built-in, MCP, and Python providers around the provider-neutral capability boundary; do not connect source families as an arbitrary adjacency chain.
|
||||
- [ ] Use larger labels and summaries, and allow user pan/zoom instead of shrinking the full graph until it fits.
|
||||
- [ ] Qualify determinism in visible copy: core semantics are deterministic for fixed definitions and handler results.
|
||||
- [ ] Keep React Flow as the one interactive graph system. Extend its layout model with named topologies or rank/position hints instead of manually drawing edge coordinates.
|
||||
|
||||
### Scene 6 figure hierarchy
|
||||
|
||||
Implement and test this hierarchy before polishing individual nodes:
|
||||
|
||||
```text
|
||||
Architecture spine
|
||||
├─ Front door and transport
|
||||
├─ Workflow API operations
|
||||
├─ WorkflowServer composition
|
||||
├─ wf_core execution loop
|
||||
│ ├─ Supported step kinds
|
||||
│ ├─ NodeUse sequence
|
||||
│ ├─ Typed interrupt contract
|
||||
│ └─ Trace frame evidence
|
||||
├─ Lifecycle records
|
||||
└─ Capability inventory
|
||||
└─ Built-in / MCP / Python providers
|
||||
```
|
||||
|
||||
The four scripted beats need not visit every child. The audience path should be root architecture, public/API boundary, `wf_core` loop, then NodeUse execution. The remaining children exist for interaction and Q&A.
|
||||
|
||||
## Task 6: Improve the prepared-run graph and node inspector
|
||||
|
||||
**Files:**
|
||||
- Modify: `web/apps/console/src/presentation/WorkflowGraphStage.tsx`
|
||||
- Modify: `web/apps/console/src/presentation/NodeSpotlight.tsx`
|
||||
- Modify: `web/apps/console/src/presentation/OperationBlock.tsx`
|
||||
- Modify: `web/apps/console/src/presentation/styles/demo-workflow.css`
|
||||
- Modify: associated tests
|
||||
|
||||
- [ ] Re-layout the long run graph into a readable two-dimensional flow with the submitted and revision branches separated vertically. Do not shrink ten displayed nodes into one horizontal strip.
|
||||
- [ ] Keep pan, drag, and zoom enabled. Use fit-view as the initial state, not the only readable state.
|
||||
- [ ] Remove selected/current-node treatment from the static graph beat unless a real execution state supports it.
|
||||
- [ ] Replace the generic `NodeSpotlight` paragraph with a reusable node inspector showing node kind, capability or boundary, factual input/output or schema summary, outcomes, and code/evidence pointer.
|
||||
- [ ] Keep the run graph visible behind or beside its inspector so selection retains context.
|
||||
- [ ] Replace “View raw evidence ->” with a precise action label such as “Inspect protocol receipt”. Open the existing evidence inspector at the relevant event rather than a generic drawer.
|
||||
- [ ] Test the interrupt and issue-creation nodes as distinct inspector examples, plus the fallback for ordinary nodes.
|
||||
|
||||
## Task 7: Visual verification
|
||||
|
||||
- [ ] Run focused scene and figure tests, full presentation tests, typecheck, and build.
|
||||
- [ ] Capture every Scene 3-6 beat and the Scene 10 graph at both rehearsal viewports.
|
||||
- [ ] Capture architecture root, client surface, core runtime, NodeUse, provider detail, and the open run-node inspector.
|
||||
- [ ] Verify no page scroll, no clipped captions, no detached connectors, and no text below 18px at `1280x720`.
|
||||
- [ ] Run the Impeccable detector and review screenshots manually.
|
||||
- [ ] Update roadmap, archive this plan, and commit.
|
||||
|
||||
**Completion gate:** Scenes 3-5 gain clear motion without redesign churn. Scene 6 remains interactive but every zoom level uses a readable, subject-appropriate diagram. The prepared-run graph is readable without fitting ten nodes into one thin row, and node selection reveals factual details rather than a generic paragraph.
|
||||
Reference in New Issue
Block a user