docs(dir): correct inverted DIR-7 in-mission-recovery intent to count-based fault-persistence model

The 11 Jul DIR-7 addendum "In-mission recovery is mode-dependent" stated
that AUV gate mode commits to recovery ON CONDITION-CLEAR. That was
inverted and wrong — it produced a contradictory GREEN-while-in-
RETURN_TO_SAFE state observed live.

Corrected intent (v1.4, 13 Jul 2026, attributed to Grant):
- GREEN is unconditionally a working state. A cleared fault returns the
  vehicle to GREEN and the mission continues/resumes; a cleared condition
  must never trigger or commit a recovery. Committed recovery is triggered
  by a fault PERSISTING or RECURRING, never by it clearing.
- Three-tier fault model: (1) uncontrollable — power loss / anything that
  disables the safety logic itself, out of scope for the FSM, adjacent to
  shelved DIR-6; (2) transient/self-resetting — system attempts restore,
  returns to GREEN and resumes on success, each failure increments a raw
  count (deliberately no time window/duration), commits to RETURN_TO_SAFE
  only once the count exceeds a configured acceptable number; (3)
  hard/persistent — a RED that doesn't clear, commits immediately without
  waiting on a count.
- All thresholds (acceptable count, transient-vs-hard classification) are
  configuration-driven via the resolved mode profile, same as health_role,
  never hardcoded.
- Survives, correct: health_role mode-awareness (2a3e577); the
  safe-zone-reached arrival-exit mechanism (bf815cc) — its role (completing
  a committed recovery) is unchanged. Retired, known-wrong: 2a3e577's
  condition-clear entry logic, which bf815cc built its exit on top of —
  pending next-session rework into the count-based model. Only the ENTRY
  into committed recovery was wrong, not the exit.

New Parked Design Item: adaptive restart-timing — monitor own restore
count/duration per fault, log it, weigh future restart attempts against
observed history rather than a fixed time. Deliberately holds all
time/duration sophistication kept out of the count-based correction;
depends on the count-based retry machinery existing first. Design-captured,
not yet specified for build.

Changelog and known-implementation-drift callout updated accordingly —
failsafe_monitor's current condition-clear logic is now flagged as a known
implementation gap pending rework, not merely an unimplemented addendum.

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

docs/design_intent_register.md

@@ -1,6 +1,6 @@
 # Design Intent Register — Argonaut 3
 
-**Version:** 1.3
+**Version:** 1.4
 **Date:** 13 July 2026
 **File:** `docs/design_intent_register.md` (repo-tracked, no version number in filename)
 
@@ -12,6 +12,7 @@
 
 | Version | Date | Change |
 |---|---|---|
+| 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. |
 | 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. |
@@ -20,12 +21,16 @@
 > ⚠ **Known implementation drift (updated 13 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).
-> The DIR-7 addendum "in-mission recovery is mode-dependent" is **essentially implemented** (13
+> The DIR-7 "in-mission recovery is mode-dependent" addendum's **core trigger logic was corrected
-> Jul 2026 — `failsafe_monitor` now reads `health_role` and branches recovery accordingly,
+> 13 Jul 2026** — the previous condition-clear-commits-to-recovery model was inverted and wrong
-> including the gate-mode arrival exit via the new `/rov/nav/safe_zone_reached` interface);
+> (it produced a contradictory GREEN-while-in-`RETURN_TO_SAFE` state observed live); see the
-> remaining gap is the event's real publisher (navigation not yet built) — see the new "Parked
+> addendum below for the corrected count-based tier model. **`failsafe_monitor`'s current code
-> Design Items" entry below. The AMBER runtime-response addendum, auto-recovery, and the
+> (`2a3e577`) still implements the RETIRED, known-wrong condition-clear entry logic** — this is
-> dedicated `string cause` field remain **intent recorded, not implemented**. DIR-12's broader
+> now a known implementation gap needing rework, not merely an unimplemented addendum, pending a
+> dedicated next session. The safe-zone-reached arrival EXIT mechanism (`bf815cc`) remains
+> correct and unaffected by this correction — only entry into committed recovery was wrong. The
+> AMBER runtime-response addendum, auto-recovery, the dedicated `string cause` field, and the new
+> adaptive restart-timing item all remain **intent recorded, not implemented**. DIR-12's broader
 > vehicle-health framing remains open beyond the FC-link piece (FD-headroom check on
 > `ardupilot_manager` not built).
 
@@ -208,46 +213,111 @@ the state without opening another tool.
 
 ---
 
-### DIR-7 addendum — In-mission recovery is mode-dependent (11 Jul 2026)
+### DIR-7 addendum — In-mission recovery is mode-dependent (11 Jul 2026, **CORRECTED 13 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.
+pre-dive gate to the in-mission runtime case. **Core trigger logic corrected 13 Jul 2026 (Grant)
+— see callout immediately below.**
 
