administrator/rov-autonomy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
5551173b7a
rov-autonomy/docs/design_intent_register.md

32 KiB
Raw Blame History

Design Intent Register — Argonaut 3

Version: 1.2 Date: 11 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.

Changelog

Version Date Change
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.
1.1 9 Jul 2026 DIR-1 corrected — the tether/HILT link, not the power source, determines operating mode. A tethered vehicle may run on battery or topside supply. DIR-7 expanded — AUV gate vs ROV advisory health semantics; and a MUST that health assessment include flight-controller connectivity (a monitor with no FC input must never report GREEN). DIR-9 superseded by DIR-9a — recording is a single ARM-bounded black-box tier, not continuous-from-boot. DIR-12 added — vehicle health is distinct from autonomy health.
1.0 Jun 2026 Initial register.

⚠ Known implementation drift (updated 11 Jul 2026): recording_manager.py still implements the superseded DIR-9 (continuous-from-boot) model, NOT the governing DIR-9a — still open. failsafe_monitor's DIR-7 FC-connectivity MUST is resolved (11 Jul 2026, see DIR-7 below); DIR-12's broader vehicle-health framing remains open beyond the FC-link piece (FD-headroom check on ardupilot_manager not built). The two new DIR-7 addenda (mode-dependent in-mission recovery, AMBER runtime-response) and both Parked Design Items are intent recorded, not implemented — see their sections.

DIR-1 — Platform is a single dual-capability vehicle (AUV + ROV)

Source: Grant, June 2026 session.

Intent: One physical platform that is both an AUV and an ROV. It is not two vehicles or three abstract modes. The tether / human-in-the-loop (HILT) link determines the operating mode:

  • No HILT link (untethered) → operates as a pure AUV: fully autonomous, NO human in the loop. Mission plan + sensor data + parameter-governed rules drive everything, including aborts.
  • HILT link present (tethered) → operates as an ROV with AUV abilities (HILT): the same autonomy stack runs the mission identically, but a human operator is able to intervene.

CORRECTED 9 Jul 2026. This entry previously stated that the power source determines the operating mode. That is WRONG. Power source and operating mode are independent. A tethered vehicle may run on internal battery or on topside supply; either way it is an ROV because the HILT link is present. The dominant axis is the link, not the volts.

Must: Treat autonomy as one shared path used in both modes. Must: Derive mode from HILT-link presence, never from power source. Must not: Implement two separate autonomy/abort flows for AUV vs ROV.

DIR-2 — HILT is an override channel, not a confirmation gate

Source: Grant, June 2026 session (explicit clarification).

Intent: In BOTH modes, the autonomy runs the same rules and acts automatically by default. Normal operations are identical in AUV and ROV mode. The ONLY difference in tethered/ROV mode is that the operator can intervene when/as required — override a rule's action, or continue manually under conditions the autonomy would otherwise abort on (an experienced pilot may safely continue where rules alone would not).

Must:

  • Run the autonomous rule-driven path always, in both modes.
  • Provide an intervention/override channel that is active only when tethered.
  • Degrade safely: if the operator does nothing, the vehicle behaves exactly as an AUV.

Must not:

  • Block or pause autonomous action waiting for human confirmation.
  • Require operator input for the vehicle to act. Intervention is optional, never a precondition.

DIR-3 — Mission is a process (aerial-drone model)

Source: Grant, multiple sessions; consolidated June 2026.

Intent: The mission follows the same lifecycle as an aerial survey drone:

  1. Mission is created or uploaded to the ROV beforehand — a process, not a button-time action.
  2. Pilot manually launches and flies the ROV to a safe place.
  3. Pilot starts the mission → ROV departs, follows the plan, records data + video/stills as instructed.
  4. Normal end: ROV autonomously returns to a designated safe place; pilot takes over for recovery.

"Safe place / safe zone": Operator-designated location, closest to the mission start, where the ROV can safely be recovered or hold. Used both as the normal return point and as the abort return point. (Drone "home" equivalent.)

