docs: cut every worktree from a freshly fetched origin/main #58
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: jlab-cluster/helm-charts#58
Reference in new issue
Block a user
Two additions to
CLAUDE.md, both bought with incidents from 2026-09-27.1. Every worktree is cut from a freshly fetched
origin/mainNew bullet in "Which forge, and with which tool", directly after the remote bullet it extends. A worktree branched from the local
mainref can be arbitrarily old — and the staleness outlives the fix, which is the part worth knowing.The project-instructions block a subagent receives at the head of its context — the binding copy of this file — is a snapshot of the spawning session's working directory, taken when that session started. It is not a live read. Fetching mid-session does not refresh it, so the file on disk can be correct while every agent started from then on is still handed the superseded rules, with nothing in the block to show its age.
Measured twice that day. First: an agent reported a "contradiction" in
CLAUDE.md— the remote bullet — that two PRs had already fixed, quoting the stale copy as binding; in the shared checkout,main..HEADshowed 105 differing files while the difference againstorigin/mainwas a single line. Then the sharper one: after that working directory had been deliberately fast-forwarded and verified as up to date, the next agent's block was still from before Gitea #47 — while its own worktree was identical toorigin/main,rev-list --left-right --countreturning0 0. A current checkout and stale instructions at the same moment, which is what identifies the block as a snapshot rather than a symptom of a stale checkout.So the bullet states the two consequences that actually hold: the spawning session's directory must be current before the session starts, and an agent checks a rule against the file in its own worktree plus a diff against
origin/main— never againstmain, and never against its own context block. The first cannot be enforced from inside an agent; the second can, and it is what kept both incidents harmless.2. The wiki's default branch is
main, notmasterOne sentence after the clone block in "The wiki". Since the rule to fetch and rebase before every wiki push, the branch name is required information: an agent tried to rebase onto
origin/master, which failed. Harmless that time — the push afterwards was a clean fast-forward and no force was involved — but avoidable.Wiki
Already pushed, each time as a fast-forward after a fetch and rebase:
Forge-and-Tooling— the long form of both facts, in the page's own voice: a new section after "The remote isorigin" with the fetch-and-branch commands, the snapshot mechanism and why a stale block is undetectable, all three measurements, and the two consequences kept separate from the ones that do not hold; plus the branch name where the wiki clone is described.Lessons-Learned— a new entry, "The instruction block no fetch could refresh". The failure form is the one that page collects: a stale instructions block looks exactly as authoritative as a current one, the same class as the probe that cannot fail and therequiredarray that never fires. Both measurements are recorded, along with the point that it went well only because someone checked. One bullet added to "The recurring shape".Workflow— the branch name added to the fetch-and-rebase rule, which is the spot where reaching fororigin/masteractually failed.Notes
**origin/main**inside a bold span, which Markdown does not render — refs and commands are in backticks instead. And the mechanism sentence was rewritten after the measurement above showed the original phrasing ("is read from the spawning session's working directory") implies that a mid-session pull repairs it, which would mislead anyone applying the rule.ci/run-quantity-render-test.shpasses (24 charts exercised, 0 failed).origin/main(5c51329) when work started, so no rebase was needed — verified rather than assumed, which is the rule being written. The instructions block handed to that same agent was nevertheless pre-Gitea #47; that is measurement two above.teacarries the workspace login.Fixes #57
Amended after review, two changes.
The mechanism was understated. The first wording said the project-instructions block "is read from the spawning session working directory", which implies that a mid-session pull repairs it. It does not: the block is a snapshot taken when the spawning session started, and nothing re-reads it afterwards. The evidence came from this round of work — the spawning session had been fast-forwarded to the tip immediately beforehand and verified as up to date, yet the agent it started received a block predating PR #47 on this forge, while the worktree of that same agent was identical to
origin/main(rev-list --left-right --countreturned0 0). A current checkout and stale instructions at the same moment.CLAUDE.mdandForge-and-Toolingnow say so, and state the two consequences that actually hold: the directory must be current before the session starts, and an agent checks a rule against the file in its own worktree plus the diff againstorigin/main. The first cannot be enforced from inside an agent; the second can, and it is what kept both incidents harmless.A
Lessons-Learnedentry was added after all — "The instruction block no fetch could refresh". Not for the damage, which was nil both times, but for the failure form: a stale instructions block looks exactly as authoritative as a current one, which is the class that page collects, alongside the probe that cannot fail and therequiredarray that never fires. Both measurements are in it, including the point that it went well only because someone checked, plus one bullet in "The recurring shape".The description above is updated to match. The render test still passes and the diff is still
CLAUDE.mdalone.