[gregoryfoster]

Closes #48 — the decision it asks for, plus the sub-decision it surfaces.

The call: refuse

Unpushed commits on main are the "code that is on no shared branch" case #37 objects to. The staleness objection that keeps behind a warn does not transfer to ahead: origin/main is updated by git fetch and by a successful git push from this repository, so a never-fetched ref can hide behind-ness — remote commits this checkout cannot see — but it cannot manufacture ahead-ness for commits this checkout pushed. Ahead is local evidence, and needs no network call to be sound, which is what the fetch-less guard can afford to assert.

The only false positive needs the identical SHAs published from another clone; through a PR merge the SHAs differ, so the tree reads as diverged rather than merely ahead — refused too, with the behind warning printed alongside it so an operator is not told to push into a rejection.

Option 3 (gate the refusal on .git/FETCH_HEAD freshness) is rejected in the issue thread: that measures inbound knowledge, the behind axis, and says nothing about whether the local commits were pushed.

Sub-decision: a missing origin/main warns out loud

With ahead refusing, silence on a missing ref would make git remote remove origin a bypass of the refusal without touching the guard. Not fatal — HEAD is already proven to be main, so it is absence of evidence — but named.

Changes

• scripts/check_main_checkout.sh — ahead refuses, naming both remedies (git push / git reset --hard origin/main), the staleness hypothesis (git fetch), and the override; missing-ref warn; every warn now prints before the refusal, so one failed start names every condition; the two-tier comment rewritten as the decision.
• tests/test_check_main_checkout.py — ahead refuses, override lets unpushed commits through, diverged refuses and names both sides, missing ref warns and starts, a refused start still names the dirty tree. test_being_behind_origin_main_only_warns unchanged — that is the point.
• deploy/replicator.service — the guard's own comment, which described unpushed as a warn. Comment-only, but the installed unit is a copy: sudo cp deploy/replicator.service /etc/systemd/system/ && sudo systemctl daemon-reload after merge.
• docs/DEPLOYMENT.md, docs/STYLE.md — verdict table, the asymmetry argument, the journald line inventory, and REPLICATOR_ALLOW_ANY_CHECKOUT's incident-time use (a hotfix committed while the remote is unreachable).
• AGENTS.md, README.md, docs/COMMANDS.md, the DEPLOYMENT lifecycle table — the deploy sequence now splits the two merge paths: git pull --ff-only when the merge happened on GitHub, git push when it happened locally. A line whose first command routinely prints Everything up-to-date is one an operator learns to skip.
• .socraticodecontextartifacts.json — both descriptions that named the guard. Re-index (codebase_context_index) after merge, from the main checkout.

After merge

git pull --ff-only on the VM's main checkout, then the cp above, then restart. The branch also carries 62ce64c ("chore: update skills submodules"), which was committed to local main and never pushed — merging this PR publishes it, which is what makes the pull a fast-forward.

Reviewed as CR #17–#23; findings applied in 2867cbb. Tests: uv run pytest — 777 passed.

🤖 Generated with Claude Code