F11: Release-Admiral 'finish it' merge contract (7-step runbook)

[ArchonVII]

Summary

When a user says "looks good, finish it," the Release-Admiral has no codified contract — what gets re-checked, what gets watched, what gets logged, what gets cleaned up. The handoff is informal and easy to skip steps.

Source

• docs/phase2/gpt pro review.txt L176-209, L1347-1380
• docs/phase2/findings.md row F11 (medium)
• docs/phase2/hook-authority.md "Duplication map" row 11

Suggested approach

Codify the Release-Admiral "finish it" runbook in the org profile:

1. Re-check: rebase status, conflict check, all required checks green.
2. Watch: gh run watch until merge-required jobs complete.
3. Merge: squash or merge per repo policy.
4. Verify: git fetch origin main && git log --oneline | grep <merge-sha> to confirm.
5. Clean: git worktree remove <path>, git worktree prune, git branch -d <branch>, close active claim (transition to closed/).
6. Record: write .agent/history/YYYY-MM-DD-pr-N.md per F16.
7. Surface: report back to user only on genuine decisions/anomalies — not a step-by-step log.

Related

• F7 (role separation — only Release-Admiral may run this)
• F8 (worktree cleanup)
• F9 (claim closure)
• F16 (history record)
• F2/F10 (re-verify evidence before merge)

Acceptance

• Org profile has a "Release-Admiral runbook" section with the 7 steps.
• A skill or hook surfaces the checklist when the user says "finish it" / "ship it".
• Steps 5–6 are scriptable; reference impl shipped in .github repo or repo-template.

[ArchonVII]

Decision (2026-05-17)

RA identity — separate agent session, cold-loaded

Default for any agent-managed PR touching code, config, CI, hooks, dependencies, repo policy, AGENTS/CLAUDE/GEMINI, scripts, or agent-process files: Project-Lieutenant finishes work and stops. A fresh Release-Admiral session reviews and closes the PR cold.

Process independence ≠ different GitHub account. All merges may still happen under Joseph's identity in this solo-dev setup. What matters is that the implementation session stops and a fresh RA session loads the PR cold.

Same-session role switch is not the default — allowed only as an explicit fallback for trivial, low-risk, non-code agent PRs, or when the user authorizes.

Joseph is not the normal Release-Admiral. Joseph's role is "looks good, finish it." Owner Maintenance Lane (per F7) is fully exempt from this entire ritual.

Cold-load scope

The RA session must NOT reload the whole project, redo the plan, or relitigate the implementation. It reads only:

• the issue
• the PR body
• the PR diff
• changed file list
• CI / check status
• Lieutenant handoff
• claim / worktree state

Scripting — script-assisted, agent interprets

scripts/release-admiral/finish.sh <pr> (or equivalent) gathers:

• PR state via gh pr view
• check status via gh pr checks
• merge-commit OID
• claim records under .agent/claims/active/
• worktree list

…and runs cleanup commands (steps 4–6 below). The RA agent interprets the result, fix-forwards trivial lint/format failures, and stops on any semantic failure with a clear report.

Not fully manual (too easy to skip steps), not fully autonomous (a bug merges things you didn't intend).

Updated 7-step runbook (correction to step 4)

1. Re-check — rebase status, conflict check, all required checks green. (manual judgment)
2. Watch — gh run watch until merge-required jobs complete. (manual)
3. Merge — squash or merge per repo policy. (manual judgment)
4. Verify — replaces git log -1 --grep="<PR>" with merge-commit-OID check:

   MERGE_OID=$(gh pr view <PR> --json mergeCommit -q .mergeCommit.oid)
   git fetch origin main
   git merge-base --is-ancestor "$MERGE_OID" origin/main

   (scripted)
5. Clean — git worktree remove, git worktree prune, git branch -d, transition claim active/ → closed/. (scripted)
6. Record — see history-store decision below. (scripted)
7. Surface — RA reports back only on genuine decisions or anomalies — not a step-by-step log.

History store — do not write to main after merge

• No post-merge commit on main to add a history record. That race-prone and noisy.
• Either: write the history record before merge (committed as part of the PR itself, e.g. in .agent/history/YYYY-MM-DD-pr-N.md) — Lieutenant or RA appends it to the PR branch pre-merge, OR
• Write to a local/global history store that is gitignored (.agent/runs/*.jsonl stays local-only).

F16 already proposed the .agent/history/ location; that lives in PR-time. Local raw run ledgers stay ignored.

Implementation pieces

piece	repo	notes
Org-profile "Release-Admiral runbook" section	.github	7 steps as above, with step-4 OID check
scripts/release-admiral/finish.sh reference impl	repo-template	ships in baseline; consumed by all repos
.agent/history/ directory convention	repo-template	written pre-merge by Lieutenant or RA (pairs with F16)
.gitignore entry for .agent/runs/	repo-template	local-only run ledgers
Skill / hook surfacing "finish it" workflow	global Claude config	invokes finish.sh on RA session start

Related findings affected

• F7 Owner Maintenance Lane bypasses this whole ritual.
• F16 History records: write pre-merge in PR, not post-merge on main.
• F8 Worktree cleanup is step 5 here — F8 enforces the creation discipline.
• F9 Claim closure is step 5 here — F9 ships the active/↔closed/ directory layout.
• F2/F10 RA re-runs the evidence parser as part of step 1.

Out of scope for F11

• F19 Issue-Admiral cadence (next).
• The actual implementation of finish.sh (deferred to a follow-up issue once F7+F9+F16 land — they're its inputs).