docs: record 14 Jul session design — widget wiring map, depth dual-source, fault-injection required, FSM rework top priority

docs/design_intent_register.md v1.5:
- New DIR-13 — widget-to-hardware ownership map. W1 is a two-stage health
  gate: RPi4 FC-heartbeat MUST pass first (implemented, 86b2728), then RPi5
  autonomy-stack self-health (not yet built) — only when both pass is W1
  GREEN. W5 reflects the RPi4-connected battery. W2/W3/W4/W6/W8 reflect the
  RPi5 stack; W6 deliberately kept RPi5-direct per the standalone-autonomy
  principle. W7 specced, not built. Cross-references DIR-12.
- New DIR-14 — depth as a dual-source, operator-selectable input: RPi4
  sensor (via the FC), an RPi5-direct sensor, or a blend, selected at
  mission setup (W4) and carried in the resolved mode profile like
  health_role. Redundancy plus operator choice. Design-captured, not yet
  specified in detail.

docs/handover.md v2.27:
- New §9 widget-to-hardware wiring table matching the DIR-13 ownership map.
- Test-data/fault-injection capability flagged as an approaching required
  workstream, not optional — the failsafe logic (and the pending count-
  based FSM rework) cannot be properly tested without injecting sensor
  states and simulating running-vs-failed conditions. Incremental approach
  agreed: altitude/depth/sonar first. Near-term prerequisite for validating
  the FSM rework; added to §0 PARKED/NEXT and §16.
- FSM rework to the corrected count-based model (255096f) reconfirmed as
  top build priority — 2a3e577/bf815cc's condition-clear commit logic
  remains known-wrong pending that rework. Recorded as related to, and to
  be planned alongside, W1's RPi5-side health gating (DIR-13) and the
  fault-injection capability above.
- Confirmed and recorded: W2 reflects live mission state (observed ABORTED
  after a live abort); W3's label change to RETURN TO SAFE is complete
  (9aa5b5d) — stale references to this as outstanding work corrected in
  §0 Blocked/Open Items/NEXT and §16. argonaut-api.service manual-start
  reminder recorded for rov_api/backend testing.
- DIR pointer section bumped to DIR-1 through DIR-14.

Documentation only — no code, widget, or diagram files touched. Not
uploaded to Claude project knowledge; that remains a manual step.

docs/design_intent_register.md

@@ -1,7 +1,7 @@
 # Design Intent Register — Argonaut 3
 
-**Version:** 1.4
+**Version:** 1.5
-**Date:** 13 July 2026
+**Date:** 14 July 2026
 **File:** `docs/design_intent_register.md` (repo-tracked, no version number in filename)
 
 **Purpose of this register:** Capture operator/owner *intent* — what each behaviour MEANS and MUST/MUST NOT do — separately from mechanism (topics, code). Mechanism is recorded elsewhere. This register is the source of truth for *why*, against which any implementation is validated. Every entry dated and attributed.
@@ -12,6 +12,7 @@
 
 | Version | Date | Change |
 |---|---|---|
