@opengsd/gsd-pi 1.8.1 → 1.9.0-dev.97ef11e3

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

@@ -4,12 +4,12 @@
 import { cpSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { renderAllFromDb, renderRoadmapFromDb } from "./markdown-renderer.js";
-import { deleteArtifactsByPathPrefix, getAllMilestones, getMilestoneSlices } from "./gsd-db.js";
+import { deleteArtifactByPath, deleteArtifactsByPathPrefix, getAllMilestones, getArtifactsByPathPrefix, 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";
+import { canonicalPhaseDirName, dirIsContentBearingLegacyMilestone, gsdProjectionRoot, 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 };
@@ -60,6 +60,46 @@ function expectedPhaseDirs(basePath) {
     return getAllMilestones().map((milestone) => resolveMilestonePath(basePath, milestone.id) ??
         join(milestonesDir(basePath), canonicalPhaseDirName(milestone.id, milestone.title)));
 }
+/**
+ * Return the most-recent existing `.gsd-backups/migrate-<ts>/` snapshot, or null.
+ *
+ * The flat-phase migration can re-fire on later dispatches when the legacy
+ * `.gsd/milestones/` layout reappears (e.g. a marker-key mismatch re-triggers a
+ * whole-tree re-import — issue #1292). The DB was already reconciled from that
+ * tree before the backup step runs, so re-snapshotting an identical legacy tree
+ * on every dispatch only leaks a fresh `migrate-<ts>/` directory each time. When
+ * a prior snapshot already exists we reuse it as the rollback fallback instead
+ * of creating a duplicate, bounding the accumulation to one recovery copy.
+ */
+function existingMigrateBackup(basePath) {
+    const backupRoot = join(basePath, ".gsd-backups");
+    if (!existsSync(backupRoot))
+        return null;
+    try {
+        let latest = null;
+        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 (!hasLegacyMilestoneSubdirs(dirPath))
+                    continue;
+                if (!latest || st.mtimeMs > latest.mtimeMs)
+                    latest = { path: dirPath, mtimeMs: st.mtimeMs };
+            }
+            catch {
+                // Non-fatal: skip unreadable entries.
+            }
+        }
+        return latest?.path ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 function hasLegacyMilestoneSubdirs(dirPath) {
     if (!existsSync(dirPath))
         return false;
@@ -70,7 +110,69 @@ function hasLegacyMilestoneSubdirs(dirPath) {
         return false;
     }
 }
-function rollbackPartialMigration(basePath, backupDir, migratingPath) {
+function backupFlatProjectionIfPresent(basePath, phasesPath, backupDir) {
+    if (!existsSync(phasesPath))
+        return;
+    const phaseBackupDir = join(backupDir, "__phases");
+    try {
+        mkdirSync(backupDir, { recursive: true });
+        if (existsSync(phaseBackupDir)) {
+            removePathWithRetries(phaseBackupDir);
+        }
+        fsOps.cpSync(phasesPath, phaseBackupDir, { recursive: true, force: true });
+    }
+    catch (err) {
+        logWarning("migration", `flat-phase projection backup failed: ${err.message}`);
+        throw err;
+    }
+}
+function isInsideFlatProjectionBackup(backupDir, src) {
+    const phaseBackupDir = join(backupDir, "__phases");
+    return src === phaseBackupDir || src.startsWith(`${phaseBackupDir}/`) || src.startsWith(`${phaseBackupDir}\\`);
+}
+function removeFlatProjectionBackup(backupDir) {
+    const phaseBackupDir = join(backupDir, "__phases");
+    if (!existsSync(phaseBackupDir))
+        return;
+    try {
+        removePathWithRetries(phaseBackupDir);
+    }
+    catch (err) {
+        logWarning("migration", `flat-phase migration succeeded but could not remove temporary ${LAYOUT_SEGMENTS.level1}/ backup: ${err.message}`);
+    }
+}
+function restoreFlatProjectionFromBackup(basePath, backupDir) {
+    const phaseBackupDir = join(backupDir, "__phases");
+    if (!existsSync(phaseBackupDir))
+        return;
+    const phasesPath = join(basePath, ".gsd", LAYOUT_SEGMENTS.level1);
+    try {
+        if (existsSync(phasesPath)) {
+            removePathWithRetries(phasesPath);
+        }
+        mkdirSync(join(basePath, ".gsd"), { recursive: true });
+        cpSync(phaseBackupDir, phasesPath, { recursive: true });
+    }
+    catch (restoreErr) {
+        logWarning("migration", `rollback: could not restore ${LAYOUT_SEGMENTS.level1}/ from backup: ${restoreErr.message}`);
+    }
+}
+function pruneStaleFlatPhaseArtifactRows(basePath) {
+    const projectionRoot = gsdProjectionRoot(basePath);
+    let pruned = 0;
+    for (const row of getArtifactsByPathPrefix(`${LAYOUT_SEGMENTS.level1}/`)) {
+        if (existsSync(join(projectionRoot, row.path)))
+            continue;
+        const staleTaskPlan = row.artifact_type.toUpperCase() === "PLAN" && Boolean(row.task_id);
+        const skippedEmptyArtifact = row.full_content.trim() === "";
+        if (!staleTaskPlan && !skippedEmptyArtifact)
+            continue;
+        deleteArtifactByPath(row.path);
+        pruned++;
+    }
+    return pruned;
+}
+function rollbackPartialMigration(basePath, backupDir, migratingPath, backupCreatedThisRun = true) {
     // Remove the partially-written phases/ dir.
     try {
         removePathWithRetries(join(basePath, ".gsd", LAYOUT_SEGMENTS.level1));
@@ -83,7 +185,7 @@ function rollbackPartialMigration(basePath, backupDir, migratingPath) {
     // preserved migrating tree (the sole surviving data source) and must never be
     // removed here. Deleting the backup after a successful rollback keeps the gate
     // from leaking one .gsd-backups/migrate-<ts>/ per session_start.
-    const isDisposableBackup = Boolean(backupDir) && backupDir !== migratingPath;
+    const isDisposableBackup = Boolean(backupDir) && backupDir !== migratingPath && backupCreatedThisRun;
     const cleanupBackup = () => {
         if (!isDisposableBackup || !existsSync(backupDir))
             return;
@@ -99,11 +201,16 @@ function rollbackPartialMigration(basePath, backupDir, migratingPath) {
     try {
         if (migratingPath && existsSync(migratingPath) && !existsSync(milestonesPath)) {
             movePathWithCopyDeleteFallback(migratingPath, milestonesPath);
+            restoreFlatProjectionFromBackup(basePath, backupDir);
             cleanupBackup();
             return;
         }
         if (existsSync(backupDir)) {
-            cpSync(backupDir, milestonesPath, { recursive: true });
+            cpSync(backupDir, milestonesPath, {
+                recursive: true,
+                filter: (src) => !isInsideFlatProjectionBackup(backupDir, src),
+            });
+            restoreFlatProjectionFromBackup(basePath, backupDir);
             cleanupBackup();
         }
         if (migratingPath && existsSync(migratingPath)) {
@@ -204,17 +311,33 @@ export async function migrateToFlatPhase(basePath) {
         return;
     }
     let backupDir = migratingPath;
+    let backupCreatedThisRun = false;
     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 });
+        // 2. Backup (only reached when the DB has rows and migration will proceed).
+        // migrateFromMarkdown above already reconciled the legacy tree into the DB,
+        // so its content is safely persisted. If a prior successful migration
+        // already snapshotted the legacy tree, a re-fire of this gate (issue #1292:
+        // marker-key mismatch re-importing the whole tree at dispatch boundaries)
+        // must not leak a fresh .gsd-backups/migrate-<ts>/ every dispatch. Treat it
+        // as a marker-refresh re-projection: reuse the existing snapshot as the
+        // rollback fallback instead of creating a duplicate.
+        const priorBackup = existingMigrateBackup(basePath);
+        if (priorBackup) {
+            backupDir = priorBackup;
+            logWarning("migration", `flat-phase migration re-fired; reusing existing backup ${priorBackup} instead of re-snapshotting (issue #1292)`);
         }
-        catch (err) {
-            logWarning("migration", `flat-phase migration backup failed: ${err.message}`);
-            throw err;
+        else {
+            const ts = Date.now();
+            backupDir = join(basePath, ".gsd-backups", `migrate-${ts}`);
+            try {
+                mkdirSync(join(basePath, ".gsd-backups"), { recursive: true });
+                cpSync(milestonesPath, backupDir, { recursive: true });
+                backupCreatedThisRun = true;
+            }
+            catch (err) {
+                logWarning("migration", `flat-phase migration backup failed: ${err.message}`);
+                throw err;
+            }
         }
         if (existsSync(migratingPath)) {
             removePathWithRetries(migratingPath);
@@ -230,14 +353,34 @@ export async function migrateToFlatPhase(basePath) {
             throw err;
         }
     }
+    else {
+        const priorBackup = existingMigrateBackup(basePath);
+        if (priorBackup) {
+            backupDir = priorBackup;
+        }
+        else {
+            const ts = Date.now();
+            backupDir = join(basePath, ".gsd-backups", `migrate-${ts}`);
+            try {
+                mkdirSync(join(basePath, ".gsd-backups"), { recursive: true });
+                cpSync(migratingPath, backupDir, { recursive: true });
+                backupCreatedThisRun = true;
+            }
+            catch (err) {
+                logWarning("migration", `flat-phase migration backup failed during resume: ${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 {
+        backupFlatProjectionIfPresent(basePath, phasesPath, backupDir);
         removePathWithRetries(phasesPath);
     }
     catch (err) {
         logWarning("migration", `failed to clear stale phases/ before render: ${err.message}`);
-        rollbackPartialMigration(basePath, backupDir, migratingPath);
+        rollbackPartialMigration(basePath, backupDir, migratingPath, backupCreatedThisRun);
         throw err;
     }
     // 4. Render flat-phase from DB
@@ -260,35 +403,38 @@ export async function migrateToFlatPhase(basePath) {
     }
     catch (err) {
         logWarning("migration", `flat-phase render failed: ${err.message}`);
-        rollbackPartialMigration(basePath, backupDir, migratingPath);
+        rollbackPartialMigration(basePath, backupDir, migratingPath, backupCreatedThisRun);
         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);
+        rollbackPartialMigration(basePath, backupDir, migratingPath, backupCreatedThisRun);
         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);
+        rollbackPartialMigration(basePath, backupDir, migratingPath, backupCreatedThisRun);
         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);
+        rollbackPartialMigration(basePath, backupDir, migratingPath, backupCreatedThisRun);
         throw new Error("flat-phase migration verification failed: no artifacts rendered");
     }
     // 6. Verified — prune legacy artifact rows now that renderAllFromDb has
-    // re-inserted flat-phase rows for artifacts that still have files.
+    // re-inserted flat-phase rows for artifacts that still have files. Also
+    // prune flat-phase rows whose files the renderer intentionally no longer
+    // materializes, such as task PLAN files and empty-content artifacts.
     try {
         deleteArtifactsByPathPrefix("milestones/");
+        pruneStaleFlatPhaseArtifactRows(basePath);
     }
     catch (err) {
         logWarning("migration", `flat-phase migration could not prune legacy artifact rows: ${err.message}`);
-        rollbackPartialMigration(basePath, backupDir, migratingPath);
+        rollbackPartialMigration(basePath, backupDir, migratingPath, backupCreatedThisRun);
         throw err;
     }
     // 7. Remove the renamed legacy tree (backup already on disk).
@@ -298,4 +444,5 @@ export async function migrateToFlatPhase(basePath) {
     catch (err) {
         logWarning("migration", `flat-phase migration succeeded but could not remove ${LEGACY_MIGRATING_SEGMENT}: ${err.message}`);
     }
+    removeFlatProjectionBackup(backupDir);
 }

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

@@ -229,10 +229,15 @@ export const RUNTIME_EXCLUSION_PATHS = [
 const runtimeFilesCleanedUpRepos = new Set();
 // ─── Integration Branch Metadata ───────────────────────────────────────────
 /**
- * Path to the milestone metadata file that stores the integration branch.
- * Format: .gsd/milestones/<MID>/<MID>-META.json
+ * Path to the milestone integration-branch metadata file.
+ * Format: .gsd/<MID>-META.json  (deliberately OUTSIDE milestones/<MID>/ so it
+ * cannot poison isLegacyMilestonesLayout — see ADR-045).
  */
-function milestoneMetaPath(basePath, milestoneId) {
+export function milestoneMetaPath(basePath, milestoneId) {
+    return join(gsdRoot(basePath), `${milestoneId}-META.json`);
+}
+/** Legacy location (pre-ADR-045). Read-only fallback for existing on-disk trees. */
+function legacyMilestoneMetaPath(basePath, milestoneId) {
     return join(gsdRoot(basePath), "milestones", milestoneId, `${milestoneId}-META.json`);
 }
 /**
@@ -241,9 +246,13 @@ function milestoneMetaPath(basePath, milestoneId) {
  */
 export function readIntegrationBranch(basePath, milestoneId) {
     try {
-        const metaFile = milestoneMetaPath(basePath, milestoneId);
-        if (!existsSync(metaFile))
-            return null;
+        let metaFile = milestoneMetaPath(basePath, milestoneId);
+        if (!existsSync(metaFile)) {
+            const legacy = legacyMilestoneMetaPath(basePath, milestoneId);
+            if (!existsSync(legacy))
+                return null;
+            metaFile = legacy;
+        }
         const data = JSON.parse(readFileSync(metaFile, "utf-8"));
         const branch = data?.integrationBranch;
         if (typeof branch === "string" && branch.trim() !== "" && VALID_BRANCH_NAME.test(branch)) {
@@ -295,7 +304,10 @@ export function writeIntegrationBranch(basePath, milestoneId, branch) {
     if (existingBranch === branch)
         return;
     const metaFile = milestoneMetaPath(basePath, milestoneId);
-    mkdirSync(join(gsdRoot(basePath), "milestones", milestoneId), { recursive: true });
+    // Ensure the flat .gsd/ root exists (never milestones/<MID>/ — that would
+    // poison layout detection, ADR-045). In production .gsd/ already exists; this
+    // guards fresh trees so the write below can't ENOENT.
+    mkdirSync(gsdRoot(basePath), { recursive: true });
     // Merge with existing metadata if present
     let existing = {};
     try {