@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

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

@@ -19,7 +19,7 @@ import { openSync, closeSync, unlinkSync, statSync, writeFileSync } from "node:f
 import type { ExtensionContext } from "@gsd/pi-coding-agent";
 import { gsdRoot } from "./paths.js";
 import { getAndClearSkills } from "./skill-telemetry.js";
-import { loadJsonFile, loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
+import { loadJsonFile, loadJsonFileOrNull, saveJsonFileCompact } from "./json-persistence.js";
 import { parseUnitId } from "./unit-id.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
 import { isUnifiedAuditEnabled } from "./uok/audit-toggle.js";
@@ -846,12 +846,22 @@ function defaultLedger(): MetricsLedger {
   return { version: 1, projectStartedAt: Date.now(), units: [] };
 }
 
+export const METRICS_LEDGER_KEEP_UNITS = 1500;
+
+function compareUnitsByTime(a: UnitMetrics, b: UnitMetrics): number {
+  return a.finishedAt - b.finishedAt || a.startedAt - b.startedAt;
+}
+
+function keepNewestUnits(units: UnitMetrics[], keepCount = METRICS_LEDGER_KEEP_UNITS): UnitMetrics[] {
+  return units.length > keepCount ? [...units].sort(compareUnitsByTime).slice(-keepCount) : units;
+}
+
 /**
  * Prune the metrics ledger to at most `keepCount` most-recent unit entries.
  *
  * Called by the doctor when the ledger exceeds the bloat threshold.
- * Keeps the newest entries (highest index = most recent) and discards
- * the oldest from the head of the array. Preserves `projectStartedAt`.
+ * Keeps the newest entries by unit timestamps and discards the oldest.
+ * Preserves `projectStartedAt`.
  *
  * Updates both the on-disk file and the in-memory ledger if it is loaded,
  * so the current session sees the pruned state immediately.
@@ -862,11 +872,11 @@ export function pruneMetricsLedger(base: string, keepCount: number): number {
   const disk = loadLedgerFromDisk(base);
   if (!disk || disk.units.length <= keepCount) return 0;
   const removed = disk.units.length - keepCount;
-  disk.units = disk.units.slice(-keepCount);
-  saveJsonFile(metricsPath(base), disk);
+  disk.units = keepNewestUnits(disk.units, keepCount);
+  saveJsonFileCompact(metricsPath(base), disk);
   // Keep the in-memory ledger in sync if it is loaded for this session.
   if (ledger) {
-    ledger.units = ledger.units.slice(-keepCount);
+    ledger.units = keepNewestUnits(ledger.units, keepCount);
   }
   // Invalidate all scoped ledger cache entries. Prune is rare; clearing the
   // entire map is simpler than tracking which entry belongs to `base`. Without
@@ -1024,12 +1034,14 @@ function saveLedger(base: string, data: MetricsLedger): void {
       // Read current on-disk state and merge with worker's in-memory units.
       // Worker units take precedence on conflict (by finishedAt in deduplicateUnits).
       const onDisk = loadJsonFileOrNull(path, isMetricsLedger);
-      if (onDisk && onDisk.units.length > 0) {
-        const merged = deduplicateUnits([...onDisk.units, ...data.units]);
-        saveJsonFile(path, { ...data, units: merged });
-      } else {
-        saveJsonFile(path, data);
-      }
+      const dataUnits = keepNewestUnits(data.units);
+      const merged =
+        onDisk && onDisk.units.length > 0
+          ? deduplicateUnits([...keepNewestUnits(onDisk.units), ...dataUnits])
+          : dataUnits;
+      merged.sort(compareUnitsByTime);
+      data.units = keepNewestUnits(merged);
+      saveJsonFileCompact(path, data);
     } finally {
       releaseLock(lockPath);
     }
@@ -1040,6 +1052,7 @@ function saveLedger(base: string, data: MetricsLedger): void {
     // to a torn write caused by two writers simultaneously executing the
     // read-merge-write sequence without mutual exclusion.
     logWarning("fs", "saveLedger: lock not acquired — falling back to direct write (no merge)");
-    saveJsonFile(path, data);
+    data.units = keepNewestUnits(data.units);
+    saveJsonFileCompact(path, data);
   }
 }

package/src/resources/extensions/gsd/migrate/layout-detect.ts

@@ -0,0 +1,38 @@
+// Project/App: gsd-pi
+// File Purpose: Classify a parsed .planning/ tree into its layout so the
+// round-trip writer can recreate the same structure gsd-core wrote.
+//
+// This extracts the implicit 3-way branch that was buried in transformer.ts
+// transformToGSD (lines 425-467). Priority matches the transformer's if/else
+// chain: legacy-milestone-dir > multi-milestone > flat-phases.
+
+import type { PlanningProject } from "./types.js";
+import type { PlanningLayout } from "../compat/compat-marker.js";
+
+/**
+ * Determine which .planning/ layout a parsed project uses. Returns null when
+ * no layout signal is present (caller decides: treat as inactive or error).
+ *
+ * Priority (must match transformer.ts transformToGSD):
+ *   1. legacy-milestone-dir — milestones/<id>/ contains <id>-phases/ subdirs
+ *      with phase content. Detected when parsed.milestones has any entry with
+ *      non-empty phases.
+ *   2. multi-milestone — ROADMAP.md parsed into milestone sections.
+ *      Detected when roadmap.milestones.length > 0.
+ *   3. flat-phases — ROADMAP.md parsed into checkbox phase lines only.
+ *      Detected when roadmap.phases.length > 0.
+ */
+export function detectPlanningLayout(parsed: PlanningProject): PlanningLayout | null {
+  const hasMilestoneDirectories = parsed.milestones.some(
+    (m) => Object.keys(m.phases).length > 0,
+  );
+  if (hasMilestoneDirectories) return "legacy-milestone-dir";
+
+  const isMultiMilestone = parsed.roadmap !== null && parsed.roadmap.milestones.length > 0;
+  if (isMultiMilestone) return "multi-milestone";
+
+  const hasFlatPhases = parsed.roadmap !== null && parsed.roadmap.phases.length > 0;
+  if (hasFlatPhases) return "flat-phases";
+
+  return null;
+}

package/src/resources/extensions/gsd/migrate/planning-writer.ts

@@ -0,0 +1,259 @@
+// Project/App: gsd-pi
+// File Purpose: DB → .planning/ projection. Parallel to writer.ts (which
+// emits .gsd/). Produces the .planning/ markdown shape that gsd-core reads.
+//
+// Layout policy (spec §4.4): emits the layout recorded in the compat marker.
+// v1 supports flat-phases; multi-milestone and legacy-milestone-dir are stubbed
+// with a clear error until fixtures exist to validate them.
+
+import { mkdirSync } from "node:fs";
+import { join, relative } from "node:path";
+
+import { getAllMilestones, getMilestoneSlices, getSliceTasks } from "../gsd-db.js";
+import { saveFile } from "../files.js";
+import type { PlanningLayout } from "../compat/compat-marker.js";
+import {
+  applyPlanningProjectionWrites,
+  type PlanningProjectionWrite,
+} from "../compat/planning-compat.js";
+
+export interface PlanningWrittenFiles {
+  paths: string[];
+  layout: PlanningLayout;
+}
+
+function planningRoot(basePath: string): string {
+  return join(basePath, ".planning");
+}
+
+function slugify(title: string, fallback: string): string {
+  const slug = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40);
+  return slug || fallback;
+}
+
+function pad(n: number, width = 2): string {
+  return String(n).padStart(width, "0");
+}
+
+/**
+ * Format a roadmap for the flat-phases layout. Mirrors the checkbox line
+ * format that parsers.ts parsePhaseEntry recognizes: `- [x] NN — Title`.
+ */
+function formatPlanningRoadmapFlat(
+  entries: Array<{ number: number; title: string; done: boolean }>,
+): string {
+  const lines = ["# Roadmap", "", "## Phases", ""];
+  for (const e of entries) {
+    const box = e.done ? "[x]" : "[ ]";
+    lines.push(`- ${box} ${pad(e.number)} — ${e.title}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+/**
+ * Format STATE.md in gsd-core's phase-progress schema. gsd-pi is authoritative
+ * for status; this is a one-way DB→projection (edits to STATE.md are not
+ * re-imported — see spec §7).
+ */
+function formatPlanningState(
+  activeMilestone: string,
+  totalPhases: number,
+  completedPhases: number,
+): string {
+  const pct = totalPhases === 0 ? 0 : Math.round((completedPhases / totalPhases) * 100);
+  const ts = new Date().toISOString();
+  return [
+    "---",
+    "gsd_state_version: 1.0",
+    `milestone: ${activeMilestone}`,
+    'milestone_name: "milestone"',
+    "status: active",
+    `stopped_at: Phase 01 — in progress`,
+    `last_updated: "${ts}"`,
+    `last_activity: ${ts.slice(0, 10)}`,
+    "progress:",
+    `  total_phases: ${totalPhases}`,
+    `  completed_phases: ${completedPhases}`,
+    `  total_plans: ${totalPhases}`,
+    `  completed_plans: ${completedPhases}`,
+    `  percent: ${pct}`,
+    "---",
+    "",
+    "# Project State",
+    "",
+    "Current Phase: **01**",
+    "Status: **active**",
+    "",
+  ].join("\n");
+}
+
+function formatPlanningProject(title: string): string {
+  return `# ${title}\n`;
+}
+
+/**
+ * Format a phase plan file with the XML-tagged structure parsers.ts
+ * parseOldPlan recognizes: <objective>, <tasks>, <verification>.
+ */
+function formatPlanningPlan(
+  phaseNum: number,
+  planNum: number,
+  title: string,
+  tasks: Array<{ id: string; title: string; estimate?: string }>,
+): string {
+  const lines: string[] = [];
+  lines.push(`# ${pad(phaseNum)}-${pad(planNum)}: ${title}`, "");
+  lines.push("<objective>");
+  lines.push(`${title}.`);
+  lines.push("</objective>");
+  lines.push("");
+  lines.push("<tasks>");
+  for (const t of tasks) {
+    const est = t.estimate ? ` _(${t.estimate})_` : "";
+    lines.push(`- [ ] **${t.id}**: ${t.title}${est}`);
+  }
+  lines.push("</tasks>");
+  lines.push("");
+  lines.push("<verification>");
+  lines.push("All tasks complete and tests pass.");
+  lines.push("</verification>");
+  lines.push("");
+  return lines.join("\n");
+}
+
+/**
+ * Project DB state to .planning/ in the recorded layout.
+ * Reads DB directly (canonical source). Writes via saveFile (atomic).
+ *
+ * v1: flat-phases only. Each milestone's slices become sequentially-numbered
+ * phase dirs; each task within a slice becomes a plan file (NN-MM-PLAN.md).
+ */
+export async function writePlanningDirectory(
+  basePath: string,
+  layout: PlanningLayout,
+): Promise<PlanningWrittenFiles> {
+  if (layout !== "flat-phases") {
+    // v1: flat-phases only. multi-milestone and legacy-milestone-dir need
+    // fixtures to validate the reverse-mapping (transformer.ts is non-injective
+    // — three layouts collapse to one .gsd/ shape); stub until then.
+    throw new Error(
+      `writePlanningDirectory: layout "${layout}" not yet supported (v1 supports flat-phases only)`,
+    );
+  }
+
+  const root = planningRoot(basePath);
+  mkdirSync(root, { recursive: true });
+  const paths: string[] = [];
+  const projectionWrites: PlanningProjectionWrite[] = [];
+  const toPlanningRel = (absPath: string): string =>
+    relative(root, absPath).replace(/\\/g, "/");
+
+  const milestones = getAllMilestones();
+  if (milestones.length === 0) {
+    return { paths, layout };
+  }
+
+  // Flat-phases: each slice becomes one phase. Tasks within become plan files.
+  let phaseNum = 0;
+  const roadmapEntries: Array<{ number: number; title: string; done: boolean }> = [];
+
+  for (const milestone of milestones) {
+    const slices = getMilestoneSlices(milestone.id);
+    for (const slice of slices) {
+      phaseNum++;
+      const phaseSlug = slugify(slice.title || slice.id, slice.id.toLowerCase());
+      const phaseDirName = `${pad(phaseNum)}-${phaseSlug}`;
+      const phaseDir = join(root, "phases", phaseDirName);
+      mkdirSync(phaseDir, { recursive: true });
+
+      const tasks = getSliceTasks(milestone.id, slice.id);
+      const isDone =
+        tasks.length > 0 && tasks.every((t) => t.status === "complete");
+      roadmapEntries.push({
+        number: phaseNum,
+        title: slice.title || slice.id,
+        done: isDone,
+      });
+
+      if (tasks.length === 0) {
+        // Empty phase — write a single placeholder plan so the dir isn't empty.
+        const planPath = join(phaseDir, `${pad(phaseNum)}-01-PLAN.md`);
+        await saveFile(
+          planPath,
+          formatPlanningPlan(phaseNum, 1, slice.title || slice.id, []),
+        );
+        paths.push(planPath);
+        projectionWrites.push({
+          relPath: toPlanningRel(planPath),
+          entities: [`${milestone.id}/${slice.id}`],
+        });
+      } else {
+        for (let ti = 0; ti < tasks.length; ti++) {
+          const task = tasks[ti]!;
+          const planNum = ti + 1;
+          const planPath = join(phaseDir, `${pad(phaseNum)}-${pad(planNum)}-PLAN.md`);
+          await saveFile(
+            planPath,
+            formatPlanningPlan(phaseNum, planNum, task.title || task.id, [
+              {
+                id: task.id,
+                title: task.title || task.id,
+                estimate: task.estimate || undefined,
+              },
+            ]),
+          );
+          paths.push(planPath);
+          projectionWrites.push({
+            relPath: toPlanningRel(planPath),
+            entities: [`${milestone.id}/${slice.id}/${task.id}`],
+          });
+        }
+      }
+    }
+  }
+
+  // If no slices produced any phases, write a single empty phase so ROADMAP.md
+  // isn't blank and the layout is still discoverable.
+  if (roadmapEntries.length === 0) {
+    const phaseDirName = `${pad(1)}-milestone`;
+    const phaseDir = join(root, "phases", phaseDirName);
+    mkdirSync(phaseDir, { recursive: true });
+    const planPath = join(phaseDir, `${pad(1)}-01-PLAN.md`);
+    await saveFile(planPath, formatPlanningPlan(1, 1, milestones[0]!.title || milestones[0]!.id, []));
+    paths.push(planPath);
+    projectionWrites.push({
+      relPath: toPlanningRel(planPath),
+      entities: [milestones[0]!.id],
+    });
+    roadmapEntries.push({ number: 1, title: milestones[0]!.title || milestones[0]!.id, done: false });
+  }
+
+  // Root files
+  const milestoneEntities = milestones.map((m) => m.id);
+  const roadmapPath = join(root, "ROADMAP.md");
+  await saveFile(roadmapPath, formatPlanningRoadmapFlat(roadmapEntries));
+  paths.push(roadmapPath);
+  projectionWrites.push({ relPath: toPlanningRel(roadmapPath), entities: milestoneEntities });
+
+  const completedPhases = roadmapEntries.filter((e) => e.done).length;
+  const statePath = join(root, "STATE.md");
+  await saveFile(
+    statePath,
+    formatPlanningState(milestones[0]!.id, roadmapEntries.length, completedPhases),
+  );
+  paths.push(statePath);
+  projectionWrites.push({ relPath: toPlanningRel(statePath), entities: [milestones[0]!.id] });
+
+  const projectPath = join(root, "PROJECT.md");
+  await saveFile(projectPath, formatPlanningProject(milestones[0]!.title || milestones[0]!.id));
+  paths.push(projectPath);
+  projectionWrites.push({ relPath: toPlanningRel(projectPath), entities: [milestones[0]!.id] });
+
+  applyPlanningProjectionWrites(basePath, projectionWrites);
+  return { paths, layout };
+}

package/src/resources/extensions/gsd/migrate-external.ts

@@ -7,12 +7,13 @@
  */
 
 import { execFileSync } from "node:child_process";
-import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, renameSync, cpSync, rmSync, symlinkSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, renameSync, cpSync, rmSync, statSync, symlinkSync } from "node:fs";
 import { join } from "node:path";
-import { externalGsdRoot, isInsideWorktree } from "./repo-identity.js";
+import { externalGsdRoot, externalStateAlreadyExistsForProject, isInsideWorktree } from "./repo-identity.js";
 import { getErrorMessage } from "./error-utils.js";
 import { hasGitTrackedGsdFiles } from "./gitignore.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
+import { gsdRoot, milestonesDir, resolveGsdRootFile } from "./paths.js";
 
 export interface MigrationResult {
   migrated: boolean;
@@ -84,6 +85,16 @@ export function migrateToExternalState(basePath: string): MigrationResult {
     }
   }
 
+  // If external state already contains project data, this is not a legacy
+  // migration source. It is likely an already-migrated project whose symlink
+  // was replaced by a real directory, so copying would risk data loss.
+  if (externalStateAlreadyExistsForProject(basePath)) {
+    return {
+      migrated: false,
+      error: "External state already exists for this project; leaving local .gsd directory untouched to avoid overwriting authoritative state",
+    };
+  }
+
   const externalPath = externalGsdRoot(basePath);
   const migratingPath = join(basePath, ".gsd.migrating");
 
@@ -93,12 +104,12 @@ export function migrateToExternalState(basePath: string): MigrationResult {
 
     // Rename .gsd -> .gsd.migrating (atomic lock).
     // On Windows, NTFS may reject rename with EPERM if file descriptors are
-    // open (VS Code watchers, antivirus on-access scan). Fall back to
-    // copy+delete (#1292).
+    // open (VS Code watchers, antivirus on-access scan). WSL/DrvFs can report
+    // the same transient lock as EACCES. Fall back to copy+delete (#1292).
     try {
       renameSync(localGsd, migratingPath);
     } catch (renameErr: any) {
-      if (renameErr?.code === "EPERM" || renameErr?.code === "EBUSY") {
+      if (renameErr?.code === "EPERM" || renameErr?.code === "EBUSY" || renameErr?.code === "EACCES") {
         try {
           cpSync(localGsd, migratingPath, { recursive: true, force: true });
           rmSync(localGsd, { recursive: true, force: true });
@@ -117,6 +128,7 @@ export function migrateToExternalState(basePath: string): MigrationResult {
 
     // Copy contents to external dir, skipping worktrees/
     const entries = readdirSync(migratingPath, { withFileTypes: true });
+    const copyFailures: string[] = [];
     for (const entry of entries) {
       if (entry.name === "worktrees") continue; // worktrees stay local
 
@@ -129,10 +141,15 @@ export function migrateToExternalState(basePath: string): MigrationResult {
         } else {
           cpSync(src, dst, { force: true });
         }
-      } catch {
-        // Non-fatal: continue with other files
+      } catch (copyErr) {
+        copyFailures.push(`${entry.name}: ${getErrorMessage(copyErr)}`);
       }
     }
+    if (copyFailures.length > 0) {
+      try { rmSync(localGsd, { force: true }); } catch { /* may not exist */ }
+      renameSync(migratingPath, localGsd);
+      return { migrated: false, error: `Migration copy failed: ${copyFailures.join("; ")}` };
+    }
 
     // Create symlink .gsd -> external path
     symlinkSync(externalPath, localGsd, "junction");
@@ -159,6 +176,10 @@ export function migrateToExternalState(basePath: string): MigrationResult {
       return { migrated: false, error: `Migration verification failed: ${getErrorMessage(verifyErr)}` };
     }
 
+    // Remove .gsd.migrating once the junction is verified. The git-index cleanup
+    // below is best-effort and does not need the staging copy to survive.
+    rmSync(migratingPath, { recursive: true, force: true });
+
     // Clean the git index — any .gsd/* files tracked before migration now
     // sit behind the symlink and git can't follow it, causing them to show
     // as deleted. Remove them from the index so the working tree stays clean.
@@ -174,9 +195,6 @@ export function migrateToExternalState(basePath: string): MigrationResult {
       // Non-fatal — git may be unavailable or nothing was tracked
     }
 
-    // Remove .gsd.migrating only after symlink is verified and index is clean
-    rmSync(migratingPath, { recursive: true, force: true });
-
     return { migrated: true };
   } catch (err) {
     // Rollback: rename .gsd.migrating back to .gsd
@@ -195,16 +213,64 @@ export function migrateToExternalState(basePath: string): MigrationResult {
   }
 }
 
+export function isCurrentGsdStateIntactForMigratingCleanup(basePath: string): boolean {
+  try {
+    const stateFile = resolveGsdRootFile(basePath, "STATE");
+    const milestonesPath = milestonesDir(basePath);
+    const dbPath = join(gsdRoot(basePath), "gsd.db");
+    const hasDbFile = existsSync(dbPath);
+    const hasNonEmptyDb = hasDbFile && statSync(dbPath).size > 0;
+    return existsSync(stateFile) && existsSync(milestonesPath) && hasNonEmptyDb;
+  } catch {
+    return false;
+  }
+}
+
+function normalizeResolvedPath(p: string): string {
+  const normalized = p.replaceAll("\\", "/").replace(/\/+$/, "");
+  return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+function isLocalGsdExternalStateJunction(basePath: string, localGsd: string): boolean {
+  try {
+    const stat = lstatSync(localGsd);
+    if (!stat.isSymbolicLink()) return false;
+    const resolved = normalizeResolvedPath(realpathSync(localGsd));
+    const resolvedExternal = normalizeResolvedPath(realpathSync(externalGsdRoot(basePath)));
+    return resolved === resolvedExternal;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Recover from a failed migration (`.gsd.migrating` exists).
- * Moves `.gsd.migrating` back to `.gsd` if `.gsd` doesn't exist.
+ * Moves `.gsd.migrating` back to `.gsd` if `.gsd` doesn't exist, or removes an
+ * orphaned staging directory when `.gsd` is already a verified external state
+ * junction, or an intact real directory, with intact current state.
  */
 export function recoverFailedMigration(basePath: string): boolean {
   const localGsd = join(basePath, ".gsd");
   const migratingPath = join(basePath, ".gsd.migrating");
 
   if (!existsSync(migratingPath)) return false;
-  if (existsSync(localGsd)) return false; // both exist -- ambiguous, don't touch
+  if (existsSync(localGsd)) {
+    if (!isCurrentGsdStateIntactForMigratingCleanup(basePath)) return false;
+    if (!isLocalGsdExternalStateJunction(basePath, localGsd)) {
+      try {
+        const stat = lstatSync(localGsd);
+        if (!stat.isDirectory()) return false;
+      } catch {
+        return false;
+      }
+    }
+    try {
+      rmSync(migratingPath, { recursive: true, force: true });
+      return true;
+    } catch {
+      return false;
+    }
+  }
 
   try {
     renameSync(migratingPath, localGsd);

package/src/resources/extensions/gsd/migration-auto-check.ts

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import {
@@ -9,8 +9,8 @@ import {
 } from "./gsd-db.js";
 import { refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 import { parsePlan, parseRoadmap } from "./parsers-legacy.js";
+import { findMilestoneIds } from "./milestone-ids.js";
 import {
-  milestonesDir,
   resolveMilestoneFile,
   resolveSliceFile,
 } from "./paths.js";
@@ -90,6 +90,28 @@ function scanHasExtraIdentities(a: HierarchyScan, b: HierarchyScan): boolean {
   );
 }
 
+function paddedMilestoneId(id: string): string | null {
+  return /^\d+$/.test(id) ? `M${id.padStart(3, "0")}` : null;
+}
+
+function replaceSetPrefix(values: Set<string>, from: string, to: string): void {
+  for (const value of [...values]) {
+    if (value !== from && !value.startsWith(`${from}/`)) continue;
+    values.delete(value);
+    values.add(`${to}${value.slice(from.length)}`);
+  }
+}
+
+function alignNumericMarkdownIdsWithDb(markdownScan: HierarchyScan, dbScan: HierarchyScan): void {
+  for (const dbId of dbScan.milestones) {
+    const paddedId = paddedMilestoneId(dbId);
+    if (!paddedId || dbScan.milestones.has(paddedId) || !markdownScan.milestones.has(paddedId)) continue;
+    replaceSetPrefix(markdownScan.milestones, paddedId, dbId);
+    replaceSetPrefix(markdownScan.slices, paddedId, dbId);
+    replaceSetPrefix(markdownScan.tasks, paddedId, dbId);
+  }
+}
+
 /**
  * True when the DB holds any milestone/slice/task identity the markdown lacks —
  * i.e. a `/gsd recover --confirm` (markdown → DB) would DELETE authoritative DB
@@ -102,18 +124,9 @@ export function recoverWouldDeleteDbRows(basePath: string): boolean {
 }
 
 export function scanMarkdownHierarchy(basePath: string): HierarchyScan {
-  const root = milestonesDir(basePath);
-  if (!existsSync(root)) return emptyScan();
-
   const scan = emptyScan();
-  for (const entry of readdirSync(root, { withFileTypes: true })) {
-    if (!entry.isDirectory() || !/^M\d+/.test(entry.name)) continue;
-    // Use the CANONICAL milestone id (e.g. "M001" or "M001-a1b2c3"), matching
-    // scanDbHierarchy's milestone.id — not the raw directory name, which may
-    // carry a legacy descriptor (e.g. "M001-some-descriptor"). The canonical id
-    // both keys the identity sets AND resolves files correctly: resolveFile's
-    // prefix/legacy-pattern matching handles the descriptor dir either way.
-    const milestoneId = entry.name.match(/^(M\d+(?:-[a-z0-9]{6})?)/)?.[1] ?? entry.name;
+  // findMilestoneIds handles both flat-phase (NN-slug) and legacy (M###) dirs.
+  for (const milestoneId of findMilestoneIds(basePath)) {
     scan.counts.milestones++;
     scan.milestones.add(milestoneId);
 
@@ -194,6 +207,7 @@ export async function checkMarkdownHierarchyAgainstDb(
 
   const dbScan = scanDbHierarchy();
   const beforeDb = dbScan.counts;
+  alignNumericMarkdownIdsWithDb(markdownScan, dbScan);
 
   // Discussion-phase scratch: a milestone dir with no ROADMAP and no DB row is
   // a pre-registration discussion artifact (CONTEXT/CONTEXT-DRAFT only — the

package/src/resources/extensions/gsd/milestone-actions.ts

@@ -17,6 +17,7 @@ import {
   resolveMilestonePath,
   resolveMilestoneFile,
   buildMilestoneFileName,
+  relMilestoneFile,
 } from "./paths.js";
 import { invalidateAllCaches } from "./cache.js";
 import { loadQueueOrder, saveQueueOrder } from "./queue-order.js";
@@ -61,7 +62,8 @@ export function parkMilestone(basePath: string, milestoneId: string, reason: str
     if (summaryFile) return false;
   }
 
-  const parkedPath = join(mDir, buildMilestoneFileName(milestoneId, "PARKED"));
+  // Use relMilestoneFile for layout-aware path (legacy: M001-PARKED.md, flat-phase: 01-PARKED.md)
+  const parkedPath = join(basePath, relMilestoneFile(basePath, milestoneId, "PARKED"));
   if (existsSync(parkedPath)) return false; // already parked
 
   const content = [
@@ -100,7 +102,8 @@ export function unparkMilestone(basePath: string, milestoneId: string): boolean
   const mDir = resolveMilestonePath(basePath, milestoneId);
   if (!mDir || !existsSync(mDir)) return false;
 
-  const parkedPath = join(mDir, buildMilestoneFileName(milestoneId, "PARKED"));
+  // Use relMilestoneFile for layout-aware path (legacy: M001-PARKED.md, flat-phase: 01-PARKED.md)
+  const parkedPath = join(basePath, relMilestoneFile(basePath, milestoneId, "PARKED"));
   const hadParkedFile = existsSync(parkedPath);
   const dbThinksParked = isDbAvailable() && getMilestone(milestoneId)?.status === "parked";
 

package/src/resources/extensions/gsd/milestone-closeout.ts

@@ -26,6 +26,7 @@ import { logWarning } from "./workflow-logger.js";
 import { hasImplementationArtifacts } from "./milestone-implementation-evidence.js";
 import { buildCompleteMilestonePrompt } from "./auto-prompts.js";
 import { proveMilestoneCloseout } from "./milestone-closeout-proof.js";
+import { checkCloseoutConsistencyGate } from "./closeout-consistency-gate.js";
 import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
 import type { DispatchAction, DispatchContext } from "./auto-dispatch.js";
 import {
@@ -210,6 +211,16 @@ export async function evaluateCompleteMilestoneDispatch(
     }
   }
 
+  if (isDbAvailable()) {
+    // Repair only the missing-validation closeout case here; existing guards below
+    // and post-unit proof remain responsible for blocking incomplete closeouts.
+    checkCloseoutConsistencyGate(mid, {
+      allowOpenMilestone: true,
+      allowPassThroughValidation: true,
+      artifactBasePath: resolveCanonicalMilestoneRoot(basePath, mid),
+    });
+  }
+
   const validationFile = resolveMilestoneFile(basePath, mid, "VALIDATION");
   if (validationFile) {
     const validationContent = await loadFile(validationFile);
@@ -256,9 +267,9 @@ export async function evaluateCompleteMilestoneDispatch(
             const skippedByTrivialVariant = /trivial-scope pipeline variant/i.test(validationContent);
             const structuredMatch =
               validationContent.includes("Operational") &&
-              (validationContent.includes("MET") || validationContent.includes("N/A") || validationContent.includes("SATISFIED") || validationContent.includes("DEFERRED"));
+              (validationContent.includes("MET") || validationContent.includes("N/A") || validationContent.includes("SATISFIED") || validationContent.includes("DEFERRED") || validationContent.includes("PASS") || validationContent.includes("COVERED"));
             const proseMatch =
-              /[Oo]perational[\s\S]{0,500}?(?:✅|pass|verified|confirmed|met|complete|true|yes|addressed|covered|satisfied|partially|deferred|n\/a|not[\s-]+applicable)/i.test(validationContent);
+              /[Oo]perational[\s\S]{0,2000}?(?:✅|pass|verified|confirmed|met|complete|true|yes|addressed|covered|satisfied|partially|deferred|n\/a|not[\s-]+applicable)/i.test(validationContent);
             const hasOperationalCheck =
               skippedByMarker ||
               skippedByPreference ||