@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.72e3af2a

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

@@ -9,14 +9,15 @@
  * (e.g. M001-FLIGHT-SIMULATOR/, T03-INSTALL-PACKAGES-PLAN.md)
  * via prefix matching, so existing projects work without migration.
  */
-import { readdirSync, existsSync, realpathSync, Dirent } from "node:fs";
+import { readdirSync, existsSync, realpathSync, statSync, Dirent } from "node:fs";
 import { join, dirname, normalize, resolve } from "node:path";
 import { homedir } from "node:os";
 import { spawnSync } from "node:child_process";
 import { nativeScanGsdTree } from "./native-parser-bridge.js";
 import { DIR_CACHE_MAX } from "./constants.js";
 import { gsdHome } from "./gsd-home.js";
-import { isGsdWorktreePath, resolveExternalStateProjectGsdFromWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
+import { findWorktreeSegment, isGsdWorktreePath, resolveExternalStateProjectGsdFromWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
+import { LAYOUT_SEGMENTS, phaseDirName, planFileName, milestoneIdToPhaseNum, milestoneIdUniqueSuffix, sliceIdToPlanNum, derivePhaseSlug, } from "./layout-policy.js";
 // ─── Directory Listing Cache ──────────────────────────────────────────────────
 const dirEntryCache = new Map();
 const dirListCache = new Map();
@@ -139,19 +140,53 @@ export function clearPathCache() {
     nativeTreeBase = null;
 }
 // ─── Name Builders ─────────────────────────────────────────────────────────
+/** Directories owned by the GSD framework — metadata, never project source. */
+export const FRAMEWORK_METADATA_DIRS = [".gsd", ".planning", ".audits"];
+/**
+ * Every artifact suffix used with the name builders below — the single source
+ * for the `<ID>-<SUFFIX>.md` naming vocabulary. Extend this list when a new
+ * artifact type is introduced; consumers (md-importer walking, pre-execution
+ * artifact detection) pick it up from here.
+ */
+export const PLANNING_ARTIFACT_SUFFIXES = [
+    "CONTEXT",
+    "CONTEXT-DRAFT",
+    "ROADMAP",
+    "PLAN",
+    "REPLAN",
+    "SUMMARY",
+    "RESEARCH",
+    "VALIDATION",
+    "ASSESSMENT",
+    "UAT",
+    "DISCUSSION",
+    "EVAL-REVIEW",
+    "PARKED",
+    "VERIFICATION-FAILED",
+    "CONTINUE",
+];
+/** Matches a bare planning-artifact file name, e.g. "M001-CONTEXT.md", "S01-PLAN.md". */
+export const PLANNING_ARTIFACT_NAME_RE = new RegExp(`^[MST]\\d+-(${PLANNING_ARTIFACT_SUFFIXES.join("|")})\\.md$`, "i");
 /**
  * Build a milestone-level file name.
  * ("M001", "CONTEXT") → "M001-CONTEXT.md"
  */
 export function buildMilestoneFileName(milestoneId, suffix) {
-    return `${milestoneId}-${suffix}.md`;
+    // Flat-phase: phase-level files are NN-SUFFIX.md (e.g. "01-CONTEXT.md")
+    const phaseNum = milestoneIdToPhaseNum(milestoneId);
+    return `${String(phaseNum).padStart(2, "0")}-${suffix}.md`;
 }
 /**
  * Build a slice-level file name.
  * ("S01", "PLAN") → "S01-PLAN.md"
  */
 export function buildSliceFileName(sliceId, suffix) {
-    return `${sliceId}-${suffix}.md`;
+    // Flat-phase: plan files need both phase and plan numbers (NN-MM-SUFFIX.md),
+    // but this helper only has the sliceId. Callers needing the full name should
+    // use planFileName() from layout-policy. This returns MM-SUFFIX.md for any
+    // incremental callers that haven't migrated yet.
+    const planNum = sliceIdToPlanNum(sliceId);
+    return `${String(planNum).padStart(2, "0")}-${suffix}.md`;
 }
 /**
  * Build a task file name.
@@ -159,6 +194,8 @@ export function buildSliceFileName(sliceId, suffix) {
  * ("T03", "SUMMARY") → "T03-SUMMARY.md"
  */
 export function buildTaskFileName(taskId, suffix) {
+    // Flat-phase: tasks are checkboxes inside plan files, not separate files.
+    // This helper is deprecated but kept for backward-compat callers.
     return `${taskId}-${suffix}.md`;
 }
 // ─── Resolvers ─────────────────────────────────────────────────────────────
@@ -422,31 +459,17 @@ function assertNotGlobalGsdHome(basePath, result) {
  * When gsdRoot() is called with such a path, we must NOT walk up to the
  * project root's .gsd — each worktree manages its own .gsd state (#2594).
  *
- * Matches both forward-slash and platform-native separators to handle
- * Windows paths (path.sep = '\\') and normalized Unix paths.
+ * Layout matching is owned by worktree-root's findWorktreeSegment; this
+ * only adds the requirement that a non-empty worktree name follows the
+ * marker (the worktrees container dir itself is not a worktree).
  */
 function isInsideGsdWorktree(p) {
-    // Match /.gsd/worktrees/<name> where <name> is the final segment or
-    // followed by a separator. The <name> segment must be non-empty.
-    const sepFwd = "/";
-    const sepNative = "\\";
-    const markers = [
-        `${sepFwd}.gsd${sepFwd}worktrees${sepFwd}`,
-        `${sepNative}.gsd${sepNative}worktrees${sepNative}`,
-    ];
-    for (const marker of markers) {
-        const idx = p.indexOf(marker);
-        if (idx === -1)
-            continue;
-        // Verify there's a non-empty worktree name after the marker
-        const afterMarker = p.slice(idx + marker.length);
-        // The name is everything up to the next separator (or end of string)
-        const nameEnd = afterMarker.search(/[/\\]/);
-        const name = nameEnd === -1 ? afterMarker : afterMarker.slice(0, nameEnd);
-        if (name.length > 0)
-            return true;
-    }
-    return false;
+    const normalized = p.replaceAll("\\", "/");
+    const segment = findWorktreeSegment(normalized);
+    if (!segment)
+        return false;
+    const name = normalized.slice(segment.afterWorktrees).split("/")[0];
+    return name.length > 0;
 }
 function probeGsdRoot(rawBasePath) {
     const contract = resolveGsdPathContract(rawBasePath);
@@ -533,9 +556,188 @@ function probeGsdRoot(rawBasePath) {
     // 4. Fallback for init/creation
     return local;
 }
+function legacyMilestonesHasSubdirs(basePath) {
+    const legacy = join(gsdProjectionRoot(basePath), "milestones");
+    if (!existsSync(legacy))
+        return false;
+    try {
+        return readdirSync(legacy).some(e => statSync(join(legacy, e)).isDirectory() && dirIsContentBearingLegacyMilestone(join(legacy, e)));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A `milestones/<MID>/` directory is only a real legacy layout entry if it
+ * contains content files (CONTEXT/ROADMAP/SUMMARY/…). git-service.ts creates
+ * `milestones/<MID>/` to store the integration-branch metadata
+ * (`<MID>-META.json`) even in flat-phase projects, so a directory holding only
+ * `*-META.json` must NOT count as legacy — otherwise layout detection flips to
+ * legacy and artifact verification resolves to the wrong path
+ * (`milestones/<MID>/<MID>-CONTEXT.md` instead of `phases/NN-slug/NN-CONTEXT.md`),
+ * trapping the unit in a finalize-retry loop (#852 follow-up).
+ *
+ * See the matching TODO in markdown-renderer.ts detectStaleRenders, which
+ * disabled stale-render detection for the same reason.
+ */
+export function dirIsContentBearingLegacyMilestone(dir) {
+    try {
+        const entries = readdirSync(dir, { withFileTypes: true });
+        // 1. Any non-META regular file → real legacy content.
+        if (entries.some(e => e.isFile() && !e.name.endsWith("-META.json")))
+            return true;
+        // 2. A non-empty subdirectory → real legacy content (e.g. slices/ with slice dirs).
+        //    An *empty* subdir is treated as scaffolding (e.g. git-service.ts may create
+        //    an empty slices/ alongside the integration META file) and must NOT flip the
+        //    layout — that is the Bugbot finding this guard addresses.
+        return entries.some(e => {
+            if (!e.isDirectory())
+                return false;
+            try {
+                return readdirSync(join(dir, e.name)).length > 0;
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Returns true iff the directory exists, is non-empty, and ALL entries are
+ * `*-META.json` files (git-service integration-branch metadata pollution in a
+ * flat-phase project). Used by resolveProjectMilestonePath to skip dirs that
+ * only hold metadata — not as a layout-detection guard.
+ *
+ * Deliberately distinct from dirIsContentBearingLegacyMilestone: an EMPTY dir
+ * (new milestone, no content written yet) returns false here because it is not
+ * META-only — it is a valid placeholder that a writer may target.
+ */
+export function dirIsMetaOnlyLegacyMilestone(dir) {
+    try {
+        const entries = readdirSync(dir);
+        if (entries.length === 0)
+            return false; // empty = not META-only
+        return entries.every(name => name.endsWith("-META.json"));
+    }
+    catch {
+        return false;
+    }
+}
+export function isLegacyMilestonesLayout(basePath) {
+    return legacyMilestonesHasSubdirs(basePath);
+}
 export function milestonesDir(basePath) {
+    // Layout-aware: return milestones/ when it has legacy content, otherwise phases/.
+    const root = gsdProjectionRoot(basePath);
+    if (legacyMilestonesHasSubdirs(basePath)) {
+        return join(root, "milestones");
+    }
+    return join(root, LAYOUT_SEGMENTS.level1);
+}
+/**
+ * Legacy milestones directory (pre-flat-phase). Used as a fallback for
+ * projects that haven't been migrated yet. The migration (flat-phase-migration.ts)
+ * moves content from here to phases/ on startup.
+ */
+export function legacyMilestonesDir(basePath) {
     return join(gsdProjectionRoot(basePath), "milestones");
 }
+/**
+ * Resolve a phase directory by milestone id using the flat-phase layout.
+ * Scans phases/ for a dir whose zero-padded number prefix matches the milestone.
+ * Returns the full path or null if not found.
+ */
+function pickPreferredPhaseDir(phasesDir, matches) {
+    if (matches.length === 1)
+        return matches[0];
+    let best = matches[0];
+    let bestMtime = -1;
+    for (const name of matches) {
+        try {
+            const mtime = statSync(join(phasesDir, name)).mtimeMs;
+            if (mtime > bestMtime) {
+                bestMtime = mtime;
+                best = name;
+            }
+        }
+        catch {
+            // unreadable — keep prior best
+        }
+    }
+    return best;
+}
+function phaseDirMatchesMilestoneId(dirName, milestoneId, phaseNum) {
+    const numMatch = dirName.match(/^(\d+)-(.*)$/);
+    if (!numMatch || parseInt(numMatch[1], 10) !== phaseNum)
+        return false;
+    const slugPart = numMatch[2];
+    const suffix = milestoneIdUniqueSuffix(milestoneId);
+    if (suffix) {
+        return slugPart === suffix || slugPart.startsWith(`${suffix}-`);
+    }
+    // Plain sequential IDs must not resolve to unique-suffix phase dirs.
+    return !/^[a-z0-9]{6}(-|$)/.test(slugPart);
+}
+function resolvePhaseDir(basePath, milestoneId) {
+    // Try flat-phase layout first: phases/NN-slug/ (always scan phases/, even when
+    // legacy milestones/ coexists during partial migration).
+    const phasesDir = join(gsdProjectionRoot(basePath), LAYOUT_SEGMENTS.level1);
+    if (existsSync(phasesDir)) {
+        const phaseNum = milestoneIdToPhaseNum(milestoneId);
+        const canonical = canonicalPhaseDirName(milestoneId);
+        if (existsSync(join(phasesDir, canonical))) {
+            return join(phasesDir, canonical);
+        }
+        const matches = [];
+        try {
+            for (const entry of readdirSync(phasesDir, { withFileTypes: true })) {
+                if (!entry.isDirectory())
+                    continue;
+                if (phaseDirMatchesMilestoneId(entry.name, milestoneId, phaseNum)) {
+                    matches.push(entry.name);
+                }
+            }
+        }
+        catch {
+            // unreadable — fall through
+        }
+        if (matches.length > 0) {
+            const preferred = matches.includes(canonical)
+                ? canonical
+                : pickPreferredPhaseDir(phasesDir, matches);
+            return join(phasesDir, preferred);
+        }
+    }
+    // Legacy fallback: milestones/M001/ (pre-flat-phase layout). Only consider a
+    // milestone dir legacy if it actually carries content — git-service.ts creates
+    // milestones/<MID>/ for integration-branch metadata even in flat-phase
+    // projects, so a metadata-only dir must not flip the layout (#852 follow-up).
+    const legacyDir = legacyMilestonesDir(basePath);
+    if (existsSync(legacyDir)) {
+        const candidate = resolveDir(legacyDir, milestoneId);
+        if (candidate && dirIsContentBearingLegacyMilestone(join(legacyDir, candidate))) {
+            return join(legacyDir, candidate);
+        }
+    }
+    return null;
+}
+/**
+ * Derive the canonical phase dir name for a milestone when it doesn't exist yet.
+ * Used by the renderer to create new phase dirs, and by ensurePreconditions to
+ * scaffold the correct NN-slug directory on disk before the first render.
+ */
+export function canonicalPhaseDirName(milestoneId, title) {
+    const phaseNum = milestoneIdToPhaseNum(milestoneId);
+    const slug = derivePhaseSlug(title || milestoneId);
+    const suffix = milestoneIdUniqueSuffix(milestoneId);
+    if (suffix) {
+        return phaseDirName(phaseNum, `${suffix}-${slug}`);
+    }
+    return phaseDirName(phaseNum, slug);
+}
 export function resolveRuntimeFile(basePath) {
     return join(gsdRoot(basePath), "RUNTIME.md");
 }
@@ -557,8 +759,22 @@ export function relGsdRootFile(key) {
  * Returns null if the milestone doesn't exist.
  */
 export function resolveMilestonePath(basePath, milestoneId) {
-    const dir = resolveDir(milestonesDir(basePath), milestoneId);
-    return dir ? join(milestonesDir(basePath), dir) : null;
+    // Flat-phase: scan phases/ for NN-slug dir matching the milestone number.
+    const phaseDir = resolvePhaseDir(basePath, milestoneId);
+    if (phaseDir)
+        return phaseDir;
+    // Legacy fallback: try old milestones/ dir (pre-flat-phase layout). Same
+    // content-bearing guard as resolvePhaseDir — a metadata-only milestones/<MID>/
+    // (created by git-service.ts for the integration branch) must not be treated
+    // as a real legacy milestone dir (#852 follow-up).
+    const oldMilestonesDir = join(gsdProjectionRoot(basePath), "milestones");
+    if (existsSync(oldMilestonesDir)) {
+        const legacyDir = resolveDir(oldMilestonesDir, milestoneId);
+        if (legacyDir && dirIsContentBearingLegacyMilestone(join(oldMilestonesDir, legacyDir))) {
+            return join(oldMilestonesDir, legacyDir);
+        }
+    }
+    return null;
 }
 /**
  * Resolve the full path to a milestone file (e.g. ROADMAP, CONTEXT, RESEARCH).
@@ -567,6 +783,14 @@ export function resolveMilestoneFile(basePath, milestoneId, suffix) {
     const mDir = resolveMilestonePath(basePath, milestoneId);
     if (!mDir)
         return null;
+    // Flat-phase: phase-level files are NN-SUFFIX.md (e.g. 01-CONTEXT.md)
+    const phaseNum = milestoneIdToPhaseNum(milestoneId);
+    const prefix = `${String(phaseNum).padStart(2, "0")}`;
+    const flatName = `${prefix}-${suffix}.md`;
+    const flatPath = join(mDir, flatName);
+    if (existsSync(flatPath))
+        return flatPath;
+    // Legacy fallback: M001-SUFFIX.md
     const file = resolveFile(mDir, milestoneId, suffix);
     return file ? join(mDir, file) : null;
 }
@@ -577,24 +801,60 @@ export function resolveSlicePath(basePath, milestoneId, sliceId) {
     const mDir = resolveMilestonePath(basePath, milestoneId);
     if (!mDir)
         return null;
+    // Legacy: slice files live under slices/SID/ when that subdir exists.
     const slicesDir = join(mDir, "slices");
     const dir = resolveDir(slicesDir, sliceId);
-    return dir ? join(slicesDir, dir) : null;
+    if (dir)
+        return join(slicesDir, dir);
+    // Flat-phase: plans are files inside the phase dir, not subdirs.
+    return mDir;
 }
 /**
  * Resolve the full path to a slice file (e.g. PLAN, RESEARCH, CONTEXT, SUMMARY).
  */
 export function resolveSliceFile(basePath, milestoneId, sliceId, suffix) {
-    const sDir = resolveSlicePath(basePath, milestoneId, sliceId);
-    if (!sDir)
+    const phaseDir = resolveMilestonePath(basePath, milestoneId);
+    if (!phaseDir)
         return null;
-    const file = resolveFile(sDir, sliceId, suffix);
-    return file ? join(sDir, file) : null;
+    // Flat-phase: plan files are NN-MM-SUFFIX.md inside the phase dir
+    const phaseNum = milestoneIdToPhaseNum(milestoneId);
+    const planNum = sliceIdToPlanNum(sliceId);
+    const flatName = planFileName(phaseNum, planNum, suffix);
+    const flatPath = join(phaseDir, flatName);
+    if (existsSync(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;
+    // Try prefix match for the phase+plan number (handles suffix variations)
+    const planPrefix = `${String(phaseNum).padStart(2, "0")}-${String(planNum).padStart(2, "0")}-`;
+    try {
+        for (const entry of readdirSync(phaseDir, { withFileTypes: true })) {
+            if (entry.isFile() && entry.name.startsWith(planPrefix) && entry.name.endsWith(`-${suffix}.md`)) {
+                return join(phaseDir, entry.name);
+            }
+        }
+    }
+    catch {
+        // unreadable
+    }
+    // Legacy fallback: try old slices/SID/ dir structure
+    const sDir = resolveSlicePath(basePath, milestoneId, sliceId);
+    if (sDir && sDir !== phaseDir) {
+        const file = resolveFile(sDir, sliceId, suffix);
+        if (file)
+            return join(sDir, file);
+    }
+    return null;
 }
 /**
  * Resolve the tasks directory within a slice.
  */
 export function resolveTasksDir(basePath, milestoneId, sliceId) {
+    // Flat-phase: no tasks/ subdir. Tasks live as checkboxes inside plan files.
+    // Legacy fallback for old layouts:
     const sDir = resolveSlicePath(basePath, milestoneId, sliceId);
     if (!sDir)
         return null;
@@ -614,64 +874,129 @@ export function resolveTaskFile(basePath, milestoneId, sliceId, taskId, suffix)
 // ─── Relative Path Builders (for prompts — .gsd/milestones/...) ────────────
 /**
  * Build relative .gsd/ path to a milestone directory.
- * Uses the actual directory name on disk if it exists, otherwise bare ID.
+ * Uses the actual directory name on disk if it exists, otherwise the canonical
+ * flat-phase dir name the renderer will create (NN-slug).
+ *
+ * Pass `title` when the milestone title is available so the fallback slug
+ * matches what the renderer will create.  Without a title the phase number is
+ * used as a placeholder (no DB import is allowed here — db/engine uses
+ * import.meta.url which breaks the Next.js SSR build path).
  */
-export function relMilestonePath(basePath, milestoneId) {
-    const dir = resolveDir(milestonesDir(basePath), milestoneId);
-    if (dir)
-        return `.gsd/milestones/${dir}`;
-    return `.gsd/milestones/${milestoneId}`;
+export function relMilestonePath(basePath, milestoneId, title) {
+    // resolvePhaseDir handles both flat-phase (phases/NN-*) and legacy (milestones/M001).
+    const phaseDir = resolvePhaseDir(basePath, milestoneId);
+    if (phaseDir) {
+        const name = phaseDir.split(/[/\\]/).pop();
+        // Use the correct segment based on which layout the resolved dir lives under.
+        const legacyBase = legacyMilestonesDir(basePath);
+        if (phaseDir.startsWith(legacyBase + "/") || phaseDir.startsWith(legacyBase + "\\")) {
+            return `.gsd/milestones/${name}`;
+        }
+        return `.gsd/${LAYOUT_SEGMENTS.level1}/${name}`;
+    }
+    // No dir on disk yet — derive canonical flat-phase name.
+    // If the caller provides the milestone title, the slug will match what the
+    // renderer creates (e.g. "01-foundation").  Without a title, falls back to
+    // the milestone ID as the slug placeholder (e.g. "01-m001").
+    return `.gsd/${LAYOUT_SEGMENTS.level1}/${canonicalPhaseDirName(milestoneId, title)}`;
 }
 /**
  * Build relative .gsd/ path to a milestone file.
+ * Layout-aware: uses resolveMilestoneFile to find NN-SUFFIX.md (flat-phase)
+ * or M001-SUFFIX.md (legacy). Falls back to a layout-appropriate canonical
+ * name when the file doesn't exist yet.
  */
 export function relMilestoneFile(basePath, milestoneId, suffix) {
     const mRel = relMilestonePath(basePath, milestoneId);
-    const mDir = resolveMilestonePath(basePath, milestoneId);
-    if (mDir) {
-        const file = resolveFile(mDir, milestoneId, suffix);
-        if (file)
-            return `${mRel}/${file}`;
+    // resolveMilestoneFile checks NN-SUFFIX.md (flat-phase) and MID-SUFFIX.md (legacy).
+    const absFile = resolveMilestoneFile(basePath, milestoneId, suffix);
+    if (absFile) {
+        const fileName = absFile.split(/[/\\]/).pop();
+        return `${mRel}/${fileName}`;
     }
-    return `${mRel}/${buildMilestoneFileName(milestoneId, suffix)}`;
+    // File doesn't exist yet — use layout-aware fallback filename.
+    const mDir = resolveMilestonePath(basePath, milestoneId);
+    const legacyBase = legacyMilestonesDir(basePath);
+    const isLegacy = mDir
+        ? mDir.startsWith(legacyBase + "/") || mDir.startsWith(legacyBase + "\\")
+        : false;
+    const fileName = isLegacy
+        ? `${milestoneId}-${suffix}.md`
+        : `${String(milestoneIdToPhaseNum(milestoneId)).padStart(2, "0")}-${suffix}.md`;
+    return `${mRel}/${fileName}`;
 }
 /**
  * Build relative .gsd/ path to a slice directory.
+ * Layout-aware: legacy projects include a slices/S01/ subdir;
+ * flat-phase projects use the phase dir directly.
+ *
+ * @param milestoneTitle - Optional milestone title passed through to
+ *   relMilestonePath so the flat-phase fallback dir name uses the human-readable
+ *   slug ("05-milestone-five") rather than the bare ID slug ("05-m005").
+ *   Only consulted when no phase directory exists on disk yet.
  */
-export function relSlicePath(basePath, milestoneId, sliceId) {
-    const mRel = relMilestonePath(basePath, milestoneId);
+export function relSlicePath(basePath, milestoneId, sliceId, milestoneTitle) {
     const mDir = resolveMilestonePath(basePath, milestoneId);
     if (mDir) {
-        const slicesDir = join(mDir, "slices");
-        const dir = resolveDir(slicesDir, sliceId);
-        if (dir)
-            return `${mRel}/slices/${dir}`;
+        const legacyBase = legacyMilestonesDir(basePath);
+        if (mDir.startsWith(legacyBase + "/") || mDir.startsWith(legacyBase + "\\")) {
+            // Legacy: slices live under milestones/M001/slices/S01/
+            const mRel = relMilestonePath(basePath, milestoneId);
+            const slicesDir = join(mDir, "slices");
+            const dir = resolveDir(slicesDir, sliceId);
+            return `${mRel}/slices/${dir ?? sliceId}`;
+        }
     }
-    return `${mRel}/slices/${sliceId}`;
+    // Flat-phase: plans are files inside the phase dir, no slices/ subdir.
+    return relMilestonePath(basePath, milestoneId, milestoneTitle);
 }
 /**
  * Build relative .gsd/ path to a slice file.
+ * Layout-aware: legacy uses S01-SUFFIX.md; flat-phase uses NN-MM-SUFFIX.md.
+ *
+ * @param milestoneTitle - Optional milestone title forwarded to relSlicePath /
+ *   relMilestonePath for title-aware flat-phase fallback dir naming. Only used
+ *   when the phase directory does not yet exist on disk.
  */
-export function relSliceFile(basePath, milestoneId, sliceId, suffix) {
-    const sRel = relSlicePath(basePath, milestoneId, sliceId);
-    const sDir = resolveSlicePath(basePath, milestoneId, sliceId);
-    if (sDir) {
-        const file = resolveFile(sDir, sliceId, suffix);
-        if (file)
-            return `${sRel}/${file}`;
+export function relSliceFile(basePath, milestoneId, sliceId, suffix, milestoneTitle) {
+    const sRel = relSlicePath(basePath, milestoneId, sliceId, milestoneTitle);
+    const absPath = resolveSliceFile(basePath, milestoneId, sliceId, suffix);
+    if (absPath) {
+        const fileName = absPath.split(/[/\\]/).pop();
+        return `${sRel}/${fileName}`;
+    }
+    // Fallback when file doesn't exist yet — use layout-aware filename.
+    const mDir = resolveMilestonePath(basePath, milestoneId);
+    const legacyBase = legacyMilestonesDir(basePath);
+    const isLegacy = mDir
+        ? mDir.startsWith(legacyBase + "/") || mDir.startsWith(legacyBase + "\\")
+        : false;
+    if (isLegacy) {
+        return `${sRel}/${sliceId}-${suffix}.md`;
     }
-    return `${sRel}/${buildSliceFileName(sliceId, suffix)}`;
+    const phaseNum = milestoneIdToPhaseNum(milestoneId);
+    const planNum = sliceIdToPlanNum(sliceId);
+    return `${sRel}/${planFileName(phaseNum, planNum, suffix)}`;
 }
 /**
  * Build relative .gsd/ path to a task file.
+ *
+ * Legacy layout:  slices/SID/tasks/TID-SUFFIX.md (inside a slices/ subdir)
+ * Flat-phase:     PLAN → slice plan path (tasks as checkboxes); other suffixes
+ *                 (e.g. SUMMARY) → phase dir / TID-SUFFIX.md
  */
 export function relTaskFile(basePath, milestoneId, sliceId, taskId, suffix) {
-    const sRel = relSlicePath(basePath, milestoneId, sliceId);
-    const tDir = resolveTasksDir(basePath, milestoneId, sliceId);
-    if (tDir) {
-        const file = resolveFile(tDir, taskId, suffix);
-        if (file)
-            return `${sRel}/tasks/${file}`;
+    const sDir = resolveSlicePath(basePath, milestoneId, sliceId);
+    const phaseDir = resolveMilestonePath(basePath, milestoneId);
+    // Legacy: slice path is a slices/SID/ subdir inside the milestone dir
+    if (sDir && phaseDir && sDir !== phaseDir) {
+        const relS = relSlicePath(basePath, milestoneId, sliceId);
+        return `${relS}/tasks/${taskId}-${suffix}.md`;
+    }
+    // Flat-phase: task plans are checkboxes inside the slice plan file
+    if (suffix === "PLAN") {
+        return relSliceFile(basePath, milestoneId, sliceId, "PLAN");
     }
-    return `${sRel}/tasks/${buildTaskFileName(taskId, suffix)}`;
+    const relS = relSlicePath(basePath, milestoneId, sliceId);
+    return `${relS}/${buildTaskFileName(taskId, suffix)}`;
 }

package/dist/resources/extensions/gsd/planning-depth.js

@@ -7,7 +7,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import { atomicWriteSync } from "./atomic-write.js";
-import { getProjectGSDPreferencesPath } from "./preferences.js";
+import { clearGSDPreferencesCache, getProjectGSDPreferencesPath } from "./preferences.js";
 import { logWarning } from "./workflow-logger.js";
 import { researchDecisionPath, writeDefaultResearchSkipDecision, } from "./deep-project-setup-policy.js";
 const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
@@ -73,6 +73,7 @@ function writeProjectPreferencesParts(path, frontmatter, body) {
         ? `---\n${yamlBlock}\n---\n\n${body.replace(/^\n+/, "")}`
         : `---\n${yamlBlock}\n---\n`;
     atomicWriteSync(path, newContent, "utf-8");
+    clearGSDPreferencesCache();
 }
 function applyDeepWorkflowPreferenceDefaults(frontmatter) {
     if (frontmatter.commit_policy === undefined) {

package/dist/resources/extensions/gsd/post-execution-checks.js

@@ -14,7 +14,7 @@
  *   - Import checks are blocking failures; pattern checks are warnings
  *   - No AST parsers — uses regex heuristics
  */
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { resolve, dirname, extname } from "node:path";
 // ─── Import Resolution Check ─────────────────────────────────────────────────
 /**
@@ -263,6 +263,8 @@ export function checkImportResolution(taskRow, _priorTasks, basePath) {
     }
     return results;
 }
+let signatureCacheScope = null;
+const signatureCache = new Map();
 /**
  * Extract function signatures from TypeScript/JavaScript source code.
  */
@@ -294,6 +296,27 @@ function extractFunctionSignatures(source, fileName) {
     }
     return signatures;
 }
+function signatureCacheFor(taskRow, basePath) {
+    const scope = `${resolve(basePath)}\0${taskRow.milestone_id}\0${taskRow.slice_id}`;
+    if (signatureCacheScope !== scope) {
+        signatureCacheScope = scope;
+        signatureCache.clear();
+    }
+    return signatureCache;
+}
+function getCachedFunctionSignatures(cache, absolutePath, fileName) {
+    const stat = statSync(absolutePath);
+    const mtimeMs = stat.mtimeMs;
+    const size = stat.size;
+    const cached = cache.get(absolutePath);
+    if (cached && cached.mtimeMs === mtimeMs && cached.size === size) {
+        return cached.signatures.map((sig) => ({ ...sig, file: fileName }));
+    }
+    const source = readFileSync(absolutePath, "utf-8");
+    const signatures = extractFunctionSignatures(source, fileName);
+    cache.set(absolutePath, { mtimeMs, size, signatures });
+    return signatures;
+}
 /**
  * Normalize parameter list for comparison.
  */
@@ -320,6 +343,7 @@ export function checkCrossTaskSignatures(taskRow, priorTasks, basePath) {
     const results = [];
     // Build map of functions from prior tasks' key_files
     const priorSignatures = new Map();
+    const cache = signatureCacheFor(taskRow, basePath);
     for (const task of priorTasks) {
         for (const file of task.key_files) {
             const ext = extname(file);
@@ -329,8 +353,7 @@ export function checkCrossTaskSignatures(taskRow, priorTasks, basePath) {
             if (!existsSync(absolutePath))
                 continue;
             try {
-                const source = readFileSync(absolutePath, "utf-8");
-                const sigs = extractFunctionSignatures(source, file);
+                const sigs = getCachedFunctionSignatures(cache, absolutePath, file);
                 for (const sig of sigs) {
                     const existing = priorSignatures.get(sig.name) || [];
                     existing.push(sig);