@opengsd/gsd-pi 1.2.0-dev.4813ead6 → 1.2.0-dev.5457a158

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

@@ -0,0 +1,500 @@
+// 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, join } 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: string, destDbPath: string): boolean {
+  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 as Error).message });
+    return false;
+  }
+}
+
+export interface ReconcileResult {
+  decisions: number;
+  requirements: number;
+  artifacts: number;
+  milestones: number;
+  slices: number;
+  tasks: number;
+  memories: number;
+  replan_history: number;
+  assessments: number;
+  quality_gates: number;
+  slice_dependencies: number;
+  verification_evidence: number;
+  gate_runs: number;
+  milestone_commit_attributions: number;
+  conflicts: string[];
+}
+
+export function reconcileWorktreeDb(
+  mainDbPath: string,
+  worktreeDbPath: string,
+): ReconcileResult {
+  const zero: ReconcileResult = {
+    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 as Error).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: string[] = [];
+  try {
+    adapter.exec(`ATTACH DATABASE '${worktreeDbPath}' AS wt`);
+    try {
+      function countChanges(result: unknown): number {
+        return typeof result === "object" && result !== null ? ((result as { changes?: number }).changes ?? 0) : 0;
+      }
+
+      function wtTableInfo(tableName: string): Array<Record<string, unknown>> {
+        return adapter.prepare(`PRAGMA wt.table_info('${tableName}')`).all() as Array<Record<string, unknown>>;
+      }
+
+      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 as Record<string, unknown>)["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 as Record<string, unknown>)["id"]}: modified in both`);
+      }
+
+      const merged: Omit<ReconcileResult, "conflicts"> = {
+        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() as Array<Record<string, unknown>>;
+          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 as Error).message}`); }
+        throw txErr;
+      }
+      return { ...merged, conflicts };
+    } finally {
+      try { adapter.exec("DETACH DATABASE wt"); } catch (e) { logWarning("db", `detach worktree DB failed: ${(e as Error).message}`); }
+    }
+  } catch (err) {
+    logError("db", "worktree DB reconciliation failed", { error: (err as Error).message });
+    return { ...zero, conflicts };
+  }
+}
+
+// ─── Replan & Assessment Helpers ──────────────────────────────────────────
+

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

@@ -0,0 +1,88 @@
+// 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";
+
+/** A single row-level status write, discriminated by entity (the faces' arity). */
+export type StatusTransition =
+  | { entity: "task"; milestoneId: string; sliceId: string; taskId: string; status: string; completedAt?: string | null }
+  | { entity: "slice"; milestoneId: string; sliceId: string; status: string; completedAt?: string | null }
+  | { entity: "milestone"; milestoneId: string; status: string; completedAt?: string | null };
+
+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: StatusTransition): void {
+  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"] as string) : 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/src/resources/extensions/gsd/doctor-environment.ts

@@ -15,6 +15,7 @@ import { join } from "node:path";
 
 import type { DoctorIssue, DoctorIssueCode } from "./doctor-types.js";
 import { detectPythonExecutable } from "./python-resolver.js";
+import { projectRootFromWorktreePath } from "./worktree-root.js";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -38,27 +39,18 @@ 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: string): string | null {
   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: string, cwd: string): string | null {

package/src/resources/extensions/gsd/doctor-format.ts

@@ -1,4 +1,9 @@
-import type { DoctorIssue, DoctorIssueCode, DoctorReport, DoctorSummary } from "./doctor-types.js";
+import type { DoctorIssue, DoctorIssueCode, DoctorReport, DoctorSummary, DoctorSeverity } from "./doctor-types.js";
+import { doctorFixHint } from "./guidance.js";
+
+function severityTag(severity: DoctorSeverity): string {
+  return severity === "error" ? "ERROR" : severity === "warning" ? "WARN" : "INFO";
+}
 
 function matchesScope(unitId: string, scope?: string): boolean {
   if (!scope) return true;
@@ -53,8 +58,9 @@ export function formatDoctorReport(
   if (scopedIssues.length > 0) {
     lines.push("Priority issues:");
     for (const issue of scopedIssues.slice(0, maxIssues)) {
-      const prefix = issue.severity === "error" ? "ERROR" : issue.severity === "warning" ? "WARN" : "INFO";
-      lines.push(`- [${prefix}] ${issue.unitId}: ${issue.message}${issue.file ? ` (${issue.file})` : ""}`);
+      lines.push(`- [${severityTag(issue.severity)}] ${issue.unitId}: ${issue.message}${issue.file ? ` (${issue.file})` : ""}`);
+      const hint = doctorFixHint(issue.code);
+      if (hint && issue.severity !== "info") lines.push(`  Fix: ${hint}`);
     }
     if (scopedIssues.length > maxIssues) {
       lines.push(`- ...and ${scopedIssues.length - maxIssues} more in scope`);
@@ -72,10 +78,9 @@ export function formatDoctorReport(
 
 export function formatDoctorIssuesForPrompt(issues: DoctorIssue[]): string {
   if (issues.length === 0) return "- No remaining issues in scope.";
-  return issues.map(issue => {
-    const prefix = issue.severity === "error" ? "ERROR" : issue.severity === "warning" ? "WARN" : "INFO";
-    return `- [${prefix}] ${issue.unitId} | ${issue.code} | ${issue.message}${issue.file ? ` | file: ${issue.file}` : ""} | fixable: ${issue.fixable ? "yes" : "no"}`;
-  }).join("\n");
+  return issues.map(issue =>
+    `- [${severityTag(issue.severity)}] ${issue.unitId} | ${issue.code} | ${issue.message}${issue.file ? ` | file: ${issue.file}` : ""} | fixable: ${issue.fixable ? "yes" : "no"}`
+  ).join("\n");
 }
 
 /**