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`