Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix: catch notice ids that would break a release, and re-run the release run instead of dispatching on master
garrytanc3e1c3d339d6
diff --git a/behavior-changes.d/README.md b/behavior-changes.d/README.mdindex e9675ced1d..a9d0620c96 100644--- a/behavior-changes.d/README.md+++ b/behavior-changes.d/README.md@@ -9,7 +9,7 @@ line and nobody picks a version before the release.1. Write the notice text, one paragraph of plain text (at most 2,000characters, no markup), in `behavior-changes.d/<id>.md`. The id is- lowercase letters, digits and `_`, unique across the table, for example+ lowercase letters, digits and `_`, starting with a letter, unique across the table, for example`sync_holds_unparsable_8123`.2. Name the id in your PR's changelog fragment (`changelog.d/<slug>.md`)on its own line:@@ -19,16 +19,20 @@ line and nobody picks a version before the release.```That is all. `bun run verify` (check:regen-all) refuses a fragment with no-marker, a marker with no fragment, a duplicate id and an over-long text.+marker, a marker with no fragment, a duplicate id (including an id marked+twice among unreleased changes, or marked again after its release) and an+over-long text.## What the release does-The release (`gstack-release-stamp open`) folds every changelog fragment-into one CHANGELOG section under the new version, so each marker now sits-under that version's heading. It then runs `bun scripts/build-behavior-changes.ts`,-which writes src/core/behavior-changes.generated.ts: every fragment whose-marker sits in a released section, with that section's version as its-`since`. The files here are never edited or deleted, so the release changes+The release (`gstack-release-stamp open`) writes the new VERSION, runs+`bun scripts/build-behavior-changes.ts`, then folds every changelog fragment+into one CHANGELOG section under that version. While VERSION is newer than+the CHANGELOG's top release, the builder dates the pending markers with it,+in the order the fold writes them (fragments by path, then `## [Unreleased]`),+so its output equals what it generates once the markers sit under the new+heading. It writes src/core/behavior-changes.generated.ts: every fragment+whose marker is released, with that release as its `since`. The files here are never edited or deleted, so the release changesonly version stamps, the CHANGELOG and that generated file, which gstack'sland check regenerates byte for byte.diff --git a/docs/RELEASING.md b/docs/RELEASING.mdindex a6a4a53433..3abf6a6c1e 100644--- a/docs/RELEASING.md+++ b/docs/RELEASING.md@@ -161,13 +161,13 @@ master since the last release one version and writes all the stamps at once.**The release PR.** The merge lane runs `gstack-release-stamp open`. On afresh worktree of `origin/master` it sets VERSION to master's PATCH + 1,-folds every `changelog.d` fragment under one `## [<version>] - <date>`-heading and deletes the fragments, then runs-`bun scripts/release-restamp.ts --stamp-only <version>` (every required row+runs `bun scripts/release-restamp.ts --stamp-only <version>` (every required rowof the CLAUDE.md "Version locations" table plus the plugin, variant andtemplate stamp lines; no fetch, no merge, no commit) and-`bun scripts/build-behavior-changes.ts`, which dates each-`behavior-changes.d` row whose marker now sits under the new heading. It+`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. Itpushes `release/<version>` and opens the PR. The lane lands it with`gstack-ship-queue land --pr <n> --pin <head>`, which accepts only a headthat is exactly the release stamp of master's tip. The release PR runs the@@ -646,15 +646,20 @@ The `ci-gate` job (`scripts/release-gate.ts`) holds build, publication and thesucceed on the release commit.- **Failed run:** nothing is published and the job fails with the run and the- master-red issue. After master is green again, publish the current VERSION- with `gh workflow run release.yml --ref master`.+ 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 pushno longer cancels them; and between releases many master commits share oneVERSION, so the gate never follows to a later commit.- **Backfill:** `gh workflow run release.yml --ref master` gates and publishes- master HEAD's VERSION. Other refs are refused.-- The gate waits up to 110 minutes, then fails with the backfill command.+ master HEAD's VERSION, so use it only while HEAD is the release commit:+ between releases a later commit carries the same VERSION with unreleased+ changes. 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 itsexact tree ([master-push reuse](ci-event-parity.md#master-push-reuse))publishes only with a readable `reuse.json` naming the same workflow, thediff --git a/scripts/build-behavior-changes.ts b/scripts/build-behavior-changes.tsindex a7b14628d3..8f35801e7e 100644--- a/scripts/build-behavior-changes.ts+++ b/scripts/build-behavior-changes.ts@@ -28,7 +28,7 @@ export const CHANGELOG_FRAGMENT_DIR = 'changelog.d';export const OUT = 'src/core/behavior-changes.generated.ts';export const NOTICE_FILE = 'src/core/behavior-change-notice.ts';export const MARKER = /<!--\s*behavior-change:\s*([^\s]+)\s*-->/g;-export const ID = /^[a-z0-9][a-z0-9_]{2,95}$/;+export const ID = /^[a-z][a-z0-9_]{2,95}$/;const NOTICE_CAP = 2_000;const DOCS = 'behavior-changes.d/README.md';@@ -72,7 +72,7 @@ export function build(root: string): Built {const stamping = !!version && (!top || cmp(version, top) > 0);const pendingFiles = existsSync(join(root, CHANGELOG_FRAGMENT_DIR))? readdirSync(join(root, CHANGELOG_FRAGMENT_DIR)).filter(f => f.endsWith('.md') && f !== 'README.md').sort() : [];- const pending = [...releases.filter(r => !r.version).flatMap(r => r.ids), ...pendingFiles.flatMap(f => markers(read(root, join(CHANGELOG_FRAGMENT_DIR, f))))];+ const pending = [...pendingFiles.flatMap(f => markers(read(root, join(CHANGELOG_FRAGMENT_DIR, f)))), ...releases.filter(r => !r.version).flatMap(r => r.ids)];const sinceOf = new Map<string, string>();const order: string[] = [];const mark = (id: string, v: string) => {@@ -80,14 +80,20 @@ export function build(root: string): Built {sinceOf.set(id, v); order.push(id);};for (const r of released) for (const id of r.ids) mark(id, r.version!);- const pendingIds = new Set(pending);- if (stamping) for (const id of pending) if (!sinceOf.has(id)) mark(id, version);+ const pendingIds = new Set<string>();+ for (const id of pending) {+ if (pendingIds.has(id)) problems.push(`${id} is marked twice among the unreleased changes (changelog.d and ## [Unreleased]); the release would mark it twice`);+ else if (sinceOf.has(id)) problems.push(`${id} is marked again after release ${sinceOf.get(id)}; a released id is never marked again`);+ pendingIds.add(id);+ }+ for (const id of new Set([...sinceOf.keys(), ...pendingIds])) if (!ID.test(id)) problems.push(`the marker <!-- behavior-change: ${id} --> is not an id: lowercase letters, digits and _, starting with a letter (3-96 characters)`);+ if (stamping) for (const id of pendingIds) if (!sinceOf.has(id)) mark(id, version);const files = existsSync(join(root, FRAGMENT_DIR)) ? readdirSync(join(root, FRAGMENT_DIR)).filter(f => f !== 'README.md').sort() : [];const texts = new Map<string, string>();for (const f of files) {const id = f.replace(/\.md$/, '');- if (!f.endsWith('.md') || !ID.test(id)) { problems.push(`${FRAGMENT_DIR}/${f}: a fragment is named <id>.md, the id lowercase letters, digits and _ (3-96 characters)`); continue; }+ if (!f.endsWith('.md') || !ID.test(id)) { problems.push(`${FRAGMENT_DIR}/${f}: a fragment is named <id>.md, the id lowercase letters, digits and _, starting with a letter (3-96 characters)`); continue; }const text = read(root, join(FRAGMENT_DIR, f)).trim().replace(/\s*\n\s*/g, ' ');if (!text) problems.push(`${FRAGMENT_DIR}/${f} is empty`);else if (text.length > NOTICE_CAP) problems.push(`${FRAGMENT_DIR}/${f} is ${text.length} characters; the notice renders at most ${NOTICE_CAP}`);diff --git a/scripts/release-gate.ts b/scripts/release-gate.tsindex 29cce07c23..6aa801f9b0 100644--- a/scripts/release-gate.ts+++ b/scripts/release-gate.ts@@ -18,10 +18,11 @@* master commit with the same VERSION may carry unreleased changes, so the* gate never publishes another commit in the release commit's place;* - still running, or not created yet: wait, up to --timeout-minutes, then- * fail with the dispatch backfill command.+ * fail naming the re-run of this Release run, which gates the same commit.*- * A workflow_dispatch backfill runs the same gate for master's HEAD, so it- * publishes the current VERSION once master's CI for HEAD is green. Writes+ * A workflow_dispatch backfill runs the same gate for master's HEAD, so it is+ * right only while HEAD is the release commit; every failure names the re-run+ * of the Release run instead. Writes* `publish=true|false` and `sha=<commit>` to --output (GITHUB_OUTPUT).** Master-push reuse (scripts/ci-reuse.ts, docs/ci-event-parity.md#master-push-reuse):@@ -42,6 +43,7 @@ import { fetchArtifactJson, restClient, type GitHubClient } from './lib/gh-issueexport const GATED = [{ file: 'test.yml', name: 'Test', key: 'test' }, { file: 'e2e.yml', name: 'E2E Tests', key: 'e2e' }] as const;export const DOCS = 'docs/RELEASING.md#release-ci-gate';const RED = new Set(['failure', 'timed_out', 'startup_failure', 'action_required']);+const RERUN = `re-run this Release run (gh run rerun ${process.env.GITHUB_RUN_ID ?? '<this Release run id>'}), which gates the same release commit; a dispatch on master would gate master HEAD instead`;export interface GateRun { id: number; run_number: number; run_attempt: number; status: string; conclusion: string | null; head_sha: string; head_branch: string; event: string; html_url?: string }export interface ReusedRun { run_id: number; run_attempt: number; sha: string }@@ -68,7 +70,7 @@ export async function evaluate(deps: GateDeps, sha: string, version: string): Prreturn {kind: 'fail', sha,why: `${failed.wf.name} run ${failed.run!.id} (${failed.run!.html_url ?? `run ${failed.run!.run_number}`}) ended ${failed.run!.conclusion} on ${sha.slice(0, 12)}, so v${version} is not published and latest-stable does not move. Releases publish only commits master CI passed.`,- next: `Repair master (the open "Master red: ${failed.wf.name}" issue names the failing tests; docs/RELEASING.md#master-red-issues). Once a later push-to-master run of Test and E2E Tests is green, publish the current VERSION with: gh workflow run release.yml --ref master`,+ next: `Repair master (the open "Master red: ${failed.wf.name}" issue names the failing tests; docs/RELEASING.md#master-red-issues). If the failure is outside the release commit, re-run that run (gh run rerun ${failed.run!.id}) and, once it is green, ${RERUN}. Otherwise land the repair and open the next release.`,};}const cancelled = runs.find(r => r.run && r.run.status === 'completed' && (r.run.conclusion === 'cancelled' || r.run.conclusion === 'skipped'));@@ -76,7 +78,7 @@ export async function evaluate(deps: GateDeps, sha: string, version: string): Prreturn {kind: 'fail', sha,why: `${cancelled.wf.name} run ${cancelled.run!.id} on ${sha.slice(0, 12)} ended ${cancelled.run!.conclusion}, so v${version} is not published. Master push runs are keyed by commit, so a newer push never cancels them, and a later master commit may carry unreleased changes under the same VERSION, so the gate never publishes one in its place.`,- next: `Re-run it (gh run rerun ${cancelled.run!.id}); once Test and E2E Tests are green on ${sha.slice(0, 12)}: gh workflow run release.yml --ref master`,+ next: `Re-run it (gh run rerun ${cancelled.run!.id}); once Test and E2E Tests are green on ${sha.slice(0, 12)}, ${RERUN}`,};}const pending = runs.filter(r => !r.run || r.run.status !== 'completed');@@ -87,7 +89,7 @@ export async function evaluate(deps: GateDeps, sha: string, version: string): Prreturn {kind: 'fail', sha,why: `${unproven.wf.name} run ${unproven.run.id} reused an earlier full-suite run on ${sha.slice(0, 12)}, but its reuse record cannot name that run (${unproven.prov.problem}), so v${version} is not published. A release names the run that proved its tree.`,- next: `Re-run that push run (gh run rerun ${unproven.run.id}); it decides reuse again and records it, or runs the full suite. Once it is green: gh workflow run release.yml --ref master`,+ next: `Re-run that push run (gh run rerun ${unproven.run.id}); it decides reuse again and records it, or runs the full suite. Once it is green, ${RERUN}`,};}const sources: Source[] = proven.map(p => ({ workflow: p.wf.name, key: p.wf.key, run_id: p.run.id, ...('run_id' in p.prov ? { reused: { run_id: p.prov.run_id, run_attempt: p.prov.run_attempt, sha: p.prov.sha } } : {}) }));@@ -126,7 +128,7 @@ export async function gate(deps: GateDeps, opts: { sha: string; version: string;const v = await evaluate(deps, opts.sha, opts.version);if (v.kind !== 'wait') return v;if (now() >= deadline) {- return { kind: 'fail', sha: v.sha, why: `Test and E2E Tests did not finish on ${v.sha.slice(0, 12)} within ${Math.round(opts.timeoutMs / 60_000)} minutes (${v.why})`, next: 'When they finish green, publish with: gh workflow run release.yml --ref master' };+ return { kind: 'fail', sha: v.sha, why: `Test and E2E Tests did not finish on ${v.sha.slice(0, 12)} within ${Math.round(opts.timeoutMs / 60_000)} minutes (${v.why})`, next: `When they finish green, ${RERUN}` };}opts.log(`[release-gate] waiting: ${v.why}`);await sleep(opts.pollMs);@@ -159,12 +161,12 @@ if (import.meta.main) {write(true, v.sha);if (output) appendFileSync(output, reuseOutputs(v.sources));} else {- console.log(`::error::Release v${version} not published: ${v.kind === 'fail' ? v.why : 'gate ended while waiting'}. Next: ${v.kind === 'fail' ? v.next : 'gh workflow run release.yml --ref master'}. Docs: ${DOCS}`);+ console.log(`::error::Release v${version} not published: ${v.kind === 'fail' ? v.why : 'gate ended while waiting'}. Next: ${v.kind === 'fail' ? v.next : RERUN}. Docs: ${DOCS}`);write(false, v.sha);process.exit(1);}} catch (e) {- console.log(`::error::Release v${version} not published: the CI gate could not read the actions API (${e instanceof Error ? e.message : String(e)}). Why: publication waits for Test and E2E Tests success on the release commit. Fix: re-run this workflow (gh run rerun <this run id>) or gh workflow run release.yml --ref master. Docs: ${DOCS}`);+ console.log(`::error::Release v${version} not published: the CI gate could not read the actions API (${e instanceof Error ? e.message : String(e)}). Why: publication waits for Test and E2E Tests success on the release commit. Fix: ${RERUN}. Docs: ${DOCS}`);write(false, sha);process.exit(1);}diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.tsindex 828e5884dc..c4bbd1a4c7 100644--- a/src/core/behavior-change-notice.ts+++ b/src/core/behavior-change-notice.ts@@ -224,7 +224,7 @@ const DOCTOR_ARGV = ['gbrain', 'doctor', '--only', BEHAVIOR_NOTICE_CODE, '--jsontype ChangeText = string | ((chain: ChainDisclosure | null, remote: boolean) => string | null);/** A function row's release: the version whose CHANGELOG section marks its id (behavior-changes.d/README.md), 'TBD' until a release does. */-const releasedIn = (id: string): string => BEHAVIOR_CHANGE_RELEASES[id] ?? 'TBD';+const releasedIn = (id: string): string => (Object.hasOwn(BEHAVIOR_CHANGE_RELEASES, id) ? BEHAVIOR_CHANGE_RELEASES[id]! : 'TBD');/*** Every disclosed behavior change, with the release that introduced it; never edit a shipped `since`. A new plain-textdiff --git a/test/scripts/build-behavior-changes.test.ts b/test/scripts/build-behavior-changes.test.tsindex 73ebcabcb8..f20c7290ee 100644--- a/test/scripts/build-behavior-changes.test.ts+++ b/test/scripts/build-behavior-changes.test.ts@@ -107,9 +107,9 @@ describe('build()', () => {});const { problems } = build(root);expect(problems.sort()).toEqual([- 'behavior-changes.d/Bad-Name.md: a fragment is named <id>.md, the id lowercase letters, digits and _ (3-96 characters)',+ 'behavior-changes.d/Bad-Name.md: a fragment is named <id>.md, the id lowercase letters, digits and _, starting with a letter (3-96 characters)','behavior-changes.d/no_marker_abc.md has no <!-- behavior-change: no_marker_abc --> marker in a changelog.d fragment or the CHANGELOG, so no release would disclose it',- 'behavior-changes.d/notes.txt: a fragment is named <id>.md, the id lowercase letters, digits and _ (3-96 characters)',+ 'behavior-changes.d/notes.txt: a fragment is named <id>.md, the id lowercase letters, digits and _, starting with a letter (3-96 characters)',`behavior-changes.d/old_table_row.md repeats the id of a row in ${NOTICE_FILE}`,'behavior-changes.d/too_long_abc.md is 2001 characters; the notice renders at most 2000',`the marker <!-- behavior-change: no_fragment_abc --> names no behavior-changes.d/no_fragment_abc.md and no function row dated releasedIn('no_fragment_abc')`,@@ -174,6 +174,53 @@ describe('build()', () => {});expect(build(root).problems).toEqual(['twice_row_abc is marked in two releases (0.1.0.0 and 0.1.1.0)']);});++ test('a marker repeated among unreleased changes, or marked again after its release, is refused on the PR tree', () => {+ const twoFragments = build(tree({+ VERSION: '0.1.0.0\n',+ 'CHANGELOG.md': changelog(section('0.1.0.0', 'First.')),+ 'behavior-changes.d/dup_row_abc.md': 'Dup.\n',+ 'changelog.d/a.md': `${marker('dup_row_abc')}\n`,+ 'changelog.d/b.md': `${marker('dup_row_abc')}\n`,+ }));+ expect(twoFragments.problems).toEqual(['dup_row_abc is marked twice among the unreleased changes (changelog.d and ## [Unreleased]); the release would mark it twice']);+ const remarked = build(tree({+ VERSION: '0.1.0.0\n',+ 'CHANGELOG.md': changelog(section('0.1.0.0', marker('old_row_abc'))),+ 'behavior-changes.d/old_row_abc.md': 'Old.\n',+ 'changelog.d/a.md': `${marker('old_row_abc')}\n`,+ }));+ expect(remarked.problems).toEqual(['old_row_abc is marked again after release 0.1.0.0; a released id is never marked again']);+ });++ test('an id starting with a digit is refused, so the generated map never holds an unquoted numeric key', () => {+ const root = tree({+ VERSION: '0.1.0.0\n',+ 'CHANGELOG.md': changelog(section('0.1.0.0', 'First.')),+ 'behavior-changes.d/8123_sync.md': 'Sync.\n',+ 'changelog.d/a.md': `${marker('8123_sync')}\n`,+ });+ expect(build(root).problems).toEqual([+ 'the marker <!-- behavior-change: 8123_sync --> is not an id: lowercase letters, digits and _, starting with a letter (3-96 characters)',+ 'behavior-changes.d/8123_sync.md: a fragment is named <id>.md, the id lowercase letters, digits and _, starting with a letter (3-96 characters)',+ "the marker <!-- behavior-change: 8123_sync --> names no behavior-changes.d/8123_sync.md and no function row dated releasedIn('8123_sync')",+ ]);+ });++ test('with [Unreleased] markers on the base, the release in progress orders ids as the fold writes them', () => {+ const shared = {+ 'behavior-changes.d/frag_row_abc.md': 'From a fragment.\n',+ 'behavior-changes.d/open_row_abc.md': 'From [Unreleased].\n',+ };+ const released = section('0.1.0.0', 'First.');+ const frag = `**Fragment.**\n\n${marker('frag_row_abc')}`;+ const open = `**Open.**\n\n${marker('open_row_abc')}`;+ const inProgress = build(tree({ ...shared, 'changelog.d/a.md': `${frag}\n`, VERSION: '0.1.1.0\n', 'CHANGELOG.md': changelog(`## [Unreleased]\n\n${open}\n`, released) }));+ const folded = build(tree({ ...shared, VERSION: '0.1.1.0\n', 'CHANGELOG.md': changelog(section('0.1.1.0', frag, '', open), released) }));+ expect(inProgress.problems).toEqual([]);+ expect(folded.problems).toEqual([]);+ expect(folded.text).toBe(inProgress.text);+ });});describe('main()', () => {diff --git a/test/scripts/release-gate.test.ts b/test/scripts/release-gate.test.tsindex 821110bf9a..e0a9da43d3 100644--- a/test/scripts/release-gate.test.ts+++ b/test/scripts/release-gate.test.ts@@ -38,14 +38,16 @@ describe('release gate', () => {expect((await evaluate(missing, A, '0.60.70.0')).why).toContain('Test has no push run yet');});- test('a failed run publishes nothing and names the repair and the backfill command', async () => {+ test('a failed run publishes nothing and names the repair and the re-run of the Release run', async () => {const red = deps({ 'test.yml': [run(1, 10, A, 'completed', 'failure')], 'e2e.yml': [run(2, 20, A, 'completed', 'success')] });const v = await evaluate(red, A, '0.60.70.0');expect(v.kind).toBe('fail');if (v.kind !== 'fail') return;expect(v.why).toContain('v0.60.70.0 is not published and latest-stable does not move');expect(v.next).toContain('Master red: Test');- expect(v.next).toContain('gh workflow run release.yml --ref master');+ expect(v.next).toContain('gh run rerun 1');+ expect(v.next).toContain('re-run this Release run');+ expect(v.next).not.toContain('gh workflow run release.yml');const rerunGreen = deps({ 'test.yml': [run(1, 10, A, 'completed', 'failure'), run(1, 10, A, 'completed', 'success', 2)], 'e2e.yml': [run(2, 20, A, 'completed', 'success')] });expect((await evaluate(rerunGreen, A, '0.60.70.0')).kind).toBe('publish');});@@ -59,6 +61,7 @@ describe('release gate', () => {const v = await evaluate(d, A, '0.60.70.0');expect(v).toMatchObject({ kind: 'fail', sha: A });expect(v.kind === 'fail' && v.next).toContain('gh run rerun 1');+ expect(v.kind === 'fail' && v.next).not.toContain('gh workflow run release.yml');expect(d.calls.some(c => c.endsWith(' b'))).toBe(false);}});@@ -82,10 +85,11 @@ describe('release gate', () => {expect(v.why).toContain("no 'reused-full-suite' artifact");expect(v.why).toContain('v0.60.70.0 is not published');expect(v.next).toContain('gh run rerun 2');- expect(v.next).toContain('gh workflow run release.yml --ref master');+ expect(v.next).toContain('re-run this Release run');+ expect(v.next).not.toContain('gh workflow run release.yml');});- test('the poller waits while CI runs and fails with the backfill command at its deadline (dispatch backfill uses the same gate)', async () => {+ test('the poller waits while CI runs and fails naming the re-run of the Release run at its deadline', async () => {let t = 0;const lines: string[] = [];const states = [run(1, 10, A, 'queued', null), run(1, 10, A, 'in_progress', null), run(1, 10, A, 'completed', 'success')];@@ -101,7 +105,7 @@ describe('release gate', () => {t = 0;const late = await gate(stuck, { sha: A, version: '0.60.70.0', timeoutMs: 3 * 60_000, pollMs: 60_000, log: () => {}, sleep: async ms => { t += ms; }, now: () => t });expect(late.kind).toBe('fail');- if (late.kind === 'fail') expect(late.next).toContain('gh workflow run release.yml --ref master');+ if (late.kind === 'fail') expect(late.next).toContain('re-run this Release run');});});