+| 1.5 | 14 Jul 2026 | **Two new DIRs — documentation-only pass, no code changed.** **DIR-13 — widget-to-hardware ownership map:** records which subsystem (RPi4 gateway vs RPi5 autonomy brain) each widget reflects, as owner-stated intent. W1 is a two-stage health gate — FC heartbeat on RPi4 MUST pass first (already implemented, `86b2728`, 11 Jul), then RPi5 autonomy-stack self-health (not yet built); only when both pass is W1 GREEN. W5 reflects the RPi4-connected battery. W2/W3/W4/W6/W8 reflect the RPi5 stack; W6 altitude is deliberately kept RPi5-direct, consistent with the standalone-autonomy principle (BlueOS/Cockpit integration is the only current external dependency). W7 specced, not built. Cross-references DIR-12. **DIR-14 — depth is a dual-source, operator-selectable input:** depth may come from an RPi4 sensor (via the FC) or an RPi5-direct sensor; the system should support selecting one, the other, or a blend, chosen at mission setup (W4) and carried in the resolved mode profile like other settings. Redundancy plus operator choice; consistent with the same standalone-autonomy principle as DIR-13/W6. Design-captured intent for a future build, not yet specified in detail. |
 | 1.4 | 13 Jul 2026 | **CORRECTION: DIR-7 "in-mission recovery is mode-dependent" addendum was inverted — fixed.** The 11 Jul wording had AUV gate mode commit to recovery ON CONDITION-CLEAR; that produced a contradictory GREEN-while-in-`RETURN_TO_SAFE` state observed live. Corrected model: GREEN is unconditionally a working state; committed recovery is triggered by fault PERSISTENCE or RECURRENCE, never by clearing. Records a three-tier fault model (uncontrollable/out-of-scope for the FSM; transient/self-resetting with a raw failure-count trigger, deliberately no time window; hard/persistent, a RED that doesn't clear) with all thresholds configuration-driven via the resolved mode profile, same as `health_role`. Records what survives (health_role mode-awareness from `2a3e577`; the safe-zone-reached arrival-exit mechanism from `bf815cc`, unchanged in role) vs what's retired (the condition-clear entry logic in `2a3e577`, which `bf815cc` built its exit on top of) — pending next-session rework into the count-based model. **New Parked Design Item:** adaptive restart-timing (monitor own restore count/duration, weigh future attempts against observed history rather than a fixed time) — depends on the count-based retry machinery above existing first; design-captured, not build-specified. |
 | 1.3 | 13 Jul 2026 | **New Parked Design Item:** mode-aware safe-zone-reached arrival event (relates to the DIR-7 "in-mission recovery is mode-dependent" addendum) — the permanent `/rov/nav/safe_zone_reached` interface, mode-aware/sensor-derived arrival judgement (GPS at surface + EKF/dead-reckoning underwater), GPS recorded as first-class across mission types (not a hull/jacket-specific surface concern), gate-only scope, and the temporary W1-button bench-scaffolding publisher pending navigation. Implemented same day in `failsafe_monitor` (`bf815cc`) — see `docs/handover.md` §15f for the fix narrative; this entry records the design intent, not the commit detail. DIR-7 addendum's Implementation note updated: the mode-dependent recovery mechanism is no longer mode-blind (`2a3e577`, 13 Jul 2026). |
 | 1.2 | 11 Jul 2026 | **DIR-7's FC-connectivity MUST — RESOLVED**, four commits 11 Jul 2026 (full detail in `docs/handover.md` Changelog); open-flag callout updated accordingly. **DIR-7 gains two addenda:** in-mission recovery is mode-dependent (AUV commits to recovery on condition-clear, does not auto-resume; ROV holds and hands the continue-or-recover decision to the operator); and in-mission AMBER runtime-response (AMBER means action-required, not just informational, once a mission is underway — response branches by mode, AUV's autonomous curtailment logic left unspecified pending further design). **New "Parked Design Items" section** — auto-recovery (failsafe_monitor should attempt to re-establish the FC link itself before escalating) and a dedicated `string cause` field in `FailsafeStatus.msg` (replacing the `cockpit_bridge` message-substring shortcut) — both tracked as open implementation gaps against existing DIR-7/12 intent, not new decisions. Filename de-versioned as part of the 11 Jul doc restructure — this file moved into the repo `docs/` folder. |
@@ -497,6 +498,84 @@ are "is the vehicle actually going to keep talking to me" questions.
 
 ---
 
