fix(deck): technical-review fixes — ROS-accurate runtime, Robot interface box, stable-boundary framing (deck-technical-fixes)

[OriNachum]

Five technical-review corrections to the six-slide deck, applied exactly as
reviewed. The ARM101 card stays as written.

The three fixes

1. Runtime layer is ROS-accurate. The diagram's behavior-runtime layer
   now reads "ROS-backed or native · persistent execution" over "nodes ·
   controllers · rules · intents · arbitration" — ROS 2 is not itself a
   fixed-rate behavior loop. The 50 Hz design rate leaves the generic
   architecture and lives in the stack slide's Reachy-specific spoken aside
   ("on Reachy Mini, a fixed-rate loop at a 50 Hz design rate"), still
   qualified, so the deck-wide design-rate check keeps biting. The caption
   now says "Solid lines show operational command and state paths" — ROS
   topics, services, and actions are not universally synchronous.
2. The control-plane box is "Robot interface" (CLI · JSON feed · intent
   spool). The CLI is one executable surface of the stable contract rather
   than literally every transport, so the dotted agent↔runtime feed/intent
   paths no longer contradict "the CLI is the stable bridge". The SVG's
   accessible desc narrates the same story.
3. Slide 2 softened. "These approaches can coexist. The architectural
   question is whether the robot exposes a stable boundary between what
   intelligence decides and what robot software executes." Bottom line: "What
   matters is a stable boundary." (Bounded tools can draw one — the old
   absolute is gone.)

Polish

• Close slide Reachy command is the canonical reachy-mini-cli behavior engine run.
• Source note: "reachy-mini-cli v0.42.0 separates the optional agent from
  the symbolic runtime."

Verification

TDD-first on the two pinned strings (test re-pinned, observed failing 15/2,
then dataset updated to 17/17). astro build clean, 22/22 presentation checks,
56 pytest, markdownlint clean. Version 0.17.0 → 0.17.1.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FqTq59W6wi1YZqxGf228Tt

• org (Claude)

[OriNachum]

/agentic_review

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[qodo-code-review]

PR Summary by Qodo

Fix deck technical-review wording and bump version to 0.17.1

📝 Documentation 🧪 Tests ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Correct the stack diagram copy to be ROS-accurate and clarify the control-plane as a Robot
 interface.
• Soften slide 2 framing to emphasize coexistence and the need for a stable boundary.
• Update pinned deck tests and bump release metadata to 0.17.1.

Diagram

graph TD
  A["mind-nervous-system-body-slides.ts"] --> B["Deck renderer"] --> C["Astro build / deck"]
  D["CliRuntimeStackDiagram.astro"] --> B
  E["mind-nervous-system-body-slides.test.mjs"] --> F["CI checks"] --> C
  G["pyproject.toml + uv.lock"] --> H["Release version"]
  I["CHANGELOG.md"] --> H

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Extract diagram labels into shared constants

• ➕ Prevents drift between SVG visible text, SVG , and slide/test strings
• ➕ Makes future review-driven wording changes cheaper and less error-prone
• ➖ Requires refactoring the Astro component (and possibly test structure) beyond the scope of a quick review fix

2. Generate the diagram from a single source (e.g., Mermaid → SVG)

• ➕ Single canonical representation for labels/arrows/caption
• ➕ Easier to keep docs and visuals consistent across formats
• ➖ Adds a build step/tooling complexity and may reduce fine-grained SVG control/styling

3. Add snapshot-style tests for rendered slides/diagram

• ➕ Catches unintended copy/label regressions across multiple fields at once
• ➕ Less brittle than pinning many individual strings over time
• ➖ Snapshots can become noisy and harder to review; requires stable rendering output

Recommendation: The PR’s direct string/label edits are the right approach for review-locked deck corrections and keep risk low. Consider a follow-up to centralize shared diagram copy (at least the control-plane/runtime labels and caption) to reduce duplication between visible SVG text and the accessibility narrative.

Files changed (6) +53 / -37

Tests (1) +2 / -2

mind-nervous-system-body-slides.test.mjsRe-pin tests for slide 2 bottom line and close command +2/-2

Re-pin tests for slide 2 bottom line and close command

• Updates assertions for slide 2’s bottom line (“What matters is a stable boundary.”) and the canonical Reachy command (“reachy-mini-cli behavior engine run”).

site-astro/src/data/mind-nervous-system-body-slides.test.mjs

Documentation (3) +49 / -33

CHANGELOG.mdDocument 0.17.1 deck technical-review fixes +6/-0

Document 0.17.1 deck technical-review fixes

• Adds a 0.17.1 entry describing the ROS-accurate runtime wording, Robot interface rename, caption clarification, slide 2 softening, canonical command, and updated source note.

CHANGELOG.md

CliRuntimeStackDiagram.astroUpdate architecture diagram labels and accessibility narrative +36/-27

Update architecture diagram labels and accessibility narrative

