@opengsd/gsd-pi 1.3.0-dev.eed73bea → 1.4.0-dev.5fc22c6f

package/src/resources/extensions/gsd/db/queries.ts

@@ -413,6 +413,46 @@ export function getSlicesByMilestoneIds(milestoneIds: readonly string[]): Map<st
   return byMilestone;
 }
 
+/**
+ * Load tasks for many (milestone, slice) pairs in batched queries. Returns a Map
+ * keyed by `${milestone_id}\0${slice_id}`, preserving `ORDER BY sequence, id`
+ * within each bucket. Mirrors getSlicesByMilestoneIds to avoid an N+1 over tasks
+ * during full projection rebuilds.
+ */
+export function getTasksBySliceIds(
+  slices: ReadonlyArray<{ milestoneId: string; sliceId: string }>,
+): Map<string, TaskRow[]> {
+  const bySlice = new Map<string, TaskRow[]>();
+  const db = getDbOrNull();
+  if (!db || slices.length === 0) return bySlice;
+  // SQLite caps bound params (~999); 2 per pair, so chunk well under the limit.
+  const CHUNK = 400;
+  for (let start = 0; start < slices.length; start += CHUNK) {
+    const chunk = slices.slice(start, start + CHUNK);
+    const clauses: string[] = [];
+    const params: Record<string, unknown> = {};
+    chunk.forEach((s, i) => {
+      clauses.push(`(milestone_id = :m${i} AND slice_id = :s${i})`);
+      params[`:m${i}`] = s.milestoneId;
+      params[`:s${i}`] = s.sliceId;
+    });
+    const rows = db
+      .prepare(`SELECT * FROM tasks WHERE ${clauses.join(" OR ")} ORDER BY milestone_id, slice_id, sequence, id`)
+      .all(params) as Record<string, unknown>[];
+    for (const row of rows) {
+      const task = rowToTask(row);
+      const key = `${task.milestone_id}\0${task.slice_id}`;
+      const bucket = bySlice.get(key);
+      if (bucket) {
+        bucket.push(task);
+      } else {
+        bySlice.set(key, [task]);
+      }
+    }
+  }
+  return bySlice;
+}
+
 /** Dispatch-eligibility shape consumed by decision-path callers (ADR-017). */
 export interface MilestoneSliceSummary {
   id: string;

package/src/resources/extensions/gsd/db-memory-fts-schema.ts

@@ -2,11 +2,18 @@
 // File Purpose: Memory FTS5 SQLite schema helpers for the GSD database facade.
 
 import type { DbAdapter } from "./db-adapter.js";
+import { createRuntimeKvTableV25 } from "./db-runtime-kv-schema.js";
+
+export const MEMORIES_FTS_REBUILT_KEY = "memories_fts_rebuilt_at";
 
 export interface MemoryFtsSchemaOptions {
   onUnavailable?: (message: string) => void;
 }
 
+export interface MemoryFtsRebuildOptions {
+  onRebuildFailed?: (message: string) => void;
+}
+
 function formatFtsUnavailableError(err: unknown): string {
   const message = err instanceof Error ? err.message : String(err);
   return message.replace(/\bmoduel\s*:\s*/gi, "module: ");
@@ -64,3 +71,41 @@ export function isMemoriesFtsAvailableSchema(db: DbAdapter): boolean {
     return false;
   }
 }
+
+export function rebuildMemoriesFtsSchemaOnce(
+  db: DbAdapter,
+  options: MemoryFtsRebuildOptions = {},
+): void {
+  if (!isMemoriesFtsAvailableSchema(db)) return;
+
+  createRuntimeKvTableV25(db);
+  const marker = db.prepare(
+    "SELECT 1 as present FROM runtime_kv WHERE scope = 'global' AND scope_id = '' AND key = :key",
+  ).get({ ":key": MEMORIES_FTS_REBUILT_KEY });
+  if (marker) return;
+
+  const now = new Date().toISOString();
+  try {
+    db.exec("BEGIN");
+    db.exec("INSERT INTO memories_fts(memories_fts) VALUES('rebuild')");
+    db.prepare(
+      `INSERT INTO runtime_kv (scope, scope_id, key, value_json, updated_at)
+       VALUES ('global', '', :key, :value_json, :updated_at)
+       ON CONFLICT (scope, scope_id, key) DO UPDATE SET
+         value_json = excluded.value_json,
+         updated_at = excluded.updated_at`,
+    ).run({
+      ":key": MEMORIES_FTS_REBUILT_KEY,
+      ":value_json": JSON.stringify(now),
+      ":updated_at": now,
+    });
+    db.exec("COMMIT");
+  } catch (err) {
+    try {
+      db.exec("ROLLBACK");
+    } catch {
+      // Best effort: leave startup alive and retry the rebuild on next open.
+    }
+    options.onRebuildFailed?.(`FTS5 rebuild failed: ${(err as Error).message}`);
+  }
+}

package/src/resources/extensions/gsd/db-workspace.ts

@@ -2,7 +2,7 @@
 // File Purpose: Workspace-facing Interface for opening and maintaining the workflow database.
 
 import { existsSync } from "node:fs";
-import { dirname } from "node:path";
+import { dirname, join } from "node:path";
 
 import type { GsdWorkspace, MilestoneScope } from "./workspace.js";
 import type { DbAdapter } from "./db-adapter.js";
@@ -24,8 +24,8 @@ import {
   vacuumDatabase,
   wasDbOpenAttempted,
 } from "./gsd-db.js";
-import { resolveGsdPathContract } from "./paths.js";
-import { setLogBasePath } from "./workflow-logger.js";
+import { resolveGsdPathContract, gsdRoot } from "./paths.js";
+import { logWarning, setLogBasePath } from "./workflow-logger.js";
 
 export interface WorkflowDatabaseLocation {
   projectRoot: string;
@@ -56,6 +56,20 @@ export type WorkflowDatabaseOpenResult =
 export type WorkflowDatabaseStatus = ReturnType<typeof getDbStatus>;
 export type WorkflowDatabaseProvider = ReturnType<typeof getDbProvider>;
 
+/**
+ * Global SQLite handle invariants:
+ *
+ * - `openWorkflowDatabase` / `openDatabase` switch the process-global handle consumed by
+ *   deriveState, dispatch, reconciliation repairs, and domain writers. Only one active
+ *   project database should own the global handle at a time.
+ * - `openWorkflowDatabaseIsolated` opens a caller-owned connection that does not clobber
+ *   the global handle. Use for read-only observers (parallel monitor) and other background
+ *   probes that must not disturb the active workflow session.
+ * - Reconciliation repairs that write markdown/DB state must use `ensureWorkflowDbForBase`
+ *   so repairs target the correct project; those paths intentionally re-open the global handle.
+ * - Pair ad-hoc project switches with `closeWorkflowDatabase()` or restore via
+ *   `ensureWorkflowDbForBase(..., { refresh: true })` before returning to derive/dispatch.
+ */
 export function resolveWorkflowDatabaseLocation(basePath: string): WorkflowDatabaseLocation {
   const contract = resolveGsdPathContract(basePath);
   return {
@@ -172,6 +186,50 @@ export function refreshWorkflowDatabaseFromDisk(): boolean {
   return refreshOpenDatabaseFromDisk();
 }
 
+export function expectedWorkflowDbPathForBase(basePath: string): string {
+  return join(gsdRoot(basePath), "gsd.db");
+}
+
+export interface EnsureWorkflowDbOptions {
+  /** When true, refresh from disk before reopening if already open on the correct path. */
+  refresh?: boolean;
+}
+
+export function ensureWorkflowDbAtPath(dbPath: string | null): boolean {
+  if (!dbPath || dbPath === ":memory:") return isDbAvailable();
+  if (isDbAvailable() && getWorkflowDatabasePath() === dbPath) return true;
+  if (!existsSync(dbPath)) return false;
+  try {
+    return openWorkflowDatabasePath(dbPath);
+  } catch (err) {
+    logWarning("reconcile", `ensureWorkflowDbAtPath could not reopen DB: ${(err as Error).message}`);
+    return false;
+  }
+}
+
+export function ensureWorkflowDbForBase(
+  basePath: string,
+  options: EnsureWorkflowDbOptions = {},
+): boolean {
+  const dbPath = expectedWorkflowDbPathForBase(basePath);
+  if (!existsSync(dbPath)) return false;
+
+  try {
+    if (options.refresh) {
+      if (isDbAvailable() && getWorkflowDatabasePath() === dbPath && refreshWorkflowDatabaseFromDisk()) {
+        return true;
+      }
+      return openWorkflowDatabasePath(dbPath);
+    }
+
+    if (isDbAvailable() && getWorkflowDatabasePath() === dbPath) return true;
+    return openWorkflowDatabasePath(dbPath);
+  } catch (err) {
+    logWarning("reconcile", `ensureWorkflowDbForBase could not reopen DB: ${(err as Error).message}`);
+    return false;
+  }
+}
+
 export function checkpointWorkflowDatabase(): void {
   checkpointDatabase();
 }

package/src/resources/extensions/gsd/delegation-policy.ts

@@ -121,7 +121,7 @@ const POLICY: Record<string, DelegationPolicyEntry> = {
     toolName: "gsd_plan_task",
     verdict: "no",
     rationale:
-      "plan-slice prompt explicitly forbids calling gsd_plan_task separately; per-task granularity multiplies manifest writes and projection re-renders with no payoff.",
+      "Incremental task planning mutates the active slice plan and re-renders projections; keep it ordered in the foreground plan-slice unit.",
   },
 };
 

package/src/resources/extensions/gsd/discussion-handoff.ts

@@ -82,7 +82,13 @@ function ensureMilestoneRowForAcceptedHandoff(
   entry: PendingAutoStartEntry,
   contextFile: string | null,
 ): boolean {
-  if (!isDbAvailable()) return true;
+  if (!isDbAvailable()) {
+    logWarning(
+      "guided",
+      `R3b: milestone ${entry.milestoneId} DB-row recovery skipped because DB is unavailable`,
+    );
+    return false;
+  }
 
   const { basePath, milestoneId } = entry;
   const milestoneRow = getMilestone(milestoneId);
@@ -122,12 +128,14 @@ function ensureMilestoneRowForAcceptedHandoff(
     `(attempt ${entry.r3bRecoveryCount + 1}/${MAX_DB_ROW_RECOVERIES})`,
   );
 
+  let inserted = false;
   try {
-    insertMilestone({ id: milestoneId, title: milestoneId, status: "queued" });
+    inserted = insertMilestone({ id: milestoneId, title: milestoneId, status: "queued" });
   } catch (e) {
     logWarning("guided", `R3b: insertMilestone failed: ${(e as Error).message}`);
   }
 
+  if (inserted) return true;
   if (getMilestone(milestoneId)) return true;
 
   noteDbRowRecoveryMiss(entry);

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -163,7 +163,7 @@ Diagnostics record the file path, scope (global/project), severity (error/warnin
   - **Deprecated:** `merge_to_main` — no longer valid; milestone-level merge is always used. Remove this setting.
 
 - `workspace`: configures multi-repository parent workspaces. Keys:
-  - `mode`: `"project"` (default single-repo behavior) or `"parent"` (one `.gsd` controlling child repos).
+  - `mode`: `"project"` (default single-repo behavior) or `"parent"` (one `.gsd` controlling child repos). In `"parent"` mode at least one child repository must be declared under `repositories`, otherwise the setting is rejected at validation time.
   - `repositories`: object map of repository IDs to config.
     - Repository ID format: `^[A-Za-z0-9][A-Za-z0-9._-]*$`.
     - Reserved ID: `project` is implicit and always maps to the project root; user-defined `workspace.repositories.project` is rejected.
@@ -171,6 +171,8 @@ Diagnostics record the file path, scope (global/project), severity (error/warnin
     - `role`: optional short description of what the repo owns.
     - `verification`: optional array of verification commands for that repo.
     - `commit_policy`: optional `"auto"` or `"skip"` to include or skip commit actions per repo.
+  - Planning tools consume repository IDs through `targetRepositories`: `gsd_plan_slice.targetRepositories` sets a slice-wide default, and `gsd_plan_task.targetRepositories` records the repositories an individual task touches. Values must be declared IDs or the implicit `project`; omit these fields in single-repo projects.
+  - In parent mode with declared child repositories, `/gsd codebase generate` and automatic `.gsd/CODEBASE.md` refreshes enumerate `project` plus each child repository, render repo-labeled sections, and store repository IDs in map metadata.
 
 ## Workspace Example
 
@@ -198,6 +200,8 @@ workspace:
 
 This config sets a parent workspace with two child repositories. The implicit `project` repository is always created for the project root and cannot be user-defined.
 
+In `"parent"` mode, slice/task `targetRepositories` default to the declared child repositories (here `frontend` and `backend`) rather than the root `project` repo. In `"project"` mode (the default), `targetRepositories` defaults to `["project"]`.
+
 - `unique_milestone_ids`: boolean — when `true`, generates milestone IDs in `M{seq}-{rand6}` format (e.g. `M001-eh88as`) instead of plain sequential `M001`. Prevents ID collisions in team workflows where multiple contributors create milestones concurrently. Both formats coexist — existing `M001`-style milestones remain valid. Default: `false`.
 
 - `budget_ceiling`: number — maximum dollar amount to spend on auto-mode. When reached, behavior is controlled by `budget_enforcement`. Default: no limit.
@@ -273,10 +277,10 @@ This config sets a parent workspace with two child repositories. The implicit `p
   - `audit_unified.enabled`: boolean — dual-write unified audit envelope events. Default: `true`.
   - `plan_v2.enabled`: boolean — enable bounded clarify/research/draft/compile planning flow. Default: `true`.
 
-- `context_management`: configures context hygiene for auto-mode sessions. Keys:
+- `context_management`: configures context hygiene for auto-mode sessions. In step mode, the configurable threshold is a soft warning; automatic session re-rooting happens only at the fixed 90% hard context boundary. Keys:
   - `observation_masking`: boolean — mask old tool results to reduce context bloat. Default: `true`.
   - `observation_mask_turns`: number — keep this many recent turns verbatim (1-50). Default: `8`.
-  - `compaction_threshold_percent`: number — trigger compaction at this % of context window (0.5-0.95). Lower values fire compaction earlier, reducing drift. Default: `0.60`.
+  - `compaction_threshold_percent`: number — show a soft context warning at this fraction of the context window (0.5-0.95). Lower values warn earlier so operators can compact manually before drift accumulates. Default: `0.60`.
   - `tool_result_max_chars`: number — max chars per tool result in GSD sessions (200-10000). Default: `800`.
 
 - `auto_visualize`: boolean — show a visualizer hint after each milestone completion in auto-mode. Default: `false`.
@@ -303,7 +307,9 @@ This config sets a parent workspace with two child repositories. The implicit `p
     - `verification`: string[] (optional) — repository-specific verification commands used when global `verification_commands` is not set.
     - `commit_policy`: `"auto"` | `"skip"` (optional) — per-repository closeout commit behavior.
   - `project` is always an implicit repository target mapped to the project root for backward compatibility.
-  - Plan/task `targetRepositories` defaults to `["project"]` when omitted.
+  - `targetRepositories` on `gsd_plan_slice` sets the slice-wide default. `targetRepositories` on `gsd_plan_task` records or overrides the repository IDs for an individual task.
+  - Values must match declared repository IDs or the implicit `project`; omitted plan/task `targetRepositories` defaults to `["project"]`.
+  - `/gsd codebase` is workspace-aware in parent mode with declared child repositories: generated `.gsd/CODEBASE.md` uses workspace-relative paths, groups files under `## [repo-id]` headings, and refreshes when repository registry metadata changes.
 
 - `verification_commands`: string[] — shell commands to run as verification after task execution (e.g., `["npm test", "npm run lint"]`). Commands run in order; if any fails, the task is marked as needing fixes.
 

package/src/resources/extensions/gsd/doctor-engine-checks.ts

@@ -1,19 +1,173 @@
-import { existsSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
 
 import type { DoctorIssue } from "./doctor-types.js";
-import { isDbAvailable, _getAdapter } from "./gsd-db.js";
+import {
+  getAllMilestones,
+  getMilestoneSlices,
+  getSliceTasks,
+  isDbAvailable,
+  isMemoriesFtsAvailable,
+  _getAdapter,
+} from "./gsd-db.js";
+import { MEMORIES_FTS_REBUILT_KEY } from "./db-memory-fts-schema.js";
 import { isAfter, latestExplicitReopenAt } from "./milestone-reopen-events.js";
-import { resolveGsdPathContract, resolveMilestoneFile } from "./paths.js";
+import { gsdProjectionRoot, gsdRoot, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "./paths.js";
 import { deriveState } from "./state.js";
+import { isClosedStatus } from "./status-guards.js";
 import { workflowEventLogPath } from "./workflow-event-ledger.js";
 import { readEvents } from "./workflow-events.js";
 import { flushWorkflowProjections } from "./projection-flush.js";
+import { parseRoadmapSlices } from "./roadmap-slices.js";
+import { parsePlan } from "./parsers-legacy.js";
+
+const USER_AUTHORED_ARTIFACT_TYPES = new Set(["CONTEXT", "RESEARCH"]);
+
+function relativeFile(basePath: string, filePath: string): string {
+  return relative(basePath, filePath).split("\\").join("/");
+}
+
+function normalizedArtifactType(artifactType: string): string {
+  return artifactType.trim().toUpperCase();
+}
+
+function isUserAuthoredArtifactType(artifactType: string): boolean {
+  return USER_AUTHORED_ARTIFACT_TYPES.has(normalizedArtifactType(artifactType));
+}
+
+function userContentRecoveryCommand(artifactType: string): string {
+  return normalizedArtifactType(artifactType) === "CONTEXT" ? "/gsd discuss" : "/gsd auto";
+}
+
+function userContentMissingMessage(path: string, artifactType: string): string {
+  const type = normalizedArtifactType(artifactType) || "UNKNOWN";
+  return `Artifact \`${path}\` is a user-authored ${type} file recorded in the database but missing from disk. Re-run \`${userContentRecoveryCommand(type)}\` in this milestone to regenerate it.`;
+}
+
+function reportCheckboxDbStatusDivergence(
+  issues: DoctorIssue[],
+  basePath: string,
+  filePath: string,
+  scope: "slice" | "task",
+  unitId: string,
+  status: string,
+  checkboxDone: boolean,
+): void {
+  const dbDone = isClosedStatus(status);
+  if (checkboxDone === dbDone) return;
+
+  issues.push({
+    severity: "error",
+    code: "checkbox_db_status_divergence",
+    scope,
+    unitId,
+    message: `${scope === "slice" ? "Slice" : "Task"} ${unitId} is ${dbDone ? "closed" : "open"} in the database (status: ${status}) but the markdown checkbox is ${checkboxDone ? "checked" : "unchecked"}.`,
+    file: relativeFile(basePath, filePath),
+    fixable: false,
+  });
+}
+
+function checkProjectionCheckboxDbStatus(basePath: string, milestoneIds: string[], issues: DoctorIssue[]): void {
+  for (const milestoneId of milestoneIds) {
+    const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+    const slices = getMilestoneSlices(milestoneId);
+
+    if (roadmapPath && existsSync(roadmapPath)) {
+      try {
+        const roadmap = readFileSync(roadmapPath, "utf-8");
+        const sliceDoneById = new Map(parseRoadmapSlices(roadmap).map((entry) => [entry.id, entry.done]));
+        for (const slice of slices) {
+          const checkboxDone = sliceDoneById.get(slice.id);
+          if (checkboxDone === undefined) continue;
+          reportCheckboxDbStatusDivergence(
+            issues,
+            basePath,
+            roadmapPath,
+            "slice",
+            `${milestoneId}/${slice.id}`,
+            slice.status,
+            checkboxDone,
+          );
+        }
+      } catch {
+        // Non-fatal — checkbox drift diagnostics must never block doctor.
+      }
+    }
+
+    for (const slice of slices) {
+      const planPath = resolveSliceFile(basePath, milestoneId, slice.id, "PLAN");
+      if (!planPath || !existsSync(planPath)) continue;
+      try {
+        const plan = readFileSync(planPath, "utf-8");
+        // parsePlan reads the authoritative task checkboxes (the flat-phase
+        // <tasks> block / ## Tasks section), so a stray task-style checkbox
+        // line elsewhere in PLAN.md (e.g. a Must-Haves or Verification bullet
+        // above <tasks>) can no longer hide real drift or fake a divergence.
+        const taskDoneById = new Map(parsePlan(plan).tasks.map((entry) => [entry.id, entry.done]));
+        for (const task of getSliceTasks(milestoneId, slice.id)) {
+          const checkboxDone = taskDoneById.get(task.id);
+          if (checkboxDone === undefined) continue;
+          reportCheckboxDbStatusDivergence(
+            issues,
+            basePath,
+            planPath,
+            "task",
+            `${milestoneId}/${slice.id}/${task.id}`,
+            task.status,
+            checkboxDone,
+          );
+        }
+      } catch {
+        // Non-fatal — checkbox drift diagnostics must never block doctor.
+      }
+    }
+  }
+}
+
+function isClearedByMilestoneShellProjectionFlush(
+  basePath: string,
+  issue: DoctorIssue,
+  reRenderedMilestoneIds: Set<string>,
+): boolean {
+  if (issue.code !== "checkbox_db_status_divergence") return false;
+  if (issue.scope !== "slice") return false;
+
+  const milestoneId = issue.unitId.split("/")[0] ?? "";
+  if (!reRenderedMilestoneIds.has(milestoneId)) return false;
+
+  const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+  if (!roadmapPath || !issue.file) return false;
+
+  return issue.file === relativeFile(basePath, roadmapPath);
+}
+
+function artifactExistsOnDisk(basePath: string, artifactPath: string): boolean {
+  if (isAbsolute(artifactPath)) return existsSync(artifactPath);
+  return [
+    join(gsdProjectionRoot(basePath), artifactPath),
+    join(gsdRoot(basePath), artifactPath),
+  ].some((candidate) => existsSync(candidate));
+}
+
+function artifactUnitId(row: { milestone_id: string | null; slice_id: string | null; task_id: string | null }): string {
+  if (!row.milestone_id) return "project";
+  if (row.slice_id && row.task_id) return `${row.milestone_id}/${row.slice_id}/${row.task_id}`;
+  if (row.slice_id) return `${row.milestone_id}/${row.slice_id}`;
+  return row.milestone_id;
+}
+
+function artifactScope(row: { milestone_id: string | null; slice_id: string | null; task_id: string | null }): DoctorIssue["scope"] {
+  if (row.task_id) return "task";
+  if (row.slice_id) return "slice";
+  if (row.milestone_id) return "milestone";
+  return "project";
+}
 
 export async function checkEngineHealth(
   basePath: string,
   issues: DoctorIssue[],
   fixesApplied: string[],
+  options?: { repair?: boolean },
 ): Promise<void> {
   const dbPath = resolveGsdPathContract(basePath).projectDb;
 
@@ -34,6 +188,32 @@ export async function checkEngineHealth(
     if (isDbAvailable()) {
       const adapter = _getAdapter()!;
 
+      try {
+        if (isMemoriesFtsAvailable(adapter)) {
+          const runtimeKv = adapter
+            .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='runtime_kv'")
+            .get();
+          const marker = runtimeKv
+            ? adapter.prepare(
+                "SELECT 1 as present FROM runtime_kv WHERE scope = 'global' AND scope_id = '' AND key = :key",
+              ).get({ ":key": MEMORIES_FTS_REBUILT_KEY })
+            : undefined;
+          if (!marker) {
+            issues.push({
+              severity: "warning",
+              code: "memories_fts_rebuild_missing",
+              scope: "project",
+              unitId: "project",
+              message: `Memory full-text index exists but runtime_kv has no ${MEMORIES_FTS_REBUILT_KEY} marker. The index may be stale or incomplete, so memory search can silently degrade to the LIKE fallback.`,
+              file: ".gsd/gsd.db",
+              fixable: false,
+            });
+          }
+        }
+      } catch {
+        // Non-fatal — memory FTS health check failed
+      }
+
       // a. Orphaned tasks (task.slice_id points to non-existent slice)
       try {
         const orphanedTasks = adapter
@@ -196,7 +376,63 @@ export async function checkEngineHealth(
         // Non-fatal — completed-milestone reopen check failed
       }
 
-      // f. Completion artifacts disagree with open DB hierarchy rows.
+      // f. Artifact rows reference files that no longer exist on disk.
+      const missingUserContentArtifacts: Array<{ path: string; artifactType: string }> = [];
+      try {
+        const artifactRows = adapter
+          .prepare(
+            `SELECT path, artifact_type, milestone_id, slice_id, task_id
+             FROM artifacts
+             WHERE path != ''
+             ORDER BY path`,
+          )
+          .all() as Array<{
+            path: string;
+            artifact_type: string;
+            milestone_id: string | null;
+            slice_id: string | null;
+            task_id: string | null;
+          }>;
+
+        for (const row of artifactRows) {
+          if (artifactExistsOnDisk(basePath, row.path)) continue;
+          const unitId = artifactUnitId(row);
+          if (isUserAuthoredArtifactType(row.artifact_type)) {
+            const artifactType = normalizedArtifactType(row.artifact_type);
+            missingUserContentArtifacts.push({ path: row.path, artifactType });
+            issues.push({
+              severity: "warning",
+              code: "artifact_user_content_missing",
+              scope: artifactScope(row),
+              unitId,
+              message: userContentMissingMessage(row.path, artifactType),
+              file: row.path,
+              fixable: false,
+            });
+            continue;
+          }
+          issues.push({
+            severity: "error",
+            code: "artifact_file_missing",
+            scope: artifactScope(row),
+            unitId,
+            message: `Artifact ${row.path} is recorded in the database as ${row.artifact_type || "UNKNOWN"} but no matching file exists on disk`,
+            file: row.path,
+            fixable: false,
+          });
+        }
+      } catch {
+        // Non-fatal — artifact file existence check failed
+      }
+      if (options?.repair) {
+        for (const artifact of missingUserContentArtifacts) {
+          fixesApplied.push(
+            `skipped user-authored ${artifact.artifactType} artifact ${artifact.path} (content cannot be regenerated from the database)`,
+          );
+        }
+      }
+
+      // g. Completion artifacts disagree with open DB hierarchy rows.
       try {
         const rows = adapter
           .prepare(
@@ -225,6 +461,7 @@ export async function checkEngineHealth(
 
         const seen = new Set<string>();
         for (const row of rows) {
+          if (!artifactExistsOnDisk(basePath, row.path)) continue;
           const reopenAt = latestExplicitReopenAt(basePath, row.milestone_id);
           if (!isAfter(row.imported_at, reopenAt)) continue;
           const isSliceSummary = row.slice_id && !row.task_id && row.slice_status && !["complete", "done", "skipped", "closed"].includes(row.slice_status);
@@ -256,9 +493,24 @@ export async function checkEngineHealth(
     // Non-fatal — DB constraint checks failed entirely
   }
 
+  // Checkbox-vs-DB divergence detection runs before projection drift auto-fix
+  // so stale re-renders cannot overwrite manually edited markdown first. Runs
+  // inside its own try/catch: getAllMilestones / getMilestoneSlices /
+  // getSliceTasks issue prepared queries that can throw on a corrupt or locked
+  // DB, and like every other DB-touching check here this diagnostic must never
+  // block doctor.
+  try {
+    if (isDbAvailable()) {
+      checkProjectionCheckboxDbStatus(basePath, getAllMilestones().map((milestone) => milestone.id), issues);
+    }
+  } catch {
+    // Non-fatal: checkbox-vs-DB divergence check must never block doctor
+  }
+
   // ── Projection drift detection ──────────────────────────────────────────
   // If the DB is available, check whether markdown projections are stale
   // relative to the event log and re-render them.
+  const reRenderedMilestoneIds: string[] = [];
   try {
     if (isDbAvailable()) {
       const eventLogPath = workflowEventLogPath(basePath);
@@ -273,6 +525,7 @@ export async function checkEngineHealth(
             try {
               await flushWorkflowProjections(basePath, { milestoneId: milestone.id });
               fixesApplied.push(`re-rendered missing projections for ${milestone.id}`);
+              reRenderedMilestoneIds.push(milestone.id);
             } catch {
               // Non-fatal — projection re-render failed
             }
@@ -283,6 +536,7 @@ export async function checkEngineHealth(
             try {
               await flushWorkflowProjections(basePath, { milestoneId: milestone.id });
               fixesApplied.push(`re-rendered stale projections for ${milestone.id}`);
+              reRenderedMilestoneIds.push(milestone.id);
             } catch {
               // Non-fatal — projection re-render failed
             }
@@ -293,4 +547,20 @@ export async function checkEngineHealth(
   } catch {
     // Non-fatal — projection drift check must never block doctor
   }
+
+  if (reRenderedMilestoneIds.length > 0) {
+    const reRendered = new Set(reRenderedMilestoneIds);
+    for (let i = issues.length - 1; i >= 0; i--) {
+      const issue = issues[i]!;
+      // flushWorkflowProjections re-renders milestone shell projections (not
+      // slice PLAN.md files), so only clear stale ROADMAP checkbox diagnostics.
+      if (isClearedByMilestoneShellProjectionFlush(basePath, issue, reRendered)) {
+        issues.splice(i, 1);
+        continue;
+      }
+      if (issue.code === "artifact_file_missing" && issue.file && artifactExistsOnDisk(basePath, issue.file)) {
+        issues.splice(i, 1);
+      }
+    }
+  }
 }