docs: define defense presentation storyboard

2026-07-04 07:14:56 +07:00
parent da01d5624a
commit 13b5226849
2 changed files with 415 additions and 2 deletions
@@ -36,6 +36,7 @@ Design contracts:
 - [`self-describing interrupt contracts`](superpowers/specs/2026-07-01-self-describing-interrupt-contracts.md)
 - [`workflow console lifecycle explorer`](superpowers/specs/2026-07-02-workflow-console-lifecycle-explorer.md)
 - [`demo autoplay and replay`](superpowers/specs/2026-07-03-demo-autoplay-replay.md)
 - [`defense presentation storyboard`](superpowers/specs/2026-07-04-defense-presentation-storyboard-design.md)
 Implementation order:
@@ -81,8 +82,12 @@ Implementation order:
   [`constrained demo agent`](superpowers/specs/2026-07-03-constrained-demo-agent-design.md).
   Implementation:
   [`constrained demo agent plan`](historical/superpowers/plans/2026-07-03-constrained-demo-agent.md).
-9. Add a static slide/appendix shell only after presentation mode is clear.
+9. Implement the approved 13-scene defense storyboard as a no-scroll 720p
-   Astro remains an option, not the default next surface.
+    compositor. Content and evidence freeze before chat replacement, visual
    polish, or motion tuning. Design:
    [`defense presentation storyboard`](superpowers/specs/2026-07-04-defense-presentation-storyboard-design.md).
 10. Add a static slide/appendix shell only after presentation mode is clear.
    Astro remains an option, not the default next surface.
 Boundaries: this is not a production admin panel, generic visual workflow
 editor, scheduler, external Google Drive/mail integration, or benchmark evidence