• Renames the control-plane box to “Robot interface” with sublabel “CLI · JSON feed · intent spool,” updates runtime-layer copy to “ROS-backed or native · persistent execution,” and removes the tick-rate label from the diagram. Adjusts the SVG <desc> and caption to align with ROS semantics and the stable-boundary story.

site-astro/src/components/CliRuntimeStackDiagram.astro

mind-nervous-system-body-slides.tsRevise slide copy for stable-boundary framing and Reachy command +7/-6

Revise slide copy for stable-boundary framing and Reachy command

• Softens slide 2 spoken line to explicitly allow coexistence and focuses the question on a stable boundary between deciding and executing; updates the bottom line accordingly. Moves the 50 Hz design-rate mention into the Reachy-specific spoken aside on the stack slide, updates the close-slide command to “behavior engine run,” and refines the deck source note wording.

site-astro/src/data/mind-nervous-system-body-slides.ts

Other (2) +2 / -2

pyproject.tomlBump project version to 0.17.1 +1/-1

Bump project version to 0.17.1

• Updates the package metadata version from 0.17.0 to 0.17.1 to match the deck fix release.

pyproject.toml

uv.lockSync lockfile version to 0.17.1 +1/-1

Sync lockfile version to 0.17.1

• Updates the editable project package entry to version 0.17.1 to stay consistent with pyproject.toml.

uv.lock

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 5 rules

✅ Skills: doc-test-alignment

1. Boundary terms inconsistent 🐞 Bug ≡ Correctness

Description

The architecture diagram now defines the control plane as a “Robot interface” with three distinct
surfaces (CLI, JSON feed, intent spool), but the slide narration still calls the boundary a “stable
CLI”/“CLI line” and claims the CLI “opens all three surfaces.” This makes the deck’s core boundary
story internally contradictory and undermines the technical-review accuracy goal of this PR.

Code

site-astro/src/components/CliRuntimeStackDiagram.astro[R137-143]

+        <text x="600" y="296" text-anchor="middle" class="layer-title layer-title-lg">Robot interface</text>
        <text x="600" y="326" text-anchor="middle" class="layer-sub layer-sub-lg">
-          inspect · configure · intervene
+          CLI · JSON feed · intent spool
        </text>
        <text x="600" y="350" text-anchor="middle" class="layer-sub layer-sub-lg">
-          start / stop / status · JSON contracts
+          inspect · configure · intervene · JSON contracts
        </text>

Relevance

⭐⭐⭐ High

Team accepted prior deck terminology consistency fix (SO-ARM101 naming mismatch) in presentation
content.

PR-#25

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The diagram explicitly lists three control-plane surfaces under “Robot interface”, while slide copy
continues to describe the control plane/boundary as the CLI and attributes all surfaces to it,
creating a direct terminology/meaning mismatch within the same deck.

site-astro/src/components/CliRuntimeStackDiagram.astro[134-143]
site-astro/src/data/mind-nervous-system-body-slides.ts[200-208]
site-astro/src/data/mind-nervous-system-body-slides.ts[211-221]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The deck’s diagram now models a control-plane **Robot interface** with multiple surfaces, but slide copy still frames the contract/boundary as the **CLI** itself and incorrectly attributes “all three surfaces” to the CLI.

## Issue Context
This PR intentionally changed the diagram to avoid the “CLI is the stable bridge” vs dotted agent↔runtime path contradiction by introducing **Robot interface (CLI · JSON feed · intent spool)**. The slide copy should be updated to use the same boundary terminology and accurately describe which surfaces the agent/human use.

## Fix Focus Areas
- site-astro/src/data/mind-nervous-system-body-slides.ts[200-221]
- site-astro/src/components/CliRuntimeStackDiagram.astro[134-143]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Plan command out of date 🐞 Bug ⚙ Maintainability

Description

The close-slide Reachy command was updated to reachy-mini-cli behavior engine run, but the
exported plan doc still states reachy-mini-cli behavior engine start in its acceptance criteria.
This leaves repo documentation inconsistent with the deck’s pinned command string.

Code

site-astro/src/data/mind-nervous-system-body-slides.ts[253]

+        command: "reachy-mini-cli behavior engine run",

Relevance

⭐⭐ Medium

No clear precedent for updating exported docs/plans when commands change; plans may be treated as
frozen artifacts.

PR-#24

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The slide dataset now pins behavior engine run, but the plan doc’s acceptance criteria still names
behavior engine start, so the repository contains conflicting guidance for the same deck command.

site-astro/src/data/mind-nervous-system-body-slides.ts[248-254]
docs/plans/2026-07-22-deck-six-slide-narrative.md[14-18]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A docs plan file still references the old Reachy close-slide command (`... start`) after the deck was updated to the canonical `... run`.

## Issue Context
The slide dataset and its tests now pin the new command. The plan doc should be updated so manual validation/checklists don’t diverge from the actual deck contract.

## Fix Focus Areas
- docs/plans/2026-07-22-deck-six-slide-narrative.md[14-18]
- site-astro/src/data/mind-nervous-system-body-slides.ts[248-254]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---