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

package/src/resources/extensions/gsd/tests/doctor-providers.test.ts

@@ -20,6 +20,7 @@ import { tmpdir } from "node:os";
 
 import {
   runProviderChecks,
+  runProviderChecksAsync,
   formatProviderReport,
   summariseProviderIssues,
   type ProviderCheckResult,
@@ -47,6 +48,26 @@ function withEnv(vars: Record<string, string | undefined>, fn: () => void): void
   }
 }
 
+async function withEnvAsync(vars: Record<string, string | undefined>, fn: () => Promise<void>): Promise<void> {
+  const saved: Record<string, string | undefined> = {};
+  for (const [k, v] of Object.entries(vars)) {
+    saved[k] = process.env[k];
+    if (v === undefined) {
+      delete process.env[k];
+    } else {
+      process.env[k] = v;
+    }
+  }
+  try {
+    await fn();
+  } finally {
+    for (const [k, v] of Object.entries(saved)) {
+      if (v === undefined) delete process.env[k];
+      else process.env[k] = v;
+    }
+  }
+}
+
 function withCwd(nextCwd: string, fn: () => void): void {
   const saved = process.cwd();
   process.chdir(nextCwd);
@@ -57,6 +78,22 @@ function withCwd(nextCwd: string, fn: () => void): void {
   }
 }
 
+async function withCwdAsync(nextCwd: string, fn: () => Promise<void>): Promise<void> {
+  const saved = process.cwd();
+  process.chdir(nextCwd);
+  try {
+    await fn();
+  } finally {
+    process.chdir(saved);
+  }
+}
+
+function normalizeProviderResults(results: ProviderCheckResult[]): string[] {
+  return results
+    .map(r => `${r.name}|${r.label}|${r.category}|${r.status}|${r.message}|${r.detail ?? ""}|${r.required}`)
+    .sort();
+}
+
 const PRESENT_TEST_VALUE = "configured";
 
 // ─── formatProviderReport ─────────────────────────────────────────────────────
@@ -377,6 +414,76 @@ test("runProviderChecks detects custom provider keys from models.json", () => {
   rmSync(tmpHome, { recursive: true, force: true });
 });
 
+test("runProviderChecksAsync matches sync for models.json keys and PATH CLI checks", async () => {
+  const tmpHome = realpathSync(mkdtempSync(join(tmpdir(), "gsd-providers-async-home-")));
+  const repo = realpathSync(mkdtempSync(join(tmpdir(), "gsd-providers-async-repo-")));
+  const agentDir = join(tmpHome, ".gsd", "agent");
+  const binDir = join(tmpHome, "bin");
+  mkdirSync(agentDir, { recursive: true });
+  mkdirSync(binDir, { recursive: true });
+  mkdirSync(join(repo, ".gsd"), { recursive: true });
+
+  writeFileSync(
+    join(repo, ".gsd", "PREFERENCES.md"),
+    [
+      "---",
+      "models:",
+      "  execution:",
+      "    model: custom-model",
+      "    provider: custom-provider",
+      "  validation:",
+      "    model: gemini-2.5-pro",
+      "    provider: google-gemini-cli",
+      "---",
+      "",
+    ].join("\n"),
+  );
+  writeFileSync(join(agentDir, "models.json"), JSON.stringify({
+    providers: {
+      "custom-provider": {
+        api: "openai-completions",
+        apiKey: "x",
+        baseUrl: "https://example.invalid/v1",
+        models: [{ id: "custom-model", name: "Custom Model" }],
+      },
+    },
+  }));
+
+  const fakeGemini = join(binDir, "gemini");
+  writeFileSync(fakeGemini, "#!/bin/sh\necho mock\n");
+  chmodSync(fakeGemini, 0o755);
+
+  try {
+    await withEnvAsync({
+      HOME: tmpHome,
+      CUSTOM_PROVIDER_API_KEY: undefined,
+      GEMINI_API_KEY: undefined,
+      GOOGLE_API_KEY: undefined,
+      PATH: binDir,
+    }, async () => {
+      await withCwdAsync(repo, async () => {
+        const syncResults = runProviderChecks();
+        const asyncResults = await runProviderChecksAsync();
+
+        assert.deepEqual(normalizeProviderResults(asyncResults), normalizeProviderResults(syncResults));
+        assert.equal(
+          asyncResults.find(r => r.name === "custom-provider")?.status,
+          "ok",
+          "models.json apiKey should satisfy custom provider auth",
+        );
+        assert.equal(
+          asyncResults.find(r => r.name === "google-gemini-cli")?.status,
+          "ok",
+          "gemini CLI binary should satisfy explicit CLI provider",
+        );
+      });
+    });
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+    rmSync(tmpHome, { recursive: true, force: true });
+  }
+});
+
 test("runProviderChecks reports missing custom provider key without models.json apiKey", () => {
   const tmpHome = realpathSync(mkdtempSync(join(tmpdir(), "gsd-providers-custom-missing-home-")));
   const repo = realpathSync(mkdtempSync(join(tmpdir(), "gsd-providers-custom-missing-repo-")));
@@ -907,6 +1014,143 @@ test("runProviderChecks detects claude.exe in PATH on Windows (#4548)", { skip:
   });
 });
 