DIR-4 — Mission Start / Stop (mission-layer; paired function)

Source: Grant, June 2026 session. REVISED to align with AUV/ROV lifecycle research (see DIR-9).

Intent: Control of the mission (the survey), distinct from any vehicle-safety action.

  • Start — "go do the inspection." Begins mission-plan execution.
  • Stop — "inspection is done, or I'm calling it off." Ends mission execution.

RECORDING — revised per research (DIR-9): Mission Start/Stop does NOT start/stop the recorder itself. The recorder runs continuously and independently (DIR-9). Mission Start/Stop controls what is sampled and splits the MCAP bag on a mission-phase boundary, per the active record profile (DIR-10). This avoids the "mission ran but nothing recorded" failure mode — the single most important reason mature systems (ArduPilot, MBARI LRAUV, QGroundControl, MOOS-IvP) do NOT gate the recorder on mission state.

Must:

  • On Start: begin mission execution; split the bag to mark mission start; apply the mission's record profile (which streams sample).
  • On Stop: end mission execution; split the bag to mark mission end.
  • Treat "recorder not active" as a no-go for Start (DIR-9).

Must not:

  • Command any vehicle movement. Start/Stop is mission-layer only.
  • Stop or kill the recorder process on mission Stop — the recorder keeps running continuously.

UI note: Start/Stop is a command (mission already created/uploaded per DIR-3). What to record is selected at plan time via the record profile (DIR-10), with runtime override available.

DIR-5 — ROV Abort / Return-to-Safe (vehicle-layer)

Source: Grant, June 2026 session. NOTE: supersedes the earlier mislabelled "manual abort" intent.

Intent: A vehicle safety action, NOT merely a recording stop. Triggered when conditions exceed designated levels (power and others — see failsafe spec thresholds). Behaviour depends on mode per DIR-1/DIR-2:

  • AUV mode (untethered): rule fires → vehicle automatically stops recording and returns to the closest safe place. No human.
  • ROV/HILT mode (tethered): same rule fires and would act as in AUV mode, BUT the operator can intervene — either accept (let it return to safe) or override (continue, autonomously per mission or manually).

Recording — revised per research (DIR-9): On return-to-safe, the mission ends so mission sampling stops, but the recorder keeps running continuously through the transit and recovery (matches every mature system: keep recording through the return phase, split the bag on the phase boundary). The earlier intent "recording stops on return-to-safe" is refined: mission-driven high-rate sampling stops; the always-on core recording continues. Rationale: the return transit is itself valuable data, and stopping the recorder mid-event risks losing the record of why the abort happened.

Must:

  • Use the DP-state (GREEN/AMBER/RED) assessment logic to drive the action.
  • Stop all recording when returning to safe.
  • Return the vehicle to the closest designated safe place.
  • In tethered mode, expose alert + override capability to the operator.

Must not: Be labelled simply "abort" in a way that implies an emergency hard-stop. It is a return-to-safe, not an emergency surface.

Open / staged: HILT alert-accept-reject-override flow is multi-stage work (see staging below). Tethered-first development is a potential machine-learning opportunity.

DIR-5a — Abort is mission-bounded; outside a mission the vehicle is manual ROV

Source: Grant, June 2026 session (correction/refinement).

Intent: The autonomy, rules, and abort logic (DIR-2, DIR-5) apply only while a mission plan is executing.

  • No mission running → the vehicle is entirely manually controlled by the operator. It operates as a plain ROV. No autonomy drives it. There is nothing to abort.
  • Abort/return-to-safe only exists within a mission. It is a mission-context action, bounded by mission start and mission end.

Lifecycle:

  1. Manual control → pilot launches and flies to safe place (manual).
  2. Mission starts → autonomy active, rules apply, abort available.
  3. Mission ends (normal return-to-safe, or abort) → back to manual control for recovery.

Must: Only arm autonomy/abort logic while a mission is executing. Must not: Allow abort or autonomous action when no mission is running.

DIR-5b — Operator override continues the mission (alerts are early, parameter-driven)

