docs(claude): check the base before spending a gate slot (phaze-fkha3)

[SimplicityGuy]

What and why

A 20-25 minute gate measures a tree, and origin/main can move while it runs — so the gate may characterise a tree nobody will merge. The failure surfaces as someone else's red test in your own transcript.

Measured 2026-08-24: a seat's gate went red 23 minutes in on test_litellm_pin_is_unchanged, in a bead whose own diff was one ADR plus three comment-only edits, while origin/main advanced four commits and another seat fixed that guard as a P0.

Adds one section to CLAUDE.md, directly after the gate-slot rationing section it belongs beside — that one rations slots against the machine's headroom, this one against the result's validity.

The check

git fetch origin && git rev-list --left-right --count HEAD...origin/main

One second against 20-25 minutes.

Explicitly not a mandate to rebase. phaze-irby2 gated green, ran this check, rebased, and paid a second ~22-minute gate because the rebase changed its tree and invalidated the (tree, cmd_hash) ledger key. The rule is know before you spend the slot.

Measured, so the guidance is proportionate rather than adjectival

origin/main took 65 commits in 24 h (2.71/h). Expected commits landing during one gate: 0.99 for a 22-minute full run, 0.027 for a 35.57 s check-fast selected run. The check earns its keep on the escalated path; both numbers or neither.

Method correction

Disjointness is git merge-tree --write-tree, never hunk arithmetic — three-dot diff headers are in merge-base coordinates (measured 22-line offset on CLAUDE.md). Two limits, both measured on git 2.50.1:

• Exit 1 is ambiguous between a conflict and an unresolvable ref (nosuchref → exit 1), so a never-fetched worktree reports "conflict" having measured nothing.
• Clean is necessary, not sufficient. phaze-sy8z3 merged clean and went 2 failed, 7985 passed on a field another branch renamed.

AC 4 — verified against bh 0.15.0 source, not inferred

The bead flagged this as an inference. It is narrower than assumed:

• Molecule boundary only — work_merge.py:282/:394; the per-bead path at :854 has no stale term.
• It cannot see origin/main at all — git fetch appears nowhere in the lifecycle (work.py, work_merge.py, work_submission.py, work_group.py, worktree*); the one hit, worktree.py:823, is upstream/<base> for kind=external hives.
• The developer gate has nothing — impl_check (work_submission.py:10-71) never resolves a base.

General form (rule 5)

The next term in this file's own series rather than a free-standing aphorism: a gate's M is a property of a RUN, not a COMMAND — and an M is also a property of a MOMENT, never of the repo in perpetuity. An M about STATE decays; an M about MECHANISM does not. The label makes it worse, because M is the marker that says do not re-verify this.

Validation

Full suite on an isolated seat, read from the gate log body:

phaze test database: 'phaze_pregate_2d7978e7_test' on localhost:5433 (from TEST_DATABASE_URL, exclusive)
8038 passed, 3 skipped, 180 deselected, 96 warnings in 1303.40s (0:21:43)
TOTAL  18199  169  3922  141  98.56%
Required test coverage of 95.0% reached. Total coverage: 98.56%
GATE_EXIT=0

Per AC 7, this bead ran its own step-1 check immediately before gating — 1 0, base had not moved, so it did not gate on a stale base. Re-run after the base moved 6 commits: merge-tree clean, all asserted claims content-grepped and still true, nothing duplicated — so no rebase, which is the guidance demonstrating itself.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GazEx6kCcyQuRvifWb3aBF