Garry's Opinionated OpenClaw/Hermes Agent Brain
Releasing & contributing (gbrain)
The full release + contributor process. CLAUDE.md keeps the ship-critical IRON RULES
inline (the Version-locations table, branch=workspace, post-ship /document-release,
the Privacy + Responsible-disclosure rules, PR-title-version-first, never-hand-roll-ship)
and points here for everything else. Before any ship, read this in full. Use /ship —
never hand-roll a release.
Pre-ship requirements
Before shipping (/ship) or reviewing (/review), always run the full test suite. Two equivalent paths:
Path A — local CI gate (recommended, v0.23.1+):
bun run ci:localruns the entire stack inside Docker: gitleaks (host), guards + typecheck, then 4-shard parallel unit + E2E against four pgvector containers plus a transaction-mode PgBouncer service (unit phase keepsDATABASE_URLunset;--no-shardfor the legacy sequential flow). Stronger than PR CI's four-file Tier 1 job; closer to what nightly Tier 1 catches. Spins up + tears down postgres automatically viadocker-compose.ci.yml. Override the host port withGBRAIN_CI_PG_PORT=5435 bun run ci:localif 5434 collides.bun run ci:local:diffchecks a doc-only diff in seconds (gitleaks plusscripts/ci-doc-checks.sh) and runs the full gate for any other diff: E2E narrowing is retired (see docs/TESTING.md "E2E selection").bun run ci:ubicloud(andci:ubicloud:diff) runs the same lanes across ten ephemeral Ubicloud VMs in about five minutes instead of one Docker host. NeedsUBICLOUD_API_KEYorUBICLOUD_API_TOKEN; see "Ubicloud fan-out" in docs/TESTING.md.
Path B — manual lifecycle (still supported):
bun test— unit tests (no database required)- Follow the "E2E test DB lifecycle" steps in
docs/TESTING.md to spin up the test DB, run
bun run test:e2e, then tear it down.
Both must pass. Do not ship with failing E2E tests. Do not skip E2E tests.
Always run typecheck before pushing. Neither bun test (the bun runner)
nor bun run test gates on types — bun run test is just
bash scripts/run-unit-parallel.sh (the sharded unit runner; no typecheck,
no shell pre-checks — see the test-tier table in docs/TESTING.md).
Three ways to actually gate on types:
bun run verify— runs the shell guard checks (privacy, jsonb, source-id, progress-to-stdout, …) plusbun run typecheckin parallel (scripts/run-verify-parallel.sh). Use this mid-branch.bun run typecheck— standalone TypeScript checking with native incremental analysis in ignorednode_modules/.cache/gbrain-typecheck.tsbuildinfo. Cold checks still analyze the whole project; repeated checks reuse compiler state while retaining input invalidation and diagnostics. See Testing.bun run ci:local— the full local CI gate from Path A.
The trap is: writing a new test, running bun test test/foo.test.ts,
seeing it pass, pushing — and CI's separate typecheck stage rejects an
invalid type literal that the runner accepted. Caught one of these
shipping the v0.23.2 round-trip E2E (type: 'reflection' is not a
member of PageType). Run bun run typecheck once before push, even
when only test files changed.
Generated artifacts
bun run regen:all regenerates every generated artifact offline and keyless
(schema bundles, error-code and agent-protocol blocks, harness reference, tool
catalog, skills manifest, metric glossary, CLI flag registry, plugin tree and
persona variants, structural-suites manifest, then llms.txt/llms-full.txt
last) and lists the files it changed. Run it before pushing whenever a
freshness gate could fail; a second run changes nothing. bun run verify
runs the read-only half, check:regen-all, whose failure names each stale
artifact and the same fix. Contract goldens (export surface, CLI goldens, SQL
text) are behavior pins, so regen:all leaves them alone unless you pass
--goldens, and each changed golden needs a reason in the PR body. Goldens
that need Postgres are named in its output with their own command.
Nightly-red issues
.github/workflows/nightly-watch.yml runs scripts/nightly-issue.ts after every
scheduled workflow and keeps one issue per workflow titled Nightly red: <workflow>
(label nightly-red). The issue body lists the failing job and step pairs, the
first red run and the commits since the last green one, the gh workflow run
re-check, and a "Next step for the agent" block plus a JSON block.
- Owner: the agent on release duty owns every open
nightly-redissue; Garry is the escalation for owner-only actions (secrets, repository settings). - Response within 24 hours: a repair PR, or a row in
.github/nightly-known-red.tsv(job, failure signature, the owning TODOS.md entry, a review-by date). The file holds at most 3 rows; fix one before adding another. A matching cell keeps the issue open with theknown-redlabel; a new failure in the same job opens a new incident; a passed review-by date asks for a fix again. - Closing: nightly-watch closes the issue only when a later scheduled run is green with complete evidence and every previously failing job executed. A skipped job never closes it.
- Re-check after a fix:
gh workflow run <workflow>.yml --ref master, thengh workflow run nightly-watch.yml -f run_id=<that scheduled run id>to preview (-f dry_run=true) or apply the issue update. - Dependency advisories: pull requests block on
bun auditonly when they changebun.lock,admin/bun.lock,patches/or a package.json dependency field, or carry thedependency-auditlabel; pushes and the nightly run always block, so a new upstream advisory shows up as one red nightly instead of every open PR.
Master-red issues
nightly-watch keeps one master-red issue per workflow (Master red: Test,
Master red: E2E Tests) for push-to-master runs; scheduled runs stay in
nightly-red. The body names each failing job, every failing test file with
its bun run test:stress reproduce line, and the suspect range (last green
push SHA, first red SHA, merged PRs). Labels, close rules and recovery steps:
CI red runbook.
- Owner: the agent on release duty owns every open
master-redissue, as fornightly-red; Garry is the escalation for owner-only actions. - First response within 1 hour: a comment or a linked repair PR. CI health measures it; nothing enforces it.
- Response: a repair PR whose body says
Fixes #<issue>. Known-red rows never apply to push runs. A master-red repair PR is fast-tracked when Garry asks. - Closing: nightly-watch closes the issue on a green push run where every
previously failing job (E2E Tests: every failing test file) ran and passed
with complete evidence. Without a merged repair PR it opens
flakeissues.
Merge queue
test.yml and e2e.yml carry merge_group triggers. They are inert until the
merge queue is enabled for master in the repository settings; check with
gh api repos/garrytan/gbrain/rulesets (or the branch protection page). Queue runs use
the pull-request profile against the queued merge commit: primary native scope,
the 2,500-write soak and the 10,001-page export scale; the E2E selector diffs the
queued commit against master.
- Without the queue, a release rebases onto the latest
origin/masterand re-runs the full CI (test.yml,e2e.yml, persistence-validation) immediately before merging, because a stale base can break master even when the PR was green. - With the queue on,
gh pr mergeonly enqueues the PR. Wait until the PR is actually merged (gh pr view <n> --json state,mergedAt) before tagging, announcing or starting dependent work.
Releases per batch
PRs no longer pick a version. A PR adds a changelog fragment and lands;
a release PR, opened a few times a day, gives every fragment that reached
master since the last release one version and writes all the stamps at once.
.gstack/ship-policy.json turns this on (changelog_fragments,
merge: "direct"), and gstack's /ship, receipt and land commands follow it.
How a PR lands. Every PR, release PRs included, lands on master as one
squashed commit whose subject is the PR title followed by (#<number>), so
git log --oneline master reads as a list of changes, with no
"Merge pull request" lines and none of a branch's own housekeeping commits.
The maintainer's merge step makes that commit; its body is the PR's
summary lines, and everyone else who wrote commits on the branch is
credited with a Co-authored-by: trailer. Only the landing squashes. A
branch brings master in with a merge commit and is never rebased or
force-pushed; history: "merge-only" in .gstack/ship-policy.json makes
/ship refuse a plan that would. Write the PR title as the one line a
reader of the log should see.
What a PR carries.
changelog.d/<branch-slug>.md: the PR's CHANGELOG entry with no version heading (bold one-line summary, then the itemized sections; voice rules below). /ship writes it. Front matter may sayimportant: security|regression|data-loss, where regression means one in a release that is on stable ("Daily stable check"); releases are PATCH only, soscripts/build-behavior-changes.ts(incheck:regen-all) refuses abump:line other thanpatchand any otherimportant:class. Format: changelog.d/README.md.- One
behavior-changes.d/<id>.mdfile per new upgrade-notice row, named in the fragment as<!-- behavior-change: <id> -->(behavior-changes.d/README.md). - A
deprecations.d/<id>.mdrecord before removing or renaming anything stable promises to keep (deprecations.d/README.md). - Its own schema migrations, numbered master's latest + 1 when written.
- Nothing else that carries a version: no edit to VERSION, the package.json
version, the plugin manifests, the BOOTSTRAP stamp, the plugin or template
trees, a released CHANGELOG section or a released
since:row. The PR title is plain words with no version in front.
The release PR. The merge lane runs gstack-release-stamp open. On a
fresh worktree of origin/master it sets VERSION to master's PATCH + 1,
runs bun scripts/release-restamp.ts --stamp-only <version> (every required row
of the CLAUDE.md "Version locations" table plus the plugin, variant and
template stamp lines; no fetch, no merge, no commit) and
bun scripts/build-behavior-changes.ts, which dates each pending
behavior-changes.d marker with the new version, in the order the fold
writes them, then folds every changelog.d fragment under one
## [<version>] - <date> heading and deletes the fragments. It
pushes release/<version> and opens the PR. The lane lands it with
gstack-ship-queue land --pr <n> --pin <head>, which accepts only a head
that is exactly the release stamp of master's tip. The release PR runs the
cheap tier; release.yml's ci-gate waits for the full Test and E2E push runs
on the release commit before anything publishes.
When releases happen. At 00:00, 06:00, 12:00 and 18:00 UTC the merge
lane opens a release when master holds at least one fragment and the last
release is 4 hours old or more. It also opens one right after landing a PR
whose fragment says important:, so an important fix is in a published
release within about an hour and can go to the stable channel (see "Daily
stable check").
What refuses a bad release. gstack's land refuses a release head that
changes anything but stamps, the CHANGELOG fold and release_outputs (here
src/core/behavior-changes.generated.ts, which it regenerates and compares
byte for byte). release.yml runs bun scripts/check-behavior-since.ts --stamped,
which refuses a release commit that still holds a changelog.d fragment,
a literal since: 'TBD' row or a stale behavior-change table, and fails
closed when .gstack/ship-policy.json is missing or unparsable. A cancelled
or skipped Test or E2E push run fails the gate with the gh run rerun <id>
to run; the gate no longer follows to a later commit with the same VERSION,
because between releases every master commit shares one, and a
workflow_dispatch refuses unless master HEAD is the release commit.
Migration collisions. Two open PRs can take the same migration number.
GitHub then reports the second one conflicting (both edit the generated
registry), and check:schema-migration-order fails on the merged tree.
bun run migrations:renumber renumbers the branch's own migrations after
master's latest (file name, export name and version: literal; the rest
must be token-identical) and regenerates the registry, as step 5 of
Release restamp describes. That makes a new head, which
needs a new full CI run. Migration numbers stay sequential for the reason
given there.
Converting an open stamped PR. A PR written before this switch still
carries a version. bun run release:unstamp merges origin/master, puts
every stamp back to master's version, moves the branch's CHANGELOG entry to
changelog.d/<branch-slug>.md and its appended plain-text
BEHAVIOR_CHANGES rows to behavior-changes.d/ (with their markers),
puts the notice file and its size-table row back to master's, and commits
once. The moved rows have no kind: yet: add one to each before pushing
(bun run check:public-surface refuses a new row without it). It refuses, with the fix, a branch with no entry of its own, one that
edits a released CHANGELOG section, one that carries other PRs' entries (land
or convert those first), and notice rows it can't move (rows without an id,
rows whose text is a function, edits other than appending). Plain
release:restamp refuses once master's policy says merge: "direct".
Why notice rows are files. Every PR used to append its row to the end of
one array in src/core/behavior-change-notice.ts, which also raised that
file's line in scripts/module-size-limits.tsv; those two lines were the
second-largest source of master conflicts after the stamps. Rows in their
own files, which the release never edits or deletes, touch neither line.
CHANGELOG + VERSION are branch-scoped
Under releases per batch a PR writes only its
changelog.d fragment; the voice rules below apply to that text, and the
version and placement rules apply to the release PR.
VERSION and CHANGELOG describe what THIS branch adds vs master, not how we got here. Every feature branch that ships gets its own version bump and CHANGELOG entry. The entry is product release notes for users; it is not a log of internal decisions, review rounds, or codex findings.
Write the CHANGELOG entry at /ship time, not during development. Mid-branch
iterations, review rounds (CEO/Eng/Codex/DX), and implementation detours belong
in the plan file at ~/.claude/plans/, not in the CHANGELOG. One unified entry
per branch, covering what the branch added vs the base branch.
Never edit a CHANGELOG entry that already landed on master. If master has v0.18.2.0 and your branch adds features, bump to the next PATCH version (v0.18.3.0, never MINOR) instead of editing master's v0.18.2.0. When merging master into your branch, master may bring new CHANGELOG entries above yours — push your entry above master's latest and verify:
- Does CHANGELOG have your branch's own entry separate from master's entries?
- Is VERSION higher than master's VERSION?
- Is your entry the topmost
## [X.Y.Z]entry? grep "^## \[" CHANGELOG.mdshows a contiguous version sequence?
If any answer is no, fix it before continuing.
CHANGELOG is for users, not contributors. Write like product release notes:
- Lead with what the user can now do that they couldn't before. Sell the capability.
- Plain language, not implementation details. "You can now..." not "Refactored the..."
- Never mention internal artifacts: plan file IDs, decision tags (D-CX-#, F-ENG-#), review rounds, codex findings, subcontractor credits. These are invisible to users.
- Put contributor-facing changes in a separate
### For contributorssection at the bottom. - Every entry should make someone think "oh nice, I want to try that."
What to omit:
- "Codex caught X that the CEO review missed" — private process detail.
- "D-CX-3 split errors/warnings" — tag is meaningless to users; name the feature instead.
- "Fix-wave PR #N supersedes #M" — supersede chains belong in PR bodies, not release notes.
- "215 new cases, 3 decisions applied, 7 reviews cleared" — these are planning-mode metrics.
What to keep:
- The user-facing change: what commands exist now, what flag was added, what behavior fixed.
- Numbers that mean something to the user: TTHW, commands that timed out before, detection counts.
- Upgrade instructions:
gbrain upgrade+ any manual step if needed. - Credit to external contributors when a community PR was incorporated.
Release restamp
Under releases per batch PRs do not restamp: the
release PR stamps, and release:restamp refuses. Its renumbering runs on its
own as bun run migrations:renumber, and bun run release:unstamp converts a
PR stamped the old way. The steps below describe the shared machinery.
bun run release:restamp makes a branch next-to-merge in one command. Run it
when your PR is next in the merge line, not earlier: the merge coordinator
merges one PR at a time, so restamping at that moment allocates the version
and migration numbers without races. Preview first with --dry-run, which
prints every planned edit, predicted merge conflict, migration renumbering
and the commit it would make, and changes nothing.
Say to your agent: "Restamp this branch onto master, it's next to merge."
- Refuses a dirty working tree (commit or
git stash -ufirst) and a failed fetch (offline:git fetch origin master, then rerun). - Captures the branch's CHANGELOG entry (the sections above the newest entry it shares with master; one entry per branch) and its migration inventory.
- Merges
origin/masterwith a merge commit. Version-only hunks in the stamp files,CHANGELOG.mdand generated files (migration registry,migrations/records.json,llms*.txt, plugin trees, the template repo,bun.lock) resolve mechanically; any other conflict stops with the file list. - Sets VERSION to master's
MAJOR.MINOR.(PATCH+1).0and rewrites every required row of the CLAUDE.md "Version locations" table: VERSION,package.json, the three plugin manifests, the BOOTSTRAP runbook stamp, the CHANGELOG entry (re-stamped on top of master's entries with today's date), branch-added TODOS lines naming the old version, and everysince: 'TBD'row insrc/core/behavior-change-notice.ts(development branches write their BEHAVIOR_CHANGES rows as TBD; the stamp gives them the new version, and a restamp moves the branch's own rows from the old version). - Renumbers the branch's own schema migrations (files
origin/masterdoes not have) consecutively from master's latest + 1, in their original order. It changes only the filename, theexport const v<NNN>name and theversion:literal, and proves the rest of the file is token-identical. Published migrations are never renumbered or edited; a branch file whose payload matches a migration master already published under another number (squash-merged or cherry-picked) stops with thegit rmfix. - Regenerates the migration registry,
migrations/records.json(when the branch has migrations),bun.lock, the bootstrap template repo and everythingbun run regen:allcovers. - Lists every line the branch added that still names an old migration number
(
v209,v209-name,migration 209,schema_version ... 209,version: 209) and stops: such a line may mean the moved migration or the published one that now owns the number, so it is never rewritten. Edit each line (an edited line is not listed again), or pass--accept-referenceswith--continuewhen a line means the published migration. - Runs the drift checks (version stamps and CHANGELOG agree, bootstrap
stamp, plugin tree, template repo, migration registry and order, no
since: 'TBD'row left:bun scripts/check-behavior-since.ts --stamped, and every master release heading still in CHANGELOG.md:bun scripts/check-changelog-headings.ts), commits once asv<new> chore(release): restamp onto master v<master>, and prints the old-to-new migration mapping with the collision-recovery steps, the golden-regeneration reason for the PR body, the PR title andbun run verify.
Every stop prints what happened, why, and the fix, saves its state, and ends
with bun run release:restamp --continue (after you fix it) or --abort
(back to the pre-run commit). --no-commit leaves the restamp edits staged.
A second run with nothing to change commits nothing. It renumbers source
only and never touches a database: if you applied an old number locally,
follow "Collision recovery" in TESTING.md
(disposable DB: rebuild and replay; retained data: explicit schema_version
reconciliation).
Why stamps are not derived at build time. Several readers take the
version from committed files with no build step: bun install -g github:garrytan/gbrain installs from source, gbrain bootstrap status
compares the BOOTSTRAP runbook stamp with the installed binary, the plugin
manifests and generated trees are published as committed, and release.yml
fires on a VERSION change. A build-time value would leave those copies
wrong, so the files stay stamped and one command rewrites them.
Why migration IDs stay sequential. A brain records one integer,
schema_version, and the runner applies every migration above it in order.
A migration numbered at or below master's latest is skipped forever on
current brains, which check:schema-migration-order rejects. Unordered IDs
(timestamps, hashes) would need a per-migration applied-set table and a
bookkeeping migration for every existing brain. Renumbering at merge time,
serialized by the merge coordinator, keeps the counter correct with no
schema change. Build on release:restamp rather than a second restamp tool.
CHANGELOG voice + release-summary format
IRON RULE: the CHANGELOG describes what the user gets, not how the work
happened. Nobody reading release notes cares that codex caught a bug, that
the plan went through CEO + eng review, that the migration was originally
numbered v68 and renumbered to v79 during master merge, or that two
review rounds caught architectural mistakes. The reader cares what
gbrain brainstorm does and how to use it. If a fact only exists because
of the development process, it does NOT belong in the CHANGELOG.
Specifically forbidden in CHANGELOG entries:
- Any mention of review processes (CEO review, eng review, codex review, plan-eng-review, outside voice, adversarial review, autoplan, /review).
- "What we caught and fixed before merging" sections. Bugs found pre-merge are not changes — they're things that didn't ship.
- Plan file references, plan IDs, plan decision tags (D1, D14, D-CDX-3).
- Migration version drama ("originally v68", "renumbered to v77", "claimed by parallel waves") — just say "Migration v79 adds X." If the user cares about migration ordering, they read the diff.
- Round counts, finding counts, decision counts ("25 findings across 2 rounds", "8 architectural decisions", "5/6 expansions accepted").
- Names of internal collaborators ("codex caught", "the reviewer flagged", "Claude noticed").
- "Plan + reviews" summary bullets. The plan lives in
~/.claude/plans/; if a future reader wants the backstory they can grep there. - Any wording that frames a shipped feature as a recovery from a planning mistake ("the first plan was wrong", "we corrected the approach", "the shipped version supersedes the original design").
Smell test: read the entry as a stranger who has never touched gbrain. If any sentence makes them think "why are you telling me this?", cut it. Every sentence in the release-summary AND in the itemized changes must answer one of three questions: What can I now do? How do I use it? What should I watch for after I upgrade?
Every version entry in CHANGELOG.md MUST start with a release-summary section in
the GStack/Garry voice — one viewport's worth of prose + tables that lands like a
verdict, not marketing. The itemized changelog (subsections, bullets, files) goes
BELOW that summary, separated by a ### Itemized changes header.
The release-summary section gets read by humans, by the auto-update agent, and by anyone deciding whether to upgrade. The itemized list is for agents that need to know exactly what changed.
Release-summary template
Iron rule: lead ELI10, get precise after. The first ~150 words of every entry must be readable by someone who does NOT know gbrain's internals. No file paths, no function names, no internal constants, no acronyms (no "RRF", no "knobsHash", no "MODE_BUNDLES", no "CDX-4"), no jargon that requires reading the codebase to parse. Lead with the user-visible behavior change, in everyday English, like you're explaining it to a smart engineer who has never opened the repo.
THEN, once the reader knows what shipped and why they'd care, drill into the precise details: real file paths, real function names, real config keys, real numbers. The precision part is required (the entry is also the technical record of what changed), but it lives AFTER the plain-English lead, never before it.
The shape:
- One-line bold headline. What changed for the user, in human English. No jargon. No internal terms. Example good: "Your search stops boosting weak pages just because they have a lot of links pointing at them." Example bad: "PostFusionOpts gains floorRatio; KNOBS_HASH_VERSION bumped 2→3."
- Plain-English opener (~3-5 sentences). Describe the problem this fixes in everyday terms. Pretend the reader has a brain full of meeting notes and people pages and wants to know if this release helps them. Concrete example beats abstract description.
- A "How to turn it on" or "How to use it" section with paste-ready commands. Real flags, real config keys. This is where precision starts.
- A "What you'd see in a concrete example" or "The X numbers that matter" section with a table. Use everyday-language column headers ("Page", "Match quality", "Has many backlinks?") even when the underlying mechanism is technical. The table teaches what the feature does without requiring the reader to understand how.
- A "What's safe to know about" or "Things to watch" section for caveats, side effects, cache invalidation, mid-deploy notes. Still in plain language.
- A "What we caught and fixed before merging" section if the work went through review (CEO/eng/codex/outside-voice). Translate review findings into plain English. "We caught a stale-cache bug" beats "knobsHash() did not include floorRatio in the v=2 hash input."
### Itemized changes(precision lives here). File paths, function names, types, constants, line numbers. This section is for engineers who need to know exactly what moved.
Voice rules (apply throughout):
- No em dashes (use commas, periods, "...").
- No AI vocabulary (delve, robust, comprehensive, nuanced, fundamental, etc.) or banned phrases ("here's the kicker", "the bottom line", etc.).
- Real numbers, real file names, real commands AFTER the ELI10 lead. Not "fast"
but "
30s on 30K pages." In the ELI10 lead, "fast enough that you won't notice" or "30 seconds even on a big brain." - Short paragraphs, mix one-sentence punches with 2-3 sentence runs.
- Connect to user outcomes: "the agent does ~3x less reading" beats "improved precision."
- Be direct about quality. "Well-designed" or "this is a mess." No dancing.
The smell test: if someone who has never opened gbrain reads the first 150 words and walks away knowing what shipped and whether they care, the entry passes. If they need to grep the codebase to follow along, rewrite the lead.
Canonical examples in this CHANGELOG: v0.35.6.0 (floor-ratio gate, written ELI10-lead-first), v0.34.4.0 (embed stale fix wave). Use those shapes when in doubt. Avoid the shape of entries that lead with internal constants or release mechanics; those exist in older history but should not be the model for new work.
Source material to pull from:
- CHANGELOG.md previous entry for prior context
- Latest
gbrain-evals/docs/benchmarks/[latest].mdfor headline numbers (sibling repo) - Recent commits (
git log <prev-version>..HEAD --oneline) for what shipped - Don't make up numbers. If a metric isn't in a benchmark or production data, don't include it. Say "no measurement yet" if asked.
Target length: ~250-350 words for the summary. Should render as one viewport.
"To take advantage of v[version]" block (required, v0.13+)
After the release-summary and BEFORE ### Itemized changes, every ## [X.Y.Z]
entry MUST include a human-readable self-repair block under the heading
## To take advantage of v[version].
Why: gbrain upgrade runs gbrain post-upgrade which runs gbrain apply-migrations.
This chain has a known weak link — upgrade.ts catches post-upgrade failures as
best-effort (so the binary still works). When that chain silently fails, users end
up with half-upgraded brains. The self-repair block gives them a paste-ready
recovery path; the v0.13+ ~/.gbrain/upgrade-errors.jsonl trail + gbrain doctor
integration close the loop.
Template (adapt the verify commands per release):
## To take advantage of v[version]
`gbrain upgrade` should do this automatically. If it didn't, or if `gbrain doctor`
warns about a partial migration:
1. **Run the orchestrator manually:**
```bash
gbrain apply-migrations --yes
Your agent reads
skills/migrations/v[version].mdthe next time you interact with it. [One sentence on whether headless agents need manual action, or whether the orchestrator already handled the mechanical side.]Verify the outcome:
[release-specific verify commands, e.g. `gbrain graph ... --depth 2`] gbrain statsIf any step fails or the numbers look wrong, please file an issue: https://github.com/garrytan/gbrain/issues with:
- output of
gbrain doctor - contents of
~/.gbrain/upgrade-errors.jsonlif it exists - which step broke
This feedback loop is how the gbrain maintainers find fragile upgrade paths. Thank you.
- output of
**Skip this block** for patches that are pure bug fixes with zero user-facing action
(rare). If the release has a schema migration, data backfill, or new feature the
user needs to verify, the block is required.
The v0.13.0 entry in CHANGELOG.md is the canonical example.
### Itemized changes (the existing rules)
Below the release summary, write `### Itemized changes` and continue with the
detailed subsections (Knowledge Graph Layer, Schema migrations, Security hardening,
Tests, etc.). Same rules as before:
- Lead with what the user can now DO that they couldn't before
- Frame as benefits and capabilities, not files changed or code written
- Make the user think "hell yeah, I want that"
- Bad: "Added GBRAIN_VERIFY.md installation verification runbook"
- Good: "Your agent now verifies the entire GBrain installation end-to-end, catching
silent sync failures and stale embeddings before they bite you"
- Bad: "Setup skill Phase H and Phase I added"
- Good: "New installs automatically set up live sync so your brain never falls behind"
- **Always credit community contributions.** When a CHANGELOG entry includes work from
a community PR, name the contributor with `Contributed by @username`. Contributors
did real work. Thank them publicly every time, no exceptions.
### Reference: v0.12.0 entry as canonical example
The v0.12.0 entry in CHANGELOG.md is the canonical example of the format. Match its
structure for every future version: bold headline, lead paragraph, "numbers that
matter" with BrainBench-style before/after table, "what this means" closer, then
`### Itemized changes` with the detailed sections below.
## Version migrations
Create a migration file at `skills/migrations/v[version].md` when a release
includes changes that existing users need to act on. The auto-update agent
reads these files post-upgrade (see `docs/guides/upgrades-auto-update.md`)
and executes them.
**You need a migration file when:**
- New setup step that existing installs don't have (e.g., v0.5.0 added live sync,
existing users need to set it up, not just new installs)
- New SKILLPACK section with a MUST ADD setup requirement
- Schema changes that require `gbrain init` or manual SQL
- Changed defaults that affect existing behavior
- Deprecated commands or flags that need replacement
- New verification steps that should run on existing installs
- New cron jobs or background processes that should be registered
**You do NOT need a migration file when:**
- Bug fixes with no behavior changes
- Documentation-only improvements (the agent re-reads docs automatically)
- New optional features that don't affect existing setups
- Performance improvements that are transparent
**The key test:** if an existing user upgrades and does nothing else, will their
brain work worse than before? If yes, migration file. If no, skip it.
Write migration files as agent instructions, not technical notes. Tell the agent
what to do, step by step, with exact commands. See `skills/migrations/v0.5.0.md`
for the pattern.
## Migration is canonical, not advisory
GBrain's job is to deliver a canonical, working setup to every user on upgrade.
Anything that looks like a "host-repo change" — AGENTS.md, cron manifests,
launchctl units, config files outside `~/.gbrain/` — is a GBrain migration
step, not a nudge we leave for the host-repo maintainer. Migrations edit host
files (with backups) to make the canonical setup real. Exceptions: changes
that require human judgment (content edits, renames that break semantics,
host-specific handler registration where shell-exec would be an RCE surface).
Everything mechanical ships in the migration.
**Test:** if shipping a feature requires a sentence that starts with "in
your AGENTS.md, add…" or "in your cron/jobs.json, rewrite…", the migration
orchestrator should be doing that edit, not the user.
**The exception is host-specific code.** For custom Minion handlers
(host-specific integrations like inbox sweeps or third-party API scanners), shipping them as a
data file the worker would exec is an RCE surface. Those get registered in
the host's own repo via the plugin contract (`docs/guides/plugin-handlers.md`);
the migration orchestrator emits a structured TODO to
`~/.gbrain/migrations/pending-host-work.jsonl` + the host agent walks the
TODOs using `skills/migrations/v0.11.0.md` — stays host-agnostic, still
canonical.
## Schema state tracking
`~/.gbrain/upgrade-state.json` tracks which recommended schema directories the user
adopted, declined, or added custom. The auto-update agent
(`docs/guides/upgrades-auto-update.md`) reads this during upgrades to suggest new schema additions without re-suggesting
things the user already declined. The setup skill writes the initial state during
Phase C/E. Never modify a user's custom directories or re-suggest declined ones.
## GitHub Actions SHA maintenance
All GitHub Actions in `.github/workflows/` are pinned to commit SHAs. Before shipping
(`/ship`) or reviewing (`/review`), check for stale pins and update them:
```bash
for action in actions/checkout oven-sh/setup-bun actions/upload-artifact actions/download-artifact softprops/action-gh-release gitleaks/gitleaks-action; do
tag=$(grep -r "$action@" .github/workflows/ | head -1 | grep -o '#.*' | tr -d '# ')
[ -n "$tag" ] && echo "$action@$tag: $(gh api repos/$action/git/ref/tags/$tag --jq .object.sha 2>/dev/null)"
done
If any SHA differs from what's in the workflow files, update the pin and version comment.
GitHub releases (binary assets + self-update) — #3521
.github/workflows/release.yml publishes a GitHub release automatically for
every VERSION bump that lands on master (trigger: push to master touching
VERSION, plus workflow_dispatch for a manual first run or repair). No
manual tag push is part of the ship flow — the workflow reads VERSION (the
single source of truth), mints tag v<VERSION> at the pushed commit, titles
the release the same, uses that version's CHANGELOG.md entry as the notes,
opened by one line per folded changelog fragment with the pull request that
added it (scripts/changelog-entry.sh --pr-list; falls back to a CHANGELOG
link if the entry is missing), and attaches the compiled binaries. Every one is published as a
pre-release; only the stable release is GitHub's "Latest" (Which release GitHub
calls Latest).
The executable build job pins Bun 1.4.4, the first release with the Brotli fix
for CVE-2026-111497 (#7373): a standalone binary embeds the Bun it was built
with, so never pin a build below it. The job verifies the Darwin artifact with
strict native codesign before publishing it. A source merge does not repair
already-published bad binaries; an affected release needs its own explicitly
approved recovery and asset verification. The template and plugin publishing
jobs pin the same Bun version.
Release CI gate
The ci-gate job (scripts/release-gate.ts) holds build, publication and the
latest-stable move until the push-to-master runs of Test and E2E Tests both
succeed on the release commit.
- Failed run: nothing is published and the job fails with the run and the
master-red issue. When the failure is outside the release commit (a flake),
re-run the failed run, then re-run the Release run (
gh run rerun <release run id>), which gates the same commit; otherwise land the repair and open the next release. - Cancelled or skipped run: nothing is published and the job fails with
gh run rerun <id>. Master push runs are keyed by commit, so a newer push no longer cancels them; and between releases many master commits share one VERSION, so the gate never follows to a later commit. - Backfill:
gh workflow run release.yml --ref mastergates and publishes master HEAD's VERSION only while HEAD is the release commit (the first-parent commit that last changed VERSION): between releases a later commit carries the same VERSION with unreleased changes, so the gate then refuses and names the re-run of the release commit's push Release run. Other refs are refused. - The gate waits up to 110 minutes, then fails naming the re-run of the Release run.
- Reused push run: a push run that reused a passed full-suite run of its
exact tree (master-push reuse)
publishes only with a readable
reuse.jsonnaming the same workflow, the push head and a valid source run. The gate prints the reused run per workflow and writestest_reused_run_id/e2e_reused_run_id(empty when that workflow ran in full); theci-gatejob exposes both as outputs.
The latest-stable tag
The final step of the release job force-advances the latest-stable tag to
the gated release commit (git push origin "+${RELEASE_SHA}:refs/tags/latest-stable").
latest-stable is the alpha channel's ref: the alpha update check follows it,
and so does anyone who pins it by hand. New users start on the stable tag
instead (Stable channel promotion): the README paste
block, the BOOTSTRAP_FOR_AGENTS.md fetch URL and
bun install -g github:garrytan/gbrain#stable name it (INSTALL_REF in
src/core/install-ref.ts), and only the stable promotion moves it. Both refs
move only to a release whose assets already published, so neither has a 404
window. scripts/check-bootstrap-tag.sh and bun run check:install-ref keep the
entry docs pinned to INSTALL_REF and refuse latest-stable there.
Because it moves ONLY after binaries + provenance attestation have fully published, a half-built release never advances it. If the tag-advance step alone fails, re-advance by hand (a full workflow re-run would skip — the release already exists with all assets):
git push origin "+refs/tags/v<VERSION>^{commit}:refs/tags/latest-stable"
Which release GitHub calls Latest
release.yml publishes every batch release with prerelease: true and
make_latest: false, so the Releases page and its Latest badge point at the
release installs follow. Each promotion (scripts/promote-stable.ts, from the
promote dispatch or the daily check) ends by marking the promoted release
Latest and clearing its pre-release flag. A forward promotion also replaces its
notes with a short summary of the behaviour changes since the previous stable
(upgradeSummary() in src/core/upgrade-summary.ts, the same summary
gbrain post-upgrade prints, left out when it alone would not fit), then every
CHANGELOG entry since it, newest first; the oldest entries drop with a link to the full CHANGELOG once the notes would pass
GitHub's 125,000-character limit. A rollback keeps the notes.
A forward promotion never moves Latest to an older release than the one it
marks now, because binaries released before this rule download
releases/latest as their update. So during the changeover Latest stays on
the newest release published before the rule, until stable passes it; that
promotion sets Latest, and from then on Latest is stable. backfill should
not be needed. A hand re-run of release.yml that would republish the current
stable release as a pre-release refuses; upload missing assets with
gh release upload instead.
Nothing that installs or updates gbrain reads GitHub's Latest: #stable and
gbrain upgrade follow the stable tag and its record; the alpha channel
(binary self-update included) reads VERSION at latest-stable and fetches
that exact release; the upgrade matrix counts pre-releases as releases; the
macOS signature check resolves its tag from latest-stable. Anyone who
downloads from releases/latest by hand now gets the stable release, about a
day behind the newest. People who watch the repository for releases are still
notified of pre-releases: GitHub has no setting to skip them.
scripts/release-channel.ts handles GitHub release state outside a promotion;
each command prints its plan and writes nothing without --apply:
backfill: every published release newer than the current stable becomes a pre-release and the stable release becomes Latest with rolled-up notes. It is also the repair when a promotion movedstablebut could not mark it Latest (the refusal names it).undo: every pre-release goes back to a normal release and the newest release becomes Latest, as before this rule. Revert the workflow change with it.preview-promotion [--version <v>]: the release a promotion would make Latest and the notes it would write.
Stable channel promotion
The stable channel, the clients' default since GBRA-224, is a slower ref than
latest-stable (the alpha channel): a release reaches it only after the
production-shaped soak passed on its exact git tree. A
maintainer promotes with .github/workflows/promote-stable.yml
(scripts/promote-stable.ts), or the scheduled
daily stable check promotes by rule; manual promotions and
rollbacks go through the same dispatch:
gh workflow run promote-stable.yml -f version=<VERSION> \
-f soak_run_url=https://github.com/<owner>/<repo>/actions/runs/<run id>
Refs.
refs/tags/stableis an annotated tag on the promoted release commit, moved only by this workflow. Clients peel it (refs/tags/stable^{}) and take thev<VERSION>tag on that commit. The same push commits the evidence recordstable.json(the tag fields plusknown_badandnot_promotable) to thestable-recordbranch; clients read only that file and refuse a record without its evidence (stable_invalid,src/core/stable-channel.ts).refs/tags/stable-v<VERSION>is an immutable annotated record created on a version's first promotion and never moved or deleted. Both carry the same message: a title line (gbrain, thenstable channel: v<VERSION>), then onekey: valueline each forversion,commit,tree,soak_run,scoreboard,matrix_run(only when the promotion named one;stable.jsonalways has the key,nullwithout one),promoted_by,promoted_at(UTC),previous(noneon the first promotion),rollbackandreason(-when empty).Inputs.
version(an existingv<VERSION>release tag),soak_run_url(the soak's Actions run URL, optionally/attempts/<n>),matrix_run_url(optional for a maintainer: a green upgrade matrix run on this release, see below),scoreboard_url(optional, defaults to the run URL),rollback(default false),reason(required with rollback) andwithdraw(versions added to the carried-forwardknown_badlist; clients on one are offered the current stable, even when older), andnot_promotablewithnot_promotable_reasonandnot_promotable_fixed_in, andnot_promotable_remove(see below).Not promotable. A release can soak clean and still be bad, when the evidence comes from outside the soak (a regression found on a large brain, say). Record it so the daily check never soaks or promotes it: dispatch this workflow for the current stable version and its own soak run (the re-record path: no tag moves), with
not_promotableset to the bad versions,not_promotable_reasonsaying why andnot_promotable_fixed_innaming the newer release that fixes them. The list is carried forward on every later record, andpromote()refuses a release on it. Clients never read it, so unlikewithdrawit offers nobody a different release. To take a release off the list (one listed by mistake), pass it innot_promotable_removethe same way. A reason is at most 500 characters (link the evidence), and a record larger than clients accept (64 KiB) is refused before anything is pushed. Usewithdrawonly for a release that was stable, so its installs move off it:gh workflow run promote-stable.yml -f version=<current stable> -f soak_run_url=<its soak run> \ -f not_promotable=<v1>,<v2> -f not_promotable_reason='<why>' -f not_promotable_fixed_in=<fix release>Who. Only an actor with the admin or maintain role; anyone else is refused. The one exception is the scheduled daily check below.
Soak run. The run must belong to this repository, be completed with conclusion
success, and run the workflow file named by theSTABLE_SOAK_WORKFLOWrepository variable (Settings → Secrets and variables → Actions → Variables; a bare file name likesoak.ymlor the full.github/workflows/soak.ymlpath). With the variable unset, every promotion is refused.Upgrade matrix run. When
matrix_run_urlis given, it must be a completed run of.github/workflows/upgrade-matrix.ymlfrom master's harness (a schedule or dispatch run, not a pull request's), with the full from-version set and no fault injection, whoseupgrade-matrix-receiptartifact names this release's tag, commit and tree and was written by that run's own commit, and it must be green; a red or foreign run is refused (scripts/stable-matrix.tsjudgeMatrixRun). A maintainer may promote without one, for example past an upgrade break the matrix found: the record then saysmatrix_run: nulland names the maintainer aspromoted_by. A scheduled promotion always names one.Published release. The tag's
VERSIONfile must say the version, and its GitHub release must exist and not be a draft, so binary clients can fetch the stable release.Exact tree. The soak run's head commit must have the same git tree as the release tag. A soak of another tree is refused with both trees and the run's head commit, even when the version string matches; soak the release itself, then promote that run.
Ordering and rollback. The version must be newer than the current stable (numeric 3- or 4-part comparison). Promoting the current stable again moves no tag: it writes
stable.jsonwhen the published record does not already name that release (see the backfill below), and is a no-op refusal otherwise.rollback=truewith areasonmoves stable to an older release, or back to one promoted before (its record tag already exists and is kept; without rollback an existing record tag is refused).One atomic push. The record tag,
stableand thestable-recordbranch land together or not at all,stableandstable-recordleased on the values the run read, so a concurrent move fails the run instead of being overwritten and a failed push leaves nothing to clean up before the re-run. Thepromote-stableconcurrency group runs one promotion at a time. The run's step summary lists the version, commit, tree, soak run, scoreboard, previous stable and rollback reason.Record backfill (one time, GBRA-346). Promotions made before this script wrote the evidence record moved
stablewith nostable.json, and a client that has the stable channel reads only the record, so it would reportstable_missing. The backfill is automatic on the first scheduled run of the daily stable check after the channel client lands: whenstable.jsonis missing or names another commit thanstable, that run writes the record for the current stable and stops. The manual dispatch still works, for example to write the record before the first release with the channel client publishes:git fetch --tags --force origin git for-each-ref --format='%(contents)' refs/tags/stable # version: and soak_run: lines gh workflow run promote-stable.yml [--ref <branch with this script>] \ -f version=<that version> -f soak_run_url=<that soak_run>The run re-checks the release and the soak run, requires the tag message to name the same release, tree and soak run, writes
stable.jsonfrom it (known_badcarried forward,withdrawaccepted) and pushes only the record branch, leasingstableunchanged. Running it from a branch before the client merges is safe: older clients never read the record. A record that already names the current stable makes the run a no-op refusal. Every later promotion, manual or scheduled, writes the record itself.
Daily stable check
.github/workflows/stable-daily.yml (scripts/stable-daily.ts) runs at 05:17 and 13:17 UTC
and keeps stable between one day and one week behind what matters:
- Reason first. It acts only when a merged PR labelled
stable:importantis in a published release but not in stable, or stable is more than 7 days old and a newer release exists (the weekly floor). Otherwise it does nothing. The merge lane sets the label at merge on a security fix, a data-loss fix or a fix for a regression in a release that is on stable (on a train PR, the train carries it); a label added after the merge counts too. Anything else, a regression only alpha has or a fix that unblocks one setup included, rides the weekly floor unless a maintainer promotes by hand. The rule: an important fix reaches stable within a day once it passes the full gate and soak; everything else rides a weekly cut; stable never sits more than seven days behind gated changes on master. It finds those PRs with GitHub's search, so the workflow's token needspull-requests: read; each run logs how many labelled PRs the search returned, and if the search sees no merged PR at all the check stops red and names that permission. - Soak first. The candidate is the newest release newer than stable whose
commit is on master and whose exact tree passed a successful
STABLE_SOAK_WORKFLOWrun with the integrity gates (privacy_leaks,read_errors,version_skew,residents_alive,session_refusals) passing in every cell; the latency gates stay record-only. The soak must be the full default one: both the 65 ms and 2 ms cells, at least 2 hours each, on the requested 600,000-page fixture, with privacy probes run and none erroring, so a smaller smoke dispatch never qualifies. On the important-only path the candidate must contain the fix. A release that was stable before (itsstable-v<version>record tag exists, so it was promoted and rolled back) or thatstable.jsonlists inknown_badornot_promotableis skipped, logged, and never promoted or soaked by the schedule, on the important path and the weekly floor alike; a maintainer re-promotes it by hand if it should return. It is promoted through the samepromote()as a manual promotion, so every check above still applies and the record'spromoted_byisschedule (.github/workflows/stable-daily.yml)with the reason inreason. With no qualifying soak it dispatches one soak on the newest release's tag (never while another soak runs, and never after a soak on any newer release failed to qualify: then a maintainer decides, and the check warns once stable is past the weekly floor), and a later run promotes it. - Upgrade matrix next. The soaked candidate also needs a green
upgrade matrix run on its exact tag and tree: a
schedule or dispatch run of master's harness with the full from-version set
(which includes every stable release in the window), checked as under
"Upgrade matrix run" above and again by
promote(), and recorded asmatrix_run. With no run yet it dispatches one on the candidate's tag (upgrade-matrix.ymlon master,candidate=v<version>), unless a matrix run is active, and a later run promotes; when it dispatches a soak on the newest release it dispatches the matrix on that release too. A red or foreign run holds stable with a warning and is never re-dispatched by the schedule: a maintainer fixes the break or promotes by hand. - Upgrade breaks hold. While the matrix's own break issue is open (the
one the nightly run opens with the
<!-- gbrain-upgrade-matrix:nightly -->marker; another issue with theupgrade-breaklabel holds nothing), the check holds stable, the weekly floor included, and dispatches nothing. The one way past it on the schedule is a releasedstable:importantfix whosechangelog.dfragment saysimportant: securityorimportant: data-loss, on a candidate whose matrix run fails on no from-version the issue names (itsred-fromline) and on nothing else; the record'sreasonnames the excused from-versions. Everything else waits for the nightly run to close the issue, or for a maintainer's promotion. - Who. A schedule event runs only the workflow file as merged on the
default branch, so a scheduled run promotes by rule without a maintainer. A
manual dispatch defaults to
dry_run(report only);dry_run=falseneeds an admin or maintainer before it dispatches a soak or promotes. It shares thepromote-stableconcurrency group, so it never races a manual promotion. - Record first. Before the reason check, when
stable.jsonis missing or names another commit thanstable, it writes the record for the current stable from the stable tag's message through the same re-promotion path as the manual backfill (no tag moves; release, exact tree, soak run and leases checked;known_badcarried forward) and stops; a dry run reportswould: backfill the record for v<version>. A record that already names stable changes nothing. The kill switch and a rollback pause skip it. - Stop it. Set the repository variable
STABLE_AUTO_PROMOTE=off(Settings → Secrets and variables → Actions → Variables). It also pauses by itself while the current stable record saysrollback: true, until a maintainer promotes by hand. - Roll back. Dispatch
promote-stable.ymlas a maintainer withversionset to the previous stable (git tag --list 'stable-v*' --sort=-creatordate, or the record'spreviousfield:git show stable --no-patch),soak_run_urlset to the soak run in that version's record tag,rollback=true, areasonandwithdrawset to the version you are rolling back from.withdrawputs it on the record'sknown_badlist, so clients that already installed it are offered the previous stable. Without it they stay on the bad release, because clients on stable never downgrade on their own. The daily check stays paused until the next manual promotion.
The publish-template job
After the release job, a publish-template job force-pushes the rendered
agent-workspace template repo (the GitHub "Use this template" door,
vars.TEMPLATE_REPO, default garrytan/gbrain-agent-template) from CI only —
no human pushes it by hand, so what adopters clone is exactly what this repo
reviewed. It is guarded three ways: the release above fully published; the
vendored tree templates/bootstrap/template-repo/ exists (skip, never fail,
if not); and the TEMPLATE_REPO_PAT secret is configured (skip if not).
Before pushing, it regenerates the template tree
(bun run scripts/generate-template-repo.ts) and byte-diffs it against the
vendored copy — a mismatch fails the job; regenerate + commit the vendored
tree (scripts/check-bootstrap-templates.sh runs the same diff offline in
bun run verify).
TEMPLATE_REPO_PAT scope: a fine-grained PAT with contents: write on
the template repository ONLY — no other repositories, no other permissions.
Configure it as a repo secret; when absent, template publishing is disabled
and the job skips cleanly.
Why every bump, not selective: the alpha update check reads VERSION at
latest-stable, and binary self-update downloads that exact release
(src/core/binary-self-update.ts). Any version without a release tells binary
installs an upgrade exists that self-update cannot apply.
Invariants:
- Asset names are a contract. The build matrix's
artifact:names must equal whatexpectedAssetName()insrc/core/binary-self-update.tsreturns (gbrain-darwin-arm64,gbrain-linux-x64today). Adding a platform means updating BOTH plus the version job's completeness check;test/release-workflow.test.tspins all of it. - Idempotent + self-repairing. The version job skips when a release for
v<VERSION>already exists with all expected assets; a partial release (tag but no release, or missing assets) is completed on re-run. Racing master pushes queue via thereleaseconcurrency group — a skipped intermediate version is fine, latest is what matters. - Historical tags are never rewritten. Old 3-segment versions keep their
history; every new 4-segment
VERSIONmints a fresh tag. - Permissions stay scoped.
contents: writelives on the release job only; everything else runs read-only. - Never advance
latest-stableon a partial release. The tag moves only as the final release-job step, after every asset has published. Manual re-advances must point at a fully publishedv<VERSION>release.
PR descriptions cover the whole branch
Pull request titles and bodies must describe everything in the PR diff against the
base branch, not just the most recent commit you made. When you open or update a
PR, walk the full commit range with git log --oneline <base>..<head> and write the
body to cover all of it. Group by feature area (schema, code, tests, docs) — not
chronologically by commit.
This matters because reviewers read the PR body to understand what's shipping. If the body only covers your last commit, they miss everything else and can't review properly. A 7-commit PR with a body that describes commit 7 is worse than no body at all — it actively misleads.
When in doubt, run gh pr view <N> --json commits --jq '[.commits[].messageHeadline]'
to see what's actually in the PR before writing the body.
Community PR wave process
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:
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 closes it with a link. The steps below are the
older batch procedure; steps 4 to 7 still apply to any rebuild PR.
- Categorize — group PRs by theme (bug fixes, features, infra, docs)
- 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.
- Collector branch — create a feature branch (e.g.
garrytan/fix-wave-N), cherry-pick or manually re-implement the best fixes from each PR. Do NOT merge PR branches directly — read the diff, understand the fix, and write it yourself if needed. - Test the wave — verify with
bun test && bun run test:e2e(full E2E lifecycle). Every fix in the wave must have test coverage. Runbun run audit:contributors <base>..<collector-head> --prs <manifest>to re-prove, per merged change and per open PR (trial-merged), that its tests fail with its product hunks reversed; the tool pins the PR heads intoprs.pinned.jsonso a rerun tests the same code, and its Markdown table keeps mechanical results apart from your verdicts (see Contributor audit). Paste the table into the wave PR body. - Security review — run
bun run wave-security-scan <base>..<collector-head>over the collector branch (the repeatable mechanical sweep). It ALARMS on newly-introduced obfuscation/eval in code, secrets found by gitleaks with the test/skills allowlist stripped, and any committedadmin/distchange (the bundle-backdoor artifact); new outbound endpoints, spawns, env reads, and dependency changes print as context. Exit 1 means "eyeball before shipping," not "unsafe" — read the ALARM rows and the context lists, and confirm each is benign. Link the result (or a one-line "clean") in the wave PR body. This is the standard's teeth: a wave PR body that claims "security reviewed" must have run this. It is a net, not a proof — a human still reads the diffs. - 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
and thank them. In the wave PR body, put each folded-in contributor PR on a
Supersedes #Nline and each fixed issue on aFixes #Nline: when the wave merges, the fix-wave closeout closes those PRs with a thank-you comment and GitHub closes the issues. WriteAddresses #NorRefs #Nfor anything only partly done, so it stays open. Close declined or duplicate PRs by hand, with the reason. - Ship as one PR — single PR to master with all attributions preserved via
Co-Authored-By:trailers. Include a summary of what merged and what closed.
Community PR guardrails:
- Always AskUserQuestion before accepting commits that touch voice, tone, or promotional material (README intro, CHANGELOG voice, skill templates).
- Never auto-merge PRs that remove YC references or "neutralize" the founder perspective.
- Preserve contributor attribution in commit messages.
Fix-wave gate
.github/workflows/fix-wave-gate.yml (job contributor-gate) fails every PR into
master unless its head repository is garrytan/gbrain or the maintainer-override
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: 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
either cannot change its own result. It reads only the event payload and the PR
timeline, never PR code, with permissions: {} at the top, pull-requests: read
for the gate and pull-requests: write only for the comment job. A null head
repository (deleted fork) fails closed. The check re-runs on opened, edited,
reopened, synchronize, labeled and unlabeled.
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
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
log prints a notice naming who applied the label, when, and the timeline event id,
and the step summary repeats it.
Turning it on (repository settings, maintainer only). The guard is active only
after this step; until then the check is advisory. Settings → Rules → Rulesets (or
Settings → Branches → the master protection rule) → Require status checks to pass →
add contributor-gate with GitHub Actions as the source → save. The check must have
run once on any PR before GitHub offers it in the picker.
Residual risk. A same-repo branch (capy/* or garrytan/*) that carries
contributor commits passes by design. Keeping contributor work inside a revised fix
wave on those branches stays a policy rule, enforced by review, not by this check.
Fix-wave closeout
.github/workflows/fix-wave-closeout.yml (job close-superseded) runs when a PR
into master closes. If it merged and its head repository is garrytan/gbrain,
scripts/fix-wave-closeout.ts reads the merged PR's body and closes every open pull
request named on a Supersedes #N line (Supersedes #5085, - Supersedes #5089, #5096 and #5107, **Supersedes:** #5113). Only the list right after the keyword
counts, so Supersedes #5140, which conflicts with #5000 closes #5140 alone. Each
closed PR gets one comment, keyed by <!-- fix-wave-closeout -->, that thanks the
contributor, links the wave, and says the work landed with credit when the wave body
contains Contributed by @<their handle>. Numbers that are issues or already-closed
PRs are skipped. A failed close is a warning in the run log, and the step summary
lists every number with what happened to it. One run closes at most 50 PRs.
Issues need nothing extra: Fixes #N in the same body closes them through GitHub.
Before this workflow, contributor PRs stayed open after their wave merged, which is
most of why the open-PR count grew. To preview a body locally without writing
anything, save the event payload and run
bun scripts/fix-wave-closeout.ts --event <payload.json> --dry-run.
Like the gate, it uses pull_request_target: the workflow and script come from the
default branch, it sparse-checks-out only the script, and it never checks out or
runs PR code. Permissions are {} at the top and contents: read plus
pull-requests: write for the one job.
Checking out PRs from garrytan-agents
garrytan-agents is the AI-authored PR account and is NOT a collaborator on
this repo. Its PRs live in a fork, so GitHub Actions triggered by
pull_request events on those PRs do not receive base-repo secrets. Any CI
job that needs ANTHROPIC_API_KEY, OPENAI_API_KEY, or similar will fail
with empty-env auth errors, regardless of what's set on the base repo. This
is a GitHub security default, not a config bug.
When the user says "check out " and the PR is from garrytan-agents
(or any other non-collaborator fork), move the branch into the base repo
before running CI:
gh pr checkout <N>— pull down the fork's branch. Note the PR number and head branch name (gh pr view <N> --json headRefName --jq .headRefName).git push origin HEAD:<branch-name>— push the same branch to the base repo (origin points atgarrytan/gbrain, not the fork). This is the move that gives CI access to secrets.gh pr close <N> --comment "moving to base-repo branch for secret access"— close the fork PR so the queue stays clean.gh pr create --base master --head <branch-name>— open the replacement PR from the base-repo branch. Preserve the original PR's title and body verbatim (gh pr view <N> --json title,body); contributor attribution moves to aCo-Authored-By:trailer if needed.
Why this over alternatives: adding garrytan-agents as a collaborator, or
flipping the repo-wide "send secrets to fork PRs" toggle, both broaden
secret distribution to every fork PR from that account or any fork. Moving
the branch keeps secret scope tight to just the one PR being shipped.
ClawHub bundle plugin publish (manual)
openclaw.plugin.json makes this repository a ClawHub bundle plugin (see
docs/mcp/OPENCLAW.md). Publishing a new version to ClawHub is
a manual step outside release.yml, run from a clean checkout of the release
tag by an owner with an authenticated clawhub CLI:
bun run prepublish:clawhub # bun run build:all: bin/gbrain-darwin-arm64 + bin/gbrain-linux-x64
bun run publish:clawhub # clawhub package publish . --family bundle-plugin
build:all compiles only those two targets; the full binary matrix ships
through the GitHub release job above. gbrain upgrade never runs
clawhub update gbrain (#8464): that command updates a ClawHub skill named
gbrain from any publisher, and we publish none, so it would install someone
else's package.
Plugin dist tree (codex/claude lanes)
The committed plugin/ and plugin-variants/ trees embed the VERSION stamp
(the variants' generated plugin manifests carry it too), so a release bump
drifts them. After bumping VERSION/package.json, run bun run scripts/generate-plugin-tree.ts --out plugin --variants-out plugin-variants
and stage plugin/ + plugin-variants/ + skills/plugin-lanes.json.
scripts/check-plugin-tree.sh (in bun run verify) and the release
publish-codex-plugin job both fail on drift.
When personas change in skills/plugin-lanes.json#personas, also hand-edit
.claude-plugin/marketplace.json: the variant entries must match the
personas block exactly (test/codex-plugin-manifest.test.ts pins the
mapping, so a persona added without a marketplace entry fails the suite).