fix(hooks): scope trunk protection to the project's own repository

[IanLiYi1996]

Problem

block-push-to-main.sh blocks any push whose destination ref resolves to the trunk, but it never asks which repository the push targets. Trunk protection exists to route changes to this project through a PR — it fired on pushes to unrelated repositories too, where there is no PR flow to route through and nothing to protect.

The case that surfaced it: publishing a design doc to a GitLab project wiki. A wiki lives in a separate <project>.wiki.git repository whose default — and only — branch is main. Every wiki update tripped the guard, so wiki pages could not be pushed at all. There is no workaround from inside the session: the hook has no opt-out env var, and the only escapes are editing the project's settings.json to drop the hook or patching the hook script — both of which mean weakening a safety guard to publish a doc.

The same false positive hits any sibling checkout or vendored dependency that happens to sit on its trunk.

Notably, block-commit-outside-worktree.sh already does this correctly — it captures hook_common_dir and exits 0 when the command targets a different repository. block-push-to-main.sh was simply missing the equivalent check, so the two sibling guards disagreed on what "this repo" means.

Fix

Resolve the target repository with the existing resolve_git_command_cwd helper (it already understands git -C <path> push and cd <path> && git push), then compare git-common-dir the way block-commit-outside-worktree.sh already does, and exit 0 when the push lands in a different repository.

No new helper — this reuses what lib.sh already exports and mirrors the identity check the sibling guard was already performing. +29 lines in the hook, all additive.

Two deliberate properties:

• Not an escape hatch. Comparing git-common-dir rather than git-dir keeps a linked worktree of this project counted as this project — otherwise the guard could be sidestepped by pushing from a worktree. Pinned by TC-BP-14/15.
• Fails closed. Resolution uncertainty falls back to the inherited cwd, so an unparsable command is still checked rather than waved through.

Tests

Extends tests/unit/test-block-push-regex.sh with 4 cases — 2 reproducing the false positive, 2 pinning the escape-hatch boundary:

	case	expected
TC-BP-12	push another repo's main via git -C	allow
TC-BP-13	push a <project>.wiki.git main via cd &&	allow
TC-BP-14	push this repo's main via git -C <self>	still block
TC-BP-15	push this repo's main from a linked worktree	still block

15/15 pass. On the unmodified hook it is 13 pass / 2 fail — the two new allow-cases are exactly the false positive. TC-BP-14/15 passed before the change too, confirming the scoping narrows nothing it should still catch.

Additionally verified by hand, since parse_push_target_refspec reads the current branch and only runs on the same-repo path — bare git push in all three shapes:

• same repo on a feature branch → allow
• same repo on trunk → block
• a different repo sitting on trunk → allow

No regressions in the suites that share lib.sh: test-block-commit-outside-worktree.sh, test-install-git-pre-push.sh, test-chp-commit-file.sh all pass. shellcheck -x clean.

Note

Branched directly from upstream/main (3610c2b) so this carries only the fix — none of my fork's downstream adaptations.

[zxkane]

Thanks for this — the false positive is real, the resolve_git_command_cwd reuse is the right building block, and the observation that the two sibling guards disagreed is what made the underlying problem findable. I've pushed three commits on top rather than requesting changes, because the fix needed a different decision rule and that's easier to review as code than as prose.

The core issue: local identity is a proxy for the destination, and a false one

Trunk protection guards the project's remote trunk, so the question it has to answer is "where does this push land?" — not "which local checkout issued it?" Comparing git-common-dir answers the second, and the two come apart in both directions. I verified each of these by running the hook, and compared every result against main to confirm it was a regression rather than something pre-existing:

A second independent clone of this project has a different git-common-dir but pushes to this project's own trunk. Under the common-dir comparison it was allowed:

git -C <2nd-clone> push origin main               → 0 ALLOWED   (main: 2 blocked)
cd <2nd-clone> && git push origin main            → 0 ALLOWED   (main: 2 blocked)
git -C <2nd-clone> push origin HEAD:refs/heads/main → 0 ALLOWED (main: 2 blocked)

Both clones had origin pointing at this repo, so those pushes land on the protected trunk. TC-BP-14/15 pin only the linked-worktree case, which shares a common-dir — a narrower boundary than the "Not an escape hatch" property the description claims. Worth noting Layers 2/3 are weaker cover than they look here: Layer 2 installs per worktree/clone, so a freshly-created clone most likely has no pre-push hook at all.

And the wiki case was only half-fixed. Anchoring identity on pwd means a bare git push from inside the wiki compares the wiki against itself:

