docs(handoff): RETRACT the CI-flake ranked step — that failure is already root-caused in scripts/ci-repro/README.md

[ZacxDev]

Corrects the resume-state-worktree-resolution handoff doc, which landed in #1166 with a ranked next-step that would send the next session to do work that is already done.

The defect

Rank 2 read "File the CI-flake issue — four distinct tests, four PRs, one session, each needing a fresh push."

That failure is already root-caused, on main. scripts/ci-repro/README.md names the mechanism — server.py:_replace_bytes fsyncs the file and then the parent directory inside the request, before the response is written, and devrc-ci is pinned to one node, so stacked runs contend on one disk. It states outright that it hits PRs whose diff cannot reach it, docs-only included. The devrc/tests.md index entry carries the same finding dated 2026-09-01, measured across two docs-only PRs: 4 reds, 3 different tests, scripts/tests targets 464–530 s, each passing 3/3 locally in ~5 s with a --collect-only positive control proving the failing test was actually selected.

So the ranked step is retracted, and the Open-investigations block that fed it is superseded in place rather than deleted — the prior reading stays visible, which is the point of an append-only section.

Why it happened, recorded as a gotcha

I measured that same flake four times across four PRs — attribution against the PR's own file list, a pristine-main control, a same-window sibling PR — and concluded it was unexplained. The answer was in the subsystem index the whole time, with a deeper diagnosis than any of those four measurements produced. /resume step 4 exists for exactly this and costs one command.

Second gotcha, found by a completion audit rather than by any gate: the index write is per-effort, and a multi-effort session will skip the second one. /handoff step 4 ran for effort 1 and not for effort 2. Nothing noticed — the doc, the PRs and the claims were all clean. If a session lands more than one PR, run subsystem_touch --pr <n> once per effort.

Also updated

• Both efforts recorded as merged: fix(resume-state): a handoff in a LINKED WORKTREE reconciled a different initiative (#1164) #1197 → 6421df3c (closes fix(resume-state): an explicit handoff path in a LINKED WORKTREE falls back and reconciles the wrong initiative — #1159 does not close it #1164), test(handoff_doc): close the audit ladder's filed scaffolding gaps (#1093, #1115) #1146 → edbc596f (closes test(handoff_doc): two scaffolding gaps from #1046's audit ladder — a misdirecting failure message and a degenerate-value fixture #1093, test(handoff_doc): four scaffolding gaps from #1046 round 8 — a dead mutation anchor, an unpinned predicate, and unpinned exit values #1115), docs(handoff): stale-base-guard close-out — #1146 merged, the ladder closed on the attribution gate, two follow-ups filed #1166 → e2a9f781. All verified by content on origin/main, never by ancestry.
• The remaining work is now honestly ranked: deploy is rank 1 and has not happened. The two halves go live on different triggers — readlink -f shows scripts/resume-state.sh resolves to itself (live on a plain git pull, 0 references in nix/) while claude/skills/resume/SKILL.md is a store symlink needing a home-manager switch. Pull without switching and the narrowed resolver is live while the deployed prose still describes the old rule.
• test(handoff_doc): two scaffolding gaps from #1146 round 3 — an over-claimed prose pin and a stale floor comment #1160's byte-budget note corrected: feat(handoff): rule (k) — an elimination must name HOW it was eliminated #1144 merged (3d0b77e5) and raised MAX_BYTES to 27,000, so the headroom is 236 B, not the 7 B an earlier note claimed.

Docs only — one file, no code, no tests, no behaviour.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Emy2y7tGJjRee3GV2cNuaJ