@opengsd/gsd-pi 1.3.0-dev.65546769 → 1.3.0-dev.965d1788

package/src/resources/extensions/gsd/tests/complete-task.test.ts

@@ -380,6 +380,81 @@ console.log('\n=== complete-task: handler happy path ===');
   cleanup(dbPath);
 }
 
+// ═══════════════════════════════════════════════════════════════════════════
+// complete-task: Projection failure rolls DB completion back
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== complete-task: projection failure rolls DB completion back ===');
+{
+  const dbPath = tempDbPath();
+  openDatabase(dbPath);
+
+  const { basePath, planPath } = createTempProject();
+
+  insertMilestone({ id: 'M001', title: 'Test Milestone' });
+  insertSlice({ id: 'S01', milestoneId: 'M001', title: 'Test Slice' });
+
+  fs.unlinkSync(planPath);
+  fs.mkdirSync(planPath, { recursive: true });
+
+  const result = await handleCompleteTask(makeValidParams(), basePath);
+
+  assertTrue('error' in result, 'projection failure should return an error');
+  if ('error' in result) {
+    assertMatch(result.error, /projection write failed/, 'error should mention projection write failure');
+  }
+
+  const task = getTask('M001', 'S01', 'T01');
+  assertTrue(task !== null, 'task row should remain for retry');
+  assertEq(task!.status, 'pending', 'task status should be rolled back to pending');
+  assertEq(task!.completed_at, null, 'rolled back task should not keep completed_at');
+
+  const adapter = _getAdapter()!;
+  const evRows = adapter.prepare(
+    "SELECT * FROM verification_evidence WHERE task_id = 'T01' AND slice_id = 'S01' AND milestone_id = 'M001'"
+  ).all();
+  assertEq(evRows.length, 0, 'verification evidence should be deleted when projection rollback runs');
+
+  const summaryPath = path.join(path.dirname(planPath), 'T01-SUMMARY.md');
+  assertTrue(!fs.existsSync(summaryPath), 'SUMMARY.md should be removed so disk state stays pending');
+
+  cleanupDir(basePath);
+  cleanup(dbPath);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// complete-task: Handler does not re-render completed sibling summaries
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== complete-task: handler leaves completed sibling summaries untouched ===');
+{
+  const dbPath = tempDbPath();
+  openDatabase(dbPath);
+
+  const { basePath, planPath } = createTempProject();
+
+  insertMilestone({ id: 'M001', title: 'Test Milestone' });
+  insertSlice({ id: 'S01', milestoneId: 'M001', title: 'Test Slice', risk: 'high', depends: [], demo: 'basic functionality works', sequence: 1 });
+  insertTask({ id: 'T00', sliceId: 'S01', milestoneId: 'M001', status: 'complete', title: 'Already complete task', oneLiner: 'Previously completed' });
+  insertTask({ id: 'T02', sliceId: 'S01', milestoneId: 'M001', status: 'pending', title: 'Second task' });
+
+  const siblingSummaryPath = path.join(path.dirname(planPath), 'T00-SUMMARY.md');
+  const siblingSummaryContent = 'existing sibling summary marker\n';
+  fs.writeFileSync(siblingSummaryPath, siblingSummaryContent);
+
+  const result = await handleCompleteTask(makeValidParams(), basePath);
+
+  assertTrue(!('error' in result), 'handler should succeed without error');
+  assertEq(
+    fs.readFileSync(siblingSummaryPath, 'utf-8'),
+    siblingSummaryContent,
+    'complete-task should not re-render summaries for already-completed sibling tasks',
+  );
+
+  cleanupDir(basePath);
+  cleanup(dbPath);
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // complete-task: hard-blocker escalation with mid-execution escalation disabled
 // ═══════════════════════════════════════════════════════════════════════════

package/src/resources/extensions/gsd/tests/dashboard-overlay.test.ts

@@ -4,9 +4,10 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdirSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import { chmodSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { delimiter, join } from "node:path";
 import { tmpdir } from "node:os";
+import { performance } from "node:perf_hooks";
 
 import { GSDDashboardOverlay } from "../dashboard-overlay.ts";
 import type { UnitMetrics } from "../metrics.ts";
@@ -85,6 +86,58 @@ test("GSDDashboardOverlay non-identity refresh avoids reparsing preferences", as
   );
 });
 
+test("GSDDashboardOverlay render and scroll do not run environment doctor subprocesses", (t) => {
+  const basePath = join(
+    tmpdir(),
+    `gsd-dashboard-overlay-env-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+  );
+  const shimDir = join(
+    tmpdir(),
+    `gsd-dashboard-overlay-shim-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+  );
+  mkdirSync(basePath, { recursive: true });
+  mkdirSync(shimDir, { recursive: true });
+  writeFileSync(join(basePath, "package.json"), JSON.stringify({ engines: { node: ">=22.0.0" } }));
+
+  const posixNodeShim = join(shimDir, "node");
+  writeFileSync(posixNodeShim, "#!/bin/sh\nsleep 1\nexit 1\n");
+  chmodSync(posixNodeShim, 0o755);
+  writeFileSync(join(shimDir, "node.cmd"), "@echo off\r\nping -n 2 127.0.0.1 > nul\r\nexit /b 1\r\n");
+
+  const originalPath = process.env.PATH;
+  const overlay = new GSDDashboardOverlay({ requestRender() {} }, fakeTheme as any, () => {});
+  overlay.dispose();
+
+  t.after(() => {
+    if (originalPath === undefined) {
+      delete process.env.PATH;
+    } else {
+      process.env.PATH = originalPath;
+    }
+    rmSync(basePath, { recursive: true, force: true });
+    rmSync(shimDir, { recursive: true, force: true });
+  });
+
+  (overlay as any).loading = false;
+  (overlay as any).milestoneData = null;
+  (overlay as any).dashData = {
+    ...(overlay as any).dashData,
+    basePath,
+  };
+
+  process.env.PATH = `${shimDir}${delimiter}${originalPath ?? ""}`;
+  const start = performance.now();
+  overlay.render(100);
+  overlay.handleInput("j");
+  overlay.render(100);
+  const elapsed = performance.now() - start;
+
+  assert.ok(
+    elapsed < 500,
+    `rendering and scrolling should not wait for environment subprocesses, took ${Math.round(elapsed)}ms`,
+  );
+});
+
 function makeUnit(id: string, cost: number): UnitMetrics {
   return {
     type: "execute-task",

package/src/resources/extensions/gsd/tests/decisions-projection-from-memories.test.ts

@@ -142,6 +142,57 @@ test("backfill is idempotent — re-running over migrated rows is a no-op", () =
   }
 });
 
+test("backfill skips a decision whose memory insert throws and continues later rows", () => {
+  const base = makeTmpBase();
+  try {
+    seedRawDecision({
+      id: "D001",
+      when_context: "M001",
+      scope: "M001",
+      decision: "before poison",
+      choice: "A",
+      rationale: "first row",
+    });
+    seedRawDecision({
+      id: "D002",
+      when_context: "M001",
+      scope: "M001",
+      decision: "poison",
+      choice: "B",
+      rationale: "this insert throws",
+    });
+    seedRawDecision({
+      id: "D003",
+      when_context: "M001",
+      scope: "M001",
+      decision: "after poison",
+      choice: "C",
+      rationale: "tail row",
+    });
+
+    const adapter = _getAdapter();
+    assert.ok(adapter);
+    adapter.exec(`
+      CREATE TRIGGER fail_d002_memory_insert
+      BEFORE INSERT ON memories
+      WHEN json_extract(NEW.structured_fields, '$.sourceDecisionId') = 'D002'
+      BEGIN
+        SELECT RAISE(ABORT, 'poison decision D002');
+      END
+    `);
+
+    const written = backfillDecisionsToMemories();
+    assert.equal(written, 2, "one poisoned row should not abort the batch");
+    assert.deepEqual(
+      getAllDecisionsFromMemories().map((d) => d.id),
+      ["D001", "D003"],
+      "rows after the poisoned decision should still be migrated",
+    );
+  } finally {
+    cleanup(base);
+  }
+});
+
 // ─── Drift auto-heal ───────────────────────────────────────────────────────
 
 test("backfill auto-heals when a source decision's superseded_by changes after migration", () => {

package/src/resources/extensions/gsd/tests/dispatch-rule-coverage.test.ts

@@ -232,7 +232,7 @@ test("dispatch-rule-coverage: planning boundary without planner handoff → rese
   assertMatch(
     match,
     {
-      ruleName: "planning (no research, not S01) → research-slice",
+      ruleName: "planning (no research) → research-slice",
       action: "dispatch",
       unitType: "research-slice",
     },
@@ -240,6 +240,31 @@ test("dispatch-rule-coverage: planning boundary without planner handoff → rese
   );
 });
 
+test("dispatch-rule-coverage: S01 still researches when only milestone research exists", async (t) => {
+  const tmp = mkdtempSync(join(tmpdir(), "gsd-disp-cov-s01-research-"));
+  t.after(() => rmSync(tmp, { recursive: true, force: true }));
+
+  writeMilestoneFile(tmp, "M001", "CONTEXT", "# Context\n");
+  writeMilestoneFile(tmp, "M001", "ROADMAP", "# Roadmap\n");
+  writeMilestoneFile(tmp, "M001", "RESEARCH", "# Milestone Research\n");
+
+  const state = makeState({
+    phase: "planning",
+    activeSlice: { id: "S01", title: "First Slice" },
+    nextAction: "Plan slice S01 (First Slice).",
+  });
+  const match = await findFirstMatch(makeCtx(tmp, state));
+  assertMatch(
+    match,
+    {
+      ruleName: "planning (no research) → research-slice",
+      action: "dispatch",
+      unitType: "research-slice",
+    },
+    "S01 missing slice research despite milestone research",
+  );
+});
+
 test("dispatch-rule-coverage: executing with task plan present → execute-task", async (t) => {
   const tmp = mkdtempSync(join(tmpdir(), "gsd-disp-cov-exec-"));
   t.after(() => rmSync(tmp, { recursive: true, force: true }));

package/src/resources/extensions/gsd/tests/doctor-forensics-db-open-regression.test.ts

@@ -1,10 +1,18 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
-import { closeDatabase } from "../gsd-db.ts";
+import {
+  _getAdapter,
+  closeDatabase,
+  getHierarchyCompletionCounts,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+  openDatabase,
+} from "../gsd-db.ts";
 import { buildForensicReport } from "../forensics.ts";
 import { handleDoctor } from "../commands-handlers.ts";
 import { withCommandCwd } from "../commands/context.ts";
@@ -23,6 +31,66 @@ test("#5194 forensics opens DB before computing completion counts", async (t) =>
   assert.equal(report.dbCompletionCounts?.tasksTotal, 0);
 });
 
+test("#968 completion counts use fixed aggregate queries and canonical closed statuses", (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-forensics-counts-"));
+  const dbPath = join(base, "gsd.db");
+  t.after(() => {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  });
+
+  openDatabase(dbPath);
+
+  insertMilestone({ id: "M001", status: "complete" });
+  insertMilestone({ id: "M002", status: "active" });
+  insertMilestone({ id: "M003", status: "closed" });
+
+  insertSlice({ milestoneId: "M001", id: "S01", status: "done" });
+  insertSlice({ milestoneId: "M001", id: "S02", status: "pending" });
+  insertSlice({ milestoneId: "M002", id: "S01", status: "skipped" });
+  insertSlice({ milestoneId: "M003", id: "S01", status: "active" });
+
+  insertTask({ milestoneId: "M001", sliceId: "S01", id: "T01", status: "complete" });
+  insertTask({ milestoneId: "M001", sliceId: "S01", id: "T02", status: "done" });
+  insertTask({ milestoneId: "M001", sliceId: "S02", id: "T01", status: "skipped" });
+  insertTask({ milestoneId: "M002", sliceId: "S01", id: "T01", status: "closed" });
+  insertTask({ milestoneId: "M002", sliceId: "S01", id: "T02", status: "pending" });
+  insertTask({ milestoneId: "M003", sliceId: "S01", id: "T01", status: "active" });
+
+  const adapter = _getAdapter()!;
+  const originalPrepare = adapter.prepare.bind(adapter);
+  const preparedSql: string[] = [];
+  adapter.prepare = (sql) => {
+    preparedSql.push(sql);
+    return originalPrepare(sql);
+  };
+
+  assert.deepEqual(getHierarchyCompletionCounts(), {
+    milestones: 2,
+    milestonesTotal: 3,
+    slices: 2,
+    slicesTotal: 4,
+    tasks: 4,
+    tasksTotal: 6,
+  });
+
+  assert.equal(preparedSql.length, 3);
+  assert.ok(preparedSql.every((sql) => /COUNT\(\*\)/i.test(sql)));
+  assert.doesNotMatch(preparedSql.join("\n"), /SELECT\s+\*/i);
+});
+
+test("#968 forensics completion counts do not re-query slices and tasks", () => {
+  const source = readFileSync(join(process.cwd(), "src/resources/extensions/gsd/forensics.ts"), "utf-8");
+  const start = source.indexOf("function getDbCompletionCounts()");
+  const end = source.indexOf("// ─── Anomaly Detectors", start);
+  assert.notEqual(start, -1);
+  assert.notEqual(end, -1);
+  const body = source.slice(start, end);
+
+  assert.match(body, /getHierarchyCompletionCounts\(\)/);
+  assert.doesNotMatch(body, /getAllMilestones|getMilestoneSlices|getSliceTasks/);
+});
+
 test("#5194 doctor command does not emit false db_unavailable when gsd.db exists", async (t) => {
   const base = mkdtempSync(join(tmpdir(), "gsd-doctor-db-open-"));
   t.after(() => rmSync(base, { recursive: true, force: true }));

package/src/resources/extensions/gsd/tests/doctor-providers.test.ts

@@ -20,6 +20,7 @@ import { tmpdir } from "node:os";
 
 import {
   runProviderChecks,
+  runProviderChecksAsync,
   formatProviderReport,
   summariseProviderIssues,
   type ProviderCheckResult,
@@ -47,6 +48,26 @@ function withEnv(vars: Record<string, string | undefined>, fn: () => void): void
   }
 }
 
+async function withEnvAsync(vars: Record<string, string | undefined>, fn: () => Promise<void>): Promise<void> {
+  const saved: Record<string, string | undefined> = {};
+  for (const [k, v] of Object.entries(vars)) {
+    saved[k] = process.env[k];
+    if (v === undefined) {
+      delete process.env[k];
+    } else {
+      process.env[k] = v;
+    }
+  }
+  try {
+    await fn();
+  } finally {
+    for (const [k, v] of Object.entries(saved)) {
+      if (v === undefined) delete process.env[k];
+      else process.env[k] = v;
+    }
+  }
+}
+
 function withCwd(nextCwd: string, fn: () => void): void {
   const saved = process.cwd();
   process.chdir(nextCwd);
@@ -57,6 +78,22 @@ function withCwd(nextCwd: string, fn: () => void): void {
   }
 }
 
+async function withCwdAsync(nextCwd: string, fn: () => Promise<void>): Promise<void> {
+  const saved = process.cwd();
+  process.chdir(nextCwd);
+  try {
+    await fn();
+  } finally {
+    process.chdir(saved);
+  }
+}
+
+function normalizeProviderResults(results: ProviderCheckResult[]): string[] {
+  return results
+    .map(r => `${r.name}|${r.label}|${r.category}|${r.status}|${r.message}|${r.detail ?? ""}|${r.required}`)
+    .sort();
+}
+
 const PRESENT_TEST_VALUE = "configured";
 
 // ─── formatProviderReport ─────────────────────────────────────────────────────
@@ -377,6 +414,76 @@ test("runProviderChecks detects custom provider keys from models.json", () => {
   rmSync(tmpHome, { recursive: true, force: true });
 });
 
+test("runProviderChecksAsync matches sync for models.json keys and PATH CLI checks", async () => {
+  const tmpHome = realpathSync(mkdtempSync(join(tmpdir(), "gsd-providers-async-home-")));
+  const repo = realpathSync(mkdtempSync(join(tmpdir(), "gsd-providers-async-repo-")));
+  const agentDir = join(tmpHome, ".gsd", "agent");
+  const binDir = join(tmpHome, "bin");
+  mkdirSync(agentDir, { recursive: true });
+  mkdirSync(binDir, { recursive: true });
+  mkdirSync(join(repo, ".gsd"), { recursive: true });
+
+  writeFileSync(
+    join(repo, ".gsd", "PREFERENCES.md"),
+    [
+      "---",
+      "models:",
+      "  execution:",
+      "    model: custom-model",
+      "    provider: custom-provider",
+      "  validation:",
+      "    model: gemini-2.5-pro",
+      "    provider: google-gemini-cli",
+      "---",
+      "",
+    ].join("\n"),
+  );
+  writeFileSync(join(agentDir, "models.json"), JSON.stringify({
+    providers: {
+      "custom-provider": {
+        api: "openai-completions",
+        apiKey: "x",
+        baseUrl: "https://example.invalid/v1",
+        models: [{ id: "custom-model", name: "Custom Model" }],
+      },
+    },
+  }));
+
+  const fakeGemini = join(binDir, "gemini");
+  writeFileSync(fakeGemini, "#!/bin/sh\necho mock\n");
+  chmodSync(fakeGemini, 0o755);
+
+  try {
+    await withEnvAsync({
+      HOME: tmpHome,
+      CUSTOM_PROVIDER_API_KEY: undefined,
+      GEMINI_API_KEY: undefined,
+      GOOGLE_API_KEY: undefined,
+      PATH: binDir,
+    }, async () => {
+      await withCwdAsync(repo, async () => {
+        const syncResults = runProviderChecks();
+        const asyncResults = await runProviderChecksAsync();
+
+        assert.deepEqual(normalizeProviderResults(asyncResults), normalizeProviderResults(syncResults));
+        assert.equal(
+          asyncResults.find(r => r.name === "custom-provider")?.status,
+          "ok",
+          "models.json apiKey should satisfy custom provider auth",
+        );
+        assert.equal(
+          asyncResults.find(r => r.name === "google-gemini-cli")?.status,
+          "ok",
+          "gemini CLI binary should satisfy explicit CLI provider",
+        );
+      });
+    });
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+    rmSync(tmpHome, { recursive: true, force: true });
+  }
+});
+
 test("runProviderChecks reports missing custom provider key without models.json apiKey", () => {
   const tmpHome = realpathSync(mkdtempSync(join(tmpdir(), "gsd-providers-custom-missing-home-")));
   const repo = realpathSync(mkdtempSync(join(tmpdir(), "gsd-providers-custom-missing-repo-")));

package/src/resources/extensions/gsd/tests/exec-graceful-kill.test.ts

@@ -63,6 +63,44 @@ function wallClockGuard<T>(promise: Promise<T>, ms: number): Promise<T> {
   ]);
 }
 
+test(
+  'runExecSandbox: aborted signal terminates promptly without waiting for timeout',
+  { timeout: 10_000 },
+  async (t) => {
+    const base = freshBase();
+    t.after(() => cleanup(base));
+
+    const controller = new AbortController();
+    controller.abort();
+    const TIMEOUT_MS = 10_000;
+
+    const start = Date.now();
+    const result = await wallClockGuard(
+      runExecSandbox(
+        { runtime: 'node', script: 'setTimeout(() => {}, 30_000);', timeout_ms: TIMEOUT_MS },
+        baseOpts(base, {
+          signal: controller.signal,
+          kill_grace_ms: 500,
+          force_resolve_delay_ms: 2_000,
+        }),
+      ),
+      5_000,
+    );
+    const elapsed = Date.now() - start;
+
+    assert.equal(result.aborted, true, 'aborted signal must be recorded on the sandbox result');
+    assert.equal(result.timed_out, false, 'client abort must not be reported as a sandbox timeout');
+    assert.ok(elapsed < TIMEOUT_MS, `expected abort before ${TIMEOUT_MS}ms timeout, took ${elapsed}ms`);
+    assert.ok(
+      result.duration_ms < TIMEOUT_MS,
+      `expected result duration before timeout, got ${result.duration_ms}ms`,
+    );
+    const meta = JSON.parse(readFileSync(result.meta_path, 'utf-8'));
+    assert.equal(meta.aborted, true, 'meta.json must persist the aborted marker');
+    assert.equal(meta.timed_out, false, 'meta.json must not report timed_out when abort caused the kill');
+  },
+);
+
 // Clean up a detached child (and its process group) that a large kill_grace_ms
 // intentionally leaves alive past the force-resolve deadline.
 function cleanupByPidFile(pidFile: string): void {

package/src/resources/extensions/gsd/tests/exec-tool.test.ts

@@ -3,7 +3,7 @@ import assert from "node:assert/strict";
 
 import { registerExecTools } from "../bootstrap/exec-tools.ts";
 import { executeGsdExec, executeUatExec } from "../tools/exec-tool.ts";
-import type { ExecSandboxRequest, ExecSandboxResult } from "../exec-sandbox.ts";
+import type { ExecSandboxOptions, ExecSandboxRequest, ExecSandboxResult } from "../exec-sandbox.ts";
 
 function makeExecResult(request: ExecSandboxRequest): ExecSandboxResult {
   return {
@@ -12,6 +12,7 @@ function makeExecResult(request: ExecSandboxRequest): ExecSandboxResult {
     exit_code: 0,
     signal: null,
     timed_out: false,
+    aborted: false,
     force_resolved: false,
     duration_ms: 1,
     stdout_bytes: 12,
@@ -52,6 +53,49 @@ test("executeUatExec accepts evidence-mode aliases for intent", async () => {
   assert.equal(requests[0]?.metadata?.intent, "uat-artifact-check");
 });
 
+test("executeGsdExec passes AbortSignal into sandbox options", async () => {
+  const controller = new AbortController();
+  let capturedSignal: AbortSignal | undefined;
+
+  const result = await executeGsdExec(
+    { runtime: "bash", script: "sleep 60" },
+    {
+      baseDir: "/tmp/gsd-exec-abort-signal-test",
+      preferences: null,
+      signal: controller.signal,
+      run: async (request, opts: ExecSandboxOptions) => {
+        capturedSignal = opts.signal;
+        return makeExecResult(request);
+      },
+    },
+  );
+
+  assert.equal(result.isError, false);
+  assert.equal(capturedSignal, controller.signal);
+});
+
+test("gsd_exec surfaces aborted child termination distinctly from a clean exit", async () => {
+  const result = await executeGsdExec(
+    { runtime: "bash", script: "trap 'exit 0' TERM; sleep 60" },
+    {
+      baseDir: "/tmp/gsd-exec-aborted-test",
+      preferences: null,
+      run: async (request) => ({
+        ...makeExecResult(request),
+        aborted: true,
+        exit_code: 0,
+        signal: null,
+        digest: "[no stdout — aborted]",
+      }),
+    },
+  );
+
+  assert.equal(result.isError, true, "an aborted run must be an error even if the child exits 0");
+  assert.equal(result.details?.aborted, true, "details must expose aborted");
+  const text = result.content.map((c) => c.text ?? "").join("\n");
+  assert.match(text, /exit=aborted/, "summary must distinguish an aborted result");
+});
+
 test("gsd_exec surfaces a force-resolved (D-state) kill distinctly from a clean exit", async () => {
   // A hard-deadline force-resolve sets force_resolved=true with a synthetic SIGKILL
   // signal and null exit code. The tool result must carry that flag in details and

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 }));