Patch Proposals

Patch Proposals are durable records for agent-produced code changes. They let BMO capture a proposed change, keep its provenance and review artifacts, run bounded review policy, and separate approval from actually mutating the workspace.

Maturity: Advanced operator and maintainer surface. Use it when BMO is collecting or reviewing proposed code changes from retained worktrees, arena candidates, mesh/A2A materialization, or imported diffs. It is not the normal first-run edit path.

What problem this solves

Agent-produced changes can arrive from several places: a local retained worktree, a verified arena candidate, mesh/A2A materialization, or a diff-only import. A chat summary is not enough to decide whether that change should land.

Patch Proposals give each candidate a durable record with changed paths, validation metadata, diff artifacts, lifecycle events, and review decisions. That lets an operator inspect, accept, reject, send back, materialize, apply, or merge selected paths without treating every producer as equally trusted.

Use it when

a worker, mesh agent, arena candidate, remote agent, or change synthesis run produced code that should be reviewed before it mutates the main workspace
you need a queue of reviewable code changes scoped to a workstream
a proposal needs Quality Gate or policy evidence before human review
a diff-only result needs explicit local materialization before apply
you want audit history for accept, reject, send-back, apply, conflict, or selected-path merge actions

Do not use it when

you are making ordinary local edits in the active checkout
a proposal only describes a learning or prompt asset from Shadow Evals
the change has no readable diff artifact or materialized source
live lifecycle actions are not allowed by the workstream policy

Lifecycle

Patch Proposal status is review and mutation state, not a single yes/no flag:

Status	Meaning
`draft` / `submitted`	A producer has created or submitted the proposal.
`judging`	BMO is evaluating bounded review evidence.
`send_back`	The proposal needs revision before review can continue.
`ready_for_human`	The proposal can be inspected by an operator.
`accepted`	The proposal is approved, but not yet applied.
`applying` / `applied`	BMO is mutating, or has mutated, the workspace.
`rejected` / `superseded` / `conflicted`	The proposal is not currently landing as-is.

accepted means approval. applied means mutation succeeded. Quality Judge and proposal-review policy can move a proposal toward review readiness, but they do not merge code.

Review and apply

Workstream proposal commands expose the operator path:

bmo workstream proposals review <proposal-id>
bmo workstream proposals review <proposal-id> --json
bmo workstream proposals decisions <proposal-id>

Review can run in shadow mode or live mode depending on policy. Shadow mode records the action BMO would take, blockers, confidence, policy snapshot, and evidence snapshot without changing proposal state or workspace files.

List and detail surfaces also expose one shared status view: queue state, counts, degraded causes, next actions, and the latest actionable proposal for the current scope. Single-proposal reads include the same degraded and next-action summary so operators and agents do not have to infer queue health from raw lifecycle rows.

Live actions remain app-service gated. Apply and selected-path merge are separate from accept, so approval can be audited before mutation. When a proposal records a base commit, direct apply requires a readable workspace HEAD matching that base. An already-stale proposal remains accepted and leaves workspace files unchanged. Review it against the current workspace and collect an updated candidate before direct apply. Selected-path merge retains its separate composition and conflict checks.

Quality Gates

Patch Proposals can use Quality Gates as a review readiness signal. The judge sees bounded evidence: provenance, changed paths, diff artifact metadata, validation output, selected run events, risk notes, and optional workstream context.

Quality decisions are advisory or review-state transitions. A pass, warn, or unavailable judge keeps the proposal reviewable. send_back requests revision. escalate preserves review readiness unless conflict evidence marks the proposal conflicted.

When options.proposal_review.require_validation_summary is enabled, automated accept/apply policy for a materialized proposal requires both a nonempty validation summary and validation status passed. Collection, a descriptive summary, or an advisory judge verdict alone does not satisfy that requirement. Pending, resource-deferred, failed, skipped, incomplete, and unknown validation remain inspectable but block automated accept/apply. Diff-only materialization remains available so the candidate can be prepared for validation; explicit operator lifecycle actions and explicit policy relaxation remain separate.

The status gate is a necessary readiness check, not independent proof that every required command passed on the final revision. Retain the actual commands, results, and candidate identity with the proposal’s validation evidence. Independent verification names the records that remain after a proposal is accepted or applied. Mutation aftercare is the contract ingest that follows a successful apply. A returned aftercare failure marks the proposal conflicted even when the workspace effect completed. That conflict stays an operator review decision. The recovery pass reconciles the contract reservation and does not clear the conflict by itself.

Patch proposals vs shadow eval proposals

BMO has two proposal families:

Proposal kind	Source	Purpose
Patch Proposal	Agent-produced code change, worktree, arena candidate, A2A materialization, imported diff, or `bmo synthesize` selection	Review and optionally apply code changes. A synthesis selection stays `ready_for_human` until you accept it.
Shadow Eval proposal	Comparable replay scorecards from Shadow Evals	Decide whether to promote a learned recipe, operating pack, or change contract reference.

Both are append-only review artifacts. They do not share lifecycle authority: Patch Proposals own code-change review and apply state, while Shadow Eval proposals own learning/promotion decisions.

Implementation reference

The implementation reference covers the store, source kinds, artifacts, events, HTTP/API surfaces, and materialization. Source checkout maintainers should use that implementation reference for validation details.