ci: guard main so a PR into it brings nothing not already on v2/main

[cliffhall]

Closes #5119

Description

Adds a guard so that a pull request into main can bring nothing that is not already on v2/main.

• scripts/verify-main-source.mjs (+ tests): passes when the PR's head commit is origin/v2/main or an ancestor of it, and fails otherwise, listing each commit the head carries that v2/main does not. The check is on the commit rather than the branch name, because the release skill opens the merge PR from v2/chore/<N>-release-<milestone>, a branch pushed from origin/v2/main. It accepts an ancestor because v2/main keeps moving while the merge PR is open.
• .github/workflows/main-source.yml: the Source is v2/main job, on pull_request_target into main. It runs main's copy of the workflow and of the script, so a PR cannot edit the guard into passing. It checks out main and only fetches the PR head as git objects; none of the PR's code runs. Read-only token, no secrets.
• AGENTS.md, docs/quality-gate.md and the release skill describe the guard and the merge-commit-only rule on main. The ruleset has no bypass actors. A release that cannot be a pure merge (a release branch like 1.0.0's Release v1.0.0: merge v2/release/1.0.0 into main #5090, or a hotfix) goes through only when a repo admin disables the ruleset for that one merge and re-enables it straight away. The release skill has the recipe under "A release that cannot be a pure merge". The guard is not a local:gate stage, since no local push targets main. That exception is stated next to the pack:verify one.

Server Details

None (repository-wide): CI, a root script, docs.

Motivation and Context

GitHub rulesets can require PRs and approvals on main, but cannot restrict where a PR comes from, and #4939 and #5081 merged commits of their own into main. See #5119.

Rollout, which runs alongside this PR:

1. A repo ruleset, main: milestone merges only (id 24866866, no bypass actors), now limits main to merge commits.
2. Because pull_request_target runs main's copy, these three files also go to main in a one-off bootstrap PR (cherry-picked byte-for-byte, so the next milestone merge adds nothing new for them).
3. Once that lands, two throwaway PRs into main probe it live: one from a branch at origin/v2/main, which should pass, and one from a branch with a commit of its own, which should fail. Both are closed unmerged.
4. Then the same ruleset makes Source is v2/main a required check.

How Has This Been Tested?

No client-observable surface, so here are targeted probes:

• node --test scripts/verify-main-source.test.mjs: 9 pass. The cases build throwaway repos shaped like the release flow: a release branch pushed from v2 passes; a head v2 has moved past passes; a branch with its own commit fails and names it; a branch cut from main fails; v2 merged into another branch fails.
• Against this repo's real history:
  • --head origin/v2/main → is on origin/v2/main; nothing else comes with it.
  • --head origin/v2/main~5 → passes.
  • --head HEAD (this branch) → carries 1 commit that origin/v2/main does not.
  • --head 5abed86c (chore: bring the contribution policy to main ahead of the v2.0.0 merge #4939's merge into main) → carries 5 commits that origin/v2/main does not, listing them. That is the case this guard exists to stop.
• npm run local:gate: exit 0.
• Not yet exercised: the escape-hatch recipe (toggling the ruleset's enforcement). Disabling a protection is a human admin's act, so it was not run from the agent session. It should be checked by hand the first time it is needed, or once now while the ruleset holds only the merge-method rule.
• Follow-up filed: Protect v2/main against force-push and deletion #5121 (protect v2/main itself against force-push and deletion, since the guard trusts its history).
• Static tests pin the workflow's safety properties: pull_request_target into main only, read-only, a checkout of main with no ref, the PR head fetched as objects only, no install or execution after that, no secrets, and the event's head SHA passed to the guard. Mutation probe: adding ref: ${{ github.event.pull_request.head.sha }} to the checkout fails exactly the checkout test.
• pull_request_target loads the workflow from main, so the bootstrap PR (step 2) cannot run it. The first live runs were the step 3 probes, after ci: bring the main-source guard to main (bootstrap for #5119) #5122 merged (bbb701e7):
  • DO NOT MERGE: main-source probe (pass) #5123, head = origin/v2/main → pass: 9245b93c… is on origin/v2/main; nothing else comes with it.
  • DO NOT MERGE: main-source probe (fail) #5124, one commit of its own on main → fail: 094c1af0… carries 11 commits that origin/v2/main does not (the probe plus main's own merge commits).
  • Both ran on pull_request_target under the GitHub Actions app (id 15368), and both were closed unmerged.
• Step 4 is done: ruleset 24866866 now requires Source is v2/main from integration 15368, alongside merge-commit-only, with no bypass actors.

Breaking Changes

None for users. For maintainers: any PR into main that is not a pure v2/main merge will fail once the check is required, and main offers only "Create a merge commit".

Types of changes

• Bug fix
• New feature
• Breaking change
• Documentation update (plus CI tooling)

Checklist

• I have read the MCP Protocol Documentation (not applicable: no protocol surface)
• My changes follow MCP security best practices: pull_request_target with no PR code checked out or run, read-only token
• I have updated the server's README accordingly (not applicable: no server changed)
• I have added a changeset (not applicable: no published package changes)
• I have tested this with an LLM client (not applicable: CI-only change; see the probes above)
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling: unresolvable revisions and git failures fail closed
• I have documented all environment variables and configuration options (not applicable: none added)

🤖 Generated with Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: 8002268

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[Copilot]

🟡 Changes recommended

Workflow regression coverage and documentation and rollout inaccuracies remain unresolved.

3 open findings

• Add static tests for workflow security and SHA wiring · New
• Correct bootstrap rollout evidence for pull_request_target · New
• Update quality-gate text to reflect the additional CI-only check · New

What changed in this PR

Adds CI enforcement ensuring PRs into main contain only commits already present on v2/main.

Changes:

• Adds the source-verification script and tests.
• Adds a protected pull_request_target workflow.
• Documents the release-branch policy and guard.

File	Description
.github/​workflows/​main-source.yml	Runs the source guard for PRs into main.
scripts/​verify-main-source.mjs	Verifies PR-head ancestry and reports violations.
scripts/​verify-main-source.test.mjs	Tests argument handling and Git histories.
docs/​quality-gate.md	Documents the new CI-only check.
AGENTS.md	Records repository and release rules.
.claude/​skills/​release/​SKILL.md	Updates milestone-merge instructions.

🧠 Review effort: Balanced

[cliffhall]

Copilot round 1: 3 findings, all addressed.

• Workflow safety not pinned by tests → fixed in 9422c3f (three static workflow tests, plus a mutation probe).
• Bootstrap rollout claim wrong for pull_request_target → PR body corrected; live probes after the bootstrap, before the check is made required.
• quality-gate.md contradicted itself → fixed in 9422c3f.

Gate green on 9422c3f. Requesting round 2.

[Copilot]

🟢 Approval recommended

The guard is fail-closed, securely isolated from PR code, thoroughly tested, and consistently documented.

1 open finding

• Add static tests for workflow security and SHA wiring

2 resolved since last review

• Update quality-gate text to reflect the additional CI-only check
• Correct bootstrap rollout evidence for pull_request_target

🧠 Review effort: Balanced

[cliffhall]

Copilot round 2: clean (no new findings). The one item it still lists as open is round 1's workflow-tests thread, already fixed in 9422c3f.

Since then, c9c6e0e adds the admin escape hatch for a release that cannot be a pure merge (release skill, plus one sentence in AGENTS.md), on the maintainer's decision to keep the guard strict. Gate green; requesting round 3 for that commit.

[Copilot]

🟡 Changes recommended

The escape-hatch procedure can leave main unprotected if interrupted before the ruleset is restored.

2 open findings

• Ensure ruleset is restored on script exit or failure · New
• Add static tests for workflow security and SHA wiring

🧠 Review effort: Balanced

[cliffhall]

Copilot round 3: 1 new finding (escape hatch could leave the ruleset disabled if interrupted), fixed in 8002268. Disable, merge and re-enable now run under one exit trap, verified in bash and zsh against a fake gh on success, failure and SIGINT. The other item it lists as open is round 1's workflow-tests thread, already fixed in 9422c3f.

Gate green on 8002268. Requesting round 4.

[Copilot]

🟢 Approval recommended

The implementation matches #5119, fails closed, and has comprehensive automated and live-probe coverage.

0 open findings

2 resolved since last review

• Ensure ruleset is restored on script exit or failure
• Add static tests for workflow security and SHA wiring

🧠 Review effort: Balanced

[cliffhall]

Copilot round 4: clean (0 open findings, both earlier threads resolved). Review loop done; ready for a maintainer merge.