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

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

@@ -28,11 +28,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,
@@ -271,6 +270,7 @@ async function writeForensicsDedupPref(ctx: ExtensionCommandContext, enabled: bo
   }
 
   writeFileSync(prefsPath, `---\n${frontmatter}---${body}`, "utf-8");
+  clearGSDPreferencesCache();
 }
 
 // ─── Entry Point ──────────────────────────────────────────────────────────────
@@ -758,37 +758,7 @@ function loadCompletedKeys(basePath: string): string[] {
 function getDbCompletionCounts(): DbCompletionCounts | null {
   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/src/resources/extensions/gsd/git-conflict-state.ts

@@ -64,7 +64,23 @@ export function gitDiffCheckFailures(basePath: string): string[] | null {
       .filter(Boolean)
       .join("\n")
       .trim();
-    failures.push(output || `git diff --check ${args.join(" ")} failed`);
+
+    // git diff --check exits non-zero for both whitespace errors and leftover
+    // conflict markers. Only conflict markers block the gate — whitespace errors
+    // in staged files (common in auto-generated code) must not be misread as an
+    // unresolved merge conflict. Filter to lines git explicitly labels as
+    // "leftover conflict marker".
+    if (!output) {
+      failures.push(`git diff --check ${args.join(" ")} failed`);
+      continue;
+    }
+    const conflictMarkerLines = output
+      .split("\n")
+      .filter((line) => /leftover conflict marker/i.test(line))
+      .join("\n");
+    if (conflictMarkerLines) {
+      failures.push(conflictMarkerLines);
+    }
   }
 
   return failures;

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

@@ -359,6 +359,7 @@ export interface PreMergeCheckResult {
  * This array must stay synchronized with it.
  */
 export const RUNTIME_EXCLUSION_PATHS: readonly string[] = [
+  ".gsd-worktrees/",
   ".gsd/activity/",
   ".gsd/audit/",
   ".gsd/forensics/",
@@ -377,6 +378,8 @@ export const RUNTIME_EXCLUSION_PATHS: readonly string[] = [
   ".gsd/DISCUSSION-MANIFEST.json",
 ];
 
+const runtimeFilesCleanedUpRepos = new Set<string>();
+
 // ─── Integration Branch Metadata ───────────────────────────────────────────
 
 /**
@@ -754,7 +757,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]);
@@ -763,7 +767,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
@@ -892,9 +896,6 @@ export class GitServiceImpl {
     }
   }
 
-  /** Tracks whether runtime file cleanup has run this session. */
-  private _runtimeFilesCleanedUp = false;
-
   /**
    * Stage files (smart staging) and commit.
    * Returns the commit message string on success, or null if nothing to commit.
@@ -920,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)
@@ -1281,6 +1285,7 @@ function runPerRepositoryCommitAction(args: {
   unitId: string;
   taskContext?: TaskCommitContext;
   targetRepositories?: string[];
+  dirtyRepositories?: Record<string, boolean>;
 }): {
   commitMessages: Record<string, string>;
   commitErrors: Record<string, string>;
@@ -1312,6 +1317,7 @@ function runPerRepositoryCommitAction(args: {
           args.unitId,
           [],
           args.taskContext,
+          args.dirtyRepositories?.[repo.id],
         ) ?? "";
       if (message) {
         commitMessages[repo.id] = message;
@@ -1359,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

@@ -25,6 +25,7 @@ import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
  * but retained for backwards compatibility during migration.
  */
 const GSD_RUNTIME_PATTERNS = [
+  ".gsd-worktrees/",
   ".gsd/activity/",
   ".gsd/audit/",
   ".gsd/forensics/",
@@ -48,6 +49,8 @@ const GSD_RUNTIME_PATTERNS = [
 const BASELINE_PATTERNS = [
   // ── GSD state directory (symlink to external storage) ──
   ".gsd",
+  // Worktree container sibling — NOT covered by the ".gsd" pattern above.
+  ".gsd-worktrees/",
   ".gsd-id",
   ".mcp.json",
   ".bg-shell/",
@@ -218,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/gsd-command-home.ts

@@ -66,7 +66,7 @@ function disabled(description: string, reason: string): string {
 
 export function buildGsdHomeModel(
   state: GSDState,
-  closeout?: Pick<CloseoutContext, "strandedQuick" | "unmergedMilestones">,
+  closeout?: Pick<CloseoutContext, "strandedQuick" | "unmergedMilestones" | "idleResidueHint">,
 ): GsdHomeModel {
   const blocked = isBlocked(state);
   const complete = state.phase === "complete";
@@ -74,10 +74,14 @@ export function buildGsdHomeModel(
   const workLabel = activeWorkLabel(state);
   const strandedQuick = closeout?.strandedQuick ?? null;
   const unmergedMilestone = closeout?.unmergedMilestones?.[0];
+  const idleResidueHint = closeout?.idleResidueHint ?? null;
+  const hasIdleResidue = Boolean(idleResidueHint);
   const nextReason = complete
     ? "all milestones are complete"
     : blocked
       ? "the active milestone is blocked"
+      : hasIdleResidue
+        ? "milestone git residue needs recovery"
       : !hasActiveWork
         ? "there is no active milestone"
         : "";
@@ -91,6 +95,8 @@ export function buildGsdHomeModel(
       ? "finish_milestone"
       : blocked
         ? "fix_recover"
+        : hasIdleResidue
+          ? "fix_recover"
         : canAdvance
           ? "continue_step"
           : complete && unmappedActive > 0
@@ -107,6 +113,8 @@ export function buildGsdHomeModel(
     ? [`Quick task Q${strandedQuick.taskNum} finished on ${strandedQuick.quickBranch} but is not merged to ${strandedQuick.originalBranch}.`]
     : unmergedMilestone
       ? [`${unmergedMilestone.milestoneId} is complete but not merged into ${unmergedMilestone.integrationBranch}.`]
+      : idleResidueHint
+        ? [idleResidueHint.message]
       : completionSummary;
 
   return {
@@ -181,10 +189,12 @@ export function buildGsdHomeModel(
         label: "Fix or recover",
         description: blocked
           ? "Review the blocker and recovery commands for the active milestone."
+          : hasIdleResidue
+            ? "Review stranded milestone worktrees/branches and run the suggested recovery command."
           : disabled("This becomes active when closeout, validation, or state recovery is needed.", "no blocker is active"),
-        enabled: blocked,
+        enabled: blocked || hasIdleResidue,
         recommended: recommended === "fix_recover",
-        disabledReason: blocked ? undefined : "no blocker is active",
+        disabledReason: blocked || hasIdleResidue ? undefined : "no blocker is active",
       },
       {
         id: "start_configure",