fix(resume-state): a handoff in a LINKED WORKTREE reconciled a different initiative (#1164)

[ZacxDev]

scripts/resume-state.sh given an explicit path to a handoff doc that lives in a linked worktree reported NO SUCH FILE, fell back to newest-of-N, and emitted a complete, confident digest reconciled against a different initiative.

That fires on this repo's own mandated workflow: claude/RULES.md makes worktree isolation the standing default for any file-modifying agent, so handoff docs land in linked worktrees by construction.

Closes #1164

The measured symptom, same command both revisions

Using a doc that exists in exactly one linked worktree (handoff-linux-cpu-profiling.md, in devrc-1136), invoked with the base clone's path:

	resolves to	# repo:
d86e5f81	handoff-mention-detection.md — a different initiative, plus the NO SUCH FILE gap	the base clone
this branch	handoff-linux-cpu-profiling.md	/home/zach/workspace/devrc-1136

Part 1 — resolve into linked worktrees, scoped to the NAMED tree's own clone

New worktrees_holding <dir> <base> enumerates git -C <dir> worktree list --porcelain and returns the claudedocs/<base> copies that exist: rc 0 + one path, rc 2 + N paths, rc 1 + nothing.

🔴 The clone is an ARGUMENT, never $PWD. For <X>/claudedocs/<base> it is ${dir%/claudedocs} — the tree the caller actually named — and only the relative re-anchor uses $root. This preserves the invariant already in the file:

RELATIVE ONLY, and that restriction is the load-bearing half. An ABSOLUTE token that is not on disk stays a miss: the caller named a specific tree, so serving a same-named doc out of THIS repo would be the very wrong-initiative bug this clause exists to remove.

Searching $PWD's worktrees would have reintroduced exactly that bug one level down. test_an_UNRELATED_repos_worktrees_are_never_searched and test_an_ABSENT_clone_is_not_served_out_of_THIS_repos_worktrees pin it.

Ambiguity is not adjudicated. Two or more worktrees holding the basename ⇒ nothing is chosen, and the gap says how many and where (new rc 3 carries the token plus the candidate list).

Part 2 — a named-missing handoff path no longer falls back

The fallback chain is wrapped in if [ -z "$named_missing" ], so HANDOFF stays empty and the existing, already-tested branch fires: NOTHING was reconciled; the DRIFT section below is about no document at all.

🔴 No exit code and no refusal were introduced. The script has none today and always reports; adding one would be a contract change for the skill and every caller. Reusing the empty-HANDOFF path gets the same protection with no new surface.

🔴 Scoped to named_missing, NOT unresolved. A bare basename is a slug, not a handoff-shaped path, and the file records a MEASURED case where the fallback correctly served exactly that doc. test_a_bare_BASENAME_slug_STILL_falls_back_and_resolves and test_the_civitai_slug_STILL_falls_back_and_resolves are the regression guards for it.

Verification

Regression matrix, pre-fix script + post-fix tests, re-derived rather than taken from the implementing agent:

	d86e5f81	HEAD
the 12 behavioural tests (incl. parametrised variants)	12 RED	GREEN
the 4 vacuity controls	pass — by design, they pin unchanged behaviour	pass

test_resume_state_handoff_resolution.py: 165 passed (151 at base, +14).

Both sandbox tiers, ONE AT A TIME per #1088, read from each runner's own RESULT: line rather than a piped exit code:

• checks.x86_64-linux.pytests — RESULT: PASS (exit=0), collected=20090 passed=20087 skipped=3 failed=0 (floor 18383)
• checks.x86_64-linux.nodetests — RESULT: PASS (exit=0), suites=5 files=41 tests=1449 pass=1449 fail=0 (floor 1367)

Mutation battery (mutation_battery_resume_state.py), re-run independently under PYTHONDONTWRITEBYTECODE=1, checking NOT APPLIED before reading any kill count: 56/56 killed, 0 NOT APPLIED, survived: none. 14 new rows W1–W15, each with a named killer — including W2 (search $PWD's clone instead of the named one), W9 (fallback runs for a named path) and W10 (the guard widened to any supplied argument, killed by 42 tests including both slug controls).

Two decisions taken beyond the brief, both kept

The ambiguous enumeration is capped at 4, with , and N more. Measured on the real clone: 140 linked worktrees, and one handoff basename appears in 28 of them — uncapped that is a ~2.5 KB single line inside the GAPS block. The count is never capped, only the enumeration, and both sides of the threshold are pinned (W13/W14/W15).

claude/skills/resume/SKILL.md carried a claim this change makes false — "That gap means the digest is about a different initiative than you named" — now true only of the slug class. Split by input class rather than left to rot.

Four existing tests changed expectation — read them

They asserted the fallback that #1164 calls the bug: test_a_prose_path_that_does_NOT_exist_is_not_taken (×2 params), test_a_DIRECTORY_named_like_a_handoff_is_not_taken, and two test_every_gap_sentence_is_pinned_WHOLE rows. Each carries its reason in its docstring. The vacuity controls (..._decoy_PROVES_these_are_not_vacuous, ..._three_docs_ARE_takeable_...) exist so that "reconciles NONE" cannot pass merely because nothing was takeable.

⚠ The two halves deploy DIFFERENTLY — corrected

An earlier revision of this section said both files are nix-managed and inert until a home-manager switch. That was wrong, and measured with the arbiter claude/RULES.md names:

path	readlink -f	deploys on
scripts/resume-state.sh	itself	a plain git pull — it is a working-tree file, and command grep -rn resume-state nix/ returns 0 matches
claude/skills/resume/SKILL.md	/nix/store/…-devrc-claude-skills/resume/SKILL.md	a home-manager switch

🔴 So there is a window where the resolver is narrowed but the deployed prose still describes the old behaviour. In it, an agent following the deployed skill pastes a relative sibling-worktree path, gets (none found — git-only), and has no deployed text explaining why. Pull and switch together, or expect that gap.

Corrections to this PR's own record

Two are mine and are retracted in the history rather than quietly edited:

• 60c893b7 claimed d756a1f8 shipped an ungated re-anchor. False. I read scripts/resume-state.sh while the mutation battery was rewriting it in place and attributed mutant X1 to the commit — the diagnosis matched a named mutant because it was the mutant. Disproved in a git archive extraction of d756a1f8: 180 passed, condition already gated. 6f4d748b retracts it.
• 60c893b7 was comment-only, which I wrongly called harmless. Splitting *) if …; then across two lines made X1's anchor match 0x, so that row reported PATTERN OCCURS 0x — NOT APPLIED and stopped testing the hole this branch closes. 6f4d748b restores the line byte-exact; a collected test now enforces every anchor's uniqueness rather than a comment asking politely.

Superseded figures from earlier revisions of this body: the battery is 69/69 (not 56/56) and the suite is 180 passed (not 165) — both grew with round 1's fixes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Emy2y7tGJjRee3GV2cNuaJ

[ZacxDev]

Audit round 1 complete — seven findings, all fixed. Claims below for the delta round.

1. F1: the relative branch no longer searches or re-anchors on the standing clone for a token naming any other tree; a `$mine` gate (empty `<Y>`, or `<Y>`'s last component equal to the repo's own basename) guards BOTH the re-anchor and the worktree search.
2. F1 side effect: the pre-existing #1159 single-tree re-anchor no longer fires for a foreign `<Y>` either.
3. F2: the ambiguity gap now says "of the clone that path resolves against", which is true for all three relative shapes.
4. F3: claude/skills/resume/SKILL.md states which clone is searched per input class instead of claiming the standing clone is never used.
5. F4: the candidate list is collated under LC_ALL=C, and human-named worktrees are shown ahead of ephemeral .claude/worktrees/agent-* checkouts; the COUNT stays uncapped.
6. F5: a token containing a shell metacharacter is not recorded as a named document, so a glob no longer suppresses the fallback.
7. F7: the vacuity assertion now checks the whole digest rather than a line already pinned to a literal.
8. A relative token naming a SIBLING WORKTREE of the same clone now misses — a deliberate narrowing, documented in the script and the skill.

Two corrections to this PR's own record, both mine. 60c893b7 claimed d756a1f8 had shipped an ungated re-anchor. That was FALSE: I read scripts/resume-state.sh while the mutation battery was rewriting it in place and attributed mutant X1 to the commit. Proven wrong in a git archive extraction of d756a1f8 — 180 passed, condition already gated. 6f4d748b retracts it in the history.

And 60c893b7 was comment-only, which I wrongly called harmless: splitting *) if …; then across two lines made X1's mutation anchor match 0x, so that row reported PATTERN OCCURS 0x — NOT APPLIED and stopped testing the hole this branch closes. 6f4d748b restores the line byte-exact and moves the prose above the case.

