From cf39e6a30c566e9fd6173537d167e467bd713950 Mon Sep 17 00:00:00 2001 From: garrytan Date: Mon, 2 Nov 2026 02:18:08 +0000 Subject: [PATCH 1/4] fix(ship): a slot restamp after the docs audit keeps finish's docs check fresh (GST-906) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- lib/ship-release.ts | 21 +++++++++++++++++++-- test/ship-rereview-triggers.test.ts | 29 +++++++++++++++++++++++++++++ 2 files changed, 48 insertions(+), 2 deletions(-) diff --git a/lib/ship-release.ts b/lib/ship-release.ts index b6e517d91..9e282a4ba 100644 --- a/lib/ship-release.ts +++ b/lib/ship-release.ts @@ -11,6 +11,8 @@ */ import * as fs from 'node:fs'; import * as path from 'node:path'; +import { normalizeChangelog } from './changelog-check'; +import { versionAtRef } from './restamp'; import { classifyPath } from './review-depth'; import { comparePath, contextPacket, gateEditedPaths, isTestCode, PACKET_SECTION_CAP, readScopedReview, touchedPaths, type PatchSides } from './ship-patch'; import { parseReceiptDocs, type ReceiptDocs } from './ship-receipt-docs'; @@ -217,7 +219,11 @@ function route(cwd: string, base: string, reviewed: string, reviewedBase: string return by; } -/** Step 16 stage 3. Test code, paths only the base moved, and --docs-requested fixes the audit's own result asked for do not stale the audit (GST-391). */ +/** + * Step 16 stage 3. Test code, paths only the base or a stamp moved, a slot restamp after the audit (the CHANGELOG's heading + * move or re-heading, the version file's version, each against the audited bytes; GST-906), and --docs-requested fixes the + * audit's own result asked for do not stale the audit (GST-391). + */ function docsFresh(cwd: string, base: string, postFile: string, moved: readonly string[], requested: string[], resultFile: string | undefined, r: Report): boolean { const cmp = bin(cwd, 'gstack-docs-candidate', ['compare', postFile], 120_000); let stale: string[] | null = null; @@ -253,7 +259,18 @@ function docsFresh(cwd: string, base: string, postFile: string, moved: readonly if (!atAudit || (nowDiff && nowDiff.status !== 0)) { r.stop(`git could not list the paths the branch touched against ${baseRef}; documentation freshness is unknown (stage 3)`); return false; } const branchAtAudit = new Set([...atAudit, ...record.staged, ...record.unstaged, ...record.untracked]); const branchNow = new Set([...(nowDiff ? nul(nowDiff.stdout) : []), ...nul(git(cwd, ['ls-files', '-z', '--others', '--exclude-standard']).stdout)]); - const carried = { tests: stale.filter(isTestCode), base: stale.filter(p => !isTestCode(p) && (moved.includes(p) || (!!auditBase && !!nowBase && !branchAtAudit.has(p) && !branchNow.has(p)))), requested: [] as string[] }; + const changelog = shipPolicy(cwd, base)?.changelog; + const versionFile = versionAtRef(cwd, 'HEAD'); + const restamped = stale.filter(p => { + const isChangelog = p === changelog; + if (!isChangelog && !('rel' in versionFile && p === versionFile.rel)) return false; + const audited = typeof record.hashes?.[p] === 'string' ? git(cwd, ['cat-file', 'blob', record.hashes[p]]) : null; + if (audited?.status !== 0) return false; + let now: string; + try { now = fs.readFileSync(path.join(cwd, p), 'utf8'); } catch { return false; } + return isChangelog ? normalizeChangelog(audited.stdout) === normalizeChangelog(now) : !!parseVersion(audited.stdout.trim()) && !!parseVersion(now.trim()); + }); + const carried = { tests: stale.filter(isTestCode), base: stale.filter(p => !isTestCode(p) && (moved.includes(p) || restamped.includes(p) || (!!auditBase && !!nowBase && !branchAtAudit.has(p) && !branchNow.has(p)))), requested: [] as string[] }; let audit: any = null; try { audit = resultFile ? JSON.parse(fs.readFileSync(resultFile, 'utf8')) : null; } catch { audit = null; } for (const p of requested.filter(q => stale!.includes(q) && !carried.tests.includes(q) && !carried.base.includes(q))) { diff --git a/test/ship-rereview-triggers.test.ts b/test/ship-rereview-triggers.test.ts index f06b65074..dd82cb6fb 100644 --- a/test/ship-rereview-triggers.test.ts +++ b/test/ship-rereview-triggers.test.ts @@ -525,3 +525,32 @@ describe('preflight carry route for an adjacent base edit (GST-442)', () => { }); }); +describe('a CHANGELOG re-heading after the docs audit (GST-906, GBRA-258, gbrain #8372)', () => { + // Value: protects=a slot restamp after the Step 14.5 snapshot that only re-heads the branch's CHANGELOG entry + // ([Unreleased], or its old version after a lost slot, moved to `## [] - `, with the audited VERSION moved + // in the second case) keeps the audit fresh, while an entry edit beside the re-heading, or audited bytes git does not + // hold, stays stale; fails_when=finish stops with DOCS: stale (CHANGELOG.md) or (VERSION) on a pure restamp (recovery + // then needs a third audit or a named risk) or waves an entry edit through; seam=lib/ship-release.ts docsFresh; + // no_claim=the restamp writer + test('a re-heading alone keeps the audit fresh; an entry edit or unheld audited bytes stays stale', () => { + const policy = JSON.stringify({ bump: 'patch', queue_mode: 'stamp-at-merge', changelog: 'CHANGELOG.md', stamp_files: ['VERSION', 'package.json', 'CHANGELOG.md'] }); + const log = (heading: string, entry = '- b ships') => `# Changelog\n\n${heading}\n\n${entry}\n\n## [1.0.0.0] - 2026-10-30\n\n- base entry\n`; + const cases = [ + ['[Unreleased] re-headed', '1.0.0.0', log('## [Unreleased]'), '1.0.1.0', log('## [1.0.1.0] - 2026-11-01'), true, 'fresh'], + ['old version re-headed after a lost slot', '1.0.1.0', log('## [1.0.1.0] - 2026-11-01'), '1.0.2.0', log('## [1.0.2.0] - 2026-11-02'), true, 'fresh'], + ['re-heading plus an entry edit', '1.0.0.0', log('## [Unreleased]'), '1.0.1.0', log('## [1.0.1.0] - 2026-11-01', '- b ships fast'), true, 'stale'], + ['audited bytes never committed or staged', '1.0.0.0', log('## [Unreleased]'), '1.0.1.0', log('## [1.0.1.0] - 2026-11-01'), false, 'stale'], + ] as const; + for (const [name, audited, auditedLog, stamped, stampedLog, committed, verdict] of cases) { + const f = fx({ '.gstack/ship-policy.json': policy, 'CHANGELOG.md': '# Changelog\n\n## [1.0.0.0] - 2026-10-30\n\n- base entry\n' }); + const reviewed = wtree(f); + f.write({ VERSION: `${audited}\n`, 'CHANGELOG.md': auditedLog }); + if (committed) f.commit('Steps 12-13: version and CHANGELOG'); + const post = snapshot(f); + f.write({ VERSION: `${stamped}\n`, 'CHANGELOG.md': stampedLog }); f.commit('slot restamp'); + const r = finish(f, reviewed, post, ['--reviewed-base', mergeBase(f)]); + if (verdict === 'fresh') expect([name, r.status, lineOf(r.stdout, 'DOCS')]).toEqual([name, 0, expect.stringContaining('DOCS: fresh against the Step 14.5 post-audit snapshot')]); + else expect([name, r.status, lineOf(r.stdout, 'DOCS')]).toEqual([name, 3, 'DOCS: stale (CHANGELOG.md)']); + } + }); +}); From 6340025f179697c959dcb5d7b705e5d1e99d226b Mon Sep 17 00:00:00 2001 From: garrytan Date: Mon, 2 Nov 2026 03:04:47 +0000 Subject: [PATCH 2/4] fix(ship): the GST-906 restamp carry also holds after the slot merges main (red-team, ship round 1) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- lib/ship-release.ts | 13 ++++++++---- test/ship-rereview-triggers.test.ts | 31 +++++++++++++++++++++++++++++ 2 files changed, 40 insertions(+), 4 deletions(-) diff --git a/lib/ship-release.ts b/lib/ship-release.ts index 9e282a4ba..dbcaa6bb9 100644 --- a/lib/ship-release.ts +++ b/lib/ship-release.ts @@ -11,7 +11,7 @@ */ import * as fs from 'node:fs'; import * as path from 'node:path'; -import { normalizeChangelog } from './changelog-check'; +import { mergeChangelogs, normalizeChangelog } from './changelog-check'; import { versionAtRef } from './restamp'; import { classifyPath } from './review-depth'; import { comparePath, contextPacket, gateEditedPaths, isTestCode, PACKET_SECTION_CAP, readScopedReview, touchedPaths, type PatchSides } from './ship-patch'; @@ -221,8 +221,9 @@ function route(cwd: string, base: string, reviewed: string, reviewedBase: string /** * Step 16 stage 3. Test code, paths only the base or a stamp moved, a slot restamp after the audit (the CHANGELOG's heading - * move or re-heading, the version file's version, each against the audited bytes; GST-906), and --docs-requested fixes the - * audit's own result asked for do not stale the audit (GST-391). + * move or re-heading after the restamp writer's own merge of the base's CHANGELOG into the audited one, the version file's + * version, each against the audited bytes; GST-906), and --docs-requested fixes the audit's own result asked for do not + * stale the audit (GST-391). */ function docsFresh(cwd: string, base: string, postFile: string, moved: readonly string[], requested: string[], resultFile: string | undefined, r: Report): boolean { const cmp = bin(cwd, 'gstack-docs-candidate', ['compare', postFile], 120_000); @@ -268,7 +269,11 @@ function docsFresh(cwd: string, base: string, postFile: string, moved: readonly if (audited?.status !== 0) return false; let now: string; try { now = fs.readFileSync(path.join(cwd, p), 'utf8'); } catch { return false; } - return isChangelog ? normalizeChangelog(audited.stdout) === normalizeChangelog(now) : !!parseVersion(audited.stdout.trim()) && !!parseVersion(now.trim()); + if (!isChangelog) return !!parseVersion(audited.stdout.trim()) && !!parseVersion(now.trim()); + const [atAuditBase, atNowBase] = [auditBase, nowBase].map(b => b ? git(cwd, ['show', `${b}:${p}`]) : null); + if (atAuditBase?.status !== 0 || atNowBase?.status !== 0) return false; + const merged = mergeChangelogs(audited.stdout, atNowBase.stdout, atAuditBase.stdout); + return merged !== null && normalizeChangelog(merged) === normalizeChangelog(now); }); const carried = { tests: stale.filter(isTestCode), base: stale.filter(p => !isTestCode(p) && (moved.includes(p) || restamped.includes(p) || (!!auditBase && !!nowBase && !branchAtAudit.has(p) && !branchNow.has(p)))), requested: [] as string[] }; let audit: any = null; diff --git a/test/ship-rereview-triggers.test.ts b/test/ship-rereview-triggers.test.ts index dd82cb6fb..22fb6b07f 100644 --- a/test/ship-rereview-triggers.test.ts +++ b/test/ship-rereview-triggers.test.ts @@ -553,4 +553,35 @@ describe('a CHANGELOG re-heading after the docs audit (GST-906, GBRA-258, gbrain else expect([name, r.status, lineOf(r.stdout, 'DOCS')]).toEqual([name, 3, 'DOCS: stale (CHANGELOG.md)']); } }); + + // Value: protects=the lost-slot restamp merges main first (CREW rule 6), so the CHANGELOG also gains main's new sections; + // that merge plus the re-heading keeps the audit fresh, while a merge that drops or edits a main section, or hides an + // entry edit, stays stale; fails_when=finish stops with DOCS: stale (CHANGELOG.md) after main merged a sibling's release, + // or waves a changed section through; seam=lib/ship-release.ts docsFresh (mergeChangelogs as lib/restamp.ts calls it); + // no_claim=the restamp writer + test('a main merge before the re-heading keeps the audit fresh; a dropped or edited section stays stale', () => { + const policy = JSON.stringify({ bump: 'patch', queue_mode: 'stamp-at-merge', changelog: 'CHANGELOG.md', stamp_files: ['VERSION', 'package.json', 'CHANGELOG.md'] }); + const section = (heading: string, entry: string) => `${heading}\n\n${entry}\n\n`; + const log = (...sections: string[]) => `# Changelog\n\n${sections.join('')}## [1.0.0.0] - 2026-10-30\n\n- base entry\n`; + const own = section('## [1.0.1.0] - 2026-11-01', '- b ships'); + const sibling = section('## [1.0.1.0] - 2026-11-01', '- sibling ships'); + const cases = [ + ['main merged, then re-headed', log(section('## [1.0.2.0] - 2026-11-02', '- b ships'), sibling), 'fresh'], + ['merge drops a main section', log(section('## [1.0.2.0] - 2026-11-02', '- b ships')), 'stale'], + ['merge edits a main section', log(section('## [1.0.2.0] - 2026-11-02', '- b ships'), section('## [1.0.1.0] - 2026-11-01', '- sibling ships fast')), 'stale'], + ['entry edit hidden inside a merge', log(section('## [1.0.2.0] - 2026-11-02', '- b ships fast'), sibling), 'stale'], + ] as const; + for (const [name, stampedLog, verdict] of cases) { + const f = fx({ '.gstack/ship-policy.json': policy, VERSION: '1.0.0.0\n', 'CHANGELOG.md': log() }); + const reviewed = wtree(f); + f.write({ VERSION: '1.0.1.0\n', 'CHANGELOG.md': log(own) }); f.commit('Steps 12-13: version and CHANGELOG'); + const post = snapshot(f); + f.advanceBase({ VERSION: '1.0.1.0\n', 'CHANGELOG.md': log(sibling) }); + mergeMain(f, { VERSION: '1.0.1.0\n', 'CHANGELOG.md': log(own, sibling) }); + f.write({ VERSION: '1.0.2.0\n', 'CHANGELOG.md': stampedLog }); f.commit('slot restamp'); + const r = finish(f, reviewed, post, ['--reviewed-base', mergeBase(f)]); + if (verdict === 'fresh') expect([name, r.status, lineOf(r.stdout, 'DOCS')]).toEqual([name, 0, expect.stringContaining('DOCS: fresh against the Step 14.5 post-audit snapshot')]); + else expect([name, r.status, lineOf(r.stdout, 'DOCS')]).toEqual([name, 3, 'DOCS: stale (CHANGELOG.md)']); + } + }); }); From 5ea38af1e5db2c228442dbf328448c5717c03f4c Mon Sep 17 00:00:00 2001 From: garrytan Date: Mon, 2 Nov 2026 03:23:42 +0000 Subject: [PATCH 3/4] fix(ship): the GST-906 merge carry may only add the base's sections; an unmoved base keeps the direct rule (scoped fix-check) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- lib/ship-release.ts | 4 +++- test/ship-rereview-triggers.test.ts | 30 +++++++++++++++++++++++++++++ 2 files changed, 33 insertions(+), 1 deletion(-) diff --git a/lib/ship-release.ts b/lib/ship-release.ts index dbcaa6bb9..805756335 100644 --- a/lib/ship-release.ts +++ b/lib/ship-release.ts @@ -272,8 +272,10 @@ function docsFresh(cwd: string, base: string, postFile: string, moved: readonly if (!isChangelog) return !!parseVersion(audited.stdout.trim()) && !!parseVersion(now.trim()); const [atAuditBase, atNowBase] = [auditBase, nowBase].map(b => b ? git(cwd, ['show', `${b}:${p}`]) : null); if (atAuditBase?.status !== 0 || atNowBase?.status !== 0) return false; + if (atAuditBase.stdout === atNowBase.stdout) return normalizeChangelog(audited.stdout) === normalizeChangelog(now); + const kept = mergeChangelogs(audited.stdout, atAuditBase.stdout, atAuditBase.stdout); const merged = mergeChangelogs(audited.stdout, atNowBase.stdout, atAuditBase.stdout); - return merged !== null && normalizeChangelog(merged) === normalizeChangelog(now); + return kept !== null && merged !== null && normalizeChangelog(kept) === normalizeChangelog(audited.stdout) && normalizeChangelog(merged) === normalizeChangelog(now); }); const carried = { tests: stale.filter(isTestCode), base: stale.filter(p => !isTestCode(p) && (moved.includes(p) || restamped.includes(p) || (!!auditBase && !!nowBase && !branchAtAudit.has(p) && !branchNow.has(p)))), requested: [] as string[] }; let audit: any = null; diff --git a/test/ship-rereview-triggers.test.ts b/test/ship-rereview-triggers.test.ts index 22fb6b07f..04b91cf4b 100644 --- a/test/ship-rereview-triggers.test.ts +++ b/test/ship-rereview-triggers.test.ts @@ -584,4 +584,34 @@ describe('a CHANGELOG re-heading after the docs audit (GST-906, GBRA-258, gbrain else expect([name, r.status, lineOf(r.stdout, 'DOCS')]).toEqual([name, 3, 'DOCS: stale (CHANGELOG.md)']); } }); + + // Value: protects=the base merge in the carry may only add the base's sections: dropping a header line the audit saw + // stays stale with or without a main merge, and a branch that also corrected a released entry keeps a pure re-heading + // fresh; fails_when=mergeChangelogs' base-wins resolution hides a deleted audited line (DOCS: fresh) or stales a pure + // re-heading; seam=lib/ship-release.ts docsFresh; no_claim=the restamp writer + test('the base merge only adds base sections: a dropped audited line stays stale, a corrected released entry stays fresh', () => { + const policy = JSON.stringify({ bump: 'patch', queue_mode: 'stamp-at-merge', changelog: 'CHANGELOG.md', stamp_files: ['VERSION', 'package.json', 'CHANGELOG.md'] }); + const released = (entry = '- base entry') => `## [1.0.0.0] - 2026-10-30\n\n${entry}\n`; + const log = (header: string, own: string, rest: string) => `# Changelog\n\n${header}${own}\n\n- b ships\n\n${rest}`; + const sibling = '## [1.0.1.0] - 2026-11-01\n\n- sibling ships\n\n'; + const cases = [ + ['audited header line dropped, no main merge', log('Notice: read this.\n\n', '## [1.0.1.0] - 2026-11-01', released()), false, log('', '## [1.0.2.0] - 2026-11-02', released()), 'stale'], + ['audited header line dropped in a main merge', log('Notice: read this.\n\n', '## [1.0.1.0] - 2026-11-01', released()), true, log('', '## [1.0.2.0] - 2026-11-02', sibling + released()), 'stale'], + ['released entry corrected, then re-headed', log('', '## [1.0.1.0] - 2026-11-01', released('- base entry, corrected')), false, log('', '## [1.0.2.0] - 2026-11-02', released('- base entry, corrected')), 'fresh'], + ] as const; + for (const [name, auditedLog, merges, stampedLog, verdict] of cases) { + const f = fx({ '.gstack/ship-policy.json': policy, VERSION: '1.0.0.0\n', 'CHANGELOG.md': `# Changelog\n\n${released()}` }); + const reviewed = wtree(f); + f.write({ VERSION: '1.0.1.0\n', 'CHANGELOG.md': auditedLog }); f.commit('Steps 12-13: version and CHANGELOG'); + const post = snapshot(f); + if (merges) { + f.advanceBase({ VERSION: '1.0.1.0\n', 'CHANGELOG.md': `# Changelog\n\n${sibling}${released()}` }); + mergeMain(f, { VERSION: '1.0.1.0\n', 'CHANGELOG.md': stampedLog }); + } + f.write({ VERSION: '1.0.2.0\n', 'CHANGELOG.md': stampedLog }); f.commit('slot restamp'); + const r = finish(f, reviewed, post, ['--reviewed-base', mergeBase(f)]); + if (verdict === 'fresh') expect([name, r.status, lineOf(r.stdout, 'DOCS')]).toEqual([name, 0, expect.stringContaining('DOCS: fresh against the Step 14.5 post-audit snapshot')]); + else expect([name, r.status, lineOf(r.stdout, 'DOCS')]).toEqual([name, 3, 'DOCS: stale (CHANGELOG.md)']); + } + }); }); From 15b3b90e3a91a5d062d9ce1e4b72d900c237d18d Mon Sep 17 00:00:00 2001 From: garrytan Date: Mon, 2 Nov 2026 03:26:02 +0000 Subject: [PATCH 4/4] changelog.d: GST-906 restamp carry fragment Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- changelog.d/gst-906-changelog-rehead-docs.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 changelog.d/gst-906-changelog-rehead-docs.md diff --git a/changelog.d/gst-906-changelog-rehead-docs.md b/changelog.d/gst-906-changelog-rehead-docs.md new file mode 100644 index 000000000..977f7eedf --- /dev/null +++ b/changelog.d/gst-906-changelog-rehead-docs.md @@ -0,0 +1,5 @@ +**A slot restamp after the docs audit no longer stops `finish` with `DOCS: stale (CHANGELOG.md)` (GST-906).** When a PR lost its merge slot after Step 14.5, the new slot's restamp re-heads the CHANGELOG entry and moves VERSION, and on the lost-slot path it merges main first. `gstack-ship-release finish` read all of that as a docs change, so the only ways forward were a third docs audit, which the policy forbids, or an owner-accepted named risk. Reported by GBRA-258 on gbrain #8372. + +### Fixed +- **Step 16's docs check carries a restamp.** The CHANGELOG counts as unchanged when it differs from the audited copy only by the heading move or re-heading. After a main merge, the audited copy is first merged with main's CHANGELOG by the same `mergeChangelogs` call the restamp writer makes, and that merge may only add main's sections. The version file counts as unchanged when it held a bare version at the audit and still does. +- **Anything else still stales the audit.** That includes an entry edit, a dropped or edited main section, a dropped line the audit saw, and an audited CHANGELOG that git never held.