From 7c918efcdab6f8261304e7fde16dc4be232bb9de Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Wed, 4 Nov 2026 16:57:03 -0800 Subject: [PATCH] docs: agents close or label with no comment; notes to people are drafts for the maintainer (GST-1376) (#4010) * docs: agents close or label with no comment; notes to people are drafts for the maintainer (GST-1376) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * test(modernize): pin the no-comment rule (GST-1376) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * docs(modernize): Step 3 asks before any push or close, never a closing comment (GST-1376) 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> --- CONTRIBUTING.md | 25 ++++++++++++------- .../capy-gst-1376-no-comments-to-people.md | 1 + docs/captain.md | 4 ++- docs/recommended-harness.md | 2 +- docs/skills.md | 5 ++-- docs/support-tiers.md | 2 +- docs/triage.md | 7 ++++++ modernize/SKILL.md | 6 +++-- modernize/SKILL.md.tmpl | 6 +++-- test/modernize-skill.test.ts | 3 ++- 10 files changed, 42 insertions(+), 19 deletions(-) create mode 100644 changelog.d/capy-gst-1376-no-comments-to-people.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 72e98612a..2e2e00d28 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -919,7 +919,9 @@ This affects all projects. To revert: `git checkout main && git pull && bun run An issue is open, parked or closed, and closed means fixed, duplicate or won't fix, each with its reason in the closing comment. An issue we intend to fix later stays open under the `parked` label with one comment saying where it is -tracked (a TODOS.md theme or a tracking issue) and what fixes it. The full rule, +tracked (a TODOS.md theme or a tracking issue) and what fixes it. Those comments +are a maintainer's to post: an agent triaging for the maintainer closes or labels +with no comment and writes each note as a draft for 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) @@ -933,7 +935,9 @@ When community PRs accumulate, batch them into themed waves: 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. + respect that with clear communication. A maintainer posts these notes and + comments; an agent running the wave closes with no comment and writes each + one as a draft for the maintainer to send. 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. @@ -970,16 +974,19 @@ follows ([docs/captain.md](docs/captain.md#contributions-from-outside-the-crew)) port's `## Approvals` section (when the repo uses one) records who asked for the port. 5. **Close the original with a specific thank-you.** After the port lands, - comment on their PR with what landed (the port's number and version), what - you changed and why, and thank them by name for the specific thing they - fixed. Then close it. Closing a contribution without landing it is a + a maintainer comments on their PR with what landed (the port's number and + version), what you changed and why, and thanks them by name for the + specific thing they fixed, then closes it. An agent doing the port closes + their PR with no comment and writes that thank-you as a draft for the + maintainer to send; the credit stays in the port's PR body and its + `Co-authored-by:` lines. Closing a contribution without landing it is a maintainer's call, never a lane's: ask first, and when the answer is no, - say why in the same comment. + the reason goes in the same comment or draft. A port is not a rewrite. If the contributor's approach is one you would not -land, say that on their PR and close or park it under -[Issue triage](#issue-triage) instead of shipping a different change under -their name. +land, say that on their PR (an agent drafts the note for the maintainer +instead) and close or park it under [Issue triage](#issue-triage) instead of +shipping a different change under their name. ## Upgrade migrations diff --git a/changelog.d/capy-gst-1376-no-comments-to-people.md b/changelog.d/capy-gst-1376-no-comments-to-people.md new file mode 100644 index 000000000..ecda52495 --- /dev/null +++ b/changelog.d/capy-gst-1376-no-comments-to-people.md @@ -0,0 +1 @@ +- **Agents no longer comment to people on a maintainer's behalf.** CONTRIBUTING.md (porting step 5, the wave process and issue triage), docs/triage.md, docs/captain.md, docs/support-tiers.md, docs/recommended-harness.md and /modernize used to tell an agent to thank a contributor, explain a close or point to a winner in a GitHub comment. When an agent does the work it now closes or labels with no comment and writes the note as a draft for the maintainer to send; a maintainer can still comment, and credit stays in the PR body and `Co-authored-by:` lines. (GST-1376) diff --git a/docs/captain.md b/docs/captain.md index f395dbf7d..a6280c098 100644 --- a/docs/captain.md +++ b/docs/captain.md @@ -248,7 +248,9 @@ dependencies, CI permissions and weakened tests before anything runs it, and do a fork's "tests pass": run a focused review and the free tier at the port head before the port opens. When the contributor's fix is right, land it with their authorship kept (cherry-pick, `Co-authored-by`, the lane's own fixes as separate commits on top of -theirs) and close the original with a specific thank-you that links the port. Closing a +theirs) and close the original with no comment: the specific thank-you that links the port +is a draft for the owner to send, and the credit stays in the port's PR body and +`Co-authored-by`. Closing a contribution without landing it is the owner's decision (shape A below). The repository's own statement of the porting steps is [CONTRIBUTING.md](../CONTRIBUTING.md#porting-a-contributors-pr). diff --git a/docs/recommended-harness.md b/docs/recommended-harness.md index 3226b492e..8482d15f2 100644 --- a/docs/recommended-harness.md +++ b/docs/recommended-harness.md @@ -351,7 +351,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 | ported onto a crew branch with the author's commits kept and `Co-authored-by`; the fork PR is closed with a thank-you that links the port | landed through a wave PR with "Contributed by @handle", `Co-Authored-By` and `Supersedes` lines | +| Contributor PRs | ported onto a crew branch with the author's commits kept and `Co-authored-by`; the fork PR is closed with no comment, and the thank-you that links the port is drafted for the owner to send | landed through a wave PR with "Contributed by @handle", `Co-Authored-By` and `Supersedes` lines | | 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 diff --git a/docs/skills.md b/docs/skills.md index 58b3f91a8..fbc205f04 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -831,8 +831,9 @@ Claude: Claim: #2187 caches the skill census so `bun run skill:check` stops already memoizes per process. The cache the PR adds would be a second one. Verdict: CLOSE. The base solves the problem another way (a2f9c01). Nothing - was pushed and the PR stays open; say "close it" and I will post the reason - and the superseding commit, with thanks to its author. + was pushed and the PR stays open; say "close it" and I will close it with no + comment, and draft the reason, the superseding commit and a thank-you to + its author for you to post. ``` Three verdicts, one chosen before anything is pushed. **MODERNIZE**: the claim still diff --git a/docs/support-tiers.md b/docs/support-tiers.md index b69b507a9..9678d922a 100644 --- a/docs/support-tiers.md +++ b/docs/support-tiers.md @@ -19,7 +19,7 @@ That is the whole promise. Other skills, optional parts such as `/cso`'s native - No Windows-only or Gemini-only features, parity work, tuning or polish. - No new Windows or Gemini CI jobs or eval cells, apart from the path-scoped Windows checks under Windows CI below (ship-90-90 plan D). Other Windows CI tuning stops. -- A Windows-only or Gemini-only report that doesn't break install, startup or a core workflow closes as won't fix ([triage rules](triage.md#closing-an-issue)), with a link to this page. A report that does break one of them gets a small fix. +- A Windows-only or Gemini-only report that doesn't break install, startup or a core workflow closes as won't fix ([triage rules](triage.md#closing-an-issue)), with a link to this page in the closing comment (a maintainer's to post; an agent drafts it). A report that does break one of them gets a small fix. ## Windows CI diff --git a/docs/triage.md b/docs/triage.md index 57bee8764..4acd89a2b 100644 --- a/docs/triage.md +++ b/docs/triage.md @@ -7,6 +7,13 @@ feature requests into TODOS.md themes with a "not rejected" note, and reporters still saw a closed issue with no fix. Those were reopened on 2026-10-25 under the `parked` label, and this page is the rule going forward. +Every comment this page describes is a maintainer's to post. An agent triaging +for the maintainer never comments to a person, not even a thank-you, a "fixed +in" note, an ask for more information or a won't-fix note (Garry, 2026-11-04: +"never send emails or messages to human beings on my behalf ever"). It closes or +labels with no comment and writes each comment as a draft for the maintainer to +send. Credit stays in PR bodies and `Co-authored-by:` lines. + ## The three states | State | Meaning | How it looks on GitHub | diff --git a/modernize/SKILL.md b/modernize/SKILL.md index 60fc559ce..1731136f7 100644 --- a/modernize/SKILL.md +++ b/modernize/SKILL.md @@ -113,6 +113,8 @@ your own; this skill is for a branch that has gone stale, often someone else's. - You never close a PR. CLOSE is a recommendation with reasons; the person who asked, or the PR's owner, closes it. Without explicit permission in this session, the PR stays open. +- You never comment on the PR. A closing note or a thank-you to its author is a + draft in your report for the person to post. - Textual cleanliness is not currency. "Git reports no conflicts" says nothing about whether the change still makes sense; a PR that applies cleanly to code whose contract moved is more dangerous than one that conflicts. @@ -176,7 +178,7 @@ Pick exactly one and state it with the evidence from Steps 1 and 2: | **CLOSE** | The problem no longer exists, the base solves it another way, or the direction was decided against. | No push. Recommend closing with the specific reason and the commit or PR that superseded it. The PR stays open until someone with the authority says so. | Show the table row you chose and the three sentences from Step 1, then STOP and -ask (AskUserQuestion) before any push or any closing comment. If the session is +ask (AskUserQuestion) before any push or any close. If the session is unattended, the verdict and its evidence are the handoff and nothing is pushed. ## Step 4 (MODERNIZE only): Rebase and prove intent survived @@ -233,7 +235,7 @@ remote); without permission, push to a new branch on origin and say so. ## Step 6: Report -Post or hand off, in this order: the verdict and the three sentences; the +Report or hand off, in this order: the verdict and the three sentences; the conceptual-conflict findings with their commits; for MODERNIZE, the range-diff summary, the tests run and the lease push line; for REWORK or CLOSE, the recommended next action and who decides it. Credit the original author in every diff --git a/modernize/SKILL.md.tmpl b/modernize/SKILL.md.tmpl index 93f2883e9..7f0e881d8 100644 --- a/modernize/SKILL.md.tmpl +++ b/modernize/SKILL.md.tmpl @@ -42,6 +42,8 @@ your own; this skill is for a branch that has gone stale, often someone else's. - You never close a PR. CLOSE is a recommendation with reasons; the person who asked, or the PR's owner, closes it. Without explicit permission in this session, the PR stays open. +- You never comment on the PR. A closing note or a thank-you to its author is a + draft in your report for the person to post. - Textual cleanliness is not currency. "Git reports no conflicts" says nothing about whether the change still makes sense; a PR that applies cleanly to code whose contract moved is more dangerous than one that conflicts. @@ -105,7 +107,7 @@ Pick exactly one and state it with the evidence from Steps 1 and 2: | **CLOSE** | The problem no longer exists, the base solves it another way, or the direction was decided against. | No push. Recommend closing with the specific reason and the commit or PR that superseded it. The PR stays open until someone with the authority says so. | Show the table row you chose and the three sentences from Step 1, then STOP and -ask (AskUserQuestion) before any push or any closing comment. If the session is +ask (AskUserQuestion) before any push or any close. If the session is unattended, the verdict and its evidence are the handoff and nothing is pushed. ## Step 4 (MODERNIZE only): Rebase and prove intent survived @@ -162,7 +164,7 @@ remote); without permission, push to a new branch on origin and say so. ## Step 6: Report -Post or hand off, in this order: the verdict and the three sentences; the +Report or hand off, in this order: the verdict and the three sentences; the conceptual-conflict findings with their commits; for MODERNIZE, the range-diff summary, the tests run and the lease push line; for REWORK or CLOSE, the recommended next action and who decides it. Credit the original author in every diff --git a/test/modernize-skill.test.ts b/test/modernize-skill.test.ts index bbc912abc..425958b28 100644 --- a/test/modernize-skill.test.ts +++ b/test/modernize-skill.test.ts @@ -32,7 +32,7 @@ describe('/modernize skill', () => { expect(flat).toContain('The disposition comes first. No rebase is pushed, and no PR is closed, until the verdict below is written and shown.'); expect(skill.indexOf('## Step 3: The disposition')).toBeLessThan(skill.indexOf('## Step 4 (MODERNIZE only)')); expect(skill.indexOf('## Step 4 (MODERNIZE only)')).toBeLessThan(skill.indexOf('## Step 5 (MODERNIZE only)')); - expect(flat).toContain('STOP and ask (AskUserQuestion) before any push or any closing comment'); + expect(flat).toContain('STOP and ask (AskUserQuestion) before any push or any close.'); expect(flat).toContain('If the session is unattended, the verdict and its evidence are the handoff and nothing is pushed.'); }); @@ -40,6 +40,7 @@ describe('/modernize skill', () => { expect(flat).toContain('You never close a PR.'); expect(flat).toContain('Without explicit permission in this session, the PR stays open.'); expect(flat).toContain('The PR stays open until someone with the authority says so.'); + expect(flat).toContain('You never comment on the PR. A closing note or a thank-you to its author is a draft in your report for the person to post.'); expect(skill).not.toMatch(/gh pr close/); });