feat(skill): extract review-merge-pr workflow from monolithic SKILL.md

Closes #334 - Add workflows/review-merge-pr.md with reviewer-only gates and steps - Add schemas/review-merge-final-report.md with mutation ledger fields - Turn SKILL.md into task-mode router; replace inlined §F/§G with links - Point review/merge templates at extracted workflow - Add doc-contract tests for split structure Part of #333. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
2026-07-07 03:32:59 -04:00
parent e4d78a5013
commit 3976f886e4
6 changed files with 447 additions and 104 deletions
@@ -0,0 +1,113 @@
+# Review-merge final report schema
+
+**Task mode:** `review-merge-pr`
+
+Every review or merge run must end with a section titled exactly
+`Controller Handoff` validated by `review_proofs.assess_controller_handoff`.
+
+Use this schema — not author or issue-filing fields (`PR number opened`,
+`Claim/comment status`, `Workspace mutations`).
+
+## Required header
+
+```md
+## Controller Handoff
+
+- Task: review-merge-pr
+- Repo:
+- Role/profile:
+- Identity:
+- Mode: review-merge-pr
+```
+
+Identity format: `username / profile` (e.g. `sysadmin / prgs-reviewer`). Do not
+include personal email unless required for disambiguation (#305).
+
+## Selection and eligibility
+
+```md
+- Selected PR:
+- PR live state:
+- Pinned reviewed head:
+- Reviewer eligibility:
+- Repositories checked:
+- Open PR counts:
+- Inventory completeness:
+- Inventory pagination proof:
+- Selected PR or reason none selected:
+- Linked issue:
+- Linked issue live status:
+```
+
+Linked issue number must match across all sections (#314). If not verified live:
+`Linked issue status: not verified in this session`.
+
+## Validation proof (#311, #323)
+
+```md
+- Validation command:
+- Validation working directory:
+- Validation executable proof:
+- Validation result:
+- Baseline SHA: (required if full suite failed on PR head)
+- Baseline validation command/result: (required if approving despite full-suite failure)
+- Matching failure list:
+```
+
+Reject vague claims like "same as master" without baseline worktree proof.
+
+## Review and merge outcome
+
+```md
+- Review decision:
+- Review mutations:
+- Merge result:
+- Merge commit:
+- Cleanup status:
+```
+
+`Review mutations` must list exactly one live terminal review unless
+operator-approved correction is documented.
+
+## Mutation ledger (#319, #320)
+
+Use precise categories — **not** `Workspace mutations` or bare `Mutations: None`.
+
+```md
+- File edits by reviewer: none
+- Worktree/index mutations:
+- Git ref mutations:
+- MCP/Gitea mutations:
+- Review mutations:
+- Merge mutations:
+- Cleanup mutations:
+- External-state mutations:
+- Read-only diagnostics:
+```
+
+Rules:
+
+- `git fetch` → Git ref mutations
+- `git worktree add/remove` → Worktree/index mutations
+- merge simulation → Worktree/index mutations (#317)
+- MCP review/merge calls → MCP/Gitea mutations + Review/Merge mutations
+
+## Proof wording (#330)
+
+Do not claim "live proof" for blockers unless revalidated this session. Prior
+feedback at unchanged head: say `prior blocker reused` or `prior request-changes
+still applies`.
+
+Reject unsupported phrases: `inventory complete`, `same as master`, `live proof`,
+`file edits none` — unless matching evidence is present.
+
+## Blockers and safety
+
+```md
+- Blockers:
+- Safe next action:
+- Safety: no self-review; no self-merge; no author mutations; no code edits
+```
+
+Long format (§K in SKILL.md) is required when merge occurred, validation failed,
+permissions blocked, or multiple repos were involved.