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

docs: add defense beat goals and anchor terms

Browse Source
This commit is contained in:
lda
2026-07-13 21:11:50 +07:00 Verified
parent 29268ddcad
commit 7966c54b63
3 changed files with 147 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/plans/2026-07-13-defense-speech-simplification.md
+132 -12
View File
@@ -2,9 +2,9 @@
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Replace the terminology-heavy timed narration for Scenes 1-8 with short spoken English that carries one idea per beat.
**Goal:** Replace the terminology-heavy timed narration for Scenes 1-8 with a clear audience goal, anchor terms, and short suggested wording for every beat.
**Architecture:** Keep `presenter-notes.ts` as the typed source of truth and keep the readable runbook synchronized through its existing test. Only `mustSay` text and timing change; evidence pointers, warnings, fallbacks, and Q&A links remain available to the presenter.
**Architecture:** Keep `presenter-notes.ts` as the typed source of truth and add `goal` plus `keywords` beside the existing suggested `mustSay` wording. Render all three in `/presenter`, keep the readable runbook synchronized through tests, and preserve evidence pointers, warnings, fallbacks, and Q&A links.
**Tech Stack:** TypeScript, Vitest, Markdown runbooks, React presenter route.
@@ -12,14 +12,16 @@
- The audience-facing storyboard remains unchanged in this slice.
- Do not remove evidence warnings, replay disclosures, or Q&A links.
- Scenes 1-8 must use one mandatory spoken idea per beat and avoid lists of unexplained system nouns.
- Every beat must define one audience goal and one to three anchor terms.
- Scenes 1-8 must additionally use one short suggested sentence per beat.
- `mustSay` is suggested wording, not a word-for-word obligation; `/presenter` must label it accordingly.
- Provider neutrality, typed contracts, source resolution, resume boundaries, and NodeUse remain optional-detail or Q&A material unless a beat visually demonstrates them.
- The timed Scenes 1-8 path must total 257 seconds or less.
- The complete must-say catalog must contain 500-700 words.
---
### Task 1: Pin The Simpler Speech And Timing Contract
### Task 1: Pin Goals, Keywords, Simpler Speech, And Timing
**Files:**
- Modify: `web/apps/console/src/presentation/presenter/presenter-notes.test.ts`
@@ -31,7 +33,7 @@
- [ ] **Step 1: Replace the old timing and word-budget expectations**
Assert scene totals of `[30, 30, 35, 40, 36, 32, 12, 42, 35, 30, 50, 120, 75]`, a complete-deck target of `642` including the existing 75-second navigation buffer, and a `500-700` word budget. Add a loop over Scenes 1-8 that strips Markdown emphasis, splits on whitespace, and asserts no `mustSay` value exceeds 28 words.
Assert scene totals of `[30, 30, 35, 40, 36, 32, 12, 42, 35, 30, 50, 120, 75]`, a complete-deck target of `642` including the existing 75-second navigation buffer, and a `500-700` word budget. Check every beat has a non-empty `goal` and one to three non-empty `keywords`. Separately check that no suggested `mustSay` value in Scenes 1-8 exceeds 28 words.
```ts
const openingSceneIds = new Set([
@@ -45,6 +47,13 @@ const openingSceneIds = new Set([
"prepared-lifecycle",
]);
for (const note of presenterNotes) {
expect(note.goal.trim().length, `${note.sceneId}/${note.beatId}`).toBeGreaterThan(0);
expect(note.keywords.length, `${note.sceneId}/${note.beatId}`).toBeGreaterThanOrEqual(1);
expect(note.keywords.length, `${note.sceneId}/${note.beatId}`).toBeLessThanOrEqual(3);
expect(note.keywords.every((keyword) => keyword.trim().length > 0)).toBe(true);
}
for (const note of presenterNotes.filter((item) => openingSceneIds.has(item.sceneId))) {
const words = note.mustSay.replaceAll("**", "").trim().split(/\s+/);
expect(words.length, `${note.sceneId}/${note.beatId}`).toBeLessThanOrEqual(28);
@@ -79,7 +88,7 @@ git add web/apps/console/src/presentation/presenter/presenter-notes.test.ts
git commit -m "test: define simpler defense speech contract"
```
### Task 2: Rewrite Scenes 1-8 Must-Say Notes
### Task 2: Add Goals And Keywords To Every Beat, Then Rewrite Scenes 1-8
**Files:**
- Modify: `web/apps/console/src/presentation/presenter/presenter-notes.ts`
@@ -87,7 +96,7 @@ git commit -m "test: define simpler defense speech contract"
**Interfaces:**
- Consumes: `beatNote()` and the existing note metadata.
- Produces: the exact presenter speech rendered by `/presenter`.
- Produces: presenter goals, anchor terms, and suggested speech rendered by `/presenter`.
- [ ] **Step 1: Set the new target seconds**
@@ -104,7 +113,72 @@ Use these per-beat values:
// Scene 8: 7, 7, 7, 7, 7, 7
```
- [ ] **Step 2: Replace the exact `mustSay` values for Scenes 1-8**
- [ ] **Step 2: Extend the presenter note type and constructor**
Add these required fields:
```ts
export type PresenterBeatNote = {
readonly sceneId: MainSceneId;
readonly beatId: string;
readonly targetSeconds: number;
readonly goal: string;
readonly keywords: readonly [string, ...string[]];
readonly mustSay: string;
// existing metadata remains unchanged
};
```
Add `goal` and `keywords` parameters to `beatNote()` before `mustSay`. Keep
`mustSay` as the existing field name to avoid unrelated navigation churn.
- [ ] **Step 3: Add exact goals and keywords for every beat**
Use this catalog in storyboard order:
```text
thesis/title: Goal "Separate the AI-agent ambition from the implemented contribution." Keywords "AI-agent goal", "platform underneath"
thesis/substrate: Goal "State what the platform lets its users do." Keywords "agents and humans", "build, run, inspect"
problem/direct-actions: Goal "Show why one successful chat is not yet automation." Keywords "tool calls", "not reusable"
problem/missing-contracts: Goal "Name the minimum durable properties reusable automation needs." Keywords "saved definition", "validation", "execution records"
positioning/landscape: Goal "Place the work beside familiar adjacent systems." Keywords "Python / n8n / Zapier", "LangGraph", "MCP"
positioning/lda-position: Goal "State the platform's narrow position without a superiority claim." Keywords "provider-neutral", "workflow layer", "not a replacement"
planner-runtime/planner: Goal "Assign workflow decisions to an external planner." Keywords "human or AI planner"
planner-runtime/runtime: Goal "Assign execution and recording to the runtime." Keywords "validation", "step-by-step execution", "state and traces"
planner-runtime/boundary: Goal "Introduce the public seam between clients and runtime." Keywords "Workflow API", "CLI", "JSON-RPC"
lifecycle/draft: Goal "Introduce the editable lifecycle state." Keywords "Draft", "being built"
lifecycle/artifact: Goal "Introduce the immutable saved definition." Keywords "Artifact", "immutable version"
lifecycle/deployment: Goal "Connect a saved definition to a runnable environment." Keywords "Deployment", "sources", "ready"
lifecycle/run: Goal "Introduce one persisted execution record." Keywords "Run", "status", "output and trace"
architecture/overview: Goal "Show how the implementation realizes the earlier concepts." Keywords "architecture spine"
architecture/client: Goal "Show that humans and agents share one public surface." Keywords "shared operations"
architecture/api: Goal "Identify the system's public front door." Keywords "Workflow API", "public boundary"
architecture/runtime: Goal "Explain what the server composes behind the API." Keywords "WorkflowServer", "records and capabilities", "execution core"
agent-handoff/request: Goal "Disclose the prepared demonstration before it begins." Keywords "prepared example", "not an autonomous planner"
prepared-lifecycle/discover: Goal "Show that authoring starts with interface discovery." Keywords "sources", "capabilities"
prepared-lifecycle/draft: Goal "Show mutable workflow authoring." Keywords "Draft", "editable workflow"
prepared-lifecycle/diagnose: Goal "Show a concrete structured validation failure." Keywords "validation", "missing_outcome_edge"
prepared-lifecycle/repair: Goal "Show the exact focused correction and revalidation." Keywords "set-route", "validation passes"
prepared-lifecycle/artifact: Goal "Show the transition to an immutable saved version." Keywords "Artifact", "immutable"
prepared-lifecycle/deployment: Goal "Show source binding and readiness before execution." Keywords "Deployment", "three local sources"
run-from-deployment/input: Goal "Show the concrete inputs supplied before execution." Keywords "run input", "selected documents"
run-from-deployment/operation: Goal "Show that one public operation creates a persisted execution." Keywords "workflow.runs.start", "persisted Run"
run-from-deployment/graph: Goal "Show the reusable workflow executing beyond the chat conversation." Keywords "workflow graph", "declared interrupt"
typed-human-boundary/interrupt: Goal "Show what the paused workflow asks from the operator." Keywords "issue_review", "interrupt payload", "resume schema"
typed-human-boundary/approval: Goal "Show that the operator chooses a declared continuation." Keywords "submitted", "revision-requested", "typed resume"
resume-output-evidence/resume: Goal "Show continuation of the same recorded run." Keywords "workflow.runs.resume", "same Run"
resume-output-evidence/output: Goal "Show the persisted terminal results of the submitted path." Keywords "report output", "issue-board changes"
resume-output-evidence/trace: Goal "Show that execution evidence remains inspectable after completion." Keywords "trace frames", "protocol evidence"
evaluation/cohort: Goal "Describe the external-agent evaluation design." Keywords "36 trials", "two challenges", "three profiles"
evaluation/validity: Goal "Separate audited valid evidence from contaminated samples." Keywords "27 pass", "8 invalid", "1 fail"
evaluation/findings: Goal "State what the evaluation supports and what it cannot prove." Keywords "longitudinal evidence", "not a benchmark"
conclusion/limits: Goal "Bound the prototype claims before the final contribution statement." Keywords "prototype", "not production security"
conclusion/future: Goal "Name the surrounding layers left as future work." Keywords "live agent", "scheduling", "controlled evaluation"
conclusion/conclusion: Goal "Restate the implemented contribution and planner-runtime boundary." Keywords "planner proposes", "platform executes"
conclusion/questions: Goal "Open structured examiner discussion without introducing new claims." Keywords "defense questions", "evidence"
```
- [ ] **Step 4: Replace the exact `mustSay` values for Scenes 1-8**
Use these sentences in storyboard order:
@@ -144,18 +218,60 @@ Finally, a deployment connects it to the three local sources it needs.
Preserve the existing warnings, fallbacks, evidence pointers, and Q&A branch IDs. Move the existing qualification about fixed definitions/provider variability into `optionalDetail` on `planner-runtime/runtime` if it is not already represented by `warning`.
- [ ] **Step 3: Run the focused test and verify only runbook synchronization remains RED**
- [ ] **Step 5: Run the focused test and verify only UI/runbook synchronization remains RED**
Run the focused presenter-note test. Expected: catalog/timing/word constraints pass; synchronization fails because the readable runbook still contains the old speech.
- [ ] **Step 4: Commit the typed catalog rewrite**
- [ ] **Step 6: Commit the typed catalog rewrite**
```powershell
git add web/apps/console/src/presentation/presenter/presenter-notes.ts web/apps/console/src/presentation/presenter/presenter-notes.test.ts
git commit -m "docs: simplify opening defense speech"
```
### Task 3: Synchronize The Readable Speech Runbook
### Task 3: Render Goals And Keywords In `/presenter`
**Files:**
- Modify: `web/apps/console/src/presentation/presenter/PresenterNote.tsx`
- Modify: `web/apps/console/src/presentation/presenter/PresenterNote.test.tsx`
- Modify: `web/apps/console/src/presentation/presenter/presenter.css`
**Interfaces:**
- Consumes: `PresenterBeatNote.goal`, `keywords`, and `mustSay`.
- Produces: a rehearsal surface that distinguishes the slide goal, anchor terms, and flexible wording.
- [ ] **Step 1: Write failing presenter-note tests**
Assert the current note renders regions labelled `Beat goal`, `Anchor terms`,
and `Suggested wording`. Assert every keyword is visible and that the old label
`Must say` is absent.
- [ ] **Step 2: Run the focused test and verify RED**
Run `PresenterNote.test.tsx` directly.
- [ ] **Step 3: Render the three-level rehearsal hierarchy**
Render the goal first as one concise sentence, keywords second as a plain list
of one to three strong terms, and the Markdown sentence under `Suggested
wording`. Do not render keywords as decorative pills; use readable inline text
or a compact list.
- [ ] **Step 4: Style for desktop and mobile rehearsal**
Keep the goal visually strongest, keywords high-contrast and scannable, and
suggested wording readable but subordinate. Preserve the stable Previous/Next
bar and existing Q&A sidebar.
- [ ] **Step 5: Run tests and commit**
```powershell
pnpm --dir web --filter @lda/console test -- src/presentation/presenter/PresenterNote.test.tsx
git add web/apps/console/src/presentation/presenter
git commit -m "feat: show presenter goals and anchor terms"
```
### Task 4: Synchronize The Readable Speech Runbook
**Files:**
- Modify: `docs/runbooks/defense-speech-and-claim-audit.md`
@@ -165,6 +281,10 @@ git commit -m "docs: simplify opening defense speech"
- Consumes: exact `mustSay` strings from Task 2.
- Produces: a readable rehearsal document synchronized with `/presenter`.
Add each beat's **Goal** and **Anchor terms** throughout the runbook. For Scenes
1-8, also replace the **Suggested wording** with the exact plain-text version of
Task 2's `mustSay` value so the existing synchronization test stays meaningful.
- [ ] **Step 1: Update timing prose and table**
Change the must-say target from `11:00` to `9:27`, retain a `1:15` navigation buffer, and set the complete-deck target to `10:42`. Update the Scenes 1-8 segment times to match Task 2; leave Scenes 9-13 targets unchanged.
@@ -194,7 +314,7 @@ git add docs/runbooks/defense-speech-and-claim-audit.md
git commit -m "docs: synchronize simplified defense runbook"
```
### Task 4: Close The Speech Slice
### Task 5: Close The Speech Slice
**Files:**
- Modify: `docs/current_roadmap.md`
docs/superpowers/specs/2026-07-13-defense-speech-and-scene-8-evidence-design.md
+10 -5
View File
@@ -16,8 +16,11 @@ This design separates two independently shippable changes:
## Speech Contract
Each beat has one spoken idea. The presenter may use optional notes during Q&A,
but the timed path does not require lists of architecture terms.
Each beat has one audience goal, one to three anchor terms, and one suggested
sentence. The anchor terms preserve the thesis vocabulary that identifies the
beat; the sentence is rehearsal help, not a word-for-word obligation. The
presenter may use optional notes during Q&A, but the timed path does not require
lists of architecture terms.
The simplified story is:
@@ -34,9 +37,11 @@ The simplified story is:
8. The example discovers capabilities, authors a draft, diagnoses a missing
route, repairs it, saves an artifact, and creates a deployment.
Terms such as provider neutrality, typed contracts, source resolution, explicit
resume boundaries, and NodeUse remain available in visuals, optional notes, and
Q&A. They are not mandatory opening narration.
Terms such as provider neutrality, Workflow API, Draft, Artifact, Deployment,
Run, validation, and traces remain explicit anchor terms where they identify a
slide's purpose. More detailed terms such as source resolution, explicit resume
boundaries, and NodeUse remain available in visuals, optional notes, and Q&A.
They are not mandatory opening narration.
The target for Scenes 1-8 is approximately four minutes, including navigation.
The complete must-say path should remain comfortably below the previous 11-minute