@opengsd/gsd-pi 1.1.1-dev.b2556262 → 1.2.0-dev.0b870afa

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

@@ -117,7 +117,8 @@ describe("extension bootstrap isolation (#4168, #4172)", () => {
 // registration is wrapped in its own try/catch so one failure does not
 // prevent siblings from loading.
 
-import { registerGsdExtension } from "../bootstrap/register-extension.ts";
+import { CRITICAL_GSD_WORKFLOW_TOOL_NAMES, registerGsdExtension } from "../bootstrap/register-extension.ts";
+import { drainLogs } from "../workflow-logger.ts";
 
 describe("registerGsdExtension defensive registration", () => {
   test("a failing shortcut registration does not prevent kill command registration", async () => {
@@ -161,4 +162,37 @@ describe("registerGsdExtension defensive registration", () => {
       `registerGsdExtension must NOT register 'gsd' (it is registered separately by index.ts), got ${JSON.stringify(registered)}`,
     );
   });
+
+  test("critical workflow tool list includes lifecycle planning and completion tools", () => {
+    assert.ok(CRITICAL_GSD_WORKFLOW_TOOL_NAMES.includes("gsd_plan_slice"));
+    assert.ok(CRITICAL_GSD_WORKFLOW_TOOL_NAMES.includes("gsd_slice_complete"));
+    assert.ok(CRITICAL_GSD_WORKFLOW_TOOL_NAMES.includes("gsd_validate_milestone"));
+    assert.ok(CRITICAL_GSD_WORKFLOW_TOOL_NAMES.includes("gsd_complete_milestone"));
+  });
+
+  test("partial db-tools registration fails visibly when critical tools are missing", () => {
+    drainLogs();
+    const registeredTools: string[] = [];
+    const pi = {
+      registerCommand: () => {},
+      registerTool: (tool: { name: string }) => {
+        if (tool.name === "gsd_plan_slice") {
+          throw new Error("simulated db-tools partial registration failure");
+        }
+        registeredTools.push(tool.name);
+      },
+      registerHook: () => {},
+      registerShortcut: () => {},
+      events: { on: () => {}, off: () => {}, emit: () => {} },
+      getAllTools: () => registeredTools.map((name) => ({ name })),
+    };
+
+    assert.throws(
+      () => registerGsdExtension(pi as any),
+      /Critical GSD workflow tool registration failed; missing required tool\(s\): .*gsd_plan_slice/,
+    );
+    assert.ok(registeredTools.includes("gsd_plan_milestone"));
+    assert.ok(!registeredTools.includes("gsd_plan_slice"));
+    drainLogs();
+  });
 });

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

@@ -5,7 +5,7 @@ import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { validateFileChanges } from "../safety/file-change-validator.ts";
+import { validateFileChanges, effectiveFileChangeAllowlist } from "../safety/file-change-validator.ts";
 
 function git(cwd: string, ...args: string[]): string {
   return execFileSync("git", args, {
@@ -106,3 +106,35 @@ test("validateFileChanges ignores inline descriptions in expected output paths",
     "described expected output should not trigger unexpected-file warnings",
   );
 });
+
+test("effectiveFileChangeAllowlist includes .gitignore when GSD manages it", () => {
+  assert.deepEqual(effectiveFileChangeAllowlist([], undefined), [".gitignore"]);
+  assert.deepEqual(effectiveFileChangeAllowlist(["docs/**"], true), ["docs/**", ".gitignore"]);
+});
+
+test("effectiveFileChangeAllowlist keeps .gitignore auditable when management is disabled", () => {
+  assert.deepEqual(effectiveFileChangeAllowlist(["docs/**"], false), ["docs/**"]);
+});
+
+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 }));
+
+  git(base, "init");
+  git(base, "config", "user.email", "test@example.com");
+  git(base, "config", "user.name", "Test User");
+  writeFileSync(join(base, "index.html"), "<main></main>\n");
+  writeFileSync(join(base, ".gitignore"), "# ── GSD baseline (auto-generated) ──\n.gsd\n");
+  git(base, "add", ".");
+  git(base, "commit", "-m", "task commit with swept gitignore");
+
+  const audit = validateFileChanges(
+    base,
+    ["index.html"],
+    [],
+    effectiveFileChangeAllowlist([], undefined),
+  );
+
+  assert.ok(audit, "audit should be produced");
+  assert.deepEqual(audit.unexpectedFiles, [], ".gitignore must not be flagged when GSD manages it");
+});

