@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

package/src/resources/extensions/gsd/tests/export-memory.test.ts

@@ -0,0 +1,179 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { writeExportFile } from "../export.ts";
+import { closeDatabase, openDatabase } from "../gsd-db.ts";
+import { createMemory } from "../memory-store.ts";
+
+function mockTokens() {
+  return { input: 10, output: 5, cacheRead: 0, cacheWrite: 0, total: 15 };
+}
+
+test("writeExportFile includes active memories in markdown exports", () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-export-memory-"));
+  try {
+    const largeContent = "Exported reports should include memory rows. " + "A".repeat(2500);
+    const filePath = writeExportFile(base, "markdown", {
+      totals: {
+        units: 1,
+        tokens: mockTokens(),
+        cost: 0.01,
+        duration: 1000,
+        toolCalls: 1,
+        assistantMessages: 1,
+        userMessages: 1,
+      },
+      byPhase: [
+        { phase: "execution", units: 1, tokens: mockTokens(), cost: 0.01, duration: 1000 },
+      ],
+      bySlice: [
+        { sliceId: "M001/S01", units: 1, tokens: mockTokens(), cost: 0.01, duration: 1000 },
+      ],
+      byModel: [],
+      units: [
+        {
+          type: "execute-task",
+          id: "M001/S01/T01",
+          model: "claude-sonnet",
+          startedAt: 0,
+          finishedAt: 1000,
+          tokens: mockTokens(),
+          cost: 0.01,
+          toolCalls: 1,
+          assistantMessages: 1,
+          userMessages: 1,
+        },
+      ],
+      memories: {
+        totalCount: 1,
+        entries: [
+          {
+            id: "MEM001",
+            category: "gotcha",
+            content: largeContent,
+            confidence: 0.9,
+            hitCount: 2,
+            scope: "M001/S01",
+            tags: ["export", "memory"],
+            updatedAt: "2026-06-21T00:00:00.000Z",
+          },
+        ],
+      },
+    });
+
+    assert.ok(filePath);
+    const markdown = readFileSync(filePath, "utf-8");
+    assert.match(markdown, /## Memories/);
+    assert.match(markdown, /Active memories: 1/);
+    assert.match(markdown, /MEM001/);
+    assert.match(markdown, /Exported reports should include memory rows/);
+    assert.doesNotMatch(markdown, new RegExp(`A{${2500}}`));
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("writeExportFile reads project DB memories when no visualizer payload is supplied", () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-export-memory-db-"));
+  try {
+    const gsdDir = join(base, ".gsd");
+    mkdirSync(gsdDir, { recursive: true });
+    writeFileSync(
+      join(gsdDir, "metrics.json"),
+      JSON.stringify({
+        version: 1,
+        projectStartedAt: Date.now(),
+        units: [
+          {
+            type: "execute-task",
+            id: "M001/S01/T01",
+            model: "claude-sonnet",
+            startedAt: 0,
+            finishedAt: 1000,
+            tokens: mockTokens(),
+            cost: 0.01,
+            toolCalls: 1,
+            assistantMessages: 1,
+            userMessages: 1,
+          },
+        ],
+      }),
+    );
+
+    openDatabase(join(gsdDir, "gsd.db"));
+    createMemory({
+      category: "pattern",
+      content: "Shared markdown export reads memories from the project DB",
+      confidence: 0.86,
+      tags: ["export"],
+    });
+    closeDatabase();
+
+    const filePath = writeExportFile(base, "markdown");
+
+    assert.ok(filePath);
+    const markdown = readFileSync(filePath, "utf-8");
+    assert.match(markdown, /## Memories/);
+    assert.match(markdown, /MEM001/);
+    assert.match(markdown, /Shared markdown export reads memories from the project DB/);
+  } finally {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("writeExportFile includes bounded memories in json exports", () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-export-memory-json-"));
+  try {
+    const gsdDir = join(base, ".gsd");
+    mkdirSync(gsdDir, { recursive: true });
+    writeFileSync(
+      join(gsdDir, "metrics.json"),
+      JSON.stringify({
+        version: 1,
+        projectStartedAt: Date.now(),
+        units: [
+          {
+            type: "execute-task",
+            id: "M001/S01/T01",
+            model: "claude-sonnet",
+            startedAt: 0,
+            finishedAt: 1000,
+            tokens: mockTokens(),
+            cost: 0.01,
+            toolCalls: 1,
+            assistantMessages: 1,
+            userMessages: 1,
+          },
+        ],
+      }),
+    );
+
+    openDatabase(join(gsdDir, "gsd.db"));
+    const largeContent = "JSON export should carry memory rows. " + "B".repeat(2500);
+    createMemory({
+      category: "pattern",
+      content: largeContent,
+      confidence: 0.86,
+      tags: ["export"],
+    });
+    closeDatabase();
+
+    const filePath = writeExportFile(base, "json");
+
+    assert.ok(filePath);
+    const report = JSON.parse(readFileSync(filePath, "utf-8"));
+    assert.equal(report.memories.totalCount, 1);
+    assert.equal(report.memories.entries[0].id, "MEM001");
+    assert.match(report.memories.entries[0].content, /JSON export should carry memory rows/);
+    assert.ok(report.memories.entries[0].content.length < largeContent.length);
+    assert.ok(report.memories.entries[0].content.length <= 2003);
+    assert.ok(report.memories.entries[0].content.endsWith("..."));
+  } finally {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/extension-bootstrap-isolation.test.ts

@@ -195,4 +195,57 @@ describe("registerGsdExtension defensive registration", () => {
     assert.ok(!registeredTools.includes("gsd_plan_slice"));
     drainLogs();
   });
+
+  // ── #852 follow-up: assertCriticalGsdWorkflowToolsRegistered tolerates pre-bind ──
+  //
+  // During extension loading, getAllTools() is a throwing stub
+  // ("Extension runtime not initialized"). The assertion used to call it
+  // synchronously and throw, propagating to index.ts's catch and firing
+  // "Extension setup partially failed" — leaving the tool surface incomplete
+  // under Claude Code CLI. It must tolerate the pre-bind throw.
+
+  test("registerGsdExtension does not throw when getAllTools is the pre-bind stub", () => {
+    const registeredTools: string[] = [];
+    const pi = {
+      registerCommand: () => {},
+      registerTool: (tool: { name: string }) => { registeredTools.push(tool.name); },
+      registerHook: () => {},
+      registerShortcut: () => {},
+      events: { on: () => {}, off: () => {}, emit: () => {} },
+      // Simulate the pre-bind throwing stub (loader.ts:182).
+      getAllTools: () => {
+        throw new Error("Extension runtime not initialized. Action methods cannot be called during extension loading.");
+      },
+    };
+
+    // Must not throw — the old code let this propagate as "Extension setup partially failed".
+    assert.doesNotThrow(() => registerGsdExtension(pi as any));
+    // Critical tools should still have been registered (registerTool is valid during load).
+    assert.ok(registeredTools.includes("gsd_plan_milestone"));
+    assert.ok(registeredTools.includes("gsd_plan_slice"));
+    drainLogs();
+  });
+
+  test("registerGsdExtension still throws when getAllTools works and critical tools are missing (post-bind)", () => {
+    // The assertion must still fire when getAllTools returns a real value but
+    // a critical tool is missing — just not during the pre-bind window.
+    const registeredTools: string[] = [];
+    const pi = {
+      registerCommand: () => {},
+      registerTool: (tool: { name: string }) => {
+        if (tool.name === "gsd_plan_slice") throw new Error("simulated failure");
+        registeredTools.push(tool.name);
+      },
+      registerHook: () => {},
+      registerShortcut: () => {},
+      events: { on: () => {}, off: () => {}, emit: () => {} },
+      getAllTools: () => registeredTools.map((name) => ({ name })),
+    };
+
+    assert.throws(
+      () => registerGsdExtension(pi as any),
+      /Critical GSD workflow tool registration failed/,
+    );
+    drainLogs();
+  });
 });

package/src/resources/extensions/gsd/tests/external-markdown-edit.test.ts

@@ -0,0 +1,137 @@
+// Project/App: gsd-pi
+// File Purpose: Unit tests for the external-markdown-edit drift handler.
+import test, { afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+import { externalMarkdownEditHandler } from "../state-reconciliation/drift/external-markdown-edit.ts";
+import { writeCompatMarker, computeProjectionSha } from "../compat/compat-marker.ts";
+import type { DriftContext } from "../state-reconciliation/types.ts";
+import type { GSDState } from "../types.ts";
+
+const tmpDirs: string[] = [];
+
+function makeTmpBase(): string {
+  const base = mkdtempSync(join(tmpdir(), `gsd-extedit-${randomUUID()}`));
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  tmpDirs.push(base);
+  return base;
+}
+
+const stubState = { phase: "idle" } as unknown as GSDState;
+
+function ctx(base: string): DriftContext {
+  return { basePath: base, state: stubState };
+}
+
+afterEach(() => {
+  for (const dir of tmpDirs) {
+    try { rmSync(dir, { recursive: true, force: true }); } catch { /* */ }
+  }
+  tmpDirs.length = 0;
+});
+
+test("detect returns no drift when file sha matches marker", async () => {
+  const base = makeTmpBase();
+  const rel = "m1/roadmap.md";
+  mkdirSync(join(base, ".gsd", "m1"), { recursive: true });
+  writeFileSync(join(base, ".gsd", rel), "# Roadmap\n\n- [x] S1 done\n", "utf-8");
+  writeCompatMarker(base, {
+    schema: 1,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "2026-06-21T00:00:00.000Z",
+    projections: { [rel]: { sha: computeProjectionSha("# Roadmap\n\n- [x] S1 done\n"), entities: ["m1"] } },
+    piVersion: "1.4.0",
+  });
+
+  const drift = await externalMarkdownEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift.length, 0);
+});
+
+test("detect returns drift when file content differs from marker", async () => {
+  const base = makeTmpBase();
+  const rel = "m1/roadmap.md";
+  mkdirSync(join(base, ".gsd", "m1"), { recursive: true });
+  writeFileSync(join(base, ".gsd", rel), "# Roadmap\n\n- [ ] S1 NOT done\n", "utf-8");
+  writeCompatMarker(base, {
+    schema: 1,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "2026-06-21T00:00:00.000Z",
+    projections: { [rel]: { sha: "stale000000000000", entities: ["m1"] } },
+    piVersion: "1.4.0",
+  });
+
+  const drift = await externalMarkdownEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift.length, 1);
+  assert.equal(drift[0].kind, "external-markdown-edit");
+  assert.equal(drift[0].projectionPath, rel);
+  assert.deepEqual(drift[0].entities, ["m1"]);
+});
+
+test("detect treats missing marker as drift on every tracked projection file", async () => {
+  const base = makeTmpBase();
+  const rel = "m1/roadmap.md";
+  mkdirSync(join(base, ".gsd", "m1"), { recursive: true });
+  writeFileSync(join(base, ".gsd", rel), "# Roadmap\n", "utf-8");
+  // No writeCompatMarker call → marker missing → EMPTY_MARKER
+
+  // Without a marker we have no projections to compare, so detect should be a
+  // no-op (the reconcile pipeline's other handlers cover the "import everything"
+  // case via the existing /gsd recover flow). This is by design: this handler
+  // only fires when we HAVE a baseline to compare.
+  const drift = await externalMarkdownEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift.length, 0);
+});
+
+test("detect ignores files missing from disk (other handlers cover that)", async () => {
+  const base = makeTmpBase();
+  const rel = "m1/roadmap.md";
+  writeCompatMarker(base, {
+    schema: 1,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "2026-06-21T00:00:00.000Z",
+    projections: { [rel]: { sha: "abc123", entities: ["m1"] } },
+    piVersion: "1.4.0",
+  });
+  // No file written.
+
+  const drift = await externalMarkdownEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift.length, 0);
+});
+
+test("repair is idempotent: running twice produces no further drift on second detect", async () => {
+  const base = makeTmpBase();
+  const rel = "m1/roadmap.md";
+  mkdirSync(join(base, ".gsd", "m1"), { recursive: true });
+  const content = "# Roadmap\n\n- [x] S1 done\n";
+  writeFileSync(join(base, ".gsd", rel), content, "utf-8");
+  writeCompatMarker(base, {
+    schema: 1,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "2026-06-21T00:00:00.000Z",
+    projections: { [rel]: { sha: "stale000000000000", entities: ["m1"] } },
+    piVersion: "1.4.0",
+  });
+
+  const drift1 = await externalMarkdownEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift1.length, 1);
+  // repair may call migrateHierarchyToDb which requires a DB; we only assert
+  // that detect after repair produces no further drift on THIS handler. Wrap
+  // in try/catch so a no-DB environment doesn't fail the idempotency check —
+  // the marker refresh is the load-bearing part of the assertion.
+  try {
+    await externalMarkdownEditHandler.repair(drift1[0], ctx(base));
+  } catch {
+    // migrateHierarchyToDb may throw without an open DB; that's fine for this
+    // unit test — the marker refresh below the import call still runs if the
+    // import succeeds. If it throws, we skip the second-detect assertion.
+    return;
+  }
+
+  // After repair, marker should reflect the file's actual sha → no drift.
+  const drift2 = await externalMarkdownEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift2.length, 0);
+});

package/src/resources/extensions/gsd/tests/external-planning-edit.test.ts

@@ -0,0 +1,199 @@
+// Project/App: gsd-pi
+// File Purpose: Tests for the external-planning-edit drift handler.
+import test, { afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+import { externalPlanningEditHandler } from "../state-reconciliation/drift/external-planning-edit.ts";
+import { reconcileBeforeDispatch } from "../state-reconciliation.ts";
+import { writeCompatMarker, readCompatMarker } from "../compat/compat-marker.ts";
+import type { DriftContext } from "../state-reconciliation/types.ts";
+import type { GSDState } from "../types.ts";
+
+const tmpDirs: string[] = [];
+function makeTmpBase(): string {
+  const base = mkdtempSync(join(tmpdir(), `gsd-pedit-${randomUUID()}`));
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  mkdirSync(join(base, ".planning"), { recursive: true });
+  tmpDirs.push(base);
+  return base;
+}
+const stubState = { phase: "idle" } as unknown as GSDState;
+function ctx(base: string): DriftContext {
+  return { basePath: base, state: stubState };
+}
+afterEach(() => {
+  for (const d of tmpDirs) { try { rmSync(d, { recursive: true, force: true }); } catch { /* */ } }
+  tmpDirs.length = 0;
+});
+
+test("detect returns no drift when planning inactive and dir is empty", async () => {
+  const base = makeTmpBase();
+  // .planning/ exists (created by makeTmpBase) but has no ROADMAP.md → no
+  // layout signal → detectPlanningLayout returns null → stays inactive.
+  const drift = await externalPlanningEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift.length, 0);
+
+  const { readCompatMarker } = await import("../compat/compat-marker.ts");
+  const marker = readCompatMarker(base);
+  assert.equal(marker.planning?.active, false, "should not activate without a recognisable layout");
+});
+
+test("detect does NOT write the marker when planning inactive (dry-run invariant)", async () => {
+  // Regression test for COMMENT:3449147735: detect() must be read-only because
+  // it is called in both dry-run and non-dry-run contexts. Activation is owned
+  // by capturePlanningCompatIfNeeded (called from reconcileBeforeDispatch when
+  // !dryRun), not by the detect function itself.
+  const base = makeTmpBase();
+  writeFileSync(
+    join(base, ".planning", "ROADMAP.md"),
+    "# Roadmap\n\n## Phases\n\n- [ ] 01 — Foundation\n",
+    "utf-8",
+  );
+  // No compat marker written → planning.active = false by default.
+
+  const drift = await externalPlanningEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift.length, 0);
+
+  // Marker must NOT have been written by detect().
+  const { readCompatMarker } = await import("../compat/compat-marker.ts");
+  const marker = readCompatMarker(base);
+  assert.equal(marker.planning?.active, false, "detect() must not activate the marker");
+});
+
+test("detect returns drift when planning projection sha mismatches", async () => {
+  const base = makeTmpBase();
+  const rel = "ROADMAP.md";
+  writeFileSync(join(base, ".planning", rel), "# edited by gsd-core\n", "utf-8");
+  writeCompatMarker(base, {
+    schema: 2,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "2026-06-21T00:00:00.000Z",
+    projections: {},
+    planning: {
+      active: true,
+      layout: "flat-phases",
+      projections: { [rel]: { sha: "stale000000000000", entities: ["M001"] } },
+      passthrough: {},
+    },
+    piVersion: "1.4.0",
+  });
+
+  const drift = await externalPlanningEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift.length, 1);
+  assert.equal(drift[0]!.kind, "external-planning-edit");
+  assert.equal(drift[0]!.projectionPath, rel);
+  assert.equal(drift[0]!.passthrough, false);
+});
+
+test("detect flags passthrough files separately with passthrough=true", async () => {
+  const base = makeTmpBase();
+  const rel = "codebase/STACK.md";
+  mkdirSync(join(base, ".planning", "codebase"), { recursive: true });
+  writeFileSync(join(base, ".planning", rel), "# new stack content\n", "utf-8");
+  writeCompatMarker(base, {
+    schema: 2,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "2026-06-21T00:00:00.000Z",
+    projections: {},
+    planning: {
+      active: true,
+      layout: "flat-phases",
+      projections: {},
+      passthrough: { [rel]: { sha: "old0000000000000", entities: [] } },
+    },
+    piVersion: "1.4.0",
+  });
+
+  const drift = await externalPlanningEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift.length, 1);
+  assert.equal(drift[0]!.passthrough, true);
+});
+
+test("detect returns no drift when sha matches", async () => {
+  const base = makeTmpBase();
+  const rel = "ROADMAP.md";
+  const content = "# unchanged\n";
+  writeFileSync(join(base, ".planning", rel), content, "utf-8");
+  const { computeProjectionSha } = await import("../compat/compat-marker.ts");
+  writeCompatMarker(base, {
+    schema: 2,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "2026-06-21T00:00:00.000Z",
+    projections: {},
+    planning: {
+      active: true,
+      layout: "flat-phases",
+      projections: { [rel]: { sha: computeProjectionSha(content), entities: ["M001"] } },
+      passthrough: {},
+    },
+    piVersion: "1.4.0",
+  });
+
+  const drift = await externalPlanningEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift.length, 0);
+});
+
+test("repair refreshes passthrough marker sha (idempotent on second detect)", async () => {
+  const base = makeTmpBase();
+  const rel = "codebase/STACK.md";
+  mkdirSync(join(base, ".planning", "codebase"), { recursive: true });
+  writeFileSync(join(base, ".planning", rel), "# new stack content\n", "utf-8");
+  writeCompatMarker(base, {
+    schema: 2,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "2026-06-21T00:00:00.000Z",
+    projections: {},
+    planning: {
+      active: true,
+      layout: "flat-phases",
+      projections: {},
+      passthrough: { [rel]: { sha: "old0000000000000", entities: [] } },
+    },
+    piVersion: "1.4.0",
+  });
+
+  const drift1 = await externalPlanningEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift1.length, 1);
+  await externalPlanningEditHandler.repair(drift1[0]!, ctx(base));
+
+  const drift2 = await externalPlanningEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift2.length, 0);
+});
+
+test("reconcileBeforeDispatch dryRun=true does not write compat marker (planning)", async () => {
+  // Regression test for COMMENT:3449147735: /gsd sync --dry-run claimed to be
+  // read-only but capturePlanningCompatIfNeeded wrote the marker. The guard
+  // added in reconcileBeforeDispatch must prevent any marker mutations.
+  const base = makeTmpBase();
+  writeFileSync(
+    join(base, ".planning", "ROADMAP.md"),
+    "# Roadmap\n\n## Phases\n\n- [ ] 01 — Foundation\n",
+    "utf-8",
+  );
+  // Capture the marker state before the dry-run reconcile.
+  const markerBefore = readCompatMarker(base);
+
+  await reconcileBeforeDispatch(base, {
+    dryRun: true,
+    registry: [], // empty: no handlers, no repairs
+    invalidateStateCache: () => {},
+    deriveState: async () => stubState as unknown as import("../types.ts").GSDState,
+  });
+
+  // Marker must be identical to before: no planning activation, no SHA seeding.
+  const markerAfter = readCompatMarker(base);
+  assert.equal(
+    markerAfter.planning?.active,
+    markerBefore.planning?.active,
+    "dryRun reconcile must not activate planning",
+  );
+  assert.deepEqual(
+    markerAfter.planning?.projections,
+    markerBefore.planning?.projections,
+    "dryRun reconcile must not write planning projections",
+  );
+});

