@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.5fc22c6f

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

@@ -0,0 +1,272 @@
+// 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, dirIsContentBearingLegacyMilestone, milestonesDir, resolveMilestonePath, } from "./paths.js";
+const LEGACY_MIGRATING_SEGMENT = "milestones.migrating";
+const RETRYABLE_FS_ERROR_CODES = new Set(["EPERM", "EBUSY", "ENOTEMPTY"]);
+const RM_RETRY_OPTIONS = { recursive: true, force: true, maxRetries: 5, retryDelay: 100 };
+let fsOps = { cpSync, renameSync, rmSync };
+export function _setFlatPhaseMigrationFsOpsForTest(overrides) {
+    const previous = fsOps;
+    fsOps = { ...fsOps, ...overrides };
+    return () => {
+        fsOps = previous;
+    };
+}
+function legacyMigratingPath(basePath) {
+    return join(basePath, ".gsd", LEGACY_MIGRATING_SEGMENT);
+}
+function removePathWithRetries(path) {
+    fsOps.rmSync(path, { recursive: true, force: true, maxRetries: RM_RETRY_OPTIONS.maxRetries, retryDelay: RM_RETRY_OPTIONS.retryDelay });
+}
+function isRetryableFsError(err) {
+    const code = err?.code;
+    return typeof code === "string" && RETRYABLE_FS_ERROR_CODES.has(code);
+}
+function movePathWithCopyDeleteFallback(src, dst) {
+    try {
+        fsOps.renameSync(src, dst);
+        return;
+    }
+    catch (err) {
+        if (!isRetryableFsError(err))
+            throw err;
+    }
+    try {
+        fsOps.cpSync(src, dst, { recursive: true, force: true });
+        removePathWithRetries(src);
+    }
+    catch (fallbackErr) {
+        if (existsSync(src) && existsSync(dst)) {
+            try {
+                removePathWithRetries(dst);
+            }
+            catch {
+                // Leave the original error intact; the next run can pre-clean dst.
+            }
+        }
+        throw fallbackErr;
+    }
+}
+function expectedPhaseDirs(basePath) {
+    return getAllMilestones().map((milestone) => resolveMilestonePath(basePath, milestone.id) ??
+        join(milestonesDir(basePath), canonicalPhaseDirName(milestone.id, milestone.title)));
+}
+function hasLegacyMilestoneSubdirs(dirPath) {
+    if (!existsSync(dirPath))
+        return false;
+    try {
+        return readdirSync(dirPath).some((e) => statSync(join(dirPath, e)).isDirectory() && dirIsContentBearingLegacyMilestone(join(dirPath, e)));
+    }
+    catch {
+        return false;
+    }
+}
+function rollbackPartialMigration(basePath, backupDir, migratingPath) {
+    // Remove the partially-written phases/ dir.
+    try {
+        removePathWithRetries(join(basePath, ".gsd", LAYOUT_SEGMENTS.level1));
+    }
+    catch (removeErr) {
+        logWarning("migration", `rollback: could not remove partial ${LAYOUT_SEGMENTS.level1}/: ${removeErr.message}`);
+    }
+    // Restore milestones/ — prefer renaming the preserved migrating copy back.
+    const milestonesPath = join(basePath, ".gsd", "milestones");
+    try {
+        if (migratingPath && existsSync(migratingPath) && !existsSync(milestonesPath)) {
+            movePathWithCopyDeleteFallback(migratingPath, milestonesPath);
+            return;
+        }
+        if (existsSync(backupDir)) {
+            cpSync(backupDir, milestonesPath, { recursive: true });
+        }
+        if (migratingPath && existsSync(migratingPath)) {
+            removePathWithRetries(migratingPath);
+        }
+    }
+    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;
+        }
+        if (existsSync(migratingPath)) {
+            removePathWithRetries(migratingPath);
+        }
+        // 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 {
+            movePathWithCopyDeleteFallback(milestonesPath, migratingPath);
+        }
+        catch (err) {
+            logWarning("migration", `failed to rename legacy milestones/ before render: ${err.message}`);
+            throw err;
+        }
+    }
+    // Clear any stale or partially-rendered flat projection before this run
+    // writes. Verification below checks the current DB render, not leftovers.
+    try {
+        removePathWithRetries(phasesPath);
+    }
+    catch (err) {
+        logWarning("migration", `failed to clear stale phases/ before render: ${err.message}`);
+        rollbackPartialMigration(basePath, backupDir, migratingPath);
+        throw err;
+    }
+    // 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();
+    const missingPhaseDirs = expectedPhaseDirs(basePath).filter((phaseDir) => !existsSync(phaseDir));
+    if (db.milestones > 0 && missingPhaseDirs.length > 0) {
+        logWarning("migration", `flat-phase migration missing ${missingPhaseDirs.length} expected phase dir(s): ${missingPhaseDirs.join(", ")}`);
+        rollbackPartialMigration(basePath, backupDir, migratingPath);
+        throw new Error("flat-phase migration verification failed: missing rendered phase directories");
+    }
+    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 {
+        removePathWithRetries(migratingPath);
+    }
+    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

