Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Tell outside contributors what happens to their pull requests, and label issues our own automation files (#9378)

Garry Tanaab958d1a0f8
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000000..1a344d44ad
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+ - name: Community issues
+ url: https://github.com/garrytan/gbrain/issues?q=is%3Aissue%20is%3Aopen%20-label%3Aagent-filed
+ about: Open issues from the community, without the ones our own agents and CI file (label agent-filed). Check here before you file a duplicate.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5681765bd7..6ddebe0884 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -805,23 +805,65 @@ gstack reads both from master, so a branch's edits take effect after it merges.
2 MB ceiling. Those files stay covered by the privacy, gitleaks and doc
checks, and every code, test and config line is still reviewed.
-### How a contributor PR lands
-
-Contributor PRs are never merged into master as-is. A maintainer folds the
-change into a fix-wave PR, revises it there (tests, agent-facing errors,
-conventions) and lands it with credit: the commit says `Contributed by @handle`
-and carries a `Co-Authored-By:` trailer. Your PR stays open until then. When
-the fix wave merges, a workflow closes your PR with a comment that links the wave.
-
-The **Fix-wave gate** check enforces this. It fails every PR into master whose
-head branch is not in `garrytan/gbrain` itself, and posts one comment saying
-so when the PR opens. A red gate on a contributor PR is expected and is not a
-judgment of the work. Maintainers' own branches (`capy/*`, `garrytan/*`) pass.
+### How an outside pull request is handled
+
+Thanks for sending one. Here is what happens to it, so nothing comes as a
+surprise:
+
+- **Documentation people read** (README, guides, docs pages; not Markdown that
+ agents load, such as SKILL.md, AGENTS.md or prompts) can be merged as it is,
+ after we check every link, command and install step in it.
+- **Small, plainly correct fixes** (under about 40 lines, not counting tests:
+ an error message, a typo, a small docs fix) are taken even when the gain is
+ small. We rebuild them on current master and credit you as co-author: the
+ commit says `Contributed by @handle` and carries a `Co-Authored-By:`
+ trailer. We land at most one of these a day, so it can take a few days.
+- **Everything else**, including all other code and anything that runs, we
+ read as a detailed bug report. When we take it, we rebuild it on current
+ master with the same credit.
+
+Every pull request, ours and an outside documentation change alike, lands on
+master as one squashed commit, with each outside author credited by a
+`Co-authored-by:` trailer. When we rebuild a change, we close your PR with a
+link to the PR that landed it. When we don't take one, we close it with a
+short note saying why and what would change our answer. So apart from
+documentation, "closed, not merged" is the normal outcome and doesn't mean
+your work was turned down.
+
+A larger change is much easier to take when it shows:
+
+1. a way to reproduce the problem on current master, or a failing test;
+2. what goes wrong for someone using gbrain because of it;
+3. the version you saw it on (`gbrain version`).
+
+A limit of 3 open pull requests applies only to someone whose recent pull
+requests have mostly been closed without being taken. It never applies to
+anyone who has had a pull request taken (merged or rebuilt) in the last 90 days.
+
+Replies on behalf of the project come from the Capy app (`capy-ai[bot]`) or
+a maintainer; a comment from any other account that calls itself triage does
+not speak for gbrain. Every outside issue gets a first reply from us within 48
+hours. A bug report we could not reproduce gets one follow-up question after
+60 days, and is closed two weeks after that if nobody answers.
+
+The same three things make a bug report easy to act on. To see what the
+community has reported, without the issues our own agents and CI file, use the
+[community issues](https://github.com/garrytan/gbrain/issues?q=is%3Aissue%20is%3Aopen%20-label%3Aagent-filed)
+search: it lists open issues without the `agent-filed` label, which our CI
+scripts add to every issue they open and which we have added to the open
+issues our own agents filed.
+
+The **Fix-wave gate** check runs on every PR into master. It fails every PR
+whose head branch is not in `garrytan/gbrain` itself, and posts the comment
+above when the PR opens. A red gate on an outside PR is expected and is not a
+judgment of the work; a maintainer clears it when merging a documentation
+change. Maintainers' own branches (`capy/*`, `garrytan/*`) pass.
`maintainer-override` label: a human on the maintainer allowlist in
`scripts/fix-wave-gate.ts` (it starts as `garrytan`) may apply it to pass the
-gate for one PR a maintainer has decided may land from its fork (for example a
-fix wave a maintainer opened from a fork); record the reason in a PR comment.
+gate for one PR a maintainer has decided may land from its fork (for example an
+outside documentation change, or a PR a maintainer opened from a fork); record
+the reason in a PR comment.
Bots never count, and the label only counts when the most recent
`labeled` event was made by an allowlisted human. Every override is written to
the check's run log and step summary with who applied it and when. Process and
diff --git a/README.md b/README.md
index acd7633baf..499d680a51 100644
--- a/README.md
+++ b/README.md
@@ -366,7 +366,7 @@ Start with `gbrain doctor`. For database access failures, use `gbrain engine sta
Run `bun run test` for the fast loop, `bun run verify` for the pre-push gate, `bun run ci:local` to run the full Docker-backed CI stack locally. Detailed test discipline in [`CONTRIBUTING.md`](CONTRIBUTING.md).
-Community PRs are batched into release waves rather than merged one-by-one — see the community-PR-wave process in [`docs/RELEASING.md`](docs/RELEASING.md). Contributor attribution stays attached via `Co-Authored-By:` trailers. We credit every accepted contribution in [`CHANGELOG.md`](CHANGELOG.md).
+Outside documentation changes can be merged as they are. Code fixes we take are rebuilt on current master with the author credited as co-author (`Co-Authored-By:` trailers), and the original PR is closed with a link to the one that landed it; changes we don't take are closed with a note saying why. What to expect, and what makes a fix easy to take: [How an outside pull request is handled](CONTRIBUTING.md#how-an-outside-pull-request-is-handled). We credit every accepted contribution in [`CHANGELOG.md`](CHANGELOG.md). To browse community reports without our agents' own issues, use the [community issues](https://github.com/garrytan/gbrain/issues?q=is%3Aissue%20is%3Aopen%20-label%3Aagent-filed) search.
If you find a bug or want a feature: open an issue first. Quick fixes (typo, doc bug, obvious regression) can go straight to a PR. Anything touching schema, retrieval ranking, MCP protocol, or the security boundary needs a design discussion in the issue first.
diff --git a/docs/RELEASING.md b/docs/RELEASING.md
index 80b93534de..7928bbaf8f 100644
--- a/docs/RELEASING.md
+++ b/docs/RELEASING.md
@@ -927,7 +927,17 @@ to see what's actually in the PR before writing the body.
## Community PR wave process
-Never merge external PRs directly into master. Instead, use the "fix wave" workflow:
+Fix waves built from outside PR lists ended on 2026-11-01. Each outside PR is
+now triaged when it arrives, under the rules contributors see in
+[CONTRIBUTING.md](../CONTRIBUTING.md#how-an-outside-pull-request-is-handled):
+documentation people read may be merged as it is after a text read of every
+link, command and install step; a small, plainly correct fix (under about 40
+lines, not counting tests) is rebuilt on current master with credit, at most one
+small PR a day; anything else is read as a report and rebuilt only when it has
+proof and matters. Outside code is never checked out, run or merged. A rebuild
+PR lists the outside PR on a `Supersedes #N` line so the
+[closeout](#fix-wave-closeout) closes it with a link. The steps below are the
+older batch procedure; steps 4 to 7 still apply to any rebuild PR.
1. **Categorize** — group PRs by theme (bug fixes, features, infra, docs)
2. **Deduplicate** — if two PRs fix the same thing, pick the one that changes fewer
@@ -975,9 +985,11 @@ master unless its head repository is `garrytan/gbrain` or the `maintainer-overri
label counts. Only maintainers can push to `garrytan/gbrain`, so GBRA thread PRs
(`capy/*`) and `garrytan/*` branches pass; fork PRs fail whatever their branch is
called. When a contributor PR opens, a second job posts one comment with the same
-text as the failure: the work is welcome and the PR stays open, it lands through a
-fix wave with credit (`Contributed by @handle` plus a `Co-Authored-By:` trailer), and
-CONTRIBUTING.md "Where does my change go?" explains where changes belong.
+text as the failure: how outside PRs are handled (documentation merged as it is
+after a text read, small correct fixes rebuilt with credit, everything else read as
+a report and rebuilt with credit when taken, `Contributed by @handle` plus a
+`Co-Authored-By:` trailer), the proof a larger change needs, who the open-PR limit
+applies to, and a link to CONTRIBUTING.md "How an outside pull request is handled".
The workflow uses `pull_request_target`, so the workflow and
`scripts/fix-wave-gate.ts` always come from the default branch: a PR that edits
@@ -990,7 +1002,7 @@ repository (deleted fork) fails closed. The check re-runs on `opened`, `edited`,
**`maintainer-override` label.** Who: a human on `MAINTAINERS` in
`scripts/fix-wave-gate.ts` (starts as `garrytan`; changing it is a reviewed PR to
master). When: only for a PR a maintainer has decided may land from its fork, such as
-a fix wave a maintainer opened from a fork; record the reason in a PR comment. How it
+an outside documentation change or a PR a maintainer opened from a fork; record the reason in a PR comment. How it
is checked: the label counts only when the most recent `labeled` timeline event for it
was made by an allowlisted `User`; bots (`capy-ai[bot]`, `github-actions[bot]`, any
`[bot]` login) never qualify, and removing the label fails the PR again. Audit: the run
diff --git a/docs/architecture/key-files/ci-health-and-test-guards.md b/docs/architecture/key-files/ci-health-and-test-guards.md
index 4bd34ce625..0b6193fe83 100644
--- a/docs/architecture/key-files/ci-health-and-test-guards.md
+++ b/docs/architecture/key-files/ci-health-and-test-guards.md
@@ -5,7 +5,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `.github/workflows/nightly-watch.yml` + `scripts/nightly-issue.ts` — nightly-red and master-red incidents. `workflow_run` fires only for master-branch completions; the `resolve` job admits scheduled runs and push-to-master runs of Test and E2E Tests from this repository (head repository checked) plus dispatch, and `nightly-issue.ts --resolve` turns every entry path into the target workflow id and track (`schedule`, `push`; a replay writes `push`); `watch` queues on one group per repository + workflow + track. `nightly-issue.ts --run-id <id> [--replay-issue <n>] [--dry-run]` routes the run (`routeRun`: pull-request, fork, other-branch and non-allowlisted push runs are refused with a next step). Scheduled runs keep one `Nightly red: <workflow>` issue (label `nightly-red`): open on red with job/step pairs, every failing test file with its reproduce line, sanitized error excerpts, the first red run, the last green SHA and compare link, a "Next step for the agent" and a JSON block; update while red; reopen on a flap; close only on a later green scheduled run with complete evidence where every previously failing job executed. Rows in `.github/nightly-known-red.tsv` (at most 3; race-hunt jobs refused) keep a matching incident open under `known-red`. A scheduled Test or E2E Tests run also feeds that workflow's open master-red issue. Push runs go to `scripts/lib/master-red.ts`. A ratchet test fails when a scheduled workflow is not watched. Tests: `test/scripts/nightly-issue.test.ts`. Process: `docs/RELEASING.md#nightly-red-issues`, `docs/ci-red-runbook.md`.
- `.github/workflows/upgrade-matrix.yml` + `scripts/upgrade-matrix.ts` (modules in `scripts/upgrade-matrix/`) — upgrade-from-N matrix (GBRA-224 W2). `plan` resolves the candidate and from-versions (N-1, N-10, N-50, 30 days, stable) from release tags; `cell` installs a from-version with `bun install -g github:garrytan/gbrain` in an isolated HOME, seeds a brain, runs that release's `gbrain upgrade` against `github-fixture.ts` (per-cell bare mirror via git `insteadOf`, loopback tarball API, TLS fixture behind `HTTPS_PROXY`; every other host refused), then checks install identity, one build across a running serve, apply-migrations, schema head, doctor, canonical preservation (`snapshot.ts`), writes, keyed vector query on the mock provider and the old binary on the upgraded brain; `summarize` judges red/hold/green (`verdict.ts`, `known-exceptions.json`, the `W4 SWITCH POINT` for `doctor --alert`); `issue` keeps one `upgrade-break` issue. Tests: `test/scripts/upgrade-matrix.test.ts`. Docs: `docs/ci-upgrade-matrix.md`.
-- `scripts/lib/gh-issue.ts` — the GitHub seam shared by the CI watchers. `inert()` makes run-derived text (job, step and test names, error text) safe to show an agent: control characters stripped, length capped, backticks and pipes replaced, mentions and links neutralized; `redactCredentials()` strips user:password from database URLs. `GitHubClient` is the one interface the watchers call (`restClient()` uses `GH_TOKEN`/`GITHUB_TOKEN` in Actions or the authenticated `gh api` locally; `download()` reads artifact archives without forwarding the token to blob storage). `findIssueByTitle` finds an issue by label and exact title, open first, else the most recently updated closed one; `listLabeled`, `getIssue` and `linkedPulls` (PRs cross-referencing an issue) back master-red and CI health; `fetchArtifactJson` + `readZipEntry` read one JSON file from a run artifact and return a reason instead of throwing.
+- `scripts/lib/gh-issue.ts` — the GitHub seam shared by the CI watchers. `inert()` makes run-derived text (job, step and test names, error text) safe to show an agent: control characters stripped, length capped, backticks and pipes replaced, mentions and links neutralized; `redactCredentials()` strips user:password from database URLs. `GitHubClient` is the one interface the watchers call (`restClient()` uses `GH_TOKEN`/`GITHUB_TOKEN` in Actions or the authenticated `gh api` locally; `download()` reads artifact archives without forwarding the token to blob storage). `findIssueByTitle` finds an issue by label and exact title, open first, else the most recently updated closed one; `listLabeled`, `getIssue` and `linkedPulls` (PRs cross-referencing an issue) back master-red and CI health; `fetchArtifactJson` + `readZipEntry` read one JSON file from a run artifact and return a reason instead of throwing. `createIssue` adds `AGENT_FILED_LABEL` (`agent-filed`) to every issue it opens, so CONTRIBUTING.md's community-issues search can leave automation's issues out; `test/scripts/gh-issue-agent-filed.test.ts` fails if a script or workflow opens an issue any other way.
- `.github/workflows/ci-health.yml` + `scripts/ci-health-report.ts` — CI health report. Reads one window (`--days`, default 7, or `--since/--until`, also dispatch inputs) of same-repository pull-request and push-to-master runs of test.yml and e2e.yml (runs, jobs, check-run annotations, issues; never logs, fork runs or fork artifacts), paging the whole window (`listRuns` splits a query over the 1000-result search cap). It reports first-attempt pass rates (`firstAttempt()`), the exit criteria (master >= 95%, PR >= 90%; met, missed or indeterminate when the window cannot be read in full), stress-gate failures, failure classes, cancellation and completion coverage, master-red time to first response, the nightly-watch residual, the test files with the most failure annotations, shard spread and the count of fork runs it did not read; an explicit window with a missed target opens a follow-up issue. Tests: `test/scripts/ci-health-report.test.ts`. Docs: `docs/ci-red-runbook.md#ci-health-report`.
- `scripts/lib/master-red.ts` — master-red reconciliation for push-to-master runs of Test and E2E Tests (`PUSH_ALLOWLIST`). Each watch evaluates every completed push run above the high-water mark (`evaluated`: run number, then attempt) stored in the newest `Master red: <workflow>` issue's `master-red:json` block (`applyRun` folds runs; cancelled runs change nothing); a missing or malformed block is rebuilt from the actions API (`pendingRuns`). It opens on red with the suspect range (`suspectRange`: compare plus commit-to-PR lookups), updates while red, closes when every previously failing job (E2E Tests: every failing file, from the manifest) ran and passed with complete evidence, records an incident that opened and closed between watches, and keeps a not-run-since failure open with the manual-close step. A newest issue closed by hand while its block is red ends that incident (`closed_by_hand`): later runs are recorded on it as green, and only a new red run opens a new issue. `externalPass` lets a scheduled run or an issue-bound E2E replay clear failures. Closing without a merged linked repair PR opens `flake` issues (`flakeFor`, `flake:json`); `closeFlakes` closes one after its repair PR merged and a later complete run passed its file and arm. Writes re-read the issue first and re-plan when it moved; a create race closes the newer duplicate. Tests: `test/scripts/nightly-issue.test.ts`. Docs: `docs/ci-red-runbook.md`.
- `scripts/lib/ci-run.ts` — one run's failure evidence (`collectEvidence`): jobs, failing jobs' annotations and, for test.yml and e2e.yml, the `ci-manifest` artifact, returned as structured records (job, step, every failing test file and identity) apart from sanitized excerpts; a cancelled job is not run (listed in `cancelled`) unless its annotation says it timed out, and a red run whose only failures are aggregators of cancelled jobs is `ignored`; with `complete`/`problems` (an unreadable page, annotation or manifest is incomplete evidence, never zero failures). A push run with a succeeded `reused-full-suite` job is judged by the run its `reuse.json` names (`checkRecord` from `scripts/ci-reuse.ts`, recorded attempt, identical commit tree): that run's succeeded jobs and complete `ci-manifest` stand in for the push, and any gap is incomplete. `reproduceCommand` builds `bun run test:stress <file> --iterations 10 [--postgres]` from a validated test path only. `exemptionRows` turns failing identities with an exact test name and signature into the stress gate's `<!-- gbrain-stress-exemption -->` records (backend per `stressBackend`, owner `agent on release duty`), written into master-red, flake and nightly-red bodies; `test/fixtures/nightly-watch/stress-exemption-contract.ts` vendors the gate's parser so the tests prove it accepts them.
diff --git a/llms-full.txt b/llms-full.txt
index df61d9eba7..c6d2cf8271 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -4748,7 +4748,7 @@ Start with `gbrain doctor`. For database access failures, use `gbrain engine sta
Run `bun run test` for the fast loop, `bun run verify` for the pre-push gate, `bun run ci:local` to run the full Docker-backed CI stack locally. Detailed test discipline in [`CONTRIBUTING.md`](CONTRIBUTING.md).
-Community PRs are batched into release waves rather than merged one-by-one — see the community-PR-wave process in [`docs/RELEASING.md`](docs/RELEASING.md). Contributor attribution stays attached via `Co-Authored-By:` trailers. We credit every accepted contribution in [`CHANGELOG.md`](CHANGELOG.md).
+Outside documentation changes can be merged as they are. Code fixes we take are rebuilt on current master with the author credited as co-author (`Co-Authored-By:` trailers), and the original PR is closed with a link to the one that landed it; changes we don't take are closed with a note saying why. What to expect, and what makes a fix easy to take: [How an outside pull request is handled](CONTRIBUTING.md#how-an-outside-pull-request-is-handled). We credit every accepted contribution in [`CHANGELOG.md`](CHANGELOG.md). To browse community reports without our agents' own issues, use the [community issues](https://github.com/garrytan/gbrain/issues?q=is%3Aissue%20is%3Aopen%20-label%3Aagent-filed) search.
If you find a bug or want a feature: open an issue first. Quick fixes (typo, doc bug, obvious regression) can go straight to a PR. Anything touching schema, retrieval ranking, MCP protocol, or the security boundary needs a design discussion in the issue first.
diff --git a/scripts/fix-wave-closeout.ts b/scripts/fix-wave-closeout.ts
index 00ded46409..b3af55a24e 100644
--- a/scripts/fix-wave-closeout.ts
+++ b/scripts/fix-wave-closeout.ts
@@ -76,13 +76,13 @@ export function isMergedWave(event: CloseoutEvent): boolean {
export function closeoutMessage(handle: string, wave: number, waveTitle: string, credited: boolean): string {
const credit = credited
- ? ` with credit to you: the wave says \`Contributed by @${handle}\` and carries a \`Co-Authored-By:\` trailer.`
+ ? ` with credit to you: that PR says \`Contributed by @${handle}\` and carries a \`Co-Authored-By:\` trailer.`
: '.';
return [
COMMENT_MARKER,
- `Thank you, @${handle}. Fix-wave PR #${wave} (${waveTitle}) merged into master and supersedes this PR, so the change it proposed has landed there${credit}`,
+ `Thank you, @${handle}. Pull request #${wave} (${waveTitle}) merged into master and supersedes this PR, so the change it proposed has landed there${credit}`,
'',
- `I'm closing this PR because nothing is left for it to land, not because anything was wrong with it. If part of it didn't make it into #${wave}, reply here with what's missing and the next fix wave will pick it up.`,
+ `I'm closing this PR because nothing is left for it to land, not because anything was wrong with it. If part of it didn't make it into #${wave}, reply here with what's missing and why it matters.`,
'',
'This comment comes from the fix-wave closeout workflow.',
].join('\n');
diff --git a/scripts/fix-wave-gate.ts b/scripts/fix-wave-gate.ts
index 1aeb0c97fb..474d1ca7ae 100644
--- a/scripts/fix-wave-gate.ts
+++ b/scripts/fix-wave-gate.ts
@@ -30,7 +30,7 @@ export const OVERRIDE_LABEL = 'maintainer-override';
/** Humans who may apply the override label. Edit only through a reviewed PR to master. */
export const MAINTAINERS: readonly string[] = ['garrytan'];
export const COMMENT_MARKER = '<!-- fix-wave-gate -->';
-const CONTRIBUTING_URL = 'https://github.com/garrytan/gbrain/blob/master/CONTRIBUTING.md#where-does-my-change-go';
+const CONTRIBUTING_URL = 'https://github.com/garrytan/gbrain/blob/master/CONTRIBUTING.md#how-an-outside-pull-request-is-handled';
interface Repo { id?: number; full_name?: string }
interface Actor { login?: string; type?: string }
@@ -54,15 +54,28 @@ export interface GateClient {
}
export function gateMessage(handle: string): string {
+ const credit = 'credit you as co-author: the commit says `Contributed by @' + handle + '` and carries a `Co-Authored-By:` trailer with your name';
return [
COMMENT_MARKER,
- `Thanks for this pull request, @${handle}. The work is welcome, and this PR stays open.`,
+ `Thanks for this pull request, @${handle}. Here is how we handle outside pull requests, so you know what to expect:`,
'',
- 'gbrain does not merge contributor pull requests into master directly. A maintainer folds the change into a fix-wave PR, revises it there (tests, agent-facing errors, conventions), and lands it with credit to you: the commit says `Contributed by @' + handle + '` and carries a `Co-Authored-By:` trailer with your name. When that fix wave merges, this PR is closed with a comment that links it.',
+ '- **Documentation people read** (not files agents load, such as SKILL.md or AGENTS.md) can be merged as it is, after we check every link, command and install step in it.',
+ `- **Small, plainly correct fixes** (under about 40 lines not counting tests, such as an error message or a typo) are taken even when the gain is small. We rebuild them on current master and ${credit}. We land at most one of these a day, so it can take a few days.`,
+ `- **Everything else**, including all other code and anything that runs, we read as a detailed bug report. When we take it, we rebuild it on current master with the same credit.`,
'',
- `You don't need to do anything else. To see where a change belongs and what the fix wave checks, read CONTRIBUTING.md, "Where does my change go?": ${CONTRIBUTING_URL}`,
+ "When we rebuild a change, we close this PR with a link to the PR that landed it. When we don't take one, we close it with a short note saying why and what would change our answer. So apart from documentation, \"closed, not merged\" is the normal outcome and doesn't mean your work was turned down.",
'',
- 'This message comes from the fix-wave gate check, which stays red on contributor PRs by design.',
+ 'For a larger change, show us:',
+ '',
+ '- a way to reproduce the problem on current master, or a failing test;',
+ '- what goes wrong for someone using gbrain because of it;',
+ '- the version you saw it on (`gbrain version`).',
+ '',
+ 'A limit of 3 open pull requests applies only to someone whose recent pull requests have mostly been closed without being taken. It never applies to anyone who has had a pull request taken (merged or rebuilt) in the last 90 days.',
+ '',
+ `More in CONTRIBUTING.md, "How an outside pull request is handled": ${CONTRIBUTING_URL}`,
+ '',
+ 'This comment comes from the fix-wave gate check. It is red on every outside pull request by design, and a maintainer clears it when merging a documentation change.',
].join('\n');
}
diff --git a/scripts/lib/gh-issue.ts b/scripts/lib/gh-issue.ts
index 632eca64ea..1c4e0f3ed9 100644
--- a/scripts/lib/gh-issue.ts
+++ b/scripts/lib/gh-issue.ts
@@ -9,6 +9,7 @@
* - `GitHubClient` is the one seam both scripts call; tests pass a recorded
* fake, production uses `restClient()` (fetch + GH_TOKEN/GITHUB_TOKEN in
* Actions, or the authenticated `gh api` CLI for local dry runs).
+ * - `createIssue` adds `AGENT_FILED_LABEL` to every issue it opens.
* - `findIssueByTitle` looks an issue up through the list API by label and
* exact title (open first, else the most recently updated closed one, so a
* flapping workflow reopens its own issue).
@@ -169,8 +170,11 @@ export async function findIssueByTitle(client: GitHubClient, label: string, titl
export const labelNames = (issue: Issue): string[] => (issue.labels ?? []).map(l => (typeof l === 'string' ? l : l.name));
+/** On every issue our own automation opens, so the community's reports can be listed without it (CONTRIBUTING.md, "How an outside pull request is handled"). */
+export const AGENT_FILED_LABEL = 'agent-filed';
+
export async function createIssue(client: GitHubClient, title: string, body: string, labels: string[]): Promise<Issue> {
- return client.request<Issue>('POST', 'repos/{repo}/issues', { title, body, labels });
+ return client.request<Issue>('POST', 'repos/{repo}/issues', { title, body, labels: [...new Set([...labels, AGENT_FILED_LABEL])] });
}
export async function updateIssue(client: GitHubClient, number: number, patch: { body?: string; state?: 'open' | 'closed'; labels?: string[] }): Promise<Issue> {
diff --git a/scripts/lib/master-red.ts b/scripts/lib/master-red.ts
index 5f13802c0d..bc90906adb 100644
--- a/scripts/lib/master-red.ts
+++ b/scripts/lib/master-red.ts
@@ -28,7 +28,7 @@
* Docs: docs/RELEASING.md#master-red-issues, docs/ci-red-runbook.md#ci-issue-labels.
*/
import {
- commentIssue, createIssue, ensureLabel, getIssue, inert, inertBlock, jsonBlock, linkedPulls, listLabeled, readJsonBlock, updateIssue,
+ AGENT_FILED_LABEL, commentIssue, createIssue, ensureLabel, getIssue, inert, inertBlock, jsonBlock, linkedPulls, listLabeled, readJsonBlock, updateIssue,
type GitHubClient, type Issue,
} from './gh-issue.ts';
import { collectEvidence, EXEMPTION_DAYS, EXEMPTION_MARKER, exemptionRows, plusDays, reproduceCommand, stressBackend, verdictOf, workflowFile, type EvidenceOptions, type FailedJob, type FailedTest, type RunEvidence, type RunInfo } from './ci-run.ts';
@@ -520,7 +520,7 @@ async function writePlan(client: GitHubClient, repo: string, plan: MasterRedPlan
step.issue = (await createIssue(client, plan.title, renderMasterRed(step.state, repo), [MR_LABEL])).number;
const older = step.action === 'create' && (await listLabeled(client, MR_LABEL, 'open')).filter(i => i.title === plan.title && i.number < step.issue!).sort((a, b) => a.number - b.number)[0];
if (older) {
- await updateIssue(client, step.issue, { body: `Duplicate of #${older.number}: two watches created this incident at the same time; #${older.number} carries the state. Nothing to do here.`, state: 'closed', labels: [] });
+ await updateIssue(client, step.issue, { body: `Duplicate of #${older.number}: two watches created this incident at the same time; #${older.number} carries the state. Nothing to do here.`, state: 'closed', labels: [AGENT_FILED_LABEL] });
throw new CreateRace(`#${step.issue} duplicated #${older.number}`);
}
}
diff --git a/scripts/structural-suites.tsv b/scripts/structural-suites.tsv
index 1700216aea..487b37b8bc 100644
--- a/scripts/structural-suites.tsv
+++ b/scripts/structural-suites.tsv
@@ -338,6 +338,7 @@ test/scripts/e2e-wiring.test.ts (file-level) 14 readFileSync
test/scripts/fix-wave-gate.test.ts fix-wave gate workflow 3 readFileSync
test/scripts/full-ci-workflow.test.ts full CI on pull requests 7 readFileSync
test/scripts/full-ci-workflow.test.ts master-push reuse of a passed full-suite run 2 readFileSync
+test/scripts/gh-issue-agent-filed.test.ts agent-filed label 2 readFileSync
test/scripts/heavy-door-workflow.test.ts heavy door supply chain and coverage gates 8 readFileSync
test/scripts/native-lock-prebuilds.test.ts native lock distribution integrity 2 readFileSync
test/scripts/native-setup-toolchain.test.ts scripts/native/setup-toolchain.ts download budget 4 readFileSync
diff --git a/scripts/upgrade-matrix.ts b/scripts/upgrade-matrix.ts
index 89c31a8a1c..a03da238fd 100644
--- a/scripts/upgrade-matrix.ts
+++ b/scripts/upgrade-matrix.ts
@@ -21,6 +21,7 @@ import { join, resolve } from 'node:path';
import { fetchReleases, hasEnoughHistory, RELEASE_TAG, resolveFromVersions, type Candidate, type FromVersion, type Profile, type Release } from './upgrade-matrix/versions.ts';
import { cellId, runCell, type BrainShape, type Engine, type Fault, type Keys } from './upgrade-matrix/cell.ts';
import { CHECKS, loadKnownExceptions, summarize, type CellSummary } from './upgrade-matrix/verdict.ts';
+import { AGENT_FILED_LABEL } from './lib/gh-issue.ts';
const REPO = 'garrytan/gbrain';
const ROOT = resolve(import.meta.dir, '..');
@@ -236,7 +237,7 @@ async function issue(): Promise<void> {
await api('POST', '/issues/' + existing.number + '/comments', { body: 'Still red on ' + (s.candidate.tag ?? s.candidate.sha) + ': ' + s.red.join(', ') + '. ' + (s.harness.run_url ?? '') });
console.log('updated #' + existing.number);
} else {
- const created = await api('POST', '/issues', { title, body, labels: [ISSUE_LABEL] }) as any;
+ const created = await api('POST', '/issues', { title, body, labels: [ISSUE_LABEL, AGENT_FILED_LABEL] }) as any;
console.log('created #' + created.number);
}
} else if (s.status === 'green' && existing?.state === 'open') {
diff --git a/test/scripts/fix-wave-closeout.test.ts b/test/scripts/fix-wave-closeout.test.ts
index 8908df037c..e2215670a2 100644
--- a/test/scripts/fix-wave-closeout.test.ts
+++ b/test/scripts/fix-wave-closeout.test.ts
@@ -79,7 +79,7 @@ describe('fix-wave closeout run', () => {
expect(r.code).toBe(0);
expect(calls).toEqual(['get 5085', 'comment 5085', 'close 5085', 'get 5089', 'comment 5089', 'close 5089']);
expect(comments[5085]![0]).toContain(COMMENT_MARKER);
- expect(comments[5085]![0]).toContain('Fix-wave PR #9000 (v0.60.70.0 fix wave 9)');
+ expect(comments[5085]![0]).toContain('Pull request #9000 (v0.60.70.0 fix wave 9)');
expect(comments[5085]![0]).toContain('`Contributed by @alice-example`');
expect(comments[5089]![0]).not.toContain('Contributed by');
expect(r.summary).toContain('#5085: closed (@alice-example, credited)');
diff --git a/test/scripts/fix-wave-gate.test.ts b/test/scripts/fix-wave-gate.test.ts
index f9c3b120a6..9db22eeeab 100644
--- a/test/scripts/fix-wave-gate.test.ts
+++ b/test/scripts/fix-wave-gate.test.ts
@@ -46,10 +46,17 @@ describe('fix-wave gate decision', () => {
const { client, calls } = fakeClient();
const r = await gate(load('fork-gbra-branch.opened.json'), client);
expect(r.code).toBe(1);
- expect(r.out).toContain('The work is welcome, and this PR stays open.');
+ expect(r.out).not.toContain('stays open');
+ expect(r.out).toContain('can be merged as it is, after we check every link, command and install step');
+ expect(r.out).toContain('are taken even when the gain is small');
+ expect(r.out).toContain('we read as a detailed bug report');
+ expect(r.out).toContain('close this PR with a link to the PR that landed it');
+ expect(r.out).toContain('what would change our answer');
+ expect(r.out).toContain('a failing test');
+ expect(r.out).toContain('never applies to anyone who has had a pull request taken (merged or rebuilt) in the last 90 days');
expect(r.out).toContain('Contributed by @alice-example');
expect(r.out).toContain('Co-Authored-By:');
- expect(r.out).toContain('CONTRIBUTING.md#where-does-my-change-go');
+ expect(r.out).toContain('CONTRIBUTING.md#how-an-outside-pull-request-is-handled');
expect(r.summary).toContain('fail (fork)');
expect(calls).toEqual([]);
});
diff --git a/test/scripts/gh-issue-agent-filed.test.ts b/test/scripts/gh-issue-agent-filed.test.ts
new file mode 100644
index 0000000000..ebb1f8c71c
--- /dev/null
+++ b/test/scripts/gh-issue-agent-filed.test.ts
@@ -0,0 +1,72 @@
+/**
+ * scripts/lib/gh-issue.ts createIssue + every issue filer in the repository.
+ *
+ * Protects: each issue our own automation opens carries the `agent-filed`
+ * label, so CONTRIBUTING.md's "community issues" search (open issues without
+ * that label) shows only community reports. The CI filers (nightly-issue.ts,
+ * master-red.ts, ci-health-report.ts) open issues through createIssue, and
+ * upgrade-matrix.ts names the label itself; the ratchet below fails if a
+ * script or workflow opens an issue any other way.
+ */
+import { describe, expect, test } from 'bun:test';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { AGENT_FILED_LABEL, createIssue, type GitHubClient } from '../../scripts/lib/gh-issue.ts';
+
+const ROOT = join(import.meta.dir, '../..');
+
+function recorder() {
+ const calls: Array<{ method: string; path: string; body: { labels?: string[] } }> = [];
+ const client: GitHubClient = {
+ async request<T>(method: 'GET' | 'POST' | 'PATCH', path: string, body?: unknown): Promise<T> {
+ calls.push({ method, path, body: body as { labels?: string[] } });
+ return { number: 1, title: 't', state: 'open' } as T;
+ },
+ };
+ return { client, calls };
+}
+
+function files(dir: string, keep: (p: string) => boolean): string[] {
+ const out: string[] = [];
+ for (const name of readdirSync(dir)) {
+ const p = join(dir, name);
+ if (statSync(p).isDirectory()) out.push(...files(p, keep));
+ else if (keep(p)) out.push(p);
+ }
+ return out;
+}
+
+describe('agent-filed label', () => {
+ test('createIssue adds the label to the caller\'s labels, once', async () => {
+ expect(AGENT_FILED_LABEL).toBe('agent-filed');
+ const { client, calls } = recorder();
+ await createIssue(client, 'Nightly red: X', 'body', ['nightly-red']);
+ await createIssue(client, 'Flake: y', 'body', ['flake', 'agent-filed']);
+ await createIssue(client, 'z', 'body', []);
+ expect(calls.map(c => [c.method, c.path, c.body.labels])).toEqual([
+ ['POST', 'repos/{repo}/issues', ['nightly-red', 'agent-filed']],
+ ['POST', 'repos/{repo}/issues', ['flake', 'agent-filed']],
+ ['POST', 'repos/{repo}/issues', ['agent-filed']],
+ ]);
+ });
+
+ test('no script or workflow opens an issue without the label', () => {
+ const candidates = [
+ ...files(join(ROOT, 'scripts'), p => /\.(ts|sh|js|mjs)$/.test(p)),
+ ...files(join(ROOT, '.github'), p => /\.ya?ml$/.test(p)),
+ ];
+ const offenders: string[] = [];
+ for (const p of candidates) {
+ const rel = relative(ROOT, p);
+ const text = readFileSync(p, 'utf8');
+ if (/gh\s+issue\s+create|issues\.create\(/.test(text)) offenders.push(`${rel}: gh issue create / issues.create`);
+ if (rel === 'scripts/lib/gh-issue.ts') continue;
+ if (/['"`]POST['"`],\s*['"`](repos\/\{repo\})?\/?issues['"`]/.test(text) && !text.includes('AGENT_FILED_LABEL')) offenders.push(`${rel}: POST to the issues collection without AGENT_FILED_LABEL`);
+ }
+ expect(offenders).toEqual([]);
+ expect(readFileSync(join(ROOT, 'scripts/upgrade-matrix.ts'), 'utf8')).toContain('labels: [ISSUE_LABEL, AGENT_FILED_LABEL]');
+ for (const filer of ['scripts/nightly-issue.ts', 'scripts/lib/master-red.ts', 'scripts/ci-health-report.ts']) {
+ expect(readFileSync(join(ROOT, filer), 'utf8')).toContain('createIssue(client');
+ }
+ });
+});
diff --git a/test/scripts/nightly-issue.test.ts b/test/scripts/nightly-issue.test.ts
index d71668656e..9d984a8de5 100644
--- a/test/scripts/nightly-issue.test.ts
+++ b/test/scripts/nightly-issue.test.ts
@@ -73,7 +73,7 @@ describe('nightly-watch incidents', () => {
expect(plan.action).toBe('create');
const create = calls.find(c => c.method === 'POST' && c.path === 'repos/{repo}/issues')!;
expect(create.body!.title).toBe('Nightly red: Heavy Tests');
- expect(create.body!.labels).toEqual(['nightly-red']);
+ expect(create.body!.labels).toEqual(['nightly-red', 'agent-filed']);
const body = String(create.body!.body);
expect(body).toContain('| `Heavy tests` | `Bootstrap offline Docker e2e (placeholder)` | failure | no |');
expect(body).toContain('### Next step for the agent');
@@ -397,7 +397,7 @@ describe('master-red: push-to-master runs', () => {
expect(r.track).toBe('push');
expect(r.masterRed!.action).toBe('create');
const issue = masterIssue(w)!;
- expect(labelNames(issue)).toEqual(['master-red']);
+ expect(labelNames(issue)).toEqual(['master-red', 'agent-filed']);
const state = mrState(issue);
expect(state.status).toBe('red');
expect(state.first_red).toMatchObject({ run_id: T.r8320.id, sha: T.r8320.head_sha });
@@ -440,6 +440,7 @@ describe('master-red: push-to-master runs', () => {
expect(issue.comments.at(-1)).toContain('No merged repair PR is linked');
const flakes = w.labeled('flake');
expect(flakes.map(f => f.title).sort()).toEqual(['Flake: test/managed-lint.test.ts', 'Flake: test/pack-relation-direction-engine.test.ts', 'Flake: test/persistence-history-fixture.test.ts']);
+ for (const f of flakes) expect(labelNames(f)).toEqual(['flake', 'agent-filed']);
const rec = readJsonBlock<FlakeRecord>(flakes[0]!.body, FLAKE_MARKER)!;
expect(rec).toMatchObject({ schema: 'flake/v1', master_red_issue: issue.number, owner: 'agent on release duty', platform: 'linux' });
expect(rec.reproduce).toMatch(/^bun run test:stress test\/[\w./-]+\.test\.ts --iterations 10 --postgres$/);
@@ -928,7 +929,10 @@ describe('master-red: push-to-master runs', () => {
const open = both.issues.filter(i => i.title === 'Master red: Test' && i.state === 'open');
expect(open).toHaveLength(1);
expect(both.labeled('master-red')).toHaveLength(1);
- for (const twin of both.issues.filter(i => i.title === 'Master red: Test' && i.state === 'closed')) expect(twin.body).toContain(`Duplicate of #${open[0]!.number}`);
+ for (const twin of both.issues.filter(i => i.title === 'Master red: Test' && i.state === 'closed')) {
+ expect(twin.body).toContain(`Duplicate of #${open[0]!.number}`);
+ expect(labelNames(twin)).toEqual(['agent-filed']);
+ }
});
test('E2E Tests closes only when every previously failing test file was among the files a run executed and passed', async () => {