package/src/resources/extensions/gsd/tests/fixtures/pr-body/swarm-lane-no-blockers.md

@@ -48,8 +48,4 @@ Closes #123
 
 ## Rollback And Compatibility
 
-- Disable writer sequence enrichment
-
-## AI Assistance Disclosure
-
-This PR was prepared with AI assistance.
+- Disable writer sequence enrichment

package/src/resources/extensions/gsd/tests/fixtures/pr-body/swarm-lane-with-blockers.md

@@ -53,8 +53,4 @@ Closes #123
 
 ## Rollback And Compatibility
 
-- Disable writer sequence enrichment
-
-## AI Assistance Disclosure
-
-This PR was prepared with AI assistance.
+- Disable writer sequence enrichment

package/src/resources/extensions/gsd/tests/gate-state-canonicalization.test.ts

@@ -3,7 +3,7 @@
 
 import { describe, test, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, rmSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
@@ -18,6 +18,7 @@ import {
   insertSlice,
 } from "../gsd-db.ts";
 import type { GateVerdict } from "../types.ts";
+import { closeQualityGatesFromEvidence } from "../quality-gate-closure.ts";
 
 describe("gate-state canonicalization (#4950)", () => {
   let tmpDir: string;
@@ -99,4 +100,50 @@ describe("gate-state canonicalization (#4950)", () => {
       assert.notEqual(g.verdict, "", `gate ${g.gate_id} verdict must not be empty string`);
     }
   });
+
+  test("closeQualityGatesFromEvidence repairs pending gate from durable section", () => {
+    insertGateRow({ milestoneId: "M001", sliceId: "S01", gateId: "Q3", scope: "slice" });
+    mkdirSync(join(tmpDir, ".gsd", "milestones", "M001", "slices", "S01"), { recursive: true });
+    writeFileSync(
+      join(tmpDir, ".gsd", "milestones", "M001", "slices", "S01", "S01-PLAN.md"),
+      [
+        "# S01",
+        "",
+        "## Threat Surface",
+        "",
+        "- Credential stuffing is rate-limited.",
+      ].join("\n"),
+    );
+
+    const result = closeQualityGatesFromEvidence("M001", { artifactBasePath: tmpDir });
+
+    assert.deepEqual(result.unresolved, []);
+    assert.deepEqual(result.repaired, [{ gateId: "Q3", sliceId: "S01", verdict: "pass" }]);
+    assert.equal(getPendingGates("M001", "S01").length, 0);
+    assert.equal(getGateResults("M001", "S01")[0].verdict, "pass");
+  });
+
+  test("closeQualityGatesFromEvidence omits stale pending gate after validation pass", () => {
+    insertGateRow({ milestoneId: "M001", sliceId: "S01", gateId: "Q4", scope: "slice" });
+
+    const result = closeQualityGatesFromEvidence("M001", {
+      artifactBasePath: tmpDir,
+      milestoneValidationPassed: true,
+    });
+
+    assert.deepEqual(result.unresolved, []);
+    assert.deepEqual(result.repaired, [{ gateId: "Q4", sliceId: "S01", verdict: "omitted" }]);
+    assert.equal(getGateResults("M001", "S01")[0].verdict, "omitted");
+  });
+
+  test("closeQualityGatesFromEvidence leaves pending gate unresolved without evidence", () => {
+    insertGateRow({ milestoneId: "M001", sliceId: "S01", gateId: "Q3", scope: "slice" });
+
+    const result = closeQualityGatesFromEvidence("M001", { artifactBasePath: tmpDir });
+
+    assert.deepEqual(result.repaired, []);
+    assert.equal(result.unresolved.length, 1);
+    assert.equal(result.unresolved[0].gate_id, "Q3");
+    assert.equal(getPendingGates("M001", "S01").length, 1);
+  });
 });