+## DIR-13 — Widget-to-hardware ownership map
+
+**Source:** Grant, 14 Jul 2026 session.
+
+**Intent:** Record, as owner-stated intent, which physical subsystem (RPi4 BlueOS gateway vs
+RPi5 autonomy brain) each Cockpit widget actually reflects — the wiring picture behind the UI,
+so it is not left to be inferred from code. Relates directly to DIR-12 (vehicle health and
+autonomy health are distinct subjects) — this DIR is the widget-level instance of that same
+distinction, enumerated per widget rather than argued in the abstract.
+
+**W1 (System Health Indicator) is a two-stage health gate, not a single-subsystem readout:**
+1. **Flight-controller heartbeat (RPi4 gateway) MUST pass first.** A dead or unreachable FC
+   makes autonomy meaningless regardless of how healthy the RPi5 stack is — this is DIR-12's
+   "vehicle health is distinct from autonomy health" applied concretely. **Already implemented**
+   (commit `86b2728`, 11 Jul 2026) — `failsafe_monitor` forces RED on FC comms loss.
+2. **RPi5 autonomy-stack self-health** — nodes alive, EKF converged, recorder active, bridge up
+   — is the second stage. **Not yet built.**
+
+Only when both stages pass is W1 GREEN. W1 is not "an RPi5 stack indicator" and never was
+intended to be one — the FC-heartbeat stage is what makes it a *vehicle* health gate rather
+than an *autonomy* health gate (DIR-12).
+
+**Per-widget ownership (owner-stated intent):**
+- **W1 (System Health Indicator)** — BOTH: RPi4 (FC heartbeat, implemented) + RPi5 (autonomy
+  self-health, not yet built). See above.
+- **W2 (Mission Status)** — RPi5 (`mission_executor`).
+- **W3 (Return To Safe button)** — RPi5 (`failsafe_monitor` via `/rov/mission/abort`).
+- **W4 (Mission Setup button)** — RPi5 (FastAPI setup page, not yet built).
+- **W5 (Return Budget)** — RPi4. Reflects the battery, which is connected to the RPi4 (via
+  MAVROS/Pixhawk), not the RPi5.
+- **W6 (Altitude)** — RPi5. **Deliberately** kept sourced direct from the RPi5 (Ping2 on RPi5),
+  not routed via the RPi4 — consistent with the principle that the autonomy unit should be
+  standalone, with BlueOS/Cockpit integration as its only current external dependency.
+- **W7 (Backup Due Notice)** — RPi5 (+ server, Option A design). Specced, not built.
+- **W8 (Mode Indicator)** — RPi5 (`mode_profile_loader`).
+
+**Must:** Keep this ownership map in sync with `docs/handover.md`'s current-state material —
+that document carries the same table for quick operator reference; this entry is the intent
+record, that one is the live status pointer.
+
+**Must not:** Let a widget's *apparent* subject (what it visually looks like it's reporting on)
+diverge from its *actual* data source without recording the divergence here — this is exactly
+the DIR-12 failure mode (a green light that doesn't say what it's green about).
+
+---
+
+## DIR-14 — Depth is a dual-source, operator-selectable input
+
+**Source:** Grant, 14 Jul 2026 session.
+
+**Intent:** Depth may be sourced from a sensor on the RPi4 (via the flight controller) OR a
+sensor added directly to the RPi5, and the system should support selecting one source, the
+other, or a blend of both — chosen at mission setup time (associated with the W4 Mission Setup
+widget) and carried in the resolved configuration the same way other mode-profile settings
+(e.g. `health_role`) are, not hardcoded.
+
+**Rationale — redundancy plus operator choice:** Two independent depth sources give a fallback
+if one fails, and let the operator (or the setup wizard) pick whichever is more trustworthy for
+a given deployment, rather than the system being permanently committed to one sensor's data
+path.
+
+**Consistent with the standalone-autonomy principle (see DIR-13):** an RPi5-direct depth sensor
+means the RPi5 autonomy unit is not solely dependent on the RPi4 for this input — the same
+reasoning already applied to W6 altitude.
+
+**Must (once built):** Read the selected depth source (RPi4 / RPi5 / blend) from the resolved
+mode profile, the same mechanism `health_role` and the other mode-profile flags already use —
+never hardcode a single source.
+
+**Must not:** Assume depth always comes from one fixed sensor path. Both paths are legitimate;
+the choice is a configuration, not a constant.
+
+> **Status:** Design-captured intent for a future build. Not yet specified in detail — no
+> sensor selection mechanism, blending algorithm, or config-profile field decided here, only
+> the shape of the requirement (dual-source, operator-selectable, mode-profile-carried).
+
+---
+
 ## Parked Design Items (intent-adjacent, not yet actioned)
 
 Tracked here so they aren't lost between sessions. Not full DIR entries — each is an

docs/handover.md

@@ -1,7 +1,7 @@
 # ROV Autonomous Inspection System — Project Handover
 **Project Name:** Argonaut 3
-**Version:** 2.26
+**Version:** 2.27
-**Date:** 13 July 2026
+**Date:** 14 July 2026
 **File:** `docs/handover.md` (repo-tracked, no version number in filename — see Version History for versioning)
 
 **This document is the single source of truth for current project state** — what's built,
@@ -34,6 +34,17 @@ GREEN is unconditionally a working state. The safe-zone-reached arrival EXIT mec
 (`bf815cc`) is unaffected and still correct; only the ENTRY trigger needs rework. This is the
 **top-priority next-session task** — see §0 NEXT and §15g.
 
+✅ **Documentation-only session (14 Jul 2026)** — no code changed. Recorded: a widget-to-hardware
+wiring map (`docs/design_intent_register.md` DIR-13 — W1 is a two-stage gate, RPi4 FC-heartbeat
+already implemented + RPi5 self-health not yet built; W5 reflects the RPi4-connected battery;
+W6 deliberately kept RPi5-direct); depth as a dual-source, W4-selectable input (DIR-14, future
+build); test-data/fault-injection flagged as an approaching required workstream, not optional,
+needed to validate the FSM rework; and the FSM rework itself reconfirmed as top build priority,
+planned together with W1's RPi5-side health gating and the fault-injection capability. Also
+confirmed this session: W2 reflects live mission state (observed `ABORTED` after a live abort);
+W3's label change to "RETURN TO SAFE" is complete (`9aa5b5d`). See §0 and Changelog, 14 Jul
+entries.
+
 > Full narrative for each prior version is in Version History below — not repeated here.
 
 ---
@@ -97,8 +108,10 @@ GREEN is unconditionally a working state. The safe-zone-reached arrival EXIT mec
 - All three (Gitea/laptop/RPi5) level at `4e48dc2`.
 
 **UNTESTED (visual/UI confirmed, real data not flowing yet):**
