docs(claude): add 2026-07-11 SESSION LOG — failsafe FC-comms-loss resolved, parked items

CLAUDE.md

@@ -1,6 +1,11 @@
 # CLAUDE.md — Rules for Claude on the Argonaut 3 Project
-**Version:** 3.5
+**Version:** 3.6
-**Updated:** 8 July 2026
+**Updated:** 11 July 2026
+
+**Changelog 3.6:** Added measurement-before-diagnosis, step-back-on-break,
+one-restart-then-verify-9001, and Cockpit widget re-import rules to Working Style.
+Corrected the Documentation discipline note that incorrectly claimed CLAUDE.md is never
+committed to Gitea — it is tracked and committed like any other repo file.
 
 **Changelog 3.5:** Added `[VSC]` terminal label. Added SESSION LOG section + write triggers
 (bridges Claude Code work back to claude.ai chat, which has no native access to Claude Code
@@ -40,6 +45,32 @@ If uncertain: **search first, then act**. Never guess.
 ### One command at a time
 Give one command, wait for feedback, then give the next. Never batch commands unless asked.
 
+### Measurement before diagnosis (facts only)
+Every claim about system state must be backed by a read-only command output in the same
+exchange. No diagnosis from theory. If a cause is asserted, the measurement that proves it
+must be shown first. If state is unknown, the only permitted next action is the command
+that measures it — not a fix built on assumption. Enforcement phrase: if the operator says
+"measurement?" and none was shown, the rule was broken — go measure before proceeding.
+
+### Step back to the last action when something breaks
+When something that was working breaks, return to the last action taken. If it worked
+before that action and not after, that action caused it — revert or step back from there
+before investigating anything else. Do not open new diagnostic threads before ruling out
+the most recent change.
+
+### One restart, then verify — never restart-storm
+Never issue repeated `systemctl restart argonaut.service` in quick succession. Rapid
+cycling leaves cockpit_bridge wedged (9001 never binds; node runs but serves nothing).
+Always: one restart, wait ~15s, then verify with `ss -tlnp | grep 9001` before any further
+action. Only one restart is in flight at a time.
+
+### Cockpit widget re-import — full quit after JS changes
+When a Cockpit DIY widget's JS changes (not just html/css), a delete + re-import inside the
+running app can leave the old script's setInterval timer alive in the background, so old
+and new timers both write to the DOM and fields flicker. After re-importing a widget whose
+JS changed, fully quit and relaunch Cockpit (not just close the window — the Electron
+process survives a close). html/css-only changes do not need this.
+
 ### Lead with context and corrections BEFORE instructions, never after.
 
 ### Copy-paste friendly commands
@@ -320,11 +351,14 @@ backup because this was deferred — do not repeat.
 ---
 
 ## Documentation discipline
-- All project docs (handover, UI design, DIR, this file, sim/ML plan) are maintained as
+- Other project docs (handover, UI design, DIR, sim/ML plan) are maintained as COMPLETE
-  COMPLETE replacement files uploaded to Claude project knowledge — never patches or
+  replacement files uploaded to Claude project knowledge — never patches or fragments,
-  fragments, never committed to Gitea.
+  never committed to Gitea.
+- CLAUDE.md is different: it IS version-controlled and committed to Gitea like any other
+  repo file (normal patch/diff edits and commits apply to it, not the replacement-file
+  workflow above).
 - Version numbers and changelogs maintained on every update.
-- Only code and README files go to Gitea.
+- Only code, README files, and CLAUDE.md go to Gitea.
 
 ---
 
@@ -393,6 +427,34 @@ entries; correct forward with a new dated entry if something needs revising.
   connection + heartbeat and drive W1 RED on FC comms loss. W1 status line should carry
   cause text (e.g. "Vehicle Disconnected", "Heartbeat Lost", "No Board Running"). Also
   flagged: no FD-count check on ardupilot_manager in the pre-dive gate.
+- 2026-07-11 — RESOLVED the 2026-07-09 flagged safety-critical fault: failsafe_monitor now
+  drives W1 RED on FC comms loss. Four commits: (1) 86b2728 — comms loss forces
+  unconditional RED (was scored as one marginal parameter, only reached AMBER) plus
+  fcu_ever_connected latch so the startup window before any heartbeat is not reported GREEN;
+  cause text "Heartbeat Lost"/"Vehicle Disconnected" added to FailsafeStatus.message per
+  DIR-7. (2) 1b0050d — FSM recovery fix: RETURN_TO_SAFE was a terminal trap (only
+  HOLD_AND_RECOVER could return to NORMAL); now both recover when conditions clear. (3)
+  dbe9515 — cockpit_bridge publishes new data lake variable rov-failsafe-cause (substring of
+  message before first "|"; empty when nominal). (4) 3409ae5 — W1 shows state word on
+  #w1-message (state-driven, no flicker) and cause text on #w1-footer, footer restyled red
+  11px, blank when nominal. All four verified live end-to-end: kill mavros -> RED +
+  "Heartbeat Lost", restart -> recover to GREEN. Also corrected: cockpit_bridge was
+  publishing failsafe_state (FSM, can be 3+) not assessment_state (0/1/2) to rov-failsafe —
+  fixed in dbe9515's sibling commit d854641; this was the real cause of the day's "widgets
+  show no data" (value 3 out of W1's range), compounded by a restart-storm wedging 9001.
+- 2026-07-11 — PARKED for next sessions, in priority order: (a) DOC RESTRUCTURE (do first
+  next session) — consolidate all current-state into the handover as single source of truth,
+  strip state from CLAUDE.md leaving rules only, make SESSION LOG the handover's changelog;
+  DIR and domain docs stay separate. Reason: current-state is smeared across CLAUDE.md,
+  handover and SESSION LOG, causing loss of situational awareness. (b) Mode-dependent
+  failsafe recovery: AUV (health_role=gate) commits to recovery on condition-clear, ROV
+  (advisory) holds AMBER and hands to operator to decide — requires failsafe_monitor to read
+  the mode profile (currently mode-blind). (c) Auto-recovery: failsafe_monitor should attempt
+  to re-establish the FC link itself and only escalate/hold RED if it cannot — real-world has
+  no operator to restore comms. (d) Dedicated "string cause" field in FailsafeStatus.msg to
+  replace the message-substring shortcut in cockpit_bridge. (e) Operator control surface
+  (start/pause/stop buttons via rov_api) and one-command stack startup+healthcheck. (f) DIR
+  and handover updates for the above still owed this session.
 
 ---