@opengsd/gsd-pi 1.3.0 → 1.4.0

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

@@ -0,0 +1,107 @@
+// Project/App: gsd-pi
+// File Purpose: Schema-2 compat marker tests — the `planning` field.
+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 {
+  readCompatMarker,
+  writeCompatMarker,
+  EMPTY_MARKER,
+  COMPAT_MARKER_SCHEMA,
+} from "../compat/compat-marker.ts";
+
+const tmpDirs: string[] = [];
+function makeTmpBase(): string {
+  const base = mkdtempSync(join(tmpdir(), `gsd-pm-${randomUUID()}`));
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  tmpDirs.push(base);
+  return base;
+}
+afterEach(() => {
+  for (const d of tmpDirs) { try { rmSync(d, { recursive: true, force: true }); } catch { /* */ } }
+  tmpDirs.length = 0;
+});
+
+test("schema version is 2", () => {
+  assert.equal(COMPAT_MARKER_SCHEMA, 2);
+});
+
+test("EMPTY_MARKER has planning inactive with empty maps", () => {
+  assert.deepEqual(EMPTY_MARKER.planning, {
+    active: false,
+    layout: null,
+    projections: {},
+    passthrough: {},
+  });
+});
+
+test("writeCompatMarker then readCompatMarker round-trips planning field", () => {
+  const base = makeTmpBase();
+  const marker = {
+    schema: 2,
+    lastWriter: "gsd-pi" as const,
+    lastProjectedAt: "2026-06-21T00:00:00.000Z",
+    projections: {},
+    planning: {
+      active: true,
+      layout: "flat-phases" as const,
+      projections: {
+        "ROADMAP.md": { sha: "abc", entities: ["M001"] },
+      },
+      passthrough: {
+        "codebase/STACK.md": { sha: "def", entities: [] },
+      },
+    },
+    piVersion: "1.4.0",
+  };
+  writeCompatMarker(base, marker);
+  const read = readCompatMarker(base);
+  assert.deepEqual(read.planning, marker.planning);
+});
+
+test("readCompatMarker promotes a schema-1 marker by defaulting planning inactive", () => {
+  const base = makeTmpBase();
+  // Hand-write a schema-1 marker (no planning field).
+  const v1 = {
+    schema: 1,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "2026-06-01T00:00:00.000Z",
+    projections: { "x.md": { sha: "1", entities: [] } },
+    piVersion: "1.3.0",
+  };
+  writeFileSync(join(base, ".gsd", ".compat.json"), JSON.stringify(v1), "utf-8");
+
+  const read = readCompatMarker(base);
+  // Promotion: planning defaults inactive. (raw schema value preserved on read;
+  // promotion is at read-time, a rewrite would emit schema 2.)
+  assert.deepEqual(read.planning, { active: false, layout: null, projections: {}, passthrough: {} });
+});
+
+test("emptyMarker returns independent planning objects (no shared reference)", () => {
+  // Mutating one empty-marker read must not pollute another.
+  const base1 = makeTmpBase();
+  const base2 = makeTmpBase();
+  const m1 = readCompatMarker(base1);
+  m1.planning!.projections["x"] = { sha: "1", entities: [] };
+  const m2 = readCompatMarker(base2);
+  assert.equal(m2.planning!.projections["x"], undefined);
+});
+
+test("readCompatMarker quarantines a marker with invalid planning field", () => {
+  const base = makeTmpBase();
+  const bad = {
+    schema: 2,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "2026-06-21T00:00:00.000Z",
+    projections: {},
+    planning: { active: "not-a-boolean" }, // invalid
+    piVersion: "1.4.0",
+  };
+  writeFileSync(join(base, ".gsd", ".compat.json"), JSON.stringify(bad), "utf-8");
+  const read = readCompatMarker(base);
+  assert.deepEqual(read.planning, { active: false, layout: null, projections: {}, passthrough: {} });
+});

package/src/resources/extensions/gsd/tests/planning-projection-hook.test.ts

