Skip to content

Commit 69d5326

Browse files
cliffhallclaude
andcommitted
fix: anchor the instructions check at the root, re-check from the start revision
Copilot round 1 on #5219: the documented check's pathspecs were relative to the current directory, so run from src/git it looked for instructions under src/git; and a re-check against HEAD passes in a newer worktree while the session still holds the rules it started with. Pathspecs now use `:/`, and the hook prints the session-start revision and the exact re-check command built from it. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 88c83ca commit 69d5326

4 files changed

Lines changed: 115 additions & 12 deletions

File tree

‎.claude/skills/release/SKILL.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,10 @@ On `STALE`, or a `STALE` line from the `SessionStart` hook, **stop** and ask
3232
for a session started in a fresh worktree. The v2.0.0 release ran its first
3333
three steps on a `release` skill 447 commits out of date (#5167). Re-run the
3434
check after each preparation PR merges, since `v2/main` moves under the
35-
session.
35+
session, **from the session-start revision, not `HEAD`**: this flow moves
36+
between worktrees (step 4e moves the verification worktree onto a newer
37+
candidate), and a newer worktree's `HEAD` says nothing about the rules this
38+
session loaded. The hook prints that revision and the re-check command.
3639

3740
## The shape
3841

‎AGENTS.md‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -518,22 +518,29 @@ here.
518518

519519
```sh
520520
git fetch origin v2/main
521-
git diff --quiet HEAD...origin/v2/main -- AGENTS.md .claude/ \
521+
git diff --quiet HEAD...origin/v2/main -- ':/AGENTS.md' ':/.claude/' \
522522
|| echo "STALE: instructions differ from origin/v2/main"
523523
```
524524

525525
The three dots compare against where `HEAD` branched from `v2/main`, so
526-
a branch's own edits to the instructions do not read as stale. **If it is
527-
stale, stop and ask for a session started in a fresh worktree**, rather
528-
than continuing on rules you cannot trust.
526+
a branch's own edits to the instructions do not read as stale; the `:/`
527+
anchors the paths at the repository root, so the check means the same
528+
from any directory. **If it is stale, stop and ask for a session started
529+
in a fresh worktree**, rather than continuing on rules you cannot trust.
529530
530531
- The `SessionStart` hook in `.claude/settings.json`
531532
(`scripts/session-instructions-check.mjs`) runs that check at every
532533
session start and prints its verdict into the session, with a note when
533534
the session started in the primary checkout. A `STALE` line from it is
534535
the same stop.
535536
- **A long session re-checks after `v2/main` moves under it**, for
536-
example after its own PRs merge.
537+
example after its own PRs merge, **from the revision it started at, not
538+
from `HEAD`**: once the session moves into a newer worktree, that
539+
worktree's `HEAD` can match `origin/v2/main` while the rules the session
540+
holds are still the old ones. The hook prints the session-start revision
541+
and the exact re-check command; without the hook, record
542+
`git rev-parse HEAD` in the starting checkout before anything else, and
543+
put it in place of `HEAD` above.
537544
- **When work begins**, assign the issue to yourself, set Status to
538545
**In Progress**, and create a branch named
539546
`v2/<type>/<ISSUE_NUMBER>-<slug>` (for example

‎scripts/session-instructions-check.mjs‎

Lines changed: 39 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
// `origin/v2/main` and asks whether `v2/main` has changed the instructions
1515
// since this checkout's HEAD branched from it:
1616
//
17-
// git diff --quiet HEAD...origin/v2/main -- AGENTS.md .claude/
17+
// git diff --quiet HEAD...origin/v2/main -- ':/AGENTS.md' ':/.claude/'
1818
//
1919
// The three dots matter. They diff the merge base against `origin/v2/main`,
2020
// so a branch that edits the instructions itself (a PR like the one that
@@ -34,8 +34,26 @@ import { fileURLToPath, pathToFileURL } from "node:url";
3434
/** The branch whose instructions a session must be running. */
3535
export const BASE = "origin/v2/main";
3636

37-
/** The paths Claude Code loads its instructions from at session start. */
38-
export const INSTRUCTION_PATHS = ["AGENTS.md", ".claude/"];
37+
/**
38+
* The paths Claude Code loads its instructions from at session start, as
39+
* pathspecs anchored at the repository root (`:/`), so the same check means
40+
* the same thing run from `src/git` as from the root.
41+
*/
42+
export const INSTRUCTION_PATHS = [":/AGENTS.md", ":/.claude/"];
43+
44+
/**
45+
* Pure: the command that re-checks, later in the session, the instructions
46+
* loaded at `startSha`. It names the session-start revision rather than
47+
* `HEAD`: once the session moves into a newer worktree, that worktree's
48+
* `HEAD` can match `origin/v2/main` while the rules the session holds are
49+
* still the ones it started with.
50+
*
51+
* @param {string} startSha
52+
*/
53+
export function recheckCommand(startSha) {
54+
const paths = INSTRUCTION_PATHS.map((p) => `'${p}'`).join(" ");
55+
return `git fetch origin v2/main && git diff --quiet ${startSha}...${BASE} -- ${paths} || echo STALE`;
56+
}
3957

4058
/** How long the fetch may take before the check falls back to the local ref. */
4159
export const FETCH_TIMEOUT_MS = 15_000;
@@ -49,13 +67,21 @@ export const MAX_NAMED = 5;
4967
* @param {{
5068
* fetched: boolean,
5169
* baseSha: string | null,
70+
* startSha: string | null,
5271
* stale: boolean,
5372
* changed: string[],
5473
* primary: boolean,
5574
* }} state
5675
* @returns {string[]}
5776
*/
58-
export function report({ fetched, baseSha, stale, changed, primary }) {
77+
export function report({
78+
fetched,
79+
baseSha,
80+
startSha,
81+
stale,
82+
changed,
83+
primary,
84+
}) {
5985
const lines = [];
6086
if (!fetched)
6187
lines.push(
@@ -82,6 +108,12 @@ export function report({ fetched, baseSha, stale, changed, primary }) {
82108
`session-instructions-check: AGENTS.md and .claude/ match ${BASE} (${baseSha.slice(0, 8)}).`,
83109
);
84110
}
111+
if (!stale && startSha !== null)
112+
lines.push(
113+
`session-instructions-check: this session loaded its instructions at ${startSha}. ` +
114+
"Re-check from that revision, not from HEAD, after v2/main moves or the session changes " +
115+
`checkout: ${recheckCommand(startSha)}`,
116+
);
85117
if (primary)
86118
lines.push(
87119
"session-instructions-check: this session started in the primary checkout, which concurrent " +
@@ -113,6 +145,8 @@ export function checkSession({ cwd, fetch = true }) {
113145
cwd,
114146
);
115147
const baseSha = resolved.status === 0 ? resolved.stdout.trim() : null;
148+
const head = git(["rev-parse", "--verify", "--quiet", "HEAD"], cwd);
149+
const startSha = head.status === 0 ? head.stdout.trim() : null;
116150

117151
let changed = [];
118152
if (baseSha !== null) {
@@ -139,6 +173,7 @@ export function checkSession({ cwd, fetch = true }) {
139173
return report({
140174
fetched,
141175
baseSha,
176+
startSha,
142177
stale: changed.length > 0,
143178
changed,
144179
primary,

‎scripts/session-instructions-check.test.mjs‎

Lines changed: 60 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,13 +13,15 @@ import {
1313
BASE,
1414
MAX_NAMED,
1515
checkSession,
16+
recheckCommand,
1617
report,
1718
} from "./session-instructions-check.mjs";
1819

1920
const SHA = "0123456789abcdef".repeat(2) + "01234567";
2021
const fresh = {
2122
fetched: true,
2223
baseSha: SHA,
24+
startSha: null,
2325
stale: false,
2426
changed: [],
2527
primary: false,
@@ -31,6 +33,22 @@ test("report: fresh, in a worktree, prints one confirming line", () => {
3133
]);
3234
});
3335

36+
test("report: a known start revision adds the re-check, anchored at the root", () => {
37+
const lines = report({ ...fresh, startSha: SHA });
38+
assert.equal(lines.length, 2);
39+
assert.ok(lines[1].includes(recheckCommand(SHA)), lines[1]);
40+
assert.equal(
41+
recheckCommand(SHA),
42+
`git fetch origin v2/main && git diff --quiet ${SHA}...origin/v2/main -- ':/AGENTS.md' ':/.claude/' || echo STALE`,
43+
);
44+
// A stale session stops; it is not told how to re-check.
45+
assert.equal(
46+
report({ ...fresh, startSha: SHA, stale: true, changed: ["AGENTS.md"] })
47+
.length,
48+
1,
49+
);
50+
});
51+
3452
test("report: stale names what changed and says to stop", () => {
3553
const [line] = report({
3654
...fresh,
@@ -133,7 +151,10 @@ test("checkSession: a primary checkout at origin/v2/main is fresh, with the prim
133151
t.after(s.done);
134152
const lines = checkSession({ cwd: s.work });
135153
assert.match(lines[0], /match origin\/v2\/main/);
136-
assert.match(lines[1], /started in the primary checkout/);
154+
assert.ok(
155+
lines.some((l) => /started in the primary checkout/.test(l)),
156+
lines.join("\n"),
157+
);
137158
});
138159

139160
test("checkSession: the fetch finds an instruction change made behind the checkout's back", (t) => {
@@ -170,8 +191,45 @@ test("checkSession: a fresh worktree is fresh, with no primary note", (t) => {
170191
const wt = path.join(s.work, "..", "wt");
171192
s.git("worktree", "add", "-q", "--detach", wt, "origin/v2/main");
172193
const lines = checkSession({ cwd: wt });
173-
assert.equal(lines.length, 1, lines.join("\n"));
194+
assert.equal(lines.length, 2, lines.join("\n"));
174195
assert.match(lines[0], /match origin\/v2\/main/);
196+
assert.match(lines[1], /loaded its instructions at [0-9a-f]{40}/);
197+
});
198+
199+
test("checkSession: run from a subdirectory, it still checks the root instructions (#5219 review)", (t) => {
200+
const s = setup();
201+
t.after(s.done);
202+
s.write("src/git/README.md", "a server\n");
203+
s.git("add", "-A");
204+
s.git("commit", "-q", "-m", "a server directory");
205+
s.advance("AGENTS.md", "rules v2\n");
206+
const lines = checkSession({ cwd: path.join(s.work, "src", "git") });
207+
assert.match(lines[0], /^STALE: .*changed AGENTS\.md since/);
208+
});
209+
210+
test("checkSession: the printed re-check catches stale rules after moving to a newer worktree (#5219 review)", (t) => {
211+
const s = setup();
212+
t.after(s.done);
213+
// The session starts here, fresh, and is told its start revision.
214+
const started = checkSession({ cwd: s.work });
215+
const recheck = started.find((l) => l.includes("Re-check from"));
216+
assert.ok(recheck, started.join("\n"));
217+
const cmd = /checkout: (.*)$/.exec(recheck)[1];
218+
219+
// v2/main changes the rules; the session cuts a new worktree from it.
220+
s.advance("AGENTS.md", "rules v2\n");
221+
s.git("fetch", "-q", "origin", "v2/main");
222+
const wt = path.join(s.work, "..", "newer");
223+
s.git("worktree", "add", "-q", "--detach", wt, "origin/v2/main");
224+
225+
// A HEAD-based check in the new worktree passes; the printed one does not.
226+
const sh = (command) =>
227+
spawnSync("sh", ["-c", command], { cwd: wt, env, encoding: "utf8" });
228+
assert.equal(
229+
sh("git diff --quiet HEAD...origin/v2/main -- ':/AGENTS.md'").status,
230+
0,
231+
);
232+
assert.equal(sh(cmd).stdout.trim(), "STALE");
175233
});
176234

177235
test("checkSession: a HEAD with no history in common with v2/main is stale", (t) => {

0 commit comments

Comments
 (0)