Source: Grant, June 2026 session.

Intent: When the operator intervenes during a mission (tethered/ROV mode), the intervention continues the mission — it does NOT terminate or pause it. The mission context stays live throughout.

Design goal: Alerts should fire early enough that the operator can act before any pause or abort becomes necessary. This is parameter-driven — the alert thresholds (the "designated levels" in DIR-5) must give a wide enough margin for intervention ahead of a forced abort.

Consequence: Threshold tuning is critical. The HILT advantage depends entirely on the alert margin being wide enough to intervene before the condition forces return-to-safe. Ties directly to the config UI (staging Stage 4).

Must: Keep the mission running through operator intervention. Must not: Drop to manual control or pause the plan as a side-effect of intervention.

DIR-6 — Emergency Surface (SHELVED — flagged for later)

Source: Grant, failsafe design session + June 2026.

Intent: Last-resort hard stop. Surfaces the vehicle regardless of surroundings. Highest risk action; must never be a first response.

Status: SHELVED. Not in current scope. To be reviewed later. May potentially be combined with DIR-5 return-to-safe at review time (Grant: "we could combine point 3 and 4").

DIR-7 — DP lights linked to mission capability

Source: Grant, failsafe design session. Expanded 9 Jul 2026.

Intent: The GREEN/AMBER/RED DP-style states (W1) show the ROV's ability to conduct the mission. They are explicitly linked to mission capability. Mission start/stop and ROV abort are separate functions, but the DP state informs the abort decision (e.g. AMBER conditions → operator would stop mission and return to safe).

Mode-dependent role (health_role flag):

  • ROV (advisory) — display only. The pilot sees the state and decides. A HILT operator is present.
  • AUV (gate) — W1 is the pre-dive GO/NO-GO gate. RED blocks mission start. There is no operator once submerged, so this is the last human-visible decision point.

Semantics (AUV, parameter-driven): GREEN = within designated levels; AMBER = approaching a designated level; RED = terminate / do not start.

MUST — health assessment includes the vehicle, not just the autonomy stack: The assessment MUST incorporate flight-controller connectivity and heartbeat age. A dead or unreachable FC is a RED condition. This is not optional: in AUV mode W1 is a gate, and a gate that cannot see the flight controller is not a gate.

MUST — absence of data is not health: A monitor with no input MUST NOT report GREEN. "No data" and "good data" are different states and must be distinguishable in both the assessment and the display.

MUST — the state must carry its cause: W1's status line carries cause text (e.g. "Vehicle Disconnected", "Heartbeat Lost", "No Board Running", "Systems nominal"), not a bare colour. An operator must be able to act on the state without opening another tool.

✅ Resolved 11 Jul 2026 (was open, safety-critical, 9 Jul 2026): failsafe_monitor now drives W1 RED unconditionally on FC comms loss, with a fcu_ever_connected latch closing the startup-window GREEN gap, and carries cause text on FailsafeStatus.message per the MUST above. Four commits — full narrative in docs/handover.md Changelog, 11 Jul entry. This DIR entry is not the place for commit-level detail; it records that the MUST is now satisfied.

DIR-7 addendum — In-mission recovery is mode-dependent (11 Jul 2026)

Source: Grant, 11 Jul 2026 session. Extends the advisory-vs-gate framing above from the pre-dive gate to the in-mission runtime case.

Intent: When a RED (or AMBER, see next addendum) condition triggers a return-to-safe / hold-and-recover response during a mission, and the underlying condition later clears, what happens next is mode-dependent — recovery is not one behaviour:

  • AUV (gate) — commits to the recovery action on condition-clear. It does not auto-resume the interrupted mission. Recovery, once committed, runs to completion (the vehicle returns to / holds at the designated safe place per DIR-3); resuming the survey itself is a fresh, deliberate mission start (DIR-10), never an automatic side-effect of the condition going away. There is no operator to ask, so the vehicle must not guess that "condition cleared" means "carry on as if nothing happened."
  • ROV (advisory) — holds at AMBER/RED and hands the continue-or-recover decision to the operator. The operator decides whether to accept recovery or override and continue, per DIR-5's existing tethered intervention model. Matches DIR-5b: an operator override continues the mission; it does not force a recovery the operator didn't ask for.