@@ -0,0 +1,123 @@
+// Project/App: gsd-pi
+// File Purpose: Verifies renderAllFromDb projects to .planning/ when active.
+import test, { afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+import { renderAllFromDb } from "../markdown-renderer.ts";
+import { openDatabase, closeDatabase, insertMilestone, insertSlice } from "../gsd-db.ts";
+import { writeCompatMarker, readCompatMarker } from "../compat/compat-marker.ts";
+
+const tmpDirs: string[] = [];
+function makeTmp(): string {
+  const base = mkdtempSync(join(tmpdir(), `gsd-pph-${randomUUID()}`));
+  mkdirSync(join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks"), { recursive: true });
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "T", status: "active" });
+  insertSlice({
+    milestoneId: "M001", id: "S01", title: "T", status: "pending",
+    risk: "low", depends: [], demo: "", sequence: 1,
+  });
+  tmpDirs.push(base);
+  return base;
+}
+afterEach(() => {
+  closeDatabase();
+  for (const d of tmpDirs) { try { rmSync(d, { recursive: true, force: true }); } catch { /* */ } }
+  tmpDirs.length = 0;
+});
+
+test("renderAllFromDb projects to .planning/ when marker.planning.active", async () => {
+  const base = makeTmp();
+  writeCompatMarker(base, {
+    schema: 2,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "",
+    projections: {},
+    planning: { active: true, layout: "flat-phases", projections: {}, passthrough: {} },
+    piVersion: "1.4.0",
+  });
+
+  await renderAllFromDb(base);
+  assert.ok(
+    existsSync(join(base, ".planning", "ROADMAP.md")),
+    ".planning/ROADMAP.md should be projected",
+  );
+});
+
+test("renderAllFromDb does NOT project to .planning/ when marker.planning inactive", async () => {
+  const base = makeTmp();
+  // Default marker: planning inactive.
+  await renderAllFromDb(base);
+  assert.ok(
+    !existsSync(join(base, ".planning")),
+    ".planning/ should not be created when inactive",
+  );
+});
+
+test("renderAllFromDb records planning SHAs into marker.planning.projections", async () => {
+  // Regression test for COMMENT:3449128453: writePlanningDirectory wrote files
+  // but never updated marker.planning.projections, so the reconcile detector
+  // always saw an empty baseline and never reported drift.
+  const base = makeTmp();
+  writeCompatMarker(base, {
+    schema: 2,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "",
+    projections: {},
+    planning: { active: true, layout: "flat-phases", projections: {}, passthrough: {} },
+    piVersion: "1.4.0",
+  });
+
+  await renderAllFromDb(base);
+
+  const marker = readCompatMarker(base);
+  const planningKeys = Object.keys(marker.planning?.projections ?? {});
+  assert.ok(planningKeys.length > 0, "marker.planning.projections must be non-empty after projection");
+
+  // Every recorded entry must have a non-empty sha and an entities array.
+  for (const [rel, entry] of Object.entries(marker.planning!.projections)) {
+    assert.ok(typeof entry.sha === "string" && entry.sha.length > 0, `SHA missing for ${rel}`);
+    assert.ok(Array.isArray(entry.entities), `entities must be an array for ${rel}`);
+  }
+
+  // ROADMAP.md must be among the recorded SHAs.
+  assert.ok(
+    planningKeys.some((k) => k === "ROADMAP.md"),
+    `expected ROADMAP.md in projections, got ${JSON.stringify(planningKeys)}`,
+  );
+});
+
+test("renderAllFromDb planning SHA baseline survives a subsequent readCompatMarker", async () => {
+  // Regression test for COMMENT:3449128459: after renderAllFromDb the marker
+  // must durably contain planning SHAs so a fresh read (e.g. handleSync's
+  // marker stamp) does not clobber them.
+  const base = makeTmp();
+  writeCompatMarker(base, {
+    schema: 2,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "",
+    projections: {},
+    planning: { active: true, layout: "flat-phases", projections: {}, passthrough: {} },
+    piVersion: "1.4.0",
+  });
+
+  await renderAllFromDb(base);
+
+  // Simulate handleSync's marker stamp: read → mutate timestamps → write back.
+  const m = readCompatMarker(base);
+  m.lastWriter = "gsd-pi";
+  m.lastProjectedAt = new Date().toISOString();
+  const { writeCompatMarker: wm } = await import("../compat/compat-marker.ts");
+  wm(base, m);
+
+  // Planning SHAs must still be present after the stamp.
+  const after = readCompatMarker(base);
+  assert.ok(
+    Object.keys(after.planning?.projections ?? {}).length > 0,
+    "planning SHAs must survive a subsequent readCompatMarker + writeCompatMarker cycle",
+  );
+});

