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.