gsd-pi 2.50.0 → 2.51.0-dev.7d435fe

package/src/resources/extensions/gsd/tests/vacuous-truth-slices.test.ts

@@ -0,0 +1,115 @@
+/**
+ * Regression test for #2667: deriveStateFromDb must NOT treat an empty
+ * slice array as "all slices done" due to JavaScript's vacuous-truth
+ * behavior of Array.prototype.every on an empty array.
+ *
+ * [].every(predicate) === true in JavaScript. Without a length > 0 guard,
+ * this causes a premature phase transition to validating-milestone when
+ * the DB returns 0 slices (e.g. after a worktree DB wipe).
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { deriveStateFromDb, invalidateStateCache } from "../state.ts";
+import {
+  openDatabase,
+  closeDatabase,
+  insertMilestone,
+  insertSlice,
+} from "../gsd-db.ts";
+
+test("deriveStateFromDb does NOT skip to validating when slice array is empty (#2667)", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-vacuous-truth-"));
+  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+
+  try {
+    // Set up a milestone with a roadmap that references slices,
+    // but the DB has NO slice rows (simulating a worktree DB wipe)
+    writeFileSync(
+      join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md"),
+      [
+        "# M001: Test Milestone",
+        "",
+        "## Slices",
+        "",
+        "### S01 — First Slice",
+        "Do something.",
+        "",
+        "### S02 — Second Slice",
+        "Do another thing.",
+      ].join("\n"),
+    );
+
+    openDatabase(":memory:");
+    // Milestone exists but NO slices inserted — simulates DB wipe
+    insertMilestone({ id: "M001", title: "Test Milestone", status: "active" });
+
+    invalidateStateCache();
+    const state = await deriveStateFromDb(base);
+
+    // The phase must NOT be "validating-milestone" or "completing-milestone"
+    // because no slices have been executed — the empty array should not
+    // trigger the "all slices done" code path.
+    assert.notEqual(
+      state.phase,
+      "validating-milestone",
+      "empty slice array must not trigger validating-milestone (vacuous truth)",
+    );
+    assert.notEqual(
+      state.phase,
+      "completing-milestone",
+      "empty slice array must not trigger completing-milestone (vacuous truth)",
+    );
+
+    closeDatabase();
+  } finally {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("deriveStateFromDb correctly reaches validating when all slices are done (#2667 guard)", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-vacuous-truth-"));
+  mkdirSync(join(base, ".gsd", "milestones", "M001", "slices", "S01"), { recursive: true });
+
+  try {
+    writeFileSync(
+      join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md"),
+      [
+        "# M001: Test Milestone",
+        "",
+        "## Slices",
+        "",
+        "### S01 — First Slice",
+        "Do something.",
+      ].join("\n"),
+    );
+
+    // Write a slice summary so the filesystem recognizes it as complete
+    writeFileSync(
+      join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-SUMMARY.md"),
+      "# S01 Summary\n\nDone.",
+    );
+
+    openDatabase(":memory:");
+    insertMilestone({ id: "M001", title: "Test Milestone", status: "active" });
+    insertSlice({ id: "S01", milestoneId: "M001", title: "First Slice", status: "complete", risk: "low", depends: [] });
+
+    invalidateStateCache();
+    const state = await deriveStateFromDb(base);
+
+    // With one slice that IS complete, phase should advance
+    assert.ok(
+      state.phase === "validating-milestone" || state.phase === "completing-milestone",
+      `expected validating or completing phase, got "${state.phase}"`,
+    );
+
+    closeDatabase();
+  } finally {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/validate-milestone-write-order.test.ts

@@ -0,0 +1,90 @@
+import { describe, it, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, existsSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+import { handleValidateMilestone } from "../tools/validate-milestone.js";
+import { openDatabase, closeDatabase, _getAdapter, insertMilestone } from "../gsd-db.js";
+import { clearPathCache } from "../paths.js";
+import { clearParseCache } from "../files.js";
+
+function makeTmpBase(): string {
+  const base = join(tmpdir(), `gsd-val-handler-${randomUUID()}`);
+  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+  return base;
+}
+
+const VALID_PARAMS = {
+  milestoneId: "M001",
+  verdict: "pass" as const,
+  remediationRound: 0,
+  successCriteriaChecklist: "- [x] All pass",
+  sliceDeliveryAudit: "| S01 | delivered |",
+  crossSliceIntegration: "No issues",
+  requirementCoverage: "All covered",
+  verdictRationale: "Everything checks out",
+};
+
+describe("handleValidateMilestone write ordering (#2725)", () => {
+  let base: string;
+
+  afterEach(() => {
+    clearPathCache();
+    clearParseCache();
+    try { closeDatabase(); } catch { /* */ }
+    if (base) {
+      try { rmSync(base, { recursive: true, force: true }); } catch { /* */ }
+    }
+  });
+
+  it("writes DB row and disk file on success", async () => {
+    base = makeTmpBase();
+    const dbPath = join(base, ".gsd", "gsd.db");
+    openDatabase(dbPath);
+    insertMilestone({ id: "M001" });
+
+    const result = await handleValidateMilestone(VALID_PARAMS, base);
+    assert.ok(!("error" in result), `unexpected error: ${"error" in result ? result.error : ""}`);
+
+    // DB row exists
+    const adapter = _getAdapter()!;
+    const row = adapter.prepare(
+      `SELECT status, scope FROM assessments WHERE milestone_id = 'M001' AND scope = 'milestone-validation'`,
+    ).get() as { status: string; scope: string } | undefined;
+    assert.ok(row, "assessment row should exist in DB");
+    assert.equal(row!.status, "pass");
+
+    // Disk file exists
+    const filePath = join(base, ".gsd", "milestones", "M001", "M001-VALIDATION.md");
+    assert.ok(existsSync(filePath), "VALIDATION.md should exist on disk");
+  });
+
+  it("rolls back DB row when disk write fails", async () => {
+    base = makeTmpBase();
+    const dbPath = join(base, ".gsd", "gsd.db");
+    openDatabase(dbPath);
+    insertMilestone({ id: "M001" });
+
+    // Force disk write failure by replacing the milestone directory with a
+    // regular file. saveFile() will fail because it cannot write inside a
+    // non-directory. This works cross-platform (chmod is ignored on Windows).
+    const milestoneDir = join(base, ".gsd", "milestones", "M001");
+    rmSync(milestoneDir, { recursive: true, force: true });
+    writeFileSync(milestoneDir, "not-a-directory");
+
+    const result = await handleValidateMilestone(VALID_PARAMS, base);
+
+    // Should return error
+    assert.ok("error" in result, "should return error when disk write fails");
+    assert.ok(result.error.includes("disk render failed"));
+
+    // DB row should have been rolled back (deleted)
+    const adapter = _getAdapter()!;
+    const row = adapter.prepare(
+      `SELECT * FROM assessments WHERE milestone_id = 'M001' AND scope = 'milestone-validation'`,
+    ).get();
+    assert.equal(row, undefined, "assessment row should be deleted after disk-write rollback");
+  });
+});