@@ -16,7 +16,7 @@ import { gsdRoot } from "./paths.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { logWarning } from "./workflow-logger.js";
-import { createRepositoryRegistryFromPreferences } from "./repository-registry.js";
+import { createRepositoryRegistryFromPreferences, defaultRepositoryTargets } from "./repository-registry.js";
 import { isGsdGitignored } from "./gitignore.js";
 import { detectWorktreeName, } from "./worktree.js";
 import { SLICE_BRANCH_RE, QUICK_BRANCH_RE, WORKFLOW_BRANCH_RE } from "./branch-patterns.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)
@@ -1020,25 +1024,78 @@ export function handleTurnGitActionError(action, err) {
         error: errorWithStreams.stderr?.trim() || errorWithStreams.message || getErrorMessage(err),
     };
 }
+export function isRepositoryDirty(repoRoot) {
+    try {
+        return runGit(repoRoot, ["status", "--porcelain"]).length > 0;
+    }
+    catch {
+        // Fallback preserves legacy behavior if explicit status probing fails.
+        return nativeHasChanges(repoRoot);
+    }
+}
 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) {
+        dirtyByRepository[repo.id] = isRepositoryDirty(repo.root);
+    }
+    for (const repoRoot of findUndeclaredNestedGitRepositories(registry.projectRoot, registeredRoots)) {
+        const dirty = isRepositoryDirty(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 {
-            dirtyByRepository[repo.id] = runGit(repo.root, ["status", "--porcelain"]).length > 0;
+            entries = readdirSync(dir, { withFileTypes: true });
         }
         catch {
-            // Fallback preserves legacy behavior if explicit status probing fails.
-            dirtyByRepository[repo.id] = nativeHasChanges(repo.root);
+            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);
         }
     }
-    return dirtyByRepository;
+    visit(projectRoot, 0);
+    return found;
 }
 function runPerRepositoryCommitAction(args) {
     const preferences = loadEffectiveGSDPreferences(args.basePath)?.preferences;
     const registry = createRepositoryRegistryFromPreferences(args.basePath, preferences);
-    const repoIds = args.targetRepositories?.length ? args.targetRepositories : ["project"];
+    const repoIds = args.targetRepositories?.length ? args.targetRepositories : defaultRepositoryTargets(registry);
     const gitPrefs = preferences?.git ?? {};
     const commitMessages = {};
     const commitErrors = {};
@@ -1054,7 +1111,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 +1148,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,
@@ -1106,8 +1163,7 @@ export function runTurnGitAction(args) {
                 skippedRepositories: repoCommitResult.skippedRepositories,
             };
         }
-        const primaryMessage = repoCommitResult.commitMessages[args.targetRepositories?.[0] ?? "project"]
-            ?? Object.values(repoCommitResult.commitMessages)[0];
+        const primaryMessage = Object.values(repoCommitResult.commitMessages)[0];
         return {
             action: args.action,
             status: "ok",

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,21 @@ 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).",
+    artifact_user_content_missing: "Doctor cannot recreate user-authored content from the database. Re-run `/gsd discuss` for CONTEXT artifacts or `/gsd auto` for RESEARCH artifacts in that milestone.",
     uat_retry_exhausted: "Review the failing UAT criteria via `/gsd status`, fix the issue, then re-run `/gsd auto`.",
 };
 export function doctorFixHint(code) {