Gate

• Suite: 180 passed. Battery on a quiescent worktree: 69/69 killed, 0 NOT APPLIED, survived: none — X1 killed by its named test.
• MERGED-TREE gate (origin/main 76bb7507 + 6f4d748b, 0 conflicts): pytests RESULT: PASS (exit=0) collected=20382 passed=20379 skipped=3 failed=0 (floor 18404) · nodetests RESULT: PASS (exit=0) tests=1449 pass=1449 fail=0. Nobody had gated a merged tree for this PR before.
• The only change since that merge is one handoff doc, 0 non-docs files; the doc-scanning suites were re-run on a merged tree including it: 291 passed.

⚠ Tekton's earlier red on this PR was TestAHungRoundTripSAYSWhichSideBlocked.test_a_stall_in_the_FSYNC_region_is_NAMED in scripts/tests/test_subsystem_store_api.py — a file this PR does not touch, which also failed on #1169 in the same window.

[ZacxDev]

Audit round 2 complete — seven findings, all closed in 7285291b.

1. The false "both are nix-managed" deploy claim is corrected in the PR body and the handoff doc; `readlink -f` shows resume-state.sh resolves to itself and `grep -rn resume-state nix/` returns 0, so a pull makes the resolver live while the deployed skill still states the old rule.
2. scripts/tests/test_mutation_battery_anchors.py is a COLLECTED test asserting every MUTANTS row's `old` occurs exactly once in the script it targets, across BOTH batteries, with a two-way ledger so a new battery cannot be forgotten.
3. claude/skills/resume/SKILL.md and the source comment now state the residual instead of denying it: a foreign tree whose directory NAME matches this repo's still re-anchors, because the gate compares only the last component. The discriminator was deliberately NOT widened.
4. Trailing slashes in `<Y>` are normalised, so `<repo>//claudedocs/<base>` resolves again; a control pins that `other-repo//claudedocs/` still misses.
5. Mutant X17 makes the whole-`out` vacuity assertion the killer, so the handoff doc's "proven reachable" claim is now backed by a named row.
6. Mutants X14 and X15 vary the ephemeral-worktree classification PATTERN itself, with fixtures holding a human worktree under .claude/ and an agent- directory outside it.
7. Mis-cited and stale counts corrected: W10 (not X10), the head sha, and 236 B of handoff-skill headroom after #1144 raised MAX_BYTES to 27,000. One count that disagreed three ways across sources was removed rather than replaced with a fourth.

