docs(plans): BEAST-01 rebuild execution ladder — rungs, artifact design, rung-0 decisions

[Coldaine]

Description

Adds the execution ladder for the BEAST-01 clean-room rebuild as a companion work order to the governing plan held on #247. The plan on #247 owns what survives and why (preserve list, evidence, watch-outs); this document owns how the work is sequenced: nine rungs (ratify → knowledge extraction + memory triage → pin the world → CI proof → beast_hardware → C1 side-by-side → C2 fresh metal → cutover + single-commit delete → close out), with the invariant that the robot is never broken below rung 7 and every rung is revertible.

It also records, so nobody rebuilds them, the pieces that already exist: self-hosted runners (moosegoose-general, moosegoose-n5-large), the arm64 beast-ros GHCR image build with buildx/GHA layer caching, and the rollback-proven source-mode beast-pull deploy (2026-08-14 supervised rollout).

Rung 0 names the five owner decisions that gate execution, with recommendations: merge #247 (with DB-cited numbers, including resolving the 8.332 vs 8.368 V pack-trip discrepancy), decide ugv_cockpit (recommend temporary shim with expiry), pick the artifact form, keep one repo (re-evaluate after cutover), and optionally run the autonomy on-ramp's first real mapping run on the old stack pre-cutover so rung 5's side-by-side has a real map to compare against. Rung 1 adds the evidence-class triage of the insights DB (measurement / identity / diagnosis / procedure) so mis-diagnosed incidents stop passing as facts without deleting recorded history.

The second commit is a research pass over current Jetson/ROS deployment practice (container-vs-native on Jetson, L4T/JetPack base-image alignment, ROOTFS_AB/nvbootctrl field reports, QEMU-vs-native arm64 CI build numbers). It moved the artifact-form recommendation to container as the deploy vehicle — the artifact CI proves is byte-for-byte what the robot runs, and the CPU-only stack sidesteps the L4T/CUDA alignment trap today, with the GPU-era base-image rule recorded alongside the decision. Release-dir A/B stays as the rung-5 fallback; OS-layer ROOTFS_AB stays out of scope with its failure modes named. Rung 3 gains the QEMU cost figures and the native-arm64-runner escape hatch.

The third commit folds in owner-discussion findings from 2026-08-28: three preserve-list candidates the six knowledge items do not cover (the camera-to-cockpit pipeline, decided by NORTH_STAR G7 naming video as a portal surface; the autonomy on-ramp Phase 1 calibration constants and ekf.yaml fusion config, whose operative values live in old-tree files Phase D deletes; kinematics/URDF from ugv_description), the optional pre-cutover mapping run as decision 5, and a plans-directory harvest rule at rung 1 — hazards that exist only in plan prose (rosbridge bare-NaN, keyboard_ctrl SIGHUP, time-sync ordering, ESP32 velocity latch) land as insights before their code dies, and plans die with their target code at rung 8.

Branch Scope

• I reviewed all work currently on this branch.
• I confirmed which branch changes belong in this PR.
• Branch/work reviewed: single coherent branch — three commits, two files (new plan + index row; the research amendment; the owner-discussion amendment).
• Included here: all branch changes.
• Excluded or left for a later PR: None.

PR Shape

• I considered whether this work should be split into multiple PRs.
• Rationale: one plan document plus its required index entry is a single review unit; the subsequent amendments revise that same document, so they belong in the same review.

Independent Review

• I called a subagent or independent reviewer and incorporated or recorded the result.
• Not called because this change was narrow/mechanical, no suitable reviewer was available, or this branch already received equivalent review.
• Review notes: docs-only work order whose substance is precisely what the owner must review — it exists to be ratified or amended at rung 0, and its parent plan already received independent review on docs(plans): BEAST-01 platform rebuild — tear it down, keep a short list, build it back #247. The artifact-form section was checked against external practitioner sources (Jetson container base-image alignment guidance, ROOTFS_AB/nvbootctrl field reports, QEMU-vs-native arm64 CI measurements) rather than a code reviewer, which is the review that section needed. The third commit's additions come from an owner discussion cross-checked against the tree (ugv_vision entry points, build_first.sh allowlists, the on-ramp plan's executed-phase record).

Documentation

• Documentation updates made: docs/plans/2026-08-27-beast-rebuild-execution-ladder.md (new work order, then research and owner-discussion amendments), docs/plans/README.md (index row, per the plans-directory convention).
• Documentation considered but not changed: docs/deploy.md, docs/beast-ops.md, AGENTS.md — the ladder assigns their updates to rung 8 (close-out) rather than editing them ahead of executed work; docs/NORTH_STAR.md untouched by design.
• Documentation workflow: AGENTS.md "Where docs live" followed — proposed work goes in docs/plans/ with an index entry; no owner doc claims changed state.

Superseded Docs / Cleanup

• Current or superseded docs reviewed: the docs(plans): BEAST-01 platform rebuild — tear it down, keep a short list, build it back #247 rebuild plan (this document defers to it and contradicts nothing in it), the 2026-08-14 plan set (execution-order section left untouched; the ladder notes the strip-down and vendored-surface plans retire at rung 8, matching what docs(plans): BEAST-01 platform rebuild — tear it down, keep a short list, build it back #247 already states).
• Cleanup performed: None — retirement of the superseded plans is scheduled work (rung 8), not a side effect of proposing it.
• Wording/change rationale: the index row mirrors the existing table's voice (what it covers / what blocks); the plan states it is subordinate to docs(plans): BEAST-01 platform rebuild — tear it down, keep a short list, build it back #247 so the two documents cannot compete for authority.

Validation

• Checks run: git diff --check (clean); manual verification of every repo-state claim in the document against the tree (workflow names, runner labels, cache config in .github/workflows/beast-ros-image.yml, deploy state in docs/deploy.md, feat(beast): autonomy stack overhaul - explore_lite, tuned Nav2/SLAM params, base_node limits #245's post-plan changes, ugv_main/ugv_else package inventory and build allowlists); external-practice claims checked against multiple independent sources before landing.
• Checks skipped: web/robot test suites — no code touched.

Risk / Rollback

• Risk: Low — a proposed work order that explicitly does not govern ("code is truth" per the plans README) and whose rung 0 requires owner ratification before anything executes.
• Rollback: revert this PR; the plans index row goes with it.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Ev2gEVzf2qQyfpW2hyzynG

[qodo-code-review]

ⓘ Your Qodo trial ends soon. Ask your workspace admin to set up billing to keep reviews running after the trial. Manage billing