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

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

@@ -0,0 +1,476 @@
+// Project/App: gsd-pi
+// File Purpose: Worktree DB reconciliation writers for the single-writer layer.
+// Owns copyWorktreeDb + reconcileWorktreeDb: the ATTACH-and-merge of an
+// auto-worktree's gsd.db back into the project-root DB, with conflict
+// detection. Reads the shared engine handle via getDbOrNull(); opens the
+// project-root DB via the engine's openDatabase().
+import { existsSync, copyFileSync, mkdirSync, realpathSync } from "node:fs";
+import { dirname } from "node:path";
+import { createHash } from "node:crypto";
+import { logError, logWarning } from "../../workflow-logger.js";
+import { getDbOrNull, openDatabase } from "../engine.js";
+import { TERMINAL_STATUS_SQL } from "../sql-constants.js";
+/**
+ * Optional override for the project-root DB open inside reconcileWorktreeDb.
+ * Production leaves this null so the real engine.openDatabase runs; tests
+ * inject a function returning false to deterministically exercise the
+ * cannot-open-main-DB branch (reconcile.ts:82), which is otherwise unreachable
+ * without a contrived provider/OS fault (openDatabase rethrows on real failures
+ * rather than returning false across providers).
+ * @internal
+ */
+let _mainDbOpenerFn = null;
+export function _setMainDbOpenerFnForTests(fn) {
+    const previous = _mainDbOpenerFn;
+    _mainDbOpenerFn = fn;
+    return () => { _mainDbOpenerFn = previous; };
+}
+function openMainDb(mainDbPath) {
+    return _mainDbOpenerFn ? _mainDbOpenerFn(mainDbPath) : openDatabase(mainDbPath);
+}
+export function copyWorktreeDb(srcDbPath, destDbPath) {
+    try {
+        if (!existsSync(srcDbPath))
+            return false;
+        const destDir = dirname(destDbPath);
+        mkdirSync(destDir, { recursive: true });
+        copyFileSync(srcDbPath, destDbPath);
+        return true;
+    }
+    catch (err) {
+        logError("db", "failed to copy DB to worktree", { error: err.message });
+        return false;
+    }
+}
+export function reconcileWorktreeDb(mainDbPath, worktreeDbPath) {
+    const zero = {
+        decisions: 0,
+        requirements: 0,
+        artifacts: 0,
+        milestones: 0,
+        slices: 0,
+        tasks: 0,
+        memories: 0,
+        replan_history: 0,
+        assessments: 0,
+        quality_gates: 0,
+        slice_dependencies: 0,
+        verification_evidence: 0,
+        gate_runs: 0,
+        milestone_commit_attributions: 0,
+        conflicts: [],
+    };
+    if (!existsSync(worktreeDbPath))
+        return zero;
+    // Guard: bail when both paths resolve to the same physical file.
+    // ATTACHing a WAL-mode DB to itself corrupts the WAL (#2823).
+    try {
+        if (realpathSync(mainDbPath) === realpathSync(worktreeDbPath))
+            return zero;
+    }
+    catch (e) {
+        logWarning("db", `realpathSync failed: ${e.message}`);
+    }
+    // Sanitize path: reject any characters that could break ATTACH syntax.
+    // ATTACH DATABASE doesn't support parameterized paths in all providers,
+    // so we use strict allowlist validation instead.
+    if (/['";\x00]/.test(worktreeDbPath)) {
+        logError("db", "worktree DB reconciliation failed: path contains unsafe characters");
+        return zero;
+    }
+    if (!getDbOrNull()) {
+        const opened = openMainDb(mainDbPath);
+        if (!opened) {
+            logError("db", "worktree DB reconciliation failed: cannot open main DB");
+            return zero;
+        }
+    }
+    const adapter = getDbOrNull();
+    const conflicts = [];
+    try {
+        adapter.exec(`ATTACH DATABASE '${worktreeDbPath}' AS wt`);
+        try {
+            function countChanges(result) {
+                return typeof result === "object" && result !== null ? (result.changes ?? 0) : 0;
+            }
+            function wtTableInfo(tableName) {
+                return adapter.prepare(`PRAGMA wt.table_info('${tableName}')`).all();
+            }
+            const wtInfo = wtTableInfo("decisions");
+            const hasWtDecisions = wtInfo.length > 0;
+            const hasMadeBy = wtInfo.some((col) => col["name"] === "made_by");
+            // ADR-011: worktree may predate schema v16/v17. For missing columns we
+            // fall through to the main DB's existing value (not a literal default)
+            // so reconcile never silently clears state the main tree has recorded.
+            const hasDecisionSource = wtInfo.some((col) => col["name"] === "source");
+            const wtRequirementInfo = wtTableInfo("requirements");
+            const hasWtRequirements = wtRequirementInfo.length > 0;
+            const wtMilestoneInfo = wtTableInfo("milestones");
+            const hasWtMilestones = wtMilestoneInfo.length > 0;
+            const hasMilestoneSequence = wtMilestoneInfo.some((col) => col["name"] === "sequence");
+            const wtSliceInfo = wtTableInfo("slices");
+            const hasWtSlices = wtSliceInfo.length > 0;
+            const hasIsSketch = wtSliceInfo.some((col) => col["name"] === "is_sketch");
+            const hasSketchScope = wtSliceInfo.some((col) => col["name"] === "sketch_scope");
+            const hasSliceTargetRepositories = wtSliceInfo.some((col) => col["name"] === "target_repositories");
+            const wtTaskInfo = wtTableInfo("tasks");
+            const hasWtTasks = wtTaskInfo.length > 0;
+            const hasTaskTargetRepositories = wtTaskInfo.some((col) => col["name"] === "target_repositories");
+            const hasBlockerSource = wtTaskInfo.some((col) => col["name"] === "blocker_source");
+            const hasEscalationPending = wtTaskInfo.some((col) => col["name"] === "escalation_pending");
+            const hasEscalationAwaiting = wtTaskInfo.some((col) => col["name"] === "escalation_awaiting_review");
+            const hasEscalationArtifact = wtTaskInfo.some((col) => col["name"] === "escalation_artifact_path");
+            const hasEscalationOverride = wtTaskInfo.some((col) => col["name"] === "escalation_override_applied_at");
+            const wtArtifactInfo = wtTableInfo("artifacts");
+            const hasWtArtifacts = wtArtifactInfo.length > 0;
+            const wtMemoryInfo = wtTableInfo("memories");
+            const hasWtMemories = wtMemoryInfo.length > 0;
+            const hasMemoryScope = wtMemoryInfo.some((col) => col["name"] === "scope");
+            const hasMemoryTags = wtMemoryInfo.some((col) => col["name"] === "tags");
+            const hasMemoryStructuredFields = wtMemoryInfo.some((col) => col["name"] === "structured_fields");
+            const hasMemoryLastHitAt = wtMemoryInfo.some((col) => col["name"] === "last_hit_at");
+            const hasWtReplanHistory = wtTableInfo("replan_history").length > 0;
+            const hasWtAssessments = wtTableInfo("assessments").length > 0;
+            const hasWtQualityGates = wtTableInfo("quality_gates").length > 0;
+            const hasWtSliceDependencies = wtTableInfo("slice_dependencies").length > 0;
+            const hasWtVerificationEvidence = wtTableInfo("verification_evidence").length > 0;
+            const hasWtGateRuns = wtTableInfo("gate_runs").length > 0;
+            const hasWtMilestoneCommitAttributions = wtTableInfo("milestone_commit_attributions").length > 0;
+            if (hasWtDecisions) {
+                const decConf = adapter.prepare(`SELECT m.id FROM decisions m INNER JOIN wt.decisions w ON m.id = w.id WHERE m.decision != w.decision OR m.choice != w.choice OR m.rationale != w.rationale OR ${hasMadeBy ? "m.made_by != w.made_by" : "'agent' != 'agent'"} OR m.superseded_by IS NOT w.superseded_by`).all();
+                for (const row of decConf)
+                    conflicts.push(`decision ${row["id"]}: modified in both`);
+            }
+            if (hasWtRequirements) {
+                const reqConf = adapter.prepare(`SELECT m.id FROM requirements m INNER JOIN wt.requirements w ON m.id = w.id WHERE m.description != w.description OR m.status != w.status OR m.notes != w.notes OR m.superseded_by IS NOT w.superseded_by`).all();
+                for (const row of reqConf)
+                    conflicts.push(`requirement ${row["id"]}: modified in both`);
+            }
+            const merged = {
+                decisions: 0,
+                requirements: 0,
+                artifacts: 0,
+                milestones: 0,
+                slices: 0,
+                tasks: 0,
+                memories: 0,
+                replan_history: 0,
+                assessments: 0,
+                quality_gates: 0,
+                slice_dependencies: 0,
+                verification_evidence: 0,
+                gate_runs: 0,
+                milestone_commit_attributions: 0,
+            };
+            const sliceTargetRepositoriesSql = hasSliceTargetRepositories
+                ? `CASE
+             WHEN w.target_repositories = '[]' AND COALESCE(m.target_repositories, '[]') <> '[]'
+             THEN m.target_repositories
+             ELSE COALESCE(w.target_repositories, m.target_repositories, '[]')
+           END`
+                : "COALESCE(m.target_repositories, '[]')";
+            const taskTargetRepositoriesSql = hasTaskTargetRepositories
+                ? `CASE
+             WHEN w.target_repositories = '[]' AND COALESCE(m.target_repositories, '[]') <> '[]'
+             THEN m.target_repositories
+             ELSE COALESCE(w.target_repositories, m.target_repositories, '[]')
+           END`
+                : "COALESCE(m.target_repositories, '[]')";
+            adapter.exec("BEGIN");
+            try {
+                // Join the target decisions so we can prefer an existing main.source
+                // when the worktree predates v16 — otherwise a write-through reconcile
+                // would clobber 'escalation'-sourced decisions with the literal default.
+                if (hasWtDecisions) {
+                    merged.decisions = countChanges(adapter.prepare(`
+            INSERT INTO decisions (
+              id, when_context, scope, decision, choice, rationale, revisable, made_by, source, superseded_by
+            )
+            SELECT w.id, w.when_context, w.scope, w.decision, w.choice, w.rationale, w.revisable, ${hasMadeBy ? "w.made_by" : "COALESCE(m.made_by, 'agent')"}, ${hasDecisionSource ? "w.source" : "COALESCE(m.source, 'discussion')"}, w.superseded_by
+            FROM wt.decisions w
+            LEFT JOIN decisions m ON m.id = w.id
+            WHERE true
+            ON CONFLICT(id) DO UPDATE SET
+              when_context = excluded.when_context,
+              scope = excluded.scope,
+              decision = excluded.decision,
+              choice = excluded.choice,
+              rationale = excluded.rationale,
+              revisable = excluded.revisable,
+              made_by = excluded.made_by,
+              source = excluded.source,
+              superseded_by = excluded.superseded_by
+          `).run());
+                }
+                if (hasWtRequirements) {
+                    merged.requirements = countChanges(adapter.prepare(`
+            INSERT OR REPLACE INTO requirements (
+              id, class, status, description, why, source, primary_owner,
+              supporting_slices, validation, notes, full_content, superseded_by
+            )
+            SELECT id, class, status, description, why, source, primary_owner,
+                   supporting_slices, validation, notes, full_content, superseded_by
+            FROM wt.requirements
+          `).run());
+                }
+                // Always recompute artifact hashes from the content being merged. Older
+                // worktree DBs may not have content_hash at all, and migrated old DBs can
+                // carry stale default/null hashes after their content changed.
+                if (hasWtArtifacts) {
+                    const artifactRows = adapter.prepare(`
+            SELECT path, artifact_type, milestone_id, slice_id, task_id, full_content, imported_at
+            FROM wt.artifacts
+          `).all();
+                    const artifactStmt = adapter.prepare(`
+            INSERT OR REPLACE INTO artifacts (
+              path, artifact_type, milestone_id, slice_id, task_id, full_content, imported_at, content_hash
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+          `);
+                    for (const row of artifactRows) {
+                        const fullContent = String(row["full_content"] ?? "");
+                        merged.artifacts += countChanges(artifactStmt.run(row["path"], row["artifact_type"], row["milestone_id"] ?? null, row["slice_id"] ?? null, row["task_id"] ?? null, fullContent, row["imported_at"], createHash("sha256").update(fullContent).digest("hex")));
+                    }
+                }
+                // Merge milestones — worktree may have updated status/planning fields.
+                // Never downgrade status: complete > active > pre-planning (#4372).
+                // A stale worktree may carry an older 'active' status for a milestone
+                // that the main DB has already marked 'complete'; preserve the higher status.
+                if (hasWtMilestones) {
+                    merged.milestones = countChanges(adapter.prepare(`
+            INSERT OR REPLACE 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
+            )
+            SELECT w.id, w.title,
+                   CASE
+                     WHEN m.status IN (${TERMINAL_STATUS_SQL}) AND w.status NOT IN (${TERMINAL_STATUS_SQL})
+                     THEN m.status ELSE w.status
+                   END,
+                   w.depends_on,
+                   CASE
+                     WHEN m.status IN (${TERMINAL_STATUS_SQL}) AND w.status NOT IN (${TERMINAL_STATUS_SQL})
+                     THEN m.created_at ELSE w.created_at
+                   END,
+                   CASE
+                     WHEN m.status IN (${TERMINAL_STATUS_SQL}) AND w.status NOT IN (${TERMINAL_STATUS_SQL})
+                     THEN m.completed_at ELSE w.completed_at
+                   END,
+                   w.vision, w.success_criteria, w.key_risks, w.proof_strategy,
+                   w.verification_contract, w.verification_integration, w.verification_operational, w.verification_uat,
+                   w.definition_of_done, w.requirement_coverage, w.boundary_map_markdown,
+                   ${hasMilestoneSequence ? "COALESCE(w.sequence, 0)" : "COALESCE(m.sequence, 0)"}
+            FROM wt.milestones w
+            LEFT JOIN milestones m ON m.id = w.id
+          `).run());
+                }
+                // Merge slices — preserve worktree progress but never downgrade completed status (#2558).
+                // ADR-011 Phase 1: carry is_sketch + sketch_scope so reconcile doesn't
+                // silently clear sketch metadata. When the worktree predates v16,
+                // fall back to the main DB's existing value rather than a literal 0/''.
+                if (hasWtSlices) {
+                    merged.slices = countChanges(adapter.prepare(`
+            INSERT OR REPLACE 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
+            )
+            SELECT w.milestone_id, w.id, w.title,
+                   CASE
+                     WHEN m.status IN (${TERMINAL_STATUS_SQL}) AND w.status NOT IN (${TERMINAL_STATUS_SQL})
+                     THEN m.status ELSE w.status
+                   END,
+                   w.risk, w.depends, w.demo, w.created_at,
+                   CASE
+                     WHEN m.status IN (${TERMINAL_STATUS_SQL}) AND w.status NOT IN (${TERMINAL_STATUS_SQL})
+                     THEN m.completed_at ELSE w.completed_at
+                   END,
+                   w.full_summary_md, w.full_uat_md, w.goal, w.success_criteria, w.proof_level,
+                   w.integration_closure, w.observability_impact,
+                   ${sliceTargetRepositoriesSql},
+                   w.sequence, w.replan_triggered_at,
+                   ${hasIsSketch ? "w.is_sketch" : "COALESCE(m.is_sketch, 0)"},
+                   ${hasSketchScope ? "w.sketch_scope" : "COALESCE(m.sketch_scope, '')"}
+            FROM wt.slices w
+            LEFT JOIN slices m ON m.milestone_id = w.milestone_id AND m.id = w.id
+          `).run());
+                }
+                // Merge tasks — preserve execution results, never downgrade completed status (#2558).
+                // ADR-011 P2: carry blocker_source + escalation_* columns so worktree reconcile
+                // doesn't silently clear escalation state back to defaults.
+                if (hasWtTasks) {
+                    merged.tasks = countChanges(adapter.prepare(`
+            INSERT OR REPLACE 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
+            )
+            SELECT w.milestone_id, w.slice_id, w.id, w.title,
+                   CASE
+                     WHEN m.status IN (${TERMINAL_STATUS_SQL}) AND w.status NOT IN (${TERMINAL_STATUS_SQL})
+                     THEN m.status ELSE w.status
+                   END,
+                   w.one_liner, w.narrative,
+                   w.verification_result, w.duration,
+                   CASE
+                     WHEN m.status IN (${TERMINAL_STATUS_SQL}) AND w.status NOT IN (${TERMINAL_STATUS_SQL})
+                     THEN m.completed_at ELSE w.completed_at
+                   END,
+                   w.blocker_discovered,
+                   w.deviations, w.known_issues, w.key_files, w.key_decisions, w.full_summary_md,
+                   w.description, w.estimate, w.files, w.verify, w.inputs, w.expected_output,
+                   w.observability_impact, w.full_plan_md,
+                   ${taskTargetRepositoriesSql},
+                   w.sequence,
+                   ${hasBlockerSource ? "w.blocker_source" : "COALESCE(m.blocker_source, '')"},
+                   ${hasEscalationPending ? "w.escalation_pending" : "COALESCE(m.escalation_pending, 0)"},
+                   ${hasEscalationAwaiting ? "w.escalation_awaiting_review" : "COALESCE(m.escalation_awaiting_review, 0)"},
+                   ${hasEscalationArtifact ? "w.escalation_artifact_path" : "m.escalation_artifact_path"},
+                   ${hasEscalationOverride ? "w.escalation_override_applied_at" : "m.escalation_override_applied_at"}
+            FROM wt.tasks w
+            LEFT JOIN tasks m ON m.milestone_id = w.milestone_id AND m.slice_id = w.slice_id AND m.id = w.id
+          `).run());
+                }
+                // Merge memories — keep worktree-learned insights.
+                // V18 (scope, tags), V21 (structured_fields), V28 (last_hit_at): for each
+                // column the wt may not yet have (older worktree DB), fall back to the
+                // main DB's existing value via LEFT JOIN so reconcile never silently
+                // resets these fields to defaults on rows that already had them.
+                if (hasWtMemories) {
+                    merged.memories = countChanges(adapter.prepare(`
+            INSERT OR REPLACE INTO memories (
+              seq, id, category, content, confidence, source_unit_type, source_unit_id,
+              created_at, updated_at, superseded_by, hit_count,
+              scope, tags, structured_fields, last_hit_at
+            )
+            SELECT w.seq, w.id, w.category, w.content, w.confidence, w.source_unit_type, w.source_unit_id,
+                   w.created_at, w.updated_at, w.superseded_by, w.hit_count,
+                   ${hasMemoryScope ? "w.scope" : "COALESCE(m.scope, 'project')"},
+                   ${hasMemoryTags ? "w.tags" : "COALESCE(m.tags, '[]')"},
+                   ${hasMemoryStructuredFields ? "w.structured_fields" : "m.structured_fields"},
+                   ${hasMemoryLastHitAt ? "w.last_hit_at" : "m.last_hit_at"}
+            FROM wt.memories w
+            LEFT JOIN memories m ON m.id = w.id
+          `).run());
+                }
+                if (hasWtReplanHistory) {
+                    merged.replan_history = countChanges(adapter.prepare(`
+            INSERT INTO replan_history (
+              milestone_id, slice_id, task_id, summary, previous_artifact_path, replacement_artifact_path, created_at
+            )
+            SELECT w.milestone_id, w.slice_id, w.task_id, w.summary, w.previous_artifact_path, w.replacement_artifact_path, w.created_at
+            FROM wt.replan_history w
+            WHERE EXISTS (SELECT 1 FROM milestones m WHERE m.id = w.milestone_id)
+              AND NOT EXISTS (
+                SELECT 1 FROM replan_history m
+                WHERE m.milestone_id = w.milestone_id
+                  AND m.slice_id IS w.slice_id
+                  AND m.task_id IS w.task_id
+                  AND m.summary = w.summary
+                  AND m.previous_artifact_path IS w.previous_artifact_path
+                  AND m.replacement_artifact_path IS w.replacement_artifact_path
+              )
+          `).run());
+                }
+                if (hasWtAssessments) {
+                    merged.assessments = countChanges(adapter.prepare(`
+            INSERT OR REPLACE INTO assessments (
+              path, milestone_id, slice_id, task_id, status, scope, full_content, created_at
+            )
+            SELECT w.path, w.milestone_id, w.slice_id, w.task_id, w.status, w.scope, w.full_content, w.created_at
+            FROM wt.assessments w
+            WHERE EXISTS (SELECT 1 FROM milestones m WHERE m.id = w.milestone_id)
+          `).run());
+                }
+                if (hasWtQualityGates) {
+                    merged.quality_gates = countChanges(adapter.prepare(`
+            INSERT OR REPLACE INTO quality_gates (
+              milestone_id, slice_id, gate_id, scope, task_id, status, verdict, rationale, findings, evaluated_at
+            )
+            SELECT w.milestone_id, w.slice_id, w.gate_id, w.scope, COALESCE(w.task_id, ''), w.status, w.verdict, w.rationale, w.findings, w.evaluated_at
+            FROM wt.quality_gates w
+            WHERE EXISTS (SELECT 1 FROM slices s WHERE s.milestone_id = w.milestone_id AND s.id = w.slice_id)
+          `).run());
+                }
+                if (hasWtSliceDependencies) {
+                    merged.slice_dependencies = countChanges(adapter.prepare(`
+            INSERT OR IGNORE INTO slice_dependencies (milestone_id, slice_id, depends_on_slice_id)
+            SELECT w.milestone_id, w.slice_id, w.depends_on_slice_id
+            FROM wt.slice_dependencies w
+            WHERE EXISTS (SELECT 1 FROM slices s WHERE s.milestone_id = w.milestone_id AND s.id = w.slice_id)
+              AND EXISTS (SELECT 1 FROM slices d WHERE d.milestone_id = w.milestone_id AND d.id = w.depends_on_slice_id)
+          `).run());
+                }
+                // Merge verification evidence — append-only, use INSERT OR IGNORE to avoid duplicates
+                if (hasWtVerificationEvidence) {
+                    merged.verification_evidence = countChanges(adapter.prepare(`
+            INSERT OR IGNORE INTO verification_evidence (
+              task_id, slice_id, milestone_id, command, exit_code, verdict, duration_ms, created_at
+            )
+            SELECT task_id, slice_id, milestone_id, command, exit_code, verdict, duration_ms, created_at
+            FROM wt.verification_evidence
+          `).run());
+                }
+                if (hasWtGateRuns) {
+                    merged.gate_runs = countChanges(adapter.prepare(`
+            INSERT INTO gate_runs (
+              trace_id, turn_id, gate_id, gate_type, unit_type, unit_id, milestone_id, slice_id, task_id,
+              outcome, failure_class, rationale, findings, attempt, max_attempts, retryable, evaluated_at
+            )
+            SELECT w.trace_id, w.turn_id, w.gate_id, w.gate_type, w.unit_type, w.unit_id, w.milestone_id, w.slice_id, w.task_id,
+                   w.outcome, w.failure_class, w.rationale, w.findings, w.attempt, w.max_attempts, w.retryable, w.evaluated_at
+            FROM wt.gate_runs w
+            WHERE NOT EXISTS (
+              SELECT 1 FROM gate_runs m
+              WHERE m.trace_id = w.trace_id
+                AND m.turn_id = w.turn_id
+                AND m.gate_id = w.gate_id
+                AND m.attempt = w.attempt
+                AND m.evaluated_at = w.evaluated_at
+            )
+          `).run());
+                }
+                if (hasWtMilestoneCommitAttributions) {
+                    merged.milestone_commit_attributions = countChanges(adapter.prepare(`
+            INSERT OR REPLACE INTO milestone_commit_attributions (
+              commit_sha, milestone_id, slice_id, task_id, source, confidence, files_json, created_at
+            )
+            SELECT w.commit_sha, w.milestone_id, w.slice_id, w.task_id, w.source, w.confidence, w.files_json, w.created_at
+            FROM wt.milestone_commit_attributions w
+            WHERE EXISTS (SELECT 1 FROM milestones m WHERE m.id = w.milestone_id)
+          `).run());
+                }
+                adapter.exec("COMMIT");
+            }
+            catch (txErr) {
+                try {
+                    adapter.exec("ROLLBACK");
+                }
+                catch (e) {
+                    logWarning("db", `rollback failed: ${e.message}`);
+                }
+                throw txErr;
+            }
+            return { ...merged, conflicts };
+        }
+        finally {
+            try {
+                adapter.exec("DETACH DATABASE wt");
+            }
+            catch (e) {
+                logWarning("db", `detach worktree DB failed: ${e.message}`);
+            }
+        }
+    }
+    catch (err) {
+        logError("db", "worktree DB reconciliation failed", { error: err.message });
+        return { ...zero, conflicts };
+    }
+}
+// ─── Replan & Assessment Helpers ──────────────────────────────────────────

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

@@ -0,0 +1,70 @@
+// Project/App: gsd-pi
+// File Purpose: Status Transition Core (ADR-030) — the single row-level
+// chokepoint every generic status write funnels through. Owns the milestone
+// closed→open guard and is the one place future row-level status policy lands.
+// The update*Status faces in gsd-db.ts delegate here.
+//
+// Behavior this pass is intentionally identical to the prior per-face writes.
+// Two ADR-030 responsibilities are deferred for safety and documented inline:
+//   - Write-normalization via toStatus(): workflow-reconcile replays journal
+//     events that write raw "done"/"in-progress" and tests assert those exact
+//     stored values, so converging on write is a separate, behavior-sensitive
+//     change (migrate replay/import to canonical first).
+//   - Generalizing the closed→open guard to task/slice: four legitimate reopen
+//     callers (undo, tools/reopen-task, auto-post-unit, tools/plan-slice) move
+//     entities to open statuses through the generic faces. Generalizing safely
+//     needs sanctioned reopenTaskStatus/reopenSliceStatus faces first, mirroring
+//     the existing milestone updateMilestoneStatus/reopenMilestoneStatus split.
+import { getDbOrNull } from "../engine.js";
+import { GSDError, GSD_STALE_STATE } from "../../errors.js";
+import { isClosedStatus } from "../../status-guards.js";
+function requireDb() {
+    const db = getDbOrNull();
+    if (!db)
+        throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    return db;
+}
+/**
+ * Apply a row-level status transition. The single chokepoint for generic status
+ * writes — the update*Status faces delegate here so the guard and (future)
+ * normalization/journal/cache policy live in one place rather than per face.
+ *
+ * Milestone closed→open guard: generic updates may close, park/unpark, or
+ * advance a milestone, but may not reopen a closed one; callers must use
+ * reopenMilestoneStatus() (gsd_milestone_reopen). Tasks and slices are not yet
+ * guarded — see the file header.
+ */
+export function applyStatusTransition(t) {
+    const db = requireDb();
+    const completedAt = t.completedAt ?? null;
+    switch (t.entity) {
+        case "task":
+            db.prepare(`UPDATE tasks SET status = :status, completed_at = :completed_at
+         WHERE milestone_id = :milestone_id AND slice_id = :slice_id AND id = :id`).run({
+                ":status": t.status,
+                ":completed_at": completedAt,
+                ":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
+         WHERE milestone_id = :milestone_id AND id = :id`).run({
+                ":status": t.status,
+                ":completed_at": completedAt,
+                ":milestone_id": t.milestoneId,
+                ":id": t.sliceId,
+            });
+            return;
+        case "milestone": {
+            const row = db.prepare("SELECT status FROM milestones WHERE id = :id").get({ ":id": t.milestoneId });
+            const currentStatus = typeof row?.["status"] === "string" ? row["status"] : null;
+            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 });
+            return;
+        }
+    }
+}

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

@@ -1,5 +1,23 @@
 // Project/App: gsd-pi
 // File Purpose: Pre-migration backup helper for GSD database schema upgrades.
+/** Marks pre-migration backup failures so DB-open recovery cannot mask them. */
+export class MigrationBackupError extends Error {
+    constructor(message, cause) {
+        super(message, { cause });
+        this.name = "MigrationBackupError";
+    }
+}
+/** Returns true for errors raised while checkpointing or copying a migration backup. */
+export function isMigrationBackupError(err) {
+    return err instanceof MigrationBackupError;
+}
+/**
+ * Creates a same-version backup before file-backed schema migrations.
+ *
+ * Existing same-version backups are reused. New backups fail closed: WAL
+ * checkpoint failures, incomplete checkpoints, and copy failures are logged
+ * and then rethrown before migration DDL runs.
+ */
 export function backupDatabaseBeforeMigration(db, dbPath, currentVersion, deps) {
     if (!dbPath || dbPath === ":memory:" || !deps.existsSync(dbPath))
         return;
@@ -7,16 +25,41 @@ export function backupDatabaseBeforeMigration(db, dbPath, currentVersion, deps)
         const backupPath = `${dbPath}.backup-v${currentVersion}`;
         if (deps.existsSync(backupPath))
             return;
-        try {
-            db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
-        }
-        catch {
-            // Checkpoint is best effort; copying the base file is still better than no backup.
-        }
+        checkpointWal(db);
         deps.copyFileSync(dbPath, backupPath);
     }
     catch (backupErr) {
-        const message = backupErr instanceof Error ? backupErr.message : String(backupErr);
-        deps.logWarning("db", `Pre-migration backup failed: ${message}`);
+        const error = toMigrationBackupError(backupErr);
+        deps.logWarning("db", `Pre-migration backup failed: ${error.message}`);
+        throw error;
+    }
+}
+function checkpointWal(db) {
+    const row = db.prepare("PRAGMA wal_checkpoint(TRUNCATE)").get();
+    if (!isCheckpointComplete(row)) {
+        const busy = formatCheckpointValue(row, "busy");
+        const log = formatCheckpointValue(row, "log");
+        const checkpointed = formatCheckpointValue(row, "checkpointed");
+        throw new MigrationBackupError(`WAL checkpoint incomplete: busy=${busy} log=${log} checkpointed=${checkpointed}`);
     }
 }
+function isCheckpointComplete(row) {
+    if (!row)
+        return false;
+    const busy = Number(row["busy"]);
+    const log = Number(row["log"]);
+    const checkpointed = Number(row["checkpointed"]);
+    if (!Number.isFinite(busy) || !Number.isFinite(log) || !Number.isFinite(checkpointed))
+        return false;
+    return busy === 0 && log === checkpointed;
+}
+function formatCheckpointValue(row, key) {
+    const value = row?.[key];
+    return value === undefined ? "unknown" : String(value);
+}
+function toMigrationBackupError(err) {
+    if (isMigrationBackupError(err))
+        return err;
+    const message = err instanceof Error ? err.message : String(err);
+    return new MigrationBackupError(message, err);
+}