package/src/resources/extensions/gsd/tests/workflow-logger.test.ts

@@ -1,8 +1,11 @@
 // GSD Extension — Workflow Logger Tests
 // Tests for the centralized warning/error accumulator.
 
-import { describe, test, beforeEach } from "node:test";
+import { describe, test, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { makeTempDir, cleanup } from "./test-utils.ts";
 import {
   logWarning,
   logError,
@@ -14,6 +17,7 @@ import {
   hasAnyIssues,
   summarizeLogs,
   formatForNotification,
+  setLogBasePath,
   _resetLogs,
 } from "../workflow-logger.ts";
 
@@ -222,6 +226,44 @@ describe("workflow-logger", () => {
     });
   });
 
+  describe("audit log persistence", () => {
+    let dir: string;
+
+    beforeEach(() => {
+      dir = makeTempDir("wl-audit-");
+    });
+
+    afterEach(() => {
+      setLogBasePath("");
+      cleanup(dir);
+    });
+
+    test("writes entry to .gsd/audit-log.jsonl after setLogBasePath", () => {
+      setLogBasePath(dir);
+      logWarning("engine", "audit test entry");
+
+      const auditPath = join(dir, ".gsd", "audit-log.jsonl");
+      assert.ok(existsSync(auditPath), "audit-log.jsonl should exist");
+      const content = readFileSync(auditPath, "utf-8");
+      const entry = JSON.parse(content.trim());
+      assert.equal(entry.severity, "warn");
+      assert.equal(entry.component, "engine");
+      assert.equal(entry.message, "audit test entry");
+    });
+
+    test("_resetLogs does not clear the audit base path", () => {
+      setLogBasePath(dir);
+      _resetLogs();
+      logWarning("engine", "post-reset entry");
+
+      const auditPath = join(dir, ".gsd", "audit-log.jsonl");
+      assert.ok(existsSync(auditPath), "audit-log.jsonl should exist after _resetLogs");
+      const content = readFileSync(auditPath, "utf-8");
+      const entry = JSON.parse(content.trim());
+      assert.equal(entry.message, "post-reset entry");
+    });
+  });
+
   describe("buffer limit", () => {
     test("caps at MAX_BUFFER entries, dropping oldest", () => {
       const OVER = 110;
@@ -237,6 +279,44 @@ describe("workflow-logger", () => {
     });
   });
 
+  describe("audit log persistence", () => {
+    let dir: string;
+
+    beforeEach(() => {
+      dir = makeTempDir("wl-audit-");
+    });
+
+    afterEach(() => {
+      setLogBasePath("");
+      cleanup(dir);
+    });
+
+    test("writes entry to .gsd/audit-log.jsonl after setLogBasePath", () => {
+      setLogBasePath(dir);
+      logWarning("engine", "audit test entry");
+
+      const auditPath = join(dir, ".gsd", "audit-log.jsonl");
+      assert.ok(existsSync(auditPath), "audit-log.jsonl should exist");
+      const content = readFileSync(auditPath, "utf-8");
+      const entry = JSON.parse(content.trim());
+      assert.equal(entry.severity, "warn");
+      assert.equal(entry.component, "engine");
+      assert.equal(entry.message, "audit test entry");
+    });
+
+    test("_resetLogs does not clear the audit base path", () => {
+      setLogBasePath(dir);
+      _resetLogs();
+      logWarning("engine", "post-reset entry");
+
+      const auditPath = join(dir, ".gsd", "audit-log.jsonl");
+      assert.ok(existsSync(auditPath), "audit-log.jsonl should exist after _resetLogs");
+      const content = readFileSync(auditPath, "utf-8");
+      const entry = JSON.parse(content.trim());
+      assert.equal(entry.message, "post-reset entry");
+    });
+  });
+
   describe("stderr output", () => {
     test("writes WARN prefix to stderr for warnings", (t) => {
       const written: string[] = [];

package/src/resources/extensions/gsd/tests/worktree-preferences-sync.test.ts

@@ -0,0 +1,130 @@
+/**
+ * worktree-preferences-sync.test.ts — Regression test for #2684.
+ *
+ * Verifies that preferences.md is seeded into auto-mode worktrees:
+ *
+ *   1. copyPlanningArtifacts() copies preferences.md on initial worktree creation
+ *   2. syncGsdStateToWorktree() forward-syncs preferences.md (additive only)
+ *   3. syncWorktreeStateBack() does NOT overwrite project root preferences.md
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  syncGsdStateToWorktree,
+  syncWorktreeStateBack,
+} from "../auto-worktree.ts";
+
+// ─── Helpers ─────────────────────────────────────────────────────────
+
+function makeTempDir(prefix: string): string {
+  return mkdtempSync(join(tmpdir(), `gsd-prefs-test-${prefix}-`));
+}
+
+function cleanup(...dirs: string[]): void {
+  for (const dir of dirs) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function writeFile(dir: string, relativePath: string, content: string): void {
+  const fullPath = join(dir, relativePath);
+  mkdirSync(join(fullPath, ".."), { recursive: true });
+  writeFileSync(fullPath, content, "utf-8");
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────
+
+const PREFS_CONTENT = [
+  "# Preferences",
+  "",
+  "post_unit_hooks:",
+  "  - npm run lint",
+  "",
+  "skill_rules:",
+  '  - use: "frontend-design"',
+].join("\n");
+
+test("#2684: syncGsdStateToWorktree forward-syncs preferences.md when missing from worktree", (t) => {
+  const mainBase = makeTempDir("main");
+  const wtBase = makeTempDir("wt");
+  t.after(() => cleanup(mainBase, wtBase));
+
+  // Project root has preferences.md
+  writeFile(mainBase, ".gsd/preferences.md", PREFS_CONTENT);
+
+  // Worktree has .gsd/ but no preferences.md
+  mkdirSync(join(wtBase, ".gsd"), { recursive: true });
+
+  const result = syncGsdStateToWorktree(mainBase, wtBase);
+
+  assert.ok(
+    existsSync(join(wtBase, ".gsd", "preferences.md")),
+    "preferences.md should be copied to worktree",
+  );
+  assert.equal(
+    readFileSync(join(wtBase, ".gsd", "preferences.md"), "utf-8"),
+    PREFS_CONTENT,
+    "preferences.md content should match source",
+  );
+  assert.ok(
+    result.synced.includes("preferences.md"),
+    "preferences.md should appear in synced list",
+  );
+});
+
+test("#2684: syncGsdStateToWorktree does NOT overwrite existing worktree preferences.md", (t) => {
+  const mainBase = makeTempDir("main");
+  const wtBase = makeTempDir("wt");
+  t.after(() => cleanup(mainBase, wtBase));
+
+  const rootPrefs = "# Root preferences\nold: true";
+  const wtPrefs = "# Worktree preferences\nmodified: true";
+
+  writeFile(mainBase, ".gsd/preferences.md", rootPrefs);
+  writeFile(wtBase, ".gsd/preferences.md", wtPrefs);
+
+  syncGsdStateToWorktree(mainBase, wtBase);
+
+  assert.equal(
+    readFileSync(join(wtBase, ".gsd", "preferences.md"), "utf-8"),
+    wtPrefs,
+    "existing worktree preferences.md must not be overwritten",
+  );
+});
+
+test("#2684: syncWorktreeStateBack does NOT overwrite project root preferences.md", (t) => {
+  const mainBase = makeTempDir("main");
+  const wtBase = makeTempDir("wt");
+  const mid = "M001";
+  t.after(() => cleanup(mainBase, wtBase));
+
+  const rootPrefs = "# Root preferences\nauthoritative: true";
+  const wtPrefs = "# Worktree preferences\nstale-copy: true";
+
+  writeFile(mainBase, ".gsd/preferences.md", rootPrefs);
+  writeFile(wtBase, ".gsd/preferences.md", wtPrefs);
+
+  // Worktree needs at least a milestone dir for the function to proceed
+  mkdirSync(join(wtBase, ".gsd", "milestones", mid), { recursive: true });
+  mkdirSync(join(mainBase, ".gsd", "milestones"), { recursive: true });
+
+  syncWorktreeStateBack(mainBase, wtBase, mid);
+
+  assert.equal(
+    readFileSync(join(mainBase, ".gsd", "preferences.md"), "utf-8"),
+    rootPrefs,
+    "project root preferences.md must NOT be overwritten by worktree copy",
+  );
+});

package/src/resources/extensions/gsd/tools/complete-milestone.ts

@@ -14,7 +14,7 @@ import {
   getMilestone,
   getMilestoneSlices,
   getSliceTasks,
-  _getAdapter,
+  updateMilestoneStatus,
 } from "../gsd-db.js";
 import { resolveMilestonePath, clearPathCache } from "../paths.js";
 import { saveFile, clearParseCache } from "../files.js";
@@ -165,13 +165,7 @@ export async function handleCompleteMilestone(
     }
 
     // All guards passed — perform write
-    const adapter = _getAdapter()!;
-    adapter.prepare(
-      `UPDATE milestones SET status = 'complete', completed_at = :completed_at WHERE id = :mid`,
-    ).run({
-      ":completed_at": completedAt,
-      ":mid": params.milestoneId,
-    });
+    updateMilestoneStatus(params.milestoneId, 'complete', completedAt);
   });
 
   if (guardError) {
@@ -199,12 +193,7 @@ export async function handleCompleteMilestone(
     process.stderr.write(
       `gsd-db: complete_milestone — disk render failed, rolling back DB status: ${(renderErr as Error).message}\n`,
     );
-    const rollbackAdapter = _getAdapter();
-    if (rollbackAdapter) {
-      rollbackAdapter.prepare(
-        `UPDATE milestones SET status = 'active', completed_at = NULL WHERE id = :mid`,
-      ).run({ ":mid": params.milestoneId });
-    }
+    updateMilestoneStatus(params.milestoneId, 'active', null);
     invalidateStateCache();
     return { error: `disk render failed: ${(renderErr as Error).message}` };
   }

package/src/resources/extensions/gsd/tools/complete-slice.ts

@@ -19,7 +19,7 @@ import {
   getSliceTasks,
   getMilestone,
   updateSliceStatus,
-  _getAdapter,
+  setSliceSummaryMd,
 } from "../gsd-db.js";
 import { resolveSliceFile, resolveSlicePath, clearPathCache } from "../paths.js";
 import { checkOwnership, sliceUnitKey } from "../unit-ownership.js";
@@ -299,31 +299,13 @@ export async function handleCompleteSlice(
     process.stderr.write(
       `gsd-db: complete_slice — disk render failed, rolling back DB status: ${(renderErr as Error).message}\n`,
     );
-    const rollbackAdapter = _getAdapter();
-    if (rollbackAdapter) {
-      rollbackAdapter.prepare(
-        `UPDATE slices SET status = 'pending' WHERE milestone_id = :mid AND id = :sid`,
-      ).run({
-        ":mid": params.milestoneId,
-        ":sid": params.sliceId,
-      });
-    }
+    updateSliceStatus(params.milestoneId, params.sliceId, 'pending');
     invalidateStateCache();
     return { error: `disk render failed: ${(renderErr as Error).message}` };
   }
 
   // Store rendered markdown in DB for D004 recovery
-  const adapter = _getAdapter();
-  if (adapter) {
-    adapter.prepare(
-      `UPDATE slices SET full_summary_md = :summary_md, full_uat_md = :uat_md WHERE milestone_id = :mid AND id = :sid`,
-    ).run({
-      ":summary_md": summaryMd,
-      ":uat_md": uatMd,
-      ":mid": params.milestoneId,
-      ":sid": params.sliceId,
-    });
-  }
+  setSliceSummaryMd(params.milestoneId, params.sliceId, summaryMd, uatMd);
 
   // Invalidate all caches
   invalidateStateCache();

package/src/resources/extensions/gsd/tools/complete-task.ts

@@ -20,7 +20,9 @@ import {
   getMilestone,
   getSlice,
   getTask,
-  _getAdapter,
+  updateTaskStatus,
+  setTaskSummaryMd,
+  deleteVerificationEvidence,
 } from "../gsd-db.js";
 import { resolveSliceFile, resolveTasksDir, clearPathCache } from "../paths.js";
 import { checkOwnership, taskUnitKey } from "../unit-ownership.js";
@@ -248,32 +250,17 @@ export async function handleCompleteTask(
     process.stderr.write(
       `gsd-db: complete_task — disk render failed, rolling back DB status: ${(renderErr as Error).message}\n`,
     );
-    const rollbackAdapter = _getAdapter();
-    if (rollbackAdapter) {
-      rollbackAdapter.prepare(
-        `UPDATE tasks SET status = 'pending' WHERE milestone_id = :mid AND slice_id = :sid AND id = :tid`,
-      ).run({
-        ":mid": params.milestoneId,
-        ":sid": params.sliceId,
-        ":tid": params.taskId,
-      });
-    }
+    // Delete orphaned verification_evidence rows first (FK constraint
+    // references tasks, so evidence must go before status change).
+    // Without this, retries accumulate duplicate evidence rows (#2724).
+    deleteVerificationEvidence(params.milestoneId, params.sliceId, params.taskId);
+    updateTaskStatus(params.milestoneId, params.sliceId, params.taskId, 'pending');
     invalidateStateCache();
     return { error: `disk render failed: ${(renderErr as Error).message}` };
   }
 
   // Store rendered markdown in DB for D004 recovery
-  const adapter = _getAdapter();
-  if (adapter) {
-    adapter.prepare(
-      `UPDATE tasks SET full_summary_md = :md WHERE milestone_id = :mid AND slice_id = :sid AND id = :tid`,
-    ).run({
-      ":md": summaryMd,
-      ":mid": params.milestoneId,
-      ":sid": params.sliceId,
-      ":tid": params.taskId,
-    });
-  }
+  setTaskSummaryMd(params.milestoneId, params.sliceId, params.taskId, summaryMd);
 
   // Invalidate all caches
   invalidateStateCache();

package/src/resources/extensions/gsd/tools/plan-milestone.ts

@@ -6,7 +6,6 @@ import {
   insertSlice,
   upsertMilestonePlanning,
   upsertSlicePlanning,
-  _getAdapter,
 } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { renderRoadmapFromDb } from "../markdown-renderer.js";
@@ -189,27 +188,34 @@ export async function handlePlanMilestone(
     return { error: `validation failed: ${(err as Error).message}` };
   }
 
-  // ── State machine preconditions ─────────────────────────────────────────
-  const existingMilestone = getMilestone(params.milestoneId);
-  if (existingMilestone && (existingMilestone.status === "complete" || existingMilestone.status === "done")) {
-    return { error: `cannot re-plan milestone ${params.milestoneId}: it is already complete` };
-  }
+  // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
+  // Guards must be inside the transaction so the state they check cannot
+  // change between the read and the write (#2723).
+  let guardError: string | null = null;
 
-  // Validate depends_on: all dependencies must exist and be complete
-  if (params.dependsOn && params.dependsOn.length > 0) {
-    for (const depId of params.dependsOn) {
-      const dep = getMilestone(depId);
-      if (!dep) {
-        return { error: `depends_on references unknown milestone: ${depId}` };
+  try {
+    transaction(() => {
+      const existingMilestone = getMilestone(params.milestoneId);
+      if (existingMilestone && (existingMilestone.status === "complete" || existingMilestone.status === "done")) {
+        guardError = `cannot re-plan milestone ${params.milestoneId}: it is already complete`;
+        return;
       }
-      if (dep.status !== "complete" && dep.status !== "done") {
-        return { error: `depends_on milestone ${depId} is not yet complete (status: ${dep.status})` };
+
+      // Validate depends_on: all dependencies must exist and be complete
+      if (params.dependsOn && params.dependsOn.length > 0) {
+        for (const depId of params.dependsOn) {
+          const dep = getMilestone(depId);
+          if (!dep) {
+            guardError = `depends_on references unknown milestone: ${depId}`;
+            return;
+          }
+          if (dep.status !== "complete" && dep.status !== "done") {
+            guardError = `depends_on milestone ${depId} is not yet complete (status: ${dep.status})`;
+            return;
+          }
+        }
       }
-    }
-  }
 
-  try {
-    transaction(() => {
       insertMilestone({
         id: params.milestoneId,
         title: params.title,
@@ -254,6 +260,10 @@ export async function handlePlanMilestone(
     return { error: `db write failed: ${(err as Error).message}` };
   }
 
+  if (guardError) {
+    return { error: guardError };
+  }
+
   let roadmapPath: string;
   try {
     const renderResult = await renderRoadmapFromDb(basePath, params.milestoneId);