Skip to content

docs: require a merge-risk rating before merging a lanes PR and pilot wide fan-outs - #16609

Open
kyle-sexton wants to merge 2 commits into
mainfrom
docs/merge-risk-and-fanout-pilot-rules
Open

kyle-sexton wants to merge 2 commits into
mainfrom
docs/merge-risk-and-fanout-pilot-rules

Conversation

@kyle-sexton

Copy link
Copy Markdown
Member

No related issue: two rules the owner decided in session; no issue tracks them.

Summary

  • /source-control:pull-request merge §4.2.1 now requires a lanes App pull request to carry a merge-risk rating for the pinned head before a session merges, enqueues or arms --auto. 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 that rule.
  • multi-agent reference/config.md, "The 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.

Fix

  • plugins/source-control/skills/pull-request/reference/merge.md: one new §4.2.1 condition. It uses the names docs/conventions/pr-pipeline/README.md § The Merge-Risk line defines (Merge-Risk: line, pr-merge-risk-<pr>-<head> artifact, demote) and points there and at /review:merge-risk instead of restating them.
  • plugins/multi-agent/reference/config.md: one paragraph at the end of the fan-out guard section, the section route and defaults.yaml cite as the guard's owner.
  • AGENTS.md: one pointer sentence in "Merging". No other open PR touches AGENTS.md.
  • Changelog fragments for source-control and multi-agent.

Verification

  • scripts/validate-plugins.sh --only "source-control multi-agent": all manifests and the catalog validated.
  • scripts/check-changelog-fragments.sh --check-required origin/main: both plugins have a fragment.
  • scripts/check-as-of-recheck.sh --check, scripts/check-cost-figures.sh --check, scripts/check-purged-em-dashes.sh: pass.
  • No test reads merge.md or config.md.

Related

  • docs/conventions/pr-pipeline/README.md § The Merge-Risk line still says nothing reads the record back. This rule is a session rule, not a lane gate, so that file is left unchanged.
  • This PR edits AGENTS.md, so §4.2.1's merge without asking does not cover it.

session: AI Hero

🤖 Generated with Claude Code

https://claude.ai/code/session_01MWmASNT5Knyq99gphnV6B2

… 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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MWmASNT5Knyq99gphnV6B2
@kyle-sexton
kyle-sexton marked this pull request as ready for review November 16, 2026 19:18
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-16T19:19:52.901291Z 64f0802 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MWmASNT5Knyq99gphnV6B2
@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-refine/fix-docs
Model rung 0
Leg handoff
Run job success
Activity step success
Commits pushed none (read lane)
Run 43937976802

Failed GitHub API calls

Method Path Status
GET /repos/{repo}/git/ref/tags/* 404

@github-actions

Copy link
Copy Markdown
Contributor

claude-security-review reviewed aff117c548ce1feddb6ac476408174a01f12e896: read 7 of 7 changed file(s); 0 finding(s), 0 as inline comments.

Security review: no issues found

critical-findings: 0

I read every hunk of all 7 changed files. The pull request changes only documentation and instruction text: three changelog fragments, AGENTS.md, docs/conventions/pr-pipeline/README.md, plugins/multi-agent/reference/config.md and plugins/source-control/skills/pull-request/reference/merge.md. It changes no scripts, workflows, manifests or trust controls.

AGENTS.md and merge.md §4.2.1 (trusted path and instruction surface). Both changes add a new condition on merging. A session may not merge, enqueue or arm --auto on a lanes App pull request until that pull request carries the lanes App's Merge-Risk: line for the pinned head. With demote=true, every HIGH or CRITICAL reason needs an owner decision, and any reason without one goes to the owner.

  • Nothing is deleted, narrowed or softened; the existing conditions in "Merging" and §4.2.1 are unchanged.
  • The rule names the lanes App as the line's author, so a lookalike Merge-Risk: comment from another account does not satisfy it.
  • Unreadable or uncovered reasons go to the owner, so the rule fails closed.

docs/conventions/pr-pipeline/README.md. The wording now says that nothing in the pipeline reads the Merge-Risk record back, but a merging session does. No gate, hold or merge.report-only behaviour changes.

plugins/multi-agent/reference/config.md. The new paragraph asks for one pilot worker and a check that plan usage remains before a fan-out wider than about four workers. This affects subscription usage only, not cost: it is meant to save plan usage by catching a usage limit before a wide fan-out starts.

Other checks:

  • Untrusted text: the PR context contains no text addressed to the review lane.
  • Plugin manifests: none changed.
  • Protected-class list: the register was not consulted, because the change removes no rule.
  • Not a security issue: the PR description says the pr-pipeline README is "left unchanged", but the diff does edit it (one sentence plus a fragment). The edit has no security impact.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant