fix(rules): warn when a diverged checkout will strand a frustrations entry

[Dygreens]

Four frustration entries were appended on 2026-08-17 to ~/Developer/amux — a checkout ~1000 commits behind, with unpushed local commits and an hourly sync job that had failed 80+ runs. That copy held 25 entries; origin held 124.

The appends succeeded. No error, nothing to notice. They reached nobody.

.claude/rules/frustrations.md says to append to "frustrations.md at the repo root", and CLAUDE.md lives in that same stale checkout. So for a session working there — the documented working directory — the instruction is correct as written and produces an invisible write.

Why this is its own defect, not just "the checkout is stale"

A stale checkout announces itself the moment you pull. A diverged one swallows writes instead of blocking a read. So the entire premise of the file is quietly lost: one frustration is a complaint and a cluster is an argument, and a cluster only forms in the file everyone reads.

Two halves, because either alone is weak

1. The rule now says "the repo root" means the checkout that can actually push, with the two rev-list commands to check it and the divergence condition spelled out.

2. The SessionStart hook gains a third axis and says it at the one moment it matters. A doc that only asks you to remember is exactly what ethos rule 6 warns about; the hook is where a session already looks.

It fires only on divergence (ahead and behind), never on merely-behind — that's recoverable by a pull, and a push still reaches origin, so warning there would be noise. The hook's own header names silence-when-current as the reason it gets read at all.

Verified against the incident's own artifact

Run against ~/Developer/amux right now:

  - this checkout has DIVERGED (8 unpushed, 1109 behind origin/main)
    it cannot fast-forward, so nothing here reaches origin until a human reconciles it
    do NOT append to frustrations.md here — the write succeeds and reaches nobody
    log friction in a clone that is current instead (.claude/rules/frustrations.md)

Test

scripts/test-session-freshness.sh builds real git repos and runs the shipped hook against them. 10 assertions, verified to fail 3/10 against origin/main's hook.

Its control cases carry the weight:

case	expected
current checkout	no output at all
diverged (2 unpushed, 3 behind)	warns, names both counts
behind only	must not fire
ahead only	must not fire

A hook that warned unconditionally would pass the incident case while being pure noise — and noise is how a banner stops being read.

Wired into checks.yml, since a shell script outside crates/ is invisible to rust.yml's path filter.

Not fixed here — owner's call

The divergence itself (AMUX-49 / LR-1): now 8 unpushed commits and 81 consecutive sync failures. This PR makes the consequence visible; it does not reconcile the tree, and reconciling a shared checkout is not an agent's decision.

🤖 Generated with Claude Code

https://claude.ai/code/session_01B4vuEScunv4K6RMwQoT9xx