package/src/resources/extensions/gsd/tests/gsd-command-home.test.ts

@@ -4,10 +4,13 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
 import { buildGsdHomeModel, showGsdHome } from "../gsd-command-home.ts";
+import { buildIdleMenuSummary, detectIdleMilestoneResidueHint } from "../closeout-wizard.ts";
+import { closeDatabase, insertMilestone, openDatabase } from "../gsd-db.ts";
 import type { GSDState } from "../types.ts";
 
 function baseState(overrides: Partial<GSDState> = {}): GSDState {
@@ -118,6 +121,123 @@ test("/gsd home recommends start or configure after all milestones complete", ()
   assert.match(model.summary.join("\n"), /All milestones complete/);
 });
 
+test("/gsd home recommends fix or recover when milestone git residue is stranded", () => {
+  const model = buildGsdHomeModel(baseState({
+    activeMilestone: null,
+    activeSlice: null,
+    activeTask: null,
+    phase: "complete",
+    nextAction: "All milestones complete.",
+  }), {
+    strandedQuick: null,
+    unmergedMilestones: [],
+    idleResidueHint: {
+      milestoneIds: ["M008"],
+      message:
+        "Stranded milestone git residue detected (M008: worktree dir and/or milestone/* branch). " +
+        "Run /gsd dispatch complete-milestone M008 or /gsd status to recover closeout before starting new work.",
+    },
+  });
+
+  assert.equal(action(model, "fix_recover").recommended, true);
+  assert.equal(action(model, "fix_recover").enabled, true);
+  assert.match(model.summary[0], /Stranded milestone git residue/);
+  assert.equal(action(model, "continue_step").enabled, false);
+});
+
+test("detectIdleMilestoneResidueHint reports missing workflow database in a git repo", () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-home-residue-"));
+  try {
+    execFileSync("git", ["init", "-b", "main"], { cwd: base, stdio: "ignore" });
+    const hint = detectIdleMilestoneResidueHint(base);
+    assert.ok(hint);
+    assert.match(hint!.message, /\.gsd\/gsd\.db/);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("detectIdleMilestoneResidueHint matches unique-format milestone ids (M###-abc123)", () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-home-residue-unique-"));
+  try {
+    execFileSync("git", ["init", "-b", "main"], { cwd: base, stdio: "ignore" });
+    mkdirSync(join(base, ".gsd-worktrees", "M042-abc123"), { recursive: true });
+    mkdirSync(join(base, ".gsd"), { recursive: true });
+
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    try {
+      // Closed milestone with lingering worktree dir — classic residue.
+      insertMilestone({ id: "M042-abc123", title: "Closed Unique", status: "complete" });
+      const hint = detectIdleMilestoneResidueHint(base);
+      assert.ok(hint, "unique-format closed milestone with worktree should be detected");
+      assert.deepEqual(hint!.milestoneIds, ["M042-abc123"]);
+      assert.match(hint!.message, /M042-abc123/);
+    } finally {
+      closeDatabase();
+    }
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("detectIdleMilestoneResidueHint ignores in-flight milestones with worktree artifacts", () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-home-residue-active-"));
+  try {
+    execFileSync("git", ["init", "-b", "main"], { cwd: base, stdio: "ignore" });
+    mkdirSync(join(base, ".gsd-worktrees", "M001"), { recursive: true });
+    mkdirSync(join(base, ".gsd-worktrees", "M002-abc123"), { recursive: true });
+    mkdirSync(join(base, ".gsd"), { recursive: true });
+
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    try {
+      // Active and pending milestones must not be flagged as stranded residue.
+      insertMilestone({ id: "M001", title: "Active milestone", status: "active" });
+      insertMilestone({ id: "M002-abc123", title: "Pending milestone", status: "pending" });
+      const hint = detectIdleMilestoneResidueHint(base);
+      assert.equal(hint, null, "active/pending milestone worktrees must not be classified as residue");
+    } finally {
+      closeDatabase();
+    }
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("buildIdleMenuSummary surfaces idle residue hint even when phase is complete", () => {
+  const summary = buildIdleMenuSummary(
+    {
+      activeMilestone: null,
+      activeSlice: null,
+      activeTask: null,
+      phase: "complete",
+      recentDecisions: [],
+      blockers: [],
+      nextAction: "All milestones complete.",
+      lastCompletedMilestone: { id: "M001", title: "Menu Cleanup" },
+      registry: [{ id: "M001", title: "Menu Cleanup", status: "complete" }],
+      requirements: { active: 0, validated: 0, deferred: 0, outOfScope: 0, blocked: 0, total: 0 },
+      progress: {
+        milestones: { done: 1, total: 1 },
+        slices: { done: 0, total: 0 },
+        tasks: { done: 0, total: 0 },
+      },
+    },
+    {
+      strandedQuick: null,
+      unmergedMilestones: [],
+      idleResidueHint: {
+        milestoneIds: ["M008"],
+        message:
+          "Stranded milestone git residue detected (M008: worktree dir and/or milestone/* branch). " +
+          "Run /gsd dispatch complete-milestone M008 or /gsd status to recover closeout before starting new work.",
+      },
+    },
+  );
+
+  assert.match(summary[0] ?? "", /Stranded milestone git residue/);
+  assert.doesNotMatch(summary.join("\n"), /All milestones complete/);
+});
+
 test("showGsdHome renders the five-slot home text without an interactive TUI", async () => {
   const base = mkdtempSync(join(tmpdir(), "gsd-home-"));
   const notifications: Array<{ message: string; level: string }> = [];

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

@@ -30,6 +30,8 @@ import {
   insertTask,
   getTask,
   getSliceTasks,
+  getMilestoneSliceSummaries,
+  getClosedSliceIds,
   getActiveMilestoneFromDb,
   deleteMilestone,
   clearEngineHierarchy,
@@ -947,6 +949,31 @@ describe('gsd-db', () => {
     closeDatabase();
   });
 
+  test('gsd-db: slice summaries use the canonical closed vocabulary; getClosedSliceIds filters to closed ids', () => {
+    openDatabase(':memory:');
+    insertMilestone({ id: 'M001', status: 'active' });
+    insertSlice({ milestoneId: 'M001', id: 'S01', title: 'Complete', status: 'complete', depends: [], sequence: 1 });
+    insertSlice({ milestoneId: 'M001', id: 'S02', title: 'Done', status: 'done', depends: ['S01'], sequence: 2 });
+    insertSlice({ milestoneId: 'M001', id: 'S03', title: 'Skipped', status: 'skipped', depends: [], sequence: 3 });
+    insertSlice({ milestoneId: 'M001', id: 'S04', title: 'Closed', status: 'closed', depends: [], sequence: 4 });
+    insertSlice({ milestoneId: 'M001', id: 'S05', title: 'Active', status: 'active', depends: [], sequence: 5 });
+    insertSlice({ milestoneId: 'M001', id: 'S06', title: 'Pending', status: 'pending', depends: ['S05'], sequence: 6 });
+
+    const summaries = getMilestoneSliceSummaries('M001');
+    assert.deepStrictEqual(summaries[0], { id: 'S01', title: 'Complete', done: true, depends: [] });
+    assert.deepStrictEqual(summaries[5], { id: 'S06', title: 'Pending', done: false, depends: ['S05'] });
+    assert.deepStrictEqual(
+      summaries.map((s) => s.done),
+      [true, true, true, true, false, false],
+      'complete/done/skipped/closed are closed; active/pending are not',
+    );
+
+    assert.deepStrictEqual(getClosedSliceIds('M001'), ['S01', 'S02', 'S03', 'S04']);
+    assert.deepStrictEqual(getClosedSliceIds('M999'), [], 'unknown milestone yields no closed ids');
+
+    closeDatabase();
+  });
+
   test('gsd-db: FTS5 unavailable warning normalizes provider typo', () => {
     const previousStderr = setStderrLoggingEnabled(false);
     _resetLogs();

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

@@ -0,0 +1,148 @@
+// GSD Extension — Guidance module tests
+// The catalog is the test surface: every typed finding must resolve to
+// non-empty remediation, and load-bearing phrases must survive edits.
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  formatGuidance,
+  recoveryRemediation,
+  needsAttentionBlockerGuidance,
+  needsRemediationBlockerGuidance,
+  uatSignoffBlockerGuidance,
+  worktreeCreationFailedGuidance,
+  crashResumeHint,
+  doctorFixHint,
+  type RecoveryGuidanceKey,
+} from "../guidance.js";
+import { classifyFailure, type RecoveryFailureKind } from "../recovery-classification.js";
+import { isValidationBlockedState } from "../validation-block-guard.js";
+import type { GSDState } from "../types.js";
+
+const RECOVERY_KEYS: RecoveryGuidanceKey[] = [
+  "tool-schema",
+  "tool-contract",
+  "tool-unavailable",
+  "deterministic-policy",
+  "lifecycle-progression",
+  "stale-worker",
+  "worktree-invalid",
+  "verification-drift",
+  "reconciliation-drift",
+  "illegal-transition",
+  "runtime-unknown",
+  "provider-transient",
+  "provider-permanent",
+];
+
+describe("guidance catalog", () => {
+  test("every recovery guidance key resolves to non-empty remediation", () => {
+    for (const key of RECOVERY_KEYS) {
+      const remediation = recoveryRemediation(key);
+      assert.ok(remediation.length > 0, `empty remediation for ${key}`);
+    }
+  });
+
+  test("classifyFailure carries catalog remediation for every failure kind", () => {
+    const kinds: RecoveryFailureKind[] = [
+      "tool-schema",
+      "tool-contract",
+      "deterministic-policy",
+      "lifecycle-progression",
+      "stale-worker",
+      "worktree-invalid",
+      "verification-drift",
+      "reconciliation-drift",
+      "runtime-unknown",
+    ];
+    for (const kind of kinds) {
+      const result = classifyFailure({ error: new Error("boom"), failureKind: kind });
+      assert.equal(result.failureKind, kind);
+      assert.equal(result.exitReason, kind);
+      assert.ok(result.remediation.length > 0, `empty remediation for ${kind}`);
+    }
+  });
+
+  test("escalation kinds with weak guidance now name a concrete command", () => {
+    for (const key of ["stale-worker", "worktree-invalid", "verification-drift", "reconciliation-drift"] as const) {
+      assert.match(recoveryRemediation(key), /\/gsd /, `no command in remediation for ${key}`);
+    }
+  });
+
+  test("formatGuidance numbers steps under the summary", () => {
+    const text = formatGuidance({ summary: "It broke.", steps: ["Fix it.", "Retry."] });
+    assert.equal(text, "It broke.\n\n1. Fix it.\n2. Retry.");
+  });
+
+  test("formatGuidance with no steps is just the summary", () => {
+    assert.equal(formatGuidance({ summary: "All good.", steps: [] }), "All good.");
+  });
+});
+
+describe("milestone blocker guidance", () => {
+  test("needs-attention blocker keeps the phrase the validation-block guard matches", () => {
+    const state = { phase: "blocked", blockers: [needsAttentionBlockerGuidance("M005")] } as unknown as GSDState;
+    assert.ok(isValidationBlockedState(state));
+  });
+
+  test("needs-remediation blocker keeps the phrase the validation-block guard matches", () => {
+    const state = { phase: "blocked", blockers: [needsRemediationBlockerGuidance("M005")] } as unknown as GSDState;
+    assert.ok(isValidationBlockedState(state));
+  });
+
+  test("blockers carry the milestone id and concrete fix commands", () => {
+    const text = needsAttentionBlockerGuidance("M007");
+    assert.match(text, /M007/);
+    assert.match(text, /\/gsd status/);
+    assert.match(text, /\/gsd validate-milestone/);
+  });
+
+  test("UAT sign-off guidance explains direct dispatch target", () => {
+    const missing = uatSignoffBlockerGuidance("M007", "S02");
+    const failing = uatSignoffBlockerGuidance("M007", "S02", "FAIL");
+
+    for (const text of [missing, failing]) {
+      assert.match(text, /Manual UAT sign-off \(PASS\) is required before milestone closure/);
+      assert.match(text, /\/gsd dispatch uat/);
+      assert.match(text, /most recently completed slice/);
+      assert.match(text, /re-run UAT for S02/);
+      assert.match(text, /gsd_uat_result_save/);
+    }
+  });
+
+  test("worktree creation failure guidance does not claim bootstrap continues", () => {
+    const text = worktreeCreationFailedGuidance("M007", "boom");
+
+    assert.match(text, /Auto-worktree creation for M007 failed: boom\. Continuing in project root\./);
+    assert.match(text, /Worktree isolation is degraded for this session\./);
+    assert.doesNotMatch(text, /work continues in the project root/i);
+  });
+});
+
+describe("crash resume hints", () => {
+  test("bootstrap crash reports no work lost", () => {
+    assert.match(crashResumeHint("starting", "bootstrap") ?? "", /No work was lost/);
+  });
+
+  test("unit classes map to their resume hints", () => {
+    assert.match(crashResumeHint("research-milestone", "M001") ?? "", /may be incomplete/);
+    assert.match(crashResumeHint("execute-task", "T001") ?? "", /completed work is preserved/);
+    assert.match(crashResumeHint("complete-slice", "S001") ?? "", /interrupted/);
+  });
+
+  test("unknown unit types yield no hint", () => {
+    assert.equal(crashResumeHint("triage-captures", "X"), undefined);
+  });
+});
+
+describe("doctor fix hints", () => {
+  test("known codes resolve to a hint", () => {
+    assert.ok(doctorFixHint("stale_crash_lock"));
+    assert.ok(doctorFixHint("db_unavailable"));
+  });
+
+  test("codes without authored guidance resolve to undefined", () => {
+    assert.equal(doctorFixHint("delimiter_in_title"), undefined);
+  });
+});

package/src/resources/extensions/gsd/tests/guided-dispatch-root.test.ts

@@ -77,12 +77,8 @@ test("guided dispatch passes the explicit project root through model and compati
             seen.modelRoot = projectRoot;
             return { routing: null, appliedModel: null };
           },
-          getTransportSupportError: (
-            _provider: string | undefined,
-            _requiredTools: string[],
-            options?: { projectRoot?: string },
-          ) => {
-            seen.compatibilityRoot = options?.projectRoot ?? "";
+          getDispatchReadinessError: (input: { projectRoot?: string }) => {
+            seen.compatibilityRoot = input.projectRoot ?? "";
             return null;
           },
         },

package/src/resources/extensions/gsd/tests/integration/auto-worktree-milestone-merge.test.ts

@@ -35,6 +35,7 @@ import {
   insertTask,
   openDatabase,
 } from "../../gsd-db.ts";
+import { createGsdIntegrationProject } from "./gsd-integration-fixture.ts";
 
 function run(cmd: string, cwd: string): string {
   // Safe: all inputs are hardcoded test strings, not user input
@@ -42,17 +43,12 @@ function run(cmd: string, cwd: string): string {
 }
 
 function createTempRepo(): string {
-  const dir = realpathSync(mkdtempSync(join(tmpdir(), "wt-ms-merge-test-")));
-  run("git init", dir);
-  run("git config user.email test@test.com", dir);
-  run("git config user.name Test", dir);
-  writeFileSync(join(dir, "README.md"), "# test\n");
-  mkdirSync(join(dir, ".gsd"), { recursive: true });
-  writeFileSync(join(dir, ".gsd", "STATE.md"), "# State\n");
-  run("git add .", dir);
-  run("git commit -m init", dir);
-  run("git branch -M main", dir);
-  return dir;
+  return createGsdIntegrationProject({
+    prefix: "wt-ms-merge-test-",
+    initialFiles: {
+      ".gsd/STATE.md": "# State\n",
+    },
+  }).root;
 }
 
 function createTempRepoWithExternalGsd(): { repo: string; externalState: string } {
@@ -746,7 +742,7 @@ describe("auto-worktree-milestone-merge", { timeout: 300_000 }, () => {
   });
 
   test("#2156: mergeMilestoneToMain removes external-state worktrees using the milestone branch name", () => {
-    const { repo, externalState } = freshRepoWithExternalGsd();
+    const { repo } = freshRepoWithExternalGsd();
     const wtPath = createAutoWorktree(repo, "M215");
 
     addSliceToMilestone(repo, wtPath, "M215", "S01", "External cleanup", [
@@ -754,9 +750,10 @@ describe("auto-worktree-milestone-merge", { timeout: 300_000 }, () => {
     ]);
 
     const realWtPath = realpathSync(wtPath);
-    assert.ok(
-      realWtPath.startsWith(externalState),
-      `worktree should be registered under external .gsd state, got ${realWtPath}`,
+    assert.equal(
+      realWtPath,
+      join(repo, ".gsd-worktrees", "M215"),
+      `worktree should use canonical path under project root, got ${realWtPath}`,
     );
 
     // Recreate the exact divergence from #1852: local .gsd/ is replaced with a
@@ -783,6 +780,52 @@ describe("auto-worktree-milestone-merge", { timeout: 300_000 }, () => {
     );
   });
 
+  test("#2156 (legacy): mergeMilestoneToMain removes external-state worktrees created under .gsd/worktrees/", () => {
+    const { repo, externalState } = freshRepoWithExternalGsd();
+    // Worktrees created by older versions live at .gsd/worktrees/<MID>; git
+    // resolves the symlink and registers them under external state. Canonical
+    // .gsd-worktrees/ creation never crosses the symlink, so this coverage
+    // creates the legacy worktree explicitly. createAutoWorktree chdirs into
+    // the new worktree and mergeMilestoneToMain reads process.cwd() as the
+    // worktree cwd, so mirror that here.
+    const wtPath = join(repo, ".gsd", "worktrees", "M216");
+    run(`git worktree add -b milestone/M216 "${wtPath}"`, repo);
+    process.chdir(wtPath);
+
+    addSliceToMilestone(repo, wtPath, "M216", "S01", "Legacy external cleanup", [
+      { file: "legacy-external-cleanup.ts", content: "export const legacyExternalCleanup = true;\n", message: "add legacy external cleanup" },
+    ]);
+
+    const realWtPath = realpathSync(wtPath);
+    assert.ok(
+      realWtPath.startsWith(externalState),
+      `legacy worktree should be registered under external .gsd state, got ${realWtPath}`,
+    );
+
+    // Recreate the exact divergence from #1852: local .gsd/ is replaced with a
+    // stale real directory, so the computed path no longer matches git's record.
+    unlinkSync(join(repo, ".gsd"));
+    mkdirSync(join(repo, ".gsd", "worktrees", "M216"), { recursive: true });
+    writeFileSync(join(repo, ".gsd", "STATE.md"), "# Local stale state\n");
+    writeFileSync(join(repo, ".gsd", "worktrees", "M216", "stale.txt"), "stale local artifact\n");
+
+    const roadmap = makeRoadmap("M216", "Legacy external cleanup", [
+      { id: "S01", title: "Legacy external cleanup" },
+    ]);
+
+    mergeMilestoneToMain(repo, "M216", roadmap);
+
+    assert.ok(
+      !run("git worktree list", repo).includes("M216"),
+      "merged legacy milestone worktree should be removed from git worktree list",
+    );
+    assert.ok(!existsSync(realWtPath), "real external worktree directory should be removed");
+    assert.ok(
+      !run("git branch", repo).includes("milestone/M216"),
+      "milestone branch should be deleted after merge cleanup",
+    );
+  });
+
   test("#2912: MERGE_HEAD cleaned up after squash-merge conflict", () => {
     const repo = freshRepo();
     const wtPath = createAutoWorktree(repo, "M291");