aboutsummaryrefslogtreecommitdiff
path: root/claude-rules
diff options
context:
space:
mode:
authorCraig Jennings <c@cjennings.net>2026-07-02 05:19:01 -0400
committerCraig Jennings <c@cjennings.net>2026-07-02 05:19:01 -0400
commitb6a977cec25fddf1e498896cec3ad9462fc149db (patch)
tree9bbd5a1ac2609c9d1b4cba719360fa7e319db85f /claude-rules
parent78bbaae5d8634d52588c1a60d7b7f430bed238c7 (diff)
downloadrulesets-b6a977cec25fddf1e498896cec3ad9462fc149db.tar.gz
rulesets-b6a977cec25fddf1e498896cec3ad9462fc149db.zip
feat(rules): add the host-identity guard rule and startup probe
A tracked or synced doc asserting "this machine is X" is false on every machine but its origin, and an agent trusting it reasons backwards all session. It happened live: a stale "ratio" claim steered a session running on velox. The new rule bans fixed identity claims in tracked/synced docs and requires the runtime derivation instead (uname -n, since the hostname binary is often absent). Describing the fleet stays legal. Claiming the current member doesn't. startup gained a read-only probe that greps CLAUDE.md and notes.org for the pattern and surfaces hits as a judgment flag, never a block. Fixture-verified under bash and zsh.
Diffstat (limited to 'claude-rules')
-rw-r--r--claude-rules/host-identity.md20
1 files changed, 20 insertions, 0 deletions
diff --git a/claude-rules/host-identity.md b/claude-rules/host-identity.md
new file mode 100644
index 0000000..9f58392
--- /dev/null
+++ b/claude-rules/host-identity.md
@@ -0,0 +1,20 @@
+# Host-Identity Guard
+
+Applies to: `**/*` (any tracked or synced project file)
+
+Never assert mutable environment identity as a fixed fact in a file that git tracks or the template sync distributes. A `CLAUDE.md` or notes file claiming "This machine is ratio", a current OS version, an IP, or "the laptop" lands identical on every machine, so the claim is false everywhere but its origin — and an agent that trusts it reasons backwards the whole session.
+
+## The Rule
+
+- **Don't write fixed identity claims** — "this machine is X", "the current host is X", "we're on the laptop" — in `CLAUDE.md`, `notes.org`, rules files, or any other tracked/synced doc.
+- **Derive identity at runtime and name the command.** The correct phrasing in a doc is an instruction, not a fact: "run `uname -n` to find the hostname." (`uname -n` is the source of truth — the `hostname` binary is often absent, and `uname -r` is the kernel release, not the host.)
+- **Describing the fleet is fine; claiming the current member is not.** "The fleet is ratio (workstation) and velox (laptop)" is a durable fact and belongs in a doc (see `daily-drivers.md`). "This machine is ratio" is a snapshot that rots the moment the file syncs.
+- The same applies to any mutable environment fact: current OS release, current IP, current display topology. State how to derive it, not what it was when the file was written.
+
+## Worked failure
+
+archsetup, 2026-06-21: its `CLAUDE.md` asserted "This machine is **ratio**" as a fixed fact. A session running on velox reasoned from that line all session — skipping velox-only reminders as "not applicable, we're on ratio" — exactly backwards. The fix replaced the claim with the `uname -n` instruction.
+
+## Enforcement
+
+The startup workflow runs a read-only probe that greps `CLAUDE.md` and `.ai/notes.org` for fixed-identity phrasing and surfaces any hit as a startup finding. The probe flags for human judgment; it never blocks. When it fires, replace the claim with the runtime derivation, not a fresher snapshot.