@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.72e3af2a

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

@@ -520,9 +520,33 @@ export function getRecentUnitKeysForWorker(
 export function getRecentUnitKeysForProjectRoot(
   projectRootRealpath: string,
   limit = 20,
+  traceId?: string,
 ): Array<{ key: string }> {
   if (!isDbAvailable()) return [];
   const db = _getAdapter()!;
+  // When a trace_id is provided, scope the window to the current session so
+  // stale finalize-retry entries from PREVIOUS sessions don't fire detectStuck
+  // Rule 1 on the first iteration of a new session — killing auto-mode before
+  // any new dispatch runs. Without this, a project that had two consecutive
+  // finalize-retry failures in a prior session is permanently stuck: every
+  // fresh session loads those stale errors and immediately declares stuck.
+  if (traceId) {
+    const rows = db.prepare(
+      `SELECT ud.unit_type, ud.unit_id
+       FROM unit_dispatches ud
+       INNER JOIN workers w ON w.worker_id = ud.worker_id
+       WHERE w.project_root_realpath = :project_root_realpath
+         AND w.status != 'crashed'
+         AND ud.trace_id = :trace_id
+       ORDER BY ud.started_at DESC, ud.id DESC
+       LIMIT :limit`,
+    ).all({
+      ":project_root_realpath": projectRootRealpath,
+      ":trace_id": traceId,
+      ":limit": limit,
+    }) as Array<{ unit_type: string; unit_id: string }>;
+    return rows.reverse().map((r) => ({ key: `${r.unit_type}/${r.unit_id}` }));
+  }
   const rows = db.prepare(
     `SELECT ud.unit_type, ud.unit_id
      FROM unit_dispatches ud

package/src/resources/extensions/gsd/db/writers/cascades.ts

@@ -0,0 +1,237 @@
+// Project/App: gsd-pi
+// File Purpose: Domain Write Operations (Hierarchy Status Cascades) for the
+// single-writer layer. Each operation owns its own transaction() and mutates
+// the related rows of one logical hierarchy change in a single commit, so the
+// atomicity rule lives in one place instead of being hand-rolled (or missed)
+// in callers. Operations own DB-row atomicity only — markdown re-projection,
+// validation, and messaging stay in callers / db-writer.ts.
+import { getDbOrNull, transaction } from "../engine.js";
+import { GSDError, GSD_STALE_STATE } from "../../errors.js";
+import { isClosedStatus } from "../../status-guards.js";
+import { getMilestone, getSlice, getSliceTasks, getMilestoneSlices } from "../queries.js";
+// completeSliceCascade reuses the complex hierarchy write primitives (ON CONFLICT
+// upserts with null sentinels) rather than re-inlining their SQL. This is a
+// back-edge to gsd-db.ts, which re-exports this module — safe because the
+// imported bindings are hoisted function declarations only called at runtime.
+// It dissolves when these primitives move to db/writers/hierarchy.ts.
+import { insertMilestone, insertSlice, updateSliceStatus, updateMilestoneStatus } from "../../gsd-db.js";
+
+function requireDb(): void {
+  if (!getDbOrNull()!) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+}
+
+// ─── Reopen cascades ───────────────────────────────────────────────────────
+// A reopen blocked by a structural precondition returns a discriminated reason
+// (carrying the offending entity's status where the caller's message needs it).
+// Structural guards run inside the transaction for TOCTOU safety; the caller
+// owns user-facing message formatting and projection.
+
+export type ReopenSliceOutcome =
+  | { ok: true; tasksReset: number }
+  | { ok: false; reason: "milestone-not-found" }
+  | { ok: false; reason: "milestone-closed"; status: string }
+  | { ok: false; reason: "slice-not-found" }
+  | { ok: false; reason: "slice-not-complete"; status: string };
+
+/**
+ * Reopen a completed slice: slice → "in_progress", all its tasks → "pending",
+ * completion timestamps cleared, in one commit. Folds the hand-rolled
+ * transaction-plus-cascade previously in tools/reopen-slice.ts. Guards run
+ * inside the transaction (TOCTOU-safe).
+ */
+export function reopenSliceCascade(milestoneId: string, sliceId: string): ReopenSliceOutcome {
+  requireDb();
+  let outcome: ReopenSliceOutcome = { ok: true, tasksReset: 0 };
+  transaction(() => {
+    const milestone = getMilestone(milestoneId);
+    if (!milestone) { outcome = { ok: false, reason: "milestone-not-found" }; return; }
+    if (isClosedStatus(milestone.status)) { outcome = { ok: false, reason: "milestone-closed", status: milestone.status }; return; }
+    const slice = getSlice(milestoneId, sliceId);
+    if (!slice) { outcome = { ok: false, reason: "slice-not-found" }; return; }
+    if (!isClosedStatus(slice.status)) { outcome = { ok: false, reason: "slice-not-complete", status: slice.status }; return; }
+
+    const tasks = getSliceTasks(milestoneId, sliceId);
+    getDbOrNull()!.prepare(
+      `UPDATE slices SET status = 'in_progress', completed_at = NULL WHERE milestone_id = :mid AND id = :sid`,
+    ).run({ ":mid": milestoneId, ":sid": sliceId });
+    getDbOrNull()!.prepare(
+      `UPDATE tasks SET status = 'pending', completed_at = NULL WHERE milestone_id = :mid AND slice_id = :sid`,
+    ).run({ ":mid": milestoneId, ":sid": sliceId });
+    outcome = { ok: true, tasksReset: tasks.length };
+  });
+  return outcome;
+}
+
+export type ReopenMilestoneOutcome =
+  | { ok: true; slicesReset: number; tasksReset: number }
+  | { ok: false; reason: "milestone-not-found" }
+  | { ok: false; reason: "milestone-not-closed"; status: string };
+
+/**
+ * Reopen a closed milestone: milestone → "active", every slice → "in_progress",
+ * every task → "pending", completion timestamps cleared, in one commit. Folds
+ * the hand-rolled transaction-plus-cascade previously in tools/reopen-milestone.ts.
+ */
+export function reopenMilestoneCascade(milestoneId: string): ReopenMilestoneOutcome {
+  requireDb();
+  let outcome: ReopenMilestoneOutcome = { ok: true, slicesReset: 0, tasksReset: 0 };
+  transaction(() => {
+    const milestone = getMilestone(milestoneId);
+    if (!milestone) { outcome = { ok: false, reason: "milestone-not-found" }; return; }
+    if (!isClosedStatus(milestone.status)) { outcome = { ok: false, reason: "milestone-not-closed", status: milestone.status }; return; }
+
+    const slices = getMilestoneSlices(milestoneId);
+
+    getDbOrNull()!.prepare(
+      `UPDATE milestones SET status = 'active', completed_at = NULL WHERE id = :mid`,
+    ).run({ ":mid": milestoneId });
+    getDbOrNull()!.prepare(
+      `UPDATE slices SET status = 'in_progress', completed_at = NULL WHERE milestone_id = :mid`,
+    ).run({ ":mid": milestoneId });
+    const tasksResult = getDbOrNull()!.prepare(
+      `UPDATE tasks SET status = 'pending', completed_at = NULL WHERE milestone_id = :mid`,
+    ).run({ ":mid": milestoneId });
+    const tasksReset = (tasksResult as { changes?: number }).changes ?? 0;
+    outcome = { ok: true, slicesReset: slices.length, tasksReset };
+  });
+  return outcome;
+}
+
+export type CompleteSliceOutcome =
+  | { ok: true; duplicate: boolean; existingSummaryMd: string }
+  | { ok: false; reason: "milestone-closed"; status: string }
+  | { ok: false; reason: "no-tasks" }
+  | { ok: false; reason: "incomplete-tasks"; incomplete: Array<{ id: string; status: string }> };
+
+/**
+ * Complete a slice: verify preconditions, auto-create the milestone/slice rows
+ * if absent, mark the slice "complete", and activate a still-"planned"
+ * milestone once all its slices are closed — all in one transaction. Folds the
+ * hand-rolled cascade previously in tools/complete-slice.ts.
+ *
+ * Returns a discriminated outcome. The `duplicate: true` success case means the
+ * slice was already closed (no writes performed); the caller handles the stale/
+ * idempotent path. `existingSummaryMd` carries the slice's prior summary so the
+ * caller can backfill omitted requirement fields. Markdown rendering, file
+ * writes, and summary persistence stay in the caller.
+ */
+export function completeSliceCascade(
+  milestoneId: string,
+  sliceId: string,
+  opts: { sliceTitle?: string; completedAt: string },
+): CompleteSliceOutcome {
+  requireDb();
+  let outcome: CompleteSliceOutcome = { ok: true, duplicate: false, existingSummaryMd: "" };
+  transaction(() => {
+    // Preconditions inside the txn for atomicity. A missing milestone/slice is
+    // fine — they are auto-created below; only a closed one blocks.
+    const milestone = getMilestone(milestoneId);
+    if (milestone && isClosedStatus(milestone.status)) {
+      outcome = { ok: false, reason: "milestone-closed", status: milestone.status };
+      return;
+    }
+
+    const slice = getSlice(milestoneId, sliceId);
+    const existingSummaryMd = slice?.full_summary_md?.trim() ?? "";
+    if (slice && isClosedStatus(slice.status)) {
+      outcome = { ok: true, duplicate: true, existingSummaryMd };
+      return;
+    }
+
+    const tasks = getSliceTasks(milestoneId, sliceId);
+    if (tasks.length === 0) {
+      outcome = { ok: false, reason: "no-tasks" };
+      return;
+    }
+    const incomplete = tasks
+      .filter((t) => !isClosedStatus(t.status))
+      .map((t) => ({ id: t.id, status: t.status }));
+    if (incomplete.length > 0) {
+      outcome = { ok: false, reason: "incomplete-tasks", incomplete };
+      return;
+    }
+
+    // All guards passed — perform writes. Preserve existing planning metadata:
+    // completion must not overwrite title/risk/depends/demo/sequence.
+    insertMilestone({ id: milestoneId, title: milestoneId });
+    if (!slice) {
+      insertSlice({ id: sliceId, milestoneId, title: opts.sliceTitle || sliceId });
+    }
+    updateSliceStatus(milestoneId, sliceId, "complete", opts.completedAt);
+
+    const updatedSlices = getMilestoneSlices(milestoneId);
+    if (
+      milestone?.status === "planned" &&
+      updatedSlices.length > 0 &&
+      updatedSlices.every((s) => isClosedStatus(s.status))
+    ) {
+      updateMilestoneStatus(milestoneId, "active");
+    }
+    outcome = { ok: true, duplicate: false, existingSummaryMd };
+  });
+  return outcome;
+}
+
+export type SkipSliceOutcome =
+  | { ok: true; tasksSkipped: number; wasAlreadySkipped: boolean }
+  | { ok: false; reason: "slice-not-found" }
+  | { ok: false; reason: "slice-already-complete" };
+
+/**
+ * Skip a slice: slice → "skipped" (unless already skipped) and every non-closed
+ * task → "skipped", in one commit. Completed/done slices are rejected; closed
+ * tasks are never downgraded. Folds the hand-rolled cascade previously in
+ * tools/skip-slice.ts. Guards run inside the transaction (TOCTOU-safe).
+ */
+export function skipSliceCascade(milestoneId: string, sliceId: string): SkipSliceOutcome {
+  requireDb();
+  let outcome: SkipSliceOutcome = { ok: true, tasksSkipped: 0, wasAlreadySkipped: false };
+  transaction(() => {
+    const slice = getSlice(milestoneId, sliceId);
+    if (!slice) { outcome = { ok: false, reason: "slice-not-found" }; return; }
+    if (slice.status === "complete" || slice.status === "done") {
+      outcome = { ok: false, reason: "slice-already-complete" };
+      return;
+    }
+    const wasAlreadySkipped = slice.status === "skipped";
+    if (!wasAlreadySkipped) {
+      getDbOrNull()!.prepare(
+        `UPDATE slices SET status = 'skipped', completed_at = NULL WHERE milestone_id = :mid AND id = :sid`,
+      ).run({ ":mid": milestoneId, ":sid": sliceId });
+    }
+    // Cascade: skip every non-closed task so milestone completion doesn't trip
+    // the deep-task guard (#4375). Closed tasks are left untouched.
+    const tasks = getSliceTasks(milestoneId, sliceId);
+    let tasksSkipped = 0;
+    for (const task of tasks) {
+      if (!isClosedStatus(task.status)) {
+        getDbOrNull()!.prepare(
+          `UPDATE tasks SET status = 'skipped', completed_at = NULL WHERE milestone_id = :mid AND slice_id = :sid AND id = :tid`,
+        ).run({ ":mid": milestoneId, ":sid": sliceId, ":tid": task.id });
+        tasksSkipped++;
+      }
+    }
+    outcome = { ok: true, tasksSkipped, wasAlreadySkipped };
+  });
+  return outcome;
+}
+
+/**
+ * Reset a slice to "active" and all of its tasks to "pending" in one commit,
+ * clearing completion timestamps. Equivalent to the historical per-task
+ * updateTaskStatus loop + updateSliceStatus in undo's reset-slice, but atomic:
+ * an interruption can no longer leave some tasks reset and others not.
+ */
+export function resetSliceCascade(milestoneId: string, sliceId: string): void {
+  if (!getDbOrNull()!) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+  transaction(() => {
+    getDbOrNull()!.prepare(
+      `UPDATE tasks SET status = 'pending', completed_at = NULL
+       WHERE milestone_id = :mid AND slice_id = :sid`,
+    ).run({ ":mid": milestoneId, ":sid": sliceId });
+    getDbOrNull()!.prepare(
+      `UPDATE slices SET status = 'active', completed_at = NULL
+       WHERE milestone_id = :mid AND id = :sid`,
+    ).run({ ":mid": milestoneId, ":sid": sliceId });
+  });
+}

package/src/resources/extensions/gsd/db/writers/import-restore.ts

@@ -0,0 +1,310 @@
+// Project/App: gsd-pi
+// File Purpose: Bulk import/restore writers for the single-writer layer.
+// restoreManifest rebuilds the engine DB from a StateManifest;
+// bulkInsertLegacyHierarchy replaces the milestone/slice/task hierarchy from
+// markdown-parsed payloads. Both own their own transaction() and contain only
+// write SQL, read through the shared engine handle.
+import { createHash } from "node:crypto";
+import { getDbOrNull, transaction } from "../engine.js";
+import { GSDError, GSD_STALE_STATE } from "../../errors.js";
+import type { StateManifest } from "../../workflow-manifest.js";
+
+export function restoreManifest(manifest: StateManifest): void {
+  if (!getDbOrNull()!) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+  const db = getDbOrNull()!;
+
+  transaction(() => {
+    const restoredMilestoneIds = new Set(manifest.milestones.map((m) => m.id));
+    const restoredSliceKeys = new Set(manifest.slices.map((s) => JSON.stringify([s.milestone_id, s.id])));
+    const preservedReplanHistory = manifest.replan_history === undefined
+      ? db.prepare("SELECT * FROM replan_history ORDER BY id").all() as unknown as NonNullable<StateManifest["replan_history"]>
+      : [];
+    const preservedAssessments = manifest.assessments === undefined
+      ? db.prepare("SELECT * FROM assessments ORDER BY path").all() as unknown as NonNullable<StateManifest["assessments"]>
+      : [];
+    const preservedQualityGates = manifest.quality_gates === undefined
+      ? db.prepare("SELECT * FROM quality_gates ORDER BY milestone_id, slice_id, gate_id, task_id").all() as unknown as NonNullable<StateManifest["quality_gates"]>
+      : [];
+    const preservedCommitAttributions = manifest.milestone_commit_attributions === undefined
+      ? db.prepare("SELECT * FROM milestone_commit_attributions ORDER BY milestone_id, commit_sha").all() as unknown as NonNullable<StateManifest["milestone_commit_attributions"]>
+      : [];
+
+    // Clear workflow tables in dependency order.
+    db.exec("DELETE FROM verification_evidence");
+    db.exec("DELETE FROM quality_gates");
+    db.exec("DELETE FROM slice_dependencies");
+    db.exec("DELETE FROM assessments");
+    db.exec("DELETE FROM replan_history");
+    db.exec("DELETE FROM milestone_commit_attributions");
+    db.exec("DELETE FROM tasks");
+    db.exec("DELETE FROM slices");
+    db.exec("DELETE FROM milestone_leases");
+    db.exec("DELETE FROM milestones");
+    db.exec("DELETE FROM decisions WHERE 1=1");
+    db.exec(`DELETE FROM memories WHERE category = 'architecture' AND structured_fields LIKE '%"sourceDecisionId":"%'`);
+    if (manifest.artifacts !== undefined) db.exec("DELETE FROM artifacts");
+    if (manifest.requirements !== undefined) db.exec("DELETE FROM requirements");
+
+    if (manifest.requirements !== undefined) {
+      const reqStmt = db.prepare(
+        `INSERT INTO requirements (
+          id, class, status, description, why, source, primary_owner,
+          supporting_slices, validation, notes, full_content, superseded_by
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      );
+      for (const r of manifest.requirements) {
+        reqStmt.run(
+          r.id, r.class, r.status, r.description, r.why, r.source, r.primary_owner,
+          r.supporting_slices, r.validation, r.notes, r.full_content, r.superseded_by,
+        );
+      }
+    }
+
+    if (manifest.artifacts !== undefined) {
+      const artStmt = db.prepare(
+        `INSERT INTO artifacts (
+          path, artifact_type, milestone_id, slice_id, task_id, full_content, imported_at, content_hash
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      );
+      for (const a of manifest.artifacts) {
+        const fullContent = a.full_content ?? "";
+        artStmt.run(
+          a.path, a.artifact_type, a.milestone_id, a.slice_id, a.task_id,
+          fullContent, a.imported_at, a.content_hash ?? createHash("sha256").update(fullContent).digest("hex"),
+        );
+      }
+    }
+
+    // Restore milestones
+    const msStmt = db.prepare(
+      `INSERT INTO milestones (id, title, status, depends_on, created_at, completed_at,
+        vision, success_criteria, key_risks, proof_strategy,
+        verification_contract, verification_integration, verification_operational, verification_uat,
+        definition_of_done, requirement_coverage, boundary_map_markdown, sequence)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+    for (const m of manifest.milestones) {
+      msStmt.run(
+        m.id, m.title, m.status,
+        JSON.stringify(m.depends_on), m.created_at, m.completed_at,
+        m.vision, JSON.stringify(m.success_criteria), JSON.stringify(m.key_risks),
+        JSON.stringify(m.proof_strategy),
+        m.verification_contract, m.verification_integration, m.verification_operational, m.verification_uat,
+        JSON.stringify(m.definition_of_done), m.requirement_coverage, m.boundary_map_markdown, m.sequence ?? 0,
+      );
+    }
+
+    // Restore slices (ADR-011 Phase 1: includes is_sketch + sketch_scope)
+    const slStmt = db.prepare(
+      `INSERT INTO slices (milestone_id, id, title, status, risk, depends, demo,
+        created_at, completed_at, full_summary_md, full_uat_md,
+        goal, success_criteria, proof_level, integration_closure, observability_impact,
+        target_repositories, sequence, replan_triggered_at, is_sketch, sketch_scope)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+    for (const s of manifest.slices) {
+      slStmt.run(
+        s.milestone_id, s.id, s.title, s.status, s.risk,
+        JSON.stringify(s.depends), s.demo,
+        s.created_at, s.completed_at, s.full_summary_md, s.full_uat_md,
+        s.goal, s.success_criteria, s.proof_level, s.integration_closure, s.observability_impact,
+        JSON.stringify(s.target_repositories ?? []),
+        s.sequence, s.replan_triggered_at,
+        s.is_sketch ?? 0,
+        s.sketch_scope ?? "",
+      );
+    }
+
+    const depStmt = db.prepare(
+      "INSERT OR IGNORE INTO slice_dependencies (milestone_id, slice_id, depends_on_slice_id) VALUES (?, ?, ?)",
+    );
+    for (const s of manifest.slices) {
+      for (const dep of s.depends ?? []) {
+        depStmt.run(s.milestone_id, s.id, dep);
+      }
+    }
+
+    // Restore tasks (ADR-011 P2: includes blocker_source + escalation_* columns)
+    const tkStmt = db.prepare(
+      `INSERT INTO tasks (milestone_id, slice_id, id, title, status,
+        one_liner, narrative, verification_result, duration, completed_at,
+        blocker_discovered, deviations, known_issues, key_files, key_decisions,
+        full_summary_md, description, estimate, files, verify,
+        inputs, expected_output, observability_impact, full_plan_md, target_repositories, sequence,
+        blocker_source, escalation_pending, escalation_awaiting_review,
+        escalation_artifact_path, escalation_override_applied_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+    for (const t of manifest.tasks) {
+      tkStmt.run(
+        t.milestone_id, t.slice_id, t.id, t.title, t.status,
+        t.one_liner, t.narrative, t.verification_result, t.duration, t.completed_at,
+        t.blocker_discovered ? 1 : 0, t.deviations, t.known_issues,
+        JSON.stringify(t.key_files), JSON.stringify(t.key_decisions),
+        t.full_summary_md, t.description, t.estimate, JSON.stringify(t.files), t.verify,
+        JSON.stringify(t.inputs), JSON.stringify(t.expected_output),
+        t.observability_impact, t.full_plan_md ?? "", JSON.stringify(t.target_repositories ?? []), t.sequence,
+        t.blocker_source ?? "",
+        t.escalation_pending ?? 0,
+        t.escalation_awaiting_review ?? 0,
+        t.escalation_artifact_path ?? null,
+        t.escalation_override_applied_at ?? null,
+      );
+    }
+
+    // Restore decisions (ADR-011 P2: include source so escalation decisions survive)
+    const dcStmt = db.prepare(
+      `INSERT INTO decisions (seq, id, when_context, scope, decision, choice, rationale, revisable, made_by, source, superseded_by)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+    for (const d of manifest.decisions) {
+      dcStmt.run(d.seq, d.id, d.when_context, d.scope, d.decision, d.choice, d.rationale, d.revisable, d.made_by, d.source ?? "discussion", d.superseded_by);
+    }
+
+    const replanHistoryRows = manifest.replan_history ?? preservedReplanHistory.filter((r) => restoredMilestoneIds.has(r.milestone_id));
+    if (replanHistoryRows.length > 0) {
+      const replStmt = db.prepare(
+        `INSERT INTO replan_history (
+          id, milestone_id, slice_id, task_id, summary, previous_artifact_path, replacement_artifact_path, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      );
+      for (const r of replanHistoryRows) {
+        replStmt.run(
+          r.id, r.milestone_id, r.slice_id, r.task_id, r.summary,
+          r.previous_artifact_path, r.replacement_artifact_path, r.created_at,
+        );
+      }
+    }
+
+    const assessmentRows = manifest.assessments ?? preservedAssessments.filter((a) => restoredMilestoneIds.has(a.milestone_id));
+    if (assessmentRows.length > 0) {
+      const assessStmt = db.prepare(
+        `INSERT INTO assessments (
+          path, milestone_id, slice_id, task_id, status, scope, full_content, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      );
+      for (const a of assessmentRows) {
+        assessStmt.run(
+          a.path, a.milestone_id, a.slice_id, a.task_id,
+          a.status, a.scope, a.full_content, a.created_at,
+        );
+      }
+    }
+
+    const qualityGateRows = manifest.quality_gates ?? preservedQualityGates.filter((g) => (
+      restoredSliceKeys.has(JSON.stringify([g.milestone_id, g.slice_id]))
+    ));
+    if (qualityGateRows.length > 0) {
+      const gateStmt = db.prepare(
+        `INSERT INTO quality_gates (
+          milestone_id, slice_id, gate_id, scope, task_id, status, verdict, rationale, findings, evaluated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      );
+      for (const g of qualityGateRows) {
+        gateStmt.run(
+          g.milestone_id, g.slice_id, g.gate_id, g.scope, g.task_id,
+          g.status, g.verdict ?? "", g.rationale, g.findings, g.evaluated_at,
+        );
+      }
+    }
+
+    const commitAttributionRows = manifest.milestone_commit_attributions ??
+      preservedCommitAttributions.filter((a) => restoredMilestoneIds.has(a.milestone_id));
+    if (commitAttributionRows.length > 0) {
+      const attrStmt = db.prepare(
+        `INSERT OR REPLACE INTO milestone_commit_attributions (
+          commit_sha, milestone_id, slice_id, task_id, source, confidence, files_json, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      );
+      for (const a of commitAttributionRows) {
+        attrStmt.run(
+          a.commit_sha, a.milestone_id, a.slice_id, a.task_id,
+          a.source, a.confidence, a.files_json, a.created_at,
+        );
+      }
+    }
+
+    // Restore verification evidence
+    const evStmt = db.prepare(
+      `INSERT INTO verification_evidence (task_id, slice_id, milestone_id, command, exit_code, verdict, duration_ms, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+    for (const e of manifest.verification_evidence) {
+      evStmt.run(e.task_id, e.slice_id, e.milestone_id, e.command, e.exit_code, e.verdict, e.duration_ms, e.created_at);
+    }
+  });
+}
+
+// ─── Legacy markdown → DB bulk migration ─────────────────────────────────
+
+export interface LegacyMilestoneInsert {
+  id: string;
+  title: string;
+  status: string;
+}
+
+export interface LegacySliceInsert {
+  id: string;
+  milestoneId: string;
+  title: string;
+  status: string;
+  risk: string;
+  sequence: number;
+}
+
+export interface LegacyTaskInsert {
+  id: string;
+  sliceId: string;
+  milestoneId: string;
+  title: string;
+  status: string;
+  sequence: number;
+}
+
+/**
+ * Bulk delete + insert a legacy milestone hierarchy for markdown → DB migration.
+ * Used by workflow-migration.ts to populate engine tables from parsed ROADMAP/PLAN
+ * files. All operations run inside a single transaction.
+ */
+export function bulkInsertLegacyHierarchy(payload: {
+  milestones: LegacyMilestoneInsert[];
+  slices: LegacySliceInsert[];
+  tasks: LegacyTaskInsert[];
+  clearMilestoneIds: string[];
+  createdAt: string;
+}): void {
+  if (!getDbOrNull()!) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+  const db = getDbOrNull()!;
+  const { milestones, slices, tasks, clearMilestoneIds, createdAt } = payload;
+
+  if (clearMilestoneIds.length === 0) return;
+  const placeholders = clearMilestoneIds.map(() => "?").join(",");
+
+  transaction(() => {
+    db.prepare(`DELETE FROM tasks WHERE milestone_id IN (${placeholders})`).run(...clearMilestoneIds);
+    db.prepare(`DELETE FROM slices WHERE milestone_id IN (${placeholders})`).run(...clearMilestoneIds);
+    db.prepare(`DELETE FROM milestone_leases WHERE milestone_id IN (${placeholders})`).run(...clearMilestoneIds);
+    db.prepare(`DELETE FROM milestones WHERE id IN (${placeholders})`).run(...clearMilestoneIds);
+
+    const insertMilestone = db.prepare(
+      "INSERT INTO milestones (id, title, status, created_at) VALUES (?, ?, ?, ?)",
+    );
+    for (const m of milestones) {
+      insertMilestone.run(m.id, m.title, m.status, createdAt);
+    }
+
+    const insertSliceStmt = db.prepare(
+      "INSERT INTO slices (id, milestone_id, title, status, risk, depends, sequence, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+    );
+    for (const s of slices) {
+      insertSliceStmt.run(s.id, s.milestoneId, s.title, s.status, s.risk, "[]", s.sequence, createdAt);
+    }
+
+    const insertTaskStmt = db.prepare(
+      "INSERT INTO tasks (id, slice_id, milestone_id, title, description, status, estimate, files, sequence) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+    );
+    for (const t of tasks) {
+      insertTaskStmt.run(t.id, t.sliceId, t.milestoneId, t.title, "", t.status, "", "[]", t.sequence);
+    }
+  });
+}