H13: session-end must leave the shared checkout fresh — a stale tree serves stale FILES, which no HEAD-reading rule catches #541

Closed
opened 2026-07-21 19:19:11 +02:00 by timothy · 1 comment
Owner

What happened (2026-07-21, during #536)

The session kickoff was given docs/handoffs/chicorytv-issue-queue.md pasted from /Users/timothy/ersatztv, which was sitting 81 commits behind origin/main on a clean main. That copy still described the retired queue protocol — "the selector reads the pinned tracker ersatztv#237", "read #237's last ~6 session comments" — which #520 had superseded the day before. The version on main says the opposite in as many words: #237 is closed and must not be read for queue state.

Nothing broke, because selection went through scripts/select-queue.sh and never touched #237. But that was luck of routing, not a control.

Why the existing rule does not cover this

The standing lore is emphatic that the shared tree is not a main mirror and that its HEAD/git log/git status must never be read as truth about main. Every failure it describes is a session reading git state. This one read a file — no git command was ever run against that tree, so no amount of "check harder" would have fired. A stale checkout silently serves stale content, and the docs in it are exactly the content a kickoff depends on.

That lore bullet already concedes the shape of the fix: "This is a design flaw, not a discipline failure — do not 'fix' it by telling sessions to check harder. A check does not stay true." The tree being stale is the root condition; the fix is to stop it being stale.

Fix

scripts/refresh-shared-checkout.sh, run at session end (idempotent, so session start works too). It fast-forwards the shared tree to origin/main and reinstalls web/node_modules when the lockfile moved.

Deliberately timid, because the tree is shared and another session may be mid-flight in it. It refuses and changes nothing — loudly, exit 0 — when the tree is not on main, is dirty, has local commits, or is mid-rebase/merge. It never switches branches, never stashes, never discards. A refusal is a normal outcome.

Two details worth keeping:

  • It uses npm ci, not npm install — install can rewrite package-lock.json, which would leave the shared tree dirty, and a dirty tree is exactly what the next run refuses on. Caught in testing when the first version did precisely that.
  • It asserts the tree is clean at exit and reports loudly if not, since leaving it dirty is the one outcome that would make the script a net negative.

Done-when

  • scripts/refresh-shared-checkout.sh exists, is executable, and refuses safely on every unsafe state (not-main, dirty, ahead, mid-rebase, missing)
  • Happy path fast-forwards and refreshes node_modules only when the lockfile moved
  • Wired into the session-end protocol in docs/handoffs/chicorytv-issue-queue.md
  • Convention recorded in docs/decisions.md
  • Independent adversarial review passed

Refs #520, #311, #312.

## What happened (2026-07-21, during #536) The session kickoff was given `docs/handoffs/chicorytv-issue-queue.md` **pasted from `/Users/timothy/ersatztv`**, which was sitting **81 commits behind** `origin/main` on a clean `main`. That copy still described the retired queue protocol — "the selector reads the pinned tracker ersatztv#237", "read #237's last ~6 session comments" — which #520 had superseded the day before. The version on `main` says the opposite in as many words: #237 is closed and **must not** be read for queue state. Nothing broke, because selection went through `scripts/select-queue.sh` and never touched #237. But that was luck of routing, not a control. ## Why the existing rule does not cover this The standing lore is emphatic that the shared tree is not a `main` mirror and that its `HEAD`/`git log`/`git status` must never be read as truth about `main`. Every failure it describes is a session **reading git state**. This one read a **file** — no `git` command was ever run against that tree, so no amount of "check harder" would have fired. A stale checkout silently serves stale *content*, and the docs in it are exactly the content a kickoff depends on. That lore bullet already concedes the shape of the fix: *"This is a design flaw, not a discipline failure — do not 'fix' it by telling sessions to check harder. A check does not stay true."* The tree being stale is the root condition; the fix is to stop it being stale. ## Fix `scripts/refresh-shared-checkout.sh`, run at session end (idempotent, so session start works too). It fast-forwards the shared tree to `origin/main` and reinstalls `web/node_modules` when the lockfile moved. Deliberately timid, because the tree is shared and another session may be mid-flight in it. It refuses and changes nothing — loudly, exit 0 — when the tree is not on `main`, is dirty, has local commits, or is mid-rebase/merge. It never switches branches, never stashes, never discards. A refusal is a normal outcome. Two details worth keeping: - It uses **`npm ci`, not `npm install`** — `install` can rewrite `package-lock.json`, which would leave the shared tree dirty, and a dirty tree is exactly what the next run refuses on. Caught in testing when the first version did precisely that. - It **asserts the tree is clean at exit** and reports loudly if not, since leaving it dirty is the one outcome that would make the script a net negative. ## Done-when - [x] `scripts/refresh-shared-checkout.sh` exists, is executable, and refuses safely on every unsafe state (not-main, dirty, ahead, mid-rebase, missing) - [x] Happy path fast-forwards and refreshes `node_modules` only when the lockfile moved - [x] Wired into the session-end protocol in `docs/handoffs/chicorytv-issue-queue.md` - [x] Convention recorded in `docs/decisions.md` - [x] Independent adversarial review passed Refs #520, #311, #312.
timothy added the enhancementpriority: medium labels 2026-07-21 19:19:11 +02:00
Author
Owner

Closing record

Outcome: scripts/refresh-shared-checkout.sh + session-end step 6. PR #543, merged as dc130f25. Dogfooded immediately after merge: it fast-forwarded the shared tree 87 commits to 9713bae4 and left it clean — the staleness that caused this issue is gone.
Root cause: Every existing guard on the shared tree is written for a session reading git state ("never read its HEAD/git log"). This session's kickoff never ran git there — it was handed a file pasted out of that tree while it was 81 commits behind, still describing the queue protocol #520 retired the day before. A stale checkout serves stale content silently, so no discipline check could fire. Nothing broke only because selection went through scripts/select-queue.sh — routing luck, not a control.
Decisions/conventions changed: added session.shared-checkout-refresh.
Reusable knowledge:

  • The shared-tree lore already prescribed the shape of this fix for its earlier failure modes — "a design flaw, not a discipline failure; a check does not stay true." The generalisation: when a rule keeps getting broken by people doing the obvious thing, remove the stale condition rather than adding a check.
  • npm ci, never npm install, in any script that touches a shared tree. install rewrote package-lock.json and left the tree dirty — the exact state the next run refuses on, so the tool would have disabled itself after one use. Caught by running the script twice in testing, not by reading it.
  • [ -d "$dir/.git" ] is not proof $dir is a repo root. With an invalid .git and any ancestor repo, git walks up and every subsequent command operates on the ancestor. For a script that fast-forwards and reinstalls, that is the worst possible outcome; assert git rev-parse --show-toplevel equals the resolved cwd.
  • A refusal path is a feature: the script leaves the working tree untouched on not-main / dirty / ahead / detached / mid-rebase-merge-cherry-pick-revert-bisect / not-a-repo-root, and says so.
    Verification: executed against 18 scratch-repo states by the reviewer plus my own 7 (never the real tree), confirming clean-at-exit and correct refusal in each; full CI green; then the live run above.
    Deferred: none.
    Docs updated: docs/decisions.md (new record, catalog regenerated), docs/handoffs/chicorytv-issue-queue.md (session-end step 6). The narrative deliberately stayed out of the handoff doc — which became #542.
## Closing record **Outcome:** `scripts/refresh-shared-checkout.sh` + session-end step 6. PR #543, merged as `dc130f25`. **Dogfooded immediately after merge: it fast-forwarded the shared tree 87 commits to `9713bae4` and left it clean** — the staleness that caused this issue is gone. **Root cause:** Every existing guard on the shared tree is written for a session *reading git state* ("never read its HEAD/`git log`"). This session's kickoff never ran `git` there — it was handed a **file** pasted out of that tree while it was 81 commits behind, still describing the queue protocol #520 retired the day before. A stale checkout serves stale content silently, so no discipline check could fire. Nothing broke only because selection went through `scripts/select-queue.sh` — routing luck, not a control. **Decisions/conventions changed:** added `session.shared-checkout-refresh`. **Reusable knowledge:** - The shared-tree lore already prescribed the shape of this fix for its earlier failure modes — *"a design flaw, not a discipline failure; a check does not stay true."* The generalisation: when a rule keeps getting broken by people doing the obvious thing, remove the stale condition rather than adding a check. - **`npm ci`, never `npm install`, in any script that touches a shared tree.** `install` rewrote `package-lock.json` and left the tree dirty — the exact state the next run refuses on, so the tool would have disabled itself after one use. Caught by running the script twice in testing, not by reading it. - **`[ -d "$dir/.git" ]` is not proof `$dir` is a repo root.** With an invalid `.git` and any ancestor repo, git walks *up* and every subsequent command operates on the ancestor. For a script that fast-forwards and reinstalls, that is the worst possible outcome; assert `git rev-parse --show-toplevel` equals the resolved cwd. - A refusal path is a feature: the script leaves the working tree untouched on not-main / dirty / ahead / detached / mid-rebase-merge-cherry-pick-revert-bisect / not-a-repo-root, and says so. **Verification:** executed against 18 scratch-repo states by the reviewer plus my own 7 (never the real tree), confirming clean-at-exit and correct refusal in each; full CI green; then the live run above. **Deferred:** none. **Docs updated:** `docs/decisions.md` (new record, catalog regenerated), `docs/handoffs/chicorytv-issue-queue.md` (session-end step 6). The narrative deliberately stayed out of the handoff doc — which became #542.
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: timothy/ersatztv#541