feat: block edits from the main checkout, and detect two writers on a branch

Two halves of the same failure: work landing outside a worktree, and
nobody noticing when it does.

## The hook

CLAUDE.md has said "never edit any file on main, even a one-line doc fix"
unconditionally for a long time, and it keeps being skipped. The reason
is structural, not carelessness: it is prose, so it has to be REMEMBERED
at the moment of the first edit — and that is exactly the moment a
session which opened as a question has no reason to reconsider it. Six
live sessions currently sit in the main checkout for perfectly good
read-only reasons; nothing catches the one that quietly starts editing.

check-worktree-path.sh already guarded CROSS-checkout edits and passed
same-checkout ones, so main-to-main sailed through. It now also refuses
any edit made from the main checkout, detected by --git-dir equalling
--git-common-dir. That is a path comparison, the only shape
docs/agents/rules.md sanctions here — it never guesses what a command
will touch. Linked worktrees and sibling checkouts both differ, so both
still work; the rule is "be in a worktree", not "be under .claude/".

The denial names the remedy (EnterWorktree) and says what the main
checkout still does — questions, gh, backlog, dispatch — because a block
without a next move gets worked around.

Residual gap, stated plainly: this governs Edit/Write/NotebookEdit. A
Bash `sed -i` still writes. Guarding that would mean parsing command
strings, which rules.md forbids for this hook and which has produced
false positives here four times.

## The detector

pr-state.sh gains a local-writer section. GitHub cannot see this: a
branch with two writers looks normal through the API, because the
divergence exists only between a local checkout and the remote and it
collapses into an ordinary merge the moment someone reconciles.

#619 is the worked example. One writer took the branch at 08:09 and
worked from that base; another pushed 23031e7 at 09:34. The reviewer
reviewed 23031e7 three times, twice with blocking findings, while the
first line never held that commit. Fifteen hours later it landed as
`Merge remote-tracking branch 'origin/fix/...' into fix/...` — a branch
merged into itself, which is the fingerprint. `git rev-list --left-right`
would have caught it at 09:34.

Run against the live fleet it also surfaces the precursor state: #437 is
5 commits behind its own remote and #614 is 3, so a commit in either
worktree diverges immediately.

Skipped LOUDLY outside a checkout, since this script is also meant for a
container fleet where a silent skip would read as "no divergence found".

Verified by mutation: disabling the main-checkout guard reddens 2 of the
6 hook tests. The divergence detector is tested against a real two-clone
scenario, not fixtures.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: johanzander

.claude/hooks/check-worktree-path.sh

@@ -53,4 +53,45 @@ if [ "$target_root" != "$session_root" ]; then
   exit 0
 fi
 
+# ---------------------------------------------------------------------------
+# Second check: is this session in a worktree at all?
+#
+# CLAUDE.md's rule is unconditional -- "Never edit any file on main, even a
+# one-line doc fix" -- and it is prose, so it has to be REMEMBERED at the moment
+# of the first edit. That is precisely when it isn't: a session that opens as a
+# question ("why does X happen?") and drifts into implementing never re-evaluates
+# a rule it had no reason to consider at the start. Six live sessions currently
+# sit in the main checkout for exactly that legitimate read-only reason.
+#
+# The cost is not hypothetical. PR #619's branch carries a merge of itself --
+# `Merge remote-tracking branch 'origin/fix/...' into fix/...` -- because two
+# writers worked the same branch from different bases and diverged for fifteen
+# hours. The reviewer reviewed one line three times while the other line, based
+# on a commit from 08:09, never saw a single verdict.
+#
+# So the check is mechanical and fires at the transition itself: the first
+# Edit/Write IS the moment a question becomes an implementation. A linked
+# worktree has its own git dir under the main one, so `--git-dir` and
+# `--git-common-dir` differ there and are identical in the main checkout. That
+# is a path comparison, the only shape docs/agents/rules.md sanctions for this
+# hook -- it never has to guess what a command string will touch.
+#
+# Sibling checkouts (`../bess-manager-feature/`) are linked worktrees too, so
+# they pass: this enforces "work in a worktree", not "work under .claude/".
+git_dir=$(git rev-parse --absolute-git-dir 2>/dev/null || true)
+common_dir=$(cd "$(git rev-parse --git-common-dir 2>/dev/null || echo .)" 2>/dev/null && pwd || true)
+
+if [ -n "$git_dir" ] && [ -n "$common_dir" ] && [ "$git_dir" = "$common_dir" ]; then
+  branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "?")
+  reason="BLOCKED: this session is in the MAIN checkout ('${session_root}', branch '${branch}'), not a worktree, so editing '${target_path}' would write straight into the shared checkout. CLAUDE.md: work in a worktree before ANY edit -- unconditional, including a one-line doc fix. If this session started as a question and has become implementation work, that is the common path here and this is the moment to switch: call EnterWorktree (never \`git worktree add\`, which the sandbox denies), then redo the edit there. The main checkout stays read-only: questions, \`gh\`, the backlog, and dispatch all work fine from it."
+  jq -n --arg reason "$reason" '{
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: $reason
+    }
+  }'
+  exit 0
+fi
+
 echo '{"continue": true}'

