@opengsd/gsd-pi 1.0.2-dev.235ebf3 → 1.0.2-dev.2c204d3

package/src/resources/extensions/gsd/tests/custom-engine-loop-integration.test.ts

@@ -344,6 +344,70 @@ describe("Custom engine loop integration", () => {
     );
   });
 
+  it("step mode stops after one custom workflow step", async () => {
+    _resetPendingResolve();
+
+    const runDir = makeTmpDir();
+    const graph = makeGraph([
+      makeStep({ id: "step-a" }),
+      makeStep({ id: "step-b", dependsOn: ["step-a"] }),
+      makeStep({ id: "step-c", dependsOn: ["step-b"] }),
+    ], "step-mode-custom");
+    writeGraph(runDir, graph);
+    writeDefinition(runDir, graph.steps, "step-mode-custom");
+
+    const ctx = makeMockCtx();
+    const pi = makeMockPi();
+    const s = makeLoopSession({
+      activeEngineId: "custom",
+      activeRunDir: runDir,
+      basePath: runDir,
+      stepMode: true,
+    });
+
+    const deps = makeMockDeps({
+      stopAuto: async (_ctx, _pi, reason) => {
+        deps.callLog.push(`stopAuto:${reason ?? "no-reason"}`);
+        s.active = false;
+      },
+    });
+
+    const loopPromise = autoLoop(ctx, pi, s, deps);
+    await resolveNextAgentEnd();
+
+    let timeout: NodeJS.Timeout | undefined;
+    try {
+      await Promise.race([
+        loopPromise,
+        new Promise((_, reject) =>
+          timeout = setTimeout(() => {
+            s.active = false;
+            if (_hasPendingResolveForTest()) {
+              resolveAgentEnd({ messages: [{ role: "assistant" }] });
+            }
+            reject(new Error(
+              `step mode did not stop after one custom workflow step; calls=${pi.calls.length}; log=${deps.callLog.join(",")}`,
+            ));
+          }, 1_000),
+        ),
+      ]);
+    } finally {
+      if (timeout) clearTimeout(timeout);
+    }
+
+    const finalGraph = readGraph(runDir);
+    assert.equal(pi.calls.length, 1, "step mode should dispatch exactly one custom step");
+    assert.equal(finalGraph.steps[0]?.status, "complete", "first step should complete");
+    assert.equal(finalGraph.steps[1]?.status, "pending", "second step should wait for the next /gsd next");
+    assert.equal(finalGraph.steps[2]?.status, "pending", "third step should wait for a later step");
+    assert.equal(
+      deps.callLog.some((e: string) => e.startsWith("stopAuto:")),
+      false,
+      "step-mode pause should not complete or stop the whole workflow",
+    );
+    assert.equal(s.preserveStepSurfaceAfterLoopExit, true);
+  });
+
   it("stops when engine reports isComplete on first derive", async () => {
     _resetPendingResolve();
 

package/src/resources/extensions/gsd/tests/orphaned-worktree-audit.test.ts

@@ -48,20 +48,27 @@ describe("auditOrphanedMilestoneBranches", () => {
     const result = auditOrphanedMilestoneBranches(dir, "worktree");
     assert.deepStrictEqual(result.recovered, []);
     assert.deepStrictEqual(result.warnings, []);
+    assert.deepStrictEqual(result.actions, []);
+    assert.equal(result.blockingStrandedWork, null);
   });
 
-  test("skips in none isolation mode", () => {
-    // Create a milestone branch that would otherwise be detected
+  test("runs in none isolation mode and cleans safe completed residue", () => {
     run("git branch milestone/M001", dir);
     insertMilestone({ id: "M001", title: "Test", status: "complete" });
 
     const result = auditOrphanedMilestoneBranches(dir, "none");
-    assert.deepStrictEqual(result.recovered, []);
+    assert.ok(
+      result.recovered.some((r) => r.includes("Deleted merged branch milestone/M001")),
+      `should clean merged completed residue even in none mode; got: ${JSON.stringify(result.recovered)}`,
+    );
     assert.deepStrictEqual(result.warnings, []);
+    assert.ok(
+      result.actions.some((action) => action.kind === "complete-merged-branch"),
+      "should record structured cleanup action",
+    );
 
-    // Branch should still exist
     const branches = run("git branch --list milestone/M001", dir);
-    assert.ok(branches.includes("milestone/M001"), "branch should be preserved in none mode");
+    assert.equal(branches, "", "safe completed branch should be cleaned in none mode");
   });
 
   test("deletes merged branch for completed milestone", () => {
@@ -149,9 +156,12 @@ describe("auditOrphanedMilestoneBranches", () => {
     // Must surface a warning so the user knows the worktree holds uncollapsed work
     assert.ok(result.warnings.length > 0, "should warn about in-progress orphan");
     assert.ok(
-      result.warnings.some(w => w.includes("milestone/M001") && w.includes("in-progress")),
-      `warning should mention milestone/M001 and in-progress state; got: ${JSON.stringify(result.warnings)}`,
+      result.warnings.some(w => w.includes("Stranded work") && w.includes("milestone/M001") && w.includes("in-progress")),
+      `warning should mention stranded milestone/M001 and in-progress state; got: ${JSON.stringify(result.warnings)}`,
     );
+    assert.equal(result.blockingStrandedWork?.milestoneId, "M001");
+    assert.equal(result.blockingStrandedWork?.recoveryMode, "branch");
+    assert.equal(result.blockingStrandedWork?.commitsAhead, 1);
 
     // Branch must still exist
     const branches = run("git branch --list milestone/M001", dir);
@@ -184,6 +194,53 @@ describe("auditOrphanedMilestoneBranches", () => {
       result.warnings.some(w => w.includes(".gsd/worktrees/M001") || w.includes("worktree")),
       `warning should reference the worktree location; got: ${JSON.stringify(result.warnings)}`,
     );
+    assert.equal(result.blockingStrandedWork?.recoveryMode, "worktree");
+  });
+
+  test("detects dirty in-progress worktree even when branch has no commits ahead", () => {
+    run("git branch milestone/M001", dir);
+
+    const wtDir = join(dir, ".gsd", "worktrees", "M001");
+    mkdirSync(wtDir, { recursive: true });
+    writeFileSync(join(wtDir, ".git"), `gitdir: ${join(dir, ".git", "worktrees", "M001")}\n`);
+    writeFileSync(join(wtDir, "dirty.txt"), "uncommitted work\n");
+
+    insertMilestone({ id: "M001", title: "Test", status: "active" });
+
+    const result = auditOrphanedMilestoneBranches(dir, "worktree", {
+      hasChanges: (basePath) => basePath === wtDir,
+    });
+
+    assert.deepStrictEqual(result.recovered, []);
+    assert.ok(
+      result.warnings.some((w) => w.includes("uncommitted changes")),
+      `dirty worktree should be treated as stranded work; got: ${JSON.stringify(result.warnings)}`,
+    );
+    assert.equal(result.blockingStrandedWork?.milestoneId, "M001");
+    assert.equal(result.blockingStrandedWork?.dirtyWorktree, true);
+    assert.equal(result.blockingStrandedWork?.recoveryMode, "worktree");
+  });
+
+  test("detects dirty in-progress worktree even when milestone branch is absent", () => {
+    const wtDir = join(dir, ".gsd", "worktrees", "M001");
+    mkdirSync(wtDir, { recursive: true });
+    writeFileSync(join(wtDir, ".git"), `gitdir: ${join(dir, ".git", "worktrees", "M001")}\n`);
+    writeFileSync(join(wtDir, "dirty.txt"), "branchless work\n");
+
+    insertMilestone({ id: "M001", title: "Test", status: "active" });
+
+    const result = auditOrphanedMilestoneBranches(dir, "none", {
+      hasChanges: (basePath) => basePath === wtDir,
+    });
+
+    assert.deepStrictEqual(result.recovered, []);
+    assert.ok(
+      result.warnings.some((w) => w.includes("Stranded work") && w.includes("M001")),
+      `branchless dirty worktree should block; got: ${JSON.stringify(result.warnings)}`,
+    );
+    assert.equal(result.blockingStrandedWork?.branch, undefined);
+    assert.equal(result.blockingStrandedWork?.dirtyWorktree, true);
+    assert.equal(result.blockingStrandedWork?.recoveryMode, "worktree");
   });
 
   test("cleans up orphaned worktree directory for merged milestone", () => {
@@ -359,7 +416,7 @@ describe("auditOrphanedMilestoneBranches", () => {
     assert.ok(existsSync(wtDir), "active milestone worktree dir must be preserved");
   });
 
-  test("#5879 — skips branch-less orphan in 'none' isolation mode", () => {
+  test("#5879 — cleans branch-less complete orphan in 'none' isolation mode", () => {
     insertMilestone({ id: "M001", title: "Test", status: "complete" });
 
     const wtDir = join(dir, ".gsd", "worktrees", "M001");
@@ -368,7 +425,10 @@ describe("auditOrphanedMilestoneBranches", () => {
 
     const result = auditOrphanedMilestoneBranches(dir, "none");
 
-    assert.deepStrictEqual(result.recovered, []);
-    assert.ok(existsSync(wtDir), "'none' mode must not touch worktree dirs");
+    assert.ok(
+      result.recovered.some((r) => r.includes("M001") && r.includes("branch already deleted")),
+      `none mode should still clean safe completed residue; got: ${JSON.stringify(result.recovered)}`,
+    );
+    assert.ok(!existsSync(wtDir), "completed orphan worktree dir should be cleaned in none mode");
   });
 });

package/src/resources/extensions/gsd/tests/start-auto-detached.test.ts

@@ -15,6 +15,13 @@ function readGsdFile(relativePath: string): string {
   return readFileSync(resolve(gsdDir, relativePath), "utf-8");
 }
 
+function firstIndexOfAny(source: string, needles: string[]): number {
+  const indexes = needles
+    .map((needle) => source.indexOf(needle))
+    .filter((index) => index > -1);
+  return indexes.length > 0 ? Math.min(...indexes) : -1;
+}
+
 test("command entrypoints use startAutoDetached instead of awaiting startAuto (#3733)", () => {
   const autoHandlerSrc = readGsdFile("commands/handlers/auto.ts");
   const workflowHandlerSrc = readGsdFile("commands/handlers/workflow.ts");
@@ -145,7 +152,11 @@ test("fresh start registers the auto worker before bootstrap enters worktree flo
   const resumeEnterMilestoneIdx = resumeBody.indexOf("buildLifecycle().enterMilestone");
   const dbOpenIdx = bootstrapBody.indexOf("await openProjectDbIfPresent(base);");
   const bootstrapRegisterIdx = bootstrapBody.indexOf("registerAutoWorkerForSession(base);");
-  const enterMilestoneIdx = bootstrapBody.indexOf("buildLifecycle().enterMilestone");
+  const enterMilestoneIdx = firstIndexOfAny(bootstrapBody, [
+    "buildLifecycle().enterMilestone",
+    "lifecycle.enterMilestone",
+    "lifecycle.adoptStrandedMilestone",
+  ]);
 
   assert.ok(startAutoIdx > -1, "startAuto should exist");
   assert.ok(preBootstrapRegisterIdx > -1, "startAuto should register worker before bootstrap");
@@ -158,7 +169,7 @@ test("fresh start registers the auto worker before bootstrap enters worktree flo
   assert.ok(bootstrapIdx > -1, "bootstrapAutoSession should exist");
   assert.ok(dbOpenIdx > -1, "bootstrap should open the project DB");
   assert.ok(bootstrapRegisterIdx > -1, "bootstrap should register worker after DB open");
-  assert.ok(enterMilestoneIdx > -1, "bootstrap should enter milestones through lifecycle");
+  assert.ok(enterMilestoneIdx > -1, "bootstrap should enter or adopt milestones through lifecycle");
   assert.ok(
     preBootstrapRegisterIdx < bootstrapCallIdx,
     "worker registration must happen before bootstrap so enterMilestone can claim milestone leases on first entry",

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

@@ -235,12 +235,16 @@ test("gsd_task_complete — enrichment arrays are optional", () => {
     "milestoneId",
     "oneLiner",
     "narrative",
-    "verification",
   ];
   for (const field of coreRequired) {
     assert.ok(required.has(field), `core field "${field}" must be required`);
   }
 
+  assert.ok(
+    !required.has("verification"),
+    "verification must be optional at the schema layer so step-mode can recover when verificationEvidence is present",
+  );
+
   // Enrichment fields must be optional
   const enrichmentFields = [
     "keyFiles",
@@ -272,6 +276,25 @@ test("gsd_task_complete — validates with only core params", () => {
   assert.strictEqual(errors.length, 0, `Minimal params should validate but got errors: ${errors.join(", ")}`);
 });
 
+test("gsd_task_complete — accepts evidence-only verification at schema layer", () => {
+  const tool = getTool("gsd_task_complete");
+  assert.ok(tool, "gsd_task_complete must be registered");
+
+  const params = {
+    taskId: "T01",
+    sliceId: "S01",
+    milestoneId: "M001",
+    oneLiner: "Implemented the feature",
+    narrative: "Created the module and wired it up.",
+    verificationEvidence: [
+      { command: "npm test", exitCode: 0, verdict: "pass", durationMs: 1234 },
+    ],
+  };
+
+  const errors = validateSchema(tool, params);
+  assert.strictEqual(errors.length, 0, `Evidence-only params should validate but got errors: ${errors.join(", ")}`);
+});
+
 // ─── gsd_complete_milestone: enrichment arrays must be optional ──────────────
 
 test("gsd_complete_milestone — enrichment arrays are optional", () => {

package/src/resources/extensions/gsd/tests/workflow-mcp-auto-prep.test.ts

@@ -1,6 +1,11 @@
 import test from "node:test";
 import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 
+import { registerHooks } from "../bootstrap/register-hooks.ts";
+import { GSD_WORKFLOW_MCP_SERVER_NAME } from "../mcp-project-config.ts";
 import { prepareWorkflowMcpForProject, shouldAutoPrepareWorkflowMcp } from "../workflow-mcp-auto-prep.ts";
 
 test("shouldAutoPrepareWorkflowMcp enables prep for externalCli local transport", () => {
@@ -74,3 +79,58 @@ test("prepareWorkflowMcpForProject warns with /gsd mcp init guidance when prep f
   assert.equal(notifications[0].level, "warning");
   assert.match(notifications[0].message, /Please run \/gsd mcp init \./);
 });
+
+test("before_agent_start auto-prepares project workflow MCP for Claude Code CLI", async (t) => {
+  const projectRoot = mkdtempSync(join(tmpdir(), "gsd-mcp-before-agent-"));
+  const originalCwd = process.cwd();
+  const notifications: string[] = [];
+  const handlers = new Map<string, Array<(event: any, ctx?: any) => Promise<any> | any>>();
+  const pi = {
+    on(event: string, handler: (event: any, ctx?: any) => Promise<any> | any) {
+      const existing = handlers.get(event) ?? [];
+      existing.push(handler);
+      handlers.set(event, existing);
+    },
+    getActiveTools: () => [],
+    getAllTools: () => [],
+    setActiveTools() {},
+  };
+
+  t.after(() => {
+    process.chdir(originalCwd);
+    rmSync(projectRoot, { recursive: true, force: true });
+  });
+
+  process.chdir(projectRoot);
+  registerHooks(pi as any, []);
+
+  const beforeAgentStart = handlers.get("before_agent_start")?.[0];
+  assert.ok(beforeAgentStart, "before_agent_start hook should be registered");
+
+  await beforeAgentStart(
+    { prompt: "hello", systemPrompt: "base" },
+    {
+      cwd: projectRoot,
+      model: { provider: "claude-code", baseUrl: "local://claude-code" },
+      modelRegistry: {
+        getProviderAuthMode: () => "externalCli",
+        isProviderRequestReady: () => true,
+      },
+      ui: {
+        notify(message: string) {
+          notifications.push(message);
+        },
+        setWidget() {},
+      },
+    },
+  );
+
+  const configPath = join(projectRoot, ".mcp.json");
+  assert.equal(existsSync(configPath), true, "Claude Code CLI turns should create project MCP config");
+
+  const parsed = JSON.parse(readFileSync(configPath, "utf-8")) as {
+    mcpServers?: Record<string, unknown>;
+  };
+  assert.ok(parsed.mcpServers?.[GSD_WORKFLOW_MCP_SERVER_NAME]);
+  assert.match(notifications.join("\n"), /Claude Code MCP prepared/);
+});

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

@@ -148,6 +148,60 @@ test("executeTaskComplete coerces string verificationEvidence entries", async ()
   }
 });
 
+test("executeTaskComplete derives missing verification from evidence", async () => {
+  const base = makeTmpBase();
+  try {
+    openTestDb(base);
+    const planDir = join(base, ".gsd", "milestones", "M001", "slices", "S01");
+    mkdirSync(planDir, { recursive: true });
+    writeFileSync(join(planDir, "S01-PLAN.md"), "# S01\n\n- [ ] **T01: Demo** `est:5m`\n");
+
+    const result = await inProjectDir(base, () => executeTaskComplete({
+      milestoneId: "M001",
+      sliceId: "S01",
+      taskId: "T01",
+      oneLiner: "Completed task",
+      narrative: "Did the work",
+      verificationEvidence: [
+        { command: "npm test", exitCode: 0, verdict: "pass", durationMs: 1234 },
+      ],
+    }, base));
+
+    assert.equal(result.details.operation, "complete_task");
+    const db = _getAdapter();
+    assert.ok(db, "DB should be open");
+    const row = db!.prepare(
+      "SELECT verification_result FROM tasks WHERE milestone_id = ? AND slice_id = ? AND id = ?",
+    ).get("M001", "S01", "T01") as Record<string, unknown> | undefined;
+
+    assert.match(String(row?.verification_result), /Verification evidence recorded/);
+    assert.match(String(row?.verification_result), /`npm test` exited 0 \(pass\)/);
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executeTaskComplete returns a tool error when verification cannot be derived", async () => {
+  const base = makeTmpBase();
+  try {
+    openTestDb(base);
+    const result = await inProjectDir(base, () => executeTaskComplete({
+      milestoneId: "M001",
+      sliceId: "S01",
+      taskId: "T01",
+      oneLiner: "Completed task",
+      narrative: "Did the work",
+    }, base));
+
+    assert.equal(result.isError, true);
+    assert.match(String(result.content[0]?.text), /verification is required/);
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
 test("executeSliceComplete preserves omitted optional requirement arrays", async () => {
   const base = makeTmpBase();
   try {

package/src/resources/extensions/gsd/tests/workspace-git-preflight.test.ts

@@ -9,7 +9,7 @@ import { join } from "node:path";
 import { probeGitConflictState } from "../git-conflict-state.js";
 import { ensureWorkspaceGitReadyForPath } from "../workspace-git-preflight.js";
 import { isWorkspaceGitAllowedCommand } from "../workspace-git-guard.js";
-import { cleanup, git, makeTempRepo } from "./test-utils.ts";
+import { cleanup, git, makeTempDir, makeTempRepo } from "./test-utils.ts";
 
 function seedGsdConflict(base: string): void {
   mkdirSync(join(base, ".gsd"), { recursive: true });
@@ -60,6 +60,21 @@ test("probeGitConflictState reports clean repo", () => {
   }
 });
 
+test("ensureWorkspaceGitReadyForPath allows fresh non-git project setup folders", async () => {
+  const base = makeTempDir("gsd-ws-git-non-repo-");
+  try {
+    mkdirSync(join(base, ".gsd"), { recursive: true });
+
+    const probe = probeGitConflictState(base);
+    assert.equal(probe.status, "clean");
+
+    const ready = await ensureWorkspaceGitReadyForPath(base);
+    assert.equal(ready.ok, true);
+  } finally {
+    cleanup(base);
+  }
+});
+
 test("ensureWorkspaceGitReadyForPath auto-resolves .gsd/ conflicts", async () => {
   const base = makeTempRepo("gsd-ws-git-heal-");
   try {

package/src/resources/extensions/gsd/tests/worktree-lifecycle.test.ts

@@ -212,6 +212,34 @@ test("enterMilestone returns ok:true mode:none when isolation disabled", () => {
   assert.equal(s.basePath, "/project");
 });
 
+test("adoptStrandedMilestone forces branch recovery even when normal preferences differ", (t) => {
+  const previousCwd = process.cwd();
+  const base = makeGitRepoBase({ isolation: "worktree" });
+  t.after(() => cleanupRepoBase(base, previousCwd));
+
+  const s = makeSession({ basePath: base, originalBasePath: base });
+  const deps = makeDeps();
+  const ctx = makeCtx();
+  const lifecycle = new WorktreeLifecycle(s, deps);
+
+  const result = lifecycle.adoptStrandedMilestone("M001", base, ctx, {
+    mode: "branch",
+  });
+
+  assert.equal(result.ok, true, `expected ok:true, got: ${JSON.stringify(result)}`);
+  if (result.ok) {
+    assert.equal(result.mode, "branch");
+    assert.equal(result.path, base);
+  }
+  assert.equal(s.basePath, base);
+  assert.equal(s.strandedRecoveryIsolationMode, "branch");
+  const currentBranch = execFileSync("git", ["branch", "--show-current"], {
+    cwd: base,
+    encoding: "utf-8",
+  }).trim();
+  assert.equal(currentBranch, "milestone/M001");
+});
+
 test("enterMilestone returns ok:false reason:isolation-degraded when session degraded", () => {
   const s = makeSession({ isolationDegraded: true });
   const deps = makeDeps({ getIsolationMode: () => "branch" });

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

@@ -13,7 +13,7 @@ import { mkdtempSync, mkdirSync, rmSync, existsSync, writeFileSync, readFileSync
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
-import { runWorktreePostCreateHook } from "../auto-worktree.ts";
+import { runWorktreePostCreateHook } from "../worktree-post-create-hook.ts";
 
 function makeTmpDir(): string {
   return mkdtempSync(join(tmpdir(), "gsd-wt-hook-test-"));
@@ -45,10 +45,150 @@ function writeNodeHookScript(filePath: string, code: string): void {
 test("returns null when no hook path is provided", () => {
   const src = makeTmpDir();
   const wt = makeTmpDir();
+  const previousGsdHome = process.env.GSD_HOME;
   try {
+    process.env.GSD_HOME = join(src, "empty-gsd-home");
     const result = runWorktreePostCreateHook(src, wt, undefined);
     assert.equal(result, null);
   } finally {
+    if (previousGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = previousGsdHome;
+    rmSync(src, { recursive: true, force: true });
+    rmSync(wt, { recursive: true, force: true });
+  }
+});
+
+test("reads git.worktree_post_create from project preferences without loading auto-worktree", () => {
+  const src = makeTmpDir();
+  const wt = makeTmpDir();
+  const previousGsdHome = process.env.GSD_HOME;
+  try {
+    process.env.GSD_HOME = join(src, "empty-gsd-home");
+    const hooksDir = join(src, ".gsd", "hooks");
+    mkdirSync(hooksDir, { recursive: true });
+    writeFileSync(
+      join(src, ".gsd", "PREFERENCES.md"),
+      [
+        "---",
+        "git:",
+        `  worktree_post_create: ${hookPath(".gsd/hooks/post-create")}`,
+        "---",
+        "",
+      ].join("\n"),
+    );
+    const hookFile = hookPath(join(hooksDir, "post-create"));
+    writeNodeHookScript(
+      hookFile,
+      `require("fs").writeFileSync(require("path").join(process.env.WORKTREE_DIR, "configured-hook-ran"), "ok");`,
+    );
+
+    const result = runWorktreePostCreateHook(src, wt);
+
+    assert.equal(result, null);
+    assert.ok(existsSync(join(wt, "configured-hook-ran")), "configured hook should run");
+  } finally {
+    if (previousGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = previousGsdHome;
+    rmSync(src, { recursive: true, force: true });
+    rmSync(wt, { recursive: true, force: true });
+  }
+});
+
+test("prefers canonical project PREFERENCES.md over legacy lowercase preferences.md", () => {
+  const src = makeTmpDir();
+  const wt = makeTmpDir();
+  const previousGsdHome = process.env.GSD_HOME;
+  try {
+    process.env.GSD_HOME = join(src, "empty-gsd-home");
+    const hooksDir = join(src, ".gsd", "hooks");
+    mkdirSync(hooksDir, { recursive: true });
+    writeFileSync(
+      join(src, ".gsd", "preferences.md"),
+      [
+        "---",
+        "git:",
+        `  worktree_post_create: ${hookPath(".gsd/hooks/legacy")}`,
+        "---",
+        "",
+      ].join("\n"),
+    );
+    writeFileSync(
+      join(src, ".gsd", "PREFERENCES.md"),
+      [
+        "---",
+        "git:",
+        `  worktree_post_create: ${hookPath(".gsd/hooks/canonical")}`,
+        "---",
+        "",
+      ].join("\n"),
+    );
+    writeNodeHookScript(
+      hookPath(join(hooksDir, "canonical")),
+      `require("fs").writeFileSync(require("path").join(process.env.WORKTREE_DIR, "configured-hook-ran"), "canonical");`,
+    );
+    writeNodeHookScript(
+      hookPath(join(hooksDir, "legacy")),
+      `require("fs").writeFileSync(require("path").join(process.env.WORKTREE_DIR, "configured-hook-ran"), "legacy");`,
+    );
+
+    const result = runWorktreePostCreateHook(src, wt);
+
+    assert.equal(result, null);
+    assert.equal(readFileSync(join(wt, "configured-hook-ran"), "utf-8"), "canonical");
+  } finally {
+    if (previousGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = previousGsdHome;
+    rmSync(src, { recursive: true, force: true });
+    rmSync(wt, { recursive: true, force: true });
+  }
+});
+
+test("prefers canonical global PREFERENCES.md over legacy lowercase preferences.md", () => {
+  const src = makeTmpDir();
+  const wt = makeTmpDir();
+  const previousGsdHome = process.env.GSD_HOME;
+  try {
+    const gsdHomeDir = join(src, "global-gsd-home");
+    process.env.GSD_HOME = gsdHomeDir;
+    const hooksDir = join(src, ".gsd", "hooks");
+    mkdirSync(hooksDir, { recursive: true });
+    mkdirSync(gsdHomeDir, { recursive: true });
+    writeFileSync(
+      join(gsdHomeDir, "preferences.md"),
+      [
+        "---",
+        "git:",
+        `  worktree_post_create: ${hookPath(".gsd/hooks/legacy")}`,
+        "---",
+        "",
+      ].join("\n"),
+    );
+    writeFileSync(
+      join(gsdHomeDir, "PREFERENCES.md"),
+      [
+        "---",
+        "git:",
+        `  worktree_post_create: ${hookPath(".gsd/hooks/canonical")}`,
+        "---",
+        "",
+      ].join("\n"),
+    );
+    writeNodeHookScript(
+      hookPath(join(hooksDir, "canonical")),
+      `require("fs").writeFileSync(require("path").join(process.env.WORKTREE_DIR, "configured-hook-ran"), "canonical");`,
+    );
+    writeNodeHookScript(
+      hookPath(join(hooksDir, "legacy")),
+      `require("fs").writeFileSync(require("path").join(process.env.WORKTREE_DIR, "configured-hook-ran"), "legacy");`,
+    );
+
+    const result = runWorktreePostCreateHook(src, wt);
+
+    assert.equal(result, null);
+    assert.equal(readFileSync(join(wt, "configured-hook-ran"), "utf-8"), "canonical");
+  } finally {
+    if (previousGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = previousGsdHome;
     rmSync(src, { recursive: true, force: true });
     rmSync(wt, { recursive: true, force: true });
   }