Verification

• Anchor test negative control is the real defect: run against git show 60c893b7:scripts/resume-state.sh it FAILS naming X1: occurs 0x. 0 offenders at HEAD. That is the commit whose reformat disarmed X1 — the guard would have caught it.
• Battery 1: CONTROL (pristine): 187 passed, 0 failed · 73/73 killed, survived: none · NOT APPLIED 0.
• Battery 2 (skill): CONTROL (pristine): 42 passed, 0 failed · 38/38 killed for the RIGHT reason · NOT APPLIED 0.
• MERGED-TREE gate on the EXACT current head (main 7a22c841 + 7285291b, delta to head 0 files): pytests RESULT: PASS (exit=0) collected=20401 passed=20398 skipped=3 failed=0 (floor 18404) · nodetests RESULT: PASS (exit=0) tests=1449 pass=1449 fail=0.

Ledger — round 2 · payload lines changed THIS round: 52 (resume-state.sh 38/12 + SKILL.md 1/1), of which only ONE added line is non-comment — the trailing-slash normalisation. Round 1: 187. Non-zero, so the attribution gate does not fire, but the trend is worth naming: this round's payload is 97% prose, and prose that is wrong is where most of both rounds' findings landed.

[ZacxDev]

Audit round 3 complete — seven findings, all scaffolding, all closed in add65a0a.