-**Intent:** When a RED (or AMBER, see next addendum) condition triggers a return-to-safe /
+> ⚠ **CORRECTED 13 Jul 2026 (Grant).** The original text of this addendum stated that AUV gate
-hold-and-recover response **during a mission**, and the underlying condition later clears,
+> mode **commits to the recovery action ON CONDITION-CLEAR.** That is inverted and wrong. It
-what happens next is mode-dependent — recovery is not one behaviour:
+> produced a contradictory state observed live: the failsafe assessment reporting GREEN (the
+> fault cleared) while the FSM sat in `RETURN_TO_SAFE` (committed recovery) — a "green light,
+> still returning to safe" state that should not be possible. **The corrected intent:** GREEN is
+> unconditionally a **working state** — a fault that clears returns the vehicle to GREEN and the
+> mission continues or resumes; a cleared condition must **never** trigger or commit a recovery.
+> Committed recovery is triggered by a fault **persisting or recurring**, never by it clearing.
+> The rewrite below is the corrected model, replacing the retired condition-clear wording — see
+> "What survives / what is retired" near the end of this addendum for the implementation impact.
 
-- **AUV (`gate`)** — commits to the recovery action on condition-clear. It does **not**
+**Intent (corrected 13 Jul 2026):** Recovery response is governed by a **three-tier fault
-  auto-resume the interrupted mission. Recovery, once committed, runs to completion (the
+model**, not by whether a condition has cleared:
-  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
+1. **Uncontrollable tier — out of scope for the FSM.** Loss of power, or any failure that
-  the condition going away. There is no operator to ask, so the vehicle must not guess that
+   disables the safety logic itself, cannot be governed by a parameter inside the very system
-  "condition cleared" means "carry on as if nothing happened."
+   that has just been disabled — there is no FSM response to "the thing running the FSM is
-- **ROV (`advisory`)** — holds at AMBER/RED and hands the continue-or-recover decision to the
+   gone." This tier is adjacent to, and does not duplicate, the shelved DIR-6 Emergency Surface
-  operator. The operator decides whether to accept recovery or override and continue, per
+   last-resort concern above; it is noted here only so it is not mistaken for a gap in tiers 2/3
-  DIR-5's existing tethered intervention model. Matches DIR-5b: an operator override
+   below.
-  continues the mission; it does not force a recovery the operator didn't ask for.
+2. **Transient / self-resetting tier.** E.g. a comms blip, or a critical-sensor re-sync that can
+   restore on its own. The system **attempts to restore**; on success, it returns to **GREEN**
+   and the mission **continues or resumes** — a successful restore is not itself a reason to
+   recover. Each failure **increments a count**. Only once the failure count **exceeds a
+   configured acceptable number** does the FSM commit to `RETURN_TO_SAFE`. The count is a **raw
+   count of failures for the mission** — deliberately **no time window, no fixed duration** —
+   because time-window/duration-based logic will not survive changing startup periods and
+   mission lengths. (Time/duration-aware sophistication is parked separately — see "Adaptive
+   restart-timing" in Parked Design Items below — and depends on this raw-count mechanism
+   existing first.)
+3. **Hard / persistent tier.** A RED condition that does **not** clear. Commits to
+   `RETURN_TO_SAFE` immediately, without waiting on a count — there is nothing to count against;
+   the fault is already known to be hard.
+
+**Mode-dependent role, same shape as the original addendum, now operating on the tier model
+above rather than on condition-clear:**
+- **AUV (`gate`)** — commits to `RETURN_TO_SAFE` when a fault crosses into tier 3
+  (hard/persistent) or tier 2's failure count is exceeded — **never** merely because a condition
+  cleared. Once committed, recovery 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 anything clearing. There is no operator to
+  ask, so the vehicle must not guess that a transient success means "carry on as if nothing
+  happened" — tier 2 already handles that correctly, by returning to GREEN and resuming on a
+  *successful restore*, not on the fault merely being absent this instant.
+- **ROV (`advisory`)** — holds during an active AMBER/RED condition 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.
+
+**All thresholds are configuration-driven, not hardcoded:** the acceptable failure count (tier
+2), and the classification of which specific faults are transient (tier 2) versus hard (tier 3),
+are set in the setup wizard and read from the resolved mode profile the same way `health_role`
+is — never hardcoded in `failsafe_monitor`.
 
 **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.
+  same generic response is correct for both modes.
-- AUV: treat mission resumption as a separate, deliberate action (DIR-10), never implicit in
+- Trigger committed recovery on fault **persistence or recurrence** (tier 2 count exceeded, or
-  condition-clear.
+  tier 3 hard fault) — **never** on condition-clear.
+- On a successful transient restore (tier 2), return to GREEN and continue/resume the mission —
+  a successful restore is not a reason to recover.
+- AUV: treat mission resumption as a separate, deliberate action (DIR-10), never implicit in a
+  restore or in reaching NORMAL.
 - ROV: surface the continue-or-recover choice explicitly; do not auto-decide on the operator's
   behalf.
+- Keep all thresholds (acceptable failure count, transient-vs-hard fault classification)
+  configuration-driven via the mode profile, never hardcoded.
 
-**Implementation note:** the FSM-level fix landed 11 Jul 2026 (commit `1b0050d`) made
+**Must not:**
-`RETURN_TO_SAFE` and `HOLD_AND_RECOVER` both able to return to `NORMAL` on condition-clear — the
+- Commit to, or remain committed to, recovery because a condition cleared. A cleared condition
-**mechanism**. It was initially **mode-blind** (`failsafe_monitor` did not yet read the mode
+  is evidence the vehicle is fine, not evidence it needs recovering.
-profile), so at that point it behaved the same way in both AUV and ROV.
+- Use a time window or fixed duration to decide whether a fault is "still happening" for the
+  purpose of this trigger — use the raw failure count (tier 2). Time/duration awareness is a
+  separate, later piece of sophistication (see "Adaptive restart-timing" Parked Design Item).
 
-> ✅ **Made mode-aware 13 Jul 2026** (commit `2a3e577`): `failsafe_monitor` now subscribes to
+**What survives from the 11 Jul / 13 Jul implementation work, and what is retired (13 Jul
-> `/rov/mode/profile` and branches on `health_role` per this addendum — gate commits
+2026):**
-> `HOLD_AND_RECOVER`→`RETURN_TO_SAFE` instead of returning to NORMAL; advisory holds for an
+- **Survives, correct:** `failsafe_monitor` subscribing to the resolved mode profile and reading
-> explicit operator resume (placeholder topic). This surfaced a further gap — gate-mode
+  `health_role` (commit `2a3e577`'s mode-awareness mechanism) — this is the right way to know
-> `RETURN_TO_SAFE` had no exit — closed by the new mode-aware safe-zone-reached arrival event,
+  which branch above applies, unchanged by this correction.
-> commit `bf815cc`. See the new Parked Design Item below for the arrival-event design detail,
+- **Survives, correct:** the safe-zone-reached arrival event and its permanent
-> and `docs/handover.md` §15f for the full fix narrative.
+  `/rov/nav/safe_zone_reached` topic interface (commit `bf815cc`) — this remains the correct
+  means by which a **committed** `RETURN_TO_SAFE` recovery runs to completion and exits back to
+  `NORMAL` on arrival. Its role is **unchanged** by this correction: it completes a committed
+  recovery. Only the trigger for **entering** committed recovery was wrong — how a committed
+  recovery **exits**, once genuinely entered, is untouched and still correct.
+- **Retired, known-wrong, pending rework:** the **condition-clear-commits-to-recovery entry
+  logic** — specifically, `2a3e577`'s gate-mode `HOLD_AND_RECOVER` → `RETURN_TO_SAFE` transition
+  on condition-clear (the `health_role == HEALTH_GATE` branch in
+  `failsafe_monitor._apply_failsafe_priority`'s "all clear" block), which `bf815cc` then built
+  its (correct) arrival exit on top of. The entry logic is now known-wrong per the correction
+  above and will be reworked next session into the tier-2 count-based persistence model
+  described here. Until reworked, treat that entry code path as implementing the retired
+  (wrong) intent, not this corrected one.
+
+> **Status:** Corrected 13 Jul 2026 (Grant). Design intent corrected; implementation rework
+> (count-based tier-2 persistence trigger, config-driven thresholds) is a next-session task —
+> `failsafe_monitor`'s current condition-clear entry logic is known-wrong in the meantime.
 
 ---
 
@@ -488,6 +558,33 @@ one cut when navigation takes over publishing to the same permanent topic.
 > publisher (W1 button + `rov_api` endpoint) and the real navigation-raised event are both still
 > to come.
 
+### Adaptive restart-timing (relates to the DIR-7 addendum's corrected tier-2 model; depends on the count-based retry machinery existing first)
+
+**Source:** Grant, 13 Jul 2026.
+
+Rather than a fixed restart timeout, the system should **monitor its own restore behaviour** —
+capturing **restore count and restore duration** each time a fault is recovered — log it, and
+**weigh future restart attempts against that observed history** rather than against a fixed
+time.
+
+**Worked example:** On a failure, the system attempts a restart. If the restart succeeds, it
+returns to GREEN and resumes (per the tier-2 model above), while in the background it **logs the
+restore**, including count and duration. If the failure **recurs**, it may attempt restart
+again — now **comparing against the previous attempt** — and logs the second failure.
+Subsequent failures are then subject to the configured acceptable-count parameter (tier 2
+above).
+
+This item deliberately holds **all** the time-and-duration-based sophistication (rolling
+windows, learned durations, weighing attempts against history) that was **kept out of** the
+count-based correction above — the corrected DIR-7 addendum trigger is a raw count, on purpose,
+precisely so it does not depend on this not-yet-built machinery. This item **depends on** the
+count-based retry machinery existing first; it is not a substitute for it and cannot be built
+ahead of it.
+
+> **Status:** Design-captured intent for a dedicated future session. **Not yet specified for
+> build** — no algorithm, thresholds, or storage format decided here, only the shape of the
+> problem and its dependency ordering.
+
 ---
 
 ## Proposed build staging (REVISED to align with research)