gsd-pi 2.74.0 → 2.75.0-dev.2203010a0

package/src/resources/extensions/gsd/tests/graph-context.test.ts

@@ -0,0 +1,337 @@
+/**
+ * graph-context.test.ts — Unit tests for inlineGraphSubgraph().
+ *
+ * Covers:
+ *   Group 1: Null-return paths (empty term, zero nodes, missing graph.json)
+ *   Group 2: Correct output formatting (nodes, edges, stale annotation)
+ *   Group 3: Node formatting (description, confidence, no-description)
+ *
+ * Testing strategy:
+ *   @gsd-build/mcp-server is dynamically imported inside inlineGraphSubgraph().
+ *   Because node:test (v22) does not support mock.module() without the
+ *   --experimental-test-module-mocks flag (not enabled in test:unit), we
+ *   exercise the real graphQuery/graphStatus functions by controlling the
+ *   on-disk graph.json that those functions read. This is a clean, deterministic
+ *   approach that avoids all module-level mocking.
+ *
+ *   Fixture layout per test:
+ *     <tmpDir>/.gsd/graphs/graph.json
+ *
+ *   builtAt controls staleness: old timestamp → stale, recent → fresh.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { inlineGraphSubgraph } from "../graph-context.ts";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+interface TestNode {
+  id: string;
+  label: string;
+  type: string;
+  confidence: string;
+  description?: string;
+  sourceFile?: string;
+}
+
+interface TestEdge {
+  from: string;
+  to: string;
+  type: string;
+  confidence: string;
+}
+
+interface GraphFixture {
+  nodes: TestNode[];
+  edges: TestEdge[];
+  /** ISO timestamp for graph.builtAt. Controls staleness. Default: recent (not stale). */
+  builtAt?: string;
+}
+
+/** Returns an ISO timestamp that is stale (> 24h ago). */
+function staleTimestamp(hoursAgo = 26): string {
+  return new Date(Date.now() - hoursAgo * 60 * 60 * 1000).toISOString();
+}
+
+/** Returns an ISO timestamp that is fresh (< 24h ago). */
+function freshTimestamp(): string {
+  return new Date(Date.now() - 30 * 60 * 1000).toISOString(); // 30 minutes ago
+}
+
+/**
+ * Creates a temp project directory with a .gsd/graphs/graph.json file.
+ * Returns the projectDir path. Caller is responsible for cleanup.
+ */
+function makeProjectDir(fixture: GraphFixture): string {
+  const projectDir = mkdtempSync(join(tmpdir(), "graph-ctx-test-"));
+  const gsdDir = join(projectDir, ".gsd");
+  const graphsDir = join(gsdDir, "graphs");
+  mkdirSync(graphsDir, { recursive: true });
+
+  const graph = {
+    nodes: fixture.nodes,
+    edges: fixture.edges,
+    builtAt: fixture.builtAt ?? freshTimestamp(),
+  };
+
+  writeFileSync(join(graphsDir, "graph.json"), JSON.stringify(graph), "utf-8");
+  return projectDir;
+}
+
+/** Removes a temp directory, suppressing errors on Windows. */
+function cleanup(dir: string): void {
+  try { rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+}
+
+/** Minimal node factory. */
+function makeNode(overrides: Partial<TestNode> & { id: string; label: string }): TestNode {
+  return {
+    type: "CLASS",
+    confidence: "INFERRED",
+    ...overrides,
+  };
+}
+
+/** Minimal edge factory. */
+function makeEdge(overrides: Partial<TestEdge> & { from: string; to: string }): TestEdge {
+  return {
+    type: "CALLS",
+    confidence: "INFERRED",
+    ...overrides,
+  };
+}
+
+// ─── Group 1: Null returns ────────────────────────────────────────────────────
+
+describe("inlineGraphSubgraph — null returns", () => {
+  it("returns null immediately for empty string term", async () => {
+    // No graph.json needed — exits before any file I/O
+    const result = await inlineGraphSubgraph("/tmp/nonexistent", "", { budget: 3000 });
+    assert.strictEqual(result, null);
+  });
+
+  it("returns null for whitespace-only term", async () => {
+    const result = await inlineGraphSubgraph("/tmp/nonexistent", "   ", { budget: 3000 });
+    assert.strictEqual(result, null);
+  });
+
+  it("returns null when graphQuery returns zero nodes (no matching term in graph)", async () => {
+    const projectDir = makeProjectDir({
+      nodes: [makeNode({ id: "n1", label: "AuthService" })],
+      edges: [],
+    });
+    try {
+      // "zzznomatch999" is intentionally absent from the fixture
+      const result = await inlineGraphSubgraph(projectDir, "zzznomatch999", { budget: 3000 });
+      assert.strictEqual(result, null);
+    } finally {
+      cleanup(projectDir);
+    }
+  });
+
+  it("returns null (no throw) when graph.json is missing", async () => {
+    // A project dir with no .gsd directory at all — graphQuery returns zero nodes
+    const projectDir = mkdtempSync(join(tmpdir(), "graph-ctx-nofile-"));
+    try {
+      const result = await inlineGraphSubgraph(projectDir, "auth", { budget: 3000 });
+      assert.strictEqual(result, null);
+    } finally {
+      cleanup(projectDir);
+    }
+  });
+});
+
+// ─── Group 2: Correct output formatting ──────────────────────────────────────
+
+describe("inlineGraphSubgraph — correct output", () => {
+  it("returns block with section header and node labels when term matches", async () => {
+    const projectDir = makeProjectDir({
+      nodes: [
+        makeNode({ id: "n1", label: "UserService" }),
+        makeNode({ id: "n2", label: "UserRepository" }),
+      ],
+      edges: [],
+    });
+    try {
+      const result = await inlineGraphSubgraph(projectDir, "User", { budget: 3000 });
+      assert.ok(result !== null, "result should not be null");
+      assert.ok(result!.includes("### Knowledge Graph Context"), "should include section header");
+      assert.ok(result!.includes("UserService"), "should include first node label");
+      assert.ok(result!.includes("UserRepository"), "should include second node label");
+      assert.ok(result!.includes("Nodes (2)"), "should show node count");
+    } finally {
+      cleanup(projectDir);
+    }
+  });
+
+  it("does not include Relations section when edges array is empty", async () => {
+    const projectDir = makeProjectDir({
+      nodes: [makeNode({ id: "n1", label: "AuthController" })],
+      edges: [],
+    });
+    try {
+      const result = await inlineGraphSubgraph(projectDir, "Auth", { budget: 3000 });
+      assert.ok(result !== null, "result should not be null");
+      assert.ok(!result!.includes("Relations"), "should not include Relations section for zero edges");
+      assert.ok(!result!.includes("⚠"), "should not include stale warning for fresh graph");
+    } finally {
+      cleanup(projectDir);
+    }
+  });
+
+  it("includes Relations section when edges are present", async () => {
+    const projectDir = makeProjectDir({
+      nodes: [
+        makeNode({ id: "n1", label: "AuthService" }),
+        makeNode({ id: "n2", label: "UserRepo" }),
+      ],
+      edges: [makeEdge({ from: "n1", to: "n2", type: "CALLS" })],
+    });
+    try {
+      const result = await inlineGraphSubgraph(projectDir, "Auth", { budget: 3000 });
+      assert.ok(result !== null, "result should not be null");
+      assert.ok(result!.includes("Relations (1)"), "should show edge count");
+      assert.ok(result!.includes("→[CALLS]→"), "should include edge type in arrow notation");
+    } finally {
+      cleanup(projectDir);
+    }
+  });
+
+  it("includes stale annotation when graph was built more than 24h ago", async () => {
+    const projectDir = makeProjectDir({
+      nodes: [makeNode({ id: "n1", label: "AuthService" })],
+      edges: [],
+      builtAt: staleTimestamp(26), // 26 hours ago → stale
+    });
+    try {
+      const result = await inlineGraphSubgraph(projectDir, "Auth", { budget: 3000 });
+      assert.ok(result !== null, "result should not be null");
+      assert.ok(result!.includes("⚠ Graph last built"), "should include stale annotation");
+      assert.ok(result!.includes("h ago"), "should include hours-ago text");
+    } finally {
+      cleanup(projectDir);
+    }
+  });
+
+  it("does not include stale annotation for a fresh graph", async () => {
+    const projectDir = makeProjectDir({
+      nodes: [makeNode({ id: "n1", label: "AuthService" })],
+      edges: [],
+      builtAt: freshTimestamp(), // 30 minutes ago → not stale
+    });
+    try {
+      const result = await inlineGraphSubgraph(projectDir, "Auth", { budget: 3000 });
+      assert.ok(result !== null, "result should not be null");
+      assert.ok(!result!.includes("⚠"), "should not include stale annotation for fresh graph");
+    } finally {
+      cleanup(projectDir);
+    }
+  });
+
+  it("returns valid block even when graph.json has corrupted builtAt (graphStatus throws internally)", async () => {
+    // Write a graph.json with an invalid builtAt — graphStatus will catch and return {exists: false}
+    // inlineGraphSubgraph should still return the node block without stale annotation
+    const projectDir = mkdtempSync(join(tmpdir(), "graph-ctx-corrupt-"));
+    const gsdDir = join(projectDir, ".gsd");
+    const graphsDir = join(gsdDir, "graphs");
+    mkdirSync(graphsDir, { recursive: true });
+
+    const graph = {
+      nodes: [{ id: "n1", label: "AuthController", type: "CLASS", confidence: "INFERRED" }],
+      edges: [],
+      builtAt: "NOT-A-DATE", // invalid ISO — will cause Date.now() - NaN to produce NaN
+    };
+    writeFileSync(join(graphsDir, "graph.json"), JSON.stringify(graph), "utf-8");
+
+    try {
+      const result = await inlineGraphSubgraph(projectDir, "Auth", { budget: 3000 });
+      // graphQuery reads the file and finds the node; graphStatus may return {exists: true, stale: false/true}
+      // Either way, function must not throw and must return a string with node content
+      assert.ok(result !== null, "result should not be null");
+      assert.ok(result!.includes("AuthController"), "should include node label");
+    } finally {
+      cleanup(projectDir);
+    }
+  });
+
+  it("passes the budget option to graphQuery (enforces node count limit)", async () => {
+    // Each node uses ~20 tokens. With budget=20, only ~1 node should be returned.
+    // Build a graph with many nodes all matching the same term.
+    const nodes: TestNode[] = Array.from({ length: 10 }, (_, i) =>
+      makeNode({ id: `n${i}`, label: `AuthModule${i}` })
+    );
+    const projectDir = makeProjectDir({ nodes, edges: [] });
+    try {
+      const resultSmall = await inlineGraphSubgraph(projectDir, "Auth", { budget: 20 });
+      const resultLarge = await inlineGraphSubgraph(projectDir, "Auth", { budget: 10000 });
+
+      // Both should return something (at least 1 node matches)
+      assert.ok(resultSmall !== null, "small-budget result should not be null");
+      assert.ok(resultLarge !== null, "large-budget result should not be null");
+
+      // With a very small budget (20 tokens ≈ 1 node), fewer nodes should appear
+      const smallNodeCount = (resultSmall!.match(/- \*\*/g) || []).length;
+      const largeNodeCount = (resultLarge!.match(/- \*\*/g) || []).length;
+      assert.ok(
+        smallNodeCount <= largeNodeCount,
+        `small-budget should return <= nodes than large-budget (got ${smallNodeCount} vs ${largeNodeCount})`,
+      );
+    } finally {
+      cleanup(projectDir);
+    }
+  });
+});
+
+// ─── Group 3: Node formatting ─────────────────────────────────────────────────
+
+describe("inlineGraphSubgraph — node formatting", () => {
+  it("includes description after em-dash when node has description", async () => {
+    const projectDir = makeProjectDir({
+      nodes: [makeNode({ id: "n1", label: "JwtValidator", description: "JWT validation" })],
+      edges: [],
+    });
+    try {
+      const result = await inlineGraphSubgraph(projectDir, "Jwt", { budget: 3000 });
+      assert.ok(result !== null, "result should not be null");
+      assert.ok(result!.includes("— JWT validation"), "should include description after em-dash");
+    } finally {
+      cleanup(projectDir);
+    }
+  });
+
+  it("omits em-dash suffix when node has no description", async () => {
+    const projectDir = makeProjectDir({
+      nodes: [makeNode({ id: "n1", label: "TokenStore" })], // no description
+      edges: [],
+    });
+    try {
+      const result = await inlineGraphSubgraph(projectDir, "Token", { budget: 3000 });
+      assert.ok(result !== null, "result should not be null");
+      const lines = result!.split("\n");
+      const nodeLine = lines.find((l) => l.includes("TokenStore"));
+      assert.ok(nodeLine !== undefined, "node line should be present");
+      assert.ok(!nodeLine.includes("—"), "node line should not include em-dash when no description");
+    } finally {
+      cleanup(projectDir);
+    }
+  });
+
+  it("includes confidence tier in the node output line", async () => {
+    const projectDir = makeProjectDir({
+      nodes: [makeNode({ id: "n1", label: "AuthService", confidence: "EXTRACTED" })],
+      edges: [],
+    });
+    try {
+      const result = await inlineGraphSubgraph(projectDir, "Auth", { budget: 3000 });
+      assert.ok(result !== null, "result should not be null");
+      assert.ok(result!.includes("EXTRACTED"), "should include the confidence tier in node line");
+    } finally {
+      cleanup(projectDir);
+    }
+  });
+});

package/src/resources/extensions/gsd/tests/graph-operations.test.ts

@@ -19,7 +19,6 @@ import {
   markStepComplete,
   expandIteration,
   initializeGraph,
-  graphFromDefinition,
   type WorkflowGraph,
   type GraphStep,
 } from "../graph.ts";
@@ -459,9 +458,6 @@ describe("initializeGraph", () => {
     assert.deepStrictEqual(graph.steps[2].dependsOn, ["s1", "s2"]);
   });
 
-  it("is also exported as graphFromDefinition (backward compat)", (t) => {
-    assert.equal(graphFromDefinition, initializeGraph);
-  });
 });
 
 // ─── Atomic write safety ─────────────────────────────────────────────────

