@opengsd/gsd-pi 1.8.1 → 1.9.0

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/gsd-db.js

@@ -19,7 +19,8 @@ import { createHash } from "node:crypto";
 import { GSDError, GSD_STALE_STATE } from "./errors.js";
 import { getGateIdsForTurn } from "./gate-registry.js";
 import { logWarning } from "./workflow-logger.js";
-import { isClosedStatus } from "./status-guards.js";
+import { rowToArtifact } from "./db-milestone-artifact-rows.js";
+import { isClosedStatus, toStatus } from "./status-guards.js";
 // Connection ownership, lifecycle, schema/migrations and transaction
 // primitives now live in the engine; re-export the full public surface so
 // existing `from "./gsd-db.js"` imports keep working.
@@ -336,6 +337,11 @@ export function upsertSlicePlanning(milestoneId, sliceId, planning) {
 export function insertTask(t) {
     if (!getDbOrNull())
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    // Stamp completed_at for every terminal-complete alias (complete/done/closed),
+    // not just two literals — a task imported as "closed" is completed and must
+    // carry a timestamp. NOT for "skipped": a skipped task was never completed
+    // (cascade writers set its completed_at = NULL).
+    const isCompleteAlias = t.status != null && toStatus(t.status) === "complete";
     getDbOrNull().prepare(`INSERT INTO tasks (
       milestone_id, slice_id, id, title, status, one_liner, narrative,
       verification_result, duration, completed_at, blocker_discovered,
@@ -385,7 +391,7 @@ export function insertTask(t) {
         ":narrative": t.narrative ?? "",
         ":verification_result": t.verificationResult ?? "",
         ":duration": t.duration ?? "",
-        ":completed_at": t.status === "done" || t.status === "complete" ? new Date().toISOString() : null,
+        ":completed_at": isCompleteAlias ? new Date().toISOString() : null,
         ":blocker_discovered": t.blockerDiscovered ? 1 : 0,
         ":deviations": t.deviations ?? "",
         ":known_issues": t.knownIssues ?? "",
@@ -401,7 +407,7 @@ export function insertTask(t) {
         ":observability_impact": t.planning?.observabilityImpact ?? "",
         ":full_plan_md": t.planning?.fullPlanMd ?? "",
         ":sequence": t.sequence ?? 0,
-        ":preserve_completion": t.preserveCompletionMetadata && (t.status === "complete" || t.status === "done") ? 1 : 0,
+        ":preserve_completion": t.preserveCompletionMetadata && isCompleteAlias ? 1 : 0,
         ":target_repositories": JSON.stringify(t.planning?.targetRepositories ?? []),
         ":raw_target_repositories": t.planning && "targetRepositories" in t.planning
             ? JSON.stringify(t.planning.targetRepositories ?? [])
@@ -498,8 +504,8 @@ export function upsertTaskPlanning(milestoneId, sliceId, taskId, planning) {
         ":target_repositories": planning.targetRepositories ? JSON.stringify(planning.targetRepositories) : null,
     });
 }
-export function updateSliceStatus(milestoneId, sliceId, status, completedAt) {
-    applyStatusTransition({ entity: "slice", milestoneId, sliceId, status, completedAt });
+export function updateSliceStatus(milestoneId, sliceId, status, completedAt, preserveCompletion) {
+    applyStatusTransition({ entity: "slice", milestoneId, sliceId, status, completedAt, preserveCompletion });
 }
 export function setTaskSummaryMd(milestoneId, sliceId, taskId, md) {
     if (!getDbOrNull())
@@ -611,8 +617,8 @@ function writeMilestoneStatus(milestoneId, status, completedAt) {
  * advance planned milestones. They may not reopen a closed milestone; callers
  * must use reopenMilestoneStatus(), which is reserved for gsd_milestone_reopen.
  */
-export function updateMilestoneStatus(milestoneId, status, completedAt) {
-    applyStatusTransition({ entity: "milestone", milestoneId, status, completedAt });
+export function updateMilestoneStatus(milestoneId, status, completedAt, preserveCompletion) {
+    applyStatusTransition({ entity: "milestone", milestoneId, status, completedAt, preserveCompletion });
 }
 /**
  * Explicit closed -> active transition for gsd_milestone_reopen only.
@@ -657,6 +663,128 @@ export function insertReplanHistory(entry) {
         ":created_at": new Date().toISOString(),
     });
 }
+function reworkBriefIdFromTask(milestoneId, sliceId, taskId) {
+    return `RB-${milestoneId}-${sliceId}-${taskId}`;
+}
+function normalizeReworkStatus(status) {
+    const normalized = String(status ?? "pending");
+    if (normalized === "resolved" || normalized === "deferred-with-override") {
+        return normalized;
+    }
+    return "pending";
+}
+function rowToReworkFinding(row) {
+    let verificationCommands = [];
+    try {
+        const parsed = JSON.parse(String(row["verification_commands"] ?? "[]"));
+        verificationCommands = Array.isArray(parsed) ? parsed.map(String) : [];
+    }
+    catch {
+        verificationCommands = [];
+    }
+    return {
+        brief_id: String(row["brief_id"] ?? ""),
+        finding_id: String(row["finding_id"] ?? ""),
+        severity: String(row["severity"] ?? "blocking") === "advisory" ? "advisory" : "blocking",
+        description: String(row["description"] ?? ""),
+        required_fix: String(row["required_fix"] ?? ""),
+        verification_commands: verificationCommands,
+        status: normalizeReworkStatus(row["status"]),
+        evidence: String(row["evidence"] ?? ""),
+        decision_ref: String(row["decision_ref"] ?? ""),
+    };
+}
+export function saveReworkBrief(entry) {
+    if (!getDbOrNull())
+        throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    const briefId = entry.briefId?.trim() || reworkBriefIdFromTask(entry.milestoneId, entry.sliceId, entry.taskId);
+    const now = new Date().toISOString();
+    transaction(() => {
+        getDbOrNull().prepare(`INSERT INTO rework_briefs (id, milestone_id, slice_id, task_id, created_at, updated_at)
+       VALUES (:id, :mid, :sid, :tid, :created_at, :updated_at)
+       ON CONFLICT(id) DO UPDATE SET
+         milestone_id = :mid,
+         slice_id = :sid,
+         task_id = :tid,
+         updated_at = :updated_at`).run({
+            ":id": briefId,
+            ":mid": entry.milestoneId,
+            ":sid": entry.sliceId,
+            ":tid": entry.taskId,
+            ":created_at": now,
+            ":updated_at": now,
+        });
+        getDbOrNull().prepare("DELETE FROM rework_brief_findings WHERE brief_id = :id").run({ ":id": briefId });
+        const stmt = getDbOrNull().prepare(`INSERT INTO rework_brief_findings (
+         brief_id, finding_id, severity, description, required_fix, verification_commands,
+         status, evidence, decision_ref, updated_at
+       ) VALUES (
+         :brief_id, :finding_id, :severity, :description, :required_fix, :verification_commands,
+         :status, :evidence, :decision_ref, :updated_at
+       )`);
+        for (const finding of entry.findings) {
+            stmt.run({
+                ":brief_id": briefId,
+                ":finding_id": finding.findingId,
+                ":severity": finding.severity,
+                ":description": finding.description,
+                ":required_fix": finding.requiredFix,
+                ":verification_commands": JSON.stringify(finding.verificationCommands),
+                ":status": finding.status ?? "pending",
+                ":evidence": finding.evidence ?? "",
+                ":decision_ref": finding.decisionRef ?? "",
+                ":updated_at": now,
+            });
+        }
+    });
+    return { briefId };
+}
+export function getBlockingReworkFindingsForTask(milestoneId, sliceId, taskId) {
+    if (!getDbOrNull())
+        return [];
+    const rows = getDbOrNull().prepare(`SELECT f.*
+     FROM rework_brief_findings f
+     JOIN rework_briefs b ON b.id = f.brief_id
+     WHERE b.milestone_id = :mid
+       AND b.slice_id = :sid
+       AND b.task_id = :tid
+       AND f.severity = 'blocking'
+     ORDER BY b.created_at, f.finding_id`).all({ ":mid": milestoneId, ":sid": sliceId, ":tid": taskId });
+    return rows.map(rowToReworkFinding);
+}
+export function getUnresolvedBlockingReworkFindingsForTask(milestoneId, sliceId, taskId) {
+    return getBlockingReworkFindingsForTask(milestoneId, sliceId, taskId)
+        .filter((finding) => finding.status === "pending");
+}
+export function applyReworkResolutions(resolutions) {
+    if (!getDbOrNull())
+        throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    const now = new Date().toISOString();
+    const stmt = getDbOrNull().prepare(`UPDATE rework_brief_findings
+     SET status = :status,
+         evidence = :evidence,
+         decision_ref = :decision_ref,
+         updated_at = :updated_at
+     WHERE finding_id = :finding_id
+       AND brief_id IN (
+         SELECT id FROM rework_briefs
+         WHERE milestone_id = :mid AND slice_id = :sid AND task_id = :tid
+       )`);
+    transaction(() => {
+        for (const resolution of resolutions) {
+            stmt.run({
+                ":status": resolution.status,
+                ":evidence": resolution.evidence,
+                ":decision_ref": resolution.decisionRef ?? "",
+                ":updated_at": now,
+                ":finding_id": resolution.findingId,
+                ":mid": resolution.milestoneId,
+                ":sid": resolution.sliceId,
+                ":tid": resolution.taskId,
+            });
+        }
+    });
+}
 export function insertAssessment(entry) {
     if (!getDbOrNull())
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
@@ -767,44 +895,51 @@ export function saveGateResult(g) {
     if (!getDbOrNull())
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
     const evaluatedAt = new Date().toISOString();
-    const result = getDbOrNull().prepare(`UPDATE quality_gates
-     SET status = 'complete', verdict = :verdict, rationale = :rationale,
-         findings = :findings, evaluated_at = :evaluated_at
-     WHERE milestone_id = :mid AND slice_id = :sid AND gate_id = :gid
-       AND (task_id = :tid OR (:tid = '' AND task_id IS NULL))`).run({
-        ":mid": g.milestoneId,
-        ":sid": g.sliceId,
-        ":gid": g.gateId,
-        ":tid": g.taskId ?? "",
-        ":verdict": g.verdict,
-        ":rationale": g.rationale,
-        ":findings": g.findings,
-        ":evaluated_at": evaluatedAt,
-    });
-    if ((result.changes ?? 0) === 0) {
-        throw new GSDError(GSD_STALE_STATE, `quality gate row not found for ${g.milestoneId}/${g.sliceId}/${g.gateId}${g.taskId ? `/${g.taskId}` : ""}`);
-    }
-    const outcome = g.verdict === "pass"
-        ? "pass"
-        : g.verdict === "omitted"
-            ? "manual-attention"
-            : "fail";
-    insertGateRun({
-        traceId: `quality-gate:${g.milestoneId}:${g.sliceId}`,
-        turnId: `gate:${g.gateId}:${g.taskId ?? "slice"}`,
-        gateId: g.gateId,
-        gateType: "quality-gate",
-        milestoneId: g.milestoneId,
-        sliceId: g.sliceId,
-        taskId: g.taskId ?? undefined,
-        outcome,
-        failureClass: outcome === "fail" ? "verification" : outcome === "manual-attention" ? "manual-attention" : "none",
-        rationale: g.rationale,
-        findings: g.findings,
-        attempt: 1,
-        maxAttempts: 1,
-        retryable: false,
-        evaluatedAt,
+    // Atomic: the gate verdict UPDATE and the gate_runs ledger INSERT must commit
+    // together. As two autocommits, a crash between them records a completed gate
+    // with no ledger row (the row Recovery Classification reads). transaction()
+    // is re-entrant, so callers already inside a transaction are safe. The
+    // throw-on-zero-changes stays inside so a missing gate row rolls back cleanly.
+    transaction(() => {
+        const result = getDbOrNull().prepare(`UPDATE quality_gates
+       SET status = 'complete', verdict = :verdict, rationale = :rationale,
+           findings = :findings, evaluated_at = :evaluated_at
+       WHERE milestone_id = :mid AND slice_id = :sid AND gate_id = :gid
+         AND (task_id = :tid OR (:tid = '' AND task_id IS NULL))`).run({
+            ":mid": g.milestoneId,
+            ":sid": g.sliceId,
+            ":gid": g.gateId,
+            ":tid": g.taskId ?? "",
+            ":verdict": g.verdict,
+            ":rationale": g.rationale,
+            ":findings": g.findings,
+            ":evaluated_at": evaluatedAt,
+        });
+        if ((result.changes ?? 0) === 0) {
+            throw new GSDError(GSD_STALE_STATE, `quality gate row not found for ${g.milestoneId}/${g.sliceId}/${g.gateId}${g.taskId ? `/${g.taskId}` : ""}`);
+        }
+        const outcome = g.verdict === "pass"
+            ? "pass"
+            : g.verdict === "omitted"
+                ? "manual-attention"
+                : "fail";
+        insertGateRun({
+            traceId: `quality-gate:${g.milestoneId}:${g.sliceId}`,
+            turnId: `gate:${g.gateId}:${g.taskId ?? "slice"}`,
+            gateId: g.gateId,
+            gateType: "quality-gate",
+            milestoneId: g.milestoneId,
+            sliceId: g.sliceId,
+            taskId: g.taskId ?? undefined,
+            outcome,
+            failureClass: outcome === "fail" ? "verification" : outcome === "manual-attention" ? "manual-attention" : "none",
+            rationale: g.rationale,
+            findings: g.findings,
+            attempt: 1,
+            maxAttempts: 1,
+            retryable: false,
+            evaluatedAt,
+        });
     });
 }
 export function markAllGatesOmitted(milestoneId, sliceId) {
@@ -1012,6 +1147,13 @@ export function deleteArtifactsByPathPrefix(prefix) {
         return Number(countRow?.["count"] ?? 0);
     });
 }
+/** List artifact rows whose paths share a DB-relative prefix. */
+export function getArtifactsByPathPrefix(prefix) {
+    if (!getDbOrNull())
+        return [];
+    const rows = getDbOrNull().prepare("SELECT * FROM artifacts WHERE path LIKE :prefix ORDER BY path").all({ ":prefix": `${prefix}%` });
+    return rows.map(rowToArtifact);
+}
 /**
  * Drop hierarchy rows in dependency order inside a transaction. Used by
  * `gsd recover --confirm` to rebuild engine state from markdown.

package/dist/resources/extensions/gsd/guided-flow.js

@@ -603,6 +603,9 @@ export const _dispatchWorkflowForTest = dispatchWorkflow;
 export function getDiscussableFutureMilestones(registry, activeMilestoneId) {
     return registry.filter((m) => m.id !== activeMilestoneId && m.status !== "complete" && m.status !== "parked");
 }
+function findDiscussTargetMilestone(registry, milestoneId) {
+    return registry.find((m) => m.id === milestoneId || m.id.startsWith(`${milestoneId}-`));
+}
 function getStructuredQuestionsAvailability(pi, ctx) {
     if (!ctx)
         return "false";
@@ -964,12 +967,20 @@ export async function showDiscuss(ctx, pi, basePath, options) {
         if (slash > 0) {
             const mid = target.slice(0, slash);
             const sid = target.slice(slash + 1);
-            const targetMilestone = state.registry.find((m) => m.id === mid);
-            if (!targetMilestone || targetMilestone.status === "complete" || targetMilestone.status === "parked") {
-                ctx.ui.notify(`Milestone ${mid} is not discussable.`, "warning");
+            const targetMilestone = findDiscussTargetMilestone(state.registry, mid);
+            if (!targetMilestone) {
+                ctx.ui.notify(`Milestone ${mid} was not found in the roadmap. Use /gsd new-milestone to add it, or /gsd status to see available milestones.`, "warning");
+                return;
+            }
+            if (targetMilestone.status === "complete") {
+                ctx.ui.notify(`Milestone ${targetMilestone.id} is already complete.`, "info");
+                return;
+            }
+            if (targetMilestone.status === "parked") {
+                ctx.ui.notify(`Milestone ${targetMilestone.id} is parked. Run /gsd unpark ${targetMilestone.id} to reactivate.`, "warning");
                 return;
             }
-            const slices = await loadDiscussNormSlices(basePath, mid);
+            const slices = await loadDiscussNormSlices(basePath, targetMilestone.id);
             const chosen = slices.find((s) => s.id.toUpperCase() === sid.toUpperCase());
             if (!chosen) {
                 ctx.ui.notify(`Slice ${target} was not found in discussable slices.`, "warning");
@@ -979,19 +990,27 @@ export async function showDiscuss(ctx, pi, basePath, options) {
                 ctx.ui.notify(`Slice ${target} is already complete; nothing to discuss.`, "info");
                 return;
             }
-            const discussBasePath = resolveDiscussSliceBasePath(basePath, mid);
-            const contextFile = resolveSliceFile(discussBasePath, mid, sid, "CONTEXT");
+            const discussBasePath = resolveDiscussSliceBasePath(basePath, targetMilestone.id);
+            const contextFile = resolveSliceFile(discussBasePath, targetMilestone.id, sid, "CONTEXT");
             const sqAvail = getStructuredQuestionsAvailability(pi, ctx);
-            const prompt = await buildDiscussSlicePrompt(mid, sid, chosen.title, discussBasePath, {
+            const prompt = await buildDiscussSlicePrompt(targetMilestone.id, sid, chosen.title, discussBasePath, {
                 rediscuss: !!contextFile,
                 structuredQuestionsAvailable: sqAvail,
             });
             await dispatchWorkflow(pi, prompt, "gsd-discuss", ctx, "discuss-slice", { basePath: discussBasePath });
             return;
         }
-        const targetMilestone = state.registry.find((m) => m.id === target);
-        if (!targetMilestone || targetMilestone.status === "complete" || targetMilestone.status === "parked") {
-            ctx.ui.notify(`Milestone ${target} is not discussable.`, "warning");
+        const targetMilestone = findDiscussTargetMilestone(state.registry, target);
+        if (!targetMilestone) {
+            ctx.ui.notify(`Milestone ${target} was not found in the roadmap. Use /gsd new-milestone to add it, or /gsd status to see available milestones.`, "warning");
+            return;
+        }
+        if (targetMilestone.status === "complete") {
+            ctx.ui.notify(`Milestone ${targetMilestone.id} is already complete.`, "info");
+            return;
+        }
+        if (targetMilestone.status === "parked") {
+            ctx.ui.notify(`Milestone ${targetMilestone.id} is parked. Run /gsd unpark ${targetMilestone.id} to reactivate.`, "warning");
             return;
         }
         await dispatchDiscussForMilestone(ctx, pi, basePath, targetMilestone.id, targetMilestone.title, {});