diff options
| author | Craig Jennings <c@cjennings.net> | 2026-07-02 05:19:01 -0400 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2026-07-02 05:19:01 -0400 |
| commit | b6a977cec25fddf1e498896cec3ad9462fc149db (patch) | |
| tree | 9bbd5a1ac2609c9d1b4cba719360fa7e319db85f /claude-rules/host-identity.md | |
| parent | 78bbaae5d8634d52588c1a60d7b7f430bed238c7 (diff) | |
| download | rulesets-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/host-identity.md')
| -rw-r--r-- | claude-rules/host-identity.md | 20 |
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. |
