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

package/src/resources/extensions/gsd/flat-phase-migration.ts

@@ -0,0 +1,205 @@
+// 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: string): string {
+  return join(basePath, ".gsd", LEGACY_MIGRATING_SEGMENT);
+}
+
+function hasLegacyMilestoneSubdirs(dirPath: string): boolean {
+  if (!existsSync(dirPath)) return false;
+  try {
+    return readdirSync(dirPath).some(e => statSync(join(dirPath, e)).isDirectory());
+  } catch {
+    return false;
+  }
+}
+
+function rollbackPartialMigration(
+  basePath: string,
+  backupDir: string,
+  migratingPath?: string,
+): void {
+  // 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 as Error).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: string): boolean {
+  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: string): Promise<void> {
+  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 as Error).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 as Error).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: { rendered: number; skipped: number; errors: string[] };
+  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 as Error).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 as Error).message}`,
+    );
+  }
+}

package/src/resources/extensions/gsd/forensics.ts

@@ -32,7 +32,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,
@@ -271,6 +271,7 @@ async function writeForensicsDedupPref(ctx: ExtensionCommandContext, enabled: bo
   }
 
   writeFileSync(prefsPath, `---\n${frontmatter}---${body}`, "utf-8");
+  clearGSDPreferencesCache();
 }
 
 // ─── Entry Point ──────────────────────────────────────────────────────────────

package/src/resources/extensions/gsd/git-constants.ts

@@ -32,7 +32,7 @@ function buildSafeParentEnv(): NodeJS.ProcessEnv {
 }
 
 /** Env overlay that suppresses interactive git credential prompts and git-svn noise. */
-export const GIT_NO_PROMPT_ENV = {
+export const GIT_NO_PROMPT_ENV: NodeJS.ProcessEnv = {
   ...buildSafeParentEnv(),
   GIT_TERMINAL_PROMPT: "0",
   GIT_ASKPASS: "",

package/src/resources/extensions/gsd/git-service.ts

@@ -921,16 +921,19 @@ 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: string,
     unitId: string,
     extraExclusions: readonly string[] = [],
     taskContext?: TaskCommitContext,
+    knownDirty?: boolean,
   ): string | null {
     // Quick check: is there anything dirty at all?
     // Native path uses libgit2 (single syscall), fallback spawns git.
-    if (!nativeHasChanges(this.basePath)) return null;
+    if (knownDirty === false) return null;
+    if (knownDirty !== true && !nativeHasChanges(this.basePath)) return null;
 
     const scoped = taskContext
       ? this.scopedStageTaskFiles(taskContext, extraExclusions)
@@ -1282,6 +1285,7 @@ function runPerRepositoryCommitAction(args: {
   unitId: string;
   taskContext?: TaskCommitContext;
   targetRepositories?: string[];
+  dirtyRepositories?: Record<string, boolean>;
 }): {
   commitMessages: Record<string, string>;
   commitErrors: Record<string, string>;
@@ -1313,6 +1317,7 @@ function runPerRepositoryCommitAction(args: {
           args.unitId,
           [],
           args.taskContext,
+          args.dirtyRepositories?.[repo.id],
         ) ?? "";
       if (message) {
         commitMessages[repo.id] = message;
@@ -1360,7 +1365,7 @@ export function runTurnGitAction(args: {
       };
     }
 
-    const repoCommitResult = runPerRepositoryCommitAction(args);
+    const repoCommitResult = runPerRepositoryCommitAction({ ...args, dirtyRepositories });
     if (Object.keys(repoCommitResult.commitErrors).length > 0) {
       return {
         action: args.action,

package/src/resources/extensions/gsd/gitignore.ts

@@ -221,10 +221,14 @@ export function ensureGitignore(
   );
 
   // 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")
+  const patternsToApply: readonly string[] = gsdIsTracked
+    ? Array.from(new Set([...BASELINE_PATTERNS.filter((p) => p !== ".gsd"), ...GSD_RUNTIME_PATTERNS]))
     : BASELINE_PATTERNS;
 
   // Find patterns not yet present

package/src/resources/extensions/gsd/guidance.ts

@@ -192,8 +192,8 @@ export function crashResumeHint(unitType: string, unitId: string): string | unde
 const DOCTOR_FIX_HINTS: Partial<Record<DoctorIssueCode, string>> = {
   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:
@@ -201,14 +201,14 @@ const DOCTOR_FIX_HINTS: Partial<Record<DoctorIssueCode, string>> = {
   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`.",
 };
 

package/src/resources/extensions/gsd/guided-flow.ts

@@ -40,7 +40,7 @@ import { listUnitRuntimeRecords, clearUnitRuntimeRecord, isInFlightRuntimePhase
 import { resolveExpectedArtifactPath } from "./auto.js";
 import { gsdHome } from "./gsd-home.js";
 import {
-  gsdRoot, milestonesDir, resolveMilestoneFile,
+  gsdRoot, milestonesDir, legacyMilestonesDir, resolveMilestoneFile,
   resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile,
   relMilestoneFile, relSliceFile,
 } from "./paths.js";
@@ -366,8 +366,11 @@ function hasNestedFileOrSymlink(dir: string): boolean {
   return false;
 }
 
-function clearEmptyLegacyDeepSetupPseudoMilestones(basePath: string, entries: string[]): string[] {
-  const mDir = milestonesDir(basePath);
+function clearEmptyLegacyDeepSetupPseudoMilestones(basePath: string, entries: string[], dir?: string): string[] {
+  // 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: string[] = [];
   for (const entry of entries) {
     if (!LEGACY_DEEP_SETUP_PSEUDO_MILESTONE_DIRS.has(entry)) {
@@ -1041,7 +1044,6 @@ function bootstrapGsdProject(basePath: string): void {
   }
 
   const root = gsdRoot(basePath);
-  mkdirSync(join(root, "milestones"), { recursive: true });
   mkdirSync(join(root, "runtime"), { recursive: true });
 
   const gitPrefs = loadEffectiveGSDPreferences(basePath)?.preferences?.git;
@@ -2106,9 +2108,12 @@ export async function showSmartEntry(
     // 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. ` +

package/src/resources/extensions/gsd/layout-policy.ts

@@ -0,0 +1,85 @@
+// 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",
+} as const;
+
+function pad(n: number, width = 2): string {
+  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: number, slug: string): string {
+  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: number, planNum: number, suffix: string): string {
+  return `${pad(phaseNum)}-${pad(planNum)}-${suffix}.md`;
+}
+
+/** DB path: `.gsd/gsd.db`. gsd-core ignores this file. */
+export function dbPath(basePath: string): string {
+  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: string): number {
+  // 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: string): string | undefined {
+  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: string): number {
+  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: string): string {
+  const slug = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40)
+    .replace(/-+$/g, "");
+  return slug || "phase";
+}