@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.8e6112e9

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

@@ -0,0 +1,458 @@
+// 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";
+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 = openDatabase(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-workspace.js

@@ -0,0 +1,103 @@
+// Project/App: gsd-pi
+// File Purpose: Workspace-facing Interface for opening and maintaining the workflow database.
+import { existsSync } from "node:fs";
+import { dirname } from "node:path";
+import { backupDatabaseSnapshot, checkpointDatabase, closeAllDatabases, closeDatabase, closeDatabaseByWorkspace, getDbPath, getDbStatus, getDbProvider, isDbAvailable, openDatabase, openDatabaseByScope, openDatabaseByWorkspace, refreshOpenDatabaseFromDisk, vacuumDatabase, wasDbOpenAttempted, } from "./gsd-db.js";
+import { resolveGsdPathContract } from "./paths.js";
+import { setLogBasePath } from "./workflow-logger.js";
+export function resolveWorkflowDatabaseLocation(basePath) {
+    const contract = resolveGsdPathContract(basePath);
+    return {
+        projectRoot: dirname(dirname(contract.projectDb)),
+        projectGsd: contract.projectGsd,
+        projectDb: contract.projectDb,
+    };
+}
+/**
+ * Resolve the correct DB path for the current working directory.
+ * If `basePath` is inside a `.gsd/worktrees/<MID>/` directory, returns
+ * the project root's `.gsd/gsd.db` (shared WAL — R012). Otherwise returns
+ * `<basePath>/.gsd/gsd.db`.
+ */
+export function resolveProjectRootDbPath(basePath) {
+    return resolveWorkflowDatabaseLocation(basePath).projectDb;
+}
+export function openWorkflowDatabase(basePath) {
+    const location = resolveWorkflowDatabaseLocation(basePath);
+    if (!existsSync(location.projectGsd)) {
+        return { ok: false, reason: "missing-gsd-dir", location };
+    }
+    const existed = existsSync(location.projectDb);
+    try {
+        const opened = openDatabase(location.projectDb);
+        if (!opened) {
+            return { ok: false, reason: "open-failed", location };
+        }
+        setLogBasePath(location.projectRoot);
+        return {
+            ok: true,
+            reason: existed ? "opened-existing" : "created-empty",
+            location,
+        };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: "open-failed",
+            location,
+            error: err instanceof Error ? err : new Error(String(err)),
+        };
+    }
+}
+export function openExistingWorkflowDatabase(basePath) {
+    const location = resolveWorkflowDatabaseLocation(basePath);
+    if (!existsSync(location.projectDb)) {
+        return { ok: false, reason: "missing-database", location };
+    }
+    return openWorkflowDatabase(basePath);
+}
+export function openWorkflowDatabasePath(path) {
+    return openDatabase(path);
+}
+export function openWorkflowDatabaseByWorkspace(workspace) {
+    return openDatabaseByWorkspace(workspace);
+}
+export function openWorkflowDatabaseByScope(scope) {
+    return openDatabaseByScope(scope);
+}
+export function closeWorkflowDatabase() {
+    closeDatabase();
+}
+export function closeWorkflowDatabaseByWorkspace(workspace) {
+    closeDatabaseByWorkspace(workspace);
+}
+export function closeAllWorkflowDatabases() {
+    closeAllDatabases();
+}
+export function isWorkflowDatabaseOpen() {
+    return isDbAvailable();
+}
+export function wasWorkflowDatabaseOpenAttempted() {
+    return wasDbOpenAttempted();
+}
+export function getWorkflowDatabaseStatus() {
+    return getDbStatus();
+}
+export function getWorkflowDatabaseProvider() {
+    return getDbProvider();
+}
+export function getWorkflowDatabasePath() {
+    return getDbPath();
+}
+export function refreshWorkflowDatabaseFromDisk() {
+    return refreshOpenDatabaseFromDisk();
+}
+export function checkpointWorkflowDatabase() {
+    checkpointDatabase();
+}
+export function vacuumWorkflowDatabase() {
+    vacuumDatabase();
+}
+export function backupWorkflowDatabaseSnapshot(label) {
+    return backupDatabaseSnapshot(label);
+}

package/dist/resources/extensions/gsd/db-writer.js

@@ -620,27 +620,18 @@ async function mirrorDecisionToMemory(id, normalizedFields) {
 /**
  * Extract a milestone/slice reference from a deferral decision.
  *
- * Detects deferrals by checking:
- *   - scope contains "defer" (e.g., "deferral", "defer")
- *   - choice or decision contains "defer" + an M###/S## pattern
+ * Detects deferrals when the slice reference is part of the deferral phrase.
  *
  * Returns { milestoneId, sliceId } if found, null otherwise.
  */
 export function extractDeferredSliceRef(fields) {
-    const isDeferral = /\bdefer(?:ral|red|ring|s)?\b/i.test(fields.scope) ||
-        /\bdefer(?:ral|red|ring|s)?\b/i.test(fields.choice) ||
-        /\bdefer(?:ral|red|ring|s)?\b/i.test(fields.decision);
-    if (!isDeferral)
-        return null;
-    // Look for M###/S## pattern in choice first, then decision
-    const slicePattern = /\b(M\d{3,4})\/(S\d{2,3})\b/;
-    const choiceMatch = fields.choice.match(slicePattern);
-    if (choiceMatch) {
-        return { milestoneId: choiceMatch[1], sliceId: choiceMatch[2] };
-    }
-    const decisionMatch = fields.decision.match(slicePattern);
-    if (decisionMatch) {
-        return { milestoneId: decisionMatch[1], sliceId: decisionMatch[2] };
+    const defersSlicePattern = /\bdefer(?:ral|red|ring|s)?\b\s+(?:(?:of|the)\s+)*(?:slice\s+)?\b(M\d{3,4})\/(S\d{2,3})\b/i;
+    const sliceIsDeferredPattern = /\b(M\d{3,4})\/(S\d{2,3})\b\s+(?:is|was|will be|should be|can be)\s+defer(?:red|ring)?\b/i;
+    for (const text of [fields.choice, fields.decision, fields.scope]) {
+        const match = text.match(defersSlicePattern) ?? text.match(sliceIsDeferredPattern);
+        if (match) {
+            return { milestoneId: match[1], sliceId: match[2] };
+        }
     }
     return null;
 }