From a79d6e6554193df41afc512942c331ff5cb2fe90 Mon Sep 17 00:00:00 2001 From: Matthew Goodwin Date: Sun, 23 Aug 2026 23:25:18 -0500 Subject: [PATCH] docs: two operating rules tonight's failures earned The checkout-is-deployment half of the branch rule was implicit and got missed by two sessions at once: a daemon up 12h had been executing whichever branch the shared checkout happened to be on, so a merge changed nothing in service. The ticket rule is new. A prune ran against a ticket that had grown a section, while the work was in flight, explaining that the row being removed was kept on purpose; the eviction orphaned a daemon registry and stopped worktree reconciliation. Co-Authored-By: Claude Fable 5 --- CLAUDE.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 22bc0c5b..7fda430b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -35,7 +35,7 @@ Logging is structural, not per-feature. Outcomes are logged at central seams; fe ## Operating on this machine -This repo's tooling runs as live services on the developer's own machine. Four +This repo's tooling runs as live services on the developer's own machine. Six rules, each written after it cost real damage: - **A built binary is only ever run under an isolated HOME** — `env -i HOME= …`, @@ -48,10 +48,21 @@ rules, each written after it cost real damage: and the failure is silent. - **Check `git branch --show-current` before syncing the main checkout.** It is shared with other sessions and is what the dev-mode `rt` wrapper executes; - it is not always on `main`. + it is not always on `main`. That second half makes it operational, not + hygiene: **the branch that checkout sits on is the dev daemon's deployed + code.** A daemon that has been up for hours is running whatever was checked + out when it started — another lane's branch, quite possibly — so a merge + changes nothing in service until the checkout syncs AND the daemon restarts. - **Diagnose live services without starting competing instances.** An extra daemon squats `rt.sock` and produces exactly the symptom — starts, binds nothing, logs nothing — that then gets misdiagnosed as a permissions problem. +- **Re-read a ticket immediately before acting on it.** Tickets here are + written by other live sessions while you work, so the copy you read at the + start of a task is a snapshot, not the current state. A prune ran against a + ticket that had, in the meantime, grown a section explaining that the very + row being removed was being kept deliberately — the eviction orphaned a + daemon registry and silently stopped worktree reconciliation. The same + applies to any shared artifact a peer session can edit underneath you. A claimed recovery path (self-heal, fallback, retry) is load-bearing: trace the code that performs it before documenting it, or the docs will tell users to run