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

package/dist/resources/extensions/gsd/compat/compat-marker.js

@@ -5,8 +5,8 @@
 // distinguish gsd-pi's own writes (expected) from external edits made by gsd-core
 // (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;
 /** Marker returned when no marker exists yet (fresh project, first gsd-pi run). */
@@ -32,6 +32,35 @@ export function normalizeForHash(content) {
 export function computeProjectionSha(content) {
     return createHash("sha256").update(normalizeForHash(content)).digest("hex").slice(0, 16);
 }
+function normalizeRealPath(p) {
+    try {
+        return realpathSync.native(p);
+    }
+    catch {
+        return resolve(p);
+    }
+}
+function rootRelativeKey(rootPath, absPath) {
+    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) {
+    return rel.includes("\\") ? "\\" : "/";
+}
+export function deriveCompatProjectionKey(absPath, roots) {
+    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
@@ -39,7 +68,9 @@ export function computeProjectionSha(content) {
  * 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) {
+export function readCompatMarker(basePath, options = {}) {
+    const healInvalidKeys = options.healInvalidKeys ?? true;
+    const quarantineInvalid = options.quarantineInvalid ?? true;
     const path = compatMarkerPath(basePath);
     if (!existsSync(path))
         return emptyMarker();
@@ -55,11 +86,16 @@ export function readCompatMarker(basePath) {
         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
@@ -196,6 +232,45 @@ function isValidProjectionMap(x) {
     }
     return true;
 }
+function healMarkerProjectionKeys(basePath, marker) {
+    if (typeof marker !== "object" || marker === null)
+        return false;
+    const m = marker;
+    let changed = false;
+    if (typeof m.projections === "object" && m.projections !== null) {
+        changed = healProjectionMapKeys(basePath, ".gsd", m.projections) || changed;
+    }
+    const planning = m.planning;
+    if (typeof planning === "object" && planning !== null) {
+        const p = planning;
+        if (typeof p.projections === "object" && p.projections !== null) {
+            changed = healProjectionMapKeys(basePath, ".planning", p.projections) || changed;
+        }
+        if (typeof p.passthrough === "object" && p.passthrough !== null) {
+            changed = healProjectionMapKeys(basePath, ".planning", p.passthrough) || changed;
+        }
+    }
+    return changed;
+}
+function healProjectionMapKeys(basePath, rootName, map) {
+    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) {
     if (typeof x !== "object" || x === null)
         return false;

package/dist/resources/extensions/gsd/db/engine.js

@@ -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 { logError, logWarning } from "../workflow-logger.js";
 import { createDbAdapter } from "../db-adapter.js";
@@ -31,7 +31,10 @@ function getGsdRequire() {
     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/dist/resources/extensions/gsd/doctor-engine-checks.js

@@ -58,6 +58,23 @@ function reportCheckboxDbStatusDivergence(issues, basePath, filePath, scope, uni
         fixable: false,
     });
 }
+function bareDuplicateMilestoneId(milestoneId) {
+    const match = milestoneId.match(/^(M\d{3})-[a-z0-9]{6}$/i);
+    return match?.[1]?.toUpperCase() ?? null;
+}
+function checkboxDbStatusMilestoneIds(basePath, milestoneIds) {
+    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, milestoneIds, issues) {
     for (const milestoneId of milestoneIds) {
         const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
@@ -322,7 +339,9 @@ function staleMilestonesArtifactRowFixable(basePath, row, artifactRows) {
 }
 function stalePhasesArtifactRowFixable(basePath, row, artifactRows) {
     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, row, artifactRows) {
     return staleMilestonesArtifactRowFixable(basePath, row, artifactRows) ||
@@ -658,7 +677,7 @@ export async function checkEngineHealth(basePath, issues, fixesApplied, options)
     // block doctor.
     try {
         if (isDbAvailable()) {
-            checkProjectionCheckboxDbStatus(basePath, getAllMilestones().map((milestone) => milestone.id), issues);
+            checkProjectionCheckboxDbStatus(basePath, checkboxDbStatusMilestoneIds(basePath, getAllMilestones().map((milestone) => milestone.id)), issues);
         }
     }
     catch {

package/dist/resources/extensions/gsd/error-classifier.js

@@ -38,8 +38,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;
@@ -72,7 +76,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
  */
@@ -124,6 +128,12 @@ export function classifyError(errorMsg, retryAfterMs) {
         const delayMs = resetMatch ? Number(resetMatch[1]) * 1000 : 60_000;
         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/dist/resources/extensions/gsd/exec-sandbox.js

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

package/dist/resources/extensions/gsd/flat-phase-migration.js

@@ -130,6 +130,17 @@ function isInsideFlatProjectionBackup(backupDir, src) {
     const phaseBackupDir = join(backupDir, "__phases");
     return src === phaseBackupDir || src.startsWith(`${phaseBackupDir}/`) || src.startsWith(`${phaseBackupDir}\\`);
 }
+function removeFlatProjectionBackup(backupDir) {
+    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.message}`);
+    }
+}
 function restoreFlatProjectionFromBackup(basePath, backupDir) {
     const phaseBackupDir = join(backupDir, "__phases");
     if (!existsSync(phaseBackupDir))
@@ -433,4 +444,5 @@ export async function migrateToFlatPhase(basePath) {
     catch (err) {
         logWarning("migration", `flat-phase migration succeeded but could not remove ${LEGACY_MIGRATING_SEGMENT}: ${err.message}`);
     }
+    removeFlatProjectionBackup(backupDir);
 }

package/dist/resources/extensions/gsd/gsd-db.js

@@ -38,6 +38,7 @@ export * from "./db/queries.js";
 export * from "./db/writers/cascades.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) {
     if (!getDbOrNull())
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
@@ -169,6 +170,44 @@ export function insertArtifact(a) {
         ":content_hash": contentHash,
     });
 }
+function canonicalPhaseDirNameForDb(milestoneId, title) {
+    const phaseNum = milestoneIdToPhaseNum(milestoneId);
+    const slug = derivePhaseSlug(title || milestoneId);
+    const suffix = milestoneIdUniqueSuffix(milestoneId);
+    return phaseDirName(phaseNum, suffix ? `${suffix}-${slug}` : slug);
+}
+function reconcileMilestonePhaseArtifactPaths(milestoneId, title) {
+    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}-%/%`,
+    });
+    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 function insertMilestone(m) {
     if (!getDbOrNull())
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
@@ -207,37 +246,42 @@ export function insertMilestone(m) {
 export function upsertMilestonePlanning(milestoneId, planning) {
     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);
     });
 }
 export function insertSlice(s) {

package/dist/resources/extensions/gsd/guided-flow.js

@@ -922,7 +922,7 @@ export async function buildDiscussSlicePrompt(mid, sid, sTitle, base, options) {
         ? `\n\n## Re-discuss Mode\n\nThis slice already has an existing context file (\`${sliceContextPath}\`) from a prior discussion. The user has chosen to re-discuss it. Read the existing context file, interview for any updates, changes, or new decisions, and rewrite the file with merged findings. Do NOT skip the interview — the user explicitly asked to revisit this slice.\n`
         : "";
     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,
@@ -933,7 +933,7 @@ export async function buildDiscussSlicePrompt(mid, sid, sTitle, base, options) {
         inlinedTemplates,
         structuredQuestionsAvailable: options?.structuredQuestionsAvailable ?? "false",
         commitInstruction: buildDocsCommitInstruction(`docs(${mid}/${sid}): slice context from discuss`),
-    });
+    }));
 }
 /**
  * /gsd discuss — show a picker of non-done slices and run a slice interview.

package/dist/resources/extensions/gsd/markdown-renderer.js

@@ -11,14 +11,14 @@
 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, getMilestoneScopedArtifacts, getSliceScopedArtifacts, getMilestoneSlices, getSliceTasks, getTasksBySliceIds, getTask, getSlice, insertArtifact, deleteArtifactByPath, getGateResults, isDbAvailable, } from "./gsd-db.js";
 import { resolveDir, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, targetMilestoneFile, targetSliceFile, targetTaskFile, gsdProjectionRoot, gsdRoot, buildTaskFileName, } from "./paths.js";
 import { saveFile, clearParseCache, registerCacheClearCallback } from "./files.js";
 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";
 // ─── Compat marker invalidation ───────────────────────────────────────────
 // Every successful projection write pushes its (basePath, projectionPath,
 // entities) here; invalidateCaches() drains it and refreshes .gsd/.compat.json
@@ -71,13 +71,7 @@ function flushProjectionWritesToMarker() {
  */
 function toArtifactPath(absPath, basePath) {
     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)]);
 }
 /**
  * Invalidate all caches after a disk write.

package/dist/resources/extensions/gsd/paths.js

@@ -122,6 +122,14 @@ function cachedReaddir(dirPath) {
     dirListCache.set(dirPath, entries);
     return entries;
 }
+function isExistingFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Clear the volatile directory listing caches.
  * Call after milestone transitions, file creation in planning directories,
@@ -257,7 +265,7 @@ export function resolveFile(dir, idPrefix, suffix) {
         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)
@@ -286,7 +294,9 @@ export function resolveTaskFiles(tasksDir, suffix) {
     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();
     }
@@ -826,7 +836,7 @@ export function resolveMilestoneFile(basePath, milestoneId, suffix) {
     const prefix = `${String(phaseNum).padStart(2, "0")}`;
     const flatName = `${prefix}-${suffix}.md`;
     const flatPath = join(mDir, flatName);
-    if (existsSync(flatPath))
+    if (isExistingFile(flatPath))
         return flatPath;
     // Legacy fallback: M001-SUFFIX.md
     const file = resolveFile(mDir, milestoneId, suffix);
@@ -859,12 +869,12 @@ export function resolveSliceFile(basePath, milestoneId, sliceId, suffix) {
     const planNum = sliceIdToPlanNum(sliceId);
     const flatName = planFileName(phaseNum, planNum, suffix);
     const flatPath = join(phaseDir, flatName);
-    if (existsSync(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))
+    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")}-`;
@@ -910,10 +920,10 @@ export function resolveTaskFile(basePath, milestoneId, sliceId, taskId, suffix)
     const isLegacy = phaseDir.startsWith(legacyBase + "/") || phaseDir.startsWith(legacyBase + "\\");
     if (suffix !== "PLAN" && !isLegacy) {
         const flatPath = join(phaseDir, buildFlatTaskFileName(sliceId, taskId, suffix));
-        if (existsSync(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);
     if (tDir) {

package/dist/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.