Require and validate Controller Handoff sections in workflow final reports

- Upgrade SKILL.md §K compact format to the issue #182 canonical field set
  (Task/Repo/Role/Identity/Issue-PR/Branch-SHA/Files/Validation/Mutations/
  Current status/Blockers/Next/Safety) plus role-specific field lists for
  review/merge, author, and queue/inventory tasks.
- Point the review-pr, merge-pr, and start-issue template handoff lines at
  the exactly-titled Controller Handoff section with their role fields.
- Add review_proofs.assess_controller_handoff(): reports without the exact
  section are 'missing' (downgraded), present-but-partial are 'incomplete'
  with the absent fields listed, and role extras are enforced per role.
- Add TestControllerHandoff (8 tests) including a SKILL.md doc-contract
  test so the documented requirement cannot silently rot.

The handoff supplements the full report; full-report validation rules are
unchanged.

Closes #182

Co-Authored-By: Claude Fable 5 <[email protected]>

skills/llm-project-workflow/SKILL.md

@@ -296,22 +296,43 @@ current state immediately, without rereading the conversation.
 readability, not as a full human status report. PR bodies still carry the
 full review detail — the handoff never replaces PR documentation.
 
-Compact format (default):
+Compact format (default, canonical field set per issue #182):
 
 ```md
 ## Controller Handoff
 
 - Task:
-- Repo/state:
-- Issues/PRs:
-- Changed:
+- Repo:
+- Role:
+- Identity:
+- Issue/PR:
+- Branch/SHA:
+- Files changed:
 - Validation:
+- Mutations:
+- Current status:
 - Blockers:
-- Review:
 - Next:
 - Safety:
 ```
 
+Role-specific fields (append to the compact block):
+
+- review/merge tasks: `Selected PR:`, `Reviewer eligibility:`,
+  `Pinned reviewed head:`, `Review decision:`, `Merge result:`,
+  `Linked issue status:`, `Cleanup status:`
+- author tasks: `Selected issue:`, `Claim/comment status:`,
+  `PR number opened:`, `No review/merge:` (explicit confirmation)
+- queue/inventory tasks: `Repositories checked:`, `Open PR counts:`,
+  `Selected PR or reason none selected:`, `Inventory completeness:`
+
+The section title must be exactly `Controller Handoff`.
+`review_proofs.assess_controller_handoff()` validates this section; reports
+missing it (or missing required fields) are downgraded. The handoff never
+replaces the full report — it is the compact continuation summary at the end,
+and the full report must still carry exact validation results and mutation
+confirmation.
+
 The `Safety:` line is never omitted; it is usually:
 
 ```text

skills/llm-project-workflow/templates/merge-pr.md

@@ -35,5 +35,11 @@ Then run the cleanup template (worktree-cleanup.md):
 - delete remote branch, remove local branch + worktree folder
 - fetch/prune; confirm main checkout is clean and current (0 0).
 
-Handoff: reviewer identity, merge result + commit, cleanup done, issue closed, PR metadata state/merged flag/hash, remote master hash, post-merge verification method used & verification results.
+Handoff: end with a section titled exactly `Controller Handoff` per SKILL.md
+§K (long form — a merge is always high-risk), including the review/merge role
+fields (Selected PR, Reviewer eligibility, Pinned reviewed head, Review
+decision, Merge result, Linked issue status, Cleanup status) plus: merge
+commit, PR metadata state/merged flag/hash, remote master hash, and the
+post-merge verification method used & verification results. Reports missing
+the handoff are downgraded (review_proofs.assess_controller_handoff).
 ```

skills/llm-project-workflow/templates/review-pr.md

@@ -65,7 +65,10 @@ Steps:
    - MCP-Profile: <profile name>
    - Eligibility: passed/failed
 
-Handoff: reviewer identity, PR author, scope verdict, checks + results, decision —
-formatted per SKILL.md §K (compact by default; long form if a merge happened
-or a gate blocked you); if you could not merge, name the exact gate.
+Handoff: end with a section titled exactly `Controller Handoff` per SKILL.md
+§K (compact by default; long form if a merge happened or a gate blocked you),
+including the review/merge role fields: Selected PR, Reviewer eligibility,
+Pinned reviewed head, Review decision, Merge result, Linked issue status,
+Cleanup status. If you could not merge, name the exact gate. Reports missing
+the handoff are downgraded (review_proofs.assess_controller_handoff).
 ```

skills/llm-project-workflow/templates/start-issue.md

@@ -42,7 +42,10 @@ Steps:
    - Self-review allowed: no
 9. Stop before review/merge — you are the author.
 
-Handoff: issue #, branch, worktree path, files changed, checks + results, PR URL —
-formatted as the compact Controller Handoff (SKILL.md §K; long form only on
-the high-risk triggers); Review line: "Review needed — PR is open".
+Handoff: end with a section titled exactly `Controller Handoff` per SKILL.md
+§K (compact; long form only on the high-risk triggers), including the author
+role fields: Selected issue, Claim/comment status, PR number opened, and an
+explicit "No review/merge:" confirmation — plus branch, worktree path, files
+changed, checks + results. Next line: "Review needed — PR is open". Reports
+missing the handoff are downgraded (review_proofs.assess_controller_handoff).
 ```