docs: design lifecycle diagram pass

2026-07-14 00:54:18 +07:00
parent e47ffc95cc
commit 02926ae426
1 changed files with 194 additions and 0 deletions
@@ -0,0 +1,194 @@
 # Authoring Lifecycle Diagram Pass
 ## Goal
 Make Scene 8's prepared authoring lifecycle easier to present without returning
 to the older dense split-screen composition. Each beat should contain one large,
 immediately legible diagram and a compact factual receipt derived from the same
 reviewed evidence already used by the scene.
 The result should preserve the current unclipped, spacious layout while making
 the empty space explain a lifecycle transformation.
 ## Design Direction
 Scene 8 uses one continuous visual language across all six beats:
 - diagram nodes represent workflow or lifecycle objects;
 - solid connectors represent existing relationships;
 - an open or interrupted connector represents a typed validation failure;
 - a newly completed connector represents the repair;
 - object identity persists between adjacent beats so the audience sees a
  transformation rather than six unrelated result cards;
 - exact product facts remain visible as a compact receipt, not as the primary
  composition.
 The prepared assistant remains supporting context. It must not reclaim the
 screen area needed by the lifecycle diagram.
 ## Beat Compositions
 ### Discover
 Show the three configured local source IDs feeding one capability contract.
 The contract exposes its input, output, and outcome shape. The source inventory
 count and capability name remain in the receipt.
 The audience-facing claim is: agents discover typed capabilities before they
 author a workflow.
 ### Draft
 Show a large workflow graph:
 ```text
 read_documents --ok--> analyze --ok--> END
 ```
 The step input projection appears on the first connector. Revision, workspace
 ID, step count, and route count remain in the receipt. The diagram should reuse
 the established workflow graph vocabulary without introducing an independent
 graph data model.
 The audience-facing claim is: the draft is a mutable, inspectable workflow
 structure rather than a hidden chat transcript.
 ### Diagnose
 Reuse the Draft graph in the same spatial arrangement. Render the
 `analyze.ok` route as an incomplete connection that stops before `END`. Place
 the typed diagnostic beside that break, including its code and path.
 The prepared fault-injection command remains available as secondary evidence,
 but it must not compete with the broken route.
 The audience-facing claim is: validation identifies a concrete graph defect and
 the exact location that needs repair.
 ### Repair
 Preserve the Diagnose composition and complete the missing connection. The
 route changes from interrupted to valid, revision 3 becomes revision 4, and the
 diagnostic count becomes zero. Motion may draw or reveal the repaired segment,
 but the final state must remain fully visible when motion is disabled.
 The audience-facing claim is: repair is a focused mutation followed by
 deterministic revalidation.
 ### Artifact
 Show the repaired draft transforming into a locked, immutable artifact. The
 artifact retains the workflow silhouette while gaining an identity and version.
 Required source contracts remain visibly attached to it rather than appearing
 as an unrelated list.
 The receipt contains the artifact ID, version, and exact required source IDs.
 The audience-facing claim is: an artifact freezes a validated workflow
 definition into a reusable version.
 ### Deployment
 Show the artifact requirements on the left, their concrete configured source
 bindings in the middle, and one runnable deployment on the right. This is a
 binding map, not another generic card grid. The deployment ID and runnable
 status remain in the receipt.
 The audience-facing claim is: deployment binds logical requirements to runtime
 sources and validates readiness for a persisted run.
 ## Component Boundary
 `AuthoringPhaseVisual` remains the evidence-union dispatcher. Each evidence
 variant renders a shared diagram shell containing:
 1. a dominant diagram region;
 2. an accessible text equivalent or labelled structure;
 3. a compact factual receipt.
 Shared visual primitives should cover only recurring lifecycle concepts:
 - workflow node;
 - source or requirement node;
 - directed relationship;
 - broken relationship;
 - lifecycle object identity;
 - compact receipt row.
 Do not create a general-purpose diagram framework. Reuse an existing graph
 renderer when it improves routing or interaction; use semantic HTML and CSS for
 fixed one-dimensional mappings. Avoid hand-calculated arbitrary connector
 geometry.
 ## Evidence And Truthfulness
 All labels and relationships come from
 `PreparedLifecycleStepProjection["evidence"]` or the reviewed evidence catalog.
 The visual layer must not introduce a second set of lifecycle facts.
 The prepared authoring sequence remains replay evidence. The diagrams must not
 imply that Scene 8 performs live authoring RPC calls.
 ## Responsive Behavior
 At 1280x720, the diagram should occupy most of the result height and remain
 readable without scrolling. At 1024x768, the diagram may tighten or stack fixed
 mapping columns, but the result root must not clip or overflow its bounded
 viewport.
 On narrower presenter/mobile surfaces, horizontal diagrams may become a
 contained, scrollbar-hidden pan region. Factual receipts wrap below the diagram
 instead of shrinking labels below readable size.
 ## Motion
 Motion communicates continuity only:
 - Draft to Diagnose preserves node positions;
 - Diagnose to Repair completes the missing route;
 - Repair to Artifact changes object state while preserving the workflow
  silhouette;
 - Artifact to Deployment separates requirements into concrete bindings.
 No blur, pan-in on unchanged content, bounce, or repeated entrance animation.
 Reduced-motion mode renders each final state immediately.
 ## Accessibility
 - Every diagram has a named region.
 - Connector meaning is available in text, not color alone.
 - Broken and repaired states expose explicit labels.
 - IDs and commands remain selectable text.
 - Decorative icons are hidden from assistive technology.
 ## Verification
 Add focused tests that assert:
 - each beat renders the correct diagram kind;
 - Draft, Diagnose, and Repair preserve the same workflow node identities;
 - Diagnose exposes the missing `analyze.ok` connection;
 - Repair exposes the restored connection and zero diagnostics;
 - Artifact preserves the exact artifact identity, version, and requirements;
 - Deployment maps every requirement to its configured source;
 - no visual introduces facts absent from reviewed evidence.
 Run the presentation tests, console typecheck, and production build. Capture all
 six beats at 1280x720 plus Discover, Diagnose, and Deployment at 1024x768.
 Confirm each result has no unintended internal overflow and remains readable
 with reduced motion enabled.
 After the visual pass, review the presenter script for all six beats against the
 rendered screen. Each beat should support one short spoken claim anchored to the
 dominant diagram. Revise the script only when it describes a removed visual,
 omits the new focal transformation, or uses terminology that is harder to say
 than the diagram requires. Do not expand the script merely because the diagram
 contains more detail.
 ## Out Of Scope
 - changing the prepared assistant conversation;
 - live authoring RPC execution;
 - redesigning the lifecycle rail or presentation chrome;
 - adding arbitrary graph editing;
 - restoring the previous dense two-screenshot layout.