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

package/src/resources/extensions/gsd/visualizer-data.ts

@@ -5,6 +5,7 @@ import { join } from 'node:path';
 import { deriveState } from './state.js';
 import { parseSummary, loadFile } from './files.js';
 import { isDbAvailable, getMilestoneSlices, getSliceTasks } from './gsd-db.js';
+import { openExistingWorkflowDatabase } from './db-workspace.js';
 import { parseRoadmap, parsePlan } from './parsers-legacy.js';
 import { findMilestoneIds } from './milestone-ids.js';
 import { resolveMilestoneFile, resolveSliceFile, resolveGsdRootFile, gsdRoot } from './paths.js';
@@ -26,6 +27,7 @@ import { generateSkillHealthReport } from './skill-health.js';
 import { runEnvironmentChecks, type EnvironmentCheckResult } from './doctor-environment.js';
 import { computeProgressScore } from './progress-score.js';
 import { getHealthHistory } from './doctor-proactive.js';
+import { getActiveMemories, getActiveMemoriesRanked } from './memory-store.js';
 
 import type { Phase } from './types.js';
 import type { CaptureEntry } from './captures.js';
@@ -144,6 +146,22 @@ export interface KnowledgeInfo {
   exists: boolean;
 }
 
+export interface VisualizerMemoryEntry {
+  id: string;
+  category: string;
+  content: string;
+  confidence: number;
+  hitCount: number;
+  scope: string;
+  tags: string[];
+  updatedAt: string;
+}
+
+export interface MemoryInfo {
+  entries: VisualizerMemoryEntry[];
+  totalCount: number;
+}
+
 export interface CapturesInfo {
   entries: CaptureEntry[];
   pendingCount: number;
@@ -222,6 +240,7 @@ export interface VisualizerData {
   changelog: ChangelogInfo;
   sliceVerifications: SliceVerification[];
   knowledge: KnowledgeInfo;
+  memories: MemoryInfo;
   captures: CapturesInfo;
   health: HealthInfo;
   discussion: VisualizerDiscussionState[];
@@ -588,6 +607,39 @@ function loadKnowledge(basePath: string): KnowledgeInfo {
   return { rules, patterns, lessons, exists: true };
 }
 
+// ─── Memory Loader ────────────────────────────────────────────────────────────
+
+const VISUALIZER_MEMORY_LIMIT = 20;
+const VISUALIZER_MEMORY_CONTENT_LIMIT = 2000;
+
+function ensureVisualizerDb(basePath: string): void {
+  if (isDbAvailable()) return;
+  openExistingWorkflowDatabase(basePath);
+}
+
+function loadMemories(): MemoryInfo {
+  const allActive = getActiveMemories();
+  const ranked = getActiveMemoriesRanked(VISUALIZER_MEMORY_LIMIT);
+  return {
+    totalCount: allActive.length,
+    entries: ranked.map((memory) => ({
+      id: memory.id,
+      category: memory.category,
+      content: limitMemoryContent(memory.content),
+      confidence: memory.confidence,
+      hitCount: memory.hit_count,
+      scope: memory.scope,
+      tags: memory.tags,
+      updatedAt: memory.updated_at,
+    })),
+  };
+}
+
+function limitMemoryContent(content: string): string {
+  if (content.length <= VISUALIZER_MEMORY_CONTENT_LIMIT) return content;
+  return `${content.slice(0, VISUALIZER_MEMORY_CONTENT_LIMIT).trimEnd()}...`;
+}
+
 // ─── Health Loader ────────────────────────────────────────────────────────────
 
 function loadHealth(units: UnitMetrics[], totals: ProjectTotals | null, basePath: string): HealthInfo {
@@ -783,6 +835,7 @@ function readFileCached(filePath: string): string | null {
 // ─── Loader ───────────────────────────────────────────────────────────────────
 
 export async function loadVisualizerData(basePath: string): Promise<VisualizerData> {
+  ensureVisualizerDb(basePath);
   const state = await deriveState(basePath);
   const milestoneIds = findMilestoneIds(basePath);
 
@@ -917,6 +970,7 @@ export async function loadVisualizerData(basePath: string): Promise<VisualizerDa
   const { changelog, verifications: sliceVerifications } = await loadChangelogAndVerifications(basePath, milestones);
 
   const knowledge = loadKnowledge(basePath);
+  const memories = loadMemories();
   const allCaptures = loadAllCaptures(basePath);
   const pendingCount = countPendingCaptures(basePath);
   const captures: CapturesInfo = {
@@ -945,6 +999,7 @@ export async function loadVisualizerData(basePath: string): Promise<VisualizerDa
     changelog,
     sliceVerifications,
     knowledge,
+    memories,
     captures,
     health,
     discussion,

package/src/resources/extensions/gsd/visualizer-views.ts

@@ -935,13 +935,20 @@ export function renderKnowledgeView(
 ): string[] {
   const lines: string[] = [];
   const knowledge = data.knowledge;
+  const memories = data.memories;
 
-  if (!knowledge.exists) {
+  if (!knowledge.exists && memories.entries.length === 0) {
     lines.push(th.fg("dim", "No KNOWLEDGE.md found"));
     return lines;
   }
 
-  if (knowledge.rules.length === 0 && knowledge.patterns.length === 0 && knowledge.lessons.length === 0) {
+  if (
+    knowledge.exists &&
+    knowledge.rules.length === 0 &&
+    knowledge.patterns.length === 0 &&
+    knowledge.lessons.length === 0 &&
+    memories.entries.length === 0
+  ) {
     lines.push(th.fg("dim", "KNOWLEDGE.md exists but is empty"));
     return lines;
   }
@@ -985,6 +992,24 @@ export function renderKnowledgeView(
     lines.push("");
   }
 
+  if (memories.entries.length > 0) {
+    const countLabel = memories.totalCount > memories.entries.length
+      ? `${memories.entries.length}/${memories.totalCount}`
+      : `${memories.totalCount}`;
+    lines.push(th.fg("accent", th.bold(`Memories (${countLabel})`)));
+    lines.push("");
+    for (const memory of memories.entries) {
+      const scope = memory.scope && memory.scope !== "project" ? ` ${th.fg("dim", `[${memory.scope}]`)}` : "";
+      const tags = memory.tags.length > 0 ? ` ${th.fg("dim", `#${memory.tags.join(" #")}`)}` : "";
+      lines.push(truncateToWidth(
+        `  ${th.fg("accent", memory.id)}  (${memory.category}, ${memory.confidence.toFixed(2)}, hits ${memory.hitCount})${scope}${tags}`,
+        width,
+      ));
+      lines.push(truncateToWidth(`    ${memory.content}`, width));
+    }
+    lines.push("");
+  }
+
   return lines;
 }
 

package/src/resources/extensions/gsd/workflow-manifest.ts

@@ -10,11 +10,12 @@ import type { ArtifactRow, MilestoneRow } from "./db-milestone-artifact-rows.js"
 import type { SliceRow, TaskRow } from "./db-task-slice-rows.js";
 import type { VerificationEvidenceRow } from "./db-verification-evidence-rows.js";
 import type { Decision, GateRow, Requirement } from "./types.js";
-import { atomicWriteSync } from "./atomic-write.js";
+import { atomicWriteAsync, atomicWriteSync } from "./atomic-write.js";
 import { getAllDecisionsFromMemories } from "./context-store.js";
 import { backfillDecisionsToMemories } from "./memory-backfill.js";
 import { invalidateAllCaches } from "./cache.js";
-import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { logWarning } from "./workflow-logger.js";
+import { readFileSync, existsSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
 
 // ─── Manifest Types ──────────────────────────────────────────────────────
@@ -349,16 +350,146 @@ export function snapshotState(): StateManifest {
 
 // ─── writeManifest ───────────────────────────────────────────────────────
 
+interface ManifestWriteState {
+  filePath: string;
+  latestJson: string | null;
+  inFlightJson: string | null;
+  /** Set by sync exit flush so an in-flight async write cannot leave stale data on disk. */
+  syncFlushJson: string | null;
+  active: Promise<void> | null;
+}
+
+const manifestWrites = new Map<string, ManifestWriteState>();
+let processTeardownFlushInstalled = false;
+let beforeExitFlushStarted = false;
+
+function manifestWriteKey(basePath: string): string {
+  return resolve(basePath);
+}
+
+function manifestFilePath(basePath: string): string {
+  return join(resolve(basePath), ".gsd", "state-manifest.json");
+}
+
+function describeError(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+function logManifestWriteFailure(filePath: string, err: unknown): void {
+  logWarning("manifest", `state manifest write failed: ${describeError(err)}`, { file: filePath });
+}
+
+async function drainManifestWrites(key: string, state: ManifestWriteState): Promise<void> {
+  let lastWriteError: unknown = null;
+  try {
+    while (state.latestJson !== null && state.syncFlushJson === null) {
+      const json = state.latestJson;
+      state.latestJson = null;
+      state.inFlightJson = json;
+      try {
+        await atomicWriteAsync(state.filePath, json);
+        if (state.syncFlushJson !== null) {
+          atomicWriteSync(state.filePath, state.syncFlushJson);
+          break;
+        }
+        lastWriteError = null;
+      } catch (err) {
+        lastWriteError = err;
+        logManifestWriteFailure(state.filePath, err);
+      } finally {
+        state.inFlightJson = null;
+      }
+    }
+  } finally {
+    state.active = null;
+    if (state.latestJson === null && state.inFlightJson === null) {
+      manifestWrites.delete(key);
+    }
+  }
+  if (lastWriteError !== null && state.syncFlushJson === null) {
+    throw lastWriteError;
+  }
+}
+
+function enqueueManifestWrite(basePath: string, json: string): void {
+  const key = manifestWriteKey(basePath);
+  let state = manifestWrites.get(key);
+  if (!state) {
+    state = {
+      filePath: manifestFilePath(basePath),
+      latestJson: null,
+      inFlightJson: null,
+      syncFlushJson: null,
+      active: null,
+    };
+    manifestWrites.set(key, state);
+  }
+
+  state.latestJson = json;
+  if (!state.active) {
+    const active = drainManifestWrites(key, state);
+    void active.catch(() => {});
+    state.active = active;
+  }
+}
+
 /**
- * Write current DB state to .gsd/state-manifest.json via atomicWriteSync.
+ * Queue current DB state for an async atomic write to .gsd/state-manifest.json.
  * Uses JSON.stringify with 2-space indent for git three-way merge friendliness.
  */
 export function writeManifest(basePath: string): void {
   const manifest = snapshotState();
   const json = JSON.stringify(manifest, null, 2);
-  const dir = join(basePath, ".gsd");
-  mkdirSync(dir, { recursive: true });
-  atomicWriteSync(join(dir, "state-manifest.json"), json);
+  enqueueManifestWrite(basePath, json);
+}
+
+async function flushManifestByKey(key: string): Promise<void> {
+  for (;;) {
+    const active = manifestWrites.get(key)?.active;
+    if (!active) return;
+    await active;
+  }
+}
+
+/**
+ * Wait for any queued manifest write for this base path to become durable.
+ */
+export async function flushManifest(basePath: string): Promise<void> {
+  await flushManifestByKey(manifestWriteKey(basePath));
+}
+
+export async function flushAllManifests(): Promise<void> {
+  await Promise.all(Array.from(manifestWrites.keys(), key => flushManifestByKey(key)));
+}
+
+function flushAllManifestsSync(): void {
+  for (const [key, state] of manifestWrites) {
+    const json = state.latestJson ?? state.inFlightJson;
+    if (json === null) continue;
+    try {
+      atomicWriteSync(state.filePath, json);
+      state.latestJson = null;
+      state.inFlightJson = null;
+      state.syncFlushJson = json;
+      manifestWrites.delete(key);
+    } catch (err) {
+      logManifestWriteFailure(state.filePath, err);
+    }
+  }
+}
+
+export function installManifestFlushOnProcessTeardown(): void {
+  if (processTeardownFlushInstalled) return;
+  processTeardownFlushInstalled = true;
+
+  process.once("beforeExit", () => {
+    if (beforeExitFlushStarted) return;
+    beforeExitFlushStarted = true;
+    void flushAllManifests();
+  });
+  process.once("exit", () => {
+    flushAllManifestsSync();
+  });
 }
 
 // ─── readManifest ────────────────────────────────────────────────────────
@@ -414,9 +545,12 @@ function restoreArtifactProjections(basePath: string, manifest: StateManifest):
   if (manifest.artifacts === undefined) return;
 
   for (const artifact of manifest.artifacts) {
+    const content = artifact.full_content ?? "";
+    if (content === "") continue;
+
     atomicWriteSync(
       artifactProjectionPath(basePath, artifact.path),
-      artifact.full_content ?? "",
+      content,
     );
   }
 }

package/src/resources/extensions/gsd/workflow-mcp.ts

@@ -85,6 +85,8 @@ function lookupCommand(command: string, platform: NodeJS.Platform = process.plat
   }
 }
 
+const gsdPiRepoRootCache = new Map<string, string | null>();
+
 function findGsdPiRepoRoot(startPath: string): string | null {
   let current: string;
   try {
@@ -93,15 +95,24 @@ function findGsdPiRepoRoot(startPath: string): string | null {
     current = resolve(startPath);
   }
 
+  const cacheKey = current;
+  if (gsdPiRepoRootCache.has(cacheKey)) {
+    return gsdPiRepoRootCache.get(cacheKey) ?? null;
+  }
+
   while (true) {
     const distCli = resolve(current, "packages", "mcp-server", "dist", "cli.js");
-    if (existsSync(distCli)) return current;
+    if (existsSync(distCli)) {
+      gsdPiRepoRootCache.set(cacheKey, current);
+      return current;
+    }
 
     const parent = dirname(current);
     if (parent === current) break;
     current = parent;
   }
 
+  gsdPiRepoRootCache.set(cacheKey, null);
   return null;
 }
 

package/src/resources/extensions/gsd/workflow-projections.ts

@@ -26,7 +26,7 @@ import { deriveState } from "./state.js";
 import type { GSDState } from "./types.js";
 import { renderPlanFromDb, renderRoadmapFromDb } from "./markdown-renderer.js";
 import { readManifest } from "./workflow-manifest.js";
-import { gsdRoot } from "./paths.js";
+import { gsdRoot, resolveSliceFile, resolveMilestonePath, resolveSlicePath, gsdProjectionRoot } from "./paths.js";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────
 
@@ -328,7 +328,23 @@ export function renderSummaryProjection(basePath: string, milestoneId: string, s
 
   const evidenceRows = getVerificationEvidence(milestoneId, sliceId, taskId);
   const content = renderSummaryContent(taskRow, sliceId, milestoneId, evidenceRows);
-  const dir = join(basePath, ".gsd", "milestones", milestoneId, "slices", sliceId, "tasks");
+
+  // Layout-aware: avoid creating a milestones/ directory as a side effect for
+  // flat-phase projects. If milestonesDir() sees a freshly-created milestones/
+  // dir it treats the project as legacy, breaking all subsequent path resolution.
+  const slicePath = resolveSlicePath(basePath, milestoneId, sliceId);
+  const phaseDir = resolveMilestonePath(basePath, milestoneId);
+  let dir: string;
+  if (slicePath && phaseDir && slicePath !== phaseDir) {
+    // Legacy layout: slice has its own slices/SID/ subdir → tasks/ subdir
+    dir = join(slicePath, "tasks");
+  } else if (phaseDir) {
+    // Flat-phase: task summaries go in the phase dir (no tasks/ subdir needed)
+    dir = phaseDir;
+  } else {
+    // Fallback: legacy hardcoded path (milestone dir not on disk yet)
+    dir = join(gsdProjectionRoot(basePath), "milestones", milestoneId, "slices", sliceId, "tasks");
+  }
   mkdirSync(dir, { recursive: true });
   atomicWriteSync(join(dir, `${taskId}-SUMMARY.md`), content);
 }
@@ -435,16 +451,14 @@ export async function renderStateProjection(basePath: string): Promise<void> {
   }
 }
 
-// ─── renderAllProjections ───────────────────────────────────────────────
+// ─── renderMilestoneShellProjections ─────────────────────────────────────
 
 /**
- * Regenerate all projection files for a milestone from DB state.
- * All calls are wrapped in try/catch — projection failure is non-fatal per D-02.
+ * Regenerate milestone-level projections (roadmap, top-level views, STATE.md).
+ * Does not touch slice PLAN.md or task SUMMARY.md — those have authoritative
+ * renderers in plan-slice / complete-task.
  */
-export async function renderAllProjections(basePath: string, milestoneId: string): Promise<void> {
-  // Delegate to the authoritative roadmap renderer — the reduced
-  // renderRoadmapProjection omits sections like ## Boundary Map and would
-  // clobber the output written by plan-milestone / reassess-roadmap.
+export async function renderMilestoneShellProjections(basePath: string, milestoneId: string): Promise<void> {
   try {
     await renderRoadmapFromDb(basePath, milestoneId);
   } catch (err) {
@@ -460,6 +474,21 @@ export async function renderAllProjections(basePath: string, milestoneId: string
   } catch (err) {
     logWarning("projection", `renderTopLevelQueueFromDb failed: ${(err as Error).message}`);
   }
+  try {
+    await renderStateProjection(basePath);
+  } catch (err) {
+    logWarning("projection", `renderStateProjection failed: ${(err as Error).message}`);
+  }
+}
+
+// ─── renderAllProjections ───────────────────────────────────────────────
+
+/**
+ * Regenerate all projection files for a milestone from DB state.
+ * All calls are wrapped in try/catch — projection failure is non-fatal per D-02.
+ */
+export async function renderAllProjections(basePath: string, milestoneId: string): Promise<void> {
+  await renderMilestoneShellProjections(basePath, milestoneId);
 
   // Query all slices for this milestone
   const sliceRows = getMilestoneSlices(milestoneId);
@@ -482,13 +511,6 @@ export async function renderAllProjections(basePath: string, milestoneId: string
       }
     }
   }
-
-  // Render STATE.md
-  try {
-    await renderStateProjection(basePath);
-  } catch (err) {
-    logWarning("projection", `renderStateProjection failed: ${(err as Error).message}`);
-  }
 }
 
 // ─── regenerateIfMissing ────────────────────────────────────────────────
@@ -509,7 +531,9 @@ export async function regenerateIfMissing(
 
   switch (fileType) {
     case "PLAN":
-      filePath = join(basePath, ".gsd", "milestones", milestoneId, "slices", sliceId, `${sliceId}-PLAN.md`);
+      // Use resolveSliceFile so both flat-phase and legacy layouts are detected.
+      // Falls back to "" (non-existent) when the file hasn't been rendered yet.
+      filePath = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN") ?? "";
       break;
     case "ROADMAP":
       filePath = join(basePath, ".gsd", "milestones", milestoneId, `${milestoneId}-ROADMAP.md`);
@@ -562,7 +586,9 @@ export async function regenerateIfMissing(
     switch (fileType) {
       case "PLAN":
         await renderPlanFromDb(basePath, milestoneId, sliceId);
-        return existsSync(filePath);
+        // Re-resolve after render: the rendered file may be at a different path
+        // from the pre-check (flat-phase vs legacy). resolveSliceFile finds it.
+        return !!(resolveSliceFile(basePath, milestoneId, sliceId, "PLAN"));
       case "ROADMAP":
         await renderRoadmapFromDb(basePath, milestoneId);
         return existsSync(filePath);

package/src/resources/extensions/gsd/workspace-git-preflight.ts

@@ -7,6 +7,7 @@ import { getAutoWorktreePath } from "./auto-worktree.js";
 import { isSafeToAutoResolve } from "./auto-worktree.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import {
+  listMergeStateBlockers,
   probeGitConflictState,
   reconcileGitConflictsOnSignal,
   type GitConflictProbeResult,
@@ -30,6 +31,9 @@ export type WorkspaceGitReadyResult =
       targets: string[];
     };
 
+const CLEAN_TARGET_CACHE_TTL_MS = 10_000;
+const cleanTargetProbeCache = new Map<string, number>();
+
 function normalizeTargetPath(path: string): string {
   try {
     return realpathSync(path);
@@ -110,6 +114,25 @@ function formatBlockReason(
 
 async function ensureTargetGitReady(target: string): Promise<WorkspaceGitReadyResult> {
   const fixesApplied: string[] = [];
+  const cacheKey = normalizeTargetPath(target);
+  const cachedCleanAt = cleanTargetProbeCache.get(cacheKey);
+  if (cachedCleanAt !== undefined) {
+    if (Date.now() - cachedCleanAt < CLEAN_TARGET_CACHE_TTL_MS) {
+      // Merge-state markers (MERGE_HEAD, rebase-apply, rebase-merge) are the most
+      // common way a repo transitions from clean to dirty within the TTL window,
+      // including when a non-git folder is initialized as a repo mid-TTL and a
+      // merge immediately introduces conflicts. Check them here — they are pure
+      // existsSync calls with no git subprocess — and fall through to a full probe
+      // only when markers are present.
+      if (listMergeStateBlockers(cacheKey).length === 0) {
+        return { ok: true, fixesApplied };
+      }
+      cleanTargetProbeCache.delete(cacheKey);
+    } else {
+      cleanTargetProbeCache.delete(cacheKey);
+    }
+  }
+
   let probe = probeGitConflictState(target);
 
   for (let attempt = 0; attempt < 3 && probe.status === "dirty"; attempt++) {
@@ -129,6 +152,7 @@ async function ensureTargetGitReady(target: string): Promise<WorkspaceGitReadyRe
   }
 
   if (probe.status === "unknown") {
+    cleanTargetProbeCache.delete(cacheKey);
     return {
       ok: false,
       reason: formatBlockReason("unrecoverable", [], [target]),
@@ -141,6 +165,7 @@ async function ensureTargetGitReady(target: string): Promise<WorkspaceGitReadyRe
 
   const conflictedPaths = productConflictPaths(probe);
   if (conflictedPaths.length > 0 || probe.checkFailures.length > 0) {
+    cleanTargetProbeCache.delete(cacheKey);
     return {
       ok: false,
       reason: formatBlockReason("product-conflicts", conflictedPaths, [target]),
@@ -151,6 +176,12 @@ async function ensureTargetGitReady(target: string): Promise<WorkspaceGitReadyRe
     };
   }
 
+  if (probe.status === "clean") {
+    cleanTargetProbeCache.set(cacheKey, Date.now());
+  } else {
+    cleanTargetProbeCache.delete(cacheKey);
+  }
+
   return { ok: true, fixesApplied };
 }
 

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

@@ -1,7 +1,17 @@
 // gsd-pi + Workspace handle: single source of truth for path resolution per milestone
 
-import { join, resolve } from "node:path";
-import { type GsdPathContract, resolveGsdPathContract, normalizeRealPath } from "./paths.js";
+import { dirname, join, resolve } from "node:path";
+import {
+  buildMilestoneFileName,
+  canonicalPhaseDirName,
+  isLegacyMilestonesLayout,
+  milestonesDir,
+  type GsdPathContract,
+  resolveGsdPathContract,
+  resolveMilestoneFile,
+  resolveMilestonePath,
+  normalizeRealPath,
+} from "./paths.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
 
 export type GsdWorkspaceMode = "project" | "worktree";
@@ -31,6 +41,29 @@ function tryRealpath(p: string): string {
   return normalizeRealPath(p);
 }
 
+function isLegacyMilestoneDirectory(dir: string): boolean {
+  const parent = dirname(dir);
+  return parent.endsWith("/milestones") || parent.endsWith("\\milestones");
+}
+
+function scopeMilestoneDir(basePath: string, milestoneId: string): string {
+  return resolveMilestonePath(basePath, milestoneId) ?? join(
+    milestonesDir(basePath),
+    isLegacyMilestonesLayout(basePath) ? milestoneId : canonicalPhaseDirName(milestoneId),
+  );
+}
+
+function scopeMilestoneFile(basePath: string, milestoneId: string, suffix: string): string {
+  const existing = resolveMilestoneFile(basePath, milestoneId, suffix);
+  if (existing) return existing;
+
+  const dir = scopeMilestoneDir(basePath, milestoneId);
+  const filename = isLegacyMilestoneDirectory(dir)
+    ? `${milestoneId}-${suffix}.md`
+    : buildMilestoneFileName(milestoneId, suffix);
+  return join(dir, filename);
+}
+
 /**
  * Create an immutable GsdWorkspace handle from a raw base path.
  * Resolves both the project root and (when applicable) the worktree root,
@@ -73,22 +106,23 @@ export function createWorkspace(rawBasePath: string): GsdWorkspace {
  * Bind a milestoneId to a workspace, producing an immutable MilestoneScope
  * with path-returning closures for DB-authoritative project state.
  *
- * These scope paths intentionally route to contract.projectGsd. In-flight
- * markdown artifact readers outside this scope use the projection-aware
- * resolvers in paths.ts so worktree units can see worktree-local projections.
+ * DB paths route to contract.projectGsd. Milestone artifact paths resolve from
+ * the pinned project root with the layout-aware resolvers, so flat-phase and
+ * legacy projects use the same scope surface.
  */
 export function scopeMilestone(workspace: GsdWorkspace, milestoneId: string): MilestoneScope {
   const { contract } = workspace;
   const gsd = contract.projectGsd;
+  const basePath = workspace.projectRoot;
 
   const scope: MilestoneScope = Object.freeze({
     workspace,
     milestoneId,
-    contextFile: () => join(gsd, "milestones", milestoneId, `${milestoneId}-CONTEXT.md`),
-    roadmapFile: () => join(gsd, "milestones", milestoneId, `${milestoneId}-ROADMAP.md`),
+    contextFile: () => scopeMilestoneFile(basePath, milestoneId, "CONTEXT"),
+    roadmapFile: () => scopeMilestoneFile(basePath, milestoneId, "ROADMAP"),
     stateFile: () => join(gsd, "STATE.md"),
     dbPath: () => contract.projectDb,
-    milestoneDir: () => join(gsd, "milestones", milestoneId),
+    milestoneDir: () => scopeMilestoneDir(basePath, milestoneId),
     metaJson: () => join(gsd, `${milestoneId}-META.json`),
   });
 

package/src/resources/extensions/gsd/worktree-command.ts

@@ -570,11 +570,11 @@ async function handleMerge(
     }
 
     // Gather merge context — full repo diff, not just .gsd/
-    const diffSummary = diffWorktreeAll(basePath, name);
-    const numstat = diffWorktreeNumstat(basePath, name);
-    const gsdDiff = getWorktreeGSDDiff(basePath, name);
-    const codeDiff = getWorktreeCodeDiff(basePath, name);
-    const commitLog = getWorktreeLog(basePath, name);
+    const diffSummary = diffWorktreeAll(basePath, name, undefined, mainBranch);
+    const numstat = diffWorktreeNumstat(basePath, name, undefined, mainBranch);
+    const gsdDiff = getWorktreeGSDDiff(basePath, name, mainBranch);
+    const codeDiff = getWorktreeCodeDiff(basePath, name, mainBranch);
+    const commitLog = getWorktreeLog(basePath, name, mainBranch);
 
     const totalChanges = diffSummary.added.length + diffSummary.modified.length + diffSummary.removed.length;
     if (totalChanges === 0 && !commitLog.trim()) {
@@ -662,7 +662,7 @@ async function handleMerge(
     }
 
     try {
-      mergeWorktreeToMain(basePath, name, commitMessage);
+      mergeWorktreeToMain(basePath, name, commitMessage, undefined, mainBranch);
       ctx.ui.notify(
         [
           `${CLR.ok("✓")} Merged ${CLR.name(name)} → ${CLR.branch(mainBranch)} ${CLR.muted("(deterministic squash)")}`,