@opengsd/gsd-pi 1.7.0 → 1.8.1-dev.897b3c90

package/src/resources/extensions/gsd/flat-phase-migration.ts

@@ -6,7 +6,13 @@ import { cpSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSyn
 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";
@@ -14,6 +20,7 @@ import { LAYOUT_SEGMENTS } from "./layout-policy.js";
 import {
   canonicalPhaseDirName,
   dirIsContentBearingLegacyMilestone,
+  gsdProjectionRoot,
   milestonesDir,
   resolveMilestonePath,
 } from "./paths.js";
@@ -83,6 +90,40 @@ function expectedPhaseDirs(basePath: string): string[] {
   );
 }
 
+/**
+ * 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: string): string | null {
+  const backupRoot = join(basePath, ".gsd-backups");
+  if (!existsSync(backupRoot)) return null;
+  try {
+    let latest: { path: string; mtimeMs: number } | null = 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: string): boolean {
   if (!existsSync(dirPath)) return false;
   try {
@@ -94,10 +135,63 @@ function hasLegacyMilestoneSubdirs(dirPath: string): boolean {
   }
 }
 
+function backupFlatProjectionIfPresent(basePath: string, phasesPath: string, backupDir: string): void {
+  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 as Error).message}`);
+    throw err;
+  }
+}
+
+function isInsideFlatProjectionBackup(backupDir: string, src: string): boolean {
+  const phaseBackupDir = join(backupDir, "__phases");
+  return src === phaseBackupDir || src.startsWith(`${phaseBackupDir}/`) || src.startsWith(`${phaseBackupDir}\\`);
+}
+
+function restoreFlatProjectionFromBackup(basePath: string, backupDir: string): void {
+  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 as Error).message}`,
+    );
+  }
+}
+
+function pruneStaleFlatPhaseArtifactRows(basePath: string): number {
+  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: string,
   backupDir: string,
   migratingPath?: string,
+  backupCreatedThisRun = true,
 ): void {
   // Remove the partially-written phases/ dir.
   try {
@@ -113,7 +207,8 @@ function rollbackPartialMigration(
   // 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 = (): void => {
     if (!isDisposableBackup || !existsSync(backupDir)) return;
     try {
@@ -131,11 +226,16 @@ function rollbackPartialMigration(
   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)) {
@@ -244,16 +344,34 @@ export async function migrateToFlatPhase(basePath: string): Promise<void> {
   }
 
   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 });
-    } catch (err) {
-      logWarning("migration", `flat-phase migration backup failed: ${(err as Error).message}`);
-      throw err;
+    // 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)`,
+      );
+    } 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 as Error).message}`);
+        throw err;
+      }
     }
 
     if (existsSync(migratingPath)) {
@@ -269,15 +387,35 @@ export async function migrateToFlatPhase(basePath: string): Promise<void> {
       logWarning("migration", `failed to rename legacy milestones/ before render: ${(err as Error).message}`);
       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 as Error).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 as Error).message}`);
-    rollbackPartialMigration(basePath, backupDir, migratingPath);
+    rollbackPartialMigration(basePath, backupDir, migratingPath, backupCreatedThisRun);
     throw err;
   }
 
@@ -299,7 +437,7 @@ export async function migrateToFlatPhase(basePath: string): Promise<void> {
     }
   } catch (err) {
     logWarning("migration", `flat-phase render failed: ${(err as Error).message}`);
-    rollbackPartialMigration(basePath, backupDir, migratingPath);
+    rollbackPartialMigration(basePath, backupDir, migratingPath, backupCreatedThisRun);
     throw err;
   }
 
@@ -309,7 +447,7 @@ export async function migrateToFlatPhase(basePath: string): Promise<void> {
       "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("; ")}`,
     );
@@ -322,7 +460,7 @@ export async function migrateToFlatPhase(basePath: string): Promise<void> {
       "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) {
@@ -330,17 +468,20 @@ export async function migrateToFlatPhase(basePath: string): Promise<void> {
       "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 as Error).message}`);
-    rollbackPartialMigration(basePath, backupDir, migratingPath);
+    rollbackPartialMigration(basePath, backupDir, migratingPath, backupCreatedThisRun);
     throw err;
   }
 

package/src/resources/extensions/gsd/gsd-db.ts

@@ -41,7 +41,7 @@ import {
 } from "./db-decision-requirement-rows.js";
 import { rowToGate } from "./db-gate-rows.js";
 import { rowToArtifact, rowToMilestone, type ArtifactRow, type MilestoneRow } from "./db-milestone-artifact-rows.js";
-import { isClosedStatus } from "./status-guards.js";
+import { isClosedStatus, toStatus } from "./status-guards.js";
 import { rowToSlice, rowToTask, type SliceRow, type TaskRow } from "./db-task-slice-rows.js";
 
 // Connection ownership, lifecycle, schema/migrations and transaction
@@ -464,6 +464,11 @@ export function insertTask(t: {
   preserveCompletionMetadata?: boolean;
 }): void {
   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,
@@ -515,7 +520,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 ?? "",
@@ -531,7 +536,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
@@ -656,8 +661,8 @@ export function upsertTaskPlanning(milestoneId: string, sliceId: string, taskId:
 }
 
 
-export function updateSliceStatus(milestoneId: string, sliceId: string, status: string, completedAt?: string): void {
-  applyStatusTransition({ entity: "slice", milestoneId, sliceId, status, completedAt });
+export function updateSliceStatus(milestoneId: string, sliceId: string, status: string, completedAt?: string, preserveCompletion?: boolean): void {
+  applyStatusTransition({ entity: "slice", milestoneId, sliceId, status, completedAt, preserveCompletion });
 }
 
 export function setTaskSummaryMd(milestoneId: string, sliceId: string, taskId: string, md: string): void {
@@ -820,8 +825,8 @@ function writeMilestoneStatus(milestoneId: string, status: string, 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: string, status: string, completedAt?: string | null): void {
-  applyStatusTransition({ entity: "milestone", milestoneId, status, completedAt });
+export function updateMilestoneStatus(milestoneId: string, status: string, completedAt?: string | null, preserveCompletion?: boolean): void {
+  applyStatusTransition({ entity: "milestone", milestoneId, status, completedAt, preserveCompletion });
 }
 
 /**
@@ -893,6 +898,188 @@ export function insertReplanHistory(entry: {
   });
 }
 
+
+export type ReworkFindingSeverity = "blocking" | "advisory";
+export type ReworkFindingStatus = "pending" | "resolved" | "deferred-with-override";
+
+export interface ReworkBriefFindingInput {
+  findingId: string;
+  severity: ReworkFindingSeverity;
+  description: string;
+  requiredFix: string;
+  verificationCommands: string[];
+  status?: ReworkFindingStatus;
+  evidence?: string;
+  decisionRef?: string;
+}
+
+export interface ReworkBriefFindingRow {
+  brief_id: string;
+  finding_id: string;
+  severity: ReworkFindingSeverity;
+  description: string;
+  required_fix: string;
+  verification_commands: string[];
+  status: ReworkFindingStatus;
+  evidence: string;
+  decision_ref: string;
+}
+
+function reworkBriefIdFromTask(milestoneId: string, sliceId: string, taskId: string): string {
+  return `RB-${milestoneId}-${sliceId}-${taskId}`;
+}
+
+function normalizeReworkStatus(status: unknown): ReworkFindingStatus {
+  const normalized = String(status ?? "pending");
+  if (normalized === "resolved" || normalized === "deferred-with-override") {
+    return normalized;
+  }
+  return "pending";
+}
+
+function rowToReworkFinding(row: Record<string, unknown>): ReworkBriefFindingRow {
+  let verificationCommands: string[] = [];
+  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: {
+  briefId?: string;
+  milestoneId: string;
+  sliceId: string;
+  taskId: string;
+  findings: ReworkBriefFindingInput[];
+}): { briefId: string } {
+  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: string,
+  sliceId: string,
+  taskId: string,
+): ReworkBriefFindingRow[] {
+  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 }) as Array<Record<string, unknown>>;
+  return rows.map(rowToReworkFinding);
+}
+
+export function getUnresolvedBlockingReworkFindingsForTask(
+  milestoneId: string,
+  sliceId: string,
+  taskId: string,
+): ReworkBriefFindingRow[] {
+  return getBlockingReworkFindingsForTask(milestoneId, sliceId, taskId)
+    .filter((finding) => finding.status === "pending");
+}
+
+export function applyReworkResolutions(resolutions: Array<{
+  milestoneId: string;
+  sliceId: string;
+  taskId: string;
+  findingId: string;
+  status: ReworkFindingStatus;
+  evidence: string;
+  decisionRef?: string;
+}>): void {
+  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: {
   path: string;
   milestoneId: string;
@@ -1084,52 +1271,59 @@ export function saveGateResult(g: {
 }): void {
   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,
-  }) as { changes?: number };
-
-  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}` : ""}`,
-    );
-  }
+  // 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,
+    }) as { changes?: number };
+
+    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,
+    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,
+    });
   });
 }
 
@@ -1419,6 +1613,15 @@ export function deleteArtifactsByPathPrefix(prefix: string): number {
   });
 }
 
+/** List artifact rows whose paths share a DB-relative prefix. */
+export function getArtifactsByPathPrefix(prefix: string): ArtifactRow[] {
+  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.