gsd-pi 2.49.0-dev.de3d9f6 → 2.50.0-dev.9476db8

package/src/resources/extensions/gsd/tests/session-lock-transient-read.test.ts

@@ -0,0 +1,223 @@
+/**
+ * session-lock-transient-read.test.ts — Tests for transient lock file unreadability (#2324).
+ *
+ * Regression coverage for:
+ *   #2324  onCompromised declares lock lost when the lock file is temporarily
+ *          unreadable (NFS/CIFS latency, macOS APFS snapshot, concurrent process
+ *          briefly holding the file).
+ *
+ * Tests:
+ *   - readExistingLockDataWithRetry retries on transient read failure
+ *   - readExistingLockDataWithRetry returns data when file becomes readable after retries
+ *   - readExistingLockDataWithRetry returns null only when ALL retries exhausted
+ *   - onCompromised does not declare compromise when lock file is transiently unreadable
+ */
+
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, renameSync, unlinkSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { execSync, spawn } from 'node:child_process';
+
+import {
+  acquireSessionLock,
+  getSessionLockStatus,
+  releaseSessionLock,
+  readExistingLockDataWithRetry,
+  type SessionLockData,
+} from '../session-lock.ts';
+import { gsdRoot } from '../paths.ts';
+import { createTestContext } from './test-helpers.ts';
+
+const { assertEq, assertTrue, report } = createTestContext();
+
+async function main(): Promise<void> {
+
+  // ─── 1. readExistingLockDataWithRetry succeeds on first read when file is fine ─
+  console.log('\n=== 1. readExistingLockDataWithRetry reads file normally ===');
+  {
+    const base = mkdtempSync(join(tmpdir(), 'gsd-transient-'));
+    mkdirSync(join(base, '.gsd'), { recursive: true });
+
+    try {
+      const lockFile = join(gsdRoot(base), 'auto.lock');
+      const lockData: SessionLockData = {
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+        unitType: 'execute-task',
+        unitId: 'M001/S01/T01',
+        unitStartedAt: new Date().toISOString(),
+        sessionFile: 'test-session.json',
+      };
+      writeFileSync(lockFile, JSON.stringify(lockData, null, 2));
+
+      const result = readExistingLockDataWithRetry(lockFile);
+      assertTrue(result !== null, 'data returned for readable file');
+      assertEq(result!.pid, process.pid, 'correct PID read');
+      assertEq(result!.sessionFile, 'test-session.json', 'correct sessionFile read');
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  }
+
+  // ─── 2. readExistingLockDataWithRetry returns null for truly missing file ──
+  console.log('\n=== 2. readExistingLockDataWithRetry returns null for missing file ===');
+  {
+    const base = mkdtempSync(join(tmpdir(), 'gsd-transient-'));
+    mkdirSync(join(base, '.gsd'), { recursive: true });
+
+    try {
+      const lockFile = join(gsdRoot(base), 'auto.lock');
+      // File doesn't exist
+      const result = readExistingLockDataWithRetry(lockFile, { maxAttempts: 2, delayMs: 10 });
+      assertEq(result, null, 'null for truly missing file after retries');
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  }
+
+  // ─── 3. readExistingLockDataWithRetry recovers after transient rename ──────
+  console.log('\n=== 3. readExistingLockDataWithRetry recovers after transient unavailability ===');
+  {
+    const base = mkdtempSync(join(tmpdir(), 'gsd-transient-'));
+    mkdirSync(join(base, '.gsd'), { recursive: true });
+
+    try {
+      const lockFile = join(gsdRoot(base), 'auto.lock');
+      const tmpFile = lockFile + '.hidden';
+      const lockData: SessionLockData = {
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+        unitType: 'execute-task',
+        unitId: 'M001/S01/T01',
+        unitStartedAt: new Date().toISOString(),
+        sessionFile: 'recovery-session.json',
+      };
+      writeFileSync(lockFile, JSON.stringify(lockData, null, 2));
+
+      // Simulate transient unavailability: move file away, spawn a child process
+      // to restore it after 100ms. The child runs outside our event loop so it
+      // fires even during busy-wait retries.
+      renameSync(lockFile, tmpFile);
+      spawn('bash', ['-c', `sleep 0.1 && mv "${tmpFile}" "${lockFile}"`], { stdio: 'ignore', detached: true }).unref();
+
+      // With retries (3 attempts, 200ms delay), it should recover on 2nd or 3rd attempt
+      const result = readExistingLockDataWithRetry(lockFile, { maxAttempts: 3, delayMs: 200 });
+      assertTrue(result !== null, 'data recovered after transient unavailability');
+      if (result) {
+        assertEq(result.pid, process.pid, 'correct PID after recovery');
+        assertEq(result.sessionFile, 'recovery-session.json', 'correct sessionFile after recovery');
+      }
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  }
+
+  // ─── 4. readExistingLockDataWithRetry recovers from transient permission error ─
+  console.log('\n=== 4. readExistingLockDataWithRetry recovers from transient permission error ===');
+  {
+    const base = mkdtempSync(join(tmpdir(), 'gsd-transient-'));
+    mkdirSync(join(base, '.gsd'), { recursive: true });
+
+    try {
+      const lockFile = join(gsdRoot(base), 'auto.lock');
+      const lockData: SessionLockData = {
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+        unitType: 'execute-task',
+        unitId: 'M001/S01/T01',
+        unitStartedAt: new Date().toISOString(),
+        sessionFile: 'perm-session.json',
+      };
+      writeFileSync(lockFile, JSON.stringify(lockData, null, 2));
+
+      // Remove read permission to simulate NFS/CIFS latency, then spawn a child
+      // to restore permissions after 100ms (runs outside our event loop).
+      chmodSync(lockFile, 0o000);
+      spawn('bash', ['-c', `sleep 0.1 && chmod 644 "${lockFile}"`], { stdio: 'ignore', detached: true }).unref();
+
+      const result = readExistingLockDataWithRetry(lockFile, { maxAttempts: 3, delayMs: 200 });
+      assertTrue(result !== null, 'data recovered after transient permission error');
+      if (result) {
+        assertEq(result.pid, process.pid, 'correct PID after permission recovery');
+      }
+
+      // Ensure permissions restored for cleanup
+      try { chmodSync(lockFile, 0o644); } catch { /* best-effort */ }
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  }
+
+  // ─── 5. getSessionLockStatus does not false-positive on transient read failure ─
+  console.log('\n=== 5. getSessionLockStatus tolerates transient lock file unavailability ===');
+  {
+    const base = mkdtempSync(join(tmpdir(), 'gsd-transient-'));
+    mkdirSync(join(base, '.gsd'), { recursive: true });
+
+    try {
+      const result = acquireSessionLock(base);
+      assertTrue(result.acquired, 'lock acquired');
+
+      // Validate works initially
+      const status1 = getSessionLockStatus(base);
+      assertTrue(status1.valid, 'lock valid before transient failure');
+
+      // Temporarily hide the lock file
+      const lockFile = join(gsdRoot(base), 'auto.lock');
+      const tmpFile = lockFile + '.hidden';
+      renameSync(lockFile, tmpFile);
+
+      // Schedule restoration
+      setTimeout(() => {
+        try { renameSync(tmpFile, lockFile); } catch { /* best-effort */ }
+      }, 30);
+
+      // Small delay to ensure restoration runs, then check — with the OS lock
+      // still held, getSessionLockStatus should return valid=true even if the
+      // lock file was briefly missing (it checks _releaseFunction first).
+      await new Promise(r => setTimeout(r, 60));
+      const status2 = getSessionLockStatus(base);
+      assertTrue(status2.valid, 'lock still valid after transient file disappearance (OS lock held)');
+
+      // Restore if not yet restored
+      try { renameSync(tmpFile, lockFile); } catch { /* already restored */ }
+
+      releaseSessionLock(base);
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  }
+
+  // ─── 6. Retry defaults: 3 attempts with 200ms delay ────────────────────────
+  console.log('\n=== 6. Default retry params: function works with defaults ===');
+  {
+    const base = mkdtempSync(join(tmpdir(), 'gsd-transient-'));
+    mkdirSync(join(base, '.gsd'), { recursive: true });
+
+    try {
+      const lockFile = join(gsdRoot(base), 'auto.lock');
+      const lockData: SessionLockData = {
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+        unitType: 'execute-task',
+        unitId: 'M001/S01/T01',
+        unitStartedAt: new Date().toISOString(),
+        sessionFile: 'status-session.json',
+      };
+      writeFileSync(lockFile, JSON.stringify(lockData, null, 2));
+
+      // Call with no options — uses defaults (3 attempts, 200ms)
+      const result = readExistingLockDataWithRetry(lockFile);
+      assertTrue(result !== null, 'default params work for readable file');
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  }
+
+  report();
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/src/resources/extensions/gsd/tests/skill-activation.test.ts

@@ -75,7 +75,7 @@ test("buildSkillActivationBlock activates skills via prefer_skills when context
       prefer_skills: ["react"],
     });
 
-    assert.match(result, /Call Skill\('react'\)/);
+    assert.match(result, /Call Skill\(\{ skill: 'react' \}\)/);
     assert.doesNotMatch(result, /swiftui/);
   } finally {
     cleanup(base);
@@ -92,7 +92,7 @@ test("buildSkillActivationBlock includes always_use_skills from preferences usin
       always_use_skills: ["swift-testing"],
     });
 
-    assert.equal(result, "<skill_activation>Call Skill('swift-testing').</skill_activation>");
+    assert.equal(result, "<skill_activation>Call Skill({ skill: 'swift-testing' }).</skill_activation>");
   } finally {
     cleanup(base);
   }
@@ -120,8 +120,8 @@ test("buildSkillActivationBlock includes skill_rules matches and task-plan skill
       skill_rules: [{ when: "prisma database schema", use: ["prisma"] }],
     });
 
-    assert.match(result, /Call Skill\('accessibility'\)/);
-    assert.match(result, /Call Skill\('prisma'\)/);
+    assert.match(result, /Call Skill\(\{ skill: 'accessibility' \}\)/);
+    assert.match(result, /Call Skill\(\{ skill: 'prisma' \}\)/);
   } finally {
     cleanup(base);
   }
@@ -191,3 +191,43 @@ test("buildSkillActivationBlock does not activate skills from extraContext or ta
     cleanup(base);
   }
 });
