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, or remote agent 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.

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.

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, or imported diff	Review and optionally apply code changes.
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. Adopters who clone the BMO source can run the focused validation lane with task test:patch-proposals.