feat: choreograph architecture and workflow proof scenes

This commit is contained in:
lda
2026-07-13 08:46:37 +07:00 Verified
parent 18c930449a
commit 519780e28b
26 changed files with 2000 additions and 410 deletions
+6 -3
View File
@@ -415,9 +415,12 @@ Presentation wishlist / defense readiness:
prioritized 12-minute Q&A.
Completed: [`defense story reweighting`](historical/superpowers/plans/2026-07-13-defense-story-reweighting.md)
now provides a typed 42-beat presenter-note catalog, a 750-850-word must-say
path, evidence warnings, and a 13-minute timing contract. Remaining follow-ups,
in dependency order: [`interactive graphs and Scenes 3-6 choreography`](superpowers/plans/2026-07-13-scenes-3-6-kernel-choreography.md),
then [`read-only presenter route`](superpowers/plans/2026-07-13-read-only-presenter-route.md).
path, evidence warnings, and a 13-minute timing contract. Completed:
[`interactive graphs and Scenes 3-6 choreography`](historical/superpowers/plans/2026-07-13-scenes-3-6-kernel-choreography.md)
adds restrained Scene 3-5 choreography, a semantic-zoom architecture map,
the readable `wf_core` and NodeUse figures, and a factual prepared-run graph
inspector. The next follow-up is
[`read-only presenter route`](superpowers/plans/2026-07-13-read-only-presenter-route.md).
- Defense Q&A branch set:
[`defense Q&A runbook`](runbooks/defense-qna.md) collects answers for
"Where is the AI agent?", evaluation validity, security boundaries, demo
@@ -24,12 +24,12 @@
- 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.
- [x] Assert one primary visual region per beat through `data-visual-role="primary"`.
- [x] Assert reduced-motion behavior and stable accessible headings.
- [x] Assert Scene 6 exposes public surface, kernel loop, state/trace/routing, and provider boundary concepts across its four beats.
- [x] Assert architecture figures declare a topology appropriate to their subject rather than four repeated linear flows.
- [x] Assert the prepared-run graph preserves ten displayed action/boundary/outcome nodes, readable labels, pan/zoom, and a factual node inspector.
- [x] Capture baseline screenshots at `1280x720` and `1024x768` before implementation.
## Task 2: Add restrained motion to Scene 3 positioning
@@ -38,28 +38,28 @@
- 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.
- [x] Keep the existing information architecture and add one shared layout transition between the two beats.
- [x] On `landscape`, keep the related-system map as the complete comparison.
- [x] On `lda-position`, enlarge the typed-substrate position and shift the surrounding systems enough to make the focus obvious without hiding the comparison axis.
- [x] Use position and scale before opacity; one clear transform is enough.
- [x] 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.
- [x] Preserve the current three-pane comparison.
- [x] On `planner`, enlarge the planner pane while retaining runtime destination context.
- [x] On `runtime`, let the runtime pane grow into the released space.
- [x] On `boundary`, restore both sides and enlarge the typed CLI/JSON-RPC seam.
- [x] Animate position and width between states; do not change color theme between beats.
- [x] 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.
- [x] Preserve the four-record lifecycle rail and its order.
- [x] For each beat, grow the active record into the available space while the other records compress but remain readable.
- [x] Keep arrows and order visible so the audience does not mistake the records for independent cards.
- [x] Show raw-plan-to-artifact as optional visual evidence without implying Draft is mandatory.
- [x] Avoid replaying the prepared example; Scene 9 owns applied evidence.
## Task 5: Rebuild Scene 6 as an interactive semantic zoom
@@ -71,19 +71,19 @@
- 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.
- [x] 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.
- [x] 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.
- [x] 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.
- [x] 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.
- [x] 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.
- [x] 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.
- [x] Represent node, condition, foreach, join, subgraph, interrupt, and end with icons or conventional shapes. Explicitly exclude general fork/gather.
- [x] 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.
- [x] 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.
- [x] Group built-in, MCP, and Python providers around the provider-neutral capability boundary; do not connect source families as an arbitrary adjacency chain.
- [x] Use larger labels and summaries, and allow user pan/zoom instead of shrinking the full graph until it fits.
- [x] Qualify determinism in visible copy: core semantics are deterministic for fixed definitions and handler results.
- [x] 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
@@ -115,21 +115,21 @@ The four scripted beats need not visit every child. The audience path should be
- 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.
- [x] 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.
- [x] Keep pan, drag, and zoom enabled. Use fit-view as the initial state, not the only readable state.
- [x] Remove selected/current-node treatment from the static graph beat unless a real execution state supports it.
- [x] 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.
- [x] Keep the run graph visible behind or beside its inspector so selection retains context.
- [x] 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.
- [x] 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.
- [x] Run focused scene and figure tests, full presentation tests, typecheck, and build.
- [x] Capture every Scene 3-6 beat and the Scene 10 graph at both rehearsal viewports.
- [x] Capture architecture root, client surface, core runtime, NodeUse, provider detail, and the open run-node inspector.
- [x] Verify no page scroll, no clipped captions, no detached connectors, and no text below 18px at `1280x720`.
- [x] Run the Impeccable detector and review screenshots manually.
- [x] 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.