package/src/resources/extensions/gsd/tests/fallback-continuation.test.ts

@@ -0,0 +1,36 @@
+// gsd-pi + src/resources/extensions/gsd/tests/fallback-continuation.test.ts - Regression test for #804 fallback continuation dispatch.
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { scheduleFallbackContinuation } from "../bootstrap/fallback-continuation.ts";
+
+/**
+ * #804: After switching to a fallback model in the agent_end recovery path, the
+ * continuation must be dispatched on a *fresh* turn — not as a steering message
+ * against the turn that just errored out (which `isStreaming` is still true for
+ * until finishRun() clears it). The fix defers the send to a macrotask and uses
+ * a plain `triggerTurn` with no `deliverAs: "steer"`.
+ */
+test("scheduleFallbackContinuation defers a plain triggerTurn dispatch (no steer)", async () => {
+  const calls: Array<{ message: unknown; options: unknown }> = [];
+  const pi = {
+    sendMessage: (message: unknown, options: unknown) => {
+      calls.push({ message, options });
+    },
+  } as any;
+
+  scheduleFallbackContinuation(pi);
+
+  // Synchronous within the awaited agent_end listener: nothing sent yet so the
+  // dispatch cannot be misrouted into the still-streaming dying turn.
+  assert.equal(calls.length, 0);
+
+  // After the macrotask (finishRun() has cleared isStreaming by now).
+  await new Promise((r) => setTimeout(r, 0));
+
+  assert.equal(calls.length, 1);
+  assert.deepEqual(calls[0].options, { triggerTurn: true });
+  assert.equal((calls[0].options as { deliverAs?: unknown }).deliverAs, undefined);
+});

