@opengsd/gsd-pi 1.4.0-dev.c18009cd → 1.5.0-dev.4fb2d460

package/src/resources/extensions/gsd/tests/auto-artifact-paths.test.ts

@@ -1,6 +1,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, realpathSync, rmSync, utimesSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
@@ -360,6 +360,174 @@ test("canonical worktree + project-root legacy dir produces legacy filename (#bu
   }
 });
 
+// ── cursor[bot] 3523932401: bare milestone id must not match a team-suffix ────
+//
+// A bare milestone id (M001, no team-mode suffix) resolves its phase dir by
+// scanning phases/NN-*. Before the guard (commit 8f45bf3),
+// phaseDirMatchesMilestoneId returned true for ANY same-number dir, so a
+// leftover team-mode projection (phases/01-<6char>-.../, from a prior
+// team-suffixed run) matched the bare id too. When that stale dir carried a
+// newer mtime, pickPreferredPhaseDir selected it over the real title dir and
+// resolved the ROADMAP into a directory that has no ROADMAP — the file-not-found
+// retry loop. The guard (slugLooksLikeTeamSuffixProjection) rejects
+// team-suffix-looking slugs for bare ids in the primary pass; the suffixed
+// projection stays available only as a fallback when the primary pass finds
+// nothing (#1195, guarded by the second test below).
+
+test("bare milestone id prefers the real title dir over a newer team-suffix projection (cursor 3523932401)", () => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-bare-teamsuffix-")));
+  try {
+    const phasesDir = join(root, ".gsd", "phases");
+    // Intended flat-phase dir for the bare id: 01-<title-slug>/ with the ROADMAP.
+    const intendedDir = join(phasesDir, "01-clean-continuation");
+    mkdirSync(intendedDir, { recursive: true });
+    writeFileSync(join(intendedDir, "01-ROADMAP.md"), "# roadmap\n");
+
+    // Leftover team-mode projection: 01-<6char>-.../ with NO ROADMAP, made
+    // NEWER so an mtime tiebreak would wrongly prefer it without the guard.
+    const staleDir = join(phasesDir, "01-re4q3k-old-team-projection");
+    mkdirSync(staleDir, { recursive: true });
+    const newer = new Date(Date.now() + 60_000);
+    const older = new Date(Date.now() - 60_000);
+    utimesSync(staleDir, newer, newer);
+    utimesSync(intendedDir, older, older);
+
+    _clearGsdRootCache();
+    clearPathCache();
+
+    const resolved = resolveExpectedArtifactPath("plan-milestone", "M001", root);
+    assert.equal(
+      resolved,
+      join(intendedDir, "01-ROADMAP.md"),
+      "bare id must resolve to the real title dir, not the newer team-suffix projection",
+    );
+    assert.notEqual(
+      resolved,
+      join(staleDir, "01-ROADMAP.md"),
+      "must NOT resolve into the team-suffix projection dir that has no ROADMAP",
+    );
+  } finally {
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("bare milestone id still falls back to a lone team-suffix projection (#1195)", () => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-bare-teamsuffix-only-")));
+  try {
+    const phasesDir = join(root, ".gsd", "phases");
+    // The only on-disk dir for the bare id is a team-mode projection. With no
+    // non-suffixed candidate, the fallback pass must still resolve to it.
+    const onlyDir = join(phasesDir, "01-re4q3k-clean-continuation");
+    mkdirSync(onlyDir, { recursive: true });
+    writeFileSync(join(onlyDir, "01-ROADMAP.md"), "# roadmap\n");
+
+    _clearGsdRootCache();
+    clearPathCache();
+
+    const resolved = resolveExpectedArtifactPath("plan-milestone", "M001", root);
+    assert.equal(
+      resolved,
+      join(onlyDir, "01-ROADMAP.md"),
+      "with no non-suffixed dir, the team-suffix projection is the correct fallback",
+    );
+  } finally {
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+// ── #1208: flat-phase execute-task summaries resolve at the phase root ────────
+//
+// In flat-phase layout task summaries are written beside the plan files
+// (phases/<phase>/T##-SUMMARY.md), NOT under a tasks/ subdir. A tasks/ dir may
+// still exist to hold auxiliary task-scoped gate artifacts (e.g. T01-VERIFY.json).
+// Before the fix, the mere existence of that tasks/ dir redirected summary
+// verification into tasks/T##-SUMMARY.md — which never exists — trapping auto-mode
+// in a false verification retry that eventually paused after a successful task.
+
+test("flat-phase execute-task summary resolves at phase root when no tasks/ dir exists (#1208)", () => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-flat-task-summary-")));
+  try {
+    const gsd = join(root, ".gsd");
+    const phaseDir = join(gsd, "phases", "49-end-to-end-mandates");
+    mkdirSync(phaseDir, { recursive: true });
+    writeFileSync(join(phaseDir, "49-03-PLAN.md"), "# plan\n- [x] T02\n");
+
+    _clearGsdRootCache();
+    clearPathCache();
+
+    assert.equal(
+      resolveExpectedArtifactPath("execute-task", "M049/S03/T02", root),
+      join(phaseDir, "T02-SUMMARY.md"),
+    );
+  } finally {
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("flat-phase execute-task summary resolves at phase root even when tasks/ dir holds gate artifacts (#1208)", () => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-flat-task-tasksdir-")));
+  try {
+    const gsd = join(root, ".gsd");
+    const phaseDir = join(gsd, "phases", "49-end-to-end-mandates");
+    mkdirSync(phaseDir, { recursive: true });
+    writeFileSync(join(phaseDir, "49-03-PLAN.md"), "# plan\n- [x] T02\n");
+    // Auxiliary task-scoped gate artifact — creates the tasks/ dir but must not
+    // redirect the T02 summary into tasks/.
+    const tasksDir = join(phaseDir, "tasks");
+    mkdirSync(tasksDir, { recursive: true });
+    writeFileSync(join(tasksDir, "T01-VERIFY.json"), '{"ok":true}');
+
+    _clearGsdRootCache();
+    clearPathCache();
+
+    const resolved = resolveExpectedArtifactPath("execute-task", "M049/S03/T02", root);
+    assert.equal(
+      resolved,
+      join(phaseDir, "T02-SUMMARY.md"),
+      "flat-phase task summary must resolve at the phase root, not tasks/",
+    );
+    assert.notEqual(
+      resolved,
+      join(tasksDir, "T02-SUMMARY.md"),
+      "a tasks/ dir with gate artifacts must NOT redirect summary resolution into tasks/",
+    );
+  } finally {
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("legacy execute-task summary still resolves under slices/<SID>/tasks/ (#1208 regression guard)", () => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-legacy-task-summary-")));
+  try {
+    const milestoneDir = join(root, ".gsd", "milestones", "M001");
+    const sliceDir = join(milestoneDir, "slices", "S01");
+    const tasksDir = join(sliceDir, "tasks");
+    mkdirSync(tasksDir, { recursive: true });
+    writeFileSync(join(milestoneDir, "M001-CONTEXT.md"), "# context\n");
+    writeFileSync(join(sliceDir, "S01-PLAN.md"), "# plan\n");
+
+    _clearGsdRootCache();
+    clearPathCache();
+
+    assert.equal(
+      resolveExpectedArtifactPath("execute-task", "M001/S01/T02", root),
+      join(tasksDir, "T02-SUMMARY.md"),
+    );
+  } finally {
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
 // ── resolveSliceResearchLocation / resolveExistingSliceResearchPath ───────────
 //
 // Added in the code-quality consolidation PR as the shared dual-path resolver

package/src/resources/extensions/gsd/tests/auto-loop-no-copy-artifacts.test.ts

@@ -14,7 +14,8 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execFileSync } from "node:child_process";
 
-import { createAutoWorktree, teardownAutoWorktree } from "../auto-worktree.ts";
+import { createAutoWorktree } from "../auto-worktree-creation.ts";
+import { teardownAutoWorktree } from "../auto-worktree-teardown.ts";
 
 function git(args: string[], cwd: string): void {
   execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });

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

@@ -299,6 +299,63 @@ test("refreshRecoveryDbForArtifact treats missing execute-task DB rows as fatal
   });
 });
 
+test("refreshRecoveryDbForArtifact promotes an open execute-task DB row when artifacts are verified on disk (#1204)", () => {
+  const dir = makeTmpProject();
+  insertTask({
+    milestoneId: "M001",
+    sliceId: "S01",
+    id: "T01",
+    title: "Stuck Task",
+    status: "pending",
+  });
+  const sliceDir = join(dir, ".gsd", "milestones", "M001", "slices", "S01");
+  mkdirSync(sliceDir, { recursive: true });
+  writeFileSync(join(sliceDir, "S01-PLAN.md"), [
+    "# S01 Plan",
+    "",
+    "- [ ] **T01: Implement feature** `est:1h`",
+    "",
+  ].join("\n"));
+
+  const result = refreshRecoveryDbForArtifact("execute-task", "M001/S01/T01", dir);
+
+  assert.deepEqual(result, { ok: true });
+  assert.equal(getTask("M001", "S01", "T01")?.status, "complete");
+  const planContent = readFileSync(join(sliceDir, "S01-PLAN.md"), "utf-8");
+  assert.ok(planContent.includes("[x] **T01:"), "plan checkbox should be re-rendered to [x]");
+  const events = readEvents(join(dir, ".gsd", "event-log.jsonl"));
+  assert.ok(
+    events.some((e) => e.cmd === "complete-task" && e.trigger_reason === "stuck-artifact-recovery"),
+    "a complete-task recovery event should be appended",
+  );
+});
+
+test("refreshRecoveryDbForArtifact still appends the recovery event when the plan checkbox sync throws after DB promotion (#1221)", () => {
+  const dir = makeTmpProject();
+  insertTask({
+    milestoneId: "M001",
+    sliceId: "S01",
+    id: "T01",
+    title: "Stuck Task",
+    status: "pending",
+  });
+  const sliceDir = join(dir, ".gsd", "milestones", "M001", "slices", "S01");
+  mkdirSync(sliceDir, { recursive: true });
+  // Make the expected plan path a directory so the best-effort checkbox
+  // rewrite (readFileSync) throws EISDIR after the DB row is already promoted.
+  mkdirSync(join(sliceDir, "S01-PLAN.md"), { recursive: true });
+
+  const result = refreshRecoveryDbForArtifact("execute-task", "M001/S01/T01", dir);
+
+  assert.deepEqual(result, { ok: true });
+  assert.equal(getTask("M001", "S01", "T01")?.status, "complete");
+  const events = readEvents(join(dir, ".gsd", "event-log.jsonl"));
+  assert.ok(
+    events.some((e) => e.cmd === "complete-task" && e.trigger_reason === "stuck-artifact-recovery"),
+    "recovery event must still be appended even when the plan checkbox sync fails",
+  );
+});
+
 test("refreshRecoveryDbForArtifact closes complete-milestone DB row when artifacts exist but DB is stale (#5568)", async () => {
   const base = mkdtempSync(join(tmpdir(), "auto-recovery-complete-ms-"));
   mkdirSync(join(base, ".gsd"), { recursive: true });

package/src/resources/extensions/gsd/tests/auto-start-clean-runtime-db-gated.test.ts

@@ -6,7 +6,7 @@ import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
-import { cleanStaleRuntimeUnits } from "../auto-worktree.ts";
+import { cleanStaleRuntimeUnits } from "../auto-worktree-runtime-cleanup.ts";
 
 function makeBase(): string {
   return join(tmpdir(), `gsd-clean-runtime-${randomUUID()}`);

package/src/resources/extensions/gsd/tests/auto-warning-noise-regression.test.ts

@@ -28,7 +28,8 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 
 import { buildFlatRateContext } from "../auto-model-selection.ts";
-import { _isSamePath, _resetAutoWorktreeOriginalBaseForTests } from "../auto-worktree.ts";
+import { _resetAutoWorktreeOriginalBaseForTests } from "../auto-worktree-session-registry.ts";
+import { _isSamePath } from "../auto-worktree-path-utils.ts";
 import {
   checkAutoStartAfterDiscuss,
   clearPendingAutoStart,

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

@@ -11,7 +11,7 @@ import assert from "node:assert/strict";
 import {
   isSafeToAutoResolve,
   SAFE_AUTO_RESOLVE_PATTERNS,
-} from "../auto-worktree.ts";
+} from "../auto-worktree-conflict-auto-resolve.ts";
 
 describe("isSafeToAutoResolve", () => {
   // ─── .gsd/ state files ───────────────────────────────────────────────────

package/src/resources/extensions/gsd/tests/auto-worktree-merge-already-merged.test.ts

@@ -0,0 +1,177 @@
+// gsd-pi — Regression tests for already-merged milestone cleanup safety.
+
+import { execFileSync } from "node:child_process";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, test } from "node:test";
+
+import {
+  finalizeAlreadyMergedMilestoneIfReachable,
+  type AlreadyMergedMilestoneRequest,
+} from "../auto-worktree-merge-already-merged.js";
+import {
+  _resetMilestoneCleanupDepsForTests,
+  _setMilestoneCleanupDepsForTests,
+} from "../auto-worktree-merge-cleanup.js";
+import { GSDError } from "../errors.js";
+
+const cleanupPaths: string[] = [];
+const initialCwd = process.cwd();
+
+beforeEach(() => {
+  _resetMilestoneCleanupDepsForTests();
+});
+
+afterEach(() => {
+  _resetMilestoneCleanupDepsForTests();
+  process.chdir(initialCwd);
+  for (const path of cleanupPaths.splice(0)) {
+    rmSync(path, { recursive: true, force: true });
+  }
+});
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync("git", args, {
+    cwd,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf-8",
+  }).trim();
+}
+
+function commitFile(cwd: string, file: string, content: string, message: string): string {
+  writeFileSync(join(cwd, file), content);
+  git(cwd, ["add", file]);
+  git(cwd, ["commit", "-m", message]);
+  return git(cwd, ["rev-parse", "HEAD"]);
+}
+
+function createRepo(): string {
+  const repo = mkdtempSync(join(tmpdir(), "gsd-already-merged-"));
+  cleanupPaths.push(repo);
+  git(repo, ["init", "-b", "main"]);
+  git(repo, ["config", "user.email", "test@example.invalid"]);
+  git(repo, ["config", "user.name", "Test"]);
+  commitFile(repo, "README.md", "base\n", "initial");
+  return repo;
+}
+
+function createRegularMergedMilestone(repo: string, milestoneId = "M001"): { milestoneBranch: string } {
+  const milestoneBranch = `milestone/${milestoneId}`;
+  git(repo, ["checkout", "-b", milestoneBranch]);
+  commitFile(repo, "feature.txt", "milestone work\n", `feat: implement ${milestoneId}`);
+  git(repo, ["checkout", "main"]);
+  git(repo, ["merge", "--no-ff", milestoneBranch, "-m", `merge ${milestoneId}`]);
+  return { milestoneBranch };
+}
+
+function request(
+  repo: string,
+  milestoneBranch: string,
+  previousCwd: string,
+): AlreadyMergedMilestoneRequest {
+  return {
+    commitMessage: "merge milestone",
+    mainBranch: "main",
+    milestoneBranch,
+    milestoneId: "M001",
+    previousCwd,
+    projectRoot: repo,
+  };
+}
+
+describe("finalizeAlreadyMergedMilestoneIfReachable", () => {
+  test("returns null when the milestone branch is not reachable from integration branch", () => {
+    const repo = createRepo();
+    git(repo, ["checkout", "-b", "milestone/M001"]);
+    commitFile(repo, "feature.txt", "milestone work\n", "feat: implement M001");
+    git(repo, ["checkout", "main"]);
+
+    let cleanupCalled = false;
+    _setMilestoneCleanupDepsForTests({
+      removeWorktree: () => {
+        cleanupCalled = true;
+        return true;
+      },
+    });
+
+    const result = finalizeAlreadyMergedMilestoneIfReachable(
+      request(repo, "milestone/M001", repo),
+    );
+
+    assert.equal(result, null);
+    assert.equal(cleanupCalled, false, "unmerged branch must not be cleaned up");
+  });
+
+  test("cleans up a regular-merged milestone after main advances", () => {
+    const repo = createRepo();
+    const { milestoneBranch } = createRegularMergedMilestone(repo);
+    commitFile(repo, "hotfix.txt", "later main work\n", "fix: advance main");
+    const previousCwd = join(repo, ".gsd-worktrees", "M001");
+    const calls: string[] = [];
+
+    _setMilestoneCleanupDepsForTests({
+      removeWorktree: (_projectRoot, milestoneId, options) => {
+        assert.ok(options, "cleanup must pass branch options");
+        calls.push(
+          `remove:${milestoneId}:${options.branch}:${String(options.deleteBranch)}`,
+        );
+        return true;
+      },
+      nativeBranchDelete: (_projectRoot, branch) => {
+        calls.push(`delete:${branch}`);
+      },
+      setActiveWorkspace: (workspace) => {
+        calls.push(`workspace:${String(workspace)}`);
+      },
+      nudgeGitBranchCache: (path) => {
+        calls.push(`nudge:${path}`);
+      },
+      chdir: (path) => {
+        calls.push(`chdir:${path}`);
+      },
+    });
+
+    const result = finalizeAlreadyMergedMilestoneIfReachable(
+      request(repo, milestoneBranch, previousCwd),
+    );
+
+    assert.deepEqual(result, {
+      commitMessage: "merge milestone",
+      pushed: false,
+      prCreated: false,
+      codeFilesChanged: true,
+    });
+    assert.deepEqual(calls, [
+      "remove:M001:milestone/M001:false",
+      "delete:milestone/M001",
+      "workspace:null",
+      `nudge:${previousCwd}`,
+      `chdir:${repo}`,
+    ]);
+  });
+
+  test("throws and restores cwd when regular-merged code was later removed from main", () => {
+    const repo = createRepo();
+    const { milestoneBranch } = createRegularMergedMilestone(repo);
+    commitFile(repo, "feature.txt", "", "chore: remove milestone feature");
+    const previousCwd = join(repo, "caller-cwd");
+    mkdirSync(previousCwd);
+    process.chdir(repo);
+
+    assert.throws(
+      () => finalizeAlreadyMergedMilestoneIfReachable(
+        request(repo, milestoneBranch, previousCwd),
+      ),
+      (err: unknown) => err instanceof GSDError
+        && /milestone-touched code file/.test(err.message)
+        && /prevent data loss/.test(err.message),
+    );
+    assert.equal(
+      realpathSync(process.cwd()),
+      realpathSync(previousCwd),
+      "throws before cleanup but restores to the caller's previous cwd",
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/auto-worktree-merge-branch-head.test.ts

@@ -0,0 +1,118 @@
+// gsd-pi — Regression tests for milestone branch/head reconciliation before merge.
+
+import { execFileSync } from "node:child_process";
+import assert from "node:assert/strict";
+import { mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, test } from "node:test";
+
+import { GSDError } from "../errors.js";
+import { reconcileMilestoneBranchHead } from "../auto-worktree-merge-branch-head.js";
+
+const cleanupPaths: string[] = [];
+const initialCwd = process.cwd();
+
+afterEach(() => {
+  process.chdir(initialCwd);
+  for (const path of cleanupPaths.splice(0)) {
+    rmSync(path, { recursive: true, force: true });
+  }
+});
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync("git", args, {
+    cwd,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf-8",
+  }).trim();
+}
+
+function commitFile(cwd: string, file: string, content: string, message: string): string {
+  writeFileSync(join(cwd, file), content);
+  git(cwd, ["add", file]);
+  git(cwd, ["commit", "-m", message]);
+  return git(cwd, ["rev-parse", "HEAD"]);
+}
+
+function createRepoWithMilestoneWorktree(): { repo: string; worktree: string; branch: string } {
+  const repo = mkdtempSync(join(tmpdir(), "gsd-branch-head-"));
+  cleanupPaths.push(repo);
+  git(repo, ["init", "-b", "main"]);
+  git(repo, ["config", "user.email", "test@example.invalid"]);
+  git(repo, ["config", "user.name", "Test"]);
+  commitFile(repo, "README.md", "base\n", "initial");
+
+  const branch = "milestone/M001";
+  git(repo, ["branch", branch]);
+  const worktree = join(repo, ".gsd-worktrees", "M001");
+  git(repo, ["worktree", "add", worktree, branch]);
+  git(worktree, ["config", "user.email", "test@example.invalid"]);
+  git(worktree, ["config", "user.name", "Test"]);
+  return { repo, worktree, branch };
+}
+
+describe("reconcileMilestoneBranchHead", () => {
+  test("fast-forwards stale milestone branch ref to detached worktree HEAD", () => {
+    const { repo, worktree, branch } = createRepoWithMilestoneWorktree();
+    git(worktree, ["checkout", "--detach"]);
+    const detachedHead = commitFile(worktree, "feature.txt", "worktree-only\n", "worktree detached commit");
+
+    const result = reconcileMilestoneBranchHead({
+      projectRoot: repo,
+      worktreeCwd: worktree,
+      milestoneBranch: branch,
+      previousCwd: worktree,
+    });
+
+    assert.deepEqual(result, {
+      checked: true,
+      updated: true,
+      reason: "fast-forwarded",
+    });
+    assert.equal(git(repo, ["rev-parse", branch]), detachedHead);
+  });
+
+  test("throws and restores cwd when worktree HEAD diverges from milestone branch", () => {
+    const { repo, worktree, branch } = createRepoWithMilestoneWorktree();
+    const baseHead = git(repo, ["rev-parse", branch]);
+    git(worktree, ["checkout", "--detach", baseHead]);
+    const detachedHead = commitFile(worktree, "worktree.txt", "detached\n", "detached side");
+
+    git(repo, ["checkout", branch]);
+    const branchHead = commitFile(repo, "branch.txt", "branch\n", "branch side");
+    git(repo, ["checkout", "main"]);
+    process.chdir(repo);
+
+    assert.throws(
+      () => reconcileMilestoneBranchHead({
+        projectRoot: repo,
+        worktreeCwd: worktree,
+        milestoneBranch: branch,
+        previousCwd: worktree,
+      }),
+      (err: unknown) => err instanceof GSDError && /diverged/.test(err.message),
+    );
+
+    assert.equal(git(repo, ["rev-parse", branch]), branchHead, "diverged branch ref must not be moved");
+    assert.equal(git(worktree, ["rev-parse", "HEAD"]), detachedHead, "detached worktree commit remains for manual recovery");
+    assert.equal(realpathSync(process.cwd()), realpathSync(worktree), "divergence restores cwd to previous worktree");
+  });
+
+  test("skips reconciliation when cwd is already the project root", () => {
+    const { repo, branch } = createRepoWithMilestoneWorktree();
+
+    const result = reconcileMilestoneBranchHead({
+      projectRoot: repo,
+      worktreeCwd: repo,
+      milestoneBranch: branch,
+      previousCwd: repo,
+    });
+
+    assert.deepEqual(result, {
+      checked: false,
+      updated: false,
+      reason: "not-worktree",
+    });
+  });
+});