@opengsd/gsd-pi 1.2.0-dev.b1abb545 → 1.2.0-dev.ddc97c10

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/dispatch-guard.js

@@ -2,9 +2,8 @@
 import { resolveMilestoneFile } from "./paths.js";
 import { findMilestoneIds } from "./guided-flow.js";
 import { parseUnitId } from "./unit-id.js";
-import { isDbAvailable, getMilestoneSlices, getMilestone } from "./gsd-db.js";
-import { parseRoadmap } from "./parsers-legacy.js";
-import { isClosedStatus, isSkippedForDispatch } from "./status-guards.js";
+import { isDbAvailable, getMilestoneSliceSummaries, getMilestone } from "./gsd-db.js";
+import { isSkippedForDispatch } from "./status-guards.js";
 import { classifyMilestoneSummaryContent } from "./milestone-summary-classifier.js";
 import { readFileSync } from "node:fs";
 const SLICE_DISPATCH_TYPES = new Set([
@@ -97,38 +96,14 @@ export function getPriorSliceCompletionBlocker(base, _mainBranch, unitType, unit
                 continue;
             }
         }
-        let slices = null;
-        if (isDbAvailable()) {
-            const rows = getMilestoneSlices(mid);
-            if (rows.length > 0) {
-                slices = rows.map((r) => ({
-                    id: r.id,
-                    done: isClosedStatus(r.status),
-                    depends: r.depends ?? [],
-                }));
-            }
-        }
-        if (!slices) {
-            // File-based fallback: parse roadmap checkboxes
-            const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
-            if (!roadmapPath)
-                continue;
-            let roadmapContent;
-            try {
-                roadmapContent = readFileSync(roadmapPath, "utf-8");
-            }
-            catch {
-                continue;
-            }
-            const parsed = parseRoadmap(roadmapContent);
-            if (parsed.slices.length === 0)
-                continue;
-            slices = parsed.slices.map((s) => ({
-                id: s.id,
-                done: s.done,
-                depends: s.depends ?? [],
-            }));
-        }
+        // DB-authoritative eligibility list (ADR-017) — markdown projections are
+        // never parsed for dispatch decisions. No DB / no rows → skip this
+        // milestone's check (unknown is not a blocker).
+        if (!isDbAvailable())
+            continue;
+        const slices = getMilestoneSliceSummaries(mid);
+        if (slices.length === 0)
+            continue;
         if (mid !== targetMid) {
             const incomplete = slices.find((slice) => !slice.done);
             if (incomplete) {

package/dist/resources/extensions/gsd/doctor-engine-checks.js

@@ -5,7 +5,7 @@ import { isAfter, latestExplicitReopenAt } from "./milestone-reopen-events.js";
 import { resolveGsdPathContract, resolveMilestoneFile } from "./paths.js";
 import { deriveState } from "./state.js";
 import { readEvents } from "./workflow-events.js";
-import { renderAllProjections } from "./workflow-projections.js";
+import { flushWorkflowProjections } from "./projection-flush.js";
 export async function checkEngineHealth(basePath, issues, fixesApplied) {
     const dbPath = resolveGsdPathContract(basePath).projectDb;
     if (!isDbAvailable() && existsSync(dbPath)) {
@@ -239,7 +239,7 @@ export async function checkEngineHealth(basePath, issues, fixesApplied) {
                     const roadmapPath = resolveMilestoneFile(basePath, milestone.id, "ROADMAP");
                     if (!roadmapPath || !existsSync(roadmapPath)) {
                         try {
-                            await renderAllProjections(basePath, milestone.id);
+                            await flushWorkflowProjections(basePath, { milestoneId: milestone.id });
                             fixesApplied.push(`re-rendered missing projections for ${milestone.id}`);
                         }
                         catch {
@@ -250,7 +250,7 @@ export async function checkEngineHealth(basePath, issues, fixesApplied) {
                     const projectionMtime = statSync(roadmapPath).mtimeMs;
                     if (lastEventTs > projectionMtime) {
                         try {
-                            await renderAllProjections(basePath, milestone.id);
+                            await flushWorkflowProjections(basePath, { milestoneId: milestone.id });
                             fixesApplied.push(`re-rendered stale projections for ${milestone.id}`);
                         }
                         catch {

package/dist/resources/extensions/gsd/doctor-environment.js

@@ -12,6 +12,7 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { execSync } from "node:child_process";
 import { join } from "node:path";
 import { detectPythonExecutable } from "./python-resolver.js";
+import { projectRootFromWorktreePath } from "./worktree-root.js";
 // ── Constants ──────────────────────────────────────────────────────────────
 /** Default dev server ports to scan for conflicts. */
 const DEFAULT_DEV_PORTS = [3000, 3001, 4000, 5000, 5173, 8000, 8080, 8888];
@@ -20,26 +21,19 @@ const MIN_DISK_BYTES = 500 * 1024 * 1024;
 /** Timeout for external commands (ms). */
 const CMD_TIMEOUT = 5_000;
 // ── Helpers ────────────────────────────────────────────────────────────────
-/** Worktree sentinel — path segment that marks an auto-worktree directory. */
-const WORKTREE_PATH_SEGMENT = `${join(".gsd", "worktrees")}/`;
 /**
- * Resolve the project root when running inside a `.gsd/worktrees/<name>/`
- * auto-worktree. Returns `null` if not in a worktree.
+ * Resolve the project root when running inside a GSD auto-worktree.
+ * Returns `null` if not in a worktree.
  *
  * Detection order:
  *   1. `GSD_WORKTREE` env var (set by the worktree launcher)
- *   2. `.gsd/worktrees/` segment in basePath
+ *   2. worktree segment in basePath (via worktree-root's layout matching)
  */
 function resolveWorktreeProjectRoot(basePath) {
     const envRoot = process.env.GSD_WORKTREE;
     if (envRoot)
         return envRoot;
-    const normalised = basePath.replace(/\\/g, "/");
-    const idx = normalised.indexOf(WORKTREE_PATH_SEGMENT.replace(/\\/g, "/"));
-    if (idx === -1)
-        return null;
-    // Everything before `.gsd/worktrees/` is the project root
-    return basePath.slice(0, idx);
+    return projectRootFromWorktreePath(basePath);
 }
 function tryExec(cmd, cwd) {
     try {