+
+test("runProviderChecks reports error for required cursor-agent when binary is missing", () => {
+  const repo = realpathSync(mkdtempSync(join(tmpdir(), "gsd-providers-cursor-repo-")));
+  mkdirSync(join(repo, ".gsd"), { recursive: true });
+  writeFileSync(
+    join(repo, ".gsd", "PREFERENCES.md"),
+    [
+      "---",
+      "models:",
+      "  execution:",
+      "    model: composer-2.5",
+      "    provider: cursor-agent",
+      "---",
+      "",
+    ].join("\n"),
+  );
+
+  const tmpHome = realpathSync(mkdtempSync(join(tmpdir(), "gsd-providers-cursor-home-")));
+
+  withEnv({
+    HOME: tmpHome,
+    PATH: tmpHome,
+    CURSOR_API_KEY: undefined,
+  }, () => {
+    withCwd(repo, () => {
+      const results = runProviderChecks();
+      const cursor = results.find(r => r.name === "cursor-agent");
+      assert.ok(cursor, "cursor-agent result should exist");
+      assert.equal(cursor!.status, "error", "cursor-agent should error when the CLI binary is missing");
+      assert.ok(cursor!.detail?.includes("Cursor Agent"), "should explain Cursor Agent must be installed");
+    });
+  });
+
+  rmSync(repo, { recursive: true, force: true });
+  rmSync(tmpHome, { recursive: true, force: true });
+});
+
+test("runProviderChecks does not route OpenAI via unauthenticated cursor-agent binary in PATH", () => {
+  const repo = realpathSync(mkdtempSync(join(tmpdir(), "gsd-providers-cursor-route-repo-")));
+  mkdirSync(join(repo, ".gsd"), { recursive: true });
+  writeFileSync(
+    join(repo, ".gsd", "PREFERENCES.md"),
+    [
+      "---",
+      "models:",
+      "  execution: gpt-5.5",
+      "---",
+      "",
+    ].join("\n"),
+  );
+
+  const tmpHome = realpathSync(mkdtempSync(join(tmpdir(), "gsd-providers-cursor-route-home-")));
+  const binDir = join(tmpHome, "bin");
+  mkdirSync(binDir, { recursive: true });
+  const fakeCursor = join(binDir, "cursor-agent");
+  writeFileSync(fakeCursor, [
+    "#!/bin/sh",
+    "if [ \"$1\" = \"status\" ]; then echo \"Not logged in\"; exit 0; fi",
+    "echo mock",
+    "",
+  ].join("\n"));
+  chmodSync(fakeCursor, 0o755);
+
+  withEnv({
+    HOME: tmpHome,
+    OPENAI_API_KEY: undefined,
+    COPILOT_GITHUB_TOKEN: undefined,
+    GH_TOKEN: undefined,
+    GITHUB_TOKEN: undefined,
+    PATH: `${binDir}${delimiter}${process.env.PATH ?? ""}`,
+  }, () => {
+    try {
+      withCwd(repo, () => {
+        const results = runProviderChecks();
+        const openai = results.find(r => r.name === "openai");
+        assert.ok(openai, "openai result should exist");
+        assert.equal(openai!.status, "error", "binary-only cursor-agent must not satisfy OpenAI routing");
+        assert.ok(openai!.detail?.includes("OPENAI_API_KEY"), "should still tell the user how to configure OpenAI");
+      });
+    } finally {
+      rmSync(repo, { recursive: true, force: true });
+      rmSync(tmpHome, { recursive: true, force: true });
+    }
+  });
+});
+
+test("runProviderChecks routes OpenAI via authenticated cursor-agent CLI", () => {
+  const repo = realpathSync(mkdtempSync(join(tmpdir(), "gsd-providers-cursor-auth-route-repo-")));
+  mkdirSync(join(repo, ".gsd"), { recursive: true });
+  writeFileSync(
+    join(repo, ".gsd", "PREFERENCES.md"),
+    [
+      "---",
+      "models:",
+      "  execution: gpt-5.5",
+      "---",
+      "",
+    ].join("\n"),
+  );
+
+  const tmpHome = realpathSync(mkdtempSync(join(tmpdir(), "gsd-providers-cursor-auth-route-home-")));
+  const binDir = join(tmpHome, "bin");
+  mkdirSync(binDir, { recursive: true });
+  const fakeCursor = join(binDir, "cursor-agent");
+  writeFileSync(fakeCursor, [
+    "#!/bin/sh",
+    "if [ \"$1\" = \"--version\" ]; then echo cursor-agent 1.0; exit 0; fi",
+    "if [ \"$1\" = \"status\" ]; then echo \"Authenticated as user@example.com\"; exit 0; fi",
+    "echo mock",
+    "",
+  ].join("\n"));
+  chmodSync(fakeCursor, 0o755);
+
+  withEnv({
+    HOME: tmpHome,
+    OPENAI_API_KEY: undefined,
+    COPILOT_GITHUB_TOKEN: undefined,
+    GH_TOKEN: undefined,
+    GITHUB_TOKEN: undefined,
+    CURSOR_API_KEY: undefined,
+    PATH: `${binDir}${delimiter}${process.env.PATH ?? ""}`,
+  }, () => {
+    try {
+      withCwd(repo, () => {
+        const results = runProviderChecks();
+        const openai = results.find(r => r.name === "openai");
+        assert.ok(openai, "openai result should exist");
+        assert.equal(openai!.status, "ok", "authenticated cursor-agent should satisfy OpenAI routing");
+        assert.ok(openai!.message.toLowerCase().includes("cursor"), "should mention cursor-agent as source");
+      });
+    } finally {
+      rmSync(repo, { recursive: true, force: true });
+      rmSync(tmpHome, { recursive: true, force: true });
+    }
+  });
+});
+
 test("PROVIDER_ROUTES includes google-antigravity and google-gemini-cli as routes for google (#2922)", async () => {
   const { readFileSync: readFS } = await import("node:fs");
   const { dirname: dirn, join: joinPath } = await import("node:path");
@@ -915,7 +1159,7 @@ test("PROVIDER_ROUTES includes google-antigravity and google-gemini-cli as route
   const src = readFS(joinPath(__dir, "..", "doctor-providers.ts"), "utf-8");
 
   assert.ok(
-    src.includes('google: ["google-antigravity", "google-gemini-cli"]'),
+    src.includes('google: ["google-antigravity", "google-gemini-cli", "cursor-agent"]'),
     'PROVIDER_ROUTES must prefer "google-antigravity" over "google-gemini-cli" for google (#2922)',
   );
 });

package/src/resources/extensions/gsd/tests/doctor-scope-db-unavailable.test.ts

@@ -1,12 +1,22 @@
 import { afterEach, test } from "node:test";
 import assert from "node:assert/strict";
-import { _getAdapter, closeDatabase, insertMilestone, openDatabase } from "../gsd-db.ts";
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import {
+  _getAdapter,
+  closeDatabase,
+  insertArtifact,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+  openDatabase,
+} from "../gsd-db.ts";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { filterDoctorIssues } from "../doctor-format.ts";
 import { checkEngineHealth } from "../doctor-engine-checks.ts";
+import { MEMORIES_FTS_REBUILT_KEY } from "../db-memory-fts-schema.ts";
 import { appendEvent } from "../workflow-events.ts";
+import { renderPlanFromDb, renderRoadmapFromDb } from "../markdown-renderer.ts";
 
 afterEach(() => {
   closeDatabase();
@@ -61,6 +71,139 @@ test("checkEngineHealth reports db_unavailable when gsd.db exists but the DB is
   assert.equal(dbIssue.file, ".gsd/gsd.db");
 });
 
+test("checkEngineHealth reports memories_fts without the rebuild marker", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-doctor-memory-fts-marker-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  const gsdDir = join(base, ".gsd");
+  mkdirSync(gsdDir, { recursive: true });
+
+  openDatabase(join(gsdDir, "gsd.db"));
+  const adapter = _getAdapter()!;
+  const fts = adapter.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='memories_fts'").get();
+  if (!fts) return;
+
+  adapter.prepare(
+    "DELETE FROM runtime_kv WHERE scope = 'global' AND scope_id = '' AND key = :key",
+  ).run({ ":key": MEMORIES_FTS_REBUILT_KEY });
+
+  const issues: any[] = [];
+  await checkEngineHealth(base, issues, []);
+
+  const ftsIssue = issues.find((issue) => issue.code === "memories_fts_rebuild_missing");
+  assert.ok(ftsIssue, "doctor should surface a potentially desynced memory FTS index");
+  assert.equal(ftsIssue.severity, "warning");
+  assert.equal(ftsIssue.unitId, "project");
+  assert.equal(ftsIssue.file, ".gsd/gsd.db");
+  assert.equal(ftsIssue.fixable, false);
+});
+
+test("checkEngineHealth reports checkbox divergence against DB status", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-doctor-checkbox-drift-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  const gsdDir = join(base, ".gsd");
+  mkdirSync(gsdDir, { recursive: true });
+
+  openDatabase(join(gsdDir, "gsd.db"));
+  insertMilestone({ id: "M001", title: "Foundation", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Slice", status: "pending", risk: "low", depends: [], sequence: 1 });
+  insertTask({ id: "T01", milestoneId: "M001", sliceId: "S01", title: "Task", status: "complete", sequence: 1 });
+
+  const roadmap = await renderRoadmapFromDb(base, "M001");
+  if ("skipped" in roadmap) assert.fail("planned milestone should render a roadmap");
+  const plan = await renderPlanFromDb(base, "M001", "S01");
+
+  writeFileSync(roadmap.roadmapPath, readFileSync(roadmap.roadmapPath, "utf-8").replace("- [ ] **S01:", "- [x] **S01:"), "utf-8");
+  writeFileSync(plan.planPath, readFileSync(plan.planPath, "utf-8").replace("- [x] **T01**:", "- [ ] **T01**:"), "utf-8");
+
+  const issues: any[] = [];
+  await checkEngineHealth(base, issues, []);
+
+  const divergences = issues.filter((issue) => issue.code === "checkbox_db_status_divergence");
+  assert.deepEqual(
+    divergences.map((issue) => issue.unitId).sort(),
+    ["M001/S01", "M001/S01/T01"],
+  );
+});
+
+test("checkEngineHealth keeps PLAN checkbox divergence after stale projection flush", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-doctor-checkbox-plan-drift-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  const gsdDir = join(base, ".gsd");
+  mkdirSync(gsdDir, { recursive: true });
+
+  openDatabase(join(gsdDir, "gsd.db"));
+  insertMilestone({ id: "M001", title: "Foundation", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Slice", status: "pending", risk: "low", depends: [], sequence: 1 });
+  insertTask({ id: "T01", milestoneId: "M001", sliceId: "S01", title: "Task", status: "complete", sequence: 1 });
+
+  const roadmap = await renderRoadmapFromDb(base, "M001");
+  if ("skipped" in roadmap) assert.fail("planned milestone should render a roadmap");
+  const plan = await renderPlanFromDb(base, "M001", "S01");
+
+  writeFileSync(roadmap.roadmapPath, readFileSync(roadmap.roadmapPath, "utf-8").replace("- [ ] **S01:", "- [x] **S01:"), "utf-8");
+  writeFileSync(plan.planPath, readFileSync(plan.planPath, "utf-8").replace("- [x] **T01**:", "- [ ] **T01**:"), "utf-8");
+  appendEvent(base, {
+    cmd: "complete-task",
+    params: { milestoneId: "M001", sliceId: "S01", taskId: "T01" },
+    ts: "2999-01-01T00:00:00.000Z",
+    actor: "agent",
+  });
+
+  const issues: any[] = [];
+  const fixes: string[] = [];
+  await checkEngineHealth(base, issues, fixes);
+
+  const divergences = issues.filter((issue) => issue.code === "checkbox_db_status_divergence");
+  assert.deepEqual(
+    divergences.map((issue) => issue.unitId),
+    ["M001/S01/T01"],
+    "stale ROADMAP divergence is cleared after re-render, but stale PLAN task divergence remains",
+  );
+  assert.ok(fixes.includes("re-rendered stale projections for M001"));
+  assert.match(readFileSync(plan.planPath, "utf-8"), /- \[ \] \*\*T01\*\*:/);
+});
+
+test("checkEngineHealth reads task checkboxes from the <tasks> block, not a stray line above it", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-doctor-task-section-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  const gsdDir = join(base, ".gsd");
+  mkdirSync(gsdDir, { recursive: true });
+
+  openDatabase(join(gsdDir, "gsd.db"));
+  insertMilestone({ id: "M001", title: "Foundation", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Slice", status: "pending", risk: "low", depends: [], sequence: 1 });
+  insertTask({ id: "T01", milestoneId: "M001", sliceId: "S01", title: "Task", status: "complete", sequence: 1 });
+
+  const roadmap = await renderRoadmapFromDb(base, "M001");
+  if ("skipped" in roadmap) assert.fail("planned milestone should render a roadmap");
+  const plan = await renderPlanFromDb(base, "M001", "S01");
+
+  // Flip the authoritative <tasks> checkbox so it disagrees with the DB
+  // (DB: complete, markdown: unchecked = real drift), then inject a *checked*
+  // decoy line for the same task above the <tasks> block. The old whole-file
+  // regex matched the decoy first and hid the real drift; parsePlan reads the
+  // authoritative <tasks> block and still reports it. No events are appended,
+  // so the projection-drift re-render never runs and the crafted file stands.
+  const rendered = readFileSync(plan.planPath, "utf-8")
+    .replace("- [x] **T01**:", "- [ ] **T01**:")
+    .replace("<tasks>\n", "- [x] **T01**: stale duplicate above the tasks block\n\n<tasks>\n");
+  writeFileSync(plan.planPath, rendered, "utf-8");
+
+  const issues: any[] = [];
+  await checkEngineHealth(base, issues, []);
+
+  const divergences = issues.filter((issue) => issue.code === "checkbox_db_status_divergence");
+  assert.deepEqual(
+    divergences.map((issue) => issue.unitId),
+    ["M001/S01/T01"],
+    "task drift must be read from the authoritative <tasks> block, not a stray checkbox above it",
+  );
+});
+
 test("checkEngineHealth reads canonical reopen events from worktree bases", async (t) => {
   const base = mkdtempSync(join(tmpdir(), "gsd-doctor-reopen-worktree-"));
   t.after(() => rmSync(base, { recursive: true, force: true }));
@@ -149,3 +292,154 @@ test("checkEngineHealth treats explicit reopen as authoritative when dispatch ti
     "explicit reopen should exempt reopened milestone even when completion dispatch timestamps are absent",
   );
 });
+
+test("checkEngineHealth reports artifact rows whose files are missing on disk", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-doctor-missing-artifact-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  const gsdDir = join(base, ".gsd");
+  const worktree = join(gsdDir, "worktrees", "M001");
+  mkdirSync(join(worktree, ".gsd", "milestones", "M001"), { recursive: true });
+  writeFileSync(join(worktree, ".git"), "gitdir: ../../../../.git/worktrees/M001\n", "utf-8");
+  writeFileSync(join(worktree, ".gsd", "milestones", "M001", "M001-CONTEXT.md"), "# Context\n", "utf-8");
+
+  openDatabase(join(gsdDir, "gsd.db"));
+  insertArtifact({
+    path: "milestones/M001/M001-CONTEXT.md",
+    artifact_type: "CONTEXT",
+    milestone_id: "M001",
+    slice_id: null,
+    task_id: null,
+    full_content: "# Context\n",
+  });
+  insertArtifact({
+    path: "milestones/M001/M001-MISSING.md",
+    artifact_type: "PLAN",
+    milestone_id: "M001",
+    slice_id: null,
+    task_id: null,
+    full_content: "# Missing\n",
+  });
+
+  const issues: any[] = [];
+  await checkEngineHealth(worktree, issues, []);
+
+  assert.equal(
+    issues.some((issue) => issue.code === "artifact_file_missing" && issue.file === "milestones/M001/M001-CONTEXT.md"),
+    false,
+    "worktree-local artifacts should resolve through the projection root",
+  );
+  const missing = issues.find((issue) => issue.code === "artifact_file_missing" && issue.file === "milestones/M001/M001-MISSING.md");
+  assert.ok(missing, "missing artifact rows should be reported");
+  assert.equal(missing.unitId, "M001");
+  assert.equal(missing.fixable, false);
+});
+
+test("checkEngineHealth reports missing CONTEXT and RESEARCH artifacts as user-content warnings", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-doctor-user-content-artifact-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  const gsdDir = join(base, ".gsd");
+  mkdirSync(gsdDir, { recursive: true });
+
+  openDatabase(join(gsdDir, "gsd.db"));
+  insertArtifact({
+    path: "milestones/M002/M002-CONTEXT.md",
+    artifact_type: "CONTEXT",
+    milestone_id: "M002",
+    slice_id: null,
+    task_id: null,
+    full_content: "# Context\n",
+  });
+  insertArtifact({
+    path: "milestones/M002/M002-RESEARCH.md",
+    artifact_type: "RESEARCH",
+    milestone_id: "M002",
+    slice_id: null,
+    task_id: null,
+    full_content: "# Research\n",
+  });
+
+  const issues: any[] = [];
+  const fixes: string[] = [];
+  await checkEngineHealth(base, issues, fixes, { repair: true });
+
+  assert.equal(
+    issues.some((issue) => issue.code === "artifact_file_missing"),
+    false,
+    "missing user-authored artifacts should not be reported as blocking projection errors",
+  );
+
+  const contextIssue = issues.find((issue) => issue.code === "artifact_user_content_missing" && issue.file === "milestones/M002/M002-CONTEXT.md");
+  assert.ok(contextIssue, "missing CONTEXT should use the user-content code");
+  assert.equal(contextIssue.severity, "warning");
+  assert.equal(contextIssue.unitId, "M002");
+  assert.equal(
+    contextIssue.message,
+    "Artifact `milestones/M002/M002-CONTEXT.md` is a user-authored CONTEXT file recorded in the database but missing from disk. Re-run `/gsd discuss` in this milestone to regenerate it.",
+  );
+
+  const researchIssue = issues.find((issue) => issue.code === "artifact_user_content_missing" && issue.file === "milestones/M002/M002-RESEARCH.md");
+  assert.ok(researchIssue, "missing RESEARCH should use the user-content code");
+  assert.equal(researchIssue.severity, "warning");
+
+  assert.ok(
+    fixes.some((fix) => fix === "skipped user-authored CONTEXT artifact milestones/M002/M002-CONTEXT.md (content cannot be regenerated from the database)"),
+    "repair output should explain skipped CONTEXT content",
+  );
+  assert.ok(
+    fixes.some((fix) => fix === "skipped user-authored RESEARCH artifact milestones/M002/M002-RESEARCH.md (content cannot be regenerated from the database)"),
+    "repair output should explain skipped RESEARCH content",
+  );
+});
+
+test("checkEngineHealth clears artifact_file_missing after projection re-render recreates the file", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-doctor-stale-missing-artifact-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  const gsdDir = join(base, ".gsd");
+  mkdirSync(gsdDir, { recursive: true });
+
+  openDatabase(join(gsdDir, "gsd.db"));
+  insertMilestone({ id: "M001", title: "Foundation", status: "active", planning: { vision: "Ship the foundation." } });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Slice", status: "pending", risk: "low", depends: [], sequence: 1 });
+  insertArtifact({
+    path: "phases/01-foundation/01-ROADMAP.md",
+    artifact_type: "ROADMAP",
+    milestone_id: "M001",
+    slice_id: null,
+    task_id: null,
+    full_content: "# stale row only\n",
+  });
+  // CONTEXT is not re-rendered by flushWorkflowProjections, so its missing-file
+  // diagnostic must survive the post-re-render cleanup (guards against the
+  // clearing logic over-broadening to artifacts the same run did not recreate).
+  insertArtifact({
+    path: "phases/01-foundation/01-CONTEXT.md",
+    artifact_type: "CONTEXT",
+    milestone_id: "M001",
+    slice_id: null,
+    task_id: null,
+    full_content: "# stale context row only\n",
+  });
+  appendEvent(base, {
+    cmd: "plan-milestone",
+    params: { milestoneId: "M001" },
+    ts: "2999-01-01T00:00:00.000Z",
+    actor: "agent",
+  });
+
+  const issues: any[] = [];
+  const fixes: string[] = [];
+  await checkEngineHealth(base, issues, fixes);
+
+  assert.ok(fixes.includes("re-rendered missing projections for M001"));
+  assert.equal(
+    issues.some((issue) => issue.code === "artifact_file_missing" && issue.file === "phases/01-foundation/01-ROADMAP.md"),
+    false,
+    "doctor should not report a missing artifact that projection repair recreated in the same run",
+  );
+  const contextIssue = issues.find((issue) => issue.code === "artifact_user_content_missing" && issue.file === "phases/01-foundation/01-CONTEXT.md");
+  assert.ok(contextIssue, "doctor should still report missing user content that projection repair did not recreate");
+  assert.equal(contextIssue.severity, "warning");
+});