fix(agents): require PR readiness before review

[allyblockcast]

Thinking Path

• Paperclip is the open source control plane used to manage AI agents and their work.
• Its shipped GitHub workflow skill and default managed instructions define how agents prepare, review, and hand off pull requests.
• Agents can currently reach the reviewer-request step with an incomplete repository template or without proving that related pull requests were searched.
• That causes the commitperclip quality gate to reject the PR after a review cycle has already been spent, especially when Ally is asked to review too early.
• This pull request makes the template, duplicate-search checkbox, and commitperclip readiness gate explicit in both the reusable skill and the default managed instructions, with regression coverage.
• The benefit is that agents wait for a review-ready PR before requesting Ally or human attention, reducing avoidable review churn.

Linked Issues or Issue Description

No existing GitHub issue matched this focused instruction and regression-test change. Related implementation and operational context was reviewed in #1325, #1436, #1471, and #1141; none duplicates this change.

What happened

Agents can ask Ally or a human to review before the repository PR template is complete and before the commitperclip quality gate has passed.

Expected behavior

Agents should complete the repository template, search for duplicate or related PRs, check the dedup affirmation, and wait for commitperclip and related quality gates before requesting review.

Steps to reproduce

1. Give an agent a code change in a Paperclip repository with .github/PULL_REQUEST_TEMPLATE.md and commitperclip enabled.
2. Ask the agent to open a PR or request review without completing the template or dedup checkbox.
3. Observe that the review request can be made before the pre-review gate has passed, and the gate later reports missing PR metadata.

Paperclip version or commit

c28f893f270665d16fb9c9f2a7a17878bec85bdd (Blockcast/master)

Deployment mode

Self-hosted server with managed agent instruction bundles; change verified from source.

What Changed

• Require the repository PR template headings, issue-link or in-PR issue-description path, and exact dedup-search affirmation in the reusable GitHub PR workflow skill.
• Add an explicit commitperclip pre-review gate section telling agents to wait for quality gates before requesting Ally or human review.
• Add the same readiness rule to the default managed AGENTS.md bundle so newly materialized agents receive it.
• Add catalog and managed-bundle regression assertions, and refresh the generated skills catalog manifest.

Verification

• pnpm --filter @paperclipai/skills-catalog validate
• pnpm --filter @paperclipai/skills-catalog test -- --run packages/skills-catalog/src/shipped-catalog.test.ts (36 tests passed)
• pnpm exec vitest run server/src/__tests__/agent-skills-routes.test.ts (20 tests passed)
• git diff --check origin/master...HEAD
• Searched the GitHub pull-request list for duplicate and related work before opening this PR; the related links are listed above.

Risks

Low risk. This changes agent guidance and regression assertions only; it does not alter runtime API behavior, persistence, or deployment configuration. Reverting the commit restores the prior guidance and catalog manifest.

Model Used

OpenAI Codex powered by GPT-5, tool-enabled coding agent with repository, shell, GitHub API, and Kubernetes inspection capabilities.

Checklist

• I have included a thinking path that traces from project context to this change
• I have specified the model used (with version and capability details)
• I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work
• I have searched GitHub for duplicate or related PRs and linked them above
• I have either (a) linked existing issues with Fixes: # / Closes: # / Refs: # OR (b) described the issue in-PR following the relevant issue template
• I have run tests locally and they pass
• I have added or updated tests where applicable
• If this change affects the UI, I have included before/after screenshots
• I have updated relevant documentation to reflect my changes
• I have considered and documented any risks above
• All Paperclip CI gates are green
• Greptile is 5/5 with no open P2s, recommendations, or follow-ups
• I will address all Greptile and reviewer comments before requesting merge

[allyblockcast]

Ally — Consolidated PR Review

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

Critical Issues (0)

Important Issues (0)

Suggestions (0)

Strengths

• The guidance is placed in the reusable GitHub PR workflow skill and mirrored in the default managed AGENTS.md bundle.
• The exact template headings, duplicate-search affirmation, and commitperclip PR Review gate are covered by focused catalog and managed-bundle regression assertions.
• The generated catalog metadata is updated consistently with the skill content hash.

Recommended Action

1. No Critical or Important issues found; merge when the pending CI checks complete successfully.
2. Consider Suggestions opportunistically.