package/src/resources/extensions/gsd/tests/gsd-db.test.ts

@@ -23,6 +23,7 @@ import {
   insertTask,
   getTask,
   getSliceTasks,
+  checkpointDatabase,
 } from '../gsd-db.ts';
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -80,7 +81,7 @@ describe('gsd-db', () => {
     // Check schema_version table
     const adapter = _getAdapter()!;
     const version = adapter.prepare('SELECT MAX(version) as version FROM schema_version').get();
-    assert.deepStrictEqual(version?.['version'], 14, 'schema version should be 14');
+    assert.deepStrictEqual(version?.['version'], 17, 'schema version should be 17');
 
     // Check tables exist by querying them
     const dRows = adapter.prepare('SELECT count(*) as cnt FROM decisions').get();
@@ -518,6 +519,48 @@ describe('gsd-db', () => {
     closeDatabase();
   });
 
+  // ─── checkpointDatabase ────────────────────────────────────────────────────
+
+  describe('checkpointDatabase', () => {
+    test('checkpointDatabase: flushes WAL into base file (TRUNCATE)', (t) => {
+      const dbPath = tempDbPath();
+      t.after(() => cleanup(dbPath));
+
+      openDatabase(dbPath);
+
+      // Write enough data to ensure WAL has content
+      transaction(() => {
+        insertDecision({
+          id: 'D001',
+          when_context: 'test',
+          scope: 'global',
+          decision: 'WAL flush test',
+          choice: 'checkpoint',
+          rationale: 'WAL checkpoint regression test — #4418',
+          revisable: 'yes',
+          made_by: 'agent',
+          superseded_by: null,
+        });
+      });
+
+      const walPath = dbPath + '-wal';
+      assert.ok(fs.existsSync(walPath), 'WAL file should exist after write');
+      const walSizeBefore = fs.statSync(walPath).size;
+      assert.ok(walSizeBefore > 0, 'WAL file should be non-empty after write');
+
+      checkpointDatabase();
+
+      const walSizeAfter = fs.existsSync(walPath) ? fs.statSync(walPath).size : 0;
+      assert.equal(walSizeAfter, 0, 'WAL file should be truncated to 0 after checkpoint');
+    });
+
+    test('checkpointDatabase: is a no-op when no database is open', () => {
+      closeDatabase();
+      // Must not throw
+      assert.doesNotThrow(() => checkpointDatabase());
+    });
+  });
+
   // ─── Final Report ──────────────────────────────────────────────────────────
 
 });

