fix(release-notes): let Artur sync acknowledge known-in-source drift (#300)

Author: outof-place

scripts/release-notes/acknowledged-drift.json

@@ -0,0 +1,6 @@
+[
+  {
+    "commit": "6cf7474224eaeb97aca9e77a6a4bedb26045df01",
+    "reason": "Arthur PR #23 (fix(worker): support investigate keyword schema) removes maxItems from KEYWORDS_SCHEMA in apps/worker/src/workflows/blocks/investigate.ts. Source main already omits maxItems from that schema (verified 2026-08-17), so the drift guard's patch-id comparison is a false positive: overwriting Arthur with the source snapshot preserves the change rather than reverting it. Tracked under AIW-281."
+  }
+]

scripts/release-notes/cli.test.ts

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
@@ -278,3 +278,122 @@ test("sync-artur CLI blocks an unbackported destination commit", async () => {
   );
   assert.equal(synchronized, false);
 });
+
+test("sync-artur CLI proceeds when drift is acknowledged in source main", async () => {
+  const acknowledgedCommit = "6cf7474224eaeb97aca9e77a6a4bedb26045df01";
+  const sourceMain = await mkdtemp(path.join(os.tmpdir(), "artur-sync-ack-src-"));
+  await mkdir(path.join(sourceMain, "scripts/release-notes"), { recursive: true });
+  await writeFile(
+    path.join(sourceMain, "scripts/release-notes/acknowledged-drift.json"),
+    JSON.stringify([{ commit: acknowledgedCommit, reason: "already present in source" }]),
+  );
+  const output = await mkdtemp(path.join(os.tmpdir(), "artur-sync-ack-out-"));
+  const approvalPath = path.join(output, "approved.json");
+  const resultPath = path.join(output, "result.json");
+  await writeFile(
+    approvalPath,
+    JSON.stringify({
+      version: "2026.08.0",
+      previousSourceCommit: "a".repeat(40),
+      targetSourceCommit: "b".repeat(40),
+      notesPath: "docs/releases/artur/2026.08.0.md",
+      releaseNotesPullRequest: 193,
+      releaseNotesApprovedBy: ["zak"],
+    }),
+  );
+  const expected = {
+    version: "2026.08.0",
+    sourceCommit: "b".repeat(40),
+    destinationBaseCommit: "c".repeat(40),
+    notesPath: "docs/releases/artur/2026.08.0.md",
+    added: [],
+    modified: [],
+    deleted: [],
+    preserved: [],
+    driftCommits: [],
+  };
+  let synchronized = false;
+  await runCli(
+    [
+      "sync-artur",
+      "--version",
+      "2026.08.0",
+      "--approval",
+      approvalPath,
+      "--source-main",
+      sourceMain,
+      "--source-snapshot",
+      "/source-snapshot",
+      "--destination",
+      "/destination",
+      "--previous-destination-ref",
+      "baseline",
+      "--output",
+      resultPath,
+    ],
+    {
+      findDrift: async () => [acknowledgedCommit],
+      sync: async () => {
+        synchronized = true;
+        return expected;
+      },
+    },
+  );
+  assert.equal(synchronized, true);
+  const record = JSON.parse(await readFile(resultPath, "utf8"));
+  assert.deepEqual(record.driftCommits, []);
+  assert.deepEqual(record.acknowledgedDrift, [acknowledgedCommit]);
+});
+
+test("sync-artur CLI still blocks drift that is not acknowledged", async () => {
+  const sourceMain = await mkdtemp(path.join(os.tmpdir(), "artur-sync-ack-neg-"));
+  await mkdir(path.join(sourceMain, "scripts/release-notes"), { recursive: true });
+  await writeFile(
+    path.join(sourceMain, "scripts/release-notes/acknowledged-drift.json"),
+    JSON.stringify([{ commit: "e".repeat(40), reason: "unrelated" }]),
+  );
+  const output = await mkdtemp(path.join(os.tmpdir(), "artur-sync-ack-neg-out-"));
+  const approvalPath = path.join(output, "approved.json");
+  await writeFile(
+    approvalPath,
+    JSON.stringify({
+      version: "2026.08.0",
+      previousSourceCommit: "a".repeat(40),
+      targetSourceCommit: "b".repeat(40),
+      notesPath: "docs/releases/artur/2026.08.0.md",
+      releaseNotesPullRequest: 193,
+      releaseNotesApprovedBy: ["zak"],
+    }),
+  );
+  let synchronized = false;
+  await assert.rejects(
+    runCli(
+      [
+        "sync-artur",
+        "--version",
+        "2026.08.0",
+        "--approval",
+        approvalPath,
+        "--source-main",
+        sourceMain,
+        "--source-snapshot",
+        "/source-snapshot",
+        "--destination",
+        "/destination",
+        "--previous-destination-ref",
+        "baseline",
+        "--output",
+        path.join(output, "result.json"),
+      ],
+      {
+        findDrift: async () => ["f".repeat(40)],
+        sync: async () => {
+          synchronized = true;
+          throw new Error("must not run");
+        },
+      },
+    ),
+    /not backported.*ffff/i,
+  );
+  assert.equal(synchronized, false);
+});