backend/tests/test_pr_state.py

@@ -77,6 +77,8 @@ def _rows(out: str) -> str:
 @pytest.fixture
 def run(tmp_path: Path):
     """Shim `gh pr list` with a fixture and return the script's stdout."""
+    outside_a_repo = tmp_path / "not-a-repo"
+    outside_a_repo.mkdir()
 
     def _run(prs: list[dict]) -> str:
         bin_dir = tmp_path / "bin"
@@ -94,7 +96,12 @@ def _run(prs: list[dict]) -> str:
             capture_output=True,
             text=True,
             env=dict(os.environ, PATH=f"{bin_dir}:{os.environ['PATH']}"),
-            cwd=REPO_ROOT,
+            # NOT the repo: the script's local-writer section walks real
+            # worktrees and fetches, which would make every classifier test slow,
+            # networked, and dependent on whatever branches happen to exist.
+            # Outside a checkout it takes the documented skip path instead, which
+            # `test_the_local_writer_check_skips_loudly` pins.
+            cwd=outside_a_repo,
         )
         assert proc.returncode == 0, proc.stderr
         return proc.stdout
@@ -314,3 +321,14 @@ def test_liveness_is_reported_as_unknown_rather_than_guessed(run) -> None:
 
     assert "not a GitHub fact and is not" in out
     assert "guessed here" in out
+
+
+def test_the_local_writer_check_skips_loudly_outside_a_checkout(run) -> None:
+    """The script is meant to run against a container fleet too, where no
+    worktree exists. A silent skip there would read as "no divergence found",
+    which is the same silent-cap failure `sweep-prs` warns about — so the skip
+    has to say that it proves nothing."""
+    out = run([_pr(1)])
+
+    assert "SKIPPED" in out
+    assert "says nothing about writers" in out

backend/tests/test_pr_state_divergence.py

