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

Review-merge controller handoff schema

Task mode: review-merge-pr

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.

Do not use legacy fields: Pinned reviewed head, Scratch worktree used, Workspace mutations, Mutations: None (when mutations occurred).

## Controller Handoff

- Task:
- Repo:
- Role:
- Identity:
- Active profile:
- Runtime context:
- Selected PR:
- Linked issue:
- 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:
- Merge preflight:
- Merge result:
- 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:
- Review mutations:
- Merge mutations:
- Cleanup mutations:
- External-state mutations:
- Read-only diagnostics:
- Blockers:
- Current status:
- Safe next action:
- Safety statement:
- Workflow-load helper result:

The Workflow-load helper result field must carry structured output from gitea_load_review_workflow (workflow_hash, final_report_schema_hash, boundary_status). Narrative claims that workflow files were viewed locally are not sufficient (#403).

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).

Queue-status-only runs (no selected PR)

When the run inventories the queue but selects no PR for review:

• Selected PR: none
• Already-landed gate, Author-safety result, Merge preflight: not applicable or not run — never passed
• Review worktree detail fields: not applicable or none when Review worktree used is false
• Blockers must not be none if the narrative says all open PRs are conflicted, blocked, or unverified
• Inventory pagination proof must cite final-page metadata, not default page-size assumptions

Verifier: review_proofs.assess_queue_status_report().

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.

Proof-backed claims (#395)

Proof-sensitive claims must cite explicit command/tool evidence in the report or structured MCP metadata — not narrative alone:

• Inventory complete: has_more=false, is_final_page=true, inventory_complete=true, and/or total_count from gitea_list_prs.
• Skipped earlier PRs: merge-simulation command output, conflict file list, or live gitea_get_pr_review_feedback / mergeability fields.
• Baseline validation: baseline worktree path, baseline target SHA, dirty-before/after, exact command, exact result.
• Master integration: exact git merge / git rebase command and exit status.
• Cleanup: final git worktree list (or remove commands) proving session worktrees were removed.

When a claim relies on prior-session blocker state or MCP metadata only, label the proof source explicitly (command, MCP metadata, prior blocker, not checked). Do not use live proof without that classification.

The report must also carry the canonical self-propagating handoff block (schemas/self-propagating-handoff.md, #626) and that block must be posted to the Gitea PR thread. A reviewer hands off to merger; a merger transitions to merged-awaiting-controller rather than declaring the work accepted.