train S2: merge #3834 at 15b3b90e3a v1.92.63.0

lib/ship-release.ts

@@ -11,6 +11,8 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+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';
 import { parseReceiptDocs, type ReceiptDocs } from './ship-receipt-docs';
@@ -217,7 +219,12 @@ 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 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);
   let stale: string[] | null = null;
@@ -253,7 +260,24 @@ 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; }
+    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 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;
   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))) {