@@ -0,0 +1,154 @@
+"""Tests for pr-state.sh's local-writer section — the two-writers detector.
+
+This is the one thing GitHub cannot tell you. A branch with two writers looks
+completely normal through the API: the divergence exists only between a local
+checkout and the remote, and it collapses into an ordinary merge commit the
+moment somebody reconciles it.
+
+PR #619 is why this exists. One writer took the branch at 08:09 and worked from
+that base; another pushed 23031e78 at 09:34. The reviewer reviewed 23031e78
+three times, twice with blocking findings, while the first line never held that
+commit at all. Fifteen hours later it landed as `Merge remote-tracking branch
+'origin/fix/...' into fix/...` — a branch merged into itself.
+
+So the scenario below is built for real: a bare "origin", two clones that both
+commit to one branch, and the assertion that the script names it.
+"""
+
+import json
+import os
+import stat
+import subprocess
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SCRIPT = REPO_ROOT / "scripts" / "pr-state.sh"
+
+GIT_ENV = {
+    "PATH": "/usr/bin:/bin:/usr/local/bin:/opt/homebrew/bin",
+    "GIT_CONFIG_GLOBAL": "/dev/null",
+    "GIT_CONFIG_SYSTEM": "/dev/null",
+    "GIT_AUTHOR_NAME": "t",
+    "GIT_AUTHOR_EMAIL": "t@t",
+    "GIT_COMMITTER_NAME": "t",
+    "GIT_COMMITTER_EMAIL": "t@t",
+}
+
+BRANCH = "fix/issue-592-vpp-idle-at-floor"
+
+
+def _git(cwd: Path, *args: str) -> str:
+    proc = subprocess.run(
+        ["git", *args],
+        cwd=cwd,
+        check=True,
+        capture_output=True,
+        text=True,
+        env={**GIT_ENV, "HOME": str(cwd)},
+    )
+    return proc.stdout.strip()
+
+
+def _commit(repo: Path, name: str) -> None:
+    (repo / name).write_text(name)
+    _git(repo, "add", name)
+    _git(repo, "commit", "-q", "-m", name)
+
+
+@pytest.fixture
+def two_writers(tmp_path: Path) -> Path:
+    """A checkout whose branch has diverged from its own remote.
+
+    Writer B pushes; writer A, which branched earlier, commits locally without
+    pulling. That is #619's shape exactly.
+    """
+    origin = tmp_path / "origin.git"
+    origin.mkdir()
+    _git(origin, "init", "-q", "--bare", "-b", "main")
+
+    writer_b = tmp_path / "writer-b"
+    _git(tmp_path, "clone", "-q", str(origin), "writer-b")
+    _commit(writer_b, "seed")
+    _git(writer_b, "push", "-q", "origin", "main")
+    _git(writer_b, "checkout", "-q", "-b", BRANCH)
+    _commit(writer_b, "from-b")
+    _git(writer_b, "push", "-q", "origin", BRANCH)
+
+    writer_a = tmp_path / "writer-a"
+    _git(tmp_path, "clone", "-q", str(origin), "writer-a")
+    _git(writer_a, "checkout", "-q", "-b", BRANCH, "--no-track", "origin/main")
+    _commit(writer_a, "from-a")
+    # A never pulled B's push, so the two lines have no common tip.
+    return writer_a
+
+
+def _run(cwd: Path, tmp_path: Path, prs: list[dict]) -> str:
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir(exist_ok=True)
+    (bin_dir / "prs.json").write_text(json.dumps(prs))
+    gh = bin_dir / "gh"
+    gh.write_text(f"#!/bin/sh\ncat '{bin_dir}/prs.json'\n")
+    gh.chmod(gh.stat().st_mode | stat.S_IEXEC)
+
+    proc = subprocess.run(
+        ["bash", str(SCRIPT)],
+        capture_output=True,
+        text=True,
+        cwd=cwd,
+        env=dict(os.environ, PATH=f"{bin_dir}:{os.environ['PATH']}"),
+    )
+    assert proc.returncode == 0, proc.stderr
+    return proc.stdout
+
+
+def _pr(number: int, branch: str) -> dict:
+    return {
+        "number": number,
+        "title": f"pr {number}",
+        "isDraft": True,
+        "mergeable": "MERGEABLE",
+        "mergeStateStatus": "CLEAN",
+        "headRefName": branch,
+        "updatedAt": "2026-08-17T00:00:00Z",
+        "reviews": [],
+        "commits": [{"committedDate": "2026-08-17T00:00:00Z"}],
+        "comments": [
+            {"body": "@claude-bot review", "createdAt": "2026-08-18T00:00:00Z"}
+        ],
+        "statusCheckRollup": [
+            {"name": "Fast tests", "status": "COMPLETED", "conclusion": "SUCCESS"}
+        ],
+    }
+
+
+def test_two_writers_on_one_branch_are_named(two_writers: Path, tmp_path: Path) -> None:
+    """The #619 shape. Local has a commit the remote lacks AND the remote has a
+    commit local lacks — which cannot happen with a single writer."""
+    out = _run(two_writers, tmp_path, [_pr(619, BRANCH)])
+
+    assert "DIVERGED" in out
+    assert "TWO WRITERS" in out
+    assert "#619" in out
+
+
+def test_a_branch_in_sync_is_not_flagged(two_writers: Path, tmp_path: Path) -> None:
+    """Guards against a detector that shouts on every branch — which would get
+    it ignored, the way a CONFLICTING PR with no checks got ignored."""
+    _git(two_writers, "fetch", "-q", "origin")
+    _git(two_writers, "reset", "-q", "--hard", f"origin/{BRANCH}")
+    out = _run(two_writers, tmp_path, [_pr(619, BRANCH)])
+
+    assert "DIVERGED" not in out
+    assert "in sync" in out
+
+
+def test_a_branch_with_no_open_pr_is_not_reported(
+    two_writers: Path, tmp_path: Path
+) -> None:
+    """The fleet has ~47 worktrees and most have no open PR. Listing them all
+    would bury the one line that matters."""
+    out = _run(two_writers, tmp_path, [_pr(999, "some/other-branch")])
+
+    assert BRANCH not in out.split("Local writers")[-1]

backend/tests/test_worktree_hook.py