Must:

  • Derive the post-recovery behaviour from health_role (gate/advisory), never assume the same generic "return to NORMAL" response is correct for both modes.
  • AUV: treat mission resumption as a separate, deliberate action (DIR-10), never implicit in condition-clear.
  • ROV: surface the continue-or-recover choice explicitly; do not auto-decide on the operator's behalf.

Implementation note: the FSM-level fix landed 11 Jul 2026 (commit 1b0050d) makes RETURN_TO_SAFE and HOLD_AND_RECOVER both able to return to NORMAL on condition-clear — this is the mechanism. It is currently mode-blind (failsafe_monitor does not yet read the mode profile), so today it behaves the same way in both AUV and ROV. Making that mechanism mode-aware, per this addendum, is open — see Parked Design Items below.

DIR-7 addendum — AMBER runtime-response, in-mission (drafted 11 Jul 2026)

Source: Grant, 11 Jul 2026 session.

Intent: The pre-dive semantics above ("AMBER = approaching a designated level") describe a gate check before a mission starts. In-mission, AMBER means something more actionable: the vehicle CAN still operate, but SHOULD NOT continue as currently planned, and action IS required. It is not merely informational once a mission is underway — it is a call to do something, not just a status light. Response branches by mode:

  • AUV (gate) — no operator is present to hand the "action required" decision to. The autonomy stack must itself decide the appropriate curtailment (continue the current leg at reduced confidence vs. curtail and return to safe). AMBER does not by itself force an immediate hard return the way RED does. Exact decision logic is not yet specified — this addendum records the intent (AMBER demands a response, not just a display), not the algorithm. Left as design work, not to be inferred or invented ahead of a dedicated session.
  • ROV (advisory) — surfaces to the operator as "action required" per DIR-5b: alerts fire early enough to act before a forced abort, the mission keeps running through the intervention, and the operator decides continue-or-recover. This addendum does not change ROV behaviour — it is already covered by DIR-5b — it clarifies that AUV needs an equivalent, currently unspecified, autonomous response.

Must: Treat in-mission AMBER as requiring a response, not just a display state, in both modes — the response mechanism differs (autonomous decision vs. operator handoff), but neither mode may treat in-mission AMBER as purely informational.

Must not: Assume AMBER can be left unhandled until it escalates to RED. That defeats the purpose of an early, actionable warning (DIR-5b).

Status: Intent recorded, not implemented. AUV's autonomous curtailment logic is unspecified pending further design (see Parked Design Items).

DIR-9 — Recording is continuous and independently guarded — SUPERSEDED by DIR-9a

⚠ SUPERSEDED (9 Jul 2026). The continuous-from-boot model below is NO LONGER the governing intent. It was over-specified: it records hours of pre-dive bench idle, and it decouples the recording from the thing being recorded (the armed run). DIR-9a governs. This entry is retained for history and because recording_manager.py still implements it — that is drift, not intent. The two durable ideas carried forward into DIR-9a are: (1) the recorder is a separate node from mission_executor, and (2) recorder-active is a precondition for mission start in AUV mode.

Superseded text (DIR-9, June 2026)

Source: AUV/ROV lifecycle research (project doc: Mission_and_Data-Recording_Lifecycle...), June 2026. Aligns owner intent with proven practice.

Intent: Data recording is a dedicated, always-on process, separate from the mission executor. It is brought active before any mission can start and runs continuously through manual control, mission execution, return-to-safe, and recovery. This is the dominant pattern across ArduPilot/ArduSub (pre-arm fails if logging fails), MBARI LRAUV (continuous background logging), QGroundControl (GCS-level auto-save), and MOOS-IvP (separate pLogger process).