-- W2 Mission Status — UI confirmed (IDLE state + progress bar). Untested: needs a mission
+- W2 Mission Status — **partially verified live (14 Jul 2026):** observed `ABORTED` state
-  running. Test: `POST /mission/start` via FastAPI (now available) with a loaded plan, observe widget.
+  correctly reflected after a live abort. Still untested: `RUNNING` state + progress bar during
+  an actual active mission. Test: `POST /mission/start` via FastAPI (now available) with a
+  loaded plan, observe widget.
 - W4 Mission Setup Button — UI confirmed (cyan button, opens setup URL). Untested: needs a
   setup page served by FastAPI (not yet built — Stage 2b/Phase 6).
 - W5 Return Budget — UI confirmed (shows pending). Untested: bridge does not yet publish
@@ -106,9 +119,10 @@ GREEN is unconditionally a working state. The safe-zone-reached arrival EXIT mec
   discussion — "shortest path to safety" concept to be defined).
 
 **BLOCKED / NOT BUILT:**
-- W3 RETURN TO SAFE button — backend now LIVE (`/abort` verified end-to-end). Remaining:
+- ~~W3 RETURN TO SAFE button — label/host~~ **DONE (14 Jul 2026, `9aa5b5d`):** label changed to
-  update widget code label from "ABORT MISSION" to "RETURN TO SAFE" and set `FASTAPI_HOST`
+  "RETURN TO SAFE"; `FASTAPI_HOST` found already correct at `http://192.168.1.101:8081`.
-  to `http://192.168.1.101:8081`.
+  Backend (`/abort`) already verified end-to-end. Remaining: click-test the button itself in
+  Cockpit (the underlying `/abort` path is already independently verified).
 - W4 setup page — the page FastAPI would serve is not built (Stage 2b/Phase 6).
 - W5 return budget — `/return_budget` endpoint deferred to Stage 2b.
 - W7 Backup Due Notice — not built. Depends on FastAPI `/backup/*` (Stage 2b, Option A design:
@@ -116,7 +130,8 @@ GREEN is unconditionally a working state. The safe-zone-reached arrival EXIT mec
 - `external/rov-return-budget` — not published by cockpit_bridge. W5 budget figure pending.
 
 **OPEN ITEMS / HOUSEKEEPING:**
-- W3 widget code: update button label to "RETURN TO SAFE"; set `FASTAPI_HOST` constant.
+- ~~W3 widget code: update button label to "RETURN TO SAFE"; set `FASTAPI_HOST` constant.~~
+  DONE 14 Jul 2026 (`9aa5b5d`).
 - W6 full test: hardware-gated on Ping2 sonar purchase (Phase 3, ~$280 USD).
 - RPi5 SSH password: weak dev password. Harden before field deployment (bundled with UFW).
 - UFW: inactive on RPi5. Deferred to pre-field/pre-remote hardening pass (no online exposure
@@ -172,19 +187,37 @@ GREEN is unconditionally a working state. The safe-zone-reached arrival EXIT mec
    `rov_api` endpoint + data lake variable already built, `2def2b1`) is PAUSED pending this
    rework — see Open Items above and §15g. Advisory mode's operator resume is also still a
    placeholder topic pending the proper `rov_api` endpoint.
-3. **Auto-recovery** — `failsafe_monitor` should attempt to re-establish the FC link itself,
+3. **Test-data / fault-injection capability — APPROACHING REQUIRED, not optional (14 Jul
+   2026).** The failsafe logic — and the count-based FSM rework above in particular — cannot be
+   properly tested without the ability to inject sensor states and simulate
+   running-vs-failed sensor conditions. Agreed approach is **incremental**: start with the
+   sensors that matter now (altitude, depth, sonar) and the ability to mark each as running or
+   failed to exercise FSM transitions — not a full simulation build up front. Near-term
+   prerequisite for validating item 2. Plan together with item 2 and item 4 below.
+4. **W1 RPi5-side autonomy self-health gating (DIR-13, 14 Jul 2026).** W1 is intended as a
+   two-stage gate: RPi4 FC-heartbeat (stage 1, **already implemented**, `86b2728`) then RPi5
+   autonomy-stack self-health (stage 2, **not yet built** — nodes alive, EKF converged, recorder
+   active, bridge up). Only when both pass should W1 be GREEN. Related to, and should be
+   planned alongside, item 2 (FSM rework) and item 3 (fault-injection) above — all three are
+   failsafe/health workstreams that touch the same code.
+5. **Auto-recovery** — `failsafe_monitor` should attempt to re-establish the FC link itself,
    escalating/holding RED only if it cannot. Real-world dives have no operator to restore comms.
    **Intent now recorded** in DIR's Parked Design Items (11 Jul 2026) — implementation still open.
-4. **Dedicated `string cause` field** in `FailsafeStatus.msg`, to replace the message-substring
+6. **Dedicated `string cause` field** in `FailsafeStatus.msg`, to replace the message-substring
    shortcut currently used in `cockpit_bridge`. **Intent now recorded** in DIR's Parked Design
    Items (11 Jul 2026) — implementation still open.
-5. **Operator control surface** (start/pause/stop via `rov_api`) and one-command stack
+7. **Operator control surface** (start/pause/stop via `rov_api`) and one-command stack
    startup + healthcheck.
-6. **UFW / SSH pre-field hardening** — see Open Items above.
+8. **UFW / SSH pre-field hardening** — see Open Items above.
-7. **In-mission AMBER runtime-response** — AMBER means action-required once a mission is
+9. **In-mission AMBER runtime-response** — AMBER means action-required once a mission is
    underway, not just informational; response branches by mode. **Intent now recorded** as a
    DIR-7 addendum (11 Jul 2026) — AUV's autonomous curtailment logic is unspecified, left for
    a dedicated design session.
+10. **Depth dual-source, operator-selectable input (DIR-14, 14 Jul 2026).** Depth from an RPi4
+    sensor (via the FC), an RPi5-direct sensor, or a blend — selected at mission setup (W4) and
+    carried in the resolved mode profile like `health_role`. Redundancy plus operator choice;
+    consistent with the standalone-autonomy principle already applied to W6 altitude.
+    Design-captured intent for a future build, not yet specified in detail.
 
 **NEXT (priority order, carried from §12):**
 1. **FSM entry-trigger rework — count-based fault-persistence model (TOP PRIORITY, 13 Jul
@@ -195,23 +228,28 @@ GREEN is unconditionally a working state. The safe-zone-reached arrival EXIT mec
    that doesn't clear — immediate commit); all thresholds config-wizard-driven via the resolved
    mode profile, like `health_role`. The safe-zone-reached arrival EXIT mechanism (`bf815cc`)
    needs no rework — only the entry trigger.
-2. **Safe-zone-reached arrival button (bench scaffolding) — PAUSED, waiting on item 1.**
+2. **Test-data / fault-injection capability (14 Jul 2026) — near-term prerequisite for item 1.**
+   Incremental: start with altitude/depth/sonar and the ability to mark each running or failed,
+   to exercise FSM transitions. Not a full simulation build up front. Plan together with item 1
+   and the W1 RPi5-side health gating item in §0 PARKED.
+3. **Safe-zone-reached arrival button (bench scaffolding) — PAUSED, waiting on item 1.**
    `rov_api`'s `POST /nav/safe_zone_reached` endpoint and the `external/rov-failsafe-state` data
    lake variable it depends on are built and committed (`2def2b1`); a pre-edit W1 widget backup
    was made per CREATE-THEN-BACKUP. The widget edit itself is not started — the button would
    surface FSM state reached via the known-wrong trigger above, so it is meaningless until item
    1 lands. Disposable once navigation can raise the real GPS/EKF-derived arrival event on the
    same permanent topic. See §15g, DIR-7 addendum, and the Parked Design Items.
-3. **W3 widget code**: update label to "RETURN TO SAFE", set `FASTAPI_HOST` =
+4. ~~**W3 widget code**: update label, set `FASTAPI_HOST`~~ **DONE (14 Jul 2026, `9aa5b5d`).**
-   `http://192.168.1.101:8081`, then test W3 end-to-end (button → /abort → FSM, already
+   Remaining: click-test the button itself in Cockpit end-to-end (the underlying `/abort` path
-   verified server-side).
+   is already independently verified server-side).
-4. **Stage 2b design decisions** (deferred pending Grant): return budget "shortest path to
+5. **Stage 2b design decisions** (deferred pending Grant): return budget "shortest path to
    safety" concept; W7 backup notice (Option A confirmed: server read-only JSON, RPi5 polls
    outbound).
-5. **W2 testing**: test with live mission via `POST /mission/start` (backend now available)
+6. **W2 testing** — **partially done (14 Jul 2026):** `ABORTED` state confirmed live. Remaining:
-   + loaded plan.
+   test `RUNNING` state + progress bar via `POST /mission/start` (backend now available) with a
-6. **Ping2 sonar purchase** (~$280 USD): required for W6 full end-to-end test.
+   loaded plan.
-7. **Pre-field hardening pass**: UFW + RPi5 SSH password (bundled, triggered before remote
+7. **Ping2 sonar purchase** (~$280 USD): required for W6 full end-to-end test.
+8. **Pre-field hardening pass**: UFW + RPi5 SSH password (bundled, triggered before remote
    ops/field).
 
 **DATA LAKE VARIABLES (19 total, published by cockpit_bridge):**
@@ -273,6 +311,7 @@ GREEN is unconditionally a working state. The safe-zone-reached arrival EXIT mec
 
 | Version | Date | Changes |
 |---|---|---|
+| 2.27 | 14 Jul 2026 | **Documentation-only session — no code changed.** Records design surfaced in discussion: (1) widget-to-hardware wiring map (`docs/design_intent_register.md` DIR-13) — W1 is a two-stage gate (RPi4 FC-heartbeat, already implemented `86b2728`; RPi5 autonomy self-health, not yet built); W5 reflects the RPi4-connected battery; W2/W3/W4/W6/W8 reflect RPi5; W6 deliberately kept RPi5-direct (standalone-autonomy principle); W7 specced, not built. New §9 wiring table added. (2) Depth as a dual-source, W4-selectable input (DIR-14) — RPi4 sensor, RPi5-direct sensor, or a blend, carried in the resolved mode profile like `health_role`; design-captured, future build. (3) Test-data/fault-injection capability flagged **approaching required, not optional** — the failsafe logic (and the pending count-based FSM rework) cannot be properly tested without injecting sensor states and simulating running-vs-failed conditions; incremental approach agreed (altitude/depth/sonar first, mark running/failed), not a full simulation build up front; near-term prerequisite for validating the FSM rework. (4) FSM rework to the corrected count-based model (`255096f`) reconfirmed as top build priority — `2a3e577`/`bf815cc`'s condition-clear commit logic remains known-wrong pending that rework; the rework, W1's RPi5-side health gating, and the fault-injection capability are related and should be planned together. Also confirmed this session: W2 reflects live mission state (observed `ABORTED` after a live abort — §0 UNTESTED updated); W3's label change to "RETURN TO SAFE" is complete (`9aa5b5d` — §0 Blocked/Open Items/NEXT updated, §16 row marked resolved); `argonaut-api.service` is manual-start and must be started for any `rov_api`/backend testing. §0 Confirmed Working, Blocked/Not Built, Open Items, PARKED, NEXT, §9, §16, and the DIR pointer section all updated. Companion DIR bump: `docs/design_intent_register.md` v1.5 — see that changelog for the full DIR-13/14 text, not repeated here. |
 | 2.26 | 13 Jul 2026 | **Same-day correction, extending v2.25's record.** The mode-aware recovery built earlier today (`2a3e577`) was found to be internally contradictory: its gate-mode entry trigger commits to `RETURN_TO_SAFE` ON CONDITION-CLEAR, which produced a live state that should not be possible — W1 showing GREEN ("Systems nominal") while the vehicle sat in `RETURN_TO_SAFE` ("Recovering to safe zone"). Corrected in `docs/design_intent_register.md` v1.4 (`255096f`): GREEN is unconditionally a working state; committed recovery is triggered by fault PERSISTENCE (transient tier — config-driven raw failure count, deliberately no time window) or immediate hard-persistence (RED that doesn't clear), never by condition-clear; all thresholds config-wizard-driven via the resolved mode profile like `health_role`. Survives unaffected: `health_role` mode-awareness (`2a3e577`'s subscription mechanism) and the safe-zone-reached arrival EXIT mechanism (`bf815cc`) — only ENTRY into committed recovery was wrong. `2a3e577`'s entry logic is now flagged KNOWN-WRONG pending rework, which is the new top-priority NEXT item, ahead of everything previously listed. Also recorded: (1) the W1 safe-zone-reached button is PAUSED, not abandoned — its `rov_api` endpoint (`POST /nav/safe_zone_reached`) and the `external/rov-failsafe-state` data lake variable are built and committed (`2def2b1`), a pre-edit W1 widget backup was made per CREATE-THEN-BACKUP, but the widget edit itself was not started because the FSM state it would surface is reached via a known-wrong trigger; (2) a recurring `rov_mission` build failure (recurred 2-3 times) was root-caused to stray nested `build`/`install`/`log` directories inside `src/rov-autonomy` on RPi5 (from `colcon build` run from the wrong directory), colliding with the real workspace at `/data/ros2_ws` — fixed by removing the stray directories (gitignored, local cleanup only, no git change); durable guard recorded: `colcon build` only ever from `/data/ros2_ws`. §0 Confirmed Working, Open Items, PARKED, NEXT, Recent Commits all updated; new §15g narrative section. Companion DIR bump: `docs/design_intent_register.md` v1.4 — see that changelog for the full corrected-intent detail, not repeated here. |
 | 2.25 | 13 Jul 2026 | **Two-part fix session, both surfaced by putting the 11 Jul mode-aware work under load.** (1) `mode_profile_loader` was found never to have been wired into `rov_full.launch.py` despite being committed 7 Jul (`4e48dc2`) — `/rov/mode/profile` had zero publishers at runtime since then, so the entire operating-mode profile system had been dark and `failsafe_monitor`'s `health_role` had been silently running on its gate default the whole time. Fixed by adding the node to the launch file with respawn (`464e17e`), verified live (publisher count 0→1). (2) With the mode system now actually publishing, `failsafe_monitor`'s mode-aware recovery (`2a3e577`, same session — subscribes to the resolved profile, branches condition-clear recovery on `health_role`) surfaced a second gap: gate-mode committed recovery entered `RETURN_TO_SAFE` and could never leave it, because that branch deliberately ignores further condition-clear so recovery runs to completion, and nothing signalled completion. Fixed by a new PERMANENT interface, `/rov/nav/safe_zone_reached` (std_msgs/Bool), that transitions the FSM `RETURN_TO_SAFE`→`NORMAL` on arrival when gate-mode (`bf815cc`), verified live end-to-end on the bench (published the event by hand, watched the FSM release and the `motion_controller` recovery broadcast stop). Today's publisher is temporary bench scaffolding only — real navigation-raised arrival and a temporary W1-contextual operator button are both still to come; see the new Parked Design Item in `docs/design_intent_register.md` v1.3. §0 Confirmed Working, PARKED, and NEXT updated; new §15f narrative section. **Two pre-existing `failsafe_monitor` defects found this session (not caused by it):** `flag_manual_abort` is a one-way latch never reset, permanently shadowing all lower-priority handling (including this session's own new logic) after any single manual abort — field-deployment concern, needs its own session; and `failsafe_monitor` produced no log output in `journalctl` this session, costing diagnostic time. Both added to §0 Open Items and §15f. Companion DIR bump: `docs/design_intent_register.md` v1.3 adds the mode-aware safe-zone-reached Parked Design Item — see that changelog for detail. |
 | 2.24 | 11 Jul 2026 | **§15d resolved.** Vehicle health / FC-comms-loss fault (discovered 9 Jul, flagged OPEN/SAFETY-CRITICAL in v2.22) is fixed as of four commits today: `86b2728` (unconditional RED on comms loss + `fcu_ever_connected` latch + cause text), `1b0050d` (FSM recovery fix — `RETURN_TO_SAFE` was a terminal trap), `dbe9515` (new `external/rov-failsafe-cause` variable), `3409ae5` (W1 widget shows state + cause text). Verified live end-to-end. Related fault found+fixed same session: `cockpit_bridge` was publishing `failsafe_state` (FSM, 3+) not `assessment_state` (0/1/2) to `rov-failsafe` — the actual cause of that day's "widgets show no data," fixed in `d854641`, compounded by a restart-storm wedging port 9001 (→ CLAUDE.md's one-restart-then-verify-9001 rule). §0 Confirmed Working and Recent Commits updated; PARKED list updated to reflect intent now recorded in the DIR (mode-dependent recovery, auto-recovery, dedicated cause field, AMBER runtime-response — all still open on implementation, closed on design intent). Companion DIR bump: `docs/design_intent_register.md` v1.2 adds the two DIR-7 addenda and a Parked Design Items section — see that changelog for detail, not repeated here. |
