@opengsd/gsd-pi 1.8.1 → 1.9.0-dev.5c1a3ff2

package/dist/resources/extensions/gsd/db/writers/status.js

@@ -37,22 +37,29 @@ function requireDb() {
 export function applyStatusTransition(t) {
     const db = requireDb();
     const completedAt = t.completedAt ?? null;
+    const preserve = t.preserveCompletion ? 1 : 0;
     switch (t.entity) {
         case "task":
-            db.prepare(`UPDATE tasks SET status = :status, completed_at = :completed_at
+            db.prepare(`UPDATE tasks SET status = :status,
+           completed_at = CASE WHEN :preserve_completion = 1 AND tasks.completed_at IS NOT NULL
+                               THEN tasks.completed_at ELSE :completed_at END
          WHERE milestone_id = :milestone_id AND slice_id = :slice_id AND id = :id`).run({
                 ":status": t.status,
                 ":completed_at": completedAt,
+                ":preserve_completion": preserve,
                 ":milestone_id": t.milestoneId,
                 ":slice_id": t.sliceId,
                 ":id": t.taskId,
             });
             return;
         case "slice":
-            db.prepare(`UPDATE slices SET status = :status, completed_at = :completed_at
+            db.prepare(`UPDATE slices SET status = :status,
+           completed_at = CASE WHEN :preserve_completion = 1 AND slices.completed_at IS NOT NULL
+                               THEN slices.completed_at ELSE :completed_at END
          WHERE milestone_id = :milestone_id AND id = :id`).run({
                 ":status": t.status,
                 ":completed_at": completedAt,
+                ":preserve_completion": preserve,
                 ":milestone_id": t.milestoneId,
                 ":id": t.sliceId,
             });
@@ -63,7 +70,10 @@ export function applyStatusTransition(t) {
             if (currentStatus && isClosedStatus(currentStatus) && !isClosedStatus(t.status)) {
                 throw new Error(`Cannot update closed milestone ${t.milestoneId} from ${currentStatus} to ${t.status}; use gsd_milestone_reopen for an explicit reopen.`);
             }
-            db.prepare(`UPDATE milestones SET status = :status, completed_at = :completed_at WHERE id = :id`).run({ ":status": t.status, ":completed_at": completedAt, ":id": t.milestoneId });
+            db.prepare(`UPDATE milestones SET status = :status,
+           completed_at = CASE WHEN :preserve_completion = 1 AND milestones.completed_at IS NOT NULL
+                               THEN milestones.completed_at ELSE :completed_at END
+         WHERE id = :id`).run({ ":status": t.status, ":completed_at": completedAt, ":preserve_completion": preserve, ":id": t.milestoneId });
             return;
         }
     }

package/dist/resources/extensions/gsd/db-base-schema.js

@@ -221,6 +221,32 @@ export function createBaseSchemaObjects(db, hooks) {
       created_at TEXT NOT NULL DEFAULT '',
       FOREIGN KEY (milestone_id) REFERENCES milestones(id)
     )
+  `);
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS rework_briefs (
+      id TEXT PRIMARY KEY,
+      milestone_id TEXT NOT NULL DEFAULT '',
+      slice_id TEXT NOT NULL DEFAULT '',
+      task_id TEXT NOT NULL DEFAULT '',
+      created_at TEXT NOT NULL DEFAULT '',
+      updated_at TEXT NOT NULL DEFAULT ''
+    )
+  `);
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS rework_brief_findings (
+      brief_id TEXT NOT NULL,
+      finding_id TEXT NOT NULL,
+      severity TEXT NOT NULL DEFAULT 'blocking',
+      description TEXT NOT NULL DEFAULT '',
+      required_fix TEXT NOT NULL DEFAULT '',
+      verification_commands TEXT NOT NULL DEFAULT '[]',
+      status TEXT NOT NULL DEFAULT 'pending',
+      evidence TEXT NOT NULL DEFAULT '',
+      decision_ref TEXT NOT NULL DEFAULT '',
+      updated_at TEXT NOT NULL DEFAULT '',
+      PRIMARY KEY (brief_id, finding_id),
+      FOREIGN KEY (brief_id) REFERENCES rework_briefs(id)
+    )
   `);
     db.exec(`
     CREATE TABLE IF NOT EXISTS assessments (
@@ -336,6 +362,8 @@ export function createBaseSchemaObjects(db, hooks) {
   `);
     db.exec("CREATE INDEX IF NOT EXISTS idx_memories_active ON memories(superseded_by)");
     db.exec("CREATE INDEX IF NOT EXISTS idx_replan_history_milestone ON replan_history(milestone_id, created_at)");
+    db.exec("CREATE INDEX IF NOT EXISTS idx_rework_briefs_task ON rework_briefs(milestone_id, slice_id, task_id)");
+    db.exec("CREATE INDEX IF NOT EXISTS idx_rework_findings_status ON rework_brief_findings(brief_id, severity, status)");
     db.exec("CREATE INDEX IF NOT EXISTS idx_tasks_active ON tasks(milestone_id, slice_id, status)");
     db.exec("CREATE INDEX IF NOT EXISTS idx_slices_active ON slices(milestone_id, status)");
     db.exec("CREATE INDEX IF NOT EXISTS idx_milestones_status ON milestones(status)");

package/dist/resources/extensions/gsd/db-migration-steps.js

@@ -418,3 +418,33 @@ export function applyMigrationV22QualityGateRepair(db, hooks) {
     ensureColumn(db, "quality_gates", "scope", "ALTER TABLE quality_gates ADD COLUMN scope TEXT NOT NULL DEFAULT 'slice'");
     ensureColumn(db, "assessments", "scope", "ALTER TABLE assessments ADD COLUMN scope TEXT NOT NULL DEFAULT ''");
 }
+export function applyMigrationV30ReworkBriefs(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS rework_briefs (
+      id TEXT PRIMARY KEY,
+      milestone_id TEXT NOT NULL DEFAULT '',
+      slice_id TEXT NOT NULL DEFAULT '',
+      task_id TEXT NOT NULL DEFAULT '',
+      created_at TEXT NOT NULL DEFAULT '',
+      updated_at TEXT NOT NULL DEFAULT ''
+    )
+  `);
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS rework_brief_findings (
+      brief_id TEXT NOT NULL,
+      finding_id TEXT NOT NULL,
+      severity TEXT NOT NULL DEFAULT 'blocking',
+      description TEXT NOT NULL DEFAULT '',
+      required_fix TEXT NOT NULL DEFAULT '',
+      verification_commands TEXT NOT NULL DEFAULT '[]',
+      status TEXT NOT NULL DEFAULT 'pending',
+      evidence TEXT NOT NULL DEFAULT '',
+      decision_ref TEXT NOT NULL DEFAULT '',
+      updated_at TEXT NOT NULL DEFAULT '',
+      PRIMARY KEY (brief_id, finding_id),
+      FOREIGN KEY (brief_id) REFERENCES rework_briefs(id)
+    )
+  `);
+    db.exec("CREATE INDEX IF NOT EXISTS idx_rework_briefs_task ON rework_briefs(milestone_id, slice_id, task_id)");
+    db.exec("CREATE INDEX IF NOT EXISTS idx_rework_findings_status ON rework_brief_findings(brief_id, severity, status)");
+}

package/dist/resources/extensions/gsd/db-schema-metadata.js

@@ -12,8 +12,11 @@ export function ensureColumn(db, table, column, ddl) {
         db.exec(ddl);
 }
 export function getCurrentSchemaVersion(db) {
+    // MAX(version) on an empty table returns a row whose value is NULL —
+    // treat that (and any non-numeric value) as version 0, not NULL-as-number.
     const row = db.prepare("SELECT MAX(version) as v FROM schema_version").get();
-    return row ? row["v"] : 0;
+    const v = row?.["v"];
+    return typeof v === "number" ? v : 0;
 }
 export function recordSchemaVersion(db, version) {
     db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({

package/dist/resources/extensions/gsd/docs/preferences-reference.md

@@ -128,7 +128,7 @@ Diagnostics record the file path, scope (global/project), severity (error/warnin
   - Two equivalent ways to set it: inline as `models.<phase>.thinking`, or as a separate `thinking:` block keyed by phase. For the same phase, the inline value wins over the block; project preferences win over global; a phase that's unset inherits via the same sibling chain as `models` (e.g. `discuss → planning`).
   - If no thinking is configured for a phase, the session level (set via `/model`) is used, exactly as before — this is fully backward-compatible.
   - `execute-task` (code-writing) has a measured reasoning floor of `medium`: at lower levels models stop planning edits and thrash on file re-reads. The floor applies to the session/default path. An **explicit** `execution` thinking level bypasses the floor and is honored verbatim (with a one-time advisory) — set `execution: low` deliberately if you want it.
-  - Levels a model can't support are clamped to the nearest supported level at dispatch and never sent to the provider, so a model/level mismatch never fails a unit mid-run. `xhigh` is only honored by select model families.
+  - Levels a model can't support are clamped to the nearest supported level at dispatch and never sent to the provider, so a model/level mismatch never fails a unit mid-run. `xhigh` support is model-dependent; current examples include OpenAI Codex Max models and Claude Sonnet 5 on Amazon Bedrock.
 
 - `skill_staleness_days`: number — skills unused for this many days get deprioritized during discovery. Set to `0` to disable staleness tracking. Default: `60`.
 
@@ -357,6 +357,28 @@ In `"parent"` mode, slice/task `targetRepositories` default to the declared chil
   - `"replace"` requires `prompt`.
   - `"skip"` is valid with no additional fields.
 
+- `planning_subagents`: object — project-local widening for read-only planning subagent dispatch. Supported unit keys are `plan-milestone` and `plan-slice`; each has:
+  - `allowed`: string[] — additional planning-safe agents for that unit.
+
+  Agents must already be classified by GSD as read-only planning specialists: `mnemo`, `scout`, `planner`, `reviewer`, `security`, or `tester`. The write gate still blocks source writes outside `.gsd/**`, unrestricted bash, stale subagent calls without agent identities, agents outside the global read-only registry, and agents not listed for the active unit.
+
+  Example:
+
+  ```yaml
+  planning_subagents:
+    plan-milestone:
+      allowed:
+        - scout
+        - planner
+        - security
+    plan-slice:
+      allowed:
+        - scout
+        - planner
+        - reviewer
+        - security
+  ```
+
   **Known unit types for `before`/`after`:** `research-milestone`, `plan-milestone`, `research-slice`, `plan-slice`, `execute-task`, `complete-slice`, `replan-slice`, `reassess-roadmap`, `run-uat`.
 
 - `experimental`: opt-in experimental features. All features here are **off by default** — you must explicitly set each one to `true` to enable it. Features in this block may change or be removed without a deprecation cycle while in experimental status. Keys:
@@ -482,13 +504,13 @@ Inline form — thinking pinned alongside the model:
 version: 1
 models:
   planning:
-    model: openai-codex/gpt-5.4
+    model: bedrock/global.anthropic.claude-sonnet-5
     thinking: xhigh
   execution:
-    model: openai-codex/gpt-5.4
+    model: bedrock/global.anthropic.claude-sonnet-5
     thinking: low      # explicit → bypasses the execute-task medium floor
   validation:
-    model: openai-codex/gpt-5.4
+    model: bedrock/global.anthropic.claude-sonnet-5
     thinking: high
 ---
 ```

package/dist/resources/extensions/gsd/doctor-engine-checks.js

@@ -3,7 +3,7 @@ import { isAbsolute, join, relative, sep } from "node:path";
 import { deleteArtifactByPath, getAllMilestones, getMilestoneSlices, getSliceTasks, isDbAvailable, isMemoriesFtsAvailable, repairTaskCompletionFromSummary, _getAdapter, } from "./gsd-db.js";
 import { MEMORIES_FTS_REBUILT_KEY } from "./db-memory-fts-schema.js";
 import { isAfter, latestExplicitReopenAt } from "./milestone-reopen-events.js";
-import { buildTaskFileName, gsdProjectionRoot, gsdRoot, resolveGsdPathContract, resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, } from "./paths.js";
+import { gsdProjectionRoot, gsdRoot, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile, resolveTaskFile, } from "./paths.js";
 import { deriveState } from "./state.js";
 import { isClosedStatus } from "./status-guards.js";
 import { workflowEventLogPath } from "./workflow-event-ledger.js";
@@ -152,11 +152,8 @@ function resolveFlatPhaseArtifactDiskPath(basePath, row) {
     if (!artifactType)
         return null;
     if (row.slice_id && row.task_id) {
-        const phaseDir = resolveMilestonePath(basePath, row.milestone_id);
-        if (!phaseDir || !isFlatPhaseDiskPath(basePath, phaseDir))
-            return null;
-        const candidate = join(phaseDir, buildTaskFileName(row.task_id, artifactType));
-        return existsSync(candidate) ? candidate : null;
+        const candidate = resolveTaskFile(basePath, row.milestone_id, row.slice_id, row.task_id, artifactType);
+        return candidate && isFlatPhaseDiskPath(basePath, candidate) ? candidate : null;
     }
     const candidate = row.slice_id
         ? resolveSliceFile(basePath, row.milestone_id, row.slice_id, artifactType)

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,58 @@ 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 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 +174,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 +190,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 +300,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 +342,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 +392,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).

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 {