Ready Merge

Key Ideas

• Reviewable Change: ready-merge means work produced a change that can be inspected.
• Evidence Handoff: diffs, logs, quality output, and agent notes should travel with the Gap.
• Not Done Yet: ready-merge is a handoff state, not completion.

Purpose

Ready-merge exists because implementation and integration are different responsibilities. Agents may produce changes, but Refine needs a state where those changes can be reviewed, checked, and prepared for merge.

Expected Role

Ready-merge should connect the Gap to its Git branch or worktree, changed files, quality evidence, logs, and review context. It should make the next action obvious: inspect, build, QA, review, merge, request more work, or fail.

This state is especially important for standalone and agent-generated work because it preserves handoff without losing the isolated change context.

What Happens

When a Gap is ready-merge:

• Refine has a reviewable change, usually in a branch or worktree.
• The Gap should point to changed files, commits or diff context, agent output, logs, and source evidence.
• The system prepares the work for build, QA, review, merge, or a new round.
• Users and agents can inspect the change without losing the Gap's original intent.
• If the handoff is incomplete, conflicted, or unsafe, the Gap should move to failed or request more work rather than pretending it is complete.

Future Direction

Future ready-merge behavior should support generated merge summaries, conflict prediction, dependency-aware ordering, staged integration, and agent-assisted review preparation.