@@ -450,12 +489,39 @@ context needed. Full trigger-rule text lives in `CLAUDE.md`.
   gitignored and untracked, so this was a local filesystem cleanup only, no git change.
   Durable guard: colcon build must only ever be run from /data/ros2_ws, never from inside
   src/rov-autonomy. Recorded so this is not reintroduced.
+- 2026-07-14 — Documentation-only session, no code changed. Recorded a widget-to-hardware
+  wiring map (docs/design_intent_register.md DIR-13): W1 is a two-stage health gate — RPi4
+  FC-heartbeat MUST pass first (already implemented, 86b2728, 11 Jul), then RPi5
+  autonomy-stack self-health (not yet built) — only when both pass is W1 GREEN. W5 reflects
+  the RPi4-connected battery. W2/W3/W4/W6/W8 reflect the RPi5 stack; W6 altitude is
+  deliberately kept RPi5-direct, consistent with the standalone-autonomy principle (BlueOS/
+  Cockpit integration is the only current external dependency). W7 specced, not built. New
+  wiring table added to §9. Also recorded depth as a dual-source, operator-selectable input
+  (DIR-14): RPi4 sensor (via the FC) or an RPi5-direct sensor, or a blend, selected at mission
+  setup (W4) and carried in the resolved mode profile like health_role. Redundancy plus
+  operator choice; consistent with the same standalone-autonomy principle as W6. Design-
+  captured intent for a future build, not yet specified in detail.
+- 2026-07-14 — FLAGGED: test-data / fault-injection capability is now an approaching required
+  workstream, not optional. The failsafe logic — and the pending count-based FSM rework in
+  particular — cannot be properly tested without the ability to inject sensor states and
+  simulate running-vs-failed sensor conditions. Agreed approach is incremental: start with the
+  sensors that matter now (altitude, depth, sonar) and the ability to mark each as running or
+  failed to exercise failsafe state transitions, not a full simulation build up front. Near-
+  term prerequisite for validating the FSM rework.
+- 2026-07-14 — Confirmed current top build priority: the failsafe FSM rework to the corrected
+  count-based fault-persistence model (DIR correction 255096f). The condition-clear commit
+  logic in 2a3e577/bf815cc remains known-wrong pending that rework. This rework, W1's RPi5-side
+  health gating (DIR-13, second stage of the two-stage gate), and the test-data/fault-injection
+  capability above are related workstreams that touch the same code and should be planned
+  together. Also verified this session: W2 reflects live mission state (observed ABORTED after
+  a live abort); W3's label change to RETURN TO SAFE is complete (9aa5b5d). Reminder recorded:
+  argonaut-api.service is manual-start and must be started for any rov_api/backend testing.
 
 ---
 
 ## Design Intent Register — pointer
 
