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

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

@@ -7,7 +7,7 @@
 // execute-task only (refine-slice escalation is deferred per ADR-011).
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { resolveSlicePath } from "./paths.js";
+import { legacyMilestonesDir, resolveSlicePath, resolveTasksDir } from "./paths.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { getTask, setTaskEscalationPending, setTaskEscalationAwaitingReview, clearTaskEscalationFlags, claimEscalationOverride, findUnappliedEscalationOverride, setTaskBlockerSource, listEscalationArtifacts, } from "./gsd-db.js";
 import { emitUokAuditEvent, buildAuditEnvelope } from "./uok/audit.js";
@@ -18,10 +18,17 @@ import { logWarning } from "./workflow-logger.js";
  *   .gsd/milestones/{M}/slices/{S}/tasks/{T}-ESCALATION.json
  */
 export function escalationArtifactPath(basePath, milestoneId, sliceId, taskId) {
-    const sDir = resolveSlicePath(basePath, milestoneId, sliceId);
-    if (!sDir)
+    const tDir = resolveTasksDir(basePath, milestoneId, sliceId);
+    if (tDir)
+        return join(tDir, `${taskId}-ESCALATION.json`);
+    // Flat-phase: tasks live in plan files; escalation artifacts sit in the phase dir.
+    // Legacy without tasks/: return null so writeEscalationArtifact throws (run doctor).
+    if (existsSync(legacyMilestonesDir(basePath)))
         return null;
-    return join(sDir, "tasks", `${taskId}-ESCALATION.json`);
+    const phaseDir = resolveSlicePath(basePath, milestoneId, sliceId);
+    if (!phaseDir)
+        return null;
+    return join(phaseDir, `${taskId}-ESCALATION.json`);
 }
 // ─── Artifact I/O ─────────────────────────────────────────────────────────
 /** Build an EscalationArtifact from a gsd_complete_task escalation payload. */

package/dist/resources/extensions/gsd/export-html.js

