# Defense Speech Simplification Implementation Plan

> **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 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 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.

## Global Constraints

- The audience-facing storyboard remains unchanged in this slice.
- Do not remove evidence warnings, replay disclosures, or Q&A links.
- 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 Goals, Keywords, Simpler Speech, And Timing

**Files:**
- Modify: `web/apps/console/src/presentation/presenter/presenter-notes.test.ts`
- Test: `web/apps/console/src/presentation/presenter/presenter-notes.test.ts`

**Interfaces:**
- Consumes: `presenterNotes`, `presenterSceneNotes()`, `mainSpeechWordCount()`.
- Produces: regression constraints for the rewritten catalog.

- [x] **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. 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([
  "thesis",
  "problem",
  "positioning",
  "planner-runtime",
  "lifecycle",
  "architecture",
  "agent-handoff",
  "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);
}
```

- [x] **Step 2: Replace the obsolete diagnostic assertions**

```ts
expect(presenterBeatNoteFor("prepared-lifecycle", "diagnose")?.mustSay)
  .toMatch(/missing.*route/i);
expect(presenterBeatNoteFor("prepared-lifecycle", "repair")?.mustSay)
  .toMatch(/adds.*route|route.*validation passes/i);
expect(presenterBeatNoteFor("prepared-lifecycle", "diagnose")?.mustSay)
  .not.toMatch(/output projection/i);
```

- [x] **Step 3: Run the focused test and verify RED**

Run:

```powershell
pnpm --dir web --filter @lda/console test -- src/presentation/presenter/presenter-notes.test.ts
```

Expected: failures for timing, word budget, maximum beat length, and the obsolete diagnostic text.

- [x] **Step 4: Commit the failing contract**

```powershell
git add web/apps/console/src/presentation/presenter/presenter-notes.test.ts
git commit -m "test: define simpler defense speech contract"
```

### 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`
- Test: `web/apps/console/src/presentation/presenter/presenter-notes.test.ts`

**Interfaces:**
- Consumes: `beatNote()` and the existing note metadata.
- Produces: presenter goals, anchor terms, and suggested speech rendered by `/presenter`.

- [x] **Step 1: Set the new target seconds**

Use these per-beat values:

```ts
// Scene 1: 15, 15
// Scene 2: 15, 15
// Scene 3: 18, 17
// Scene 4: 12, 16, 12
// Scene 5: 9, 9, 9, 9
// Scene 6: 6, 8, 9, 9
// Scene 7: 12
// Scene 8: 7, 7, 7, 7, 7, 7
```

- [x] **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.

- [x] **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"
```

- [x] **Step 4: Replace the exact `mustSay` values for Scenes 1-8**

Use these sentences in storyboard order:

```text
The title describes the original goal: an AI agent for workspace automation. My contribution is the platform underneath that agent.
It lets agents and humans build workflows, run them, and inspect what happened.

Like the chat example, an agent can call tools and finish one task. But that conversation is not yet a reusable workflow.
Reusable automation needs a saved definition, validation, execution records, and a clear way to pause and continue.

Existing systems solve different parts of this problem: Python scripts, n8n, Zapier, LangGraph, and MCP.
My platform does not replace them. It provides a provider-neutral workflow layer that agents and humans can operate.

A human or AI planner decides what workflow to build.
The runtime validates the graph, executes it step by step, records state and traces, and pauses at declared boundaries.
Both sides communicate through the Workflow API. Today, clients reach it through the CLI or JSON-RPC without accessing runtime internals directly.

A workflow moves through four lifecycle stages. Draft means the workflow is still being built.
Artifact is a saved, immutable version.
Deployment connects that version to the sources it needs and checks whether it is ready.
Run is one recorded execution, including its status, output, and trace.

This is how those concepts are organized in the implementation.
Humans and agents use the same public workflow operations.
The Workflow API is the front door. It exposes lifecycle operations without exposing runtime internals.
Behind it, the workflow server brings together stored records, available capabilities, and the execution core.

This is a prepared example, not a live autonomous AI agent. It shows how an agent could use the platform to build and run a workflow.

First, the agent checks which sources and operations are available.
Then it builds an editable workflow draft.
Validation finds that the analyze step has no route for its ok outcome.
The agent adds that route, and validation passes.
The valid workflow is saved as an immutable artifact.
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`.

- [x] **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.

- [x] **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: 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.

- [x] **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.

- [x] **Step 2: Run the focused test and verify RED**

Run `PresenterNote.test.tsx` directly.

- [x] **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.

- [x] **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.

- [x] **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`
- Test: `web/apps/console/src/presentation/presenter/presenter-notes.test.ts`

**Interfaces:**
- 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.

- [x] **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.

- [x] **Step 2: Replace the Scene 1-8 `Say:` blocks verbatim**

Use the exact plain-text versions of Task 2's sentences. Keep claim qualifications below each block; do not require the presenter to speak them.

- [x] **Step 3: Run verification**

```powershell
pnpm --dir web --filter @lda/console test -- src/presentation/presenter/presenter-notes.test.ts
pnpm --dir web --filter @lda/console typecheck
git diff --check
```

Expected: all presenter tests pass, typecheck is clean, and no whitespace errors are reported.

- [x] **Step 4: Verify `/presenter` at desktop and mobile widths**

Open `/presenter#scene/planner-runtime/boundary` and `/presenter#scene/architecture/api` at `1280x720` and `390x844`. Confirm bold phrases remain readable, Previous/Next controls stay stable, and the simplified `mustSay` text does not overflow.

- [x] **Step 5: Commit the synchronized runbook**

```powershell
git add docs/runbooks/defense-speech-and-claim-audit.md
git commit -m "docs: synchronize simplified defense runbook"
```

### Task 5: Close The Speech Slice

**Files:**
- Modify: `docs/current_roadmap.md`
- Move after completion: `docs/superpowers/plans/2026-07-13-defense-speech-simplification.md` to `docs/historical/superpowers/plans/2026-07-13-defense-speech-simplification.md`

**Interfaces:**
- Consumes: verified implementation from Tasks 1-3.
- Produces: accurate live roadmap status and historical implementation record.

- [x] **Step 1: Mark only the speech item completed**

Leave the Scene 8 evidence item planned until its separate plan is implemented.

- [x] **Step 2: Move this completed plan and verify links**

Update the roadmap link to the historical path, run `git diff --check`, and confirm no live document points to the old active-plan path.

- [x] **Step 3: Commit docs closure**

```powershell
git add docs/current_roadmap.md docs/superpowers/plans/2026-07-13-defense-speech-simplification.md docs/historical/superpowers/plans/2026-07-13-defense-speech-simplification.md
git commit -m "docs: complete defense speech simplification"
```