-The full Design Intent Register (DIR-1 through DIR-12) lives in **`docs/design_intent_register.md`**,
+The full Design Intent Register (DIR-1 through DIR-14) lives in **`docs/design_intent_register.md`**,
 git-tracked in the repo, not duplicated here. That file is the source of truth for *why* —
 read it before any design/architecture decision.
 
@@ -471,6 +537,10 @@ read it before any design/architecture decision.
 - **DIR-5/5a/5b** — return-to-safe is mission-bounded, vehicle-layer, and mode-dependent
   (AUV automatic, ROV alert+override); operator override continues the mission, it does not
   pause it.
+- **DIR-13/DIR-14 (14 Jul 2026)** — DIR-13: widget-to-hardware ownership map (which of RPi4/RPi5
+  each widget reflects; W1 is a two-stage FC-heartbeat + autonomy-self-health gate). DIR-14:
+  depth as a dual-source, W4-selectable input (RPi4 sensor / RPi5-direct sensor / blend).
+  Design-captured; see §9 for the wiring table and §0 PARKED for build status.
 
 ---
 
@@ -801,6 +871,23 @@ between v2.21 (8 vars, this table) and v2.22 (19 vars, §0's table) before this
 > requires a live mission, FastAPI backend, and/or Ping2 hardware depending on the widget.
 > W6 full test requires Ping2 sonar hardware. W7 not started.
 
+### Widget-to-Hardware Wiring (owner intent — DIR-13, 14 Jul 2026)
+
+Which physical subsystem each widget actually reflects — not always obvious from the UI alone.
+Full intent record: `docs/design_intent_register.md` DIR-13. Keep this table in sync with that
+entry.
+
+| Widget | Reflects | Subsystem | Notes |
+|---|---|---|---|
+| W1 — System Health Indicator | Vehicle health (two-stage gate) | **RPi4 + RPi5** | Stage 1: RPi4 FC heartbeat MUST pass first — **implemented** (`86b2728`). Stage 2: RPi5 autonomy-stack self-health — **not yet built**. GREEN only when both pass. |
+| W2 — Mission Status | `mission_executor` | RPi5 | — |
+| W3 — Return To Safe button | `failsafe_monitor` via `/rov/mission/abort` | RPi5 | — |
+| W4 — Mission Setup button | FastAPI setup page | RPi5 | Setup page itself not yet built. |
+| W5 — Return Budget | Battery | **RPi4** | Battery is connected to the RPi4 (via MAVROS/Pixhawk), not the RPi5. |
+| W6 — Altitude | Ping2 sonar | RPi5 | **Deliberately** kept RPi5-direct, not routed via RPi4 — standalone-autonomy principle (BlueOS/Cockpit integration is the only current external dependency). |
+| W7 — Backup Due Notice | Backup status | RPi5 (+ server) | Specced (Option A), not built. |
+| W8 — Mode Indicator | `mode_profile_loader` | RPi5 | — |
+
 ### How to Install a Widget
 
 1. Open Cockpit native desktop app
@@ -1412,8 +1499,9 @@ executables in `lib/<pkg>/`. This is now the standard build command.
 | DVL absent | X/Y position dead-reckoned from IMU — drifts | High — Phase 7 |
 | Ping2 sonar not purchased | W6 full test blocked; downward altitude not flowing | Phase 3 (~$280 USD) |
 | FastAPI backend not built | W3 abort, W4 setup, W5 budget, W7 backup all blocked | High — Phase 3 Stage 2 |
-| W3 button label not updated | Widget still shows "ABORT MISSION"; should be "RETURN TO SAFE" | Next session |
+| ~~W3 button label not updated~~ | RESOLVED 14 Jul 2026 (`9aa5b5d`) — label now "RETURN TO SAFE" | Closed |
 | ~~Widget JSON not in Gitea~~ | RESOLVED — W6 committed as `w6_altitude.json`, probe widget removed (`785ec56`), see §12 | Closed |
+| Test-data / fault-injection capability absent | Failsafe logic (incl. pending FSM rework) cannot be properly tested without injecting sensor states / simulating running-vs-failed conditions. Incremental approach agreed: altitude/depth/sonar first. | Near-term — prerequisite for FSM rework validation |
 | RPi5 weak SSH password | Password auth enabled, Tailscale service disabled but installed | Pre-field |
 | RPi5 thermal in sealed enclosure | Conduction cooling path unresolved | Phase 3 |
 | ML inference compute | RPi5 has no GPU. ONNX/TFLite on-device or Jetson Orin Nano. | Phase 5 |