lda.chat/lda-wf
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: define presentation rehearsal route matrix

Browse Source
This commit is contained in:
lda
2026-07-13 00:17:25 +07:00 Verified
parent ba51db61ad
commit fce3393405
4 changed files with 166 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/runbooks/defense-presentation.md
+5
View File
@@ -143,6 +143,11 @@ replay-backed entry points.
## Useful Deep Links ## Useful Deep Links
The [presentation rehearsal matrix](presentation-rehearsal-matrix.md) is the
route checklist for rehearsal, not a new story or product contract. It covers
every current storyboard beat and records the canonical route, speaking line,
visual hierarchy, chat mode, evidence mode, and fallback route.
- Title: `http://127.0.0.1:5173/present#scene/thesis/title` - Title: `http://127.0.0.1:5173/present#scene/thesis/title`
- Positioning: `http://127.0.0.1:5173/present#scene/positioning/landscape` - Positioning: `http://127.0.0.1:5173/present#scene/positioning/landscape`
- Architecture root: `http://127.0.0.1:5173/present#scene/architecture/client` - Architecture root: `http://127.0.0.1:5173/present#scene/architecture/client`
docs/runbooks/presentation-rehearsal-matrix.md
+62
View File
@@ -0,0 +1,62 @@
# Presentation Rehearsal Matrix
This is the route checklist for rehearsing the defense presentation, not a new
story or product contract. The route column is the captureable portion of the
hash: open it as `http://127.0.0.1:5173/present#scene/<route>`.
The evidence column points to the existing storyboard evidence pointer or the
runbook fallback. Do not claim output that is not present in that pointer. A
`replay-only` beat needs no live service; `live-capable` may use the live target
when available; `explicit run` requires the prepared workflow start operation
before its live evidence exists. Every fallback is a route in this matrix and
can be shown after selecting replay with the runbook's session-storage switch.
| Route | Say | Dominant visual | Supporting visual | Chat | Evidence mode | Fallback route |
|---|---|---|---|---|---|---|
| `thesis/title` | The project began as a pursuit of an AI agent for workspace automation. | Thesis title card | Substrate framing | hidden | replay-only; Thesis Abstract and Introduction | `thesis/title` |
| `thesis/substrate` | The implemented contribution is the typed workflow substrate an agent needs. | Substrate lifecycle card | Thesis framing | hidden | replay-only; Thesis Abstract and Introduction | `thesis/substrate` |
| `problem/direct-actions` | Direct tool actions can act without becoming reusable automation. | Problem contrast | Lifecycle vocabulary | hidden | replay-only; Thesis Problem Statement and Requirements | `problem/direct-actions` |
| `problem/missing-contracts` | Reusable automation needs schemas, persistence, traces, and recovery boundaries. | Contract checklist | Problem contrast | hidden | replay-only; Thesis Problem Statement and Requirements | `problem/missing-contracts` |
| `positioning/landscape` | Related systems solve different parts of the tool, script, workflow, and agent problem. | Related-systems landscape | Problem contracts | hidden | replay-only; Thesis Positioning and Related Systems | `positioning/landscape` |
| `positioning/lda-position` | lda.chat occupies the typed, provider-neutral workflow substrate niche for external agents. | lda.chat position map | Related-systems landscape | hidden | replay-only; Thesis Positioning and Related Systems | `positioning/lda-position` |
| `planner-runtime/planner` | An external planner proposes and revises workflow structure. | Planner side of boundary | Typed operations | hidden | replay-only; Thesis Architecture Overview | `planner-runtime/planner` |
| `planner-runtime/runtime` | The runtime validates, executes, records, and resumes the proposal deterministically. | Runtime side of boundary | Lifecycle records | hidden | replay-only; Thesis Architecture Overview | `planner-runtime/runtime` |
| `planner-runtime/boundary` | Typed CLI and JSON-RPC operations make the planner/runtime boundary explicit. | Boundary diagram | CLI and RPC surface | hidden | replay-only; Thesis Architecture Overview | `planner-runtime/boundary` |
| `lifecycle/draft` | Draft is mutable iterative authoring state. | Lifecycle stage: Draft | State transition strip | hidden | replay-only; Thesis Workflow Lifecycle | `lifecycle/draft` |
| `lifecycle/artifact` | Artifact is the immutable saved workflow definition. | Lifecycle stage: Artifact | State transition strip | hidden | replay-only; Thesis Workflow Lifecycle | `lifecycle/artifact` |
| `lifecycle/deployment` | Deployment binds logical requirements to concrete sources. | Lifecycle stage: Deployment | Binding relationship | hidden | replay-only; Thesis Workflow Lifecycle | `lifecycle/deployment` |
| `lifecycle/run` | Run is persisted execution with output, status, and trace. | Lifecycle stage: Run | Evidence record chain | hidden | replay-only; Thesis Workflow Lifecycle | `lifecycle/run` |
| `architecture/client` | Human and agent clients use the same public lifecycle surface. | Architecture client node | System architecture figure | hidden | replay-only; Thesis System Architecture; `docs/project_map.md`; `docs/source_architecture.md` | `architecture/client` |
| `architecture/api` | JSON-RPC reaches WorkflowApi without owning domain behavior. | Architecture API node | Client operations | hidden | replay-only; Thesis System Architecture; `docs/project_map.md`; `docs/source_architecture.md` | `architecture/api` |
| `architecture/runtime` | Runtime resolves provider-neutral capabilities and stores lifecycle records. | Runtime/providers focus | Architecture overview | hidden | replay-only; Thesis System Architecture; `docs/project_map.md`; `docs/source_architecture.md` | `architecture/runtime` |
| `architecture/node-use` | A NodeUse validates input, invokes a capability, and reduces output into state. | NodeUse focus | Runtime/providers focus | hidden | replay-only; Thesis System Architecture; `docs/project_map.md`; `docs/source_architecture.md` | `architecture/node-use` |
| `authoring/discover` | Discovery lets an operator inspect capabilities and schemas before authoring. | Authoring discovery surface | Capability/schema list | hidden | replay-only; CLI documentation; draft authoring API; challenge UX findings | `authoring/discover` |
| `authoring/author` | Focused operations build and connect the draft. | Draft authoring surface | Workflow structure | hidden | replay-only; CLI documentation; draft authoring API; challenge UX findings | `authoring/author` |
| `authoring/diagnose` | Structured diagnostics identify invalid state instead of leaving the agent to guess. | Diagnostic receipt | Draft authoring surface | hidden | replay-only; CLI documentation; draft authoring API; challenge UX findings | `authoring/diagnose` |
| `authoring/repair` | Repair hints lead from invalid draft state to a valid compiled workflow. | Repair guidance | Diagnostic receipt | hidden | replay-only; CLI documentation; draft authoring API; challenge UX findings | `authoring/repair` |
| `agent-handoff/request` | The thin agent interface receives the report request while the platform owns execution. | Agent request surface | Workflow substrate framing | hidden | replay-only; Constrained demo agent and prepared replay recipe | `agent-handoff/request` |
| `prepared-lifecycle/discover` | The prepared example starts by inspecting its available sources, capabilities, and schemas. | Prepared lifecycle: discovery | Capability/schema evidence | hidden | replay-only; `examples/lda_report_workflow`; deployment inspect replay evidence | `prepared-lifecycle/discover` |
| `prepared-lifecycle/draft` | The example creates a report workflow draft with its steps and routes. | Prepared lifecycle: draft | Workflow definition | hidden | replay-only; `examples/lda_report_workflow`; deployment inspect replay evidence | `prepared-lifecycle/draft` |
| `prepared-lifecycle/validate` | Binding and validation diagnose and repair the prepared draft. | Prepared lifecycle: validation | Diagnostic evidence | hidden | replay-only; `examples/lda_report_workflow`; deployment inspect replay evidence | `prepared-lifecycle/validate` |
| `prepared-lifecycle/artifact` | The validated draft compiles into an immutable artifact. | Prepared lifecycle: artifact | Lifecycle state | hidden | replay-only; `examples/lda_report_workflow`; deployment inspect replay evidence | `prepared-lifecycle/artifact` |
| `prepared-lifecycle/deployment` | Deployment bindings are saved and readiness is validated before a run. | Prepared lifecycle: deployment | Binding/readiness evidence | hidden | replay-only; `examples/lda_report_workflow`; deployment inspect replay evidence | `prepared-lifecycle/deployment` |
| `run-from-deployment/input` | The run begins from selected documents and an issue-board path. | Workflow input panel | Prepared deployment | hidden | live-capable; `workflow.runs.start` replay evidence | `prepared-lifecycle/deployment` |
| `run-from-deployment/operation` | A public operation starts a durable workflow run. | Start operation | Workflow graph | hidden | explicit run; `workflow.runs.start` replay evidence | `run-from-deployment/operation` |
| `run-from-deployment/graph` | The run follows a reusable workflow graph, not a chat transcript. | Workflow graph | Run operation receipt | hidden | live-capable; `workflow.runs.start` replay evidence | `run-from-deployment/operation` |
| `typed-human-boundary/interrupt` | Execution reaches a declared issue-review boundary with a typed interrupt payload. | Interrupt boundary | Workflow graph | hidden | live-capable; typed interrupt payload and resume contract | `run-from-deployment/operation` |
| `typed-human-boundary/approval` | The operator chooses a submitted or revision-requested outcome for the paused run. | Approval decision surface | Interrupt payload | hidden | live-capable; typed interrupt payload and resume contract | `typed-human-boundary/approval` |
| `resume-output-evidence/resume` | The submitted payload resumes the same persisted run. | Resume operation | Approval decision | hidden | live-capable; `workflow.runs.resume`, workflow output, and trace replay evidence | `typed-human-boundary/approval` |
| `resume-output-evidence/output` | The workflow produces the report and issue-board changes. | Output evidence | Resume operation | hidden | live-capable; `workflow.runs.resume`, workflow output, and trace replay evidence | `resume-output-evidence/output` |
| `resume-output-evidence/trace` | Trace frames and protocol evidence remain inspectable after completion. | Trace evidence | Output evidence | hidden | live-capable; `workflow.runs.resume`, workflow output, and trace replay evidence | `resume-output-evidence/trace` |
| `evaluation/cohort` | The evaluation covers 36 audited trials across models, profiles, challenges, and waves. | Evaluation cohort summary | Trial breakdown | hidden | replay-only; Thesis Evaluation and Appendix C | `evaluation/cohort` |
| `evaluation/validity` | Manual audit separates task completion from valid product-surface evidence. | Validity boundary | Evaluation cohort | hidden | replay-only; Thesis Evaluation and Appendix C | `evaluation/validity` |
| `evaluation/findings` | The trials exposed concrete authoring and diagnostic UX gaps. | Findings summary | Validity boundary | hidden | replay-only; Thesis Evaluation and Appendix C | `evaluation/findings` |
| `conclusion/limits` | The prototype is not a production sandbox, scheduler, or broad agent benchmark. | Contribution boundary | Evaluation findings | hidden | replay-only; Thesis Limitations, Future Work, and Conclusion | `conclusion/limits` |
| `conclusion/future` | A live LLM interface, scheduling, and broader evaluation remain future work. | Future-work layers | Contribution boundary | hidden | replay-only; Thesis Limitations, Future Work, and Conclusion | `conclusion/future` |
| `conclusion/conclusion` | The typed substrate makes reusable agent-operated automation inspectable. | Conclusion contribution card | Planner/runtime boundary | hidden | replay-only; Thesis Limitations, Future Work, and Conclusion | `conclusion/conclusion` |
| `conclusion/questions` | The final beat hands the discussion to the examiner using the prepared Q&A branches. | Questions card | Defense Q&A | hidden | replay-only; Thesis Limitations, Future Work, and Conclusion | `conclusion/questions` |
For live-capable and explicit-run beats, use the existing `Live Demo
Fallbacks` section in [`defense-presentation.md`](defense-presentation.md) when
the live target or RPC server is unavailable. The fallback routes above are
replay evidence, not fresh live results.
scripts/presentation-rehearsal-routes.json
+44
View File
@@ -0,0 +1,44 @@
[
{"sceneId":"thesis","beatId":"title","route":"thesis/title","fileStem":"01-thesis-title"},
{"sceneId":"thesis","beatId":"substrate","route":"thesis/substrate","fileStem":"01-thesis-substrate"},
{"sceneId":"problem","beatId":"direct-actions","route":"problem/direct-actions","fileStem":"02-problem-direct-actions"},
{"sceneId":"problem","beatId":"missing-contracts","route":"problem/missing-contracts","fileStem":"02-problem-missing-contracts"},
{"sceneId":"positioning","beatId":"landscape","route":"positioning/landscape","fileStem":"03-positioning-landscape"},
{"sceneId":"positioning","beatId":"lda-position","route":"positioning/lda-position","fileStem":"03-positioning-lda-position"},
{"sceneId":"planner-runtime","beatId":"planner","route":"planner-runtime/planner","fileStem":"04-planner-runtime-planner"},
{"sceneId":"planner-runtime","beatId":"runtime","route":"planner-runtime/runtime","fileStem":"04-planner-runtime-runtime"},
{"sceneId":"planner-runtime","beatId":"boundary","route":"planner-runtime/boundary","fileStem":"04-planner-runtime-boundary"},
{"sceneId":"lifecycle","beatId":"draft","route":"lifecycle/draft","fileStem":"05-lifecycle-draft"},
{"sceneId":"lifecycle","beatId":"artifact","route":"lifecycle/artifact","fileStem":"05-lifecycle-artifact"},
{"sceneId":"lifecycle","beatId":"deployment","route":"lifecycle/deployment","fileStem":"05-lifecycle-deployment"},
{"sceneId":"lifecycle","beatId":"run","route":"lifecycle/run","fileStem":"05-lifecycle-run"},
{"sceneId":"architecture","beatId":"client","route":"architecture/client","fileStem":"06-architecture-client"},
{"sceneId":"architecture","beatId":"api","route":"architecture/api","fileStem":"06-architecture-api"},
{"sceneId":"architecture","beatId":"runtime","route":"architecture/runtime","fileStem":"06-architecture-runtime"},
{"sceneId":"architecture","beatId":"node-use","route":"architecture/node-use","fileStem":"06-architecture-node-use"},
{"sceneId":"authoring","beatId":"discover","route":"authoring/discover","fileStem":"07-authoring-discover"},
{"sceneId":"authoring","beatId":"author","route":"authoring/author","fileStem":"07-authoring-author"},
{"sceneId":"authoring","beatId":"diagnose","route":"authoring/diagnose","fileStem":"07-authoring-diagnose"},
{"sceneId":"authoring","beatId":"repair","route":"authoring/repair","fileStem":"07-authoring-repair"},
{"sceneId":"agent-handoff","beatId":"request","route":"agent-handoff/request","fileStem":"08-agent-handoff-request"},
{"sceneId":"prepared-lifecycle","beatId":"discover","route":"prepared-lifecycle/discover","fileStem":"09-prepared-lifecycle-discover"},
{"sceneId":"prepared-lifecycle","beatId":"draft","route":"prepared-lifecycle/draft","fileStem":"09-prepared-lifecycle-draft"},
{"sceneId":"prepared-lifecycle","beatId":"validate","route":"prepared-lifecycle/validate","fileStem":"09-prepared-lifecycle-validate"},
{"sceneId":"prepared-lifecycle","beatId":"artifact","route":"prepared-lifecycle/artifact","fileStem":"09-prepared-lifecycle-artifact"},
{"sceneId":"prepared-lifecycle","beatId":"deployment","route":"prepared-lifecycle/deployment","fileStem":"09-prepared-lifecycle-deployment"},
{"sceneId":"run-from-deployment","beatId":"input","route":"run-from-deployment/input","fileStem":"10-run-from-deployment-input"},
{"sceneId":"run-from-deployment","beatId":"operation","route":"run-from-deployment/operation","fileStem":"10-run-from-deployment-operation"},
{"sceneId":"run-from-deployment","beatId":"graph","route":"run-from-deployment/graph","fileStem":"10-run-from-deployment-graph"},
{"sceneId":"typed-human-boundary","beatId":"interrupt","route":"typed-human-boundary/interrupt","fileStem":"11-typed-human-boundary-interrupt"},
{"sceneId":"typed-human-boundary","beatId":"approval","route":"typed-human-boundary/approval","fileStem":"11-typed-human-boundary-approval"},
{"sceneId":"resume-output-evidence","beatId":"resume","route":"resume-output-evidence/resume","fileStem":"12-resume-output-evidence-resume"},
{"sceneId":"resume-output-evidence","beatId":"output","route":"resume-output-evidence/output","fileStem":"12-resume-output-evidence-output"},
{"sceneId":"resume-output-evidence","beatId":"trace","route":"resume-output-evidence/trace","fileStem":"12-resume-output-evidence-trace"},
{"sceneId":"evaluation","beatId":"cohort","route":"evaluation/cohort","fileStem":"13-evaluation-cohort"},
{"sceneId":"evaluation","beatId":"validity","route":"evaluation/validity","fileStem":"13-evaluation-validity"},
{"sceneId":"evaluation","beatId":"findings","route":"evaluation/findings","fileStem":"13-evaluation-findings"},
{"sceneId":"conclusion","beatId":"limits","route":"conclusion/limits","fileStem":"14-conclusion-limits"},
{"sceneId":"conclusion","beatId":"future","route":"conclusion/future","fileStem":"14-conclusion-future"},
{"sceneId":"conclusion","beatId":"conclusion","route":"conclusion/conclusion","fileStem":"14-conclusion-conclusion"},
{"sceneId":"conclusion","beatId":"questions","route":"conclusion/questions","fileStem":"14-conclusion-questions"}
]
web/apps/console/src/presentation/storyboard-navigation.test.ts
+55 -1
View File
@@ -1,11 +1,12 @@
import { describe, expect, it } from "vitest"; import { describe, expect, it } from "vitest";
import rehearsalRoutes from "../../../../../scripts/presentation-rehearsal-routes.json";
import { import {
hashForLocation, hashForLocation,
locationFromHash, locationFromHash,
nextMainLocation, nextMainLocation,
previousMainLocation, previousMainLocation,
} from "./storyboard-navigation.js"; } from "./storyboard-navigation.js";
import { defaultMainLocation, type MainLocation } from "./storyboard.js"; import { defaultMainLocation, mainScenes, type MainLocation } from "./storyboard.js";
describe("storyboard navigation", () => { describe("storyboard navigation", () => {
it("round-trips main and discussion hashes", () => { it("round-trips main and discussion hashes", () => {
@@ -23,6 +24,59 @@ describe("storyboard navigation", () => {
.toBe("#discuss/where-is-ai-agent"); .toBe("#discuss/where-is-ai-agent");
}); });
it("covers every current storyboard beat with one canonical rehearsal route", () => {
const storyboardRoutes = mainScenes.flatMap((scene) =>
scene.beats.map((beat) => `${scene.id}/${beat.id}`),
);
const manifestRoutes = rehearsalRoutes.map((route) => `${route.sceneId}/${route.beatId}`);
expect(new Set(manifestRoutes).size).toBe(manifestRoutes.length);
expect(manifestRoutes).toHaveLength(storyboardRoutes.length);
for (const scene of mainScenes) {
for (const beat of scene.beats) {
const matchingRoutes = rehearsalRoutes.filter(
(route) => route.sceneId === scene.id && route.beatId === beat.id,
);
expect(matchingRoutes, `missing rehearsal route for scene ${scene.id}`).toHaveLength(1);
const route = matchingRoutes[0];
if (!route) continue;
expect(route).toMatchObject({
sceneId: scene.id,
beatId: beat.id,
route: `${scene.id}/${beat.id}`,
});
expect(locationFromHash(hashForLocation({
kind: "main",
sceneId: scene.id,
beatId: beat.id,
focusPath: [],
}))).toEqual({
kind: "main",
sceneId: scene.id,
beatId: beat.id,
focusPath: [],
});
}
}
for (const route of rehearsalRoutes) {
expect(Object.keys(route).sort()).toEqual(["beatId", "fileStem", "route", "sceneId"]);
expect(storyboardRoutes).toContain(`${route.sceneId}/${route.beatId}`);
expect(locationFromHash(hashForLocation({
kind: "main",
sceneId: route.sceneId as MainLocation["sceneId"],
beatId: route.beatId,
focusPath: [],
}))).toMatchObject({
kind: "main",
sceneId: route.sceneId,
beatId: route.beatId,
focusPath: [],
});
}
});
it("parses the Questions beat location", () => { it("parses the Questions beat location", () => {
expect(locationFromHash("#scene/conclusion/questions")).toEqual({ expect(locationFromHash("#scene/conclusion/questions")).toEqual({
kind: "main", kind: "main",