package/src/resources/extensions/gsd/tests/planning-round-trip-property.test.ts

@@ -0,0 +1,164 @@
+// Project/App: gsd-pi
+// File Purpose: Round-trip property test for .planning/ parity.
+// import → render → import must produce a stable milestone/slice hierarchy.
+import test, { afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { cpSync, mkdtempSync, mkdirSync, rmSync, readdirSync, readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+import {
+  openDatabase,
+  closeDatabase,
+  getAllMilestones,
+  getMilestoneSlices,
+  getSliceTasks,
+  clearEngineHierarchy,
+} from "../gsd-db.ts";
+import { parsePlanningDirectory } from "../migrate/parser.ts";
+import { transformToGSD } from "../migrate/transformer.ts";
+import { writeGSDDirectory } from "../migrate/writer.ts";
+import { writePlanningDirectory } from "../migrate/planning-writer.ts";
+import { migrateHierarchyToDb } from "../md-importer.ts";
+import { invalidateStateCache } from "../state.ts";
+import { writeCompatMarker } from "../compat/compat-marker.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const FIXTURE_ROOT = join(__dirname, "__fixtures__", "round-trip");
+const tmpDirs: string[] = [];
+afterEach(() => {
+  closeDatabase();
+  for (const d of tmpDirs) { try { rmSync(d, { recursive: true, force: true }); } catch { /* */ } }
+  tmpDirs.length = 0;
+});
+
+function copyFixture(name: string): string {
+  const base = mkdtempSync(join(tmpdir(), `gsd-prt-${randomUUID()}`));
+  cpSync(join(FIXTURE_ROOT, name), base, { recursive: true });
+  // The fixture only ships .planning/. The DB needs a .gsd/ dir to live in.
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  tmpDirs.push(base);
+  return base;
+}
+
+interface Snapshot {
+  ms: Array<{ id: string; title: string }>;
+  slices: Array<{ mid: string; id: string; title: string }>;
+  tasks: Array<{ mid: string; sid: string; id: string; title: string }>;
+}
+
+function snapshotHierarchy(): Snapshot {
+  const ms = getAllMilestones().map((m) => ({ id: m.id, title: m.title }));
+  const slices: Snapshot["slices"] = [];
+  const tasks: Snapshot["tasks"] = [];
+  for (const m of ms) {
+    for (const s of getMilestoneSlices(m.id)) {
+      slices.push({ mid: m.id, id: s.id, title: s.title });
+      for (const t of getSliceTasks(m.id, s.id)) {
+        tasks.push({ mid: m.id, sid: s.id, id: t.id, title: t.title });
+      }
+    }
+  }
+  return { ms, slices, tasks };
+}
+
+/**
+ * Materialize a .planning/ tree into the gsd-pi DB:
+ *   parse .planning/ → transform to GSD model → write .gsd/ → import to DB
+ */
+async function importPlanningToDb(base: string): Promise<void> {
+  const parsed = await parsePlanningDirectory(join(base, ".planning"));
+  const gsd = transformToGSD(parsed);
+  await writeGSDDirectory(gsd, base);
+  migrateHierarchyToDb(base);
+  invalidateStateCache();
+}
+
+test(".planning/ round-trip: import → render → import produces stable milestone/slice ids", async () => {
+  const base = copyFixture("planning-flat-phases");
+  openDatabase(join(base, ".gsd", "gsd.db"));
+
+  // Pass 1: import fixture .planning/ → DB
+  await importPlanningToDb(base);
+  const snap1 = snapshotHierarchy();
+  assert.ok(snap1.ms.length > 0, "expected at least one milestone after first import");
+  assert.ok(snap1.slices.length > 0, "expected at least one slice after first import");
+
+  // Project DB → .planning/ (the new writer). Activate the marker first so the
+  // projection hook in renderAllFromDb fires; but we call writePlanningDirectory
+  // directly here to isolate the property under test.
+  writeCompatMarker(base, {
+    schema: 2,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "",
+    projections: {},
+    planning: { active: true, layout: "flat-phases", projections: {}, passthrough: {} },
+    piVersion: "1.4.0",
+  });
+  await writePlanningDirectory(base, "flat-phases");
+  assert.ok(existsSync(join(base, ".planning", "ROADMAP.md")), "projection should write ROADMAP.md");
+
+  // Pass 2: clear DB, re-import the projected .planning/ → DB
+  clearEngineHierarchy();
+  await importPlanningToDb(base);
+  const snap2 = snapshotHierarchy();
+
+  // Property: hierarchy ids stable across the round-trip.
+  assert.deepEqual(
+    snap2.ms.map((m) => m.id),
+    snap1.ms.map((m) => m.id),
+    "milestone ids drifted across round-trip",
+  );
+  assert.deepEqual(
+    snap2.slices.map((s) => `${s.mid}/${s.id}`),
+    snap1.slices.map((s) => `${s.mid}/${s.id}`),
+    "slice ids drifted across round-trip",
+  );
+});
+
+test(".planning/ round-trip: re-projecting is idempotent (stable .planning/ content)", async () => {
+  const base = copyFixture("planning-flat-phases");
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  await importPlanningToDb(base);
+  writeCompatMarker(base, {
+    schema: 2,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "",
+    projections: {},
+    planning: { active: true, layout: "flat-phases", projections: {}, passthrough: {} },
+    piVersion: "1.4.0",
+  });
+
+  const snapshotPlanningFiles = (b: string): Record<string, string> => {
+    const out: Record<string, string> = {};
+    const walk = (dir: string) => {
+      for (const e of readdirSync(dir, { withFileTypes: true })) {
+        const p = join(dir, e.name);
+        if (e.isDirectory()) walk(p);
+        else if (e.name.endsWith(".md")) {
+          out[p.replace(b + "/", "")] = readFileSyncNormalized(p);
+        }
+      }
+    };
+    walk(join(b, ".planning"));
+    return out;
+  };
+  const readFileSyncNormalized = (p: string): string => {
+    return readFileSync(p, "utf-8")
+      .replace(/\r\n/g, "\n")
+      .replace(/[ \t]+\n/g, "\n")
+      // STATE.md carries a write-time timestamp that legitimately differs
+      // between projections — strip it so idempotency is checked on content.
+      .replace(/last_updated: ".*"/g, 'last_updated: "<ts>"');
+  };
+
+  await writePlanningDirectory(base, "flat-phases");
+  const after1 = snapshotPlanningFiles(base);
+
+  await writePlanningDirectory(base, "flat-phases");
+  const after2 = snapshotPlanningFiles(base);
+
+  assert.deepEqual(after2, after1, "re-projecting .planning/ changed content");
+});

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

@@ -0,0 +1,82 @@
+// Project/App: gsd-pi
+// File Purpose: Tests for the DB → .planning/ projection writer.
+import test, { afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+import { writePlanningDirectory } from "../migrate/planning-writer.ts";
+import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask } from "../gsd-db.ts";
+
+const tmpDirs: string[] = [];
+function makeTmp(): string {
+  const base = mkdtempSync(join(tmpdir(), `gsd-pw-${randomUUID()}`));
+  mkdirSync(join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks"), { recursive: true });
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Foundation", status: "active" });
+  insertSlice({
+    milestoneId: "M001", id: "S01", title: "Set up tooling", status: "pending",
+    risk: "low", depends: [], demo: "build runs", sequence: 1,
+  });
+  insertTask({
+    milestoneId: "M001", sliceId: "S01", id: "T01", title: "Init repo",
+    status: "pending", sequence: 1,
+    planning: { estimate: "30m" },
+  });
+  tmpDirs.push(base);
+  return base;
+}
+afterEach(() => {
+  closeDatabase();
+  for (const d of tmpDirs) { try { rmSync(d, { recursive: true, force: true }); } catch { /* */ } }
+  tmpDirs.length = 0;
+});
+
+test("writePlanningDirectory emits flat-phases layout: ROADMAP.md + phases/NN-slug/", async () => {
+  const base = makeTmp();
+  await writePlanningDirectory(base, "flat-phases");
+
+  assert.ok(existsSync(join(base, ".planning", "ROADMAP.md")), "ROADMAP.md missing");
+  assert.ok(existsSync(join(base, ".planning", "STATE.md")), "STATE.md missing");
+  assert.ok(existsSync(join(base, ".planning", "PROJECT.md")), "PROJECT.md missing");
+
+  const phaseDirs = readdirSync(join(base, ".planning", "phases"), { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name);
+  assert.ok(phaseDirs.length >= 1, `expected ≥1 phase dir, got ${JSON.stringify(phaseDirs)}`);
+  assert.ok(/^01-/.test(phaseDirs[0]!), `phase dir should start with 01-, got ${phaseDirs[0]}`);
+});
+
+test("writePlanningDirectory emits phase plan file with XML structure", async () => {
+  const base = makeTmp();
+  await writePlanningDirectory(base, "flat-phases");
+
+  const phaseDir = readdirSync(join(base, ".planning", "phases"), { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name)[0]!;
+  const planFiles = readdirSync(join(base, ".planning", "phases", phaseDir))
+    .filter((f) => f.endsWith("PLAN.md"));
+  assert.ok(planFiles.length >= 1, "expected ≥1 plan file");
+  const plan = readFileSync(join(base, ".planning", "phases", phaseDir, planFiles[0]!), "utf-8");
+  // Planning plans use XML tags per parsers.ts extractXmlTag
+  assert.match(plan, /<objective>/);
+  assert.match(plan, /<tasks>/);
+});
+
+test("writePlanningDirectory is idempotent: writing twice produces stable content", async () => {
+  const base = makeTmp();
+  await writePlanningDirectory(base, "flat-phases");
+  const snap = (p: string) => readFileSync(p, "utf-8").replace(/\r\n/g, "\n").replace(/[ \t]+\n/g, "\n");
+  const roadmap1 = snap(join(base, ".planning", "ROADMAP.md"));
+  await writePlanningDirectory(base, "flat-phases");
+  const roadmap2 = snap(join(base, ".planning", "ROADMAP.md"));
+  assert.equal(roadmap2, roadmap1);
+});
+
+test("writePlanningDirectory throws for unsupported layouts", async () => {
+  const base = makeTmp();
+  await assert.rejects(() => writePlanningDirectory(base, "multi-milestone"), /not yet supported/);
+  await assert.rejects(() => writePlanningDirectory(base, "legacy-milestone-dir"), /not yet supported/);
+});

package/src/resources/extensions/gsd/tests/post-execution-checks.test.ts

@@ -10,7 +10,8 @@
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
 import { tmpdir } from "node:os";
-import { mkdirSync, mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import fs, { mkdirSync, mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { syncBuiltinESMExports } from "node:module";
 import { join } from "node:path";
 
 import {
@@ -769,6 +770,52 @@ describe("checkCrossTaskSignatures", () => {
       rmSync(tempDir, { recursive: true, force: true });
     }
   });
+
+  test("caches prior task signature reads across calls for the same slice", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "post-exec-cache-"));
+    mkdirSync(join(tempDir, "src"), { recursive: true });
+
+    const priorPath = join(tempDir, "src", "utils.ts");
+    writeFileSync(
+      priorPath,
+      "export function process(data: string): boolean { return true; }"
+    );
+    writeFileSync(
+      join(tempDir, "src", "api.ts"),
+      "export function process(data: string): boolean { return false; }"
+    );
+
+    const originalReadFileSync = fs.readFileSync;
+    let priorReads = 0;
+
+    fs.readFileSync = ((...args: unknown[]) => {
+      const path = args[0];
+      if (path === priorPath) priorReads++;
+      return originalReadFileSync(...(args as Parameters<typeof fs.readFileSync>));
+    }) as typeof fs.readFileSync;
+    syncBuiltinESMExports();
+
+    try {
+      const priorTask = createTask({
+        id: "T01",
+        slice_id: "S01",
+        key_files: ["src/utils.ts"],
+      });
+      const currentTask = createTask({
+        id: "T02",
+        slice_id: "S01",
+        key_files: ["src/api.ts"],
+      });
+
+      assert.deepEqual(checkCrossTaskSignatures(currentTask, [priorTask], tempDir), []);
+      assert.deepEqual(checkCrossTaskSignatures(currentTask, [priorTask], tempDir), []);
+      assert.equal(priorReads, 1);
+    } finally {
+      fs.readFileSync = originalReadFileSync;
+      syncBuiltinESMExports();
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
 });
 
 // ─── Pattern Consistency Tests ───────────────────────────────────────────────

package/src/resources/extensions/gsd/tests/post-mutation-hook.test.ts

@@ -10,7 +10,7 @@ import * as os from 'node:os';
 import { openDatabase, closeDatabase } from '../gsd-db.ts';
 import { handleCompleteTask } from '../tools/complete-task.ts';
 import { readEvents } from '../workflow-events.ts';
-import { readManifest } from '../workflow-manifest.ts';
+import { flushManifest, readManifest } from '../workflow-manifest.ts';
 
 function tempDir(): string {
   return fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-post-hook-'));
@@ -115,8 +115,9 @@ test('post-mutation-hook: state-manifest.json exists after handleCompleteTask',
     const result = await handleCompleteTask(makeCompleteTaskParams(), base);
     assert.ok(!('error' in result), `handler should succeed, got: ${JSON.stringify(result)}`);
 
+    await flushManifest(base);
     const manifestPath = path.join(base, '.gsd', 'state-manifest.json');
-    assert.ok(fs.existsSync(manifestPath), 'state-manifest.json should exist after handler completes');
+    assert.ok(fs.existsSync(manifestPath), 'state-manifest.json should exist after manifest flush');
   } finally {
     closeDatabase();
     cleanupDir(base);
@@ -131,6 +132,7 @@ test('post-mutation-hook: manifest has version 1 and includes completed task', a
 
   try {
     await handleCompleteTask(makeCompleteTaskParams(), base);
+    await flushManifest(base);
 
     const manifest = readManifest(base);
     assert.ok(manifest !== null, 'manifest should be readable');

package/src/resources/extensions/gsd/tests/preferences.test.ts

@@ -10,7 +10,7 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, rmSync, utimesSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
 import {
@@ -24,6 +24,7 @@ import {
   loadProjectGSDPreferences,
   parsePreferencesMarkdown,
   renderPreferencesForSystemPrompt,
+  clearGSDPreferencesCache,
   _resetParseWarningFlag,
 } from "../preferences.ts";
 import { collectPreferenceDiagnostics, formatPreferenceDiagnostic } from "../preferences-diagnostics.ts";
@@ -446,6 +447,51 @@ test("loadEffectiveGSDPreferences preserves disabled_model_providers across merg
   }
 });
 
+test("loadEffectiveGSDPreferences caches unchanged files until mtime changes", (t) => {
+  const originalCwd = process.cwd();
+  const originalGsdHome = process.env.GSD_HOME;
+  const tempProject = mkdtempSync(join(tmpdir(), "gsd-prefs-cache-project-"));
+  const tempGsdHome = mkdtempSync(join(tmpdir(), "gsd-prefs-cache-home-"));
+
+  t.after(() => {
+    clearGSDPreferencesCache();
+    process.chdir(originalCwd);
+    if (originalGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = originalGsdHome;
+    rmSync(tempProject, { recursive: true, force: true });
+    rmSync(tempGsdHome, { recursive: true, force: true });
+  });
+
+  mkdirSync(join(tempProject, ".gsd"), { recursive: true });
+  process.env.GSD_HOME = tempGsdHome;
+  process.chdir(tempProject);
+  clearGSDPreferencesCache();
+
+  const globalPrefsPath = join(tempGsdHome, "PREFERENCES.md");
+  const fixedMtime = new Date("2025-01-01T00:00:00.000Z");
+  const changedMtime = new Date("2025-01-01T00:00:01.000Z");
+
+  writeFileSync(globalPrefsPath, "---\nversion: 1\nlanguage: Spanish\n---\n", "utf-8");
+  utimesSync(globalPrefsPath, fixedMtime, fixedMtime);
+
+  const first = loadEffectiveGSDPreferences();
+  assert.notEqual(first, null);
+  assert.equal(first!.preferences.language, "Spanish");
+
+  writeFileSync(globalPrefsPath, "---\nversion: 1\nlanguage: English\n---\n", "utf-8");
+  utimesSync(globalPrefsPath, fixedMtime, fixedMtime);
+
+  const cached = loadEffectiveGSDPreferences();
+  assert.notEqual(cached, null);
+  assert.equal(cached!.preferences.language, "Spanish");
+
+  utimesSync(globalPrefsPath, changedMtime, changedMtime);
+
+  const reloaded = loadEffectiveGSDPreferences();
+  assert.notEqual(reloaded, null);
+  assert.equal(reloaded!.preferences.language, "English");
+});
+
 // ── Wizard fields ────────────────────────────────────────────────────────────
 
 test("budget fields validate correctly", () => {