docs(skill): load canonical review-merge prompt into workflow file

Replace summary workflow with full §0–§38 canonical PR review/merge rules.
Align review-merge-final-report schema with §37 controller handoff fields.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

skills/llm-project-workflow/SKILL.md

@@ -24,7 +24,7 @@ final-report schema; do not apply rules from other modes.
 
 | Task mode | Workflow | Final report schema |
 |-----------|----------|---------------------|
-| `review-merge-pr` | [`workflows/review-merge-pr.md`](workflows/review-merge-pr.md) | [`schemas/review-merge-final-report.md`](schemas/review-merge-final-report.md) |
+| `review-merge-pr` | [`workflows/review-merge-pr.md`](workflows/review-merge-pr.md) (canonical; §0–§38) | [`schemas/review-merge-final-report.md`](schemas/review-merge-final-report.md) |
 | `create-issue` | `workflows/create-issue.md` (planned — #333) | `schemas/create-issue-final-report.md` (planned) |
 | `work-issue` | `workflows/work-issue.md` (planned — #333) | `schemas/work-issue-final-report.md` (planned) |
 

skills/llm-project-workflow/schemas/review-merge-final-report.md

@@ -1,80 +1,56 @@
-# Review-merge final report schema
+# Review-merge controller handoff 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`.
+End every review/merge run with a section titled exactly `Controller Handoff`.
+Use this canonical field set. Do not omit fields — use `none` or
+`not verified in this session` where appropriate.
 
-Use this schema — not author or issue-filing fields (`PR number opened`,
-`Claim/comment status`, `Workspace mutations`).
-
-## Required header
+Do not use legacy fields: `Pinned reviewed head`, `Scratch worktree used`,
+`Workspace mutations`, `Mutations: None` (when mutations occurred).
 
 ```md
 ## Controller Handoff
 
-- Task: review-merge-pr
+- Task:
 - Repo:
-- Role/profile:
+- Role:
 - 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
+- Active profile:
+- Runtime context:
 - 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
+- Eligibility class:
+- Queue ordering policy:
+- Inventory pagination proof:
+- Earlier PRs skipped:
+- Candidate head SHA:
+- Reviewed head SHA:
+- Target branch:
+- Target branch SHA:
+- Already-landed gate:
+- Author-safety result:
+- Prior request-changes state:
+- Review worktree used:
+- Review worktree path:
+- Review worktree inside branches:
+- Review worktree HEAD state:
+- Review worktree dirty before validation:
+- Review worktree dirty after validation:
+- Baseline worktree used:
+- Baseline worktree path:
+- Files reviewed:
+- Validation:
+- Official validation integrity status:
+- Terminal review mutation:
 - Review decision:
-- Review mutations:
+- Merge preflight:
 - 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
+- Linked issue status:
+- Main checkout branch:
+- Main checkout dirty state:
+- Main checkout updated:
+- File edits by reviewer:
 - Worktree/index mutations:
 - Git ref mutations:
 - MCP/Gitea mutations:
@@ -83,31 +59,24 @@ Use precise categories — **not** `Workspace mutations` or bare `Mutations: Non
 - 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:
+- Current status:
 - Safe next action:
-- Safety: no self-review; no self-merge; no author mutations; no code edits
+- Safety statement:
 ```
 
-Long format (§K in SKILL.md) is required when merge occurred, validation failed,
-permissions blocked, or multiple repos were involved.
+### Already-landed handoff overrides
+
+When eligibility class is `ALREADY_LANDED_RECONCILE_REQUIRED`:
+
+- Reviewed head SHA: `none`
+- Review worktree used: `false`
+- Review worktree path: `none`
+- Review decision: `none`
+- Merge result: `none`
+
+Identity format: `username / profile` (not personal email unless required — #305).
+
+Narrative final report and controller handoff must agree on eligibility class,
+candidate/reviewed head SHA, mutation state, worktree usage, review decision,
+terminal review mutation, merge result, and linked issue status.

tests/test_llm_workflow_split.py

@@ -8,17 +8,21 @@ SKILL_DIR = REPO_ROOT / "skills" / "llm-project-workflow"
 def test_review_merge_workflow_file_exists():
     path = SKILL_DIR / "workflows" / "review-merge-pr.md"
     text = path.read_text(encoding="utf-8")
-    assert "Task mode:" in text
+    assert "canonical: true" in text
     assert "review-merge-pr" in text
-    assert "gitea-reviewer" in text
-    assert "scripts/worktree-review" in text
+    assert "## 0. Load the canonical workflow first" in text
+    assert "## 26A. Terminal review mutation hard-stop" in text
+    assert "## 37. Controller handoff schema" in text
+    assert "INVENTORY_PAGINATION_UNPROVEN" in text
+    assert "ALREADY_LANDED_RECONCILE_REQUIRED" in text
 
 
 def test_review_merge_final_report_schema_exists():
     path = SKILL_DIR / "schemas" / "review-merge-final-report.md"
     text = path.read_text(encoding="utf-8")
     assert "Controller Handoff" in text
-    assert "Worktree/index mutations" in text
+    assert "Candidate head SHA:" in text
+    assert "Terminal review mutation:" in text
     assert "Workspace mutations" in text  # documented as rejected