package/src/resources/extensions/gsd/tests/file-change-validator.test.ts

@@ -116,6 +116,46 @@ test("effectiveFileChangeAllowlist keeps .gitignore auditable when management is
   assert.deepEqual(effectiveFileChangeAllowlist(["docs/**"], false), ["docs/**"]);
 });
 
+test("validateFileChanges excludes .gsd-backups/ migration snapshots from unexpected-change warnings", (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-file-change-validator-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  const backupFile = join(
+    base,
+    ".gsd-backups",
+    "migrate-1782703701330",
+    "M010",
+    "slices",
+    "S01",
+    "S01-ASSESSMENT.md",
+  );
+  mkdirSync(join(base, "src"), { recursive: true });
+  mkdirSync(join(backupFile, ".."), { recursive: true });
+
+  git(base, "init");
+  git(base, "config", "user.email", "test@example.com");
+  git(base, "config", "user.name", "Test User");
+
+  writeFileSync(join(base, "src", "app.ts"), "initial\n");
+  writeFileSync(backupFile, "legacy assessment\n");
+  git(base, "add", ".");
+  git(base, "commit", "-m", "initial");
+
+  writeFileSync(join(base, "src", "app.ts"), "updated\n");
+  writeFileSync(backupFile, "legacy assessment touched\n");
+  git(base, "add", ".");
+  git(base, "commit", "-m", "task commit");
+
+  const audit = validateFileChanges(base, ["src/app.ts"], []);
+  assert.ok(audit, "audit should be produced");
+  assert.deepEqual(audit!.unexpectedFiles, [], ".gsd-backups/ must not trigger warnings");
+  assert.equal(
+    audit!.violations.filter(v => v.severity === "warning").length,
+    0,
+    "no warnings when only source and migration backup files changed",
+  );
+});
+
 test("GSD-managed .gitignore edit swept into a task commit is not flagged", (t) => {
   const base = mkdtempSync(join(tmpdir(), "gsd-file-change-validator-"));
   t.after(() => rmSync(base, { recursive: true, force: true }));