1. The residual now states all three legs — the base clone's copy, a linked worktree's when only a worktree holds it, and the ambiguity gap when several do — in both SKILL.md and the source comment.
2. The residual's pinning test is parametrised over HOLDER as well as `<Y>` and asserts the `# repo:` line, because `handoff:` prints a basename and cannot distinguish the base-clone leg from the worktree leg.
3. Battery 1 carries the sibling's `expected` attribution: verdicts are KILLED / KILLED(attributed) / KILLED-WRONG-REASON, the last a battery failure, so X17 can no longer pass on an unrelated failure.
4. test_mutation_battery_anchors.py pins that a tuple `old` has a same-length tuple `new`, walking every row of both batteries, so the zip-truncation shape cannot recur in a future row.
5. The battery ledger globs both `mutation_battery_*.py` and `mutants-*.py` with an explicit exemption list, plus a test that fails if an exempted file grows a MUTANTS table.
6. The docstring's enumerator lists both battery families instead of a marker grep that returned zero .sh files.
7. W10's kill count is re-measured at 47 (was 42), and three doc sites describing round 2's fixes as uncommitted are corrected.

🔴 Round 3 was itself partly wrong, and this was checked rather than implemented. It claimed two .sh batteries carry no did-not-apply control. Verified file by file: all nine carry one, in three spellings (MUTATION DID NOT APPLY, mutation did not apply uniquely, 🔴 NOT-APPLIED) — which is the actual reason no single marker grep enumerates the families. The true version is recorded instead of the claimed exception.

Verification

• X17's attribution control — the point of finding 3: with the whole-out assertion PRESENT, f=110 and the phrase appears in the E lines → KILLED(attributed). With it DELETED, f=108 — still "killed" under the old any-test-failed criterion — and the phrase is absent → KILLED-WRONG-REASON. The guard was previously scoring itself green for the wrong reason.
• Battery: NOT APPLIED 0 · CONTROL (pristine): 190 passed, 0 failed · 73/73 killed (rows carrying expected: for the RIGHT reason); problems: none.
• MERGED-TREE gate on the exact current head (main 72ea6d5b + add65a0a): pytests RESULT: PASS (exit=0) collected=20414 passed=20411 skipped=3 failed=0 (floor 18404) · nodetests RESULT: PASS (exit=0) tests=1449 pass=1449 fail=0.
• 201 passed across the anchor module and the resolution suite; scripts/resume-state.sh's diff this round is mechanically comment-only.

Ledger — round 3 · payload: SKILL.md 1/1 and resume-state.sh 21/6 of which ZERO added lines are non-comment. Rounds 1/2/3 payload: 187 → 52 (1 executable) → 0 executable. The attribution gate cannot fire on a prose-payload PR, so the relevant stop criterion is the stated one: no 🔴, blast radius limited to "a document contains a false sentence", and the recurring shape swept at every site rather than at the one reported. The first two have held since round 2; the third is met only now — the tuple-pair invariant is pinned across every row of both batteries rather than at the reported row. Round 4 is running; if it returns only prose findings at no new sites, the remainder gets filed rather than fixed.