package/src/resources/extensions/gsd/tests/health-widget.test.ts

@@ -191,6 +191,7 @@ test("session_start bootstraps the health widget alongside notifications", async
   });
 
   const widgets: string[] = [];
+  const statuses: string[] = [];
   const handlers = new Map<string, (event: unknown, ctx: any) => Promise<void> | void>();
   const pi = {
     on(event: string, handler: (event: unknown, ctx: any) => Promise<void> | void) {
@@ -198,7 +199,7 @@ test("session_start bootstraps the health widget alongside notifications", async
     },
   } as any;
 
-  registerHooks(pi);
+  registerHooks(pi, []);
   const sessionStart = handlers.get("session_start");
   assert.ok(sessionStart, "session_start handler is registered");
 
@@ -206,7 +207,9 @@ test("session_start bootstraps the health widget alongside notifications", async
     hasUI: true,
     ui: {
       notify: () => {},
-      setStatus: () => {},
+      setStatus: (key: string) => {
+        statuses.push(key);
+      },
       setWorkingMessage: () => {},
       onTerminalInput: () => () => {},
       setWidget: (key: string) => {
@@ -220,5 +223,8 @@ test("session_start bootstraps the health widget alongside notifications", async
   } as any);
 
   assert.ok(widgets.includes("gsd-health"), "health widget is bootstrapped");
-  assert.ok(widgets.includes("gsd-notifications"), "notification widget still boots");
+  assert.ok(
+    statuses.some((k) => k.includes("notifications")),
+    "notification status chip is registered",
+  );
 });

package/src/resources/extensions/gsd/tests/init-prefs-routing.test.ts

@@ -0,0 +1,190 @@
+// GSD — /gsd init → unified preferences-write routing tests.
+//
+// Verifies the refactor that routes init's preferences write through the same
+// writePreferencesFile helper used by handlePrefsWizard, and that the typed
+// ProjectPreferences shape maps correctly into the wizard's
+// Record<string, unknown> shape.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { mapInitPrefsToWizardShape } from "../init-wizard.ts";
+import { writePreferencesFile } from "../commands-prefs-wizard.ts";
+
+test("mapInitPrefsToWizardShape — full roundtrip with all fields", () => {
+  const out = mapInitPrefsToWizardShape({
+    mode: "team",
+    gitIsolation: "branch",
+    mainBranch: "develop",
+    verificationCommands: ["npm test", "npm run lint"],
+    customInstructions: ["Use TypeScript strict mode", "Always write tests"],
+    tokenProfile: "quality",
+    skipResearch: true,
+    autoPush: false,
+  });
+
+  assert.equal(out.mode, "team");
+  assert.deepEqual(out.git, { isolation: "branch", main_branch: "develop", auto_push: false });
+  assert.deepEqual(out.verification_commands, ["npm test", "npm run lint"]);
+  assert.deepEqual(out.custom_instructions, ["Use TypeScript strict mode", "Always write tests"]);
+  assert.equal(out.token_profile, "quality");
+  assert.deepEqual(out.phases, { skip_research: true });
+});
+
+test("mapInitPrefsToWizardShape — omits defaults to keep YAML clean", () => {
+  const out = mapInitPrefsToWizardShape({
+    mode: "solo",
+    gitIsolation: "worktree",
+    mainBranch: "main",
+    verificationCommands: [],
+    customInstructions: [],
+    tokenProfile: "balanced",
+    skipResearch: false,
+    autoPush: true,
+  });
+
+  // tokenProfile=balanced is the default — should not be serialized.
+  assert.equal(out.token_profile, undefined);
+  // skipResearch=false is the default — phases should not appear.
+  assert.equal(out.phases, undefined);
+  // Empty arrays should not be serialized.
+  assert.equal(out.verification_commands, undefined);
+  assert.equal(out.custom_instructions, undefined);
+});
+
+test("writePreferencesFile — writes valid frontmatter from prefill", async () => {
+  const tmp = mkdtempSync(join(tmpdir(), "gsd-init-prefs-routing-"));
+  const path = join(tmp, "PREFERENCES.md");
+
+  try {
+    const prefs = mapInitPrefsToWizardShape({
+      mode: "solo",
+      gitIsolation: "worktree",
+      mainBranch: "main",
+      verificationCommands: ["npm test"],
+      customInstructions: [],
+      tokenProfile: "balanced",
+      skipResearch: false,
+      autoPush: true,
+    });
+
+    await writePreferencesFile(path, prefs, null, { scope: "project" });
+
+    const content = readFileSync(path, "utf-8");
+    assert.match(content, /^---/);
+    assert.match(content, /mode: solo/);
+    assert.match(content, /git:/);
+    assert.match(content, /isolation: worktree/);
+    assert.match(content, /main_branch: main/);
+    assert.match(content, /auto_push: true/);
+    assert.match(content, /verification_commands:/);
+    assert.match(content, /- npm test/);
+    // version: 1 is added by writePreferencesFile if missing
+    assert.match(content, /version: 1/);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test("writePreferencesFile — preserves existing markdown body", async () => {
+  const tmp = mkdtempSync(join(tmpdir(), "gsd-init-prefs-routing-"));
+  const path = join(tmp, "PREFERENCES.md");
+  const customBody = "\n# My Custom Notes\n\nUser-edited content here.\n";
+
+  try {
+    // Seed file with frontmatter + custom body
+    writeFileSync(path, `---\nmode: solo\nversion: 1\n---${customBody}`, "utf-8");
+
+    await writePreferencesFile(path, { mode: "team", version: 1 }, null);
+
+    const content = readFileSync(path, "utf-8");
+    assert.match(content, /mode: team/);
+    assert.match(content, /My Custom Notes/);
+    assert.match(content, /User-edited content here/);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test("writePreferencesFile — falls back to default body for new files", async () => {
+  const tmp = mkdtempSync(join(tmpdir(), "gsd-init-prefs-routing-"));
+  const path = join(tmp, "PREFERENCES.md");
+  const initBody = "\n# Init body marker\n";
+
+  try {
+    await writePreferencesFile(path, { mode: "solo" }, null, { defaultBody: initBody });
+    const content = readFileSync(path, "utf-8");
+    assert.match(content, /Init body marker/);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+// ─── Regression tests from #4457 codex adversarial review ──────────────────
+
+test("init — Step 9b shape: 'not_yet' option is recognized as defer (#4457 review)", async () => {
+  // The init wizard relies on showNextAction always appending a `not_yet` action
+  // and mapping Escape to it. The Step 9b code must explicitly handle `not_yet`
+  // as defer (return without bootstrapping or persisting prefs). This test
+  // documents the contract — it doesn't drive the full wizard, but it locks in
+  // that "not_yet" is the canonical defer signal so a future refactor can't
+  // silently drop the explicit branch.
+  const { showNextAction } = await import("../../shared/tui.ts") as { showNextAction: unknown };
+  assert.equal(typeof showNextAction, "function");
+
+  // Read the source to assert Step 9b explicitly handles not_yet — a static
+  // smoke test cheaper than spinning up the full wizard with a mocked ctx.
+  const src = readFileSync(
+    new URL("../init-wizard.ts", import.meta.url),
+    "utf-8",
+  );
+  assert.match(
+    src,
+    /reviewChoice === "not_yet"[\s\S]*?return \{ completed: false, bootstrapped: false \}/,
+    "init Step 9b must short-circuit on not_yet without writing preferences",
+  );
+});
+
+test("init — preferences path is basePath-derived, not cwd-derived (#4457 review)", async () => {
+  // If basePath !== process.cwd(), preferences must still write to
+  // join(gsdRoot(basePath), "PREFERENCES.md"), not the cwd-derived path.
+  // Static check: the post-#4457-review code constructs the path from gsdRoot(basePath).
+  const src = readFileSync(
+    new URL("../init-wizard.ts", import.meta.url),
+    "utf-8",
+  );
+  assert.match(
+    src,
+    /projectPrefsPath\s*=\s*join\(gsdRoot\(basePath\),\s*"PREFERENCES\.md"\)/,
+    "init must derive the project preferences path from basePath",
+  );
+  // And neither write site should call getProjectGSDPreferencesPath() (which
+  // resolves from process.cwd()).
+  assert.doesNotMatch(
+    src,
+    /getProjectGSDPreferencesPath\s*\(/,
+    "init must not use the cwd-derived getProjectGSDPreferencesPath()",
+  );
+});
+
+test("handlePrefsWizard — accepts pathOverride to target a non-cwd location", async () => {
+  // The wizard's signature must support pathOverride so /gsd init can route
+  // both the review and skip branches to the basePath-derived path.
+  const { handlePrefsWizard } = await import("../commands-prefs-wizard.ts");
+  assert.equal(handlePrefsWizard.length >= 2, true);
+  // Read source to confirm the opts.pathOverride wiring exists — calling
+  // handlePrefsWizard end-to-end requires a full ExtensionCommandContext
+  // mock, which is heavier than this contract check warrants.
+  const src = readFileSync(
+    new URL("../commands-prefs-wizard.ts", import.meta.url),
+    "utf-8",
+  );
+  assert.match(
+    src,
+    /opts\?\.pathOverride[\s\S]*?\?\?[\s\S]*?(getProjectGSDPreferencesPath|getGlobalGSDPreferencesPath)/,
+    "handlePrefsWizard must honor opts.pathOverride before falling back to scope-derived path",
+  );
+});