@@ -760,10 +760,11 @@ function buildChangelogSection(data) {
 // ─── Section: Knowledge ───────────────────────────────────────────────────────
 function buildKnowledgeSection(data) {
     const k = data.knowledge;
-    if (!k.exists)
+    const memories = data.memories;
+    if (!k.exists && memories.entries.length === 0)
         return section('knowledge', 'Knowledge', '<p class="empty">No KNOWLEDGE.md found.</p>');
     const total = k.rules.length + k.patterns.length + k.lessons.length;
-    if (total === 0)
+    if (total === 0 && memories.entries.length === 0)
         return section('knowledge', 'Knowledge', '<p class="empty">KNOWLEDGE.md exists but no entries parsed.</p>');
     const rulesHtml = k.rules.length > 0 ? `
     <h3>Rules <span class="count">${k.rules.length}</span></h3>
@@ -783,7 +784,13 @@ function buildKnowledgeSection(data) {
       <thead><tr><th>ID</th><th>Lesson</th></tr></thead>
       <tbody>${k.lessons.map(l => `<tr><td class="mono">${esc(l.id)}</td><td>${esc(l.content)}</td></tr>`).join('')}</tbody>
     </table>` : '';
-    return section('knowledge', `Knowledge <span class="count">${total}</span>`, `${rulesHtml}${patternsHtml}${lessonsHtml}`);
+    const memoriesHtml = memories.entries.length > 0 ? `
+    <h3>Memories <span class="count">${memories.entries.length}/${memories.totalCount}</span></h3>
+    <table class="tbl">
+      <thead><tr><th>ID</th><th>Category</th><th>Scope</th><th>Memory</th></tr></thead>
+      <tbody>${memories.entries.map(m => `<tr><td class="mono">${esc(m.id)}</td><td>${esc(m.category)}</td><td>${esc(m.scope)}</td><td>${esc(m.content)}</td></tr>`).join('')}</tbody>
+    </table>` : '';
+    return section('knowledge', `Knowledge <span class="count">${total + memories.totalCount}</span>`, `${rulesHtml}${patternsHtml}${lessonsHtml}${memoriesHtml}`);
 }
 // ─── Section: Captures ────────────────────────────────────────────────────────
 function buildCapturesSection(data) {

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

@@ -7,6 +7,71 @@ import { getLedger, getProjectTotals, aggregateByPhase, aggregateBySlice, aggreg
 import { gsdRoot } from "./paths.js";
 import { formatDuration, fileLink } from "../shared/format-utils.js";
 import { getErrorMessage } from "./error-utils.js";
+import { isDbAvailable } from "./gsd-db.js";
+import { openExistingWorkflowDatabase } from "./db-workspace.js";
+import { getActiveMemories, getActiveMemoriesRanked } from "./memory-store.js";
+const EXPORT_MEMORY_LIMIT = 20;
+const EXPORT_MEMORY_CONTENT_LIMIT = 2000;
+function ensureExportDb(basePath) {
+    if (isDbAvailable())
+        return;
+    openExistingWorkflowDatabase(basePath);
+}
+function loadExportMemories(basePath, visualizerData) {
+    if (visualizerData?.memories)
+        return limitMemoryInfo(visualizerData.memories);
+    ensureExportDb(basePath);
+    try {
+        const allActive = getActiveMemories();
+        const ranked = getActiveMemoriesRanked(EXPORT_MEMORY_LIMIT);
+        return {
+            totalCount: allActive.length,
+            entries: ranked.map((memory) => ({
+                id: memory.id,
+                category: memory.category,
+                content: limitMemoryContent(memory.content),
+                confidence: memory.confidence,
+                hitCount: memory.hit_count,
+                scope: memory.scope,
+                tags: memory.tags,
+                updatedAt: memory.updated_at,
+            })),
+        };
+    }
+    catch {
+        return { entries: [], totalCount: 0 };
+    }
+}
+function limitMemoryInfo(memories) {
+    return {
+        totalCount: memories.totalCount,
+        entries: memories.entries.map((memory) => ({
+            ...memory,
+            content: limitMemoryContent(memory.content),
+        })),
+    };
+}
+function limitMemoryContent(content) {
+    if (content.length <= EXPORT_MEMORY_CONTENT_LIMIT)
+        return content;
+    return `${content.slice(0, EXPORT_MEMORY_CONTENT_LIMIT).trimEnd()}...`;
+}
+function formatMemoryLines(memories) {
+    if (memories.entries.length === 0)
+        return [];
+    return [
+        `## Memories`,
+        ``,
+        `Active memories: ${memories.totalCount}`,
+        ``,
+        ...memories.entries.map((memory) => {
+            const scope = memory.scope ? `, scope ${memory.scope}` : "";
+            const tags = memory.tags.length > 0 ? `, tags ${memory.tags.join(", ")}` : "";
+            return `- **${memory.id}** (${memory.category}, confidence ${Math.round(memory.confidence * 100)}%, hits ${memory.hitCount}${scope}${tags}): ${memory.content}`;
+        }),
+        ``,
+    ];
+}
 /**
  * Open a file in the user's default browser.
  * Uses platform-specific commands: `open` (macOS), `xdg-open` (Linux), `start` (Windows).
@@ -47,6 +112,7 @@ export function writeExportFile(basePath, format, visualizerData) {
     mkdirSync(exportDir, { recursive: true });
     const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
     if (format === "json") {
+        const memories = loadExportMemories(basePath, visualizerData);
         const report = {
             exportedAt: new Date().toISOString(),
             project: projectName,
@@ -54,6 +120,7 @@ export function writeExportFile(basePath, format, visualizerData) {
             byPhase: visualizerData?.byPhase ?? aggregateByPhase(units),
             bySlice: visualizerData?.bySlice ?? aggregateBySlice(units),
             byModel: visualizerData?.byModel ?? aggregateByModel(units),
+            memories,
             units,
         };
         const outPath = join(exportDir, `export-${timestamp}.json`);
@@ -64,6 +131,7 @@ export function writeExportFile(basePath, format, visualizerData) {
         const totals = visualizerData?.totals ?? getProjectTotals(units);
         const phases = visualizerData?.byPhase ?? aggregateByPhase(units);
         const slices = visualizerData?.bySlice ?? aggregateBySlice(units);
+        const memories = loadExportMemories(basePath, visualizerData);
         const md = [
             `# GSD Session Report — ${projectName}`,
             ``,
@@ -86,6 +154,7 @@ export function writeExportFile(basePath, format, visualizerData) {
             `|-------|-------|------|--------|----------|`,
             ...slices.map((s) => `| ${s.sliceId} | ${s.units} | ${formatCost(s.cost)} | ${formatTokenCount(s.tokens.total)} | ${formatDuration(s.duration)} |`),
             ``,
+            ...formatMemoryLines(memories),
         ].join("\n");
         const outPath = join(exportDir, `export-${timestamp}.md`);
         writeFileSync(outPath, md, "utf-8");
@@ -216,6 +285,7 @@ export async function handleExport(args, ctx, basePath) {
     mkdirSync(exportDir, { recursive: true });
     const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
     if (format === "json") {
+        const memories = loadExportMemories(basePath);
         const report = {
             exportedAt: new Date().toISOString(),
             project: projectName,
@@ -223,6 +293,7 @@ export async function handleExport(args, ctx, basePath) {
             byPhase: aggregateByPhase(units),
             bySlice: aggregateBySlice(units),
             byModel: aggregateByModel(units),
+            memories,
             units,
         };
         const outPath = join(exportDir, `export-${timestamp}.json`);
@@ -233,6 +304,7 @@ export async function handleExport(args, ctx, basePath) {
         const totals = getProjectTotals(units);
         const phases = aggregateByPhase(units);
         const slices = aggregateBySlice(units);
+        const memories = loadExportMemories(basePath);
         const md = [
             `# GSD Session Report — ${projectName}`,
             ``,
@@ -255,6 +327,7 @@ export async function handleExport(args, ctx, basePath) {
             `|-------|-------|------|--------|----------|`,
             ...slices.map(s => `| ${s.sliceId} | ${s.units} | ${formatCost(s.cost)} | ${formatTokenCount(s.tokens.total)} | ${formatDuration(s.duration)} |`),
             ``,
+            ...formatMemoryLines(memories),
             `## Unit History`,
             ``,
             `| Type | ID | Model | Cost | Tokens | Duration |`,

package/dist/resources/extensions/gsd/file-lock.js

@@ -30,9 +30,9 @@ function acquireLockSyncWithRetry(filePath, retries, stale) {
 export function withFileLockSync(filePath, fn, opts = {}) {
     if (!existsSync(filePath))
         return fn();
-    const retries = opts.retries ?? DEFAULT_RETRIES;
     const stale = opts.stale ?? DEFAULT_STALE_MS;
     const onLocked = opts.onLocked ?? "fail";
+    const retries = onLocked === "skip" ? 0 : (opts.retries ?? DEFAULT_RETRIES);
     try {
         const release = acquireLockSyncWithRetry(filePath, retries, stale);
         try {

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

@@ -0,0 +1,176 @@
+// Project/App: gsd-pi
+// File Purpose: One-time migration from legacy nested .gsd/milestones/ to
+// flat-phase .gsd/phases/. Runs on startup when the legacy structure is detected.
+import { cpSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { renderAllFromDb, renderRoadmapFromDb } from "./markdown-renderer.js";
+import { getAllMilestones, getMilestoneSlices } from "./gsd-db.js";
+import { migrateFromMarkdown } from "./md-importer.js";
+import { countDbHierarchy } from "./migration-auto-check.js";
+import { logWarning } from "./workflow-logger.js";
+import { LAYOUT_SEGMENTS } from "./layout-policy.js";
+import { canonicalPhaseDirName, milestonesDir, resolveMilestonePath } from "./paths.js";
+const LEGACY_MIGRATING_SEGMENT = "milestones.migrating";
+function legacyMigratingPath(basePath) {
+    return join(basePath, ".gsd", LEGACY_MIGRATING_SEGMENT);
+}
+function hasLegacyMilestoneSubdirs(dirPath) {
+    if (!existsSync(dirPath))
+        return false;
+    try {
+        return readdirSync(dirPath).some(e => statSync(join(dirPath, e)).isDirectory());
+    }
+    catch {
+        return false;
+    }
+}
+function rollbackPartialMigration(basePath, backupDir, migratingPath) {
+    // Remove the partially-written phases/ dir.
+    rmSync(join(basePath, ".gsd", LAYOUT_SEGMENTS.level1), { recursive: true, force: true });
+    // Restore milestones/ — prefer renaming the preserved migrating copy back.
+    const milestonesPath = join(basePath, ".gsd", "milestones");
+    try {
+        if (migratingPath && existsSync(migratingPath) && !existsSync(milestonesPath)) {
+            renameSync(migratingPath, milestonesPath);
+            return;
+        }
+        if (existsSync(backupDir)) {
+            cpSync(backupDir, milestonesPath, { recursive: true });
+        }
+        if (migratingPath && existsSync(migratingPath)) {
+            rmSync(migratingPath, { recursive: true, force: true });
+        }
+    }
+    catch (restoreErr) {
+        logWarning("migration", `rollback: could not restore milestones/: ${restoreErr.message}`);
+        // Non-fatal: backup still exists at backupDir for manual recovery.
+    }
+}
+/**
+ * Detect whether the project uses the legacy nested layout.
+ * True when .gsd/milestones/ exists AND contains at least one milestone
+ * subdirectory. An empty milestones/ dir (created by old bootstrap code
+ * before it was fixed) is not a real legacy layout and must not trigger
+ * a migration that would thrash the reconciler.
+ */
+export function needsFlatPhaseMigration(basePath) {
+    if (hasLegacyMilestoneSubdirs(join(basePath, ".gsd", "milestones")))
+        return true;
+    // Resume an interrupted migration where the legacy tree was renamed aside.
+    return hasLegacyMilestoneSubdirs(legacyMigratingPath(basePath));
+}
+/**
+ * Migrate from legacy nested .gsd/milestones/ to flat-phase .gsd/phases/.
+ *
+ * Steps:
+ * 1. Backup .gsd/milestones/ to .gsd-backups/migrate-<ts>/
+ * 2. Rename .gsd/milestones/ aside so path resolvers target phases/
+ * 3. Render flat-phase from the DB (which already has the data)
+ * 4. Verify counts match
+ * 5. Remove the renamed legacy tree
+ *
+ * Idempotent: if .gsd/milestones/ doesn't exist, returns immediately.
+ */
+export async function migrateToFlatPhase(basePath) {
+    if (!needsFlatPhaseMigration(basePath))
+        return;
+    const milestonesPath = join(basePath, ".gsd", "milestones");
+    const migratingPath = legacyMigratingPath(basePath);
+    const phasesPath = join(basePath, ".gsd", LAYOUT_SEGMENTS.level1);
+    const resumingInterrupted = !hasLegacyMilestoneSubdirs(milestonesPath) && hasLegacyMilestoneSubdirs(migratingPath);
+    // 1. Reconcile DB from legacy markdown before backup/removal so on-disk-only
+    // content is imported even when milestone rows already exist in SQLite.
+    // Check BEFORE creating the backup — avoids accumulating .gsd-backups/ entries
+    // on every session start when milestones/ exists but the DB has no rows.
+    migrateFromMarkdown(basePath);
+    const milestonesBefore = getAllMilestones().length;
+    if (milestonesBefore === 0) {
+        logWarning("migration", "flat-phase migration skipped: legacy milestones/ exists but DB has no milestone rows — will retry when DB is populated");
+        return;
+    }
+    let backupDir = migratingPath;
+    if (!resumingInterrupted) {
+        // 2. Backup (only reached when the DB has rows and migration will proceed)
+        const ts = Date.now();
+        backupDir = join(basePath, ".gsd-backups", `migrate-${ts}`);
+        try {
+            mkdirSync(join(basePath, ".gsd-backups"), { recursive: true });
+            cpSync(milestonesPath, backupDir, { recursive: true });
+        }
+        catch (err) {
+            logWarning("migration", `flat-phase migration backup failed: ${err.message}`);
+            throw err;
+        }
+        // 3. Rename legacy tree aside before rendering so path resolvers target
+        // phases/ instead of writing back into the nested milestones/ layout.
+        // Keep the full tree on disk until render+verify succeed (unlike rmSync).
+        try {
+            renameSync(milestonesPath, migratingPath);
+        }
+        catch (err) {
+            logWarning("migration", `failed to rename legacy milestones/ before render: ${err.message}`);
+            throw err;
+        }
+    }
+    else {
+        // Interrupted run: clear any partial phases/ projection before retrying.
+        rmSync(phasesPath, { recursive: true, force: true });
+    }
+    // 4. Render flat-phase from DB
+    let renderResult;
+    try {
+        renderResult = await renderAllFromDb(basePath);
+        // Slice-less milestones still need a phase directory for flat-phase layout.
+        for (const milestone of getAllMilestones()) {
+            if (getMilestoneSlices(milestone.id).length > 0)
+                continue;
+            const roadmapResult = await renderRoadmapFromDb(basePath, milestone.id);
+            if ("skipped" in roadmapResult) {
+                const phaseDir = resolveMilestonePath(basePath, milestone.id) ??
+                    join(milestonesDir(basePath), canonicalPhaseDirName(milestone.id, milestone.title));
+                mkdirSync(phaseDir, { recursive: true });
+                continue;
+            }
+            renderResult.rendered++;
+        }
+    }
+    catch (err) {
+        logWarning("migration", `flat-phase render failed: ${err.message}`);
+        rollbackPartialMigration(basePath, backupDir, migratingPath);
+        throw err;
+    }
+    // 5. Verify render succeeded and flat-phase projection was written
+    if (renderResult.errors.length > 0) {
+        logWarning("migration", `flat-phase render had ${renderResult.errors.length} error(s): ${renderResult.errors.join("; ")}`);
+        rollbackPartialMigration(basePath, backupDir, migratingPath);
+        throw new Error(`flat-phase migration render failed: ${renderResult.errors.slice(0, 3).join("; ")}`);
+    }
+    const db = countDbHierarchy();
+    let renderedDirCount = 0;
+    try {
+        // /^\d+-/ matches any numeric prefix (01-, 10-, 100-) so M100+ milestones
+        // whose dirs start with "100-slug" are counted correctly.
+        renderedDirCount = readdirSync(phasesPath, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && /^\d+-/.test(entry.name)).length;
+    }
+    catch {
+        // phases/ doesn't exist or is unreadable — same as zero dirs
+    }
+    if (db.milestones > 0 && renderedDirCount !== db.milestones) {
+        logWarning("migration", `phases/ dir count mismatch: expected ${db.milestones}, found ${renderedDirCount}`);
+        rollbackPartialMigration(basePath, backupDir, migratingPath);
+        throw new Error("flat-phase migration verification failed: phases dir milestone count mismatch");
+    }
+    if (db.slices > 0 && renderResult.rendered === 0) {
+        logWarning("migration", "flat-phase migration verification failed: render produced no artifacts for populated DB");
+        rollbackPartialMigration(basePath, backupDir, migratingPath);
+        throw new Error("flat-phase migration verification failed: no artifacts rendered");
+    }
+    // 6. Verified — remove the renamed legacy tree (backup already on disk).
+    try {
+        rmSync(migratingPath, { recursive: true, force: true });
+    }
+    catch (err) {
+        logWarning("migration", `flat-phase migration succeeded but could not remove ${LEGACY_MIGRATING_SEGMENT}: ${err.message}`);
+    }
+}

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

@@ -26,7 +26,7 @@ import { isDbAvailable, getAllMilestones, getMilestoneSlices, getSliceTasks } fr
 import { isClosedStatus } from "./status-guards.js";
 import { formatDuration } from "../shared/format-utils.js";
 import { getAutoWorktreePath } from "./auto-worktree.js";
-import { loadEffectiveGSDPreferences, loadGlobalGSDPreferences, getGlobalGSDPreferencesPath } from "./preferences.js";
+import { clearGSDPreferencesCache, loadEffectiveGSDPreferences, loadGlobalGSDPreferences, getGlobalGSDPreferencesPath } from "./preferences.js";
 import { showNextAction } from "../shared/tui.js";
 import { isInteractiveCommandContext, notifyForensicsNeedsInteractiveMenu, } from "./command-feedback.js";
 import { ensurePreferencesFile, serializePreferencesToFrontmatter } from "./commands-prefs-wizard.js";
@@ -154,6 +154,7 @@ async function writeForensicsDedupPref(ctx, enabled) {
         }
     }
     writeFileSync(prefsPath, `---\n${frontmatter}---${body}`, "utf-8");
+    clearGSDPreferencesCache();
 }
 // ─── Entry Point ──────────────────────────────────────────────────────────────
 export async function handleForensics(args, ctx, pi) {

package/dist/resources/extensions/gsd/git-service.js

@@ -708,11 +708,14 @@ export class GitServiceImpl {
      *
      * Returns the commit message on success, or null if nothing to commit.
      * @param extraExclusions Additional paths to exclude from staging (e.g. [".gsd/"] for pre-switch commits).
+     * @param knownDirty Fresh caller-provided dirty status; when omitted, autoCommit probes the tree.
      */
-    autoCommit(unitType, unitId, extraExclusions = [], taskContext) {
+    autoCommit(unitType, unitId, extraExclusions = [], taskContext, knownDirty) {
         // Quick check: is there anything dirty at all?
         // Native path uses libgit2 (single syscall), fallback spawns git.
-        if (!nativeHasChanges(this.basePath))
+        if (knownDirty === false)
+            return null;
+        if (knownDirty !== true && !nativeHasChanges(this.basePath))
             return null;
         const scoped = taskContext
             ? this.scopedStageTaskFiles(taskContext, extraExclusions)
@@ -1054,7 +1057,7 @@ function runPerRepositoryCommitAction(args) {
             continue;
         }
         try {
-            const message = new GitServiceImpl(repo.root, gitPrefs).autoCommit(args.unitType, args.unitId, [], args.taskContext) ?? "";
+            const message = new GitServiceImpl(repo.root, gitPrefs).autoCommit(args.unitType, args.unitId, [], args.taskContext, args.dirtyRepositories?.[repo.id]) ?? "";
             if (message) {
                 commitMessages[repo.id] = message;
             }
@@ -1091,7 +1094,7 @@ export function runTurnGitAction(args) {
                 dirtyRepositories,
             };
         }
-        const repoCommitResult = runPerRepositoryCommitAction(args);
+        const repoCommitResult = runPerRepositoryCommitAction({ ...args, dirtyRepositories });
         if (Object.keys(repoCommitResult.commitErrors).length > 0) {
             return {
                 action: args.action,

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

@@ -201,10 +201,14 @@ export function ensureGitignore(basePath, options) {
         .map((l) => l.trim())
         .filter((l) => l && !l.startsWith("#")));
     // Determine which patterns to apply. If .gsd/ has tracked files,
-    // exclude the ".gsd" pattern to prevent deleting tracked state.
+    // exclude the ".gsd" pattern to prevent deleting tracked state, but
+    // substitute the granular GSD_RUNTIME_PATTERNS so transient artifacts
+    // (STATE.md, runtime/, gsd.db, event-log.jsonl, …) still get ignored.
+    // Without this fallback, the pre-completion commit gate sees those
+    // runtime paths as untracked and blocks milestone close-out forever.
     const gsdIsTracked = hasGitTrackedGsdFiles(basePath);
     const patternsToApply = gsdIsTracked
-        ? BASELINE_PATTERNS.filter((p) => p !== ".gsd")
+        ? Array.from(new Set([...BASELINE_PATTERNS.filter((p) => p !== ".gsd"), ...GSD_RUNTIME_PATTERNS]))
         : BASELINE_PATTERNS;
     // Find patterns not yet present
     const missing = patternsToApply.filter((p) => !existingLines.has(p));

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

@@ -137,20 +137,20 @@ export function crashResumeHint(unitType, unitId) {
 // guidance is authored — the gap is visible in one place.
 const DOCTOR_FIX_HINTS = {
     db_unavailable: "The workflow database could not be opened — state derivation is degraded. Restart the session; if it persists, run `/gsd doctor` from the project root.",
-    stale_crash_lock: "Run `/gsd doctor` to clear the stale lock, then `/gsd auto` to resume.",
-    stale_parallel_session: "Run `/gsd doctor` to clear the stale session registration.",
+    stale_crash_lock: "Run `/gsd doctor fix` to clear the stale lock, then `/gsd auto` to resume.",
+    stale_parallel_session: "Run `/gsd doctor fix` to clear the stale session registration.",
     unresolved_git_conflicts: "Resolve the conflict markers, commit, then re-run `/gsd auto`.",
     conflict_markers_in_tracked_files: "Search the listed files for `<<<<<<<` markers, resolve, and commit.",
     worktree_dirty: "Commit or merge the worktree's changes (`gsd worktree merge <name>`) before removing it.",
     worktree_branch_merged: "The branch is merged — remove the worktree to reclaim space.",
-    orphaned_auto_worktree: "Run `/gsd doctor` to fix, or merge salvageable work with `gsd worktree merge <name>`.",
-    gitignore_missing_patterns: "Run `/gsd doctor` to append the missing .gitignore patterns.",
+    orphaned_auto_worktree: "Run `/gsd doctor fix` to fix, or merge salvageable work with `gsd worktree merge <name>`.",
+    gitignore_missing_patterns: "Run `/gsd doctor fix` to append the missing .gitignore patterns.",
     invalid_preferences: "Edit .gsd/PREFERENCES.md to fix the invalid field, then re-run the command.",
     provider_key_missing: "Add the provider API key to your environment or provider config, then retry.",
     provider_key_backedoff: "The key is cooling down after repeated failures — wait, or switch the phase model in .gsd/PREFERENCES.md.",
-    state_file_stale: "Run `/gsd doctor` to rebuild the projection from the database.",
-    state_file_missing: "Run `/gsd doctor` to rebuild the projection from the database.",
-    projection_drift: "Run `/gsd doctor` to rebuild markdown projections from the database (DB is the source of truth).",
+    state_file_stale: "Run `/gsd doctor fix` to rebuild the projection from the database.",
+    state_file_missing: "Run `/gsd doctor fix` to rebuild the projection from the database.",
+    projection_drift: "Run `/gsd doctor fix` to rebuild markdown projections from the database (DB is the source of truth).",
     uat_retry_exhausted: "Review the failing UAT criteria via `/gsd status`, fix the issue, then re-run `/gsd auto`.",
 };
 export function doctorFixHint(code) {

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

@@ -20,7 +20,7 @@ import { assessInterruptedSession, formatInterruptedSessionRunningMessage, forma
 import { listUnitRuntimeRecords, clearUnitRuntimeRecord, isInFlightRuntimePhase } from "./unit-runtime.js";
 import { resolveExpectedArtifactPath } from "./auto.js";
 import { gsdHome } from "./gsd-home.js";
-import { gsdRoot, milestonesDir, resolveMilestoneFile, resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile, relMilestoneFile, relSliceFile, } from "./paths.js";
+import { gsdRoot, milestonesDir, legacyMilestonesDir, resolveMilestoneFile, resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile, relMilestoneFile, relSliceFile, } from "./paths.js";
 import { join } from "node:path";
 import { readFileSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
 import { readSessionLockData, isSessionLockProcessAlive } from "./session-lock.js";
@@ -211,8 +211,11 @@ function hasNestedFileOrSymlink(dir) {
     }
     return false;
 }
-function clearEmptyLegacyDeepSetupPseudoMilestones(basePath, entries) {
-    const mDir = milestonesDir(basePath);
+function clearEmptyLegacyDeepSetupPseudoMilestones(basePath, entries, dir) {
+    // These are LEGACY pseudo-milestone dirs — prefer legacyMilestonesDir (milestones/)
+    // when it exists; caller may also supply the dir directly.
+    const legacyDir = legacyMilestonesDir(basePath);
+    const mDir = dir ?? (existsSync(legacyDir) ? legacyDir : milestonesDir(basePath));
     const remaining = [];
     for (const entry of entries) {
         if (!LEGACY_DEEP_SETUP_PSEUDO_MILESTONE_DIRS.has(entry)) {
@@ -732,7 +735,6 @@ function bootstrapGsdProject(basePath) {
         nativeInit(basePath, mainBranch);
     }
     const root = gsdRoot(basePath);
-    mkdirSync(join(root, "milestones"), { recursive: true });
     mkdirSync(join(root, "runtime"), { recursive: true });
     const gitPrefs = loadEffectiveGSDPreferences(basePath)?.preferences?.git;
     const manageGitignore = gitPrefs?.manage_gitignore;
@@ -1643,9 +1645,12 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
         // cwd, etc). Warn instead of silently starting a new-project flow.
         if (milestoneIds.length === 0) {
             const mDir = milestonesDir(basePath);
-            if (existsSync(mDir)) {
+            const legDir = legacyMilestonesDir(basePath);
+            // Check flat-phase dir first; fall back to legacy milestones/ dir
+            const checkDir = existsSync(mDir) ? mDir : existsSync(legDir) ? legDir : null;
+            if (checkDir) {
                 try {
-                    const entries = clearEmptyLegacyDeepSetupPseudoMilestones(basePath, readdirSync(mDir));
+                    const entries = clearEmptyLegacyDeepSetupPseudoMilestones(basePath, readdirSync(checkDir), checkDir);
                     if (entries.length > 0) {
                         ctx.ui.notify(`Milestone directory has ${entries.length} entries but none were recognized as milestones. ` +
                             `This may indicate a corrupted state or wrong working directory. Run \`/gsd doctor\` to diagnose.`, "warning");

package/dist/resources/extensions/gsd/layout-policy.js

@@ -0,0 +1,75 @@
+// Project/App: gsd-pi
+// File Purpose: Single source of truth for the on-disk layout inside .gsd/.
+// Adopted gsd-core's flat-phase structure so both tools read/write the same
+// shape. The 17 path resolvers in paths.ts delegate here; the renderer and
+// importer route through them.
+//
+// DB table/column names (milestones/slices/tasks, milestone_id, etc.) stay
+// unchanged — those are internal identifiers. Only the on-disk segment names
+// and file-naming change.
+/** Root directory name. Both gsd-core (Stage 2) and gsd-pi standardize here. */
+export const LAYOUT_ROOT = ".gsd";
+/** Segment names inside the root. */
+export const LAYOUT_SEGMENTS = {
+    /** Was "milestones". A phase = one unit of work (gsd-core vocabulary). */
+    level1: "phases",
+};
+function pad(n, width = 2) {
+    return String(n).padStart(width, "0");
+}
+/**
+ * Phase directory name: `NN-slug` (e.g. "01-foundation").
+ * Matches gsd-core's `phases/NN-name/` convention.
+ */
+export function phaseDirName(phaseNum, slug) {
+    return `${pad(phaseNum)}-${slug}`;
+}
+/**
+ * Plan file name: `NN-MM-SUFFIX.md` (e.g. "01-01-PLAN.md").
+ * Matches gsd-core's per-plan file convention.
+ */
+export function planFileName(phaseNum, planNum, suffix) {
+    return `${pad(phaseNum)}-${pad(planNum)}-${suffix}.md`;
+}
+/** DB path: `.gsd/gsd.db`. gsd-core ignores this file. */
+export function dbPath(basePath) {
+    return `${basePath}/${LAYOUT_ROOT}/gsd.db`.replaceAll(/\/+/g, "/");
+}
+/**
+ * Extract the numeric portion of a milestone id (M001 → 1).
+ * Used by the renderer to derive the phase number from the DB's milestone_id.
+ */
+export function milestoneIdToPhaseNum(milestoneId) {
+    // No $ anchor: accepts bare (M012) and team-suffixed (M012-abc123) IDs.
+    const m = milestoneId.match(/^M0*(\d+)/i);
+    return m ? Number.parseInt(m[1], 10) : 1;
+}
+/** Team-mode suffix from milestone ids like M001-abc123. */
+export function milestoneIdUniqueSuffix(milestoneId) {
+    const m = milestoneId.match(/^M(\d{3})(?:-([a-z0-9]{6}))?$/);
+    return m?.[2];
+}
+/**
+ * Extract the numeric portion of a slice id (S01 → 1).
+ * Used by the renderer to derive the plan number from the DB's slice_id.
+ */
+export function sliceIdToPlanNum(sliceId) {
+    const m = sliceId.match(/^S0*(\d+)$/i);
+    return m ? Number.parseInt(m[1], 10) : 1;
+}
+/**
+ * Derive a stable, deterministic, filesystem-safe slug from a milestone title.
+ * Used for the phase directory name so the layout is human-readable.
+ *
+ * Stability is load-bearing: the renderer must produce the same slug for the
+ * same title on every run, or the directory churns on every projection.
+ */
+export function derivePhaseSlug(title) {
+    const slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40)
+        .replace(/-+$/g, "");
+    return slug || "phase";
+}