gsd-pi 2.22.0 → 2.24.0

package/dist/resources/extensions/gsd/tests/auto-lock-creation.test.ts

@@ -0,0 +1,186 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, writeFileSync, existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { writeLock, readCrashLock, clearLock, isLockProcessAlive } from "../crash-recovery.ts";
+
+// ─── writeLock creates auto.lock in .gsd/ ────────────────────────────────
+
+test("writeLock creates auto.lock with correct structure", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-lock-test-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+
+  writeLock(dir, "starting", "M001", 0);
+
+  const lockPath = join(dir, ".gsd", "auto.lock");
+  assert.ok(existsSync(lockPath), "auto.lock should exist after writeLock");
+
+  const data = JSON.parse(readFileSync(lockPath, "utf-8"));
+  assert.equal(data.pid, process.pid, "lock should contain current PID");
+  assert.equal(data.unitType, "starting", "lock should contain unit type");
+  assert.equal(data.unitId, "M001", "lock should contain unit ID");
+  assert.equal(data.completedUnits, 0, "lock should show 0 completed units");
+  assert.ok(data.startedAt, "lock should have startedAt timestamp");
+
+  rmSync(dir, { recursive: true, force: true });
+});
+
+test("writeLock updates existing lock with new unit info", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-lock-test-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+
+  writeLock(dir, "starting", "M001", 0);
+  writeLock(dir, "execute-task", "M001/S01/T01", 2, "/tmp/session.jsonl");
+
+  const data = JSON.parse(readFileSync(join(dir, ".gsd", "auto.lock"), "utf-8"));
+  assert.equal(data.unitType, "execute-task", "lock should be updated to new unit type");
+  assert.equal(data.unitId, "M001/S01/T01", "lock should be updated to new unit ID");
+  assert.equal(data.completedUnits, 2, "completed count should be updated");
+  assert.equal(data.sessionFile, "/tmp/session.jsonl", "session file should be recorded");
+
+  rmSync(dir, { recursive: true, force: true });
+});
+
+// ─── readCrashLock reads auto.lock data ──────────────────────────────────
+
+test("readCrashLock returns null when no lock file exists", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-lock-test-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+
+  const lock = readCrashLock(dir);
+  assert.equal(lock, null, "should return null when no lock file");
+
+  rmSync(dir, { recursive: true, force: true });
+});
+
+test("readCrashLock returns lock data when file exists", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-lock-test-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+
+  writeLock(dir, "plan-milestone", "M002", 5);
+  const lock = readCrashLock(dir);
+
+  assert.ok(lock, "should return lock data");
+  assert.equal(lock!.unitType, "plan-milestone");
+  assert.equal(lock!.unitId, "M002");
+  assert.equal(lock!.completedUnits, 5);
+
+  rmSync(dir, { recursive: true, force: true });
+});
+
+// ─── clearLock removes auto.lock ─────────────────────────────────────────
+
+test("clearLock removes the lock file", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-lock-test-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+
+  writeLock(dir, "starting", "M001", 0);
+  assert.ok(existsSync(join(dir, ".gsd", "auto.lock")), "lock should exist before clear");
+
+  clearLock(dir);
+  assert.ok(!existsSync(join(dir, ".gsd", "auto.lock")), "lock should be removed after clear");
+
+  rmSync(dir, { recursive: true, force: true });
+});
+
+test("clearLock is safe when no lock file exists", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-lock-test-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+
+  // Should not throw
+  clearLock(dir);
+
+  rmSync(dir, { recursive: true, force: true });
+});
+
+// ─── isLockProcessAlive detects live vs dead PIDs ────────────────────────
+
+test("isLockProcessAlive returns false for dead PID", () => {
+  const lock = {
+    pid: 9999999,
+    startedAt: new Date().toISOString(),
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+    unitStartedAt: new Date().toISOString(),
+    completedUnits: 0,
+  };
+  assert.equal(isLockProcessAlive(lock), false, "dead PID should return false");
+});
+
+test("isLockProcessAlive returns false for own PID (recycled)", () => {
+  const lock = {
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+    unitStartedAt: new Date().toISOString(),
+    completedUnits: 0,
+  };
+  assert.equal(isLockProcessAlive(lock), false, "own PID should return false (recycled)");
+});
+
+test("isLockProcessAlive returns false for invalid PID", () => {
+  const lock = {
+    pid: -1,
+    startedAt: new Date().toISOString(),
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+    unitStartedAt: new Date().toISOString(),
+    completedUnits: 0,
+  };
+  assert.equal(isLockProcessAlive(lock), false, "negative PID should return false");
+});
+
+// ─── Cross-process detection via lock file ───────────────────────────────
+
+test("lock file enables cross-process auto-mode detection", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-lock-test-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+
+  // Use the parent process PID — guaranteed alive on all platforms (Unix and Windows).
+  // PID 1 (init) only works on Unix; on Windows it doesn't exist.
+  const alivePid = process.ppid;
+  const lockData = {
+    pid: alivePid,
+    startedAt: new Date().toISOString(),
+    unitType: "execute-task",
+    unitId: "M001/S01/T02",
+    unitStartedAt: new Date().toISOString(),
+    completedUnits: 3,
+  };
+  writeFileSync(join(dir, ".gsd", "auto.lock"), JSON.stringify(lockData, null, 2));
+
+  const lock = readCrashLock(dir);
+  assert.ok(lock, "should read the lock");
+  assert.equal(lock!.pid, alivePid);
+
+  // Parent PID is always alive — isLockProcessAlive should detect it
+  const alive = isLockProcessAlive(lock!);
+  assert.equal(alive, true, "parent PID should be detected as alive");
+
+  rmSync(dir, { recursive: true, force: true });
+});
+
+test("stale lock from dead process is detected as not alive", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-lock-test-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+
+  // Simulate a stale lock from a process that no longer exists
+  const lockData = {
+    pid: 9999999,
+    startedAt: "2026-03-01T00:00:00Z",
+    unitType: "plan-slice",
+    unitId: "M001/S02",
+    unitStartedAt: "2026-03-01T00:05:00Z",
+    completedUnits: 1,
+  };
+  writeFileSync(join(dir, ".gsd", "auto.lock"), JSON.stringify(lockData, null, 2));
+
+  const lock = readCrashLock(dir);
+  assert.ok(lock, "should read the stale lock");
+  assert.equal(isLockProcessAlive(lock!), false, "dead process should not be alive");
+
+  rmSync(dir, { recursive: true, force: true });
+});