+
+test("buildSkillActivationBlock rejects skill names with special characters", () => {
+  const base = makeTempBase();
+  try {
+    // Skill names with quotes, braces, or other non-alphanumeric characters are
+    // rejected by the SAFE_SKILL_NAME guard to prevent prompt injection.
+    writeSkill(base, "my-skill's", "Skill with apostrophe in name.");
+    loadOnlyTestSkills(base);
+
+    const result = buildBlock(base, {}, {
+      always_use_skills: ["my-skill's"],
+    });
+
+    // Unsafe skill name is filtered out — empty result
+    assert.equal(result, "");
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("buildSkillActivationBlock allows valid skill names and rejects invalid ones", () => {
+  const base = makeTempBase();
+  try {
+    writeSkill(base, "react", "React skill.");
+    writeSkill(base, "bad'name", "Injection attempt.");
+    writeSkill(base, "good-skill-2", "Another valid skill.");
+    loadOnlyTestSkills(base);
+
+    const result = buildBlock(base, {}, {
+      always_use_skills: ["react", "bad'name", "good-skill-2"],
+    });
+
+    assert.match(result, /skill_activation/);
+    assert.match(result, /Call Skill\(\{ skill: 'react' \}\)/);
+    assert.match(result, /Call Skill\(\{ skill: 'good-skill-2' \}\)/);
+    assert.doesNotMatch(result, /bad'name/);
+  } finally {
+    cleanup(base);
+  }
+});

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

@@ -44,7 +44,7 @@ console.log('\n── Tool naming: registration count ──');
 const pi = makeMockPi();
 registerDbTools(pi);
 
-assert.deepStrictEqual(pi.tools.length, 26, 'Should register exactly 26 tools (13 canonical + 13 aliases)');
+assert.deepStrictEqual(pi.tools.length, 27, 'Should register exactly 27 tools (13 canonical + 13 aliases + 1 gate tool)');
 
 // ─── Both names exist for each pair ──────────────────────────────────────────
 

package/src/resources/extensions/gsd/tests/validate-milestone.test.ts

@@ -6,7 +6,8 @@ import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
 
 import { deriveState, isValidationTerminal } from "../state.ts";
-import { resolveExpectedArtifactPath, verifyExpectedArtifact, diagnoseExpectedArtifact, buildLoopRemediationSteps } from "../auto-recovery.ts";
+import { resolveExpectedArtifactPath, diagnoseExpectedArtifact } from "../auto-artifact-paths.ts";
+import { verifyExpectedArtifact, buildLoopRemediationSteps } from "../auto-recovery.ts";
 import { resolveDispatch, type DispatchContext } from "../auto-dispatch.ts";
 import type { GSDState } from "../types.ts";
 import { clearPathCache } from "../paths.ts";

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

@@ -226,8 +226,6 @@ describe("verification-gate: execution", () => {
 
   test("all commands pass → gate passes", () => {
     const result = runVerificationGate({
-      basePath: tmp,
-      unitId: "T01",
       cwd: tmp,
       preferenceCommands: ["echo hello", "echo world"],
     });
@@ -243,8 +241,6 @@ describe("verification-gate: execution", () => {
 
   test("one command fails → gate fails with exit code + stderr", () => {
     const result = runVerificationGate({
-      basePath: tmp,
-      unitId: "T01",
       cwd: tmp,
       preferenceCommands: ["echo ok", "sh -c 'echo err >&2; exit 1'"],
     });
@@ -257,8 +253,6 @@ describe("verification-gate: execution", () => {
 
   test("no commands discovered → gate passes with 0 checks", () => {
     const result = runVerificationGate({
-      basePath: tmp,
-      unitId: "T01",
       cwd: tmp,
     });
     assert.equal(result.passed, true);
@@ -268,8 +262,6 @@ describe("verification-gate: execution", () => {
 
   test("command not found → exit code 127", () => {
     const result = runVerificationGate({
-      basePath: tmp,
-      unitId: "T01",
       cwd: tmp,
       preferenceCommands: ["__nonexistent_command_xyz_42__"],
     });
@@ -289,8 +281,6 @@ describe("verification-gate: execution", () => {
     const script = [
       `import { runVerificationGate } from ${JSON.stringify(pathToFileURL(gatePath).href)};`,
       `runVerificationGate({`,
-      `  basePath: ${JSON.stringify(tmp)},`,
-      `  unitId: "T-DEP",`,
       `  cwd: ${JSON.stringify(tmp)},`,
       `  preferenceCommands: ["echo dep0190-check"],`,
       `});`,
@@ -317,8 +307,6 @@ describe("verification-gate: execution", () => {
 
   test("each check has durationMs", () => {
     const result = runVerificationGate({
-      basePath: tmp,
-      unitId: "T01",
       cwd: tmp,
       preferenceCommands: ["echo fast"],
     });
@@ -330,8 +318,6 @@ describe("verification-gate: execution", () => {
   test("one command fails — remaining commands still run (non-short-circuit)", () => {
     // First fails, second and third should still execute
     const result = runVerificationGate({
-      basePath: tmp,
-      unitId: "T02",
       cwd: tmp,
       preferenceCommands: [
         "sh -c 'exit 1'",
@@ -351,8 +337,6 @@ describe("verification-gate: execution", () => {
   test("gate execution uses cwd for spawnSync", () => {
     // pwd should report the temp dir
     const result = runVerificationGate({
-      basePath: tmp,
-      unitId: "T02",
       cwd: tmp,
       preferenceCommands: ["pwd"],
     });

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

@@ -846,3 +846,70 @@ test("GitService is rebuilt with originalBasePath after exitMilestone", () => {
 
   assert.equal(gitServiceBasePath, "/project"); // project root, not worktree
 });
+
+// ─── Isolation Degradation Tests (#2483) ──────────────────────────────────
+
+test("enterMilestone sets isolationDegraded when worktree creation throws (#2483)", () => {
+  const s = makeSession();
+  const deps = makeDeps({
+    getAutoWorktreePath: () => null,
+    createAutoWorktree: () => {
+      throw new Error("empty repo");
+    },
+  });
+  const ctx = makeNotifyCtx();
+  const resolver = new WorktreeResolver(s, deps);
+
+  resolver.enterMilestone("M001", ctx);
+
+  assert.equal(s.isolationDegraded, true);
+  assert.equal(s.basePath, "/project"); // unchanged — error recovery
+});
+
+test("enterMilestone is no-op when isolationDegraded is true (#2483)", () => {
+  const s = makeSession();
+  s.isolationDegraded = true;
+  const deps = makeDeps();
+  const ctx = makeNotifyCtx();
+  const resolver = new WorktreeResolver(s, deps);
+
+  resolver.enterMilestone("M001", ctx);
+
+  assert.equal(s.basePath, "/project"); // unchanged
+  assert.equal(findCalls(deps.calls, "createAutoWorktree").length, 0);
+  assert.equal(findCalls(deps.calls, "enterAutoWorktree").length, 0);
+  assert.equal(findCalls(deps.calls, "shouldUseWorktreeIsolation").length, 0);
+});
+
+test("mergeAndExit is no-op when isolationDegraded is true (#2483)", () => {
+  const s = makeSession({
+    basePath: "/project",
+    originalBasePath: "/project",
+  });
+  s.isolationDegraded = true;
+  const deps = makeDeps({
+    getIsolationMode: () => "worktree",
+  });
+  const ctx = makeNotifyCtx();
+  const resolver = new WorktreeResolver(s, deps);
+
+  resolver.mergeAndExit("M001", ctx);
+
+  assert.equal(findCalls(deps.calls, "mergeMilestoneToMain").length, 0);
+  assert.equal(findCalls(deps.calls, "teardownAutoWorktree").length, 0);
+  assert.equal(findCalls(deps.calls, "getIsolationMode").length, 0);
+  assert.ok(
+    ctx.messages.some(
+      (m) => m.level === "info" && m.msg.includes("isolation was degraded"),
+    ),
+  );
+});
+
+test("isolationDegraded is reset by session.reset() (#2483)", () => {
+  const s = new AutoSession();
+  s.isolationDegraded = true;
+
+  s.reset();
+
+  assert.equal(s.isolationDegraded, false);
+});

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

@@ -27,7 +27,7 @@ import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, readFileSync
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 
-import { syncProjectRootToWorktree } from '../auto-worktree-sync.ts';
+import { syncProjectRootToWorktree } from '../auto-worktree.ts';
 import { syncGsdStateToWorktree, syncWorktreeStateBack } from '../auto-worktree.ts';
 import { describe, test } from 'node:test';
 import assert from 'node:assert/strict';

package/src/resources/extensions/gsd/tests/worktree-sync-overwrite-loop.test.ts

@@ -0,0 +1,204 @@
+/**
+ * worktree-sync-overwrite-loop.test.ts — Regression tests for #1886.
+ *
+ * Reproduces the infinite validate-milestone loop caused by two bugs
+ * in syncProjectRootToWorktree:
+ *
+ * 1. safeCopyRecursive overwrites worktree-authoritative files (e.g.
+ *    VALIDATION.md written by validate-milestone gets clobbered by the
+ *    stale project root copy that lacks the file).
+ *
+ * 2. completed-units.json is not forward-synced from project root to
+ *    worktree, so the worktree never learns about already-completed units.
+ *
+ * Covers:
+ *   - syncProjectRootToWorktree does NOT overwrite existing worktree files
+ *   - syncProjectRootToWorktree copies files missing from the worktree
+ *   - completed-units.json is forward-synced from project root to worktree
+ *   - completed-units.json sync uses force:true (project root is authoritative)
+ */
+
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  rmSync,
+  existsSync,
+  readFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { syncProjectRootToWorktree } from "../auto-worktree.ts";
+import { createTestContext } from "./test-helpers.ts";
+
+const { assertTrue, assertEq, report } = createTestContext();
+
+function createBase(name: string): string {
+  const base = mkdtempSync(join(tmpdir(), `gsd-wt-1886-${name}-`));
+  mkdirSync(join(base, ".gsd", "milestones"), { recursive: true });
+  return base;
+}
+
+function cleanup(base: string): void {
+  rmSync(base, { recursive: true, force: true });
+}
+
+async function main(): Promise<void> {
+  // ─── 1. Worktree VALIDATION.md must NOT be overwritten by project root ──
+  console.log(
+    "\n=== 1. #1886: worktree VALIDATION.md preserved (not overwritten) ===",
+  );
+  {
+    const mainBase = createBase("main");
+    const wtBase = createBase("wt");
+
+    try {
+      // Project root has an older CONTEXT but no VALIDATION
+      const prM004 = join(mainBase, ".gsd", "milestones", "M004");
+      mkdirSync(prM004, { recursive: true });
+      writeFileSync(join(prM004, "M004-CONTEXT.md"), "# old context");
+
+      // Worktree has CONTEXT + VALIDATION (written by validate-milestone)
+      const wtM004 = join(wtBase, ".gsd", "milestones", "M004");
+      mkdirSync(wtM004, { recursive: true });
+      writeFileSync(join(wtM004, "M004-CONTEXT.md"), "# worktree context");
+      writeFileSync(
+        join(wtM004, "M004-VALIDATION.md"),
+        "verdict: pass\nremediation_round: 1",
+      );
+
+      syncProjectRootToWorktree(mainBase, wtBase, "M004");
+
+      // VALIDATION.md must still exist in worktree
+      assertTrue(
+        existsSync(join(wtM004, "M004-VALIDATION.md")),
+        "#1886: VALIDATION.md still exists after sync",
+      );
+      assertEq(
+        readFileSync(join(wtM004, "M004-VALIDATION.md"), "utf-8"),
+        "verdict: pass\nremediation_round: 1",
+        "#1886: VALIDATION.md content preserved",
+      );
+
+      // CONTEXT.md should NOT be overwritten — worktree version is authoritative
+      assertEq(
+        readFileSync(join(wtM004, "M004-CONTEXT.md"), "utf-8"),
+        "# worktree context",
+        "#1886: existing worktree CONTEXT.md not overwritten",
+      );
+    } finally {
+      cleanup(mainBase);
+      cleanup(wtBase);
+    }
+  }
+
+  // ─── 2. Missing files ARE still copied from project root ────────────────
+  console.log("\n=== 2. #1886: missing worktree files still copied ===");
+  {
+    const mainBase = createBase("main");
+    const wtBase = createBase("wt");
+
+    try {
+      const prM004 = join(mainBase, ".gsd", "milestones", "M004");
+      mkdirSync(prM004, { recursive: true });
+      writeFileSync(join(prM004, "M004-CONTEXT.md"), "# from project root");
+      writeFileSync(join(prM004, "M004-ROADMAP.md"), "# roadmap");
+
+      // Worktree has no M004 directory at all
+      syncProjectRootToWorktree(mainBase, wtBase, "M004");
+
+      assertTrue(
+        existsSync(join(wtBase, ".gsd", "milestones", "M004", "M004-CONTEXT.md")),
+        "#1886: missing CONTEXT.md copied from project root",
+      );
+      assertTrue(
+        existsSync(join(wtBase, ".gsd", "milestones", "M004", "M004-ROADMAP.md")),
+        "#1886: missing ROADMAP.md copied from project root",
+      );
+    } finally {
+      cleanup(mainBase);
+      cleanup(wtBase);
+    }
+  }
+
+  // ─── 3. completed-units.json forward-synced from project root ───────────
+  console.log(
+    "\n=== 3. #1886: completed-units.json forward-synced to worktree ===",
+  );
+  {
+    const mainBase = createBase("main");
+    const wtBase = createBase("wt");
+
+    try {
+      // Project root has completed units (authoritative after crash recovery)
+      writeFileSync(
+        join(mainBase, ".gsd", "completed-units.json"),
+        JSON.stringify(["validate-milestone/M004"]),
+      );
+
+      // Worktree has empty completed-units
+      writeFileSync(
+        join(wtBase, ".gsd", "completed-units.json"),
+        JSON.stringify([]),
+      );
+
+      syncProjectRootToWorktree(mainBase, wtBase, "M004");
+
+      const wtCompleted = JSON.parse(
+        readFileSync(join(wtBase, ".gsd", "completed-units.json"), "utf-8"),
+      );
+      assertEq(
+        wtCompleted,
+        ["validate-milestone/M004"],
+        "#1886: completed-units.json synced from project root (force:true)",
+      );
+    } finally {
+      cleanup(mainBase);
+      cleanup(wtBase);
+    }
+  }
+
+  // ─── 4. completed-units.json: no-op when project root has no file ───────
+  console.log(
+    "\n=== 4. #1886: completed-units.json no-op when missing in project root ===",
+  );
+  {
+    const mainBase = createBase("main");
+    const wtBase = createBase("wt");
+
+    try {
+      // Project root milestone dir must exist for sync to run
+      const prM004 = join(mainBase, ".gsd", "milestones", "M004");
+      mkdirSync(prM004, { recursive: true });
+
+      // No completed-units.json in project root
+      // Worktree has its own
+      writeFileSync(
+        join(wtBase, ".gsd", "completed-units.json"),
+        JSON.stringify(["some-unit/M001"]),
+      );
+
+      syncProjectRootToWorktree(mainBase, wtBase, "M004");
+
+      const wtCompleted = JSON.parse(
+        readFileSync(join(wtBase, ".gsd", "completed-units.json"), "utf-8"),
+      );
+      assertEq(
+        wtCompleted,
+        ["some-unit/M001"],
+        "#1886: worktree completed-units.json untouched when project root has none",
+      );
+    } finally {
+      cleanup(mainBase);
+      cleanup(wtBase);
+    }
+  }
+
+  report();
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});