gsd-pi 2.65.0-dev.5c8557b → 2.65.0-dev.6cc5110

package/src/resources/extensions/gsd/tests/worktree.test.ts

@@ -14,9 +14,11 @@ import {
   resolveProjectRoot,
   setActiveMilestoneId,
   SLICE_BRANCH_RE,
+  _resetServiceCache,
 } from "../worktree.ts";
 import { readIntegrationBranch } from "../git-service.ts";
 import { _resetHasChangesCache } from "../native-git-bridge.ts";
+import { _clearGsdRootCache } from "../paths.ts";
 import { describe, test } from 'node:test';
 import assert from 'node:assert/strict';
 
@@ -165,15 +167,30 @@ describe('worktree', async () => {
     run("git checkout -b my-feature", repo);
     captureIntegrationBranch(repo, "M001");
 
-    // Without milestone set, getMainBranch returns "main"
-    setActiveMilestoneId(repo, null);
-    assert.deepStrictEqual(getMainBranch(repo), "main",
-      "getMainBranch returns main without milestone set");
-
-    // With milestone set, getMainBranch returns feature branch
-    setActiveMilestoneId(repo, "M001");
-    assert.deepStrictEqual(getMainBranch(repo), "my-feature",
-      "getMainBranch returns integration branch with milestone set");
+    // Isolate from user's global preferences (which may have git.main_branch set).
+    // Reset caches so getService() creates a fresh instance with empty preferences.
+    const originalHome = process.env.HOME;
+    const fakeHome = mkdtempSync(join(tmpdir(), "gsd-fake-home-"));
+    process.env.HOME = fakeHome;
+    _clearGsdRootCache();
+    _resetServiceCache();
+
+    try {
+      // Without milestone set, getMainBranch returns "main"
+      setActiveMilestoneId(repo, null);
+      assert.deepStrictEqual(getMainBranch(repo), "main",
+        "getMainBranch returns main without milestone set");
+
+      // With milestone set, getMainBranch returns feature branch
+      setActiveMilestoneId(repo, "M001");
+      assert.deepStrictEqual(getMainBranch(repo), "my-feature",
+        "getMainBranch returns integration branch with milestone set");
+    } finally {
+      process.env.HOME = originalHome;
+      _clearGsdRootCache();
+      _resetServiceCache();
+      rmSync(fakeHome, { recursive: true, force: true });
+    }
 
     rmSync(repo, { recursive: true, force: true });
   }

package/src/resources/extensions/gsd/tests/zero-slice-roadmap-guided.test.ts

@@ -0,0 +1,19 @@
+/**
+ * Regression test for #3441: guided flow must treat a roadmap with zero
+ * parseable slices the same as no roadmap — offer "Create roadmap" not "Go auto".
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+test("guided-flow checks roadmap slice count before offering auto (#3441)", () => {
+  const src = readFileSync(
+    join(import.meta.dirname, "..", "guided-flow.ts"),
+    "utf-8",
+  );
+  assert.ok(
+    src.includes("roadmapHasSlices") || src.includes("parseRoadmapSlices"),
+    "Guided flow must parse roadmap for slices before deciding which options to show",
+  );
+});

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

@@ -23,7 +23,7 @@ import { invalidateStateCache } from "../state.js";
 import { renderAllProjections, stripIdPrefix } from "../workflow-projections.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
-import { logWarning } from "../workflow-logger.js";
+import { logWarning, logError } from "../workflow-logger.js";
 
 export interface CompleteMilestoneParams {
   milestoneId: string;
@@ -218,9 +218,19 @@ export async function handleCompleteMilestone(
   clearParseCache();
 
   // ── Post-mutation hook: projections, manifest, event log ───────────────
+  // Separate try/catch per step so a projection failure doesn't prevent
+  // the event log entry (critical for worktree reconciliation).
   try {
     await renderAllProjections(basePath, params.milestoneId);
+  } catch (projErr) {
+    logWarning("tool", `complete-milestone projection warning: ${(projErr as Error).message}`);
+  }
+  try {
     writeManifest(basePath);
+  } catch (mfErr) {
+    logWarning("tool", `complete-milestone manifest warning: ${(mfErr as Error).message}`);
+  }
+  try {
     appendEvent(basePath, {
       cmd: "complete-milestone",
       params: { milestoneId: params.milestoneId },
@@ -229,8 +239,8 @@ export async function handleCompleteMilestone(
       actor_name: params.actorName,
       trigger_reason: params.triggerReason,
     });
-  } catch (hookErr) {
-    logWarning("tool", `complete-milestone post-mutation hook warning: ${(hookErr as Error).message}`);
+  } catch (eventErr) {
+    logError("tool", `complete-milestone event log FAILED — completion invisible to reconciliation`, { error: (eventErr as Error).message });
   }
 
   return {

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

@@ -30,7 +30,7 @@ import { renderRoadmapCheckboxes } from "../markdown-renderer.js";
 import { renderAllProjections } from "../workflow-projections.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
-import { logWarning } from "../workflow-logger.js";
+import { logWarning, logError } from "../workflow-logger.js";
 
 export interface CompleteSliceResult {
   sliceId: string;
@@ -233,8 +233,18 @@ export async function handleCompleteSlice(
     return { error: ownershipErr };
   }
 
+  // ── Verification content gate (#3580) ──────────────────────────────────
+  // Reject completion when the provided verification/UAT clearly indicates
+  // the slice is blocked or failed. Prevents prompt regressions from
+  // silently advancing blocked slices.
+  const BLOCKED_SIGNALS = /\b(status:\s*blocked|verification_result:\s*failed|slice is blocked|cannot complete|verification failed)\b/i;
+  if (BLOCKED_SIGNALS.test(params.verification || "") || BLOCKED_SIGNALS.test(params.uatContent || "")) {
+    return { error: `slice verification indicates blocked/failed state — do not complete a slice that has not passed verification. Address the blockers and re-verify first.` };
+  }
+
   // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
   const completedAt = new Date().toISOString();
+  const originalSliceStatus = getSlice(params.milestoneId, params.sliceId)?.status ?? "pending";
   let guardError: string | null = null;
 
   transaction(() => {
@@ -268,8 +278,8 @@ export async function handleCompleteSlice(
     }
 
     // All guards passed — perform writes
-    insertMilestone({ id: params.milestoneId });
-    insertSlice({ id: params.sliceId, milestoneId: params.milestoneId });
+    insertMilestone({ id: params.milestoneId, title: params.milestoneId });
+    insertSlice({ id: params.sliceId, milestoneId: params.milestoneId, title: params.sliceId });
     updateSliceStatus(params.milestoneId, params.sliceId, "complete", completedAt);
   });
 
@@ -312,7 +322,7 @@ export async function handleCompleteSlice(
   } catch (renderErr) {
     // Disk render failed — roll back DB status so state stays consistent
     logWarning("tool", `complete_slice — disk render failed for ${params.milestoneId}/${params.sliceId}, rolling back DB status`, { error: (renderErr as Error).message });
-    updateSliceStatus(params.milestoneId, params.sliceId, 'pending');
+    updateSliceStatus(params.milestoneId, params.sliceId, originalSliceStatus);
     invalidateStateCache();
     return { error: `disk render failed: ${(renderErr as Error).message}` };
   }
@@ -326,9 +336,19 @@ export async function handleCompleteSlice(
   clearParseCache();
 
   // ── Post-mutation hook: projections, manifest, event log ───────────────
+  // Separate try/catch per step so a projection failure doesn't prevent
+  // the event log entry (critical for worktree reconciliation).
   try {
     await renderAllProjections(basePath, params.milestoneId);
+  } catch (projErr) {
+    logWarning("tool", `complete-slice projection warning for ${params.milestoneId}/${params.sliceId}: ${(projErr as Error).message}`);
+  }
+  try {
     writeManifest(basePath);
+  } catch (mfErr) {
+    logWarning("tool", `complete-slice manifest warning: ${(mfErr as Error).message}`);
+  }
+  try {
     appendEvent(basePath, {
       cmd: "complete-slice",
       params: { milestoneId: params.milestoneId, sliceId: params.sliceId },
@@ -337,8 +357,8 @@ export async function handleCompleteSlice(
       actor_name: params.actorName,
       trigger_reason: params.triggerReason,
     });
-  } catch (hookErr) {
-    logWarning("tool", `complete-slice post-mutation hook failed for ${params.milestoneId}/${params.sliceId}`, { error: (hookErr as Error).message });
+  } catch (eventErr) {
+    logError("tool", `complete-slice event log FAILED — completion invisible to reconciliation`, { error: (eventErr as Error).message });
   }
 
   return {

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

@@ -33,7 +33,7 @@ import { renderPlanCheckboxes } from "../markdown-renderer.js";
 import { renderAllProjections, renderSummaryContent } from "../workflow-projections.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
-import { logWarning } from "../workflow-logger.js";
+import { logWarning, logError } from "../workflow-logger.js";
 
 export interface CompleteTaskResult {
   taskId: string;
@@ -44,6 +44,18 @@ export interface CompleteTaskResult {
 
 import type { TaskRow } from "../gsd-db.js";
 
+/**
+ * Normalize a list parameter that may arrive as a string (newline-delimited
+ * bullet list from the LLM) into a string array (#3361).
+ */
+function normalizeListParam(value: unknown): string[] {
+  if (Array.isArray(value)) return value.map(String);
+  if (typeof value === "string" && value.trim()) {
+    return value.split(/\n/).map(s => s.replace(/^[\s\-*•]+/, "").trim()).filter(Boolean);
+  }
+  return [];
+}
+
 /**
  * Build a TaskRow-shaped object from CompleteTaskParams so the unified
  * renderSummaryContent() can be used at completion time (#2720).
@@ -63,8 +75,8 @@ function paramsToTaskRow(params: CompleteTaskParams, completedAt: string): TaskR
     blocker_discovered: params.blockerDiscovered ?? false,
     deviations: params.deviations ?? "",
     known_issues: params.knownIssues ?? "",
-    key_files: params.keyFiles ?? [],
-    key_decisions: params.keyDecisions ?? [],
+    key_files: normalizeListParam(params.keyFiles),
+    key_decisions: normalizeListParam(params.keyDecisions),
     full_summary_md: "",
     description: "",
     estimate: "",
@@ -140,8 +152,8 @@ export async function handleCompleteTask(
     }
 
     // All guards passed — perform writes
-    insertMilestone({ id: params.milestoneId });
-    insertSlice({ id: params.sliceId, milestoneId: params.milestoneId });
+    insertMilestone({ id: params.milestoneId, title: params.milestoneId });
+    insertSlice({ id: params.sliceId, milestoneId: params.milestoneId, title: params.sliceId });
     insertTask({
       id: params.taskId,
       sliceId: params.sliceId,
@@ -230,9 +242,19 @@ export async function handleCompleteTask(
   clearParseCache();
 
   // ── Post-mutation hook: projections, manifest, event log ───────────────
+  // Separate try/catch per step so a projection failure doesn't prevent
+  // the event log entry (critical for worktree reconciliation).
   try {
     await renderAllProjections(basePath, params.milestoneId);
+  } catch (projErr) {
+    logWarning("tool", `complete-task projection warning: ${(projErr as Error).message}`);
+  }
+  try {
     writeManifest(basePath);
+  } catch (mfErr) {
+    logWarning("tool", `complete-task manifest warning: ${(mfErr as Error).message}`);
+  }
+  try {
     appendEvent(basePath, {
       cmd: "complete-task",
       params: { milestoneId: params.milestoneId, sliceId: params.sliceId, taskId: params.taskId },
@@ -241,8 +263,8 @@ export async function handleCompleteTask(
       actor_name: params.actorName,
       trigger_reason: params.triggerReason,
     });
-  } catch (hookErr) {
-    logWarning("tool", `complete-task post-mutation hook warning: ${(hookErr as Error).message}`);
+  } catch (eventErr) {
+    logError("tool", `complete-task event log FAILED — completion invisible to reconciliation`, { error: (eventErr as Error).message });
   }
 
   return {

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

@@ -48,13 +48,13 @@ export interface PlanMilestoneParams {
   keyRisks?: Array<{ risk: string; whyItMatters: string }>;
   /** @optional — defaults to [] when omitted */
   proofStrategy?: Array<{ riskOrUnknown: string; retireIn: string; whatWillBeProven: string }>;
-  /** @optional — defaults to "Not provided." when omitted */
+  /** @optional — defaults to "" when omitted */
   verificationContract?: string;
-  /** @optional — defaults to "Not provided." when omitted */
+  /** @optional — defaults to "" when omitted */
   verificationIntegration?: string;
-  /** @optional — defaults to "Not provided." when omitted */
+  /** @optional — defaults to "" when omitted */
   verificationOperational?: string;
-  /** @optional — defaults to "Not provided." when omitted */
+  /** @optional — defaults to "" when omitted */
   verificationUat?: string;
   /** @optional — defaults to [] when omitted */
   definitionOfDone?: string[];
@@ -168,10 +168,10 @@ function validateParams(params: PlanMilestoneParams): PlanMilestoneParams {
     successCriteria: params.successCriteria ? validateStringArray(params.successCriteria, "successCriteria") : [],
     keyRisks: params.keyRisks ? validateRiskEntries(params.keyRisks) : [],
     proofStrategy: params.proofStrategy ? validateProofStrategy(params.proofStrategy) : [],
-    verificationContract: params.verificationContract ?? "Not provided.",
-    verificationIntegration: params.verificationIntegration ?? "Not provided.",
-    verificationOperational: params.verificationOperational ?? "Not provided.",
-    verificationUat: params.verificationUat ?? "Not provided.",
+    verificationContract: params.verificationContract ?? "",
+    verificationIntegration: params.verificationIntegration ?? "",
+    verificationOperational: params.verificationOperational ?? "",
+    verificationUat: params.verificationUat ?? "",
     definitionOfDone: params.definitionOfDone ? validateStringArray(params.definitionOfDone, "definitionOfDone") : [],
     requirementCoverage: params.requirementCoverage ?? "Not provided.",
     boundaryMapMarkdown: params.boundaryMapMarkdown ?? "Not provided.",
@@ -256,7 +256,8 @@ export async function handlePlanMilestone(
         boundaryMapMarkdown: params.boundaryMapMarkdown,
       });
 
-      for (const slice of params.slices) {
+      for (let i = 0; i < params.slices.length; i++) {
+        const slice = params.slices[i]!;
         // Preserve completed/done status on re-plan (#2558).
         // Without this, a re-plan after milestone transition would reset
         // already-completed slices back to "pending".
@@ -272,6 +273,7 @@ export async function handlePlanMilestone(
           risk: slice.risk,
           depends: slice.depends,
           demo: slice.demo,
+          sequence: i + 1, // Preserve agent-ordered sequence (#3356)
         });
         upsertSlicePlanning(params.milestoneId, slice.sliceId, {
           goal: slice.goal,

package/src/resources/extensions/gsd/tools/reassess-roadmap.ts

@@ -186,8 +186,10 @@ export async function handleReassessRoadmap(
         });
       }
 
-      // Insert new slices
-      for (const added of params.sliceChanges.added) {
+      // Insert new slices — assign sequence after existing slices (#3356)
+      const existingCount = getMilestoneSlices(params.milestoneId).length;
+      for (let i = 0; i < params.sliceChanges.added.length; i++) {
+        const added = params.sliceChanges.added[i]!;
         insertSlice({
           id: added.sliceId,
           milestoneId: params.milestoneId,
@@ -196,6 +198,7 @@ export async function handleReassessRoadmap(
           risk: added.risk,
           depends: added.depends,
           demo: added.demo ?? "",
+          sequence: existingCount + i + 1,
         });
       }
 

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

@@ -0,0 +1,152 @@
+// GSD — reopen-milestone tool handler
+
+/**
+ * reopen-milestone handler — the core operation behind gsd_milestone_reopen.
+ *
+ * Resets a closed milestone back to "active", all of its slices to
+ * "in_progress", and all tasks to "pending". Cleans up stale filesystem
+ * artifacts so the DB-filesystem reconciler does not auto-correct
+ * entities back to "complete".
+ */
+
+import {
+  getMilestone,
+  getMilestoneSlices,
+  getSliceTasks,
+  updateMilestoneStatus,
+  updateSliceStatus,
+  updateTaskStatus,
+  transaction,
+} from "../gsd-db.js";
+import { invalidateStateCache } from "../state.js";
+import { isClosedStatus } from "../status-guards.js";
+import { renderAllProjections } from "../workflow-projections.js";
+import { writeManifest } from "../workflow-manifest.js";
+import { appendEvent } from "../workflow-events.js";
+import { logWarning } from "../workflow-logger.js";
+import { debugLog } from "../debug-logger.js";
+import { existsSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { resolveMilestonePath, resolveSlicePath, resolveTasksDir, clearPathCache } from "../paths.js";
+
+export interface ReopenMilestoneParams {
+  milestoneId: string;
+  reason?: string;
+  /** Optional caller-provided identity for audit trail */
+  actorName?: string;
+  /** Optional caller-provided reason this action was triggered */
+  triggerReason?: string;
+}
+
+export interface ReopenMilestoneResult {
+  milestoneId: string;
+  slicesReset: number;
+  tasksReset: number;
+}
+
+export async function handleReopenMilestone(
+  params: ReopenMilestoneParams,
+  basePath: string,
+): Promise<ReopenMilestoneResult | { error: string }> {
+  // ── Validate required fields ────────────────────────────────────────────
+  if (!params.milestoneId || typeof params.milestoneId !== "string" || params.milestoneId.trim() === "") {
+    return { error: "milestoneId is required and must be a non-empty string" };
+  }
+
+  // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
+  let guardError: string | null = null;
+  let slicesResetCount = 0;
+  let tasksResetCount = 0;
+
+  transaction(() => {
+    const milestone = getMilestone(params.milestoneId);
+    if (!milestone) {
+      guardError = `milestone not found: ${params.milestoneId}`;
+      return;
+    }
+    if (!isClosedStatus(milestone.status)) {
+      guardError = `milestone ${params.milestoneId} is not closed (status: ${milestone.status}) — nothing to reopen`;
+      return;
+    }
+
+    updateMilestoneStatus(params.milestoneId, "active", null);
+
+    const slices = getMilestoneSlices(params.milestoneId);
+    slicesResetCount = slices.length;
+
+    for (const slice of slices) {
+      updateSliceStatus(params.milestoneId, slice.id, "in_progress");
+      const tasks = getSliceTasks(params.milestoneId, slice.id);
+      tasksResetCount += tasks.length;
+      for (const task of tasks) {
+        updateTaskStatus(params.milestoneId, slice.id, task.id, "pending");
+      }
+    }
+  });
+
+  if (guardError) {
+    return { error: guardError };
+  }
+
+  // ── Invalidate caches ────────────────────────────────────────────────────
+  invalidateStateCache();
+
+  // ── Clean up stale filesystem artifacts (M12 fix) ────────────────────────
+  // Without this, the DB-filesystem reconciler sees SUMMARY.md files and
+  // auto-corrects entities back to "complete", making reopen a no-op (#3161).
+  try {
+    const milestoneDir = resolveMilestonePath(basePath, params.milestoneId);
+    if (milestoneDir) {
+      const milestoneSummary = join(milestoneDir, `${params.milestoneId}-SUMMARY.md`);
+      if (existsSync(milestoneSummary)) unlinkSync(milestoneSummary);
+    }
+
+    const slices = getMilestoneSlices(params.milestoneId);
+    for (const slice of slices) {
+      const sliceDir = resolveSlicePath(basePath, params.milestoneId, slice.id);
+      if (sliceDir) {
+        const sliceSummary = join(sliceDir, `${slice.id}-SUMMARY.md`);
+        if (existsSync(sliceSummary)) unlinkSync(sliceSummary);
+        const sliceUat = join(sliceDir, `${slice.id}-UAT.md`);
+        if (existsSync(sliceUat)) unlinkSync(sliceUat);
+      }
+
+      const tasksDir = resolveTasksDir(basePath, params.milestoneId, slice.id);
+      if (tasksDir) {
+        const tasks = getSliceTasks(params.milestoneId, slice.id);
+        for (const task of tasks) {
+          const taskSummary = join(tasksDir, `${task.id}-SUMMARY.md`);
+          if (existsSync(taskSummary)) unlinkSync(taskSummary);
+        }
+      }
+    }
+  } catch (err) { debugLog("reopen-milestone-cleanup-failed", { milestoneId: params.milestoneId, error: String(err) }); }
+  clearPathCache();
+
+  // ── Post-mutation hook ───────────────────────────────────────────────────
+  try {
+    await renderAllProjections(basePath, params.milestoneId);
+    writeManifest(basePath);
+    appendEvent(basePath, {
+      cmd: "reopen-milestone",
+      params: {
+        milestoneId: params.milestoneId,
+        reason: params.reason ?? null,
+        slicesReset: slicesResetCount,
+        tasksReset: tasksResetCount,
+      },
+      ts: new Date().toISOString(),
+      actor: "agent",
+      actor_name: params.actorName,
+      trigger_reason: params.triggerReason,
+    });
+  } catch (hookErr) {
+    logWarning("tool", `reopen-milestone post-mutation hook warning: ${(hookErr as Error).message}`);
+  }
+
+  return {
+    milestoneId: params.milestoneId,
+    slicesReset: slicesResetCount,
+    tasksReset: tasksResetCount,
+  };
+}

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

@@ -25,6 +25,9 @@ import { renderAllProjections } from "../workflow-projections.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
+import { existsSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { resolveTasksDir, resolveSlicePath, clearPathCache } from "../paths.js";
 
 export interface ReopenSliceParams {
   milestoneId: string;
@@ -96,6 +99,30 @@ export async function handleReopenSlice(
   // ── Invalidate caches ────────────────────────────────────────────────────
   invalidateStateCache();
 
+  // ── Clean up stale filesystem artifacts (M12 fix) ────────────────────────
+  // Without this, the DB-filesystem reconciler sees SUMMARY.md files and
+  // auto-corrects tasks back to "complete", making reopen a no-op (#3161).
+  try {
+    const tasksDir = resolveTasksDir(basePath, params.milestoneId, params.sliceId);
+    if (tasksDir) {
+      const tasks = getSliceTasks(params.milestoneId, params.sliceId);
+      for (const task of tasks) {
+        const summaryPath = join(tasksDir, `${task.id}-SUMMARY.md`);
+        if (existsSync(summaryPath)) unlinkSync(summaryPath);
+      }
+    }
+    const sliceDir = resolveSlicePath(basePath, params.milestoneId, params.sliceId);
+    if (sliceDir) {
+      const sliceSummary = join(sliceDir, `${params.sliceId}-SUMMARY.md`);
+      if (existsSync(sliceSummary)) unlinkSync(sliceSummary);
+      const sliceUat = join(sliceDir, `${params.sliceId}-UAT.md`);
+      if (existsSync(sliceUat)) unlinkSync(sliceUat);
+    }
+  } catch (cleanupErr) {
+    logWarning("tool", `reopen-slice artifact cleanup warning: ${(cleanupErr as Error).message}`);
+  }
+  clearPathCache();
+
   // ── Post-mutation hook ───────────────────────────────────────────────────
   try {
     await renderAllProjections(basePath, params.milestoneId);

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

@@ -23,6 +23,9 @@ import { renderAllProjections } from "../workflow-projections.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
+import { existsSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { resolveTasksDir, clearPathCache } from "../paths.js";
 
 export interface ReopenTaskParams {
   milestoneId: string;
@@ -100,6 +103,20 @@ export async function handleReopenTask(
   // ── Invalidate caches ────────────────────────────────────────────────────
   invalidateStateCache();
 
+  // ── Clean up stale filesystem artifacts (M12 fix) ────────────────────────
+  // Without this, the DB-filesystem reconciler sees the SUMMARY.md and
+  // auto-corrects the task back to "complete", making reopen a no-op (#3161).
+  try {
+    const tasksDir = resolveTasksDir(basePath, params.milestoneId, params.sliceId);
+    if (tasksDir) {
+      const summaryPath = join(tasksDir, `${params.taskId}-SUMMARY.md`);
+      if (existsSync(summaryPath)) unlinkSync(summaryPath);
+    }
+  } catch (cleanupErr) {
+    logWarning("tool", `reopen-task artifact cleanup warning: ${(cleanupErr as Error).message}`);
+  }
+  clearPathCache();
+
   // ── Post-mutation hook ───────────────────────────────────────────────────
   try {
     await renderAllProjections(basePath, params.milestoneId);