Explain in CONTRIBUTING how outside reports and PRs land (GST-2723) (#4374)

* Explain in CONTRIBUTING how outside reports and PRs land (GST-2723)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Fix contributor-docs wording found in review

Review-Finding: p1/specialist-batched#1 reader=security
Review-Finding: p1/specialist-batched#2 reader=red-team
Review-Finding: p1/adversarial-native#5 reader=adversarial-native
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Say in the review policy that docs-only outside PRs are not rewritten

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

---------

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
Garry Tanandcapy-ai[bot] authored and GitHub committed 2026-11-15 02:06:53 +00:00
1 parent 3805969159
commit caa7140eee
9 files changed
+102 -47

No files matched your search

+70 -30
View File
@@ -922,44 +922,79 @@ triaging for the maintainer posts these comments under its bot identity
`gh` runs as the maintainer. The full rule,
including the labels and the close reasons, is in [docs/triage.md](docs/triage.md).
## Community PR triage (wave process)
## Sending a report or a PR
When community PRs accumulate, batch them into themed waves:
gstack is maintained day to day by AI agents working for Garry Tan. They triage issues
and PRs, rebuild good patches on current main, and land them with the author credited.
That's why nearly every commit on main reads as Garry's: the agents commit under his
account, and your credit is a `Co-authored-by:` trailer plus a line in the PR body.
1. **Categorize** — group by theme (security, features, infra, docs)
2. **Deduplicate** — if two PRs fix the same thing, pick the one that
changes fewer lines. Close the other with a note pointing to the winner.
3. **Collector branch** — create `pr-wave-N`, merge clean PRs, resolve
conflicts for dirty ones, verify with `bun run test && bun run build`
4. **Close with context** — every closed PR gets a comment explaining
why and what (if anything) supersedes it. Contributors did real work;
respect that with clear communication. An agent running the wave posts
these notes under its bot identity, never the maintainer's own account.
5. **Ship as one PR** — single PR to main with all attributions preserved
in merge commits. Include a summary table of what merged and what closed.
**What happens to your PR.** Outside code is treated as untrusted: an agent reads your
diff as text and never checks it out, runs it or builds it. Then one of three things
happens.
See [PR #205](../../pull/205) (v0.8.3) for the first wave as an example.
- **Docs for people only** (for example the README) can be merged as
they are, after an agent checks every link, command and install step in them against
main.
- **A small fix** that is plainly correct, about 40 lines or fewer not counting its
tests, is taken even when the gain is small. An agent rebuilds it on current main
with you as co-author. We land at most one of these a day.
- **Everything else**, including anything that runs and any Markdown agents load
(`SKILL.md` files and their templates, `AGENTS.md`, `CLAUDE.md`, prompts), is
rebuilt on main with credit when it passes the test below, and closed with a short
note saying why when it doesn't.
When your change is rebuilt, the agent comments on your PR with a link to what landed
and closes your PR, so a taken PR usually shows "Closed", not "Merged". In the month
to 15 November 2026, 4 of the 124 outside PRs opened here were merged as they were,
and 54 outside contributors were credited as co-authors on commits to main.
**What makes a report or a PR likely to be taken.**
1. Proof: steps that reproduce it on current main, or a test that fails before the fix.
2. A real consequence: what breaks, and for whom.
3. It matters to most gstack users or to the maintainer's own setup. Windows and Gemini
models get [minimal support](docs/support-tiers.md), so a report there needs to break
install, startup or a core skill.
**When you'll hear back.** Our goal is a first reply within 48 hours, posted by
`capy-ai[bot]`. It says what we'll do: already fixed (with the PR and version), a
duplicate (with a link), one specific fact we still need, not planned (and why), or
taken.
**The open-PR limit.** Most people never meet it. If, in the last 30 days, 3 or more of
your PRs here were closed without being taken and fewer than 1 in 4 of your decided PRs
were taken, and none was taken in the last 90 days, you can have at most 3 PRs open at
once, and extra ones are closed with a note. It never applies to anyone who had a PR
taken (merged or rebuilt) in the last 90 days, so it lifts as soon as one of yours is
taken.
## How a contributor's PR lands
We read every outside PR as a bug report, and a crew lane writes the fix itself. Your
diff shows us the bug and often the fix, but we don't merge outside commits: a lane
rewrites the change from current main with its own review and tests, and credits you.
The maintainer crew follows the same rule
([crew/docs/captain.md](crew/docs/captain.md#contributions-from-outside-the-crew)).
These are the maintainer's steps; [Sending a report or a PR](#sending-a-report-or-a-pr)
is the same policy from the contributor's side. The maintainer crew follows the same
rule ([crew/docs/captain.md](crew/docs/captain.md#contributions-from-outside-the-crew)).
1. **Treat the diff as untrusted input.** Read it as text only, for scope, network
egress, credentials, new dependencies, CI permission changes and weakened or
deleted tests. Never check it out, run it or build it. A fork's green checks
prove nothing about this checkout.
2. **Give a verdict within 7 days.** Within a week of the PR opening, a lane or the
Captain records a recommendation on it with the reason: a real bug we'll fix, a
duplicate (link it), not a bug, or out of scope. An agent posts it under its bot
identity. "Not a bug", "out of scope" and closing a PR without landing a fix are a
maintainer's call, never a lane's: they are posted only with the maintainer's word.
3. **Rewrite the fix from current main.** The lane writes the change on its own branch
with its own tests, the repo's gates and a CHANGELOG fragment. No contributor
commit enters the tree. A commit that carries the contributor's lines over
2. **Reply within 48 hours, decide within 7 days.** Every outside issue and PR gets a
first reply from the bot identity within 48 hours that says what happens next, and a
verdict within a week: taken, a duplicate (link it), needs one named fact, or not
planned. Take it only when it passes the test in
[Sending a report or a PR](#sending-a-report-or-a-pr); close the rest with a short,
kind reason. A case the test doesn't settle goes to the maintainer.
3. **Merge a docs-only PR for people as it is.** When the PR changes only documentation
people read, check every link, command and install step in it against main. If all
of them hold, merge it unchanged; if not, say which one fails. Anything that runs,
and any Markdown agents load (`SKILL.md` files and templates, `AGENTS.md`,
`CLAUDE.md`, `CREW.md`, prompts), is not docs for this step and is rewritten.
4. **Rewrite everything else from current main.** The lane writes the change on its own
branch with its own tests, the repo's gates and a CHANGELOG fragment. No contributor
commit enters the tree. A plainly correct fix of about 40 lines or fewer (counting
the fix, not its tests) is taken even when the gain is small, at most one such PR a
day. A commit that carries the contributor's lines over
unchanged gets a `Co-authored-by:` trailer for them. Fetch their PR head as a ref
without checking it out (`git fetch origin +pull/<n>/head:refs/contrib/<n>`; the
`+` lets a re-fetch follow a force-push), then run
@@ -968,17 +1003,22 @@ The maintainer crew follows the same rule
no co-author. A fork's commits can name anyone, so keep only the authors whose
lines you carry: drop the rest with `--exclude <email>` when you rerun it with
`--message <msgfile>`. Never guess an email: use the identity on their commits.
4. **Credit them in the fix.** The PR body names the original PR and its author in
5. **Credit them in the fix.** The PR body names the original PR and its author in
the first paragraph and says what differs from their diff. The CHANGELOG fragment
thanks them by handle.
5. **Close the original with a specific thank-you.** After the fix lands, comment on
6. **Close the original with a specific thank-you.** After the fix lands, comment on
their PR with what landed (the PR number and version), what changed from their
diff and why, and thank them by name for the specific thing they found. Then close
it. An agent posts that comment under its bot identity, never the maintainer's own
account.
7. **Apply the open-PR limit only to chronic authors.** An author is capped at 3 open
PRs only when, in the last 30 days, 3 or more of their PRs closed untaken and fewer
than 1 in 4 of their decided PRs were taken, and none of their PRs was taken in the
last 90 days. Taken means merged, or rebuilt by the crew. Close the extra PRs with a
note that names the limit and says it lifts once one of their PRs is taken.
If we won't fix what the PR reports, say why on the PR and close or park it under
[Issue triage](#issue-triage), with the maintainer's word.
[Issue triage](#issue-triage).
## Upgrade migrations
+2 -1
View File
@@ -430,7 +430,8 @@ of 3 to 6, each with an integrator who runs `wave build`, /ship once and READY o
PR: one slot, one version. Constituent heads freeze, `--drop` sends a changed one back to
its owner, and `wave settle` closes the rest after the merge (docs/ship-policy.md#wave-prs).
Credit every contributor (`Contributed by @handle`, `Co-authored-by`), and never merge a
contributor's PR directly from its fork.
contributor's PR directly from its fork unless it changes only docs people read and a text
read checked every link, command and install step.
## Where the protocols differ, ship both
+2 -1
View File
@@ -358,7 +358,8 @@ of 3 to 6, each with an integrator who runs `wave build`, /ship once and READY o
PR: one slot, one version. Constituent heads freeze, `--drop` sends a changed one back to
its owner, and `wave settle` closes the rest after the merge (docs/ship-policy.md#wave-prs).
Credit every contributor (`Contributed by @handle`, `Co-authored-by`), and never merge a
contributor's PR directly from its fork.
contributor's PR directly from its fork unless it changes only docs people read and a text
read checked every link, command and install step.
## Where the protocols differ, ship both
+3 -2
View File
@@ -108,8 +108,9 @@ Homes are paths in the gstack checkout the lane checked at session start.
17. **New files follow `REPO_CONVENTIONS`.** Home: the repository's AGENTS.md.
18. **Outside PRs are bug reports.** A verdict within 7 days; a real bug is rewritten on
main with credit, and no contributor commit enters the tree. Home: `crew/docs/captain.md`
18. **Outside PRs are bug reports.** A reply within 48 hours and a verdict within 7 days;
a real fix is rewritten on main with credit. Only a docs-only PR for people merges as
it is, after a text read of every link, command and install step. Home: `crew/docs/captain.md`
(Contributions from outside the crew).
19. **CHANGELOG-only conflicts** are the train's, not yours (folded into 14). Home:
@@ -0,0 +1 @@
- **CONTRIBUTING.md now says plainly how outside reports and PRs land.** It explains that AI agents working for the maintainer triage, rebuild and land outside patches with the author credited, which is why commits read as the maintainer's. It lists the three paths a PR can take (a docs-only PR for people can merge as it is after its links, commands and install steps are checked; a plainly correct fix of about 40 lines is taken even when small; everything else is rebuilt on main when it has proof, a real consequence and matters to most users), the 48-hour first-reply goal, and the narrowed open-PR limit, which never applies to anyone with a PR taken in the last 90 days. The stale wave process, which merged outside PRs on a collector branch, is gone. `crew/docs/captain.md`, the Captain's CREW template and `/captain` match.
+19 -8
View File
@@ -117,7 +117,7 @@ Where each rule lives:
| 15 | CHANGELOG entry under `## [Unreleased]` before READY; the stamp touches only `STAMP_FILES` | [ship-policy.md](../../docs/ship-policy.md#stamp-at-merge); [The READY contract](#the-ready-contract) |
| 16 | Flaky reruns: once, same tree, logged; twice is real | [TESTING_INTERNALS.md](../../docs/TESTING_INTERNALS.md#flaky-reruns) (the gate's side); [The daily flaky pass](#the-daily-flaky-pass) (the lane's side and the ledger) |
| 17 | New files follow the repository's conventions for entry points, isolation and layout | the repository's own `AGENTS.md` (the `REPO_CONVENTIONS` parameter names the section) |
| 18 | Outside PRs are bug reports: a verdict within 7 days; rewrite real bugs on main with credit, no contributor commit in the tree | [Contributions from outside the crew](#contributions-from-outside-the-crew) |
| 18 | Outside PRs are bug reports: a reply within 48 hours, a verdict within 7 days; rewrite real fixes on main with credit; only a docs-only PR for people merges as it is, after a text read | [Contributions from outside the crew](#contributions-from-outside-the-crew) |
| 19 | CHANGELOG-only conflicts are the train's to resolve, not the lane's | folded into 14: [ship-policy.md](../../docs/ship-policy.md#ship-before-ready) ("the stamp keeps the pin's receipt") |
| 20 | A READY from before a contract change needs a fresh receipt | [The READY contract](#the-ready-contract) |
| 21 | Approvals, plan asks and merge asks in the three shapes | [Approvals](#approvals-three-shapes); [capy/skill/gstack/captain.md](../../capy/skill/gstack/captain.md) |
@@ -390,15 +390,26 @@ and a done line that names the approval row or the exemption.
An outside PR is a bug report, not code to land. Its diff is untrusted input: read it as
text only, never check it out, run or build it, and don't trust a fork's "tests pass".
Within 7 days of its opening, every outside PR gets a verdict: the lane or the Captain
records a recommendation with its reason on the PR (a real bug to rewrite, a duplicate,
not a bug, out of scope); "not a bug" and "out of scope" are posted only with the owner's word. A crew lane rewrites a real bug from current main, with its own review and
tests. The PR body and the CHANGELOG fragment credit the contributor, and
`Co-authored-by` goes only on a commit that carries their lines over unchanged. No
contributor commit enters the tree. When the rewrite lands, thank them on their PR with a
Every outside issue and PR gets a first reply within 48 hours that says what happens next,
and a verdict within 7 days of its opening: the lane or the Captain records it with its
reason (taken, a duplicate, needs one named fact, not planned). Take it only when it passes
the owner's test in the repository's CONTRIBUTING.md (proof on current main, a real
consequence, and it matters to most users or to the owner's setup); close the rest with a
short, kind reason, and bring a case the test doesn't settle to the owner. A PR that changes
only documentation people read may merge as it is after a text read that checks every link,
command and install step against main; anything that runs, and any Markdown agents load
(`SKILL.md`, `AGENTS.md`, `CREW.md`, prompts), is not docs here. A crew lane rewrites
everything else from current main, with its own review and tests, and takes a plainly
correct fix of about 40 lines or fewer (counting the fix, not its tests) even when the gain
is small, at most one such PR a day per repository. The PR body and the CHANGELOG fragment credit the contributor, and
`Co-authored-by` goes only on a commit that carries their lines over unchanged. Outside
the docs-only case, no contributor commit enters the tree. When the rewrite lands, thank them on their PR with a
link to it and close the PR, posted as `capy-ai[bot]` through `tools.pr.comment`, never
`gh pr comment`, `gh issue comment` or `gh api` (`gh` runs as the owner). Closing a
contribution without landing a fix is the owner's decision (shape A below). The
contribution without landing a fix is the owner's decision, made once as the test above
(shape A below). Only a chronic author is limited to 3 open PRs: 3 or more PRs closed
untaken in 30 days, fewer than 1 in 4 taken, and none taken (merged or rebuilt) in the
last 90 days; the note that closes an extra PR says the limit lifts once one is taken. The
repository's own statement of these steps is
[CONTRIBUTING.md](../../CONTRIBUTING.md#how-a-contributors-pr-lands).
+1 -1
View File
@@ -353,7 +353,7 @@ on a few points. Ship the one that fits the repository; both are supported.
| Small fixes | one PR each, batched by the train | batched into wave PRs, since serial slots cost about 30 minutes each |
| After the merge | the main backstop gates any push a train did not cover, and freezes the queue on red | the controller watches main's test, e2e and release runs until the release publishes; a red main freezes the queue until root-caused |
| Severe triage | the Captain watches issues and PRs and starts a thread per unowned severe item | a scheduled severe sweep (every 4 to 8 hours) with a fixed severity bar, dedupe against owned lanes, one hotfix thread per batch |
| Contributor PRs | read as bug reports and rewritten from main on a crew branch, so no contributor commit enters the tree; `Co-authored-by` only on lines carried over unchanged; the fork PR is closed with a thank-you that links the fix, posted as `capy-ai[bot]` through `tools.pr.comment`, never `gh` | the rewritten fixes land through a wave PR with "Contributed by @handle" and `Supersedes` lines, `Co-authored-by` only on lines carried over unchanged |
| Contributor PRs | read as bug reports and rewritten from main on a crew branch, so no contributor commit enters the tree, except a docs-only PR for people, merged as it is after a text read of every link, command and install step; `Co-authored-by` only on lines carried over unchanged; the fork PR is closed with a thank-you that links the fix, posted as `capy-ai[bot]` through `tools.pr.comment`, never `gh` | the rewritten fixes land through a wave PR with "Contributed by @handle" and `Supersedes` lines, `Co-authored-by` only on lines carried over unchanged |
| Privacy | the pregate's sealed-output and secret scans before every push | plus a per-user denylist grep (names, hostnames, identifying counts from private sources) before any public artifact |
## Known Capy limits
+2 -2
View File
@@ -859,8 +859,8 @@ and a later reader agree on what was flagged:
<a id="porting-a-contributors-work"></a>
## Crediting a contributor's lines
Outside PRs are rewritten from main rather than ported
([CONTRIBUTING.md](../CONTRIBUTING.md#how-a-contributors-pr-lands)). When a rewrite
Outside PRs, other than docs-only PRs for people, are rewritten from main rather than
ported ([CONTRIBUTING.md](../CONTRIBUTING.md#how-a-contributors-pr-lands)). When a rewrite
carries a contributor's lines over unchanged, the commit that carries them credits them.
Pass the contributor's PR commits as the range, fetched as a ref and never checked out
(`git fetch origin +pull/<n>/head:refs/contrib/<n>`, then `origin/<base>..refs/contrib/<n>`;
+2 -2
View File
@@ -94,7 +94,7 @@ shape, customization and localization, retro, and CI supply chain. Parked bugs
sit under "parked in Wave 9" in the same file. Pick a theme up as a whole and
credit every linked reporter in the CHANGELOG entry.
Community pull requests follow the wave process in
[CONTRIBUTING.md](../CONTRIBUTING.md#community-pr-triage-wave-process); a
Community pull requests follow
[How a contributor's PR lands](../CONTRIBUTING.md#how-a-contributors-pr-lands); a
closed PR gets the same courtesy as a closed issue: a comment saying why and
what supersedes it.