friction: prevent read-only review worktrees from pushing implementation branches

[ll7]

Archetype Metadata

archetype: workflow
evidence_tier: smoke
linked_policy:
  - docs/dev/worktree_lifecycle.md
  - docs/code_review.md
  - AGENTS.md

Goal / Problem

Observed behavior

During the exact-head review of release-tooling PR #8318, a worktree on branch
review/pr-8318-review-20260903 created synthetic merge commit
12347725eaeaa89de03de5bb9e9a9e8a7b5cdad3 and then explicitly pushed
HEAD:fix/issue-8285-erratum-successor-20260902 with force-with-lease. That changed the remote
implementation PR head after its exact-head checks and reviews, despite the worktree's declared
read-only review purpose. The incident was detected by the final remote-head compare-and-swap guard;
#8318 was closed unmerged and replaced by #8320 at the preserved exact commit.

Expected behavior

A read-only review or synthetic-integration worktree must be technically unable to push any remote
ref. Integration checks should use a no-commit merge that is always aborted and should prove the
reviewed remote refs are unchanged before returning success.

Reproduction

# In a worktree intended only for review:
git merge --no-edit origin/main
git push origin HEAD:fix/example-implementation --force-with-lease=<expected-old-sha>

Today the explicit destination refspec bypasses the fact that the review branch has no upstream.

Scope

• Affected modules: linked-worktree creation/review helpers, push guards, and agent review guidance.
• Regression: no; this is an observed missing safety boundary.
• In scope:
  • define a machine-detectable read-only review-worktree mode;
  • reject every git push initiated from that mode, including explicit HEAD:<other-branch> and
    force-with-lease refspecs;
  • provide a canonical synthetic-integration helper using --no-commit --no-ff, guaranteed abort,
    and before/after git ls-remote assertions;
  • add regression coverage for blocked review pushes and allowed implementation-worktree pushes;
  • update review-agent instructions to use the guarded helper.
• Out of scope:
  • rewriting fix(release): add immutable benchmark erratum workflow (#8285) #8318 history;
  • changing the frozen benchmark source, scientific rows, or release publication contract;
  • globally disabling pushes from ordinary implementation worktrees.

Added Value Estimation

• User impact: prevents an apparently read-only review from silently invalidating reviewed PR state.
• Benchmark impact: protects immutable release and evidence branches from unrelated merge absorption.
• Maintenance impact: converts a behavioral instruction into an executable, testable boundary.
• Why now: the failure occurred during the September erratum release and required a replacement PR.

Effort Estimation

• Rough estimate: 4-8 hours.
• Best estimate: 6 hours.
• Unknowns: whether the safest implementation is a per-worktree Git config, guarded wrapper,
  pre-push hook, or a combination; compatibility with existing shared hooks must be tested.

Complexity Estimation

• Implementation complexity: medium.
• Dependencies: existing worktree helpers and Git hook installation path.
• Open questions: how to preserve the guard across fresh shared-venv worktrees without changing
  remote behavior for implementation worktrees.

Risk Assessment

• Functional risk: a broad guard could block legitimate pushes.
• Compatibility risk: worktree-local Git configuration differs across installed Git versions.
• Rollout risk: guidance-only fixes can still be bypassed by explicit refspecs.
• Mitigation: test both negative review mode and positive implementation mode; fail closed only when
  the worktree is explicitly classified read-only.

Affected Files

• scripts/dev/create_worktree.sh or a dedicated review-worktree helper — establish protected mode.
• repository Git-hook/bootstrap owner — reject pushes from protected review worktrees.
• .agents/skills/implementation-verification/SKILL.md and review workflows — require guarded
  synthetic integration.
• tests/dev/ — subprocess regression tests with a temporary bare remote.

Definition of Done

• Root cause and the explicit-refspec bypass are documented.
• A review-mode worktree cannot push any ref to any configured remote.
• HEAD:<implementation-branch> and force-with-lease attempts fail before remote mutation.
• The canonical synthetic merge leaves the worktree clean and the compared remote refs unchanged.
• An ordinary implementation worktree can still push through the supported path.
• Focused tests, shell/static checks, and the repository readiness gate pass.

Success Metrics

• The incident reproduction deterministically fails before the remote ref changes.
• Before/after remote-ref snapshots are byte-identical in a successful review integration check.
• Existing implementation push workflows retain their expected behavior.

Validation / Testing

• Add a temporary bare-remote test reproducing the explicit destination-ref push.
• Verify protected review mode rejects normal, explicit-refspec, and force-with-lease pushes.
• Verify the supported implementation path still pushes successfully.
• Run focused tests/dev/ coverage plus BASE_REF=origin/main scripts/dev/pr_ready_check.sh.

Estimate Discussion

• Values reflect a bounded workflow/tooling guard plus subprocess Git tests.
• Confidence: 80%; Git-version and hook-installation behavior may expand the test matrix.
• The estimate should be revised after identifying the canonical shared hook/config owner.

Project Metadata

• Priority: high while release branches are active.
• Effort: 6 hours.
• Reviewed: no.

[ll7]

Exact-head review findings for PR #8326

PR #8326 is currently at exact head 7cdeafc4c3f748b7e8a17fcdab787e2310f34ec1 against
origin/main=33d157f1f6eefa3e4b2e4585ad03286f7d7cdbd8. Its advertised focused suite passes, but
the stated acceptance boundary is not yet met:

• A local url.<actual-remote-url>.insteadOf=<blocked-push-url> override combined with
  git push --no-verify origin HEAD:refs/heads/... bypasses both the worktree hook and blocked URL
  rewrite, and successfully mutates the bare remote.
• After review mode is configured, git remote add mirror <different-url> followed by
  git push --no-verify mirror HEAD:refs/heads/... successfully mutates the newly configured
  remote because the static barrier only covers the initial remote set.

Reviews 5098108302 and
5098124286 record the
reproductions. This is not benchmark or scientific evidence. Before merge, either enforce a
contract that prevents remote/config changes and explicitly define the supported threat model, or
narrow the issue/PR acceptance and documentation to the paths actually protected, with regression
coverage for that chosen boundary.

[ll7]

Fix-forward update for PR #8326

PR #8326 now includes commit 7f26a1988bd86423b5ab7ddcd21de1e73f742737, which adds a push-only
catch-all and a regression proving that a remote added after review configuration is blocked under
ordinary Git configuration. The affected suite passes 35 tests locally.

The remaining exact reproduction is the deliberate command-line override
git -c url.<actual-remote-url>.insteadOf=<blocked-push-url> push --no-verify ..., which can replace
the blocked URL before Git's push-only rules apply. The PR body now records that residual and uses
Refs #8321; this issue remains open until the stronger boundary is implemented or the maintainer
explicitly narrows/accepts the threat model. No merge-ready admission is requested.

[ll7]

Review-worktree guard follow-up at c3c902c4c

PR #8326 now includes the receive-pack barrier and push-only catch-all fix-forward, plus a
regression for remotes added after review configuration. At exact head
c3c902c4c6c48beefc9be0a6abac650f6d4a7648 against origin/main=33d157f1f6eefa3e4b2e4585ad03286f7d7cdbd8:

• the focused worktree/receipt/capacity/documentation suite passed: 35 tests;
• Ruff, diff checks, and the full Markdown evidence-link scan passed;
• the PR body and workflow docs now state the boundary honestly and keep this issue open.

The remaining acceptance decision is deliberate Git command-line override behavior. In a temporary
bare-remote fixture, this still succeeds from review mode and creates a ref:

git -c url.<actual-remote-url>.insteadOf=<blocked-push-url> \
  push --no-verify --receive-pack=git-receive-pack origin HEAD:refs/heads/config-override-bypass

This is a repository-local Git guard, not an operating-system sandbox; preventing a caller who
deliberately supplies -c/--receive-pack while skipping hooks would require a stronger process
or OS boundary. The issue remains state:running pending the maintainer decision whether the
narrowed ordinary-invocation contract is sufficient. No merge-ready admission is requested for
PR #8326 while this decision and its hosted checks remain open.

[ll7]

Acceptance-boundary update

PR #8326 is now a bounded partial implementation at exact head 920fa10c2ea492e75365a5bcbb1ed7fd8c383363
against origin/main=791ad449b32b8b39a999be0abd2a613b13201b58. It protects ordinary review-worktree
Git invocations, including configured custom transports, explicit refspecs, inherited/new push URLs,
and --no-verify attempts; its focused suite passes 37 tests.

The deliberate command-line override reproduction remains outside a repository-local Git guard:
git -c ... push --receive-pack=... --no-verify. I opened successor #8343 to own the stronger
process/OS isolation decision and proof. #8321 remains open until its acceptance contract is
explicitly narrowed or #8343 supplies the missing boundary. PR #8326 therefore references, rather
than closes, this issue.