scripts/release-notes/cli.ts

@@ -216,6 +216,13 @@ const approvedSourceSchema = z.object({
   releaseNotesApprovedBy: z.array(z.string().min(1)).min(1),
 });
 
+const acknowledgedDriftSchema = z.array(
+  z.object({
+    commit: z.string().regex(/^[0-9a-f]{40}$/),
+    reason: z.string().min(1),
+  }),
+);
+
 interface CliDeps {
   validate?: typeof validateApprovedSourceRelease;
   findDrift?: typeof findUnbackportedDestinationCommits;
@@ -330,6 +337,18 @@ async function guardArturCommand(argv: string[]): Promise<unknown> {
   return { version, available: true };
 }
 
+async function readAcknowledgedDrift(sourceMainDir: string): Promise<Set<string>> {
+  const file = path.join(sourceMainDir, "scripts/release-notes/acknowledged-drift.json");
+  let raw: string;
+  try {
+    raw = await readFile(file, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return new Set();
+    throw error;
+  }
+  return new Set(acknowledgedDriftSchema.parse(JSON.parse(raw)).map((entry) => entry.commit));
+}
+
 async function syncArturCommand(argv: string[], deps: CliDeps): Promise<SyncResult> {
   const version = parseVersion(requiredArg(argv, "version"));
   const approval = approvedSourceSchema.parse(
@@ -342,13 +361,16 @@ async function syncArturCommand(argv: string[], deps: CliDeps): Promise<SyncResu
   const sourceSnapshotDir = path.resolve(requiredArg(argv, "source-snapshot"));
   const destinationDir = path.resolve(requiredArg(argv, "destination"));
   const previousDestinationRef = requiredArg(argv, "previous-destination-ref");
-  const driftCommits = await (deps.findDrift ?? findUnbackportedDestinationCommits)({
+  const foundDrift = await (deps.findDrift ?? findUnbackportedDestinationCommits)({
     sourceSnapshotDir,
     destinationDir,
     previousSourceCommit: approval.previousSourceCommit,
     targetSourceCommit: approval.targetSourceCommit,
     previousDestinationRef,
   });
+  const acknowledgedDrift = await readAcknowledgedDrift(sourceMainDir);
+  const acknowledged = foundDrift.filter((commit) => acknowledgedDrift.has(commit));
+  const driftCommits = foundDrift.filter((commit) => !acknowledgedDrift.has(commit));
   if (driftCommits.length > 0) {
     throw new Error(
       `Artur contains application commits that are not backported to the selected source snapshot: ${driftCommits.join(", ")}`,
@@ -363,7 +385,9 @@ async function syncArturCommand(argv: string[], deps: CliDeps): Promise<SyncResu
   });
   const outputPath = path.resolve(requiredArg(argv, "output"));
   await mkdir(path.dirname(outputPath), { recursive: true });
-  await writeFile(outputPath, `${JSON.stringify({ ...result, driftCommits }, null, 2)}\n`);
+  const record: Record<string, unknown> = { ...result, driftCommits };
+  if (acknowledged.length > 0) record.acknowledgedDrift = acknowledged;
+  await writeFile(outputPath, `${JSON.stringify(record, null, 2)}\n`);
   return { ...result, driftCommits };
 }