@opengsd/gsd-pi 1.9.0-dev.5c1a3ff2 → 1.9.0-dev.97ef11e3

package/src/resources/extensions/gsd/compat/compat-marker.ts

@@ -6,8 +6,8 @@
 // (drift to import). gsd-core is oblivious to this file and ignores it.
 
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync, mkdirSync } from "node:fs";
-import { dirname, join, isAbsolute, normalize } from "node:path";
+import { existsSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join, isAbsolute, normalize, relative, resolve } from "node:path";
 
 /** Current marker schema version. Bump on breaking format changes + migrate. */
 export const COMPAT_MARKER_SCHEMA = 2;
@@ -54,6 +54,13 @@ export interface CompatMarker {
   piVersion: string;
 }
 
+export interface ReadCompatMarkerOptions {
+  /** Rewrite invalid-but-derivable marker keys back to safe root-relative keys. */
+  healInvalidKeys?: boolean;
+  /** Quarantine malformed/unsafe markers. Disable only for read-only previews. */
+  quarantineInvalid?: boolean;
+}
+
 /** Marker returned when no marker exists yet (fresh project, first gsd-pi run). */
 export const EMPTY_MARKER: CompatMarker = {
   schema: COMPAT_MARKER_SCHEMA,
@@ -81,6 +88,37 @@ export function computeProjectionSha(content: string): string {
   return createHash("sha256").update(normalizeForHash(content)).digest("hex").slice(0, 16);
 }
 
+function normalizeRealPath(p: string): string {
+  try {
+    return realpathSync.native(p);
+  } catch {
+    return resolve(p);
+  }
+}
+
+function rootRelativeKey(rootPath: string, absPath: string): string | null {
+  const root = normalizeRealPath(rootPath);
+  const abs = normalizeRealPath(absPath);
+  const rel = relative(root, abs);
+  if (!rel || rel === ".." || rel.startsWith(`..${sepForRelative(rel)}`) || isAbsolute(rel)) {
+    return null;
+  }
+  return rel.replace(/\\/g, "/");
+}
+
+function sepForRelative(rel: string): string {
+  return rel.includes("\\") ? "\\" : "/";
+}
+
+export function deriveCompatProjectionKey(absPath: string, roots: readonly string[]): string {
+  for (const root of roots) {
+    const key = rootRelativeKey(root, absPath);
+    if (key) return key;
+  }
+  const fallbackRoot = roots[roots.length - 1] ?? dirname(absPath);
+  return relative(fallbackRoot, absPath).replace(/\\/g, "/");
+}
+
 /**
  * Read & validate the marker. A missing marker → EMPTY_MARKER (treat every
  * projection as external on next reconcile). A malformed marker is quarantined
@@ -88,7 +126,12 @@ export function computeProjectionSha(content: string): string {
  * EMPTY_MARKER. A schema-mismatch returns EMPTY_MARKER (forward-compat: refuse
  * to act on a future format we don't understand).
  */
-export function readCompatMarker(basePath: string): CompatMarker {
+export function readCompatMarker(
+  basePath: string,
+  options: ReadCompatMarkerOptions = {},
+): CompatMarker {
+  const healInvalidKeys = options.healInvalidKeys ?? true;
+  const quarantineInvalid = options.quarantineInvalid ?? true;
   const path = compatMarkerPath(basePath);
   if (!existsSync(path)) return emptyMarker();
 
@@ -103,12 +146,16 @@ export function readCompatMarker(basePath: string): CompatMarker {
   try {
     parsed = JSON.parse(raw);
   } catch {
-    quarantine(basePath, raw);
+    if (quarantineInvalid) quarantine(basePath, raw);
     return emptyMarker();
   }
 
+  if (healInvalidKeys && healMarkerProjectionKeys(basePath, parsed) && isValidMarker(parsed)) {
+    writeCompatMarker(basePath, parsed);
+  }
+
   if (!isValidMarker(parsed)) {
-    quarantine(basePath, raw);
+    if (quarantineInvalid) quarantine(basePath, raw);
     return emptyMarker();
   }
   // Promote older markers by defaulting absent fields. Schema 1 → 2 only adds
@@ -245,6 +292,53 @@ function isValidProjectionMap(x: unknown): boolean {
   return true;
 }
 
+function healMarkerProjectionKeys(basePath: string, marker: unknown): marker is CompatMarker {
+  if (typeof marker !== "object" || marker === null) return false;
+  const m = marker as Record<string, unknown>;
+  let changed = false;
+
+  if (typeof m.projections === "object" && m.projections !== null) {
+    changed = healProjectionMapKeys(basePath, ".gsd", m.projections as Record<string, ProjectionEntry>) || changed;
+  }
+
+  const planning = m.planning;
+  if (typeof planning === "object" && planning !== null) {
+    const p = planning as Record<string, unknown>;
+    if (typeof p.projections === "object" && p.projections !== null) {
+      changed = healProjectionMapKeys(basePath, ".planning", p.projections as Record<string, ProjectionEntry>) || changed;
+    }
+    if (typeof p.passthrough === "object" && p.passthrough !== null) {
+      changed = healProjectionMapKeys(basePath, ".planning", p.passthrough as Record<string, ProjectionEntry>) || changed;
+    }
+  }
+
+  return changed;
+}
+
+function healProjectionMapKeys(
+  basePath: string,
+  rootName: ".gsd" | ".planning",
+  map: Record<string, ProjectionEntry>,
+): boolean {
+  let changed = false;
+  const root = join(basePath, rootName);
+
+  for (const key of Object.keys(map)) {
+    if (isSafeProjectionKey(key)) continue;
+    if (key.includes("\0") || isAbsolute(key) || /^[A-Za-z]:/.test(key)) continue;
+    const healedKey = rootRelativeKey(root, resolve(root, key));
+    if (!healedKey || !isSafeProjectionKey(healedKey)) continue;
+
+    if (!map[healedKey]) {
+      map[healedKey] = map[key]!;
+    }
+    delete map[key];
+    changed = true;
+  }
+
+  return changed;
+}
+
 function isValidPlanningMarker(x: unknown): x is PlanningMarker {
   if (typeof x !== "object" || x === null) return false;
   const p = x as Record<string, unknown>;

package/src/resources/extensions/gsd/db/engine.ts

@@ -10,7 +10,7 @@
 // writer layer.
 import { createRequire } from "node:module";
 import { existsSync, copyFileSync, mkdirSync, realpathSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { GSDError, GSD_STALE_STATE } from "../errors.js";
 import type { GsdWorkspace, MilestoneScope } from "../workspace.js";
 import { logError, logWarning } from "../workflow-logger.js";
@@ -71,7 +71,10 @@ let _gsdRequire: ReturnType<typeof createRequire> | null | undefined;
 function getGsdRequire(): ReturnType<typeof createRequire> | null {
   if (_gsdRequire !== undefined) return _gsdRequire;
   try {
-    _gsdRequire = createRequire(import.meta.url);
+    // Next.js may emit this module into a CommonJS chunk. Avoid ESM-only module
+    // metadata syntax here; it is a hard parse error there.
+    const packageRoot = process.env.GSD_WEB_PACKAGE_ROOT || process.env.GSD_PKG_ROOT || process.cwd();
+    _gsdRequire = createRequire(resolve(packageRoot, "package.json"));
   } catch {
     _gsdRequire = null;
   }

package/src/resources/extensions/gsd/doctor-engine-checks.ts

@@ -95,6 +95,25 @@ function reportCheckboxDbStatusDivergence(
   });
 }
 
+function bareDuplicateMilestoneId(milestoneId: string): string | null {
+  const match = milestoneId.match(/^(M\d{3})-[a-z0-9]{6}$/i);
+  return match?.[1]?.toUpperCase() ?? null;
+}
+
+function checkboxDbStatusMilestoneIds(basePath: string, milestoneIds: string[]): string[] {
+  if (!hasFlatPhaseLayout(basePath)) return milestoneIds;
+
+  // Flat-phase directories are keyed by phase number. A restored
+  // M003-xxxxxx row alongside M003 is a stale duplicate for the same
+  // phases/03-* projection, so checking both can compare DB status against two
+  // competing PLAN files and report a persistent false divergence.
+  const allIds = new Set(milestoneIds.map((id) => id.toUpperCase()));
+  return milestoneIds.filter((milestoneId) => {
+    const bareId = bareDuplicateMilestoneId(milestoneId);
+    return !bareId || !allIds.has(bareId);
+  });
+}
+
 function checkProjectionCheckboxDbStatus(basePath: string, milestoneIds: string[], issues: DoctorIssue[]): void {
   for (const milestoneId of milestoneIds) {
     const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
@@ -434,7 +453,9 @@ function staleMilestonesArtifactRowFixable(basePath: string, row: ArtifactRow, a
 
 function stalePhasesArtifactRowFixable(basePath: string, row: ArtifactRow, artifactRows: ArtifactRow[]): boolean {
   const issuePath = artifactPathRelativeToGsd(row.path);
-  return issuePath.startsWith(`${LAYOUT_SEGMENTS.level1}/`) && hasPresentMilestonesReplacement(basePath, row, artifactRows);
+  return issuePath.startsWith(`${LAYOUT_SEGMENTS.level1}/`) &&
+    (hasPresentFlatPhaseReplacement(basePath, row, artifactRows) ||
+      hasPresentMilestonesReplacement(basePath, row, artifactRows));
 }
 
 function staleArtifactRowFixable(basePath: string, row: ArtifactRow, artifactRows: ArtifactRow[]): boolean {
@@ -807,7 +828,11 @@ export async function checkEngineHealth(
   // block doctor.
   try {
     if (isDbAvailable()) {
-      checkProjectionCheckboxDbStatus(basePath, getAllMilestones().map((milestone) => milestone.id), issues);
+      checkProjectionCheckboxDbStatus(
+        basePath,
+        checkboxDbStatusMilestoneIds(basePath, getAllMilestones().map((milestone) => milestone.id)),
+        issues,
+      );
     }
   } catch {
     // Non-fatal: checkbox-vs-DB divergence check must never block doctor

package/src/resources/extensions/gsd/error-classifier.ts

@@ -65,8 +65,12 @@ const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|web
 // transient errors so auto-mode can retry with reduced budget or fall back to a larger-context model.
 // See: https://github.com/open-gsd/gsd-pi/issues/4528
 const SERVER_RE = /internal(?: server)?[ _-]?error|server[ _-]?error|500|502|503|overloaded|server_error|api_error|service.?unavailable|context (?:window|length) exceed|context window exceed/i;
+// Provider adapters throw this when an upstream stop reason reaches Pi before
+// the adapter knows how to map it. Keep the match scoped so plain "unknown"
+// runtime errors still pause for inspection instead of being retried forever.
+const PROVIDER_STOP_REASON_RE = /unhandled stop reason:\s*(?:abort|unknown)\b/i;
 // ECONNRESET/ECONNREFUSED are in NETWORK_RE (same-model retry first).
-const CONNECTION_RE = /terminated|connection.?(?:refused|error)|other side closed|EPIPE|network.?(?:is\s+)?unavailable|stream_exhausted(?:_without_result)?/i;
+const CONNECTION_RE = /terminated|\babort\b|connection.?(?:refused|error)|other side closed|EPIPE|network.?(?:is\s+)?unavailable|stream_exhausted(?:_without_result)?/i;
 // Catch-all for V8 JSON.parse errors: all modern variants end with "in JSON at position \d+".
 // This eliminates the need to enumerate every error message variant individually.
 const STREAM_RE = /in JSON at position \d+|Unexpected end of JSON|SyntaxError.*JSON/i;
@@ -103,7 +107,7 @@ const UNSUPPORTED_MODEL_SCOPE_RE = /\b(?:account|plan|tier|subscription)\b/i;
  *  3. Network (ECONNRESET, ETIMEDOUT, socket hang up, fetch failed, dns)
  *  4. Stream truncation (malformed JSON from mid-stream cut)
  *  5. Server (500/502/503, overloaded, server_error)
- *  6. Connection (terminated, ECONNREFUSED, EPIPE, other side closed)
+ *  6. Connection (terminated, abort/unknown stop reason, ECONNREFUSED, EPIPE, other side closed)
  *  7. Model error (400 invalid argument / payload rejected for this model)
  *  8. Unknown
  */
@@ -163,6 +167,13 @@ export function classifyError(errorMsg: string, retryAfterMs?: number): ErrorCla
     return { kind: "rate-limit", retryAfterMs: delayMs };
   }
 
+  // Provider stop-reason adapter gaps are usually request/stream failures from
+  // the current model. Treat the scoped adapter message as fallback-eligible,
+  // but keep generic unknown errors on the indefinite pause path.
+  if (PROVIDER_STOP_REASON_RE.test(errorMsg)) {
+    return { kind: "connection", retryAfterMs: retryAfterMs ?? 15_000 };
+  }
+
   // 3. Network errors — same-model retry candidate
   if (NETWORK_RE.test(errorMsg)) {
     // Exclude if also matches permanent signals (already handled above for

package/src/resources/extensions/gsd/exec-sandbox.ts

@@ -111,6 +111,7 @@ export const EXEC_DEFAULTS = {
     "LOGNAME",
     "TMPDIR",
     "NODE_OPTIONS",
+    "NODE_PATH",
     "PYTHONPATH",
     "PYTHONIOENCODING",
   ] as const,

package/src/resources/extensions/gsd/flat-phase-migration.ts

@@ -155,6 +155,19 @@ function isInsideFlatProjectionBackup(backupDir: string, src: string): boolean {
   return src === phaseBackupDir || src.startsWith(`${phaseBackupDir}/`) || src.startsWith(`${phaseBackupDir}\\`);
 }
 
+function removeFlatProjectionBackup(backupDir: string): void {
+  const phaseBackupDir = join(backupDir, "__phases");
+  if (!existsSync(phaseBackupDir)) return;
+  try {
+    removePathWithRetries(phaseBackupDir);
+  } catch (err) {
+    logWarning(
+      "migration",
+      `flat-phase migration succeeded but could not remove temporary ${LAYOUT_SEGMENTS.level1}/ backup: ${(err as Error).message}`,
+    );
+  }
+}
+
 function restoreFlatProjectionFromBackup(basePath: string, backupDir: string): void {
   const phaseBackupDir = join(backupDir, "__phases");
   if (!existsSync(phaseBackupDir)) return;
@@ -494,4 +507,5 @@ export async function migrateToFlatPhase(basePath: string): Promise<void> {
       `flat-phase migration succeeded but could not remove ${LEGACY_MIGRATING_SEGMENT}: ${(err as Error).message}`,
     );
   }
+  removeFlatProjectionBackup(backupDir);
 }

package/src/resources/extensions/gsd/gsd-db.ts

@@ -67,6 +67,13 @@ export type { SliceRow, TaskRow } from "./db-task-slice-rows.js";
 
 import { TERMINAL_STATUS_SQL } from "./db/sql-constants.js";
 import { applyStatusTransition } from "./db/writers/status.js";
+import {
+  LAYOUT_SEGMENTS,
+  derivePhaseSlug,
+  milestoneIdToPhaseNum,
+  milestoneIdUniqueSuffix,
+  phaseDirName,
+} from "./layout-policy.js";
 
 export function insertDecision(d: Omit<Decision, "seq">): void {
   if (!getDbOrNull()!) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
@@ -206,6 +213,47 @@ export function insertArtifact(a: {
   });
 }
 
+function canonicalPhaseDirNameForDb(milestoneId: string, title: string): string {
+  const phaseNum = milestoneIdToPhaseNum(milestoneId);
+  const slug = derivePhaseSlug(title || milestoneId);
+  const suffix = milestoneIdUniqueSuffix(milestoneId);
+  return phaseDirName(phaseNum, suffix ? `${suffix}-${slug}` : slug);
+}
+
+function reconcileMilestonePhaseArtifactPaths(milestoneId: string, title: string): void {
+  const db = getDbOrNull()!;
+  const phaseNumPrefix = String(milestoneIdToPhaseNum(milestoneId)).padStart(2, "0");
+  const canonicalDir = canonicalPhaseDirNameForDb(milestoneId, title);
+  const staleRows = db.prepare(
+    `SELECT path
+       FROM artifacts
+      WHERE milestone_id = :milestone_id
+        AND path LIKE :phase_prefix`,
+  ).all({
+    ":milestone_id": milestoneId,
+    ":phase_prefix": `${LAYOUT_SEGMENTS.level1}/${phaseNumPrefix}-%/%`,
+  }) as Array<{ path: string }>;
+
+  const updatePath = db.prepare("UPDATE artifacts SET path = :new_path WHERE path = :old_path");
+  const deletePath = db.prepare("DELETE FROM artifacts WHERE path = :path");
+  const existingPath = db.prepare("SELECT 1 AS present FROM artifacts WHERE path = :path");
+
+  for (const row of staleRows) {
+    const parts = row.path.split("/");
+    if (parts.length < 3) continue;
+    if (parts[0] !== LAYOUT_SEGMENTS.level1) continue;
+    if (parts[1] === canonicalDir) continue;
+    if (!parts[1]?.startsWith(`${phaseNumPrefix}-`)) continue;
+
+    const newPath = [LAYOUT_SEGMENTS.level1, canonicalDir, ...parts.slice(2)].join("/");
+    if (existingPath.get({ ":path": newPath })) {
+      deletePath.run({ ":path": row.path });
+      continue;
+    }
+    updatePath.run({ ":new_path": newPath, ":old_path": row.path });
+  }
+}
+
 export interface MilestonePlanningRecord {
   vision: string;
   successCriteria: string[];
@@ -287,39 +335,43 @@ export function insertMilestone(m: {
 
 export function upsertMilestonePlanning(milestoneId: string, planning: Partial<MilestonePlanningRecord> & { title?: string; status?: string; depends_on?: string[] }): void {
   if (!getDbOrNull()!) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
-  getDbOrNull()!.prepare(
-    `UPDATE milestones SET
-      title = COALESCE(NULLIF(:title, ''), title),
-      status = COALESCE(NULLIF(:status, ''), status),
-      depends_on = COALESCE(:depends_on, depends_on),
-      vision = COALESCE(:vision, vision),
-      success_criteria = COALESCE(:success_criteria, success_criteria),
-      key_risks = COALESCE(:key_risks, key_risks),
-      proof_strategy = COALESCE(:proof_strategy, proof_strategy),
-      verification_contract = COALESCE(:verification_contract, verification_contract),
-      verification_integration = COALESCE(:verification_integration, verification_integration),
-      verification_operational = COALESCE(:verification_operational, verification_operational),
-      verification_uat = COALESCE(:verification_uat, verification_uat),
-      definition_of_done = COALESCE(:definition_of_done, definition_of_done),
-      requirement_coverage = COALESCE(:requirement_coverage, requirement_coverage),
-      boundary_map_markdown = COALESCE(:boundary_map_markdown, boundary_map_markdown)
-     WHERE id = :id`,
-  ).run({
-    ":id": milestoneId,
-    ":title": planning.title ?? "",
-    ":status": planning.status ?? "",
-    ":depends_on": planning.depends_on ? JSON.stringify(planning.depends_on) : null,
-    ":vision": planning.vision ?? null,
-    ":success_criteria": planning.successCriteria ? JSON.stringify(planning.successCriteria) : null,
-    ":key_risks": planning.keyRisks ? JSON.stringify(planning.keyRisks) : null,
-    ":proof_strategy": planning.proofStrategy ? JSON.stringify(planning.proofStrategy) : null,
-    ":verification_contract": planning.verificationContract ?? null,
-    ":verification_integration": planning.verificationIntegration ?? null,
-    ":verification_operational": planning.verificationOperational ?? null,
-    ":verification_uat": planning.verificationUat ?? null,
-    ":definition_of_done": planning.definitionOfDone ? JSON.stringify(planning.definitionOfDone) : null,
-    ":requirement_coverage": planning.requirementCoverage ?? null,
-    ":boundary_map_markdown": planning.boundaryMapMarkdown ?? null,
+  transaction(() => {
+    getDbOrNull()!.prepare(
+      `UPDATE milestones SET
+        title = COALESCE(NULLIF(:title, ''), title),
+        status = COALESCE(NULLIF(:status, ''), status),
+        depends_on = COALESCE(:depends_on, depends_on),
+        vision = COALESCE(:vision, vision),
+        success_criteria = COALESCE(:success_criteria, success_criteria),
+        key_risks = COALESCE(:key_risks, key_risks),
+        proof_strategy = COALESCE(:proof_strategy, proof_strategy),
+        verification_contract = COALESCE(:verification_contract, verification_contract),
+        verification_integration = COALESCE(:verification_integration, verification_integration),
+        verification_operational = COALESCE(:verification_operational, verification_operational),
+        verification_uat = COALESCE(:verification_uat, verification_uat),
+        definition_of_done = COALESCE(:definition_of_done, definition_of_done),
+        requirement_coverage = COALESCE(:requirement_coverage, requirement_coverage),
+        boundary_map_markdown = COALESCE(:boundary_map_markdown, boundary_map_markdown)
+       WHERE id = :id`,
+    ).run({
+      ":id": milestoneId,
+      ":title": planning.title ?? "",
+      ":status": planning.status ?? "",
+      ":depends_on": planning.depends_on ? JSON.stringify(planning.depends_on) : null,
+      ":vision": planning.vision ?? null,
+      ":success_criteria": planning.successCriteria ? JSON.stringify(planning.successCriteria) : null,
+      ":key_risks": planning.keyRisks ? JSON.stringify(planning.keyRisks) : null,
+      ":proof_strategy": planning.proofStrategy ? JSON.stringify(planning.proofStrategy) : null,
+      ":verification_contract": planning.verificationContract ?? null,
+      ":verification_integration": planning.verificationIntegration ?? null,
+      ":verification_operational": planning.verificationOperational ?? null,
+      ":verification_uat": planning.verificationUat ?? null,
+      ":definition_of_done": planning.definitionOfDone ? JSON.stringify(planning.definitionOfDone) : null,
+      ":requirement_coverage": planning.requirementCoverage ?? null,
+      ":boundary_map_markdown": planning.boundaryMapMarkdown ?? null,
+    });
+    const finalTitle = planning.title?.trim();
+    if (finalTitle) reconcileMilestonePhaseArtifactPaths(milestoneId, finalTitle);
   });
 }
 

package/src/resources/extensions/gsd/guided-flow.ts

@@ -1282,7 +1282,7 @@ export async function buildDiscussSlicePrompt(
     : "";
 
   const inlinedTemplates = inlineTemplate("slice-context", "Slice Context");
-  return loadPrompt("guided-discuss-slice", {
+  return prependLanguageDirective(base, loadPrompt("guided-discuss-slice", {
     milestoneId: mid,
     sliceId: sid,
     sliceTitle: sTitle,
@@ -1293,7 +1293,7 @@ export async function buildDiscussSlicePrompt(
     inlinedTemplates,
     structuredQuestionsAvailable: options?.structuredQuestionsAvailable ?? "false",
     commitInstruction: buildDocsCommitInstruction(`docs(${mid}/${sid}): slice context from discuss`),
-  });
+  }));
 }
 
 /**

package/src/resources/extensions/gsd/markdown-renderer.ts

@@ -12,7 +12,7 @@
 import { readFileSync, existsSync, mkdirSync, statSync, unlinkSync } from "node:fs";
 import { logWarning } from "./workflow-logger.js";
 import { isClosedStatus } from "./status-guards.js";
-import { dirname, join, relative } from "node:path";
+import { dirname, join } from "node:path";
 import {
   getAllMilestones,
   getMilestone,
@@ -50,7 +50,7 @@ import { saveFile, clearParseCache, registerCacheClearCallback } from "./files.j
 import { parseRoadmap, parsePlan } from "./parsers-legacy.js";
 import { invalidateStateCache } from "./state.js";
 import { clearPathCache, milestonesDir, legacyMilestonesDir, isLegacyMilestonesLayout, resolveMilestonePath, relSliceFile, canonicalPhaseDirName } from "./paths.js";
-import { readCompatMarker, writeCompatMarker, computeProjectionSha } from "./compat/compat-marker.js";
+import { readCompatMarker, writeCompatMarker, computeProjectionSha, deriveCompatProjectionKey } from "./compat/compat-marker.js";
 import type { RiskLevel } from "./types.js";
 import {
   phaseDirName,
@@ -109,13 +109,7 @@ function flushProjectionWritesToMarker(): void {
  */
 function toArtifactPath(absPath: string, basePath: string): string {
   const projectionRoot = gsdProjectionRoot(basePath);
-  const projectionRel = relative(projectionRoot, absPath);
-  const root = projectionRel && !projectionRel.startsWith("..") && !projectionRel.startsWith("/")
-    ? projectionRoot
-    : gsdRoot(basePath);
-  const rel = relative(root, absPath);
-  // Normalize to forward slashes for consistent DB keys
-  return rel.replace(/\\/g, "/");
+  return deriveCompatProjectionKey(absPath, [projectionRoot, gsdRoot(basePath)]);
 }
 
 /**

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

@@ -136,6 +136,14 @@ function cachedReaddir(dirPath: string): string[] {
   return entries;
 }
 
+function isExistingFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Clear the volatile directory listing caches.
  * Call after milestone transitions, file creation in planning directories,
@@ -284,7 +292,7 @@ export function resolveFile(dir: string, idPrefix: string, suffix: string): stri
   if (!existsSync(dir)) return null;
   const target = `${idPrefix}-${suffix}.md`.toUpperCase();
   try {
-    const entries = cachedReaddir(dir);
+    const entries = cachedReaddirWithTypes(dir).filter(e => e.isFile()).map(e => e.name);
     // Direct match: ID-SUFFIX.md
     const direct = entries.find(e => e.toUpperCase() === target);
     if (direct) return direct;
@@ -311,7 +319,9 @@ export function resolveFile(dir: string, idPrefix: string, suffix: string): stri
 export function resolveTaskFiles(tasksDir: string, suffix: string): string[] {
   if (!existsSync(tasksDir)) return [];
   try {
-    return cachedReaddir(tasksDir)
+    return cachedReaddirWithTypes(tasksDir)
+      .filter(e => e.isFile())
+      .map(e => e.name)
       .filter(f => taskIdFromTaskFileName(f, suffix) !== null)
       .sort();
   } catch {
@@ -860,7 +870,7 @@ export function resolveMilestoneFile(
   const prefix = `${String(phaseNum).padStart(2, "0")}`;
   const flatName = `${prefix}-${suffix}.md`;
   const flatPath = join(mDir, flatName);
-  if (existsSync(flatPath)) return flatPath;
+  if (isExistingFile(flatPath)) return flatPath;
   // Legacy fallback: M001-SUFFIX.md
   const file = resolveFile(mDir, milestoneId, suffix);
   return file ? join(mDir, file) : null;
@@ -895,11 +905,11 @@ export function resolveSliceFile(
   const planNum = sliceIdToPlanNum(sliceId);
   const flatName = planFileName(phaseNum, planNum, suffix);
   const flatPath = join(phaseDir, flatName);
-  if (existsSync(flatPath)) return flatPath;
+  if (isExistingFile(flatPath)) return flatPath;
   // Also check plan-number-only format MM-SUFFIX.md (written by buildSliceFileName)
   const planOnlyName = `${String(planNum).padStart(2, "0")}-${suffix}.md`;
   const planOnlyPath = join(phaseDir, planOnlyName);
-  if (existsSync(planOnlyPath)) return planOnlyPath;
+  if (isExistingFile(planOnlyPath)) return planOnlyPath;
   // Try prefix match for the phase+plan number (handles suffix variations)
   const planPrefix = `${String(phaseNum).padStart(2, "0")}-${String(planNum).padStart(2, "0")}-`;
   try {
@@ -949,9 +959,9 @@ export function resolveTaskFile(
 
   if (suffix !== "PLAN" && !isLegacy) {
     const flatPath = join(phaseDir, buildFlatTaskFileName(sliceId, taskId, suffix));
-    if (existsSync(flatPath)) return flatPath;
+    if (isExistingFile(flatPath)) return flatPath;
     const legacyFlatPath = join(phaseDir, buildTaskFileName(taskId, suffix));
-    return existsSync(legacyFlatPath) ? legacyFlatPath : null;
+    return isExistingFile(legacyFlatPath) ? legacyFlatPath : null;
   }
 
   const tDir = resolveTasksDir(basePath, milestoneId, sliceId);

package/src/resources/extensions/gsd/prompts/validate-milestone.md

@@ -24,18 +24,18 @@ Roadmap, slice summaries, assessments, requirements, decisions, and project cont
 
 ### Step 1 - Dispatch Parallel Reviewers
 
-The Inlined Context above already preloads the evidence reviewers need — the roadmap, per-slice SUMMARY/ASSESSMENT excerpts, requirements, and verification classes. **Embed the relevant preloaded evidence directly into each reviewer's task prompt** so reviewers work from it instead of re-reading the same artifacts from disk. Each reviewer should read a full file only when its excerpt is missing, truncated, or internally inconsistent — never as a routine first step. This avoids three reviewers independently re-surveying artifacts the orchestrator already holds.
+The Inlined Context above already preloads the evidence reviewers need — the roadmap, per-slice SUMMARY/ASSESSMENT excerpts, requirements, and verification classes. **Embed the relevant preloaded evidence directly into each reviewer's task prompt** so reviewers work from it instead of re-reading the same artifacts from disk. Each reviewer should read a full file only when its excerpt is missing, truncated, or internally inconsistent — never as a routine first step. When a reviewer needs a full artifact, use only explicit file paths from the On-demand Validation Artifacts / On-demand Milestone Context blocks or discover files with `find .gsd -type f`; never pass a phase, slice, `tasks/`, or `slices/` directory to `read` or `readFileSync`. This avoids three reviewers independently re-surveying artifacts the orchestrator already holds.
 
 Call `subagent` with `tasks: [...]` containing ALL THREE reviewers simultaneously:
 
 **Reviewer A - Requirements Coverage**
-Prompt: "Review milestone {{milestoneId}} requirements coverage. Working directory: {{workingDirectory}}. Use the preloaded requirements and slice SUMMARY evidence embedded in this task — do not re-read them from disk. For each requirement, mark COVERED, PARTIAL, or MISSING against that evidence. Read a full SUMMARY under `.gsd/milestones/{{milestoneId}}/slices/` only if its preloaded excerpt is missing, truncated, or inconsistent. Output table: Requirement | Status | Evidence. End with one-line verdict: PASS if all covered, NEEDS-ATTENTION if partials exist, FAIL if any missing."
+Prompt: "Review milestone {{milestoneId}} requirements coverage. Working directory: {{workingDirectory}}. Use the preloaded requirements and slice SUMMARY evidence embedded in this task — do not re-read them from disk. For each requirement, mark COVERED, PARTIAL, or MISSING against that evidence. Read a full SUMMARY only from an explicit file path in the On-demand Validation Artifacts list, or discover candidates with `find .gsd -type f -name '*-SUMMARY.md'`; never read a directory path. Output table: Requirement | Status | Evidence. End with one-line verdict: PASS if all covered, NEEDS-ATTENTION if partials exist, FAIL if any missing."
 
 **Reviewer B - Cross-Slice Integration**
-Prompt: "Review milestone {{milestoneId}} cross-slice integration. Working directory: {{workingDirectory}}. Use the preloaded roadmap and slice SUMMARY evidence embedded in this task — do not re-read them from disk. Find the boundary map (produces/consumes contracts) in the roadmap. For each boundary, confirm producer SUMMARY produced the artifact and consumer SUMMARY consumed it. Read `{{roadmapPath}}` or a full SUMMARY only if the preloaded evidence is missing, truncated, or inconsistent. Output table: Boundary | Producer Summary | Consumer Summary | Status. End with one-line verdict: PASS if all boundaries honored, NEEDS-ATTENTION if any gaps."
+Prompt: "Review milestone {{milestoneId}} cross-slice integration. Working directory: {{workingDirectory}}. Use the preloaded roadmap and slice SUMMARY evidence embedded in this task — do not re-read them from disk. Find the boundary map (produces/consumes contracts) in the roadmap. For each boundary, confirm producer SUMMARY produced the artifact and consumer SUMMARY consumed it. Read `{{roadmapPath}}` or a full SUMMARY from the On-demand Validation Artifacts list only if the preloaded evidence is missing, truncated, or inconsistent; never read a directory path. Output table: Boundary | Producer Summary | Consumer Summary | Status. End with one-line verdict: PASS if all boundaries honored, NEEDS-ATTENTION if any gaps."
 
 **Reviewer C - Assessment & Acceptance Criteria**
-Prompt: "Review milestone {{milestoneId}} assessment evidence and acceptance criteria. Working directory: {{workingDirectory}}. Use the preloaded milestone context, slice SUMMARY, and ASSESSMENT evidence embedded in this task — do not re-read them from disk. Read `.gsd/milestones/{{milestoneId}}/{{milestoneId}}-CONTEXT.md`, a full SUMMARY, or a full ASSESSMENT only if the preloaded excerpt is missing, truncated, or inconsistent. UAT files are specs, not evidence. Verify each criterion maps to passing evidence. Then review the inlined `Verification Classes (from planning)` table. For every planned row in that table, output a `Verification Classes` table with columns `Class | Planned Check | Evidence | Verdict`. Preserve every planned non-empty class row; do not summarize, rename, combine, or omit planned classes. The first cell of each row must be exactly `Contract`, `Integration`, `Operational`, or `UAT` when that class is present in planning. If a planned class lacks evidence, still include its canonical row and mark the verdict NEEDS-ATTENTION or FAIL. If a planned browser/UAT class has no ASSESSMENT with browser/runtime actions and assertions, return NEEDS-ATTENTION. If no verification classes were planned, say that explicitly. Output sections `Acceptance Criteria` with checklist `[ ] Criterion | Evidence`, and `Verification Classes` with the table. End with one-line verdict: PASS if all criteria and classes are covered by evidence, NEEDS-ATTENTION if gaps exist."
+Prompt: "Review milestone {{milestoneId}} assessment evidence and acceptance criteria. Working directory: {{workingDirectory}}. Use the preloaded milestone context, slice SUMMARY, and ASSESSMENT evidence embedded in this task — do not re-read them from disk. Read the milestone context from the On-demand Milestone Context file path, and read full SUMMARY or ASSESSMENT files only from explicit paths in the On-demand Validation Artifacts list, if the preloaded excerpt is missing, truncated, or inconsistent. UAT files are specs, not evidence. Verify each criterion maps to passing evidence. Then review the inlined `Verification Classes (from planning)` table. For every planned row in that table, output a `Verification Classes` table with columns `Class | Planned Check | Evidence | Verdict`. Preserve every planned non-empty class row; do not summarize, rename, combine, or omit planned classes. The first cell of each row must be exactly `Contract`, `Integration`, `Operational`, or `UAT` when that class is present in planning. If a planned class lacks evidence, still include its canonical row and mark the verdict NEEDS-ATTENTION or FAIL. If a planned browser/UAT class has no ASSESSMENT with browser/runtime actions and assertions, return NEEDS-ATTENTION. If no verification classes were planned, say that explicitly. Output sections `Acceptance Criteria` with checklist `[ ] Criterion | Evidence`, and `Verification Classes` with the table. End with one-line verdict: PASS if all criteria and classes are covered by evidence, NEEDS-ATTENTION if gaps exist."
 
 ### Step 2 - Synthesize Findings
 
@@ -85,6 +85,6 @@ If verdict is `needs-remediation`:
 
 **You MUST call `gsd_validate_milestone` before finishing. Do not manually write `{{validationPath}}`.**
 
-**File system safety:** When scanning milestone directories, use `ls` or `find` first. Never pass a directory path such as `tasks/` or `slices/` directly to `read`; it only accepts files.
+**File system safety:** When scanning milestone directories, use `find .gsd -type f` first and read only files. In flat-phase projects, `.gsd/phases/<NN>-<slug>/` is a directory, not an artifact. Never pass a directory path such as a phase directory, `tasks/`, or `slices/` directly to `read`, `readFile`, or `readFileSync`.
 
 When done, say: "Milestone {{milestoneId}} validation complete — verdict: <verdict>." Say this exactly once — if you already said it in a prior message, do not repeat it.