docs: clarify Ally review gate routing

[kkroo]

Thinking Path

The on-prem review-gate runbook told operators to collect two approvals but blurred which identity satisfies which control. review/ally-complete and the singleton Blockcast/onprem-k8s-ally-reviewer team rule are separate gates satisfied by separate identities, and the old wording could be read as either one standing in for the other. A reader who took the User-seat approval as satisfying the App gate would end up one independent exact-head attestation short, and discover it only at merge time.

The second gap was the self-review case. The old text said a required reviewer "cannot supply its own required review" without stating plainly that a Paperclip agent normally authors as allyblockcast[bot], so in practice most agent PRs need an independent-author replacement before the App can approve.

What Changed

Wording only, in docs/runbooks/onprem-k8s-agent-pr-review-gate.md. Names the App approval as the only evidence review/ally-complete accepts, states the App-authored replacement path explicitly rather than by implication, and folds the two "do not treat X as Y" cautions into one sentence covering both substitutions.

Verification

Rebased onto current master and confirmed it still applies cleanly: zero commits behind, git merge-tree --write-tree returns 0 (clean), one commit ahead.

Scope-checked against the repo's own gate definitions rather than assumed: docs: is in SKIP_PREFIXES / SKIP_ISSUE_PREFIXES / SKIP_TEST_PREFIXES, so the dedup, linked-issue and test-coverage gates do not apply here; check-pr-template.mjs has no skip list, so this description was written against its REQUIRED_SECTIONS and validated by running that checker directly.

Risks

Documentation only — no code path, no runtime behaviour, nothing to roll back beyond the text.

The real risk is the text being wrong rather than the change being unsafe. I inherited this PR after a rebase and did not re-derive its claims from the current implementation; I confirmed the diff still applies and reads coherently, not that review/ally-complete still accepts exactly what the runbook says it accepts. Anyone relying on this operationally should confirm the gate's behaviour against server/src/ before following it, and a reviewer who knows that gate should treat the two-identity claim as the thing to check.

Model Used

claude-opus-5[1m]

[allyblockcast]

Hey @kkroo! Before this PR can be reviewed, a few things need attention:

Missing or incomplete:

• No linked issue or inline issue description found — either tag an existing issue with Fixes #NNN / Closes #NNN / Refs #NNN, or describe the underlying issue inline in the PR body following one of our issue templates (https://github.com/paperclipai/paperclip/tree/master/.github/ISSUE_TEMPLATE). See CONTRIBUTING.md → "Link Issues or Describe Them In-PR".
• No test files detected in this PR — please include a test that verifies the bug fix or new behavior. If this PR genuinely doesn't need a test (e.g. a refactor), please retitle with refactor: prefix.

Once updated, push a new commit and these checks will re-run automatically.

— commitperclip

[allyblockcast]

Ally — Consolidated PR Review

Lenses: pr-review-toolkit (code, tests, comments, errors, types) + gstack/review + native-codex.
Reviewed head: 422964a

Critical Issues (0)

Important Issues (1)

• [native-codex] docs/runbooks/onprem-k8s-agent-pr-review-gate.md:32-40 — The revised runbook incorrectly says review/ally-complete accepts only an exact-head App approval and that an App-authored PR must be reopened under an independent author. The current Paperclip gate implementation explicitly supports Ally's App-authored COMMENTED formal reviews and comment-shaped reviews, and the App is intentionally the author-only identity in this workflow; the separate onprem ruleset is the Team approval requirement. Following this text would cause operators to replace valid App-authored PRs and seek an approval the App cannot provide.
  • Describe the App artifact as the gate's accepted Ally review evidence (including COMMENTED self-review where applicable), and describe the Team approval as the independent merge requirement. Verify the runbook against the live gate before publishing.

Suggestions (0)

Strengths

• The change correctly distinguishes the App identity from the User seat and keeps the Team approval as a separate requirement.
• The exact-head language is explicit and useful for operators.

Recommended Action

1. Address Important issues before merge.
2. Consider Suggestions opportunistically.