@opengsd/gsd-pi 1.3.0 → 1.4.0

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

@@ -0,0 +1,221 @@
+// 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));
+}
+/** Retention window before flat-phase migration backups are auto-pruned. */
+export const FLAT_PHASE_BACKUP_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * Remove stale flat-phase migration backups after the retention window.
+ * Only runs when migration is complete (.gsd/phases/ exists, legacy layout gone).
+ * Returns the number of migrate-* directories removed.
+ */
+export function pruneStaleFlatPhaseBackups(basePath) {
+    if (needsFlatPhaseMigration(basePath))
+        return 0;
+    const phasesPath = join(basePath, ".gsd", LAYOUT_SEGMENTS.level1);
+    if (!existsSync(phasesPath))
+        return 0;
+    const backupRoot = join(basePath, ".gsd-backups");
+    if (!existsSync(backupRoot))
+        return 0;
+    const now = Date.now();
+    let removed = 0;
+    for (const entry of readdirSync(backupRoot)) {
+        if (!entry.startsWith("migrate-"))
+            continue;
+        const dirPath = join(backupRoot, entry);
+        try {
+            const st = statSync(dirPath);
+            if (!st.isDirectory())
+                continue;
+            if (now - st.mtimeMs < FLAT_PHASE_BACKUP_RETENTION_MS)
+                continue;
+            rmSync(dirPath, { recursive: true, force: true });
+            removed++;
+        }
+        catch {
+            // Non-fatal: leave backup for manual recovery.
+        }
+    }
+    try {
+        if (readdirSync(backupRoot).length === 0) {
+            rmSync(backupRoot, { recursive: true, force: true });
+        }
+    }
+    catch {
+        // Non-fatal.
+    }
+    return removed;
+}
+/**
+ * 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

@@ -22,11 +22,10 @@ import { deriveState } from "./state.js";
 import { isAutoActive } from "./auto.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
-import { isDbAvailable, getAllMilestones, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
-import { isClosedStatus } from "./status-guards.js";
+import { isDbAvailable, getHierarchyCompletionCounts } from "./gsd-db.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 +153,7 @@ async function writeForensicsDedupPref(ctx, enabled) {
         }
     }
     writeFileSync(prefsPath, `---\n${frontmatter}---${body}`, "utf-8");
+    clearGSDPreferencesCache();
 }
 // ─── Entry Point ──────────────────────────────────────────────────────────────
 export async function handleForensics(args, ctx, pi) {
@@ -592,36 +592,7 @@ function loadCompletedKeys(basePath) {
 function getDbCompletionCounts() {
     if (!isDbAvailable())
         return null;
-    const milestones = getAllMilestones();
-    let completedMilestones = 0;
-    let totalSlices = 0;
-    let completedSlices = 0;
-    let totalTasks = 0;
-    let completedTasks = 0;
-    for (const m of milestones) {
-        if (isClosedStatus(m.status))
-            completedMilestones++;
-        const slices = getMilestoneSlices(m.id);
-        for (const s of slices) {
-            totalSlices++;
-            if (isClosedStatus(s.status))
-                completedSlices++;
-            const tasks = getSliceTasks(m.id, s.id);
-            for (const t of tasks) {
-                totalTasks++;
-                if (isClosedStatus(t.status))
-                    completedTasks++;
-            }
-        }
-    }
-    return {
-        milestones: completedMilestones,
-        milestonesTotal: milestones.length,
-        slices: completedSlices,
-        slicesTotal: totalSlices,
-        tasks: completedTasks,
-        tasksTotal: totalTasks,
-    };
+    return getHierarchyCompletionCounts();
 }
 // ─── Anomaly Detectors ───────────────────────────────────────────────────────
 /**

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

@@ -208,6 +208,7 @@ export class MergeConflictError extends GSDError {
  */
 export const RUNTIME_EXCLUSION_PATHS = [
     ".gsd-worktrees/",
+    ".gsd-backups/**",
     ".gsd/activity/",
     ".gsd/audit/",
     ".gsd/forensics/",
@@ -225,6 +226,7 @@ export const RUNTIME_EXCLUSION_PATHS = [
     ".gsd/event-log.jsonl",
     ".gsd/DISCUSSION-MANIFEST.json",
 ];
+const runtimeFilesCleanedUpRepos = new Set();
 // ─── Integration Branch Metadata ───────────────────────────────────────────
 /**
  * Path to the milestone metadata file that stores the integration branch.
@@ -565,7 +567,8 @@ export class GitServiceImpl {
         // and the worktree is torn down. This prevents a mid-execution behavioral
         // discontinuity where the first half of a milestone has .gsd/ artifacts
         // committed but the second half doesn't (#1326).
-        if (!this._runtimeFilesCleanedUp) {
+        const cleanupRepoKey = resolve(this.basePath);
+        if (!runtimeFilesCleanedUpRepos.has(cleanupRepoKey)) {
             let cleaned = false;
             for (const exclusion of RUNTIME_EXCLUSION_PATHS) {
                 const removed = nativeRmCached(this.basePath, [exclusion]);
@@ -575,7 +578,7 @@ export class GitServiceImpl {
             if (cleaned) {
                 nativeCommit(this.basePath, "chore: untrack .gsd/ runtime files from git index", { allowEmpty: false });
             }
-            this._runtimeFilesCleanedUp = true;
+            runtimeFilesCleanedUpRepos.add(cleanupRepoKey);
         }
         // Stage everything using pathspec exclusions so excluded paths are never
         // hashed by git. The old approach of `git add -A` followed by unstaging
@@ -683,8 +686,6 @@ export class GitServiceImpl {
             return false;
         }
     }
-    /** Tracks whether runtime file cleanup has run this session. */
-    _runtimeFilesCleanedUp = false;
     /**
      * Stage files (smart staging) and commit.
      * Returns the commit message string on success, or null if nothing to commit.
@@ -708,11 +709,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)
@@ -1024,6 +1028,7 @@ function collectRepositoryDirtyStatus(basePath) {
     const preferences = loadEffectiveGSDPreferences(basePath)?.preferences;
     const registry = createRepositoryRegistryFromPreferences(basePath, preferences);
     const dirtyByRepository = {};
+    const registeredRoots = new Set(registry.repositories.map((repo) => resolve(repo.root)));
     for (const repo of registry.repositories) {
         try {
             dirtyByRepository[repo.id] = runGit(repo.root, ["status", "--porcelain"]).length > 0;
@@ -1033,8 +1038,63 @@ function collectRepositoryDirtyStatus(basePath) {
             dirtyByRepository[repo.id] = nativeHasChanges(repo.root);
         }
     }
+    for (const repoRoot of findUndeclaredNestedGitRepositories(registry.projectRoot, registeredRoots)) {
+        let dirty = false;
+        try {
+            dirty = runGit(repoRoot, ["status", "--porcelain"]).length > 0;
+        }
+        catch {
+            dirty = nativeHasChanges(repoRoot);
+        }
+        if (!dirty)
+            continue;
+        const relPath = relative(registry.projectRoot, repoRoot).split(sep).join("/") || repoRoot;
+        const label = `${relPath} (undeclared)`;
+        dirtyByRepository[label] = true;
+        logWarning("engine", `undeclared dirty nested git repo ${relPath}; declare it under workspace.repositories or commit manually`, { file: "git-service.ts" });
+    }
     return dirtyByRepository;
 }
+const UNDECLARED_NESTED_REPO_SCAN_MAX_DEPTH = 4;
+const UNDECLARED_NESTED_REPO_SKIP_DIRS = new Set([
+    ".git",
+    ".gsd",
+    ".gsd-worktrees",
+    "node_modules",
+    "dist",
+    "dist-test",
+]);
+function findUndeclaredNestedGitRepositories(projectRoot, registeredRoots) {
+    const found = [];
+    function visit(dir, depth) {
+        if (depth >= UNDECLARED_NESTED_REPO_SCAN_MAX_DEPTH)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (UNDECLARED_NESTED_REPO_SKIP_DIRS.has(entry.name))
+                continue;
+            const child = join(dir, entry.name);
+            const childRoot = resolve(child);
+            const hasGitDir = existsSync(join(child, ".git"));
+            const isRegistered = registeredRoots.has(childRoot);
+            if (hasGitDir && !isRegistered) {
+                found.push(childRoot);
+                continue;
+            }
+            visit(child, depth + 1);
+        }
+    }
+    visit(projectRoot, 0);
+    return found;
+}
 function runPerRepositoryCommitAction(args) {
     const preferences = loadEffectiveGSDPreferences(args.basePath)?.preferences;
     const registry = createRepositoryRegistryFromPreferences(args.basePath, preferences);
@@ -1054,7 +1114,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 +1151,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

@@ -22,8 +22,9 @@ import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
  * With external state (symlink), these are a no-op in most cases,
  * but retained for backwards compatibility during migration.
  */
-const GSD_RUNTIME_PATTERNS = [
+export const GSD_RUNTIME_PATTERNS = [
     ".gsd-worktrees/",
+    ".gsd-backups/",
     ".gsd/activity/",
     ".gsd/audit/",
     ".gsd/forensics/",
@@ -48,6 +49,8 @@ const BASELINE_PATTERNS = [
     ".gsd",
     // Worktree container sibling — NOT covered by the ".gsd" pattern above.
     ".gsd-worktrees/",
+    // Flat-phase migration snapshots — NOT covered by the ".gsd" pattern above.
+    ".gsd-backups/",
     ".gsd-id",
     ".mcp.json",
     ".bg-shell/",
@@ -201,10 +204,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-queue.js

@@ -12,7 +12,7 @@ import { loadFile } from "./files.js";
 import { loadPrompt, inlineTemplate } from "./prompt-loader.js";
 import { deriveState } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
-import { gsdRoot, resolveMilestoneFile, resolveGsdRootFile, relGsdRootFile, } from "./paths.js";
+import { gsdRoot, resolveMilestoneFile, resolveGsdRootFile, relGsdRootFile, relMilestoneFile, } from "./paths.js";
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
 import { nativeAddPaths, nativeCommit } from "./native-git-bridge.js";
@@ -20,6 +20,9 @@ import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { saveQueueOrder } from "./queue-order.js";
 import { findMilestoneIds, nextMilestoneId } from "./milestone-ids.js";
 import { isFutureMilestoneStatus } from "./status-guards.js";
+const QUEUE_ARTIFACT_EXCERPT_MAX_CHARS = 20_000;
+const QUEUE_EXISTING_MILESTONES_CONTEXT_MAX_CHARS = 120_000;
+const QUEUE_CONTEXT_SECTION_SEPARATOR = "\n\n---\n\n";
 // ─── Queue Entry Point ──────────────────────────────────────────────────────
 /**
  * Queue future milestones via conversational intake.
@@ -215,7 +218,7 @@ export async function buildExistingMilestonesContext(basePath, milestoneIds, sta
         if (contextFile) {
             const content = await loadFile(contextFile);
             if (content) {
-                parts.push(`\n**Context:**\n${content.trim()}`);
+                parts.push(`\n**Context:**\n${summarizeArtifactForQueue(content, relMilestoneFile(basePath, mid, "CONTEXT"))}`);
             }
         }
         else {
@@ -224,7 +227,7 @@ export async function buildExistingMilestonesContext(basePath, milestoneIds, sta
             if (draftFile) {
                 const draftContent = await loadFile(draftFile);
                 if (draftContent) {
-                    parts.push(`\n**Draft context available:**\n${draftContent.trim()}`);
+                    parts.push(`\n**Draft context available:**\n${summarizeArtifactForQueue(draftContent, relMilestoneFile(basePath, mid, "CONTEXT-DRAFT"))}`);
                 }
             }
         }
@@ -235,7 +238,7 @@ export async function buildExistingMilestonesContext(basePath, milestoneIds, sta
             if (roadmapFile) {
                 const content = await loadFile(roadmapFile);
                 if (content) {
-                    parts.push(`\n**Roadmap:**\n${content.trim()}`);
+                    parts.push(`\n**Roadmap:**\n${summarizeArtifactForQueue(content, relMilestoneFile(basePath, mid, "ROADMAP"))}`);
                 }
             }
         }
@@ -249,7 +252,65 @@ export async function buildExistingMilestonesContext(basePath, milestoneIds, sta
             sections.push(`### Previous Queue Entries\nSource: \`${relGsdRootFile("QUEUE")}\`\n\n${queueContent.trim()}`);
         }
     }
-    return sections.join("\n\n---\n\n");
+    return capExistingMilestonesContext(sections);
+}
+function summarizeArtifactForQueue(content, sourcePath, cap = QUEUE_ARTIFACT_EXCERPT_MAX_CHARS) {
+    const trimmed = content.trim();
+    if (trimmed.length <= cap) {
+        return `Source: \`${sourcePath}\`\n\n${trimmed}`;
+    }
+    const excerpt = trimmed.slice(0, cap).trimEnd();
+    const omittedChars = trimmed.length - excerpt.length;
+    return [
+        `Source: \`${sourcePath}\``,
+        "",
+        excerpt,
+        "",
+        `[Truncated ${omittedChars} chars. Read \`${sourcePath}\` for full content.]`,
+    ].join("\n");
+}
+function capExistingMilestonesContext(sections, cap = QUEUE_EXISTING_MILESTONES_CONTEXT_MAX_CHARS) {
+    const fullContext = sections.join(QUEUE_CONTEXT_SECTION_SEPARATOR);
+    if (fullContext.length <= cap)
+        return fullContext;
+    const notice = `[Existing milestones context truncated to ${cap} chars. Read source paths in this prompt or the corresponding .gsd artifacts for full details.]`;
+    const noticeSuffix = `${QUEUE_CONTEXT_SECTION_SEPARATOR}${notice}`;
+    const selected = [];
+    for (const section of sections) {
+        const candidate = [...selected, section].join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+        if (candidate.length <= cap) {
+            selected.push(section);
+            continue;
+        }
+        break;
+    }
+    if (selected.length === sections.length) {
+        return selected.join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+    }
+    const compactTail = sections.slice(selected.length).map(compactSectionForQueueBudget);
+    const hybrid = [...selected, ...compactTail].join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+    if (hybrid.length <= cap)
+        return hybrid;
+    const compact = sections.map(compactSectionForQueueBudget);
+    const compactContext = compact.join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+    if (compactContext.length <= cap)
+        return compactContext;
+    return `${compactContext.slice(0, Math.max(0, cap - notice.length - 2)).trimEnd()}\n\n${notice}`;
+}
+function compactSectionForQueueBudget(section) {
+    const lines = section.split("\n");
+    const compact = [];
+    if (lines[0])
+        compact.push(lines[0]);
+    const statusLine = lines.find(line => line.startsWith("**Status:**"));
+    if (statusLine)
+        compact.push(statusLine);
+    const sourceLines = lines.filter(line => line.startsWith("Source: `"));
+    if (sourceLines.length > 0) {
+        compact.push("", "**Sources:**", ...sourceLines);
+        compact.push("", "[Artifact excerpts omitted due to total queue/rethink context budget.]");
+    }
+    return compact.join("\n");
 }
 // ─── Internal Helpers ───────────────────────────────────────────────────────
 /**

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");