From 64f08027ac0d65288be3b47a39777c7dc66ec81a Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:13:34 -0500 Subject: [PATCH 1/3] docs: require a merge-risk rating before merging a lanes PR and pilot wide fan-outs merge.md 4.2.1: a lanes App pull request merges, enqueues or arms --auto only at a head its Merge-Risk line rates. With demote=true the session merges only when an owner decision covers each HIGH or CRITICAL reason; any other reason goes to the owner. AGENTS.md "Merging" points at it. multi-agent config.md, fan-out guard: before a fan-out wider than about four workers, run one pilot worker and confirm plan usage remains, since a usage limit mid-fan-out stops every worker at once. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01MWmASNT5Knyq99gphnV6B2 --- .../docs-merge-risk-and-fanout-pilot-rules-7471c24c.md | 7 +++++++ .../docs-merge-risk-and-fanout-pilot-rules-6e0f12b0.md | 7 +++++++ AGENTS.md | 3 ++- plugins/multi-agent/reference/config.md | 4 ++++ .../source-control/skills/pull-request/reference/merge.md | 7 +++++++ 5 files changed, 27 insertions(+), 1 deletion(-) create mode 100644 .changes/multi-agent/docs-merge-risk-and-fanout-pilot-rules-7471c24c.md create mode 100644 .changes/source-control/docs-merge-risk-and-fanout-pilot-rules-6e0f12b0.md diff --git a/.changes/multi-agent/docs-merge-risk-and-fanout-pilot-rules-7471c24c.md b/.changes/multi-agent/docs-merge-risk-and-fanout-pilot-rules-7471c24c.md new file mode 100644 index 00000000000..be1ba067b6e --- /dev/null +++ b/.changes/multi-agent/docs-merge-risk-and-fanout-pilot-rules-7471c24c.md @@ -0,0 +1,7 @@ +--- +bump: minor +--- + +### Added + +- The fan-out guard section now asks for one pilot worker and a check that plan usage remains before a fan-out wider than about four workers, since a usage limit reached mid-fan-out stops every worker at once. diff --git a/.changes/source-control/docs-merge-risk-and-fanout-pilot-rules-6e0f12b0.md b/.changes/source-control/docs-merge-risk-and-fanout-pilot-rules-6e0f12b0.md new file mode 100644 index 00000000000..21071e157ac --- /dev/null +++ b/.changes/source-control/docs-merge-risk-and-fanout-pilot-rules-6e0f12b0.md @@ -0,0 +1,7 @@ +--- +bump: minor +--- + +### Added + +- Merging after AI review now requires a lanes App pull request to carry a merge-risk rating for the pinned head. With `demote=true`, the session merges only when an owner decision covers each HIGH or CRITICAL reason, and sends any other reason to the owner. diff --git a/AGENTS.md b/AGENTS.md index 0d9419b5000..2e6703269e3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -87,7 +87,8 @@ Merging is a judgment, not a fixed stop: merge when the user or the task wants t the body, or a human comment asking to wait). A body hold or wait comment stops the merge until the owner lifts it; the owner deciding the PR in their own words, in a session or on the PR, lifts it. Ask first when any of those is missing, or when the change alters what agents may do unattended and -the owner has not decided that change. +the owner has not decided that change. A lanes App pull request also needs its merge-risk rating on +the current head: `plugins/source-control/skills/pull-request/reference/merge.md` §4.2.1. ### Review advisories while issue filing is paused diff --git a/plugins/multi-agent/reference/config.md b/plugins/multi-agent/reference/config.md index af248659d5f..43175fe79a0 100644 --- a/plugins/multi-agent/reference/config.md +++ b/plugins/multi-agent/reference/config.md @@ -140,6 +140,10 @@ Setting `fanout.frontier_guard: false` is an explicit opt-in to frontier fan-outs. Set it on the layer whose scope you mean: the personal override for one checkout, the user-global file for every repository on one machine. +Before a fan-out wider than about four workers, run one worker as a pilot and +confirm plan usage remains for the rest: a usage limit reached mid-fan-out +stops every worker at once. + ## Example team file This `docs/conventions/multi-agent.yaml` raises the worker's effort and diff --git a/plugins/source-control/skills/pull-request/reference/merge.md b/plugins/source-control/skills/pull-request/reference/merge.md index 42129f603a0..949c905a546 100644 --- a/plugins/source-control/skills/pull-request/reference/merge.md +++ b/plugins/source-control/skills/pull-request/reference/merge.md @@ -122,6 +122,13 @@ for the user. so the unresolved-thread gate below covers it. Marking the PR ready is what starts those reviews, so this never happens at `ready`. - All 4.1 readiness gates pass and no review thread is unresolved. +- A lanes App pull request has a merge-risk rating for the head you pin: the lanes App's + `Merge-Risk:` line naming that head, with its reasons in the `pr-merge-risk--` artifact + ([`docs/conventions/pr-pipeline/README.md` § The Merge-Risk line](https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/conventions/pr-pipeline/README.md#the-merge-risk-line)). + Never merge, enqueue or arm `--auto` without it: an `unrated` line, no line, or a rating of an + earlier head holds. With `demote=true` (`max` HIGH or CRITICAL; `/review:merge-risk` § What + `demote` may do), read the HIGH and CRITICAL rows' `why` and merge only when an owner decision + covers each one. A reason no owner decision covers, or one you cannot read, goes to the owner. - The session can reach GraphQL and the PR is not a stack layer; otherwise wait for the user. Run the merge script From aff117c548ce1feddb6ac476408174a01f12e896 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:22:39 -0500 Subject: [PATCH 2/3] docs(pr-pipeline): say a merging session reads the merge-risk record The Merge-Risk section said nothing reads the record back. That holds for the pipeline, and no longer for a session: the pull-request merge reference now has a session read the rating before it merges a lanes App pull request. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_01MWmASNT5Knyq99gphnV6B2 --- .../docs-merge-risk-and-fanout-pilot-rules-808b97f1.md | 8 ++++++++ docs/conventions/pr-pipeline/README.md | 5 +++-- 2 files changed, 11 insertions(+), 2 deletions(-) create mode 100644 .changes/pr-pipeline/docs-merge-risk-and-fanout-pilot-rules-808b97f1.md diff --git a/.changes/pr-pipeline/docs-merge-risk-and-fanout-pilot-rules-808b97f1.md b/.changes/pr-pipeline/docs-merge-risk-and-fanout-pilot-rules-808b97f1.md new file mode 100644 index 00000000000..7857010fdbc --- /dev/null +++ b/.changes/pr-pipeline/docs-merge-risk-and-fanout-pilot-rules-808b97f1.md @@ -0,0 +1,8 @@ +--- +bump: patch +--- + +### Changed + +- The Merge-Risk section says the pipeline reads no record back, and that a session merging a lanes + App pull request does, per the pull-request merge reference §4.2.1. diff --git a/docs/conventions/pr-pipeline/README.md b/docs/conventions/pr-pipeline/README.md index 1382ec492ea..e80869e4255 100644 --- a/docs/conventions/pr-pipeline/README.md +++ b/docs/conventions/pr-pipeline/README.md @@ -2546,8 +2546,9 @@ failure signals. one comment unless anyone other than the lanes App edited its record; there is no write when the head's record already holds the line or a rating. Its `issue_comment` event starts `intake-label-outside-actor-activity` and `intake-reenter` runs whose jobs skip a bot's comment, as they do - for the pin. Nothing reads the record back: no gate, hold or rung. Not while - `merge.report-only` is true. + for the pin. Nothing in the pipeline reads the record back: no gate, hold or rung. Not while + `merge.report-only` is true. A session that merges a lanes App pull request does read it + (`plugins/source-control/skills/pull-request/reference/merge.md` §4.2.1). - **Telemetry.** The rating run writes one `pr-merge-risk` lane-outcome record (outcome, class, `durationMs`, `costUsd`, models), and each arm logs a `merge-risk` notice (`pr= head= merge-risk= read-ms=`, plus From 90fe979089beb3fab99b0c599e9fe34a54992f95 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:35:17 -0500 Subject: [PATCH 3/3] docs(source-control): accept the rating artifact when a lanes PR was never armed The lanes App writes the Merge-Risk line only when it arms auto-merge, so requiring the line held every lanes PR the pipeline had not armed. The rating artifact for the pinned head now counts as the rating there. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_01MWmASNT5Knyq99gphnV6B2 --- docs/conventions/pr-pipeline/README.md | 3 ++- .../source-control/skills/pull-request/reference/merge.md | 7 +++++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/conventions/pr-pipeline/README.md b/docs/conventions/pr-pipeline/README.md index e80869e4255..71cf4de423d 100644 --- a/docs/conventions/pr-pipeline/README.md +++ b/docs/conventions/pr-pipeline/README.md @@ -2547,7 +2547,8 @@ failure signals. holds the line or a rating. Its `issue_comment` event starts `intake-label-outside-actor-activity` and `intake-reenter` runs whose jobs skip a bot's comment, as they do for the pin. Nothing in the pipeline reads the record back: no gate, hold or rung. Not while - `merge.report-only` is true. A session that merges a lanes App pull request does read it + `merge.report-only` is true. A session that merges a lanes App pull request does read it, + or the rating artifact for that head when the pull request was never armed (`plugins/source-control/skills/pull-request/reference/merge.md` §4.2.1). - **Telemetry.** The rating run writes one `pr-merge-risk` lane-outcome record (outcome, class, `durationMs`, `costUsd`, models), and each arm logs a `merge-risk` notice diff --git a/plugins/source-control/skills/pull-request/reference/merge.md b/plugins/source-control/skills/pull-request/reference/merge.md index 949c905a546..01c18737ee5 100644 --- a/plugins/source-control/skills/pull-request/reference/merge.md +++ b/plugins/source-control/skills/pull-request/reference/merge.md @@ -125,8 +125,11 @@ for the user. - A lanes App pull request has a merge-risk rating for the head you pin: the lanes App's `Merge-Risk:` line naming that head, with its reasons in the `pr-merge-risk--` artifact ([`docs/conventions/pr-pipeline/README.md` § The Merge-Risk line](https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/conventions/pr-pipeline/README.md#the-merge-risk-line)). - Never merge, enqueue or arm `--auto` without it: an `unrated` line, no line, or a rating of an - earlier head holds. With `demote=true` (`max` HIGH or CRITICAL; `/review:merge-risk` § What + The App writes the line only when it arms auto-merge, so on a pull request it has not armed the + rating is that artifact itself, from a `pr-rate-merge-risk.yml` run on the default branch, named + for the pull request and the head you pin. + Never merge, enqueue or arm `--auto` without a rating: an `unrated` line, neither a line nor an + artifact, or a rating of an earlier head holds. With `demote=true` (`max` HIGH or CRITICAL; `/review:merge-risk` § What `demote` may do), read the HIGH and CRITICAL rows' `why` and merge only when an owner decision covers each one. A reason no owner decision covers, or one you cannot read, goes to the owner. - The session can reach GraphQL and the PR is not a stack layer; otherwise wait for the user.