@opengsd/gsd-pi 1.2.0-dev.fbdca60b → 1.3.0-dev.65546769

package/src/resources/extensions/gsd/state.ts

@@ -31,6 +31,8 @@ import {
 } from './files.js';
 
 import {
+  buildMilestoneFileName,
+  resolveFile,
   resolveMilestonePath,
   resolveMilestoneFile,
   resolveSlicePath,
@@ -67,8 +69,9 @@ import {
   getRequirementCounts,
   getLatestAssessmentByScope,
   getPendingGateCountForTurn,
+  setMilestoneQueueOrder,
 } from './gsd-db.js';
-import { wasWorkflowDatabaseOpenAttempted } from './db-workspace.js';
+import { openExistingWorkflowDatabase, wasWorkflowDatabaseOpenAttempted } from './db-workspace.js';
 import { formatCompletePhaseNextAction, countUnmappedActiveRequirements } from './requirements-backlog.js';
 import type { MilestoneRow } from './db-milestone-artifact-rows.js';
 import type { SliceRow, TaskRow } from './db-task-slice-rows.js';
@@ -269,6 +272,38 @@ export function invalidateStateCache(): void {
   _stateCache = null;
 }
 
+function syncQueueOrderProjectionToDb(basePath: string): void {
+  const queueOrder = loadQueueOrder(basePath);
+  if (!queueOrder) return;
+
+  const currentIds = getAllMilestones().map((m) => m.id);
+  const desiredIds = sortByQueueOrder(currentIds, queueOrder);
+  if (currentIds.length === desiredIds.length && currentIds.every((id, i) => id === desiredIds[i])) return;
+
+  setMilestoneQueueOrder(desiredIds);
+}
+
+function ensureExistingWorkflowDbOpen(basePath: string): boolean {
+  const opened = isDbAvailable() || openExistingWorkflowDatabase(basePath).ok;
+  if (opened) syncQueueOrderProjectionToDb(basePath);
+  return opened;
+}
+
+function buildDbUnavailableState(): GSDState {
+  return {
+    activeMilestone: null,
+    activeSlice: null,
+    activeTask: null,
+    phase: "pre-planning",
+    recentDecisions: [],
+    blockers: ["DB unavailable — runtime markdown state derivation is disabled"],
+    nextAction: "Open or create the canonical GSD database before deriving workflow state. If this project only has markdown state, run /gsd migrate explicitly.",
+    registry: [],
+    requirements: { active: 0, validated: 0, deferred: 0, outOfScope: 0, blocked: 0, total: 0 },
+    progress: { milestones: { done: 0, total: 0 } },
+  };
+}
+
 /**
  * Returns the ID of the first incomplete milestone, or null if all are complete.
  */
@@ -299,6 +334,7 @@ export async function getActiveMilestoneId(basePath: string): Promise<string | n
 
   // DB-first: query milestones table for the first non-complete, non-parked milestone
   if (isDbAvailable()) {
+    syncQueueOrderProjectionToDb(basePath);
     const allMilestones = getAllMilestones();
     if (allMilestones.length > 0) {
       for (const m of allMilestones) {
@@ -382,6 +418,8 @@ export async function deriveState(
   // DB-backed derivation is authoritative whenever the DB is open. Runtime
   // degrade must not infer state from ROADMAP.md, PLAN.md, SUMMARY.md,
   // REQUIREMENTS.md, or flag files.
+  ensureExistingWorkflowDbOpen(basePath);
+
   if (isDbAvailable()) {
     const stopDbTimer = debugTime("derive-state-db");
     result = await deriveStateFromDb(basePath, opts?.projectRootForReads ?? basePath);
@@ -391,18 +429,7 @@ export async function deriveState(
     if (wasWorkflowDatabaseOpenAttempted()) {
       logWarning("state", "DB unavailable — refusing implicit markdown state derivation");
     }
-    result = {
-      activeMilestone: null,
-      activeSlice: null,
-      activeTask: null,
-      phase: "pre-planning",
-      recentDecisions: [],
-      blockers: ["DB unavailable — runtime markdown state derivation is disabled"],
-      nextAction: "Open or create the canonical GSD database before deriving workflow state. If this project only has markdown state, run /gsd migrate explicitly.",
-      registry: [],
-      requirements: { active: 0, validated: 0, deferred: 0, outOfScope: 0, blocked: 0, total: 0 },
-      progress: { milestones: { done: 0, total: 0 } },
-    };
+    result = buildDbUnavailableState();
   }
 
   result.recentDecisions = await loadRecentDecisions(cacheKey);
@@ -465,6 +492,16 @@ function buildCompletenessSet(basePath: string, milestones: MilestoneRow[]) {
   return { completeMilestoneIds, parkedMilestoneIds };
 }
 
+function milestoneArtifactExistsInResolvedDir(
+  milestoneDir: string | null,
+  milestoneId: string,
+  suffix: string,
+): boolean {
+  if (!milestoneDir) return false;
+  const flatPath = join(milestoneDir, buildMilestoneFileName(milestoneId, suffix));
+  return existsSync(flatPath) || resolveFile(milestoneDir, milestoneId, suffix) !== null;
+}
+
 async function buildRegistryAndFindActive(
   basePath: string,
   milestones: MilestoneRow[],
@@ -503,8 +540,9 @@ async function buildRegistryAndFindActive(
     const allSlicesDone = slices.length > 0 && slices.every(s => isStatusDone(s.status));
 
     const title = stripMilestonePrefix(m.title) || m.id;
-    const hasContext = !!resolveMilestoneFile(basePath, m.id, "CONTEXT");
-    const hasDraftContext = !hasContext && !!resolveMilestoneFile(basePath, m.id, "CONTEXT-DRAFT");
+    const milestoneDir = resolveMilestonePath(basePath, m.id);
+    const hasContext = milestoneArtifactExistsInResolvedDir(milestoneDir, m.id, "CONTEXT");
+    const hasDraftContext = !hasContext && milestoneArtifactExistsInResolvedDir(milestoneDir, m.id, "CONTEXT-DRAFT");
     const readiness = classifyMilestoneReadiness({
       status: m.status,
       hasContext,
@@ -730,6 +768,10 @@ export async function deriveStateFromDb(
   basePath: string,
   artifactReadRoot: string = basePath,
 ): Promise<GSDState> {
+  if (!ensureExistingWorkflowDbOpen(basePath)) {
+    return buildDbUnavailableState();
+  }
+
   const requirements = getRequirementCounts();
 
   const allMilestones = getAllMilestones();

package/src/resources/extensions/gsd/sync-lock.ts

@@ -1,27 +1,18 @@
 // GSD Extension — Advisory Sync Lock
 // Prevents concurrent worktree syncs from colliding via a simple file lock.
 // Stale locks (mtime > 60s, owner PID confirmed dead) are overridden. Lock
-// acquisition waits up to 5 seconds then skips non-fatally.
+// acquisition skips non-fatally when a live lock is already held.
 
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeSync } from "node:fs";
 import { dirname, join } from "node:path";
 
 const STALE_THRESHOLD_MS = 60_000; // 60 seconds
-const DEFAULT_TIMEOUT_MS = 5_000;  // 5 seconds
-const SPIN_INTERVAL_MS = 100;      // 100ms polling interval
-
-// SharedArrayBuffer for synchronous sleep via Atomics.wait
-const SLEEP_BUFFER = new SharedArrayBuffer(4);
-const SLEEP_VIEW = new Int32Array(SLEEP_BUFFER);
+const DEFAULT_TIMEOUT_MS = 0;      // fail fast; sync waits block the JS event loop
 
 function lockFilePath(basePath: string): string {
   return join(basePath, ".gsd", "sync.lock");
 }
 
-function sleepSync(ms: number): void {
-  Atomics.wait(SLEEP_VIEW, 0, 0, ms);
-}
-
 /** True if the given PID is alive in the current process namespace. */
 function isPidAlive(pid: number): boolean {
   try {
@@ -64,7 +55,7 @@ function tryCreateLockFile(lp: string, payload: string): boolean {
 
 /**
  * Acquire an advisory sync lock for the given basePath.
- * Returns { acquired: true } on success, { acquired: false } after timeout.
+ * Returns { acquired: true } on success, { acquired: false } when a live lock is held.
  *
  * Replaces a non-atomic `existsSync` + `atomicWriteSync` (write-temp+rename,
  * which is not exclusive-create) sequence that allowed two callers to both
@@ -75,13 +66,16 @@ function tryCreateLockFile(lp: string, payload: string): boolean {
  * before stealing — prevents a slow event-loop pause (>60s under heavy I/O)
  * from making a legitimately-held lock appear stale and get stolen.
  * (Issue #4980 M-concurrency-3)
+ *
+ * Contended live locks fail fast. A synchronous wait here would freeze timers,
+ * I/O, and UI work on Node's single JS thread. The timeout argument remains
+ * accepted for compatibility but is intentionally not used for sync waiting.
  */
 export function acquireSyncLock(
   basePath: string,
-  timeoutMs: number = DEFAULT_TIMEOUT_MS,
+  _timeoutMs: number = DEFAULT_TIMEOUT_MS,
 ): { acquired: boolean } {
   const lp = lockFilePath(basePath);
-  const deadline = Date.now() + timeoutMs;
   const lockData = JSON.stringify(
     { pid: process.pid, acquired_at: new Date().toISOString() },
     null,
@@ -98,7 +92,7 @@ export function acquireSyncLock(
       /* unexpected — fall through to retry */
     }
 
-    // File exists. Decide whether to steal (stale + owner dead) or wait.
+    // File exists. Decide whether to steal (stale + owner dead) or skip.
     let canSteal = false;
     try {
       const stat = statSync(lp);
@@ -129,11 +123,8 @@ export function acquireSyncLock(
       continue;
     }
 
-    // Lock is held and not stale (or owner is alive) — wait or give up.
-    if (Date.now() >= deadline) {
-      return { acquired: false };
-    }
-    sleepSync(SPIN_INTERVAL_MS);
+    // Lock is held and not stale (or owner is alive) — skip non-fatally.
+    return { acquired: false };
   }
 }
 

package/src/resources/extensions/gsd/tests/__fixtures__/flat-phase/.gsd/phases/01-foundation/01-01-PLAN.md

@@ -0,0 +1,13 @@
+# 01-01: Set up tooling
+
+<objective>
+Set up the build tooling.
+</objective>
+
+<tasks>
+- [ ] **T01**: Init repo _(30m)_
+</tasks>
+
+<verification>
+Build runs.
+</verification>

package/src/resources/extensions/gsd/tests/__fixtures__/flat-phase/.gsd/phases/01-foundation/01-ROADMAP.md

@@ -0,0 +1,8 @@
+# 01: Foundation
+
+**Vision:** A foundational setup.
+
+## Slices
+
+- [ ] **S01: Set up tooling** `risk:low` `depends:[]`
+  > After this: build runs

package/src/resources/extensions/gsd/tests/__fixtures__/round-trip/m001-basic/.gsd/milestones/M001/M001-ROADMAP.md

@@ -0,0 +1,13 @@
+# M001: First Milestone
+
+**Vision:** A round-trippable milestone.
+
+## Success Criteria
+
+- Criterion one
+- Criterion two
+
+## Slices
+
+- [ ] **S01: First slice** `risk:low` `depends:[]`
+  > After this: a demo exists

package/src/resources/extensions/gsd/tests/__fixtures__/round-trip/m001-basic/.gsd/milestones/M001/slices/S01/S01-PLAN.md

@@ -0,0 +1,5 @@
+# S01: First slice
+
+## Tasks
+
+- [ ] **T01: First task** `estimate:30m`

package/src/resources/extensions/gsd/tests/__fixtures__/round-trip/planning-flat-phases/.planning/PROJECT.md

@@ -0,0 +1 @@
+# Foundation

package/src/resources/extensions/gsd/tests/__fixtures__/round-trip/planning-flat-phases/.planning/ROADMAP.md

@@ -0,0 +1,5 @@
+# Roadmap
+
+## Phases
+
+- [ ] 01 — Foundation

package/src/resources/extensions/gsd/tests/__fixtures__/round-trip/planning-flat-phases/.planning/STATE.md

@@ -0,0 +1,10 @@
+---
+gsd_state_version: 1.0
+milestone: M001
+status: active
+---
+
+# Project State
+
+Current Phase: **01**
+Status: **active**

package/src/resources/extensions/gsd/tests/__fixtures__/round-trip/planning-flat-phases/.planning/phases/01-foundation/01-01-PLAN.md

@@ -0,0 +1,13 @@
+# 01-01: Set up tooling
+
+<objective>
+Set up the build tooling.
+</objective>
+
+<tasks>
+- [ ] **T01**: Init repo _(30m)_
+</tasks>
+
+<verification>
+Build runs.
+</verification>

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

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 
 import { resolveExpectedArtifactPath } from "../auto-artifact-paths.ts";
-import { clearPathCache, _clearGsdRootCache } from "../paths.ts";
+import { clearPathCache, _clearGsdRootCache, isLegacyMilestonesLayout, milestonesDir } from "../paths.ts";
 
 test("worktree artifact resolution falls back to project .gsd artifacts", () => {
   const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-auto-artifact-")));
@@ -38,3 +38,324 @@ test("worktree artifact resolution falls back to project .gsd artifacts", () =>
     rmSync(root, { recursive: true, force: true });
   }
 });
+
+// ── #852 follow-up: metadata-only milestones/<MID>/ must not flip the layout ──
+//
+// git-service.ts creates milestones/<MID>/ to store <MID>-META.json (the
+// integration-branch metadata) even in flat-phase projects. Before this fix,
+// the existence of that dir made layout detection conclude "legacy", so
+// verification resolved the CONTEXT/ROADMAP to milestones/<MID>/<MID>-CONTEXT.md
+// (which doesn't exist in a flat-phase project) instead of phases/NN-slug/ —
+// trapping the unit in a finalize-retry loop. A milestones/<MID>/ dir holding
+// only *-META.json must NOT count as a real legacy milestone.
+
+test("metadata-only milestones/<MID>/ does not flip layout to legacy (#852)", () => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-meta-pollution-")));
+  try {
+    const gsd = join(root, ".gsd");
+    // Flat-phase layout: phases/15-m015/ with real content.
+    const phaseDir = join(gsd, "phases", "15-m015");
+    mkdirSync(phaseDir, { recursive: true });
+    writeFileSync(join(phaseDir, "15-CONTEXT.md"), "# context\n");
+
+    // Pollution: git-service.ts creates milestones/M015/ for META.json only.
+    const metaDir = join(gsd, "milestones", "M015");
+    mkdirSync(metaDir, { recursive: true });
+    writeFileSync(join(metaDir, "M015-META.json"), '{"branch":"milestone/M015"}');
+
+    _clearGsdRootCache();
+    clearPathCache();
+
+    // The metadata-only dir must NOT make this look like a legacy project.
+    assert.equal(isLegacyMilestonesLayout(root), false, "metadata-only milestones dir must not flip layout");
+    assert.ok(milestonesDir(root).endsWith(join(".gsd", "phases")), "milestonesDir resolves to phases/ not milestones/");
+
+    // And the discuss-milestone CONTEXT artifact must resolve to the flat-phase path.
+    assert.equal(
+      resolveExpectedArtifactPath("discuss-milestone", "M015", root),
+      join(phaseDir, "15-CONTEXT.md"),
+    );
+  } finally {
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("milestones/<MID>/ with only META.json + subdir does not flip layout to legacy", () => {
+  // Regression for the Cursor Bugbot finding: a flat-phase project whose
+  // milestones/<MID>/ contains only *-META.json plus an empty subdirectory
+  // (e.g. slices/) must NOT be treated as a content-bearing legacy milestone.
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-meta-subdir-")));
+  try {
+    const gsd = join(root, ".gsd");
+    // Flat-phase layout: phases/01-m001/ with real content.
+    const phaseDir = join(gsd, "phases", "01-m001");
+    mkdirSync(phaseDir, { recursive: true });
+    writeFileSync(join(phaseDir, "01-CONTEXT.md"), "# context\n");
+
+    // Pollution: milestones/M001/ has a META file + a bare subdirectory.
+    const metaDir = join(gsd, "milestones", "M001");
+    mkdirSync(join(metaDir, "slices"), { recursive: true });
+    writeFileSync(join(metaDir, "M001-META.json"), '{"branch":"milestone/M001"}');
+
+    _clearGsdRootCache();
+    clearPathCache();
+
+    assert.equal(
+      isLegacyMilestonesLayout(root),
+      false,
+      "META-only + subdir milestones dir must not flip layout",
+    );
+    assert.ok(
+      milestonesDir(root).endsWith(join(".gsd", "phases")),
+      "milestonesDir resolves to phases/ not milestones/",
+    );
+  } finally {
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("milestones/<MID>/ with non-empty slices/ subdir is detected as legacy (no files in milestone root)", () => {
+  // The common real-legacy fixture pattern: milestones/M001/slices/S01/ with no
+  // file directly in milestones/M001/.  The non-empty slices/ subdir must still
+  // trigger legacy detection so artifact resolution stays on the milestones/ path.
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-legacy-subdir-")));
+  try {
+    const legacyDir = join(root, ".gsd", "milestones", "M001");
+    mkdirSync(join(legacyDir, "slices", "S01", "tasks"), { recursive: true });
+
+    _clearGsdRootCache();
+    clearPathCache();
+
+    assert.equal(
+      isLegacyMilestonesLayout(root),
+      true,
+      "non-empty slices/ subdir must still detect as legacy",
+    );
+  } finally {
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("content-bearing milestones/<MID>/ still resolves to legacy (#852 regression guard)", () => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-legacy-real-")));
+  try {
+    // Legacy layout: milestones/M001/ with real content (not just META).
+    const legacyDir = join(root, ".gsd", "milestones", "M001");
+    mkdirSync(legacyDir, { recursive: true });
+    writeFileSync(join(legacyDir, "M001-CONTEXT.md"), "# context\n");
+
+    _clearGsdRootCache();
+    clearPathCache();
+
+    assert.equal(isLegacyMilestonesLayout(root), true, "content-bearing milestones dir is legacy");
+    assert.equal(
+      resolveExpectedArtifactPath("discuss-milestone", "M001", root),
+      join(legacyDir, "M001-CONTEXT.md"),
+    );
+  } finally {
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+// ── #852 follow-up: the EXACT failure path that survived #858 ────────────────
+//
+// #858 fixed legacyMilestonesHasSubdirs/resolvePhaseDir/resolveMilestonePath in
+// paths.ts, but resolveMilestoneArtifactPath (auto-artifact-paths.ts:35) has an
+// EARLY-RETURN legacy check via resolveProjectMilestonePath that bypassed all of
+// those. With a flat-phase project + a META-only milestones/M015/ dir (created
+// by git-service.ts), the early-return resolved CONTEXT to
+// milestones/M015/M015-CONTEXT.md (never exists) instead of
+// phases/15-m015/15-CONTEXT.md — reproducing the production loop:
+//   verify-fail discuss-milestone M015: existsSync false for
+//     .../milestones/M015/M015-CONTEXT.md
+// This test guards the project-root legacy lookup, not just paths.ts.
+
+test("resolveProjectMilestonePath ignores META-only dir: flat-phase wins (#852 follow-up to #858)", () => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-meta-bypass-")));
+  try {
+    const gsd = join(root, ".gsd");
+
+    // Flat-phase layout: phases/15-m015/ with real CONTEXT content.
+    const phaseDir = join(gsd, "phases", "15-m015");
+    mkdirSync(phaseDir, { recursive: true });
+    writeFileSync(join(phaseDir, "15-CONTEXT.md"), "# M015 context\n");
+
+    // Pollution: git-service.ts:450 created milestones/M015/ for META only.
+    // This is the dir that previously flipped the early-return to legacy.
+    const metaDir = join(gsd, "milestones", "M015");
+    mkdirSync(metaDir, { recursive: true });
+    writeFileSync(join(metaDir, "M015-META.json"), '{"branch":"milestone/M015"}');
+
+    _clearGsdRootCache();
+    clearPathCache();
+
+    const resolved = resolveExpectedArtifactPath("discuss-milestone", "M015", root);
+
+    // MUST resolve to the flat-phase path, NOT the legacy META-only path.
+    assert.equal(
+      resolved,
+      join(phaseDir, "15-CONTEXT.md"),
+      "META-only milestones/M015/ must not produce the legacy path; flat-phase wins",
+    );
+    // Explicitly assert the bug does NOT reproduce — the legacy path is wrong.
+    assert.notEqual(
+      resolved,
+      join(metaDir, "M015-CONTEXT.md"),
+      "must NOT resolve to the legacy milestones/M015/M015-CONTEXT.md path",
+    );
+  } finally {
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("resolveProjectMilestonePath ignores META-only dir even when phases/ has no matching dir yet", () => {
+  // The worktree/early-run edge case: phases/ doesn't exist yet (or doesn't have
+  // 15-m015/), but milestones/M015/ exists with only META. The resolver must
+  // return null (file genuinely not found yet) rather than the wrong legacy
+  // path — so the caller reports a clear "missing" instead of looping on a
+  // path that will never exist.
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-meta-no-phase-")));
+  try {
+    const metaDir = join(root, ".gsd", "milestones", "M015");
+    mkdirSync(metaDir, { recursive: true });
+    writeFileSync(join(metaDir, "M015-META.json"), '{"branch":"milestone/M015"}');
+    // Note: no phases/ dir at all.
+
+    _clearGsdRootCache();
+    clearPathCache();
+
+    const resolved = resolveExpectedArtifactPath("discuss-milestone", "M015", root);
+    // Must not produce the legacy path; null or a non-legacy path is correct.
+    assert.ok(
+      resolved === null || !resolved.includes(join("milestones", "M015")),
+      `META-only dir with no phases/ must not resolve to legacy; got: ${resolved}`,
+    );
+  } finally {
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+// ── #852: flat-phase dir must get flat-phase filename, not legacy ─────────────
+//
+// The most insidious variant: resolveProjectedMilestonePath found the correct
+// flat-phase directory (phases/15-m015/), but the old code at line 37 built
+// the LEGACY filename (M015-CONTEXT.md) unconditionally — producing
+// existsSync-false for phases/15-m015/M015-CONTEXT.md. The file is named
+// 15-CONTEXT.md. This test guards the layout-aware filename for ALL branches.
+
+test("flat-phase worktree dir resolves to 15-CONTEXT.md not M015-CONTEXT.md (#852)", () => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-filename-layout-")));
+  try {
+    const gsd = join(root, ".gsd");
+    // Flat-phase layout: phases/15-m015/ with the correctly-named file.
+    const phaseDir = join(gsd, "phases", "15-m015");
+    mkdirSync(phaseDir, { recursive: true });
+    writeFileSync(join(phaseDir, "15-CONTEXT.md"), "# M015 context\n");
+
+    _clearGsdRootCache();
+    clearPathCache();
+
+    const resolved = resolveExpectedArtifactPath("discuss-milestone", "M015", root);
+
+    // MUST use the flat-phase filename, not the legacy one.
+    assert.equal(
+      resolved,
+      join(phaseDir, "15-CONTEXT.md"),
+      "flat-phase dir must use 15-CONTEXT.md (phase-number prefix)",
+    );
+    assert.notEqual(
+      resolved,
+      join(phaseDir, "M015-CONTEXT.md"),
+      "must NOT use M015-CONTEXT.md (legacy milestone-id prefix) for a flat-phase dir",
+    );
+  } finally {
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("flat-phase project-root dir resolves to 15-ROADMAP.md not M015-ROADMAP.md (#852)", () => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-filename-roadmap-")));
+  try {
+    const gsd = join(root, ".gsd");
+    const phaseDir = join(gsd, "phases", "16-m016");
+    mkdirSync(phaseDir, { recursive: true });
+    writeFileSync(join(phaseDir, "16-ROADMAP.md"), "# M016 roadmap\n");
+
+    _clearGsdRootCache();
+    clearPathCache();
+
+    const resolved = resolveExpectedArtifactPath("plan-milestone", "M016", root);
+    assert.equal(
+      resolved,
+      join(phaseDir, "16-ROADMAP.md"),
+      "flat-phase dir must use 16-ROADMAP.md (phase-number prefix)",
+    );
+  } finally {
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+// ── Bugbot c5ee8eba: canonical worktree + project-root legacy dir ─────────────
+//
+// On a canonical worktree (<project>/.gsd-worktrees/M001/):
+//   - legacyMilestonesDir(base) uses gsdProjectionRoot → <project>/.gsd-worktrees/M001/.gsd/milestones
+//   - resolveProjectMilestonePath(base) uses gsdRoot → <project>/.gsd/milestones/M001/
+//
+// These are different paths. When there is no flat-phase dir in the worktree
+// but a legacy milestones/<MID>/ dir exists at the project root, the old code
+// compared the project-root dir against the worktree legacyBase — a mismatch
+// — so isLegacy was false and the flat-phase filename "01-ROADMAP.md" was
+// built instead of "M001-ROADMAP.md". The file-not-found loop follows.
+
+test("canonical worktree + project-root legacy dir produces legacy filename (#bugbot c5ee8eba)", () => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-canonical-wt-legacy-")));
+  try {
+    // Project-root legacy milestone dir with some content (not just META).
+    const projectLegacyDir = join(root, ".gsd", "milestones", "M001");
+    mkdirSync(projectLegacyDir, { recursive: true });
+    // Write CONTEXT but NOT ROADMAP — forces the dir-resolution cold path for ROADMAP.
+    writeFileSync(join(projectLegacyDir, "M001-CONTEXT.md"), "# M001 context\n");
+
+    // Canonical worktree: <project>/.gsd-worktrees/M001/.gsd/ (no phases dir).
+    const wtRoot = join(root, ".gsd-worktrees", "M001");
+    mkdirSync(join(wtRoot, ".gsd"), { recursive: true });
+
+    _clearGsdRootCache();
+    clearPathCache();
+
+    const resolved = resolveExpectedArtifactPath("plan-milestone", "M001", wtRoot);
+
+    // Must use the legacy milestone-id prefix (M001-ROADMAP.md), not the
+    // flat-phase phase-number prefix (01-ROADMAP.md).
+    assert.equal(
+      resolved,
+      join(projectLegacyDir, "M001-ROADMAP.md"),
+      "canonical worktree + project-root legacy dir must use M001-ROADMAP.md",
+    );
+    assert.notEqual(
+      resolved,
+      join(projectLegacyDir, "01-ROADMAP.md"),
+      "must NOT produce flat-phase filename 01-ROADMAP.md for a legacy milestones/ dir",
+    );
+  } finally {
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(root, { recursive: true, force: true });
+  }
+});