From 0afba4c71d17a230281d60016be7c536c3c979d5 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 14:47:38 +0000 Subject: [PATCH 1/2] docs(agents): note that checkout-from-ref stages the index (#8280) `git checkout -- ` writes the index as well as the working tree, so restoring the file with `cp` after a reverse-verification lap leaves the index holding main's content. `git diff HEAD` reads clean and the tests pass off the working tree, while a bare `git commit` builds from the index and lands a commit that deletes the fix the PR claims to make. Verified in a worktree before writing: MM in `git status --porcelain`, clean `git diff HEAD`, 2 deletions in `git diff --cached`, and a bare commit that captured the reversion. Both prescribed restores (`git checkout HEAD -- ` and `git restore --source=HEAD --staged --worktree `) clear index and tree together. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_018WuTtyckQa1VcXwgd52JpN --- AGENTS.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 9e79f13901..cd93beb04e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -192,6 +192,20 @@ being in the session transcript. If you ever retype a lost change, prove identit insertion count is **not** byte-identity — then re-run the reverse verification from the committed state, so the red/green numbers you report are trustworthy. +**⛔ And `git checkout -- ` STAGES what it retrieves — putting the file +back with `cp` undoes only half of it.** It writes the **index** as well as the working +tree, so after `git checkout origin/main -- ` … `cp` your copy back, the index +holds `main`'s content while the tree holds yours. Measured here: +`git status --porcelain` shows `MM` (staged *and* unstaged modifications on one path) +and `git show :` reads back `main`'s copy — but `git diff HEAD` is **clean** (it +compares the tree with HEAD and never consults the index), the tests pass because they +read the tree, and a bare `git commit` builds from the **index**: a commit that deletes +your own fix, in a PR whose body accurately describes a change it does not contain (one +real PR had 157 such deletions staged, caught only by the `MM`). Restore with +`git checkout HEAD -- ` or `git restore --source=HEAD --staged --worktree ` +— both reset index *and* tree — and read `git status --porcelain` before you commit; +⛔ never trust `git diff HEAD` alone after a checkout-from-ref. + **Claim the issue BEFORE you write any code.** Assign it to yourself (`gh issue edit --add-assignee @me`, or `issue_write` with `assignees`) as the *first* action of the task — before the worktree, before the first read. An unassigned From f1c0aeecea18d57d4017e4b5a27357a5e602a9f2 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 14:57:18 +0000 Subject: [PATCH 2/2] docs(agents): name the non-staging way in, per seat ruling (#8280) One clause appended to the checkout-from-ref note: `git restore --source= -- ` without `--staged` writes the working tree only, so the foreign copy never reaches the index and the trap cannot arise. Prevention at source beside the existing cure. Measured with the exact prescribed form on this branch (HEAD holds the note, origin/main does not): porcelain ' M AGENTS.md', `git diff --cached` empty (index untouched), and the restore verified by byte-identity of hash-object against the HEAD blob. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_018WuTtyckQa1VcXwgd52JpN --- AGENTS.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index cd93beb04e..2fdf10862f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -204,7 +204,10 @@ your own fix, in a PR whose body accurately describes a change it does not conta real PR had 157 such deletions staged, caught only by the `MM`). Restore with `git checkout HEAD -- ` or `git restore --source=HEAD --staged --worktree ` — both reset index *and* tree — and read `git status --porcelain` before you commit; -⛔ never trust `git diff HEAD` alone after a checkout-from-ref. +⛔ never trust `git diff HEAD` alone after a checkout-from-ref. Better still, don't +stage it at all: `git restore --source= -- ` (no `--staged`) writes the tree +only — porcelain shows a lone unstaged `M`, not `MM` — so prefer it when standing +another ref's version up for a counterfactual. **Claim the issue BEFORE you write any code.** Assign it to yourself (`gh issue edit --add-assignee @me`, or `issue_write` with `assignees`) as the