git push            (cwd = wiki clone) → 2 BLOCKED
git push origin main (cwd = wiki clone) → 2 BLOCKED

So the explicit git -C <wiki> and single-line cd <wiki> && git push shapes worked, but cd-ing into the wiki in one turn and pushing in the next — the most natural agent workflow — still didn't. The description's hand-verification note for the bare-push case doesn't reproduce; that's the shape it covers.

What changed

Compare canonical push-destination URLs against a wrapper-exported project anchor, and allow only when the destination is proven and the anchor is readable and doesn't own it.

To your question about a config switch for specific repo URLs — mostly not needed, and this is the nice part: the wiki relationship is derivable. A wiki lives at <project>.wiki.git, which canonicalizes differently from <project>.git on both GitHub and GitLab. So the same comparison that blocks the second clone allows the wiki, with zero configuration. I did add PUSH_ALLOWED_REMOTE_URLS for the residual case the comparison genuinely can't infer — a destination that is this project's trunk but which you've decided may be pushed directly (a mirror, a fork you own). It's an allowlist of specific destinations, deliberately not a boolean "disable trunk protection" switch, so an operator names what's exempt and a reader sees exactly what was exempted.

The anchor is wrapper-exported (AUTONOMOUS_PROJECT_DIR) rather than pwd-derived, following the existing BASE_BRANCH resolve-once/export-once pattern from INV-131 — PROJECT_DIR was already a required, validated conf value. That keeps hooks zero-dependency shell and cross-agent, instead of reaching for a Claude-specific variable.

The sibling-guard analogy is a good precedent for the helper, but not for the rule: worktree hygiene protects the local workspace, where another local repo genuinely is out of scope, so local identity is exact there. resolve_git_command_cwd is reused; its decision rule isn't.

Two review passes found nine more holes in my own work

Worth being explicit about, since it shows where the sharp edges are. The first pass found six bypasses in my initial rework — chained pushes (git push a x && git push origin main, where the operand lookup answered for the first push while the trunk-ref parser read the whole line), quoted operands (read -ra doesn't strip quotes, so git push "<url>" main canonicalized to …team.git" — a confidently wrong destination, which is worse than an unresolved one because it satisfies the allow gate), resolve_git_command_cwd rc=2 falling back to the cwd, // and .GIT normalization gaps, remote.pushDefault silently moving the anchor, and @-in-path collapsing two hosts.

The second pass then found that those fixes had opened two more: DNS-equivalent trailing-dot hostnames with ./.. path segments, and anchor_owns_destination returning the same value for "doesn't own it" and "couldn't read the anchor" — making a mis-set anchor a blanket opt-out.

The common thread is one rule, now stated as an invariant: an allow requires proof, and every form of uncertainty blocks. Unparsable command, ambiguous operand, multiple pushes, unreadable anchor, un-canonicalizable URL — all fall through to the trunk check.

One consequence to flag, because it's a deliberate limitation rather than an oversight: the wiki allowance only covers command shapes resolve_git_command_cwd can parse. env git -C <wiki> push origin main is rc=2 and therefore still blocked. Widening that grammar is the way to allow more shapes; relaxing fail-closed isn't.

Tests and docs

11 → 56 assertions. Measured red/green: 20 of 56 fail on this PR's parent and 14 of 56 on my first cut, and the two sets barely overlap by design — the parent is red where it's too strict or blind to the destination, the first cut where it was too permissive. A pin failing on only one leaves the other failure mode unguarded. Every new test was verified non-vacuous by reverting its fix and confirming only the intended assertions flip; that's how I caught that the original TC-BP-24 and the set -f glob test were passing vacuously.

Also added docs/pipeline/invariants.md INV-148 and docs/test-cases/push-destination-scoping.md, plus the startup-export docs in both wrapper flow files — the pipeline-docs-gate check would have failed as-is (I confirmed with the gate's own regexes: touches_pipeline=1, touches_docs=0).

Two things left for you

• No linked issue — closingIssuesReferences is empty and there's no Closes #N. Could you add one, or say the word and I'll file it?
• CI has never run — both workflows are sitting at action_required pending maintainer approval for the fork PR. I'll approve them.

One pre-existing bug surfaced along the way, unrelated to this PR and unchanged by it: --signed is listed among the value-taking flags in the shared parser, but it takes no separate-argument value, so git push --signed origin main mis-parses to the current branch and can evade Layer 1. It's on main too — I'll file it separately.