Two failure modes this prevents:

  1. "Mission ran but nothing recorded" — prevented by making recorder-active a precondition for mission start (hard no-go, like ArduPilot's "PreArm: Logging failed").
  2. "Continuous recording filled the disk" — prevented by bag splitting (max size/duration), zstd/lz4 compression, and a retention/circular policy (delete-oldest below a free-space threshold).

Architecture:

  • Recording runs as a dedicated ROS2 lifecycle node ("recording manager"), separate from mission_executor, managed Nav2-style and brought to active before missions can start.
  • The recorder is a real rosbag2 MCAP recorder (or Foxglove SDK MCAP sink), controlled via its services (~/pause, ~/resume, ~/split_bagfile, snapshot mode).
  • CORRECTION TO PRIOR DOCS/MEMORY: "MCAP recording via foxglove_bridge" is WRONG. foxglove_bridge is a live-visualisation WebSocket bridge ONLY — it does not record MCAP. The recorder and the bridge are separate nodes running alongside each other. This error must be corrected wherever it appears (handover, memory).

Must:

  • Run the recorder continuously, independent of mission state.
  • Block mission start if the recorder is not active; surface recorder health in the operator UI and treat a recorder fault like a failsafe (warn).
  • Split bags on mission-phase boundaries; annotate bags with mission metadata (YAML, schema version, vehicle/firmware IDs, active profile).

Must not:

  • Bind recorder liveness to mission start/stop.
  • Use foxglove_bridge as the recording mechanism.

DIR-9a — Recording is a single ARM-bounded black-box tier (GOVERNING)

Source: Grant, July 2026. Supersedes DIR-9.

Intent: There is one recording tier, and it is bounded by the armed run — not by boot, not by mission state. Its purpose is black-box / debug / ML / fault-finding. It is the flight recorder: it covers the period in which the vehicle can move.

Behaviour, keyed to the recording_control flag (not the mode name):

  • AUV (auto) — recording starts on ARM, stops on DISARM. No operator is present; the vehicle records its own armed run.
  • ROV (manual) — the operator starts and stops recording. On the ARM edge, if the recorder is not active, the Recording Control widget raises a reminder ("armed, not recording"). Keyed to record_reminder_on_arm.

No-go coupling, keyed to the nogo_gate flag:

  • AUV (enforced) — a recording failure is a hard no-go. Mission stops; vehicle is recovered.
  • ROV (relaxed) — a recording failure after ARM alerts the pilot; the operator resolves it in-water or recovers. Not a hard stop, because a human is in the loop.

Must:

  • Bound recording to the armed run, per armed run.
  • Derive behaviour from the recording_control / nogo_gate flags, never from a mode string.
  • Keep the recorder a separate node from mission_executor (carried forward from DIR-9).
  • Split bags, compress, and enforce a retention policy — the disk-fill failure mode from DIR-9 remains real and its mitigations still apply.

Must not:

  • Record continuously from node startup, independent of ARM state.
  • Treat recorded data as a client deliverable. Certified deliverable capture is OUT of scope pending Class-approved devices. Recorded data is dev/debug/ML only.
  • Use foxglove_bridge as the recording mechanism (carried forward from DIR-9 — it is visualisation only).

⚠ Implementation drift (9 Jul 2026): recording_manager.py still implements DIR-9 (continuous-from-boot). foxglove_mcap.launch.py comments also still cite DIR-9. Additionally argonaut-stack.sh passes record:=${RECORD} to a launch file that declares no such argument, so RECORD=false is silently ignored and bags record regardless. A dedicated DIR-9a rework is required. Do NOT wire RECORD into the current DIR-9 model.

DIR-10 — Record intent lives in the mission plan; runtime override allowed

Source: AUV/ROV lifecycle research + Grant's "checkboxes for what to record" requirement, June 2026.

Intent: What gets recorded is decided primarily at plan time, embedded in the mission, with runtime operator override always available. This mirrors the universal pattern (ArduPilot in-mission camera DO-items, LRAUV Enabled<Instrument> arguments, QGC plan-attached camera actions) where default capture is planned but the operator can always start/stop/split/add/drop a stream live.

Representation:

  • A recording: block in the mission YAML carrying named record profiles (e.g. nav_only, inspection_full) and per-stream toggles (forward camera, sonar, CTD, navigation, etc.). This is Grant's checkbox concept — surfaced in the mission planner UI, stored in the mission file.
  • At execute time, the profile translates into (a) the rosbag2 recorder's topic set and (b) any MAVLink camera DO_* items — the same YAML→MISSION_ITEM translation already done by rov_mission.
  • A low-rate always-on core (vehicle state, mode, mission status, nav) records continuously regardless of profile; the profile governs the high-rate sensor streams.

Must:

  • Let the operator choose record streams at plan time (checkboxes / profiles in the planner UI).
  • Allow runtime override from the console (start/stop/split/snapshot, add/drop a stream).
  • Keep the always-on core recording regardless of selected profile.

Must not: Require the operator to configure recording separately from the mission for the common case — the plan should imply its data products.

UI note: This is where the checkbox UI Grant described lives — in the mission planner (plan-time), with a runtime override surface on the operator console. The 3D Mission Planner (deferred to Phase 6+) is the eventual home; an interim plan-time mechanism may be needed sooner.

DIR-12 — Vehicle health and autonomy health are distinct; the operator must see both

Source: Grant + measured failure, 9 July 2026.

Origin: With the flight controller unreachable ("No board running" in BlueOS), W1 displayed GREEN / "Systems nominal". Every widget indicator was reporting on the RPi5 autonomy stack, not on the vehicle:

  • W1 reads the failsafe assessment, which does not gate on FC connectivity.
  • W8 reads the active mode profile, sourced from a YAML file — it would show AUV with the Pixhawk sitting in a drawer.
  • Foxglove "Connected: true" means connected to foxglove_bridge on the RPi5, not to the vehicle.

Intent: "Health" is not one thing. There are two independent subjects, and conflating them produces a display that is confidently wrong at the worst moment:

  1. Autonomy health — the RPi5 stack: nodes alive, EKF converged, recorder active, bridge up.
  2. Vehicle health — the FC and the platform: FC reachable, heartbeat fresh, arm state known, sensors reporting, power sane.

Must:

  • Assess vehicle health as a first-class input to the failsafe state (see DIR-7).
  • Make the subject of any health indication unambiguous to the operator — a green light must answer "green about what?".
  • Treat loss of FC communications as a vehicle-health RED regardless of how healthy the autonomy stack is. The autonomy stack being perfectly well is irrelevant if it is talking to nothing.

Must not:

  • Allow an indicator that reads only autonomy state to be presented as overall system health.
  • Allow an AUV pre-dive gate (DIR-7, health_role: gate) to pass without a verified FC link.
  • Rely on the operator having a second tool (BlueOS, QGC) open to know whether the vehicle is alive. In AUV mode nobody is watching; pre-dive, the gate must be self-sufficient.

Related, same class of failure: the BlueOS ardupilot_manager /dev/i2c-1 FD leak (docs/handover.md §15a) can silently exhaust the FC-management service after ~11 h of cumulative board-config page exposure. The FD count does not reset at launch. A pre-dive gate that checks FD headroom on ardupilot_manager belongs here, alongside the FC-link check — both are "is the vehicle actually going to keep talking to me" questions.

Status: OPEN. Not implemented. Safety-critical for AUV mode.

Parked Design Items (intent-adjacent, not yet actioned)

Tracked here so they aren't lost between sessions. Not full DIR entries — each is an implementation gap against an existing DIR, recorded so the next session that touches the relevant code knows the decision is already made in principle, just not built.

Auto-recovery (relates to DIR-7, DIR-12)

failsafe_monitor should attempt to re-establish the FC link itself before escalating — holding or forcing RED only if it cannot restore comms. Real-world dives have no operator to restore the connection manually; the current implementation (11 Jul 2026 fix) correctly detects and reports loss but does not attempt recovery on its own. This is distinct from the FSM's condition-clear recovery (which reacts once the condition is already gone) — auto-recovery is about the monitor actively trying to make the condition go away.

Dedicated string cause field (relates to DIR-7's "state must carry its cause" MUST)

FailsafeStatus.msg currently carries cause information as a substring of message (cockpit_bridge splits on the first |), not a first-class field. Add a dedicated string cause field to FailsafeStatus.msg and have cockpit_bridge read it directly, retiring the substring-parsing shortcut. Same intent as already specified in DIR-7; this is purely a mechanism cleanup, not a new decision.

Proposed build staging (REVISED to align with research)

Derived from the above and the lifecycle research; tethered-first since initial development is tethered. Reordered because the recording manager is foundational — it must be active before any mission can start (DIR-9).

  • Stage 1 — Recording Manager (foundational): dedicated ROS2 lifecycle node running a rosbag2 MCAP recorder, ARM-bounded per DIR-9a (not continuous — the original "continuous" wording here reflected the superseded DIR-9), separate from mission_executor. Bag splitting, compression, retention policy, health surfaced to UI. Recorder-active becomes a precondition for mission start. (Replaces the prior "MCAP via foxglove_bridge" assumption.) CREATE-THEN-BACKUP applies.
  • Stage 2 — Mission Start/Stop: mission-layer command via the existing MissionCommand service (START/ABORT/PAUSE/RESUME/LOAD already implemented). Splits the bag on mission boundaries; applies record profile. Does not move vehicle, does not stop the recorder.
  • Stage 3 — Record profiles + intent in mission YAML: the recording: block (DIR-10), profiles and per-stream toggles, translated at execute time. Includes the checkbox UI surface.
  • Stage 4 — Condition detection + alerting: autonomy detects designated levels exceeded; raises alert (AUV acts; ROV surfaces alert to operator).
  • Stage 5 — Return-to-Safe + HILT override: vehicle return-to-safe (auto in AUV, intervenable in ROV); recorder continues through transit, bag split on phase boundary.
  • Stage 6 — Config UI: threshold parameters ("designated levels") governing Stage 4/5; also the W5 return-budget constants (DIR ties to battery floor + reserve).
  • Stage 7 (SHELVED) — Emergency Surface.

Note on existing code: mission_executor already implements the MissionCommand service (START/LOAD/PAUSE/RESUME/ABORT) and failsafe integration (emergency-surface and return-to-safe both abort the mission). It does NOT control recording — correct per DIR-9. Stage 2 wires Mission Start/Stop to this existing service plus bag-split calls to the Stage 1 recorder.

Implications for existing code/widgets (factual, for validation)

  • The currently wired /rov/mission/abort (Bool → failsafe_monitor → flag_manual_abort → state machine) matches the AUV automatic path (DIR-5 AUV mode). It does NOT implement the tethered HILT intervention model (DIR-2/DIR-5 ROV mode), which is the near-term need.
  • mission_executor implements the MissionCommand service (not a topic): commands START/LOAD/PAUSE/RESUME/ABORT, request {command, mission_id, parameters[]}, response {success, message}. Mission Start/Stop (DIR-4, Stage 2) drives this.
  • mission_executor does not control recording — correct per DIR-9a. Recording is a separate Stage-1 manager.
  • W1 reports GREEN with the flight controller unreachable (DIR-12, DIR-7). failsafe_monitor does not consume /mavros/state connectivity. OPEN, safety-critical.
  • recording_manager.py implements superseded DIR-9, not governing DIR-9a. OPEN.
  • "MCAP via foxglove_bridge" is WRONG (DIR-9). foxglove_bridge is viz-only. Correct this in the handover (Tools section, Section 8/11) and in memory. Recording = rosbag2 MCAP recorder, separate node.
  • W3 button label "ABORT MISSION" is misleading per DIR-5 — implies emergency hard-stop but maps to assessed return-to-safe. Rename pending — exact wording TBC with Grant.
  • W2/W4 mission state relates to DIR-4 (mission start/stop), mission-layer, distinct from DIR-5 vehicle action.