Merge and release

Merge and Release

Reference document for merge and release policy. The executable bash lives in plugins/flow/commands/merge.md and plugins/flow/commands/release.md. This skill describes what those commands enforce and why.

Both merge and release are Tier 3 — they always require explicit human confirmation, even in autonomous mode. This is non-negotiable.

Iron Law

MERGE IS IRREVERSIBLE IN PRACTICE. Treat every merge as permanent. Every prerequisite must be verified with fresh evidence, not memory.

Reverting a merge is technically possible in git but disruptive in practice — downstream branches rebase off the merge, deploys propagate it, and history grows confusing. Prevention is the only reliable strategy. The Tier 3 confirmation requirement is the structural expression of that fact.

Merge Prerequisites — The Five-Check Gate

Before a merge proceeds, all five checks must pass. The runnable verification is in plugins/flow/commands/merge.md Phase 1.

#	Check	Requirement	What it protects against
1	Approval	At least one approval, no outstanding requested changes	Merging code that no human has signed off on
2	CI Checks	All status checks pass (statusCheckRollup all success)	Merging code that fails the project's automated tests
3	Mergeable	No merge conflicts (mergeable == "MERGEABLE")	Merging a PR whose content cannot cleanly land on the base branch
4	Conversations	All review threads resolved (unresolved count == 0)	Closing reviewer concerns by ignoring them
5	Stale approval	No commits after the last approval timestamp	Merging code that was approved before the latest changes existed

The conversation-resolution check requires GitHub's GraphQL API (the REST reviewThreads field is incomplete). The exact GraphQL query used is in plugins/flow/commands/merge.md.

Stop Conditions — Non-Negotiable

When any of these conditions is detected, the command stops without asking "merge anyway?":

• ANY of the five prerequisites fails
• Stale approval detected — request re-review, do not merge
• Unresolved conversations > 0 — resolve first, do not merge
• Finding-ledger check fails (see pr-lifecycle skill for details)

There is no "override the gate" option in autonomous mode. Overrides require the human user to take the action themselves outside the command.

Stale Approval Detection

A "stale" approval is one that predates the most recent commit on the PR. The check compares:

• The latest submittedAt timestamp among reviews where state == "APPROVED"
• The committedDate of the most recent commit on the PR

If commits exist after the last approval, the command warns: "Approval may be stale." Stale approvals are a stop condition because the approver has not actually seen what is being merged.

Merge Execution

After all prerequisites pass, the command displays a Merge Assessment table and explicitly asks the user to confirm. Only after a clear "yes" does the merge proceed:

• Strategy is read from settings (squash | merge | rebase, default squash)
• Branch deletion is read from settings (default true)
• The gh pr merge invocation is in plugins/flow/commands/merge.md Phase 3

The user-visible assessment lists every prerequisite's status, the chosen strategy, and the branch-delete decision so the human can verify before approving.

Release Process

Releases follow the same Tier 3 confirmation discipline as merges. The runnable bash is in plugins/flow/commands/release.md.

Version Calculation

Bump type	Format	When to use
patch	0.0.X+1	Bug fixes only, no behavior change
minor	0.X+1.0	New features, no breaking changes
major	X+1.0.0	Breaking changes

The first release defaults to v1.0.0 if no prior tag exists.

Changelog Generation

The changelog is built from merged PRs since the last release tag, categorized by conventional commit prefix:

• Features — feat: PRs
• Bug Fixes — fix: PRs
• Other Changes — docs:, chore:, etc.

Each entry includes the PR number and author. A "Full Changelog" link compares the previous tag to the new one.

Release Execution

After the changelog and version are displayed, the command asks the user to confirm. Only after explicit confirmation:

1. Create annotated tag: git tag -a "$TAG" -m "Release $TAG"
2. Push tag: git push origin "$TAG"
3. Create GitHub release: gh release create "$TAG" --title "$TAG" --notes "$CHANGELOG"

These three operations together are the release. They are not split across multiple agent turns — the user confirms once and the command performs them in sequence.

Post-Merge / Post-Release

After either operation completes, the command verifies state:

• Merge: gh pr view $PR_NUM --json state should return MERGED
• Release: gh release view $TAG should succeed

The command then suggests cleanup: switch to the default branch, pull latest, and (for releases) update plugin version files if applicable.

Why Tier 3 Is Structural, Not Optional

Merges and releases produce visible, durable artifacts: a merge commit on main, a published tag, a GitHub release page that subscribers may receive notifications for. The cost of an unwanted merge or release is paid by everyone downstream — other developers rebasing, users seeing a notification for a release that was a mistake, package managers fetching the new version.

Tier 3 is not gatekeeping for its own sake. It is the structural expression of: the cost of an unwanted action is borne by people who are not in this conversation. The human in the loop is the only person who can speak for those downstream people.

Where the Bash Lives

This skill is reference-only. The runnable implementations are:

• Merge prerequisites + execution: plugins/flow/commands/merge.md
• Release version calculation + tagging + GitHub release creation: plugins/flow/commands/release.md

When the policy needs to evolve — a new prerequisite, a new release strategy, a different versioning scheme — update the command and update this reference together. The bash is the runtime; this document is the rationale.