@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

package/src/resources/extensions/gsd/tests/orphan-stash-audit.test.ts

@@ -1,6 +1,7 @@
 // gsd-pi + src/resources/extensions/gsd/tests/orphan-stash-audit.test.ts
-// Regression: orphaned gsd-preflight-stash entries from completed milestones
-// must be auto-applied at startup so the user's pre-merge work returns.
+// Regression coverage for orphaned gsd-preflight-stash entries from completed
+// milestones: safe startup recovery for untracked work, manual warnings for
+// tracked or dirty-tree cases that would silently mutate user state.
 
 import { describe, test, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
@@ -37,6 +38,13 @@ function pushPreflightStash(repo: string, milestoneId: string, fileName: string,
   return marker;
 }
 
+function pushTrackedPreflightStash(repo: string, milestoneId: string, fileName: string, content: string): string {
+  writeFileSync(join(repo, fileName), content);
+  const marker = `gsd-preflight-stash:${milestoneId}:42:1700000000000:tracked`;
+  git(repo, "stash", "push", "-m", `gsd-preflight-stash [${marker}]`);
+  return marker;
+}
+
 describe("auditOrphanedPreflightStashes", () => {
   let repo: string;
 
@@ -83,6 +91,23 @@ describe("auditOrphanedPreflightStashes", () => {
     assert.match(list, /gsd-preflight-stash:M002:/);
   });
 
+  test("does not auto-apply a tracked orphan preflight stash onto a clean working tree", () => {
+    pushTrackedPreflightStash(repo, "M006", "seed.txt", "seed\ntracked pre-merge work\n");
+    assert.equal(readFileSync(join(repo, "seed.txt"), "utf-8"), "seed\n");
+
+    const result = auditOrphanedPreflightStashes(repo, () => true);
+
+    assert.equal(result.applied.length, 0);
+    assert.equal(result.warnings.length, 1);
+    assert.match(result.warnings[0], /not auto-applied/);
+    assert.match(result.warnings[0], /stash modifies tracked files/);
+    assert.match(result.warnings[0], /git stash apply stash@\{\d+\}/);
+    assert.equal(readFileSync(join(repo, "seed.txt"), "utf-8"), "seed\n");
+
+    const list = git(repo, "stash", "list");
+    assert.match(list, /gsd-preflight-stash:M006:/);
+  });
+
   test("ignores stashes whose milestone is not complete", () => {
     pushPreflightStash(repo, "M003", "wip.txt", "still-working\n");
 
@@ -115,23 +140,25 @@ describe("auditOrphanedPreflightStashes", () => {
     assert.match(result.warnings[0], /db unavailable/);
   });
 
-  test("collects a warning when stash apply fails (conflicting working tree)", () => {
-    // Push a stash containing a change to seed.txt; then dirty seed.txt with
-    // a conflicting modification before the audit runs so apply fails.
+  test("collects a warning instead of applying when the working tree is not clean", () => {
+    // Push a stash containing a change to seed.txt; then dirty seed.txt before
+    // the audit runs. Startup recovery must leave the tree untouched and ask
+    // the user to apply the retained backup stash manually.
     writeFileSync(join(repo, "seed.txt"), "stashed\n");
     const marker = `gsd-preflight-stash:M005:42:1700:zz`;
     git(repo, "stash", "push", "-m", `gsd-preflight-stash [${marker}]`);
 
-    // Dirty the working tree so apply will conflict.
     writeFileSync(join(repo, "seed.txt"), "conflicting modification\n");
 
     const result = auditOrphanedPreflightStashes(repo, () => true);
 
     assert.equal(result.applied.length, 0);
     assert.equal(result.warnings.length, 1);
-    assert.match(result.warnings[0], /Could not apply orphaned preflight stash/);
+    assert.match(result.warnings[0], /not auto-applied/);
+    assert.match(result.warnings[0], /working tree not clean/);
     assert.match(result.warnings[0], /M005/);
     assert.match(result.warnings[0], /git stash apply/);
+    assert.equal(readFileSync(join(repo, "seed.txt"), "utf-8"), "conflicting modification\n");
 
     const list = git(repo, "stash", "list");
     assert.match(list, /gsd-preflight-stash:M005:/);
@@ -169,6 +196,63 @@ describe("auditOrphanedPreflightStashes", () => {
       "second run must NOT warn — files are already restored from first run",
     );
   });
+
+  test("warns instead of silently skipping when only some stash untracked files were restored", () => {
+    // Cursor Bugbot caught: isAlreadyRestoredUntrackedStatus treated a dirty
+    // tree as fully restored when every *current* untracked path appeared in
+    // the stash, without requiring every *stash* untracked path to be present.
+    // A partial restore (only some files recovered) was misread as the
+    // idempotent steady state, so the audit no-oped and the remaining pre-merge
+    // files stayed missing with no warning.
+    writeFileSync(join(repo, "first.txt"), "first\n");
+    writeFileSync(join(repo, "second.txt"), "second\n");
+    const marker = `gsd-preflight-stash:M007:42:1700000000000:partial`;
+    git(repo, "stash", "push", "--include-untracked", "-m", `gsd-preflight-stash [${marker}]`);
+
+    // Both files are stashed away.
+    assert.equal(existsSync(join(repo, "first.txt")), false);
+    assert.equal(existsSync(join(repo, "second.txt")), false);
+
+    // Simulate a partial restore: only first.txt came back; second.txt is still
+    // missing from the working tree.
+    writeFileSync(join(repo, "first.txt"), "first\n");
+
+    const result = auditOrphanedPreflightStashes(repo, () => true);
+
+    // Must NOT be treated as already-restored: second.txt is still missing, so
+    // the audit must surface a manual-recovery warning rather than no-op.
+    assert.equal(result.applied.length, 0);
+    assert.equal(result.warnings.length, 1, "partial restore must warn, not silently no-op");
+    assert.match(result.warnings[0], /not auto-applied/);
+    assert.match(result.warnings[0], /working tree not clean/);
+    assert.match(result.warnings[0], /M007/);
+    assert.match(result.warnings[0], /git stash apply/);
+
+    // The stash entry must remain so the user can recover second.txt manually.
+    const list = git(repo, "stash", "list");
+    assert.match(list, /gsd-preflight-stash:M007:/);
+  });
+
+  test("fully restored multi-file untracked stash stays a silent no-op", () => {
+    // Guards the other direction of the set-equality fix: when EVERY stash
+    // untracked file is present in the working tree, the genuine idempotent
+    // steady state must still be recognized and skipped without warning, even
+    // when the stash captured more than one file.
+    writeFileSync(join(repo, "alpha.txt"), "alpha\n");
+    writeFileSync(join(repo, "beta.txt"), "beta\n");
+    const marker = `gsd-preflight-stash:M008:42:1700000000000:multi`;
+    git(repo, "stash", "push", "--include-untracked", "-m", `gsd-preflight-stash [${marker}]`);
+
+    const first = auditOrphanedPreflightStashes(repo, () => true);
+    assert.equal(first.applied.length, 1, "first run applies both files");
+    assert.equal(first.warnings.length, 0);
+    assert.equal(existsSync(join(repo, "alpha.txt")), true);
+    assert.equal(existsSync(join(repo, "beta.txt")), true);
+
+    const second = auditOrphanedPreflightStashes(repo, () => true);
+    assert.equal(second.applied.length, 0, "second run skips");
+    assert.equal(second.warnings.length, 0, "fully restored multi-file stash must not warn");
+  });
 });
 
 test("_isAlreadyRestoredApplyError detects the git stash apply already-exists error", () => {

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

@@ -160,7 +160,10 @@ describe("auditOrphanedMilestoneBranches", () => {
       `warning should mention stranded milestone/M001 and in-progress state; got: ${JSON.stringify(result.warnings)}`,
     );
     assert.equal(result.blockingStrandedWork?.milestoneId, "M001");
-    assert.equal(result.blockingStrandedWork?.recoveryMode, "branch");
+    // #812 — worktree-configured isolation must recover as "worktree" even when
+    // the worktree directory is absent on disk, so recovery re-materializes the
+    // worktree from the branch instead of checking it out in the project root.
+    assert.equal(result.blockingStrandedWork?.recoveryMode, "worktree");
     assert.equal(result.blockingStrandedWork?.commitsAhead, 1);
 
     // Branch must still exist
@@ -168,6 +171,54 @@ describe("auditOrphanedMilestoneBranches", () => {
     assert.ok(branches.includes("milestone/M001"), "in-progress branch must be preserved");
   });
 
+  test("#812 — in-progress orphan under branch isolation recovers as branch", () => {
+    // Same stranded scenario but the project is configured for branch-mode
+    // isolation, where there is never a worktree to re-materialize. Recovery
+    // must stay "branch".
+    run("git checkout -b milestone/M001", dir);
+    writeFileSync(join(dir, "feature.txt"), "in-progress work\n");
+    run("git add feature.txt", dir);
+    run("git commit -m \"in-progress work on M001\"", dir);
+    run("git checkout main", dir);
+
+    insertMilestone({ id: "M001", title: "Test", status: "active" });
+
+    const result = auditOrphanedMilestoneBranches(dir, "branch");
+
+    assert.equal(result.blockingStrandedWork?.milestoneId, "M001");
+    assert.equal(result.blockingStrandedWork?.recoveryMode, "branch");
+  });
+
+  test("#812-followup — worktree-mode project degrades to branch recovery when branch is already checked out at root", () => {
+    // Simulates the leftover state from the pre-fix #812 recovery path: the
+    // old code checked out milestone/<id> in the project root instead of
+    // creating a worktree. On the next bootstrap:
+    //   - isolationMode === "worktree"
+    //   - HEAD at project root === "milestone/M001"
+    //   - no linked worktree directory on disk
+    //
+    // Requesting worktree recovery in this state calls `git worktree add` for
+    // a branch git already considers "in use by another worktree" (the main
+    // worktree counts), causing bootstrap to abort with GSD_LOCK_HELD.
+    // The fix detects the root checkout and degrades to "branch" so the
+    // session resumes on the already-checked-out branch without failing.
+    run("git checkout -b milestone/M001", dir);
+    writeFileSync(join(dir, "feature.txt"), "in-progress work\n");
+    run("git add feature.txt", dir);
+    run("git commit -m \"in-progress work on M001\"", dir);
+    // NOTE: stay on milestone/M001 — do NOT check out main.
+    // This simulates the project root being on the milestone branch.
+
+    insertMilestone({ id: "M001", title: "Test", status: "active" });
+
+    const result = auditOrphanedMilestoneBranches(dir, "worktree");
+
+    assert.equal(result.blockingStrandedWork?.milestoneId, "M001");
+    // Must degrade to "branch" — worktree creation would fail because the
+    // branch is already checked out at the project root.
+    assert.equal(result.blockingStrandedWork?.recoveryMode, "branch");
+  });
+
   test("#4762 — also surfaces worktree directory for in-progress orphan when present", () => {
     // In-progress + unmerged + physical worktree directory — the full primary scenario.
     run("git checkout -b milestone/M001", dir);

package/src/resources/extensions/gsd/tests/parallel-monitor-overlay.test.ts

@@ -3,9 +3,14 @@
 
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
+import { createRequire } from "node:module";
+import { appendFileSync, mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
 
 import { visibleWidth } from "@gsd/pi-tui";
 import { assertFullOuterBorder } from "./tui-border-assertions.ts";
+import { closeDatabase, insertMilestone, insertSlice, insertTask, openDatabase } from "../gsd-db.ts";
 
 function assertLinesFit(lines: string[], width: number): void {
   for (const line of lines) {
@@ -17,6 +22,92 @@ function assertLinesFit(lines: string[], width: number): void {
 }
 
 describe("parallel-monitor-overlay", () => {
+  it("reads worker DB progress and appended NDJSON cost without sqlite CLI or full stdout reads", async () => {
+    const base = mkdtempSync(join(tmpdir(), "gsd-parallel-overlay-"));
+    const stdoutPath = join(base, ".gsd", "parallel", "M001.stdout.log");
+    const cjsRequire = createRequire(import.meta.url);
+    const fsBuiltin = cjsRequire("node:fs") as typeof import("node:fs");
+    const childProcessBuiltin = cjsRequire("node:child_process") as typeof import("node:child_process");
+    const originalReadFileSync = fsBuiltin.readFileSync;
+    const originalSpawnSync = childProcessBuiltin.spawnSync;
+
+    try {
+      mkdirSync(join(base, ".gsd", "parallel"), { recursive: true });
+      assert.equal(openDatabase(join(base, ".gsd", "gsd.db")), true);
+      insertMilestone({ id: "M001", title: "Monitor Fixture" });
+      insertSlice({ milestoneId: "M001", id: "S01", title: "Build overlay", status: "pending", sequence: 1 });
+      insertTask({
+        milestoneId: "M001",
+        sliceId: "S01",
+        id: "T01",
+        status: "complete",
+        oneLiner: "render progress",
+        sequence: 1,
+      });
+      insertTask({ milestoneId: "M001", sliceId: "S01", id: "T02", status: "pending", sequence: 2 });
+      closeDatabase();
+
+      writeFileSync(
+        join(base, ".gsd", "parallel", "M001.status.json"),
+        JSON.stringify({
+          milestoneId: "M001",
+          pid: process.pid,
+          state: "running",
+          cost: 0,
+          lastHeartbeat: Date.now(),
+          startedAt: Date.now() - 30_000,
+          worktreePath: join(base, ".gsd-worktrees", "M001"),
+        }),
+        "utf-8",
+      );
+      writeFileSync(
+        stdoutPath,
+        JSON.stringify({ type: "message_end", message: { usage: { cost: { total: 1.25 } } } }) + "\n",
+        "utf-8",
+      );
+
+      fsBuiltin.readFileSync = ((filePath: Parameters<typeof originalReadFileSync>[0], ...args: unknown[]) => {
+        if (String(filePath) === stdoutPath) throw new Error("full stdout log reads are disabled in this test");
+        return (originalReadFileSync as (...readArgs: unknown[]) => unknown)(filePath, ...args);
+      }) as typeof fsBuiltin.readFileSync;
+      childProcessBuiltin.spawnSync = ((command: Parameters<typeof originalSpawnSync>[0], ...args: unknown[]) => {
+        if (command === "sqlite3") throw new Error("sqlite3 CLI is disabled in this test");
+        return (originalSpawnSync as (...spawnArgs: unknown[]) => unknown)(command, ...args);
+      }) as typeof childProcessBuiltin.spawnSync;
+
+      const mod = await import("../parallel-monitor-overlay.js");
+      const mockTui = { requestRender: () => {} };
+      const mockTheme = {
+        fg: (_color: string, text: string) => text,
+        bold: (text: string) => text,
+      };
+      const overlay = new mod.ParallelMonitorOverlay(mockTui, mockTheme as any, () => {}, base);
+
+      try {
+        const joined = overlay.render(100).join("\n");
+        assert.match(joined, /S01:1\/2/, "slice progress should come from the in-process DB reader");
+        assert.match(joined, /S01\/T01: render progress/, "recent completions should come from the in-process DB reader");
+        assert.match(joined, /\$1\.25/, "cost should come from bounded NDJSON reads");
+
+        appendFileSync(
+          stdoutPath,
+          JSON.stringify({ type: "message_end", message: { usage: { cost: { total: 2.00 } } } }) + "\n",
+          "utf-8",
+        );
+        (overlay as any).refresh();
+        const refreshed = overlay.render(100).join("\n");
+        assert.match(refreshed, /\$3\.25/, "cost should include only newly appended NDJSON events");
+      } finally {
+        overlay.dispose();
+      }
+    } finally {
+      fsBuiltin.readFileSync = originalReadFileSync;
+      childProcessBuiltin.spawnSync = originalSpawnSync;
+      try { closeDatabase(); } catch { /* already closed */ }
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+
   it("progressBar generates correct width", async () => {
     // Dynamic import to test the module loads cleanly
     const mod = await import("../parallel-monitor-overlay.js");

package/src/resources/extensions/gsd/tests/parallel-research-dispatch.test.ts

@@ -145,6 +145,32 @@ describe("parallel-research-slices dispatch rule", () => {
     }
   });
 
+  test("dispatches parallel research for S01 even when milestone research exists", async () => {
+    writeRoadmap(base, "M001", [
+      { id: "S01", title: "Alpha" },
+      { id: "S02", title: "Beta" },
+    ]);
+    writeFileSync(
+      join(base, ".gsd", "milestones", "M001", "M001-RESEARCH.md"),
+      "# Milestone Research\n",
+      "utf-8",
+    );
+
+    const action = await resolveDispatch({
+      basePath: base,
+      mid: "M001",
+      midTitle: "Parallel Research Milestone",
+      state: baseState(),
+      prefs: undefined,
+    });
+
+    assert.equal(action.action, "dispatch");
+    if (action.action === "dispatch") {
+      assert.equal(action.unitType, "research-slice");
+      assert.equal(action.unitId, "M001/parallel-research");
+    }
+  });
+
   test("does not dispatch parallel research with only one ready slice", async () => {
     writeRoadmap(base, "M001", [{ id: "S01", title: "Alpha" }]);
 

package/src/resources/extensions/gsd/tests/parsers-legacy-importers.test.ts

@@ -54,9 +54,12 @@ const ALLOWED_IMPORTERS = new Set([
   // explicit degraded-mode fallback when DB has no task rows (warns on use)
   "gsd/reactive-graph.ts",
   // recovery path: explicit pre-migration/DB-unavailable fallback branches
-  "gsd/auto-recovery.ts",
+  // (verifyExpectedArtifact extracted here from auto-recovery.ts)
+  "gsd/artifact-verification.ts",
   // diagnostics-only surfaces: report on projections, make no dispatch decisions
   "gsd/doctor.ts",
+  // diagnostics-only: compares PLAN.md task checkboxes against DB status
+  "gsd/doctor-engine-checks.ts",
   // display/telemetry-only surfaces
   "gsd/workspace-index.ts",
   "gsd/visualizer-data.ts",

package/src/resources/extensions/gsd/tests/pending-autostart-scope.test.ts

@@ -55,8 +55,8 @@ describe("pendingAutoStart scope pinning (C1)", () => {
     assert.ok(entry.scope, "entry.scope should be set");
     assert.equal(entry.scope.milestoneId, "M001");
 
-    const expectedContext = join(base, ".gsd", "milestones", "M001", "M001-CONTEXT.md");
-    const expectedRoadmap = join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md");
+    const expectedContext = join(base, ".gsd", "phases", "01-m001", "01-CONTEXT.md");
+    const expectedRoadmap = join(base, ".gsd", "phases", "01-m001", "01-ROADMAP.md");
     const expectedState = join(base, ".gsd", "STATE.md");
 
     assert.equal(entry.scope.contextFile(), expectedContext);

package/src/resources/extensions/gsd/tests/phases-merge-error-stops-auto.test.ts

@@ -82,13 +82,57 @@ const ic = {
       return { ok: true, needsManualRecovery: false };
     },
     lifecycle: {
-      exitMilestone() {
+      // Mirror WorktreeLifecycle.exitMilestone's guarded-merge branch
+      // (preflight -> inner merge -> postflight). Since #1169 the closeout
+      // routes the guard through the lifecycle verb, so a non-conflict inner
+      // failure ("teardown-failed") is mapped to "merge-failed" here rather
+      // than by the caller.
+      exitMilestone(
+        milestoneId: string,
+        exitOpts: {
+          merge: boolean;
+          guardedMerge?: {
+            projectRoot: string;
+            preflightCleanRoot: (
+              basePath: string,
+              milestoneId: string,
+              notify: (message: string, level: "info" | "warning" | "error") => void,
+            ) => { blocked?: boolean; blockedReason?: string; stashPushed: boolean; stashMarker?: string };
+            postflightPopStash: (
+              basePath: string,
+              milestoneId: string,
+              stashMarker: string | undefined,
+              notify: (message: string, level: "info" | "warning" | "error") => void,
+            ) => { needsManualRecovery?: boolean };
+          };
+        },
+        exitCtx?: { notify: (message: string, level: "info" | "warning" | "error") => void },
+      ) {
+        const notify = exitCtx?.notify ?? (() => {});
+        const guarded = exitOpts.guardedMerge;
+        if (exitOpts.merge && guarded) {
+          const preflight = guarded.preflightCleanRoot(guarded.projectRoot, milestoneId, notify);
+          if (preflight.blocked) {
+            return {
+              ok: false,
+              reason: preflight.blockedReason?.startsWith("unmerged-conflicts")
+                ? "preflight-unmerged-conflicts"
+                : "preflight-dirty-overlap",
+            };
+          }
+          // Inner merge fails with a non-conflict error. The lifecycle still
+          // runs postflight stash restore on the failed-merge path, then maps
+          // the non-conflict failure to "merge-failed" (a MergeConflictError
+          // would instead map to "merge-conflict").
+          calls.push("merge");
+          const cause = new Error("remote rejected push");
+          if (preflight.stashPushed) {
+            guarded.postflightPopStash(guarded.projectRoot, milestoneId, preflight.stashMarker, notify);
+          }
+          return { ok: false, reason: "merge-failed", cause };
+        }
         calls.push("merge");
-        return {
-          ok: false,
-          reason: "teardown-failed",
-          cause: new Error("remote rejected push"),
-        };
+        return { ok: false, reason: "teardown-failed", cause: new Error("remote rejected push") };
       },
     },
     async stopAuto(_ctx: unknown, _pi: unknown, reason?: string) {

package/src/resources/extensions/gsd/tests/pipeline-variant-dispatch.test.ts

@@ -22,7 +22,7 @@ import { invalidateAllCaches } from "../cache.ts";
 import type { GSDState } from "../types.ts";
 
 const PARALLEL_RESEARCH_RULE = "planning (multiple slices need research) → parallel-research-slices";
-const SINGLE_RESEARCH_RULE = "planning (no research, not S01) → research-slice";
+const SINGLE_RESEARCH_RULE = "planning (no research) → research-slice";
 const VALIDATE_RULE = "validating-milestone → validate-milestone";
 
 // ─── Fixture helpers ──────────────────────────────────────────────────────

package/src/resources/extensions/gsd/tests/plan-milestone-boundary-map-preservation.test.ts

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync, readFileSync, existsSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 
@@ -86,7 +86,12 @@ function planParams() {
 
 test('#4402 plan-milestone preserves ## Boundary Map after post-mutation projections', async (t) => {
   const base = mkdtempSync(join(tmpdir(), 'gsd-4402-'));
-  mkdirSync(join(base, '.gsd', 'milestones', 'M001'), { recursive: true });
+  const mDir = join(base, '.gsd', 'milestones', 'M001');
+  mkdirSync(mDir, { recursive: true });
+  // A content-bearing legacy milestone dir requires at least one non-META file
+  // (dirIsContentBearingLegacyMilestone) so the layout sniffer treats it as a
+  // real legacy milestone rather than a metadata-only placeholder.
+  writeFileSync(join(mDir, 'M001-CONTEXT.md'), '# M001\n');
   openDatabase(join(base, '.gsd', 'gsd.db'));
 
   t.after(() => {

package/src/resources/extensions/gsd/tests/plan-milestone-sketch-render.test.ts

@@ -7,7 +7,7 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, rmSync, readFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
@@ -16,7 +16,12 @@ import { handlePlanMilestone, type PlanMilestoneParams } from "../tools/plan-mil
 
 function makeTmpBase(): string {
   const base = mkdtempSync(join(tmpdir(), "gsd-plan-sketch-render-"));
-  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+  const mDir = join(base, ".gsd", "milestones", "M001");
+  mkdirSync(mDir, { recursive: true });
+  // A content-bearing legacy milestone dir requires at least one non-META file
+  // (dirIsContentBearingLegacyMilestone) so the layout sniffer treats it as a
+  // real legacy milestone rather than a metadata-only placeholder.
+  writeFileSync(join(mDir, "M001-CONTEXT.md"), "# M001\n");
   openDatabase(join(base, ".gsd", "gsd.db"));
   return base;
 }

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

@@ -13,7 +13,7 @@ import { parseRoadmap } from '../parsers-legacy.ts';
 
 function makeTmpBase(): string {
   const base = mkdtempSync(join(tmpdir(), 'gsd-plan-milestone-'));
-  mkdirSync(join(base, '.gsd', 'milestones', 'M001'), { recursive: true });
+  mkdirSync(join(base, '.gsd', 'phases', '01-test'), { recursive: true });
   return base;
 }
 
@@ -91,7 +91,7 @@ test('handlePlanMilestone writes milestone and slice planning state and renders
     assert.equal(slices[0]?.goal, 'Wire the handler.');
     assert.equal(slices[1]?.depends[0], 'S01');
 
-    const roadmapPath = join(base, '.gsd', 'milestones', 'M001', 'M001-ROADMAP.md');
+    const roadmapPath = join(base, '.gsd', 'phases', '01-test', '01-ROADMAP.md');
     assert.ok(existsSync(roadmapPath), 'roadmap should be rendered to disk');
     const roadmap = readFileSync(roadmapPath, 'utf-8');
     assert.match(roadmap, /# M001: DB-backed planning/);
@@ -151,14 +151,17 @@ test('handlePlanMilestone surfaces render failures and does not clear parse-visi
   openDatabase(dbPath);
 
   try {
-    const fallbackRoadmapPath = join(base, '.gsd', 'milestones', 'MISSING', 'MISSING-ROADMAP.md');
+    // Block the rendered roadmap path: M999 → phaseNum=999, slug='db-backed-planning'
+    // → renderer targets phases/999-db-backed-planning/999-ROADMAP.md.
+    // Creating that path as a directory causes EISDIR → render fails.
+    const fallbackRoadmapPath = join(base, '.gsd', 'phases', '999-db-backed-planning', '999-ROADMAP.md');
     mkdirSync(fallbackRoadmapPath, { recursive: true });
 
-    const result = await handlePlanMilestone({ ...validParams(), milestoneId: 'MISSING' }, base);
+    const result = await handlePlanMilestone({ ...validParams(), milestoneId: 'M999' }, base);
     assert.ok('error' in result);
     assert.match(result.error, /render failed:/);
 
-    const existingRoadmapPath = join(base, '.gsd', 'milestones', 'M001', 'M001-ROADMAP.md');
+    const existingRoadmapPath = join(base, '.gsd', 'phases', '01-test', '01-ROADMAP.md');
     writeFileSync(existingRoadmapPath, '# M001: Cached roadmap\n\n**Vision:** old value\n\n## Slices\n\n', 'utf-8');
     const cachedAfter = parseRoadmap(readFileSync(existingRoadmapPath, 'utf-8'));
     assert.equal(cachedAfter.vision, 'old value');
@@ -173,7 +176,7 @@ test('handlePlanMilestone clears parse-visible roadmap state after successful re
   openDatabase(dbPath);
 
   try {
-    const roadmapPath = join(base, '.gsd', 'milestones', 'M001', 'M001-ROADMAP.md');
+    const roadmapPath = join(base, '.gsd', 'phases', '01-test', '01-ROADMAP.md');
     writeFileSync(roadmapPath, '# M001: Cached roadmap\n\n**Vision:** old value\n\n## Slices\n\n', 'utf-8');
 
     const cachedBefore = parseRoadmap(readFileSync(roadmapPath, 'utf-8'));

package/src/resources/extensions/gsd/tests/plan-slice-prompt.test.ts

@@ -34,6 +34,7 @@ const BASE_VARS = {
   planTemplatePath: "C:\\Users\\Test\\.gsd\\agent\\extensions\\gsd\\templates\\plan.md",
   taskPlanTemplatePath: "C:\\Users\\Test\\.gsd\\agent\\extensions\\gsd\\templates\\task-plan.md",
   skillActivation: "Load the relevant skills.",
+  repoRegistry: "",
 };
 
 const DEFAULT_SKILL_ACTIVATION = "If a `GSD Skill Preferences` block is present in system context, use it and the `<available_skills>` catalog in your system prompt to decide which skills to load and follow for this unit, without relaxing required verification or artifact rules.";
@@ -61,6 +62,22 @@ test("plan-slice prompt: all variables substituted", () => {
   assert.ok(result.includes("S01"));
 });
 
+test("plan-slice prompt: repoRegistry block surfaces declared repositories when non-empty", () => {
+  const block = "### Declared Repositories\n\n- `frontend` (frontend/)\n- `backend` (backend/)\n\nAssign each task's `targetRepositories`";
+  const result = loadPrompt("plan-slice", { ...BASE_VARS, repoRegistry: block, commitInstruction: "Do not commit." });
+  assert.ok(result.includes("### Declared Repositories"), "declared repositories block should appear when provided");
+  assert.ok(result.includes("`frontend`"), "declared repo ids should be visible to the planner");
+  assert.ok(result.includes("targetRepositories"), "repo-assignment guidance should appear");
+});
+
+test("plan-slice prompt: empty repoRegistry leaves no orphan marker", () => {
+  const result = loadPrompt("plan-slice", { ...BASE_VARS, repoRegistry: "", commitInstruction: "Do not commit." });
+  assert.ok(!result.includes("{{repoRegistry}}"), "the repoRegistry placeholder must be substituted");
+  // The block heading only renders when repoRegistry is non-empty; the rule-9
+  // guidance text mentions "Declared Repositories" but is not a rendered block.
+  assert.ok(!result.includes("### Declared Repositories"), "single-repo prompts must not show a declared-repositories block");
+});
+
 test("plan-slice prompt: DB-backed tool names survive template substitution", () => {
   const result = loadPrompt("plan-slice", { ...BASE_VARS, commitInstruction: "Do not commit." });
   assert.ok(result.includes("gsd_plan_slice"), "gsd_plan_slice should appear in rendered prompt");
@@ -94,6 +111,16 @@ test("plan-slice prompt: absence checks use negated quiet searches", () => {
   assert.ok(result.includes("count commands exit 1 when they find zero matches"));
 });
 
+test("plan-slice prompt: npm package existence rule is stated during generation", () => {
+  const result = loadPrompt("plan-slice", { ...BASE_VARS, commitInstruction: "Do not commit." });
+  assert.ok(result.includes("reference only packages that exist on the public npm registry"));
+  assert.ok(result.includes("remove or correct any package name that is not real"));
+  // The post-unit pre-execution gate parses package names from require/import
+  // patterns too, not just install commands, so the rule must cover that scope.
+  assert.ok(result.includes("require('...')"));
+  assert.ok(result.includes("import ... from '...'"));
+});
+
 test("plan-slice prompt: footer references gsd_plan_slice tool, not direct write", () => {
   const result = loadPrompt("plan-slice", { ...BASE_VARS, commitInstruction: "Do not commit." });
   assert.ok(