gsd-pi 2.51.0 → 2.52.0-dev.655ad8a

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,9 +14,10 @@ import {
   getMilestone,
   getMilestoneSlices,
   getSliceTasks,
-  _getAdapter,
+  updateMilestoneStatus,
 } from "../gsd-db.js";
 import { resolveMilestonePath, clearPathCache } from "../paths.js";
+import { isClosedStatus } from "../status-guards.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { renderAllProjections } from "../workflow-projections.js";
@@ -134,7 +135,7 @@ export async function handleCompleteMilestone(
       guardError = `milestone not found: ${params.milestoneId}`;
       return;
     }
-    if (milestone.status === "complete" || milestone.status === "done") {
+    if (isClosedStatus(milestone.status)) {
       guardError = `milestone ${params.milestoneId} is already complete`;
       return;
     }
@@ -146,7 +147,7 @@ export async function handleCompleteMilestone(
       return;
     }
 
-    const incompleteSlices = slices.filter(s => s.status !== "complete" && s.status !== "done");
+    const incompleteSlices = slices.filter(s => !isClosedStatus(s.status));
     if (incompleteSlices.length > 0) {
       const incompleteIds = incompleteSlices.map(s => `${s.id} (status: ${s.status})`).join(", ");
       guardError = `incomplete slices: ${incompleteIds}`;
@@ -156,7 +157,7 @@ export async function handleCompleteMilestone(
     // Deep check: verify all tasks in all slices are complete
     for (const slice of slices) {
       const tasks = getSliceTasks(params.milestoneId, slice.id);
-      const incompleteTasks = tasks.filter(t => t.status !== "complete" && t.status !== "done");
+      const incompleteTasks = tasks.filter(t => !isClosedStatus(t.status));
       if (incompleteTasks.length > 0) {
         const ids = incompleteTasks.map(t => `${t.id} (status: ${t.status})`).join(", ");
         guardError = `slice ${slice.id} has incomplete tasks: ${ids}`;
@@ -165,13 +166,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 +194,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

@@ -11,6 +11,7 @@ import { join } from "node:path";
 import { mkdirSync } from "node:fs";
 
 import type { CompleteSliceParams } from "../types.js";
+import { isClosedStatus } from "../status-guards.js";
 import {
   transaction,
   insertMilestone,
@@ -19,7 +20,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";
@@ -225,13 +226,13 @@ export async function handleCompleteSlice(
     // Milestone/slice not existing is OK — insertMilestone/insertSlice below will auto-create.
     // Only block if they exist and are closed.
     const milestone = getMilestone(params.milestoneId);
-    if (milestone && (milestone.status === "complete" || milestone.status === "done")) {
+    if (milestone && isClosedStatus(milestone.status)) {
       guardError = `cannot complete slice in a closed milestone: ${params.milestoneId} (status: ${milestone.status})`;
       return;
     }
 
     const slice = getSlice(params.milestoneId, params.sliceId);
-    if (slice && (slice.status === "complete" || slice.status === "done")) {
+    if (slice && isClosedStatus(slice.status)) {
       guardError = `slice ${params.sliceId} is already complete — use gsd_slice_reopen first if you need to redo it`;
       return;
     }
@@ -243,7 +244,7 @@ export async function handleCompleteSlice(
       return;
     }
 
-    const incompleteTasks = tasks.filter(t => t.status !== "complete" && t.status !== "done");
+    const incompleteTasks = tasks.filter(t => !isClosedStatus(t.status));
     if (incompleteTasks.length > 0) {
       const incompleteIds = incompleteTasks.map(t => `${t.id} (status: ${t.status})`).join(", ");
       guardError = `incomplete tasks: ${incompleteIds}`;
@@ -299,31 +300,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

@@ -11,6 +11,7 @@ import { join } from "node:path";
 import { mkdirSync, existsSync } from "node:fs";
 
 import type { CompleteTaskParams } from "../types.js";
+import { isClosedStatus } from "../status-guards.js";
 import {
   transaction,
   insertMilestone,
@@ -20,7 +21,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";
@@ -157,19 +160,19 @@ export async function handleCompleteTask(
     // Milestone/slice not existing is OK — insertMilestone/insertSlice below will auto-create.
     // Only block if they exist and are closed.
     const milestone = getMilestone(params.milestoneId);
-    if (milestone && (milestone.status === "complete" || milestone.status === "done")) {
+    if (milestone && isClosedStatus(milestone.status)) {
       guardError = `cannot complete task in a closed milestone: ${params.milestoneId} (status: ${milestone.status})`;
       return;
     }
 
     const slice = getSlice(params.milestoneId, params.sliceId);
-    if (slice && (slice.status === "complete" || slice.status === "done")) {
+    if (slice && isClosedStatus(slice.status)) {
       guardError = `cannot complete task in a closed slice: ${params.sliceId} (status: ${slice.status})`;
       return;
     }
 
     const existingTask = getTask(params.milestoneId, params.sliceId, params.taskId);
-    if (existingTask && (existingTask.status === "complete" || existingTask.status === "done")) {
+    if (existingTask && isClosedStatus(existingTask.status)) {
       guardError = `task ${params.taskId} is already complete — use gsd_task_reopen first if you need to redo it`;
       return;
     }
@@ -248,32 +251,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

@@ -1,4 +1,6 @@
 import { clearParseCache } from "../files.js";
+import { isClosedStatus } from "../status-guards.js";
+import { isNonEmptyString, validateStringArray } from "../validation.js";
 import {
   transaction,
   getMilestone,
@@ -6,7 +8,6 @@ import {
   insertSlice,
   upsertMilestonePlanning,
   upsertSlicePlanning,
-  _getAdapter,
 } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { renderRoadmapFromDb } from "../markdown-renderer.js";
@@ -55,20 +56,6 @@ export interface PlanMilestoneResult {
   roadmapPath: string;
 }
 
-function isNonEmptyString(value: unknown): value is string {
-  return typeof value === "string" && value.trim().length > 0;
-}
-
-function validateStringArray(value: unknown, field: string): string[] {
-  if (!Array.isArray(value)) {
-    throw new Error(`${field} must be an array`);
-  }
-  if (value.some((item) => !isNonEmptyString(item))) {
-    throw new Error(`${field} must contain only non-empty strings`);
-  }
-  return value;
-}
-
 function validateRiskEntries(value: unknown): Array<{ risk: string; whyItMatters: string }> {
   if (!Array.isArray(value)) {
     throw new Error("keyRisks must be an array");
@@ -189,27 +176,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 && isClosedStatus(existingMilestone.status)) {
+        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 (!isClosedStatus(dep.status)) {
+            guardError = `depends_on milestone ${depId} is not yet complete (status: ${dep.status})`;
+            return;
+          }
+        }
       }
-    }
-  }
 
-  try {
-    transaction(() => {
       insertMilestone({
         id: params.milestoneId,
         title: params.title,
@@ -254,6 +248,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);

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

@@ -1,4 +1,6 @@
 import { clearParseCache } from "../files.js";
+import { isClosedStatus } from "../status-guards.js";
+import { isNonEmptyString, validateStringArray } from "../validation.js";
 import {
   transaction,
   getMilestone,
@@ -7,7 +9,6 @@ import {
   upsertSlicePlanning,
   upsertTaskPlanning,
   insertGateRow,
-  _getAdapter,
 } from "../gsd-db.js";
 import type { GateId } from "../types.js";
 import { invalidateStateCache } from "../state.js";
@@ -51,20 +52,6 @@ export interface PlanSliceResult {
   taskPlanPaths: string[];
 }
 
-function isNonEmptyString(value: unknown): value is string {
-  return typeof value === "string" && value.trim().length > 0;
-}
-
-function validateStringArray(value: unknown, field: string): string[] {
-  if (!Array.isArray(value)) {
-    throw new Error(`${field} must be an array`);
-  }
-  if (value.some((item) => !isNonEmptyString(item))) {
-    throw new Error(`${field} must contain only non-empty strings`);
-  }
-  return value;
-}
-
 function validateTasks(value: unknown): PlanSliceTaskInput[] {
   if (!Array.isArray(value) || value.length === 0) {
     throw new Error("tasks must be a non-empty array");
@@ -146,24 +133,33 @@ export async function handlePlanSlice(
     return { error: `validation failed: ${(err as Error).message}` };
   }
 
-  const parentMilestone = getMilestone(params.milestoneId);
-  if (!parentMilestone) {
-    return { error: `milestone not found: ${params.milestoneId}` };
-  }
-  if (parentMilestone.status === "complete" || parentMilestone.status === "done") {
-    return { error: `cannot plan slice in a closed milestone: ${params.milestoneId} (status: ${parentMilestone.status})` };
-  }
-
-  const parentSlice = getSlice(params.milestoneId, params.sliceId);
-  if (!parentSlice) {
-    return { error: `missing parent slice: ${params.milestoneId}/${params.sliceId}` };
-  }
-  if (parentSlice.status === "complete" || parentSlice.status === "done") {
-    return { error: `cannot re-plan slice ${params.sliceId}: it is already complete — use gsd_slice_reopen first` };
-  }
+  // ── 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;
 
   try {
     transaction(() => {
+      const parentMilestone = getMilestone(params.milestoneId);
+      if (!parentMilestone) {
+        guardError = `milestone not found: ${params.milestoneId}`;
+        return;
+      }
+      if (isClosedStatus(parentMilestone.status)) {
+        guardError = `cannot plan slice in a closed milestone: ${params.milestoneId} (status: ${parentMilestone.status})`;
+        return;
+      }
+
+      const parentSlice = getSlice(params.milestoneId, params.sliceId);
+      if (!parentSlice) {
+        guardError = `missing parent slice: ${params.milestoneId}/${params.sliceId}`;
+        return;
+      }
+      if (isClosedStatus(parentSlice.status)) {
+        guardError = `cannot re-plan slice ${params.sliceId}: it is already complete — use gsd_slice_reopen first`;
+        return;
+      }
+
       upsertSlicePlanning(params.milestoneId, params.sliceId, {
         goal: params.goal,
         successCriteria: params.successCriteria,
@@ -211,6 +207,10 @@ export async function handlePlanSlice(
     return { error: `db write failed: ${(err as Error).message}` };
   }
 
+  if (guardError) {
+    return { error: guardError };
+  }
+
   try {
     const renderResult = await renderPlanFromDb(basePath, params.milestoneId, params.sliceId);
     invalidateStateCache();