@@ -0,0 +1,146 @@
+"""Tests for .claude/hooks/check-worktree-path.sh.
+
+The hook is the only mechanical enforcement of "work in a worktree before ANY
+edit". CLAUDE.md has stated that rule unconditionally for a long time and it
+still gets skipped, because prose has to be REMEMBERED at the moment of the
+first edit — and that is exactly the moment a session which opened as a question
+has no reason to reconsider it.
+
+The damage is on the record. PR #619's branch carries a merge of itself
+(`Merge remote-tracking branch 'origin/fix/...' into fix/...`) because two
+writers worked the same branch from different bases and diverged for fifteen
+hours; the reviewer reviewed one line three times while the other, based on a
+commit from 08:09, never saw a verdict.
+
+So these tests pin the decision the hook makes, against real git checkouts built
+in tmp_path rather than the developer's own layout.
+"""
+
+import json
+import subprocess
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+HOOK = REPO_ROOT / ".claude" / "hooks" / "check-worktree-path.sh"
+
+
+def _git(cwd: Path, *args: str) -> None:
+    subprocess.run(
+        ["git", *args],
+        cwd=cwd,
+        check=True,
+        capture_output=True,
+        env={
+            "PATH": "/usr/bin:/bin:/usr/local/bin:/opt/homebrew/bin",
+            "HOME": str(cwd),
+            "GIT_CONFIG_GLOBAL": "/dev/null",
+            "GIT_CONFIG_SYSTEM": "/dev/null",
+            "GIT_AUTHOR_NAME": "t",
+            "GIT_AUTHOR_EMAIL": "t@t",
+            "GIT_COMMITTER_NAME": "t",
+            "GIT_COMMITTER_EMAIL": "t@t",
+        },
+    )
+
+
+@pytest.fixture
+def repo(tmp_path: Path) -> Path:
+    """A real main checkout on `main` with one commit."""
+    main = tmp_path / "main-checkout"
+    main.mkdir()
+    _git(main, "init", "-q", "-b", "main")
+    (main / "seed.txt").write_text("seed\n")
+    _git(main, "add", "seed.txt")
+    _git(main, "commit", "-q", "-m", "seed")
+    return main
+
+
+@pytest.fixture
+def worktree(repo: Path, tmp_path: Path) -> Path:
+    """A linked worktree of that checkout — the sanctioned place to edit."""
+    wt = tmp_path / "linked-worktree"
+    _git(repo, "worktree", "add", "-q", "-b", "feat/x", str(wt))
+    return wt
+
+
+def _decide(cwd: Path, target: Path) -> dict:
+    """Run the hook as Claude Code would, and return its decision."""
+    proc = subprocess.run(
+        ["bash", str(HOOK)],
+        cwd=cwd,
+        input=json.dumps({"tool_input": {"file_path": str(target)}}),
+        capture_output=True,
+        text=True,
+    )
+    assert proc.returncode == 0, proc.stderr
+    return json.loads(proc.stdout)
+
+
+def _denial(decision: dict) -> str | None:
+    hook_out = decision.get("hookSpecificOutput")
+    if not hook_out or hook_out.get("permissionDecision") != "deny":
+        return None
+    return hook_out["permissionDecisionReason"]
+
+
+def test_editing_from_the_main_checkout_is_blocked(repo: Path) -> None:
+    """The gap this closes. The pre-existing check only fired when the target
+    was a DIFFERENT checkout, so an edit made from the main checkout to a file
+    in the main checkout — the exact shape of a question-session that drifted
+    into implementing — sailed through."""
+    reason = _denial(_decide(repo, repo / "seed.txt"))
+
+    assert reason is not None
+    assert "MAIN checkout" in reason
+    # The remedy has to be in the message: an agent that is blocked without
+    # being told the next move retries or works around it.
+    assert "EnterWorktree" in reason
+
+
+def test_the_message_names_the_branch_and_the_read_only_escape(repo: Path) -> None:
+    """Blocking is only half the job. The main checkout has legitimate
+    read-only uses — six live sessions sit there asking questions, running
+    `gh`, and dispatching — so the denial must say what still works, or it
+    reads as "this session is useless here"."""
+    reason = _denial(_decide(repo, repo / "seed.txt"))
+
+    assert reason is not None
+    assert "branch 'main'" in reason
+    assert "read-only" in reason
+
+
+def test_editing_inside_a_linked_worktree_is_allowed(worktree: Path) -> None:
+    """The rule must not block the sanctioned path, or it just gets disabled."""
+    decision = _decide(worktree, worktree / "seed.txt")
+
+    assert _denial(decision) is None
+    assert decision.get("continue") is True
+
+
+def test_a_new_file_in_a_worktree_is_allowed(worktree: Path) -> None:
+    """Resolution goes via the parent directory so a not-yet-created file still
+    lands in the right checkout — pinned because most edits during
+    implementation create files."""
+    decision = _decide(worktree, worktree / "brand-new.py")
+
+    assert _denial(decision) is None
+
+
+def test_cross_checkout_edits_are_still_blocked(repo: Path, worktree: Path) -> None:
+    """Regression guard on the original purpose: a stale absolute path from an
+    earlier turn writing into a different checkout."""
+    reason = _denial(_decide(worktree, repo / "seed.txt"))
+
+    assert reason is not None
+    assert "DIFFERENT checkout" in reason
+
+
+def test_outside_a_git_repo_the_hook_stays_out_of_the_way(tmp_path: Path) -> None:
+    """The hook governs this repo's worktree discipline, not the filesystem."""
+    plain = tmp_path / "not-a-repo"
+    plain.mkdir()
+    decision = _decide(plain, plain / "file.txt")
+
+    assert _denial(decision) is None