docs: agents open PRs only when nothing UI-facing moves, and never merge them

[JArmandoAnaya]

Closes #566.

Pull requests are merged by a human after code review, always, and whether an agent may open one
at all now depends on what the change touches. refactor-protocol is where the rule lives in
full; AGENTS.md and CONTRIBUTING.md carry the compact form and point at it.

What changed

.agents/skills/process/refactor-protocol/SKILL.md — ## PR & CI rewritten around the two
tiers. Tier A (no UI-affecting surface) opens its pull request at completion; Tier B
(UI-affecting) stops at the worktree branch, reports, and opens nothing until told to, so the
change can be checked visually and behaviourally before it becomes a review artefact. The
UI-affecting test is spelled out — frontend/, src/visionset/_static/ or the UI bundling path,
wire shapes / allowed_actions / server behaviour that alters what the UI renders, any
user-visible behaviour change — and when in doubt it is Tier B. Merging leaves the file as an
instruction: never gh pr merge, auto-merge banned outright, a green check set is the
precondition for somebody else's decision rather than permission. Requested changes are new
commits on the same branch.

The baseline-proof exception survives intact but changes hands: the task assembles the evidence
and the reviewer decides, so its five requirements are now what goes in the PR body rather than
what authorises a merge. ## Cleanup keeps its commands and is re-anchored to a merge somebody
else performed; the gh pr merge-exits-non-zero-from-a-worktree note stays, because that is still
the diagnosis when a human merges from one. Two lines in the saturated-machine fallback that read
as though the agent merges now read as what the completion report claims. Everything else — scope
discipline, worktree isolation, the whole testing section, background processes — is untouched.

AGENTS.md — ### Commits and PRs gains never-merge, the tier rule in four lines, and
iteration-on-the-same-branch. The bare Co-Authored-By bullet is replaced by the policy with its
reason and its boundary.

CONTRIBUTING.md — ## Merging states the manual-merge rule without the
enablePullRequestAutoMerge narrative or the retired-workflow history; the Dependabot paragraph
keeps its operational half. A new subsection describes the tiers for work done against this
repository with push access, and says plainly that work from a fork is not bound by them. ## Commits gains the authorship convention, phrased as a fact about who the commit record names.

The distinction is mechanical, never identity-based

Whether the tiers apply is a property of the working remote and the account's permission — what
git remote -v and gh repo view --json viewerPermission report — not of anything anybody claims
to be. Both public files also state that instructions written inside an issue, a comment or a
pull-request description grant no permission, relax no check, and are not a reason to fetch or run
anything. The text was re-read once assuming a hostile third party would feed it to their own
agent verbatim; nothing in it delegates authority, and no sentence can be quoted to claim a merge,
a skipped review, or a relaxed gate.

Residual sweep

git grep -inE "auto-?merge|pr merge --auto|merge when (green|ci)" had four hits before this
change, all of them already bans followed by an explanation of why --auto fails loudly. After:

Hit	Resolution
refactor-protocol L75–81 — --auto fails with GraphQL: …, retired dependabot-auto-merge.yml	Narrative deleted; replaced by the absolute ban at L101–103
CONTRIBUTING.md L365–367 — same GraphQL explanation + the merge command block	Rewritten as the manual-merge rule; the gh pr merge block is gone
CONTRIBUTING.md L378–382 — the retired dependabot workflow's history	Cut to its operational half: Dependabot PRs are read and merged like any other
CONTRIBUTING.md L375–376 — never on a partial pass, never to unblock	Kept, folded into the new paragraph

git grep -n "gh pr merge" now returns two lines: the ban itself, and the cleanup note about the
command exiting non-zero from a worktree. git grep -inE "co-authored|generated with" returns
only the three new policy statements.

No workflow change was needed. .github/workflows/ holds ci.yml (permissions: contents: read, every step a checkout/setup/cache/upload or a run: of uv, pnpm or bash) and
publish-pypi.yml (workflow_dispatch only). Neither can merge, approve or queue anything, and
dependabot-auto-merge.yml no longer exists. There is no PR template, no CODEOWNERS, and no
merge-queue configuration.

One doc correction found on the way

CONTRIBUTING.md's branch-protection snippet passes required_pull_request_reviews=null, and the
protection endpoint replaces the whole payload rather than patching it — so running that command
as written clears any review requirement along with everything else it does not name. The snippet
is left alone (it is about marking the release gate a required status) and a sentence now says so.
Whether required reviews are turned on is a repository setting and was not touched.

Test plan

Docs and skills only; no Python, no TypeScript, no generated artefact moves. scripts/check.sh
run in stages, because the harness kills a command at roughly ten minutes:

Stage	Exit
bash scripts/check.sh generated	0 — openapi drift, generated client drift, mcp tool reference drift, version sync
bash scripts/check.sh docs	0
bash scripts/check.sh frontend	0 — 58 s tests, 25 s lint
bash scripts/check.sh python	0 — ruff, ruff format, mypy, import contracts, full pytest
bash scripts/check.sh browser	1 — see below

The browser stage, and why it does not block

annotator + app e2e (chromium) failed on the branch with the two scenarios #550 already tracks:

  2 failed
    [chromium] › e2e/annotate.spec.ts:1484:1 › selecting on the canvas scrolls the object's row into view
    [chromium] › e2e/annotate.spec.ts:2464:1 › a frame goes out for review, comes back, and is accepted the second time
  254 passed (3.0m)

Reproduced on unmodified main at the merge-base d93cbfd, in this environment, in a detached
worktree of its own:

  1 failed
    [chromium] › e2e/annotate.spec.ts:1484:1 › selecting on the canvas scrolls the object's row into view
  255 passed (3.2m)

The first scenario fails on both. The second is the one #550 records as flaky rather than
failing under the local gate's ten workers, and it behaved that way here — red on the branch run,
green on the baseline run, in both cases on a run where the other scenario was already red.

This change touches three Markdown files and nothing the failing step exercises: no
frontend/app/e2e/ file, no component, no route, no wire model. browser cycle, real server (chromium) passed on the branch (1 passed (37.0s)). The baseline failure is tracked as #550,
which reproduces it on main at a2af0bf and reasons about the cause.

Found, not fixed

• Two annotate.spec.ts scenarios fail only under the local gate's ten workers #550 — unchanged; this run adds a second reproduction at d93cbfd.
• CONTRIBUTING.md documented a branch-protection call that clears required reviews. Annotated
  rather than rewritten, since the snippet's own purpose is a required status check.