@@ -0,0 +1,408 @@
 # Defense Presentation Storyboard Design
 ## Status
 Current narrative and composition contract for the lda.chat thesis defense.
 This document defines what the presentation must communicate and how the stage
 changes while it does so. It complements the
 [React presentation mode design](2026-07-03-react-presentation-mode-design.md),
 which defines the existing route and component architecture, and the
 [constrained demo agent design](2026-07-03-constrained-demo-agent-design.md),
 which defines the prepared replay driver.
 ## Purpose
 The defense must explain a systems contribution, demonstrate a real product
 surface, and survive unreliable network or model access. The current `/present`
 route proves that the components can be composed, but it does not yet provide a
 coherent defense story or fit the content into a `1280x720` viewport.
 The presentation is not a conventional slide deck wrapped around a separate
 demo. It is a staged React compositor. Thesis claims, architecture diagrams,
 chat, workflow graphs, operations, interrupt approval, outputs, and evidence
 occupy the same stable stage and move between semantic scenes.
 The listed scene budgets total 8 minutes 54 seconds. Rehearsal should target a
 10-to-11-minute main path after transitions, approval interaction, and natural
 pauses. This leaves margin in a 15-minute slot without forcing the presenter to
 rush.
 ## Speaking Voice
 The spoken script primarily uses personal defense voice:
 - "I designed and implemented ..."
 - "I evaluated ..."
 - "I deliberately excluded ..."
 Technical invariants remain neutral where precision matters:
 - "The runtime validates the payload before execution."
 - "A deployment binds logical requirements to concrete sources."
 This keeps ownership clear without making the system sound subjective.
 ## Claim Discipline
 Every scene carries one claim class. The visual treatment must make the class
 clear without requiring the presenter to recite a disclaimer.
 - **Motivation:** problem framing or design rationale; not an empirical result.
 - **Implemented:** supported by current code, tests, or a product operation.
 - **Evaluated:** supported by the thesis case studies or the audited 36-trial
  challenge cohort.
 - **External context:** a cited result from another organization; not evidence
  about lda.chat.
 - **Future work:** a plausible extension that is not part of the submitted
  implementation.
 Each scene definition must retain an evidence pointer. An evidence pointer may
 be a thesis section, repository path, deterministic replay event, test group, or
 external source. A scene without an evidence pointer may present motivation or
 transition language, but it may not introduce a new factual claim.
 ## Stable Stage Geography
 The stage has three stable regions:
 ```text
 +----------------+--------------------------------+----------------+
 | agent / chat   | primary graph, model, output   | evidence       |
 | optional       | always owns visual focus       | optional       |
 +----------------+--------------------------------+----------------+
 ```
 The regions may expand, collapse, or overlap, but they do not swap meanings.
 The audience should learn the geography once.
 - **Left:** agent conversation and operation intent.
 - **Center:** the primary explanation, workflow graph, output, or evaluation
  result.
 - **Right:** raw and interpreted evidence, trace, schemas, or source details.
 Narrative scenes hide chat. Demo scenes may show chat as `full`, `rail`, or
 `dock`. Evidence is collapsed unless the scene explicitly needs it.
 Vertical stacking is forbidden on the main path. At `1280x720`, the presenter
 must not scroll to discover the graph, approval control, output, or next action.
 ## Independent Presentation State
 The stage and chat are independently themed and positioned:
 ```ts
 type PresentationAppearance = {
  readonly stageTheme: "paper" | "night";
  readonly chatTheme: "light" | "dark";
  readonly chatMode: "hidden" | "full" | "rail" | "dock";
 };
 ```
 The themes are not required to match. A professional light chat may enter over
 a dark cinematic stage, then collapse into a narrow rail while the graph takes
 focus.
 A rehearsal toolbar may override scene defaults for stage theme, chat theme,
 motion, playback mode, and scene selection. It is hidden during the defense.
 ## Motion Contract
 Motion explains changing ownership of the stage:
 - chat enters as a complete application surface;
 - an operation card expands from chat into the center stage;
 - the workflow graph takes over while chat moves to a rail;
 - a selected node expands into a spotlight without navigating away;
 - evidence peeks from the right and opens only when needed;
 - chat collapses to a dock after the workflow completes.
 Messages appear as complete blocks with a short fade. There is no slow
 typewriter simulation. Major transitions should normally complete within one
 second and never exceed two seconds. Reduced-motion mode replaces spatial
 movement with immediate visibility changes or short fades.
 ## Main Storyboard
 ### Scene 1: Thesis
 - **Time:** 0:20
 - **Claim class:** Implemented
 - **Spoken intent:** "I designed and implemented lda.chat as a workflow
  substrate that external agents and human operators can use to create,
  validate, run, and inspect reusable workspace automations."
 - **Primary visual:** title and one-sentence thesis.
 - **Composition:** paper stage; chat hidden; no evidence panel.
 - **Evidence pointer:** thesis Abstract and Introduction.
 - **Transition:** the title contracts into a small persistent lda.chat mark.
 ### Scene 2: The Problem
 - **Time:** 0:40
 - **Claim class:** Motivation
 - **Spoken intent:** direct agent tool calls can perform actions, but reusable
  automation also needs lifecycle state, validation, bindings, persistence,
  traceability, and recovery boundaries.
 - **Primary visual:** an unstable sequence of direct tool calls contrasted with
  a durable workflow record.
 - **Composition:** night stage; chat hidden.
 - **Evidence pointer:** thesis problem statement and research question.
 - **Transition:** scattered calls align into named system responsibilities.
 ### Scene 3: The Missing Middle
 - **Time:** 0:35
 - **Claim class:** Implemented
 - **Spoken intent:** "I moved contracts and durable execution concerns out of
  the planner loop and into the platform."
 - **Primary visual:** five requirements: typed contracts, lifecycle, source
  bindings, deterministic execution, and evidence.
 - **Composition:** paper stage; one requirement enters at a time.
 - **Evidence pointer:** thesis requirements and contribution summary.
 - **Transition:** the requirements become the boundary between planner and
  runtime.
 ### Scene 4: Planner and Runtime
 - **Time:** 0:40
 - **Claim class:** Implemented
 - **Spoken intent:** the external planner proposes or revises workflow
  structure; the deterministic runtime validates, executes, records, and
  resumes it.
 - **Primary visual:** a two-sided planner/runtime boundary with explicit
  operations crossing it.
 - **Composition:** night stage; chat hidden.
 - **Evidence pointer:** thesis architecture overview and workflow API boundary.
 - **Transition:** the runtime side expands into the lifecycle.
 ### Scene 5: Lifecycle
 - **Time:** 1:00
 - **Claim class:** Implemented
 - **Spoken intent:** explain Draft, Artifact, Deployment, and Run as distinct
  records with different mutability and responsibility.
 - **Primary visual:** lifecycle records, including both draft-save and direct
  plan-import paths into an immutable artifact.
 - **Composition:** paper stage; center focus; evidence panel may show one compact
  record at a time.
 - **Evidence pointer:** thesis lifecycle chapter and lifecycle explorer.
 - **Transition:** selecting a deployment zooms into the runtime architecture.
 ### Scene 6: Architecture Zoom
 - **Time:** 1:25
 - **Claim class:** Implemented
 - **Spoken intent:** walk from client operations through JSON-RPC, WorkflowApi,
  providers and stores, then into the graph runner and one `NodeUse` execution.
 - **Primary visual:** semantic zoom through four levels rather than four
  unrelated diagrams.
 - **Composition:** night stage; chat hidden; right evidence panel peeks for
  concrete package or operation names.
 - **Evidence pointer:** thesis architecture diagrams, `docs/project_map.md`, and
  `docs/source_architecture.md`.
 - **Transition:** the node contract narrows into progressive capability
  discovery.
 ### Scene 7: Scaling Agent Interfaces
 - **Time:** 0:45
 - **Claim class:** External context
 - **Spoken intent:** large flat tool catalogs create context pressure; industry
  work increasingly uses progressive discovery and code or CLI surfaces.
 - **Primary visual:** two externally attributed measurements, followed by a
  separate "lda.chat alignment" panel listing schema discovery, CLI operations,
  workflow wrappers, artifacts, and replayable runs.
 - **Composition:** paper stage; external results use visibly distinct source
  labels.
 - **Evidence pointer:** Cloudflare reports roughly 1,000 tokens for two Code
  Mode tools versus 1.17 million for an equivalent flat MCP surface, and
  Anthropic reports a worked example reducing tool context from 150,000 to
  2,000 tokens. These are external examples, not lda.chat measurements:
  [Cloudflare Code Mode](https://blog.cloudflare.com/code-mode-mcp/) and
  [Anthropic code execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp).
 - **Transition:** the alignment panel becomes lda.chat's authoring loop.
 ### Scene 8: Author, Validate, Repair
 - **Time:** 0:45
 - **Claim class:** Implemented
 - **Spoken intent:** show discovery, focused draft operations, validation
  diagnostics, repair hints, compilation, and save as one machine-operable
  loop.
 - **Primary visual:** an operation sequence with one structured diagnostic and
  its repair action.
 - **Composition:** night stage; chat hidden; operation block in center; evidence
  peeks right.
 - **Evidence pointer:** CLI documentation, draft authoring API, and challenge
  UX findings.
 - **Transition:** the operation block becomes the first card in the agent UI.
 ### Scene 9: Agent Handoff
 - **Time:** 0:20
 - **Claim class:** Implemented
 - **Spoken intent:** "The submitted contribution is the substrate. This prepared
  agent interaction shows how a thin external interface can operate it."
 - **Primary visual:** a standard AI application surface enters full-screen.
 - **Composition:** light chat full-screen over a night stage; evidence hidden.
 - **Evidence pointer:** constrained demo agent design and prepared replay recipe.
 - **Transition:** the operator request and first operation appear immediately.
 ### Scene 10: Workflow Takes the Stage
 - **Time:** 0:45
 - **Claim class:** Implemented
 - **Spoken intent:** the prepared agent invokes the report workflow; the visible
  tool call expands into raw and interpreted operation output; the workflow
  graph becomes primary.
 - **Primary visual:** operation card transforming into the report workflow
  graph.
 - **Composition:** chat moves from full to rail; graph owns center; evidence
  remains collapsed.
 - **Evidence pointer:** prepared recording events and
  `examples/lda_report_workflow/`.
 - **Transition:** execution stops at the typed `issue_review` interrupt.
 ### Scene 11: Interrupt, Resume, Evidence
 - **Time:** 1:30
 - **Claim class:** Implemented
 - **Spoken intent:** explain the typed approval contract, approve selected
  issues, resume the same run, then show the generated report, issue-board
  writes, trace frames, and raw/interpreted evidence.
 - **Primary visual:** interrupt approval followed by output and trace projection.
 - **Composition:** chat rail during approval, then dock; center alternates
  between interrupt, output, and trace; right evidence panel opens once.
 - **Evidence pointer:** deterministic replay recording, typed interrupt schemas,
  run inspect result, and trace events.
 - **Failure fallback:** if the live server or operation fails, switch to the
  reviewed replay at the current semantic event without resetting the layout or
  explaining a new UI.
 - **Transition:** trace frames collapse into evaluation evidence.
 ### Scene 12: Evaluation
 - **Time:** 1:25
 - **Claim class:** Evaluated
 - **Spoken intent:** present the 36-trial cohort as bounded agent-operability and
  longitudinal product evidence, not a model leaderboard or broad success-rate
  estimate.
 - **Primary visual:** cohort structure, audited validity, failure classes, and
  selected product improvements discovered through trials.
 - **Composition:** paper stage; chat hidden; one chart at a time; evidence panel
  links to the audit/run records.
 - **Evidence pointer:** thesis evaluation chapter, Appendix C, generated cohort
  figures, and challenge reports.
 - **Transition:** limitations remain while the charts simplify into the final
  planner/runtime boundary.
 ### Scene 13: Limits and Conclusion
 - **Time:** 1:00
 - **Claim class:** Future work
 - **Spoken intent:** distinguish implemented substrate from a future live LLM
  interface, production security, scheduling, broader model evaluation, and
  comparative studies; end on the planner/runtime separation.
 - **Primary visual:** implemented core in focus, future layers around it, then
  the one-sentence thesis.
 - **Composition:** night stage returning to paper; chat dock may remain as a
  subtle reminder that the agent is a client of the substrate.
 - **Evidence pointer:** thesis limitations and future-work chapters.
 - **Transition:** none; hold a stable conclusion frame for questions.
 ## Presenter Controls
 The presenter needs a hidden or unobtrusive rehearsal surface with:
 - next and previous scene;
 - direct scene jump by number or hash;
 - current and next speaker note;
 - elapsed and planned time;
 - stage-theme and chat-theme overrides;
 - motion reduction toggle;
 - replay/live indicator and forced replay fallback;
 - reset to the start of the current scene;
 - open Q&A index.
 The audience view must not expose these controls unless explicitly opened.
 ## Q&A Index
 Q&A material is not scene 14. It is a separate deep-link index that can open
 focused views without replaying the main story.
 Required entries:
 - where the AI agent is and what is actually submitted;
 - Draft versus Artifact versus Deployment versus Run;
 - raw-plan import versus draft authoring;
 - source-provider boundary and MCP status;
 - schema validation and repair hints;
 - deterministic execution and reducer-aware state;
 - typed interrupt and resume contract;
 - persistence and recovery boundaries;
 - challenge methodology and validity limits;
 - security and sandboxing non-goals;
 - why not direct tool calling, generated scripts, LangGraph, Temporal, or n8n;
 - live demo failure and replay provenance.
 Each entry should deep-link to an existing component or evidence record. Avoid a
 second, disconnected slide deck.
 ## Chat Component Direction
 The next visual slice should copy source-owned primitives from Vercel AI
 Elements rather than invent another chat UI or adopt a second agent runtime.
 Useful primitives include conversation scrolling, messages, Markdown response,
 prompt input, and tool-call presentation.
 The copied components adapt to the existing `AgentMessagePart` and
 `AgentDriver` contracts. Do not adopt `useChat`, model selection, attachments,
 accounts, or a complete ChatGPT shell until a live AI SDK driver exists.
 The chat remains a supporting presentation surface. It must never push the
 graph, approval, or evidence below the fold.
 ## Content and Visual Freeze
 Content freezes before visual polish:
 1. approve scene order, claims, evidence pointers, and spoken intent;
 2. implement the compositor states and navigation;
 3. replace chat primitives and establish visual tokens;
 4. tune motion and final scene styling;
 5. rehearse timing and revise wording without restructuring components.
 This ordering prevents the presentation from becoming visually polished while
 still telling the wrong story.
 ## Acceptance Criteria
 The storyboard implementation is acceptable when:
 1. all 13 scenes are directly addressable and navigable without page scroll;
 2. the main path fits within 12 minutes in rehearsal;
 3. every factual scene has a claim class and evidence pointer;
 4. external measurements are visibly attributed and never presented as
   lda.chat evaluation;
 5. chat, graph, approval, output, and evidence retain stable stage geography;
 6. stage and chat themes can be controlled independently;
 7. live failure can fall back to the matching replay event without layout
   reset;
 8. the full main path is readable at `1280x720` with browser zoom at 100%;
 9. reduced-motion mode preserves all information and controls;
 10. the Q&A index opens focused evidence without replaying the presentation;
 11. the spoken script primarily uses personal defense voice while technical
    invariants remain precise;
 12. the existing `/console` product route remains independent from cinematic
    presentation styling.
 ## Out of Scope
 - a live general-purpose LLM planner;
 - a second slide framework or Astro shell;
 - a generic drag-and-drop presentation editor;
 - redesigning the normal console in the presentation's cinematic style;
 - reproducing every thesis diagram or code listing;
 - presenting historical challenge waves as a controlled benchmark;
 - adding claims merely because a visual component can display them.