package/dist/resources/extensions/gsd/tests/auto-preflight.test.ts

@@ -17,6 +17,7 @@ writeFileSync(join(gsd, "milestones", "M001", "slices", "S01", "S01-PLAN.md"), `
 writeFileSync(join(gsd, "milestones", "M001", "slices", "S01", "tasks", "T01-SUMMARY.md"), `---\nid: T01\nparent: S01\nmilestone: M001\nprovides: []\nrequires: []\naffects: []\nkey_files: []\nkey_decisions: []\npatterns_established: []\nobservability_surfaces: []\ndrill_down_paths: []\nduration: 5m\nverification_result: passed\ncompleted_at: 2026-03-09T00:00:00Z\n---\n\n# T01: Old Task\n\n**Done**\n\n## What Happened\nDone.\n\n## Diagnostics\n- log\n`);
 writeFileSync(join(gsd, "milestones", "M001", "slices", "S01", "S01-SUMMARY.md"), `---\nid: S01\nparent: M001\nmilestone: M001\nprovides: []\nrequires: []\naffects: []\nkey_files: []\nkey_decisions: []\npatterns_established: []\nobservability_surfaces: []\ndrill_down_paths: []\nduration: 5m\nverification_result: passed\ncompleted_at: 2026-03-09T00:00:00Z\n---\n\n# S01: Old Slice\n\n**Done**\n\n## What Happened\nDone.\n\n## Verification\nDone.\n\n## Deviations\nNone\n\n## Known Limitations\nNone\n\n## Follow-ups\nNone\n\n## Files Created/Modified\n- \`x\` — x\n\n## Forward Intelligence\n\n### What the next slice should know\n- x\n\n### What's fragile\n- x\n\n### Authoritative diagnostics\n- x\n\n### What assumptions changed\n- x\n`);
 
+writeFileSync(join(gsd, "milestones", "M001", "M001-VALIDATION.md"), `---\nverdict: pass\nremediation_round: 0\n---\n\n# Validation\nPassed.\n`);
 writeFileSync(join(gsd, "milestones", "M001", "M001-SUMMARY.md"), `---\nid: M001\nstatus: complete\ncompleted_at: 2026-03-09T00:00:00Z\n---\n\n# M001: Historical\n\nComplete.\n`);
 
 writeFileSync(join(gsd, "milestones", "M009", "M009-ROADMAP.md"), `# M009: Active\n\n## Slices\n- [ ] **S01: Active Slice** \`risk:low\` \`depends:[]\`\n  > After this: active works\n`);

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

@@ -10,6 +10,7 @@ import {
   verifyExpectedArtifact,
   diagnoseExpectedArtifact,
   buildLoopRemediationSteps,
+  selfHealRuntimeRecords,
   completedKeysPath,
   persistCompletedKey,
   removePersistedKey,
@@ -273,6 +274,68 @@ test("removePersistedKey is safe when file doesn't exist", () => {
   }
 });
 
+// ─── Dual-load across worktree boundary (#769) ───────────────────────────
+
+test("loadPersistedKeys unions keys from project root and worktree", () => {
+  // Simulate two separate .gsd directories (project root + worktree)
+  // each with a different set of completed keys. Loading from both
+  // into the same Set should produce the union.
+  const projectRoot = makeTmpBase();
+  const worktree = makeTmpBase();
+  try {
+    // Persist different keys in each location
+    persistCompletedKey(projectRoot, "execute-task/M001/S01/T01");
+    persistCompletedKey(projectRoot, "plan-slice/M001/S02");
+
+    persistCompletedKey(worktree, "execute-task/M001/S01/T02");
+    persistCompletedKey(worktree, "plan-slice/M001/S02"); // overlap
+
+    // Load from both into the same set (mimicking startup dual-load)
+    const keys = new Set<string>();
+    loadPersistedKeys(projectRoot, keys);
+    loadPersistedKeys(worktree, keys);
+
+    assert.ok(keys.has("execute-task/M001/S01/T01"), "key from project root");
+    assert.ok(keys.has("plan-slice/M001/S02"), "shared key");
+    assert.ok(keys.has("execute-task/M001/S01/T02"), "key from worktree");
+    assert.equal(keys.size, 3, "union should deduplicate overlapping keys");
+  } finally {
+    cleanup(projectRoot);
+    cleanup(worktree);
+  }
+});
+
+test("completed-units.json set-union merge produces correct result", () => {
+  // Verify that a manual set-union merge (as done in syncStateToProjectRoot)
+  // correctly merges two JSON arrays of keys.
+  const projectRoot = makeTmpBase();
+  const worktree = makeTmpBase();
+  try {
+    // Write keys to both locations
+    const prKeysFile = join(projectRoot, ".gsd", "completed-units.json");
+    const wtKeysFile = join(worktree, ".gsd", "completed-units.json");
+
+    writeFileSync(prKeysFile, JSON.stringify(["a", "b"]));
+    writeFileSync(wtKeysFile, JSON.stringify(["b", "c", "d"]));
+
+    // Perform the same merge logic used in syncStateToProjectRoot
+    const srcKeys: string[] = JSON.parse(readFileSync(wtKeysFile, "utf8"));
+    let dstKeys: string[] = [];
+    if (existsSync(prKeysFile)) {
+      dstKeys = JSON.parse(readFileSync(prKeysFile, "utf8"));
+    }
+    const merged = [...new Set([...dstKeys, ...srcKeys])];
+    writeFileSync(prKeysFile, JSON.stringify(merged, null, 2));
+
+    // Verify the merged result
+    const result: string[] = JSON.parse(readFileSync(prKeysFile, "utf8"));
+    assert.deepStrictEqual(result.sort(), ["a", "b", "c", "d"]);
+  } finally {
+    cleanup(projectRoot);
+    cleanup(worktree);
+  }
+});
+
 // ─── verifyExpectedArtifact: parse cache collision regression ─────────────
 
 test("verifyExpectedArtifact detects roadmap [x] change despite parse cache", () => {
@@ -320,3 +383,204 @@ test("verifyExpectedArtifact detects roadmap [x] change despite parse cache", ()
     cleanup(base);
   }
 });
+
+// ─── verifyExpectedArtifact: plan-slice empty scaffold regression (#699) ──
+
+test("verifyExpectedArtifact rejects plan-slice with empty scaffold", () => {
+  const base = makeTmpBase();
+  try {
+    const sliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01");
+    mkdirSync(sliceDir, { recursive: true });
+    writeFileSync(join(sliceDir, "S01-PLAN.md"), "# S01: Test Slice\n\n## Tasks\n\n");
+    assert.strictEqual(
+      verifyExpectedArtifact("plan-slice", "M001/S01", base),
+      false,
+      "Empty scaffold should not be treated as completed artifact",
+    );
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("verifyExpectedArtifact accepts plan-slice with actual tasks", () => {
+  const base = makeTmpBase();
+  try {
+    const sliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01");
+    const tasksDir = join(sliceDir, "tasks");
+    mkdirSync(tasksDir, { recursive: true });
+    writeFileSync(join(sliceDir, "S01-PLAN.md"), [
+      "# S01: Test Slice",
+      "",
+      "## Tasks",
+      "",
+      "- [ ] **T01: Implement feature** `est:2h`",
+      "- [ ] **T02: Write tests** `est:1h`",
+    ].join("\n"));
+    writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01 Plan");
+    writeFileSync(join(tasksDir, "T02-PLAN.md"), "# T02 Plan");
+    assert.strictEqual(
+      verifyExpectedArtifact("plan-slice", "M001/S01", base),
+      true,
+      "Plan with task entries should be treated as completed artifact",
+    );
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("verifyExpectedArtifact accepts plan-slice with completed tasks", () => {
+  const base = makeTmpBase();
+  try {
+    const sliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01");
+    const tasksDir = join(sliceDir, "tasks");
+    mkdirSync(tasksDir, { recursive: true });
+    writeFileSync(join(sliceDir, "S01-PLAN.md"), [
+      "# S01: Test Slice",
+      "",
+      "## Tasks",
+      "",
+      "- [x] **T01: Implement feature** `est:2h`",
+      "- [ ] **T02: Write tests** `est:1h`",
+    ].join("\n"));
+    writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01 Plan");
+    writeFileSync(join(tasksDir, "T02-PLAN.md"), "# T02 Plan");
+    assert.strictEqual(
+      verifyExpectedArtifact("plan-slice", "M001/S01", base),
+      true,
+      "Plan with completed task entries should be treated as completed artifact",
+    );
+  } finally {
+    cleanup(base);
+  }
+});
+
+// ─── verifyExpectedArtifact: plan-slice task plan check (#739) ────────────
+
+test("verifyExpectedArtifact plan-slice passes when all task plan files exist", () => {
+  const base = makeTmpBase();
+  try {
+    const tasksDir = join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks");
+    const planPath = join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-PLAN.md");
+    const planContent = [
+      "# S01: Test Slice",
+      "",
+      "## Tasks",
+      "",
+      "- [ ] **T01: First task** `est:1h`",
+      "- [ ] **T02: Second task** `est:2h`",
+    ].join("\n");
+    writeFileSync(planPath, planContent);
+    writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01 Plan\n\nDo the thing.");
+    writeFileSync(join(tasksDir, "T02-PLAN.md"), "# T02 Plan\n\nDo the other thing.");
+
+    const result = verifyExpectedArtifact("plan-slice", "M001/S01", base);
+    assert.equal(result, true, "should pass when all task plan files exist");
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("verifyExpectedArtifact plan-slice fails when a task plan file is missing (#739)", () => {
+  const base = makeTmpBase();
+  try {
+    const tasksDir = join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks");
+    const planPath = join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-PLAN.md");
+    const planContent = [
+      "# S01: Test Slice",
+      "",
+      "## Tasks",
+      "",
+      "- [ ] **T01: First task** `est:1h`",
+      "- [ ] **T02: Second task** `est:2h`",
+    ].join("\n");
+    writeFileSync(planPath, planContent);
+    // Only write T01-PLAN.md — T02 is missing
+    writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01 Plan\n\nDo the thing.");
+
+    const result = verifyExpectedArtifact("plan-slice", "M001/S01", base);
+    assert.equal(result, false, "should fail when T02-PLAN.md is missing");
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("verifyExpectedArtifact plan-slice fails for plan with no tasks (#699)", () => {
+  const base = makeTmpBase();
+  try {
+    const planPath = join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-PLAN.md");
+    const planContent = [
+      "# S01: Test Slice",
+      "",
+      "## Goal",
+      "",
+      "Just some documentation updates, no tasks.",
+    ].join("\n");
+    writeFileSync(planPath, planContent);
+
+    const result = verifyExpectedArtifact("plan-slice", "M001/S01", base);
+    assert.equal(result, false, "should fail when plan has no task entries (empty scaffold, #699)");
+  } finally {
+    cleanup(base);
+  }
+});
+
+// ─── selfHealRuntimeRecords — worktree base path (#769) ──────────────────
+
+test("selfHealRuntimeRecords clears stale record when artifact exists at worktree base (#769)", async () => {
+  // Simulate worktree layout: the runtime record AND the artifact both live
+  // under the worktree's .gsd/, not the main project root.
+  const worktreeBase = makeTmpBase();
+  const mainBase = makeTmpBase();
+  try {
+    const { writeUnitRuntimeRecord, readUnitRuntimeRecord } = await import("../unit-runtime.ts");
+
+    // Write a stale runtime record in the worktree .gsd/runtime/units/
+    writeUnitRuntimeRecord(worktreeBase, "run-uat", "M001/S01", Date.now() - 7200_000, {
+      phase: "dispatched",
+    });
+
+    // Write the UAT result artifact in the worktree .gsd/milestones/
+    const uatPath = join(worktreeBase, ".gsd", "milestones", "M001", "slices", "S01", "S01-UAT-RESULT.md");
+    writeFileSync(uatPath, "---\nresult: pass\n---\n# UAT Result\nAll tests passed.\n");
+
+    // Verify the runtime record exists before heal
+    const before = readUnitRuntimeRecord(worktreeBase, "run-uat", "M001/S01");
+    assert.ok(before, "runtime record should exist before heal");
+
+    // Mock ExtensionContext with minimal notify
+    const notifications: string[] = [];
+    const mockCtx = {
+      ui: { notify: (msg: string) => { notifications.push(msg); } },
+    } as any;
+
+    // Call selfHeal with worktreeBase — this is the fix: using the worktree path
+    // so both the runtime record and artifact are found
+    const completedKeys = new Set<string>();
+    await selfHealRuntimeRecords(worktreeBase, mockCtx, completedKeys);
+
+    // The stale record should be cleared
+    const after = readUnitRuntimeRecord(worktreeBase, "run-uat", "M001/S01");
+    assert.equal(after, null, "runtime record should be cleared after heal");
+
+    // The completion key should be persisted
+    assert.ok(completedKeys.has("run-uat/M001/S01"), "completion key should be added");
+    assert.ok(notifications.some(n => n.includes("Self-heal")), "should emit self-heal notification");
+
+    // Now verify that calling with mainBase does NOT find/clear anything (the old bug)
+    // Write a stale record at mainBase but NO artifact there
+    writeUnitRuntimeRecord(mainBase, "run-uat", "M001/S01", Date.now() - 7200_000, {
+      phase: "dispatched",
+    });
+    const mainKeys = new Set<string>();
+    await selfHealRuntimeRecords(mainBase, mockCtx, mainKeys);
+
+    // The record at mainBase should be cleared by the stale timeout (>1h),
+    // but the completion key should NOT be set (artifact doesn't exist at mainBase)
+    const afterMain = readUnitRuntimeRecord(mainBase, "run-uat", "M001/S01");
+    assert.equal(afterMain, null, "stale record at main base should be cleared by timeout");
+    assert.ok(!mainKeys.has("run-uat/M001/S01"), "completion key should NOT be set when artifact is missing");
+  } finally {
+    cleanup(worktreeBase);
+    cleanup(mainBase);
+  }
+});

package/dist/resources/extensions/gsd/tests/auto-skip-loop.test.ts

@@ -0,0 +1,123 @@
+/**
+ * auto-skip-loop.test.ts — Tests for the consecutive-skip loop breaker.
+ *
+ * Regression for #728: auto-mode infinite skip loop on previously completed
+ * plan-slice units when deriveState keeps returning the same unit.
+ *
+ * The skip paths in dispatchNextUnit track consecutive skips per unit via
+ * unitConsecutiveSkips. When the same unit is skipped > MAX_CONSECUTIVE_SKIPS
+ * times without a real dispatch in between, the completion record is evicted
+ * so deriveState can reconcile.
+ */
+
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  _getUnitConsecutiveSkips,
+  _resetUnitConsecutiveSkips,
+  MAX_CONSECUTIVE_SKIPS,
+} from "../auto.ts";
+import { persistCompletedKey, removePersistedKey, loadPersistedKeys } from "../auto-recovery.ts";
+import { createTestContext } from "./test-helpers.ts";
+
+const { assertEq, assertTrue, report } = createTestContext();
+
+function makeTmpBase(): string {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-skip-loop-test-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+  return dir;
+}
+
+async function main(): Promise<void> {
+  // ─── Counter starts at zero ────────────────────────────────────────────
+  console.log("\n=== skip loop counter: initial state ===");
+  {
+    _resetUnitConsecutiveSkips();
+    const map = _getUnitConsecutiveSkips();
+    assertEq(map.size, 0, "counter map starts empty after reset");
+  }
+
+  // ─── Counter increments correctly ────────────────────────────────────
+  console.log("\n=== skip loop counter: increments on repeated calls ===");
+  {
+    _resetUnitConsecutiveSkips();
+    const map = _getUnitConsecutiveSkips();
+    const key = "plan-slice/M001/S04";
+
+    for (let i = 1; i <= MAX_CONSECUTIVE_SKIPS; i++) {
+      const prev = map.get(key) ?? 0;
+      map.set(key, prev + 1);
+    }
+
+    assertEq(map.get(key), MAX_CONSECUTIVE_SKIPS, `counter reaches MAX_CONSECUTIVE_SKIPS (${MAX_CONSECUTIVE_SKIPS})`);
+  }
+
+  // ─── Threshold constant is sane ──────────────────────────────────────
+  console.log("\n=== skip loop counter: threshold is reasonable ===");
+  {
+    assertTrue(MAX_CONSECUTIVE_SKIPS >= 3, "threshold allows a few legitimate skips");
+    assertTrue(MAX_CONSECUTIVE_SKIPS <= 10, "threshold catches loops quickly");
+  }
+
+  // ─── Reset clears all keys ────────────────────────────────────────────
+  console.log("\n=== skip loop counter: reset clears all keys ===");
+  {
+    _resetUnitConsecutiveSkips();
+    const map = _getUnitConsecutiveSkips();
+    map.set("plan-slice/M001/S01", 2);
+    map.set("plan-slice/M001/S02", 1);
+    assertEq(map.size, 2, "map has 2 entries before reset");
+
+    _resetUnitConsecutiveSkips();
+    assertEq(_getUnitConsecutiveSkips().size, 0, "map empty after reset");
+  }
+
+  // ─── Eviction path: persistCompletedKey + removePersistedKey round-trip
+  //     (simulates what the loop-breaker does) ───────────────────────────
+  console.log("\n=== skip loop counter: eviction removes persisted key ===");
+  {
+    _resetUnitConsecutiveSkips();
+    const base = makeTmpBase();
+    try {
+      const key = "plan-slice/M001/S04";
+      const keySet = new Set<string>();
+
+      persistCompletedKey(base, key);
+      loadPersistedKeys(base, keySet);
+      assertTrue(keySet.has(key), "key persisted before eviction");
+
+      // Simulate loop-breaker eviction
+      keySet.delete(key);
+      removePersistedKey(base, key);
+      const keySet2 = new Set<string>();
+      loadPersistedKeys(base, keySet2);
+      assertTrue(!keySet2.has(key), "key absent after eviction");
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  }
+
+  // ─── Counter resets per-key, not globally ─────────────────────────────
+  console.log("\n=== skip loop counter: per-key isolation ===");
+  {
+    _resetUnitConsecutiveSkips();
+    const map = _getUnitConsecutiveSkips();
+    map.set("plan-slice/M001/S04", MAX_CONSECUTIVE_SKIPS + 1);
+    map.set("plan-slice/M001/S05", 1);
+
+    // Deleting S04 (eviction) should not affect S05
+    map.delete("plan-slice/M001/S04");
+    assertTrue(!map.has("plan-slice/M001/S04"), "S04 evicted");
+    assertEq(map.get("plan-slice/M001/S05"), 1, "S05 counter unaffected");
+  }
+
+  _resetUnitConsecutiveSkips();
+  report();
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

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

@@ -290,6 +290,40 @@ async function main(): Promise<void> {
       assertTrue(existsSync(join(repo, "feature.ts")), "feature.ts merged to main");
     }
 
+    // ─── Test 6: Skip checkout when main already current (#757) ───────
+    console.log("\n=== skip checkout when main already current (#757) ===");
+    {
+      const repo = freshRepo();
+      const wtPath = createAutoWorktree(repo, "M060");
+
+      addSliceToMilestone(repo, wtPath, "M060", "S01", "Skip checkout test", [
+        { file: "skip-checkout.ts", content: "export const skip = true;\n", message: "add skip-checkout" },
+      ]);
+
+      const roadmap = makeRoadmap("M060", "Skip checkout verification", [
+        { id: "S01", title: "Skip checkout test" },
+      ]);
+
+      // Verify main is already checked out at repo root (worktree default)
+      const branchAtRoot = run("git rev-parse --abbrev-ref HEAD", repo);
+      assertEq(branchAtRoot, "main", "main is already checked out at project root");
+
+      // mergeMilestoneToMain should succeed without attempting to checkout main
+      // (which would fail with "already used by worktree" error)
+      let threw = false;
+      try {
+        const result = mergeMilestoneToMain(repo, "M060", roadmap);
+        assertTrue(result.commitMessage.includes("feat(M060)"), "merge commit created");
+      } catch (err) {
+        threw = true;
+        console.error("Unexpected error:", err);
+      }
+      assertTrue(!threw, "does not fail when main is already checked out at project root");
+
+      // Verify the merge actually happened
+      assertTrue(existsSync(join(repo, "skip-checkout.ts")), "skip-checkout.ts merged to main");
+    }
+
   } finally {
     process.chdir(savedCwd);
     for (const d of tempDirs) {

package/dist/resources/extensions/gsd/tests/complete-milestone.test.ts

@@ -45,6 +45,12 @@ function writeMilestoneSummary(base: string, mid: string, content: string): void
   writeFileSync(join(dir, `${mid}-SUMMARY.md`), content);
 }
 
+function writeMilestoneValidation(base: string, mid: string, verdict: string = "pass"): void {
+  const dir = join(base, ".gsd", "milestones", mid);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${mid}-VALIDATION.md`), `---\nverdict: ${verdict}\nremediation_round: 0\n---\n\n# Validation\nValidated.`);
+}
+
 function cleanup(base: string): void {
   rmSync(base, { recursive: true, force: true });
 }
@@ -176,7 +182,8 @@ async function main(): Promise<void> {
       const roadmap = parseRoadmap(roadmapContent!);
       assertTrue(isMilestoneComplete(roadmap), "isMilestoneComplete returns true when all slices are [x]");
 
-      // Verify deriveState returns completing-milestone phase
+      // Verify deriveState returns completing-milestone phase (with validation already done)
+      writeMilestoneValidation(base, "M001");
       const state = await deriveState(base);
       assertEq(state.phase, "completing-milestone", "deriveState returns completing-milestone when all slices done, no summary");
       assertEq(state.activeMilestone?.id, "M001", "active milestone is M001");