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/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/.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/docs/conventions/pr-pipeline/README.md b/docs/conventions/pr-pipeline/README.md index 1382ec492ea..71cf4de423d 100644 --- a/docs/conventions/pr-pipeline/README.md +++ b/docs/conventions/pr-pipeline/README.md @@ -2546,8 +2546,10 @@ 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, + 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 (`pr= head= merge-risk= read-ms=`, plus 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..01c18737ee5 100644 --- a/plugins/source-control/skills/pull-request/reference/merge.md +++ b/plugins/source-control/skills/pull-request/reference/merge.md @@ -122,6 +122,16 @@ 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)). + 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. Run the merge script