diff --git a/CLAUDE.md b/CLAUDE.md index 6b5b4e9..837df19 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,11 @@ # CLAUDE.md — Rules for Claude on the Argonaut 3 Project -**Version:** 3.5 -**Updated:** 8 July 2026 +**Version:** 3.6 +**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 - COMPLETE replacement files uploaded to Claude project knowledge — never patches or - fragments, never committed to Gitea. +- Other project docs (handover, UI design, DIR, sim/ML plan) are maintained as COMPLETE + replacement files uploaded to Claude project knowledge — never patches or fragments, + 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. ---