gsd-pi 2.65.0-dev.5c8557b → 2.65.0-dev.d0517ff

package/dist/resources/extensions/gsd/templates/context-enhanced.md

@@ -0,0 +1,138 @@
+# {{milestoneId}}: {{milestoneTitle}}
+
+**Gathered:** {{date}}
+**Status:** Ready for planning
+
+## Project Description
+
+{{description}}
+
+## Why This Milestone
+
+{{whatProblemThisSolves_AND_whyNow}}
+
+## Codebase Brief
+
+### Technology Stack
+
+{{techStack}}
+
+### Key Modules
+
+{{keyModules}}
+
+### Patterns in Use
+
+{{patternsInUse}}
+
+## User-Visible Outcome
+
+### When this milestone is complete, the user can:
+
+- {{literalUserActionInRealEnvironment}}
+- {{literalUserActionInRealEnvironment}}
+
+### Entry point / environment
+
+- Entry point: {{CLI command / URL / bot / extension / service / workflow}}
+- Environment: {{local dev / browser / mobile / launchd / CI / production-like}}
+- Live dependencies involved: {{telegram / database / webhook / rpc subprocess / none}}
+
+## Completion Class
+
+- Contract complete means: {{what can be proven by tests / fixtures / artifacts}}
+- Integration complete means: {{what must work across real subsystems}}
+- Operational complete means: {{what must work under real lifecycle conditions, or none}}
+
+## Architectural Decisions
+
+### {{decisionTitle}}
+
+**Decision:** {{decisionStatement}}
+
+**Rationale:** {{rationale}}
+
+**Evidence:** {{evidence}}
+
+**Alternatives Considered:**
+- {{alternative1}} — {{whyNotChosen1}}
+- {{alternative2}} — {{whyNotChosen2}}
+
+---
+
+> Add additional decisions as separate `### Decision Title` blocks following the same structure above.
+
+## Interface Contracts
+
+{{interfaceContracts}}
+
+> Document API boundaries, function signatures, data shapes, or protocol agreements that must be honored. Leave blank or remove if not applicable to this milestone.
+
+## Error Handling Strategy
+
+{{errorHandlingStrategy}}
+
+> Describe the approach for handling failures, edge cases, and error propagation. Include retry policies, fallback behaviors, and user-facing error messages where relevant.
+
+## Final Integrated Acceptance
+
+To call this milestone complete, we must prove:
+
+- {{one real end-to-end scenario}}
+- {{one real end-to-end scenario}}
+- {{what cannot be simulated if this milestone is to be considered truly done}}
+
+## Testing Requirements
+
+{{testingRequirements}}
+
+> Specify test types (unit, integration, e2e), coverage expectations, and any specific test scenarios that must pass.
+
+## Acceptance Criteria
+
+{{acceptanceCriteria}}
+
+> Per-slice acceptance criteria gathered during discussion. Each slice should have clear, testable criteria.
+
+## Risks and Unknowns
+
+- {{riskOrUnknown}} — {{whyItMatters}}
+
+## Existing Codebase / Prior Art
+
+- `{{fileOrModule}}` — {{howItRelates}}
+- `{{fileOrModule}}` — {{howItRelates}}
+
+> See `.gsd/DECISIONS.md` for all architectural and pattern decisions — it is an append-only register; read it during planning, append to it during execution.
+
+## Relevant Requirements
+
+- {{requirementId}} — {{howThisMilestoneAdvancesIt}}
+
+## Scope
+
+### In Scope
+
+- {{inScopeItem}}
+
+### Out of Scope / Non-Goals
+
+- {{outOfScopeItem}}
+
+## Technical Constraints
+
+- {{constraint}}
+
+## Integration Points
+
+- {{systemOrService}} — {{howThisMilestoneInteractsWithIt}}
+
+## Ecosystem Notes
+
+{{ecosystemNotes}}
+
+> Research findings, best practices, known issues, and relevant external documentation discovered during preparation.
+
+## Open Questions
+
+- {{question}} — {{currentThinking}}

package/dist/resources/extensions/gsd/tools/complete-milestone.js

@@ -15,7 +15,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";
 function renderMilestoneSummaryMarkdown(params) {
     const now = new Date().toISOString();
     const displayTitle = stripIdPrefix(params.title, params.milestoneId);
@@ -156,9 +156,21 @@ export async function handleCompleteMilestone(params, basePath) {
     clearPathCache();
     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.message}`);
+    }
+    try {
         writeManifest(basePath);
+    }
+    catch (mfErr) {
+        logWarning("tool", `complete-milestone manifest warning: ${mfErr.message}`);
+    }
+    try {
         appendEvent(basePath, {
             cmd: "complete-milestone",
             params: { milestoneId: params.milestoneId },
@@ -168,8 +180,8 @@ export async function handleCompleteMilestone(params, basePath) {
             trigger_reason: params.triggerReason,
         });
     }
-    catch (hookErr) {
-        logWarning("tool", `complete-milestone post-mutation hook warning: ${hookErr.message}`);
+    catch (eventErr) {
+        logError("tool", `complete-milestone event log FAILED — completion invisible to reconciliation`, { error: eventErr.message });
     }
     return {
         milestoneId: params.milestoneId,

package/dist/resources/extensions/gsd/tools/complete-slice.js

@@ -18,7 +18,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";
 /**
  * Render slice summary markdown matching the template format.
  * YAML frontmatter uses snake_case keys for parseSummary() compatibility.
@@ -187,8 +187,17 @@ export async function handleCompleteSlice(params, basePath) {
     if (ownershipErr) {
         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 = null;
     transaction(() => {
         // State machine preconditions (inside txn for atomicity).
@@ -217,8 +226,8 @@ export async function handleCompleteSlice(params, basePath) {
             return;
         }
         // 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);
     });
     if (guardError) {
@@ -256,7 +265,7 @@ export async function handleCompleteSlice(params, basePath) {
     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.message });
-        updateSliceStatus(params.milestoneId, params.sliceId, 'pending');
+        updateSliceStatus(params.milestoneId, params.sliceId, originalSliceStatus);
         invalidateStateCache();
         return { error: `disk render failed: ${renderErr.message}` };
     }
@@ -267,9 +276,21 @@ export async function handleCompleteSlice(params, basePath) {
     clearPathCache();
     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.message}`);
+    }
+    try {
         writeManifest(basePath);
+    }
+    catch (mfErr) {
+        logWarning("tool", `complete-slice manifest warning: ${mfErr.message}`);
+    }
+    try {
         appendEvent(basePath, {
             cmd: "complete-slice",
             params: { milestoneId: params.milestoneId, sliceId: params.sliceId },
@@ -279,8 +300,8 @@ export async function handleCompleteSlice(params, basePath) {
             trigger_reason: params.triggerReason,
         });
     }
-    catch (hookErr) {
-        logWarning("tool", `complete-slice post-mutation hook failed for ${params.milestoneId}/${params.sliceId}`, { error: hookErr.message });
+    catch (eventErr) {
+        logError("tool", `complete-slice event log FAILED — completion invisible to reconciliation`, { error: eventErr.message });
     }
     return {
         sliceId: params.sliceId,

package/dist/resources/extensions/gsd/tools/complete-task.js

@@ -18,7 +18,19 @@ 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";
+/**
+ * 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) {
+    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).
@@ -38,8 +50,8 @@ function paramsToTaskRow(params, completedAt) {
         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: "",
@@ -101,8 +113,8 @@ export async function handleCompleteTask(params, basePath) {
             return;
         }
         // 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,
@@ -182,9 +194,21 @@ export async function handleCompleteTask(params, basePath) {
     clearPathCache();
     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.message}`);
+    }
+    try {
         writeManifest(basePath);
+    }
+    catch (mfErr) {
+        logWarning("tool", `complete-task manifest warning: ${mfErr.message}`);
+    }
+    try {
         appendEvent(basePath, {
             cmd: "complete-task",
             params: { milestoneId: params.milestoneId, sliceId: params.sliceId, taskId: params.taskId },
@@ -194,8 +218,8 @@ export async function handleCompleteTask(params, basePath) {
             trigger_reason: params.triggerReason,
         });
     }
-    catch (hookErr) {
-        logWarning("tool", `complete-task post-mutation hook warning: ${hookErr.message}`);
+    catch (eventErr) {
+        logError("tool", `complete-task event log FAILED — completion invisible to reconciliation`, { error: eventErr.message });
     }
     return {
         taskId: params.taskId,

package/dist/resources/extensions/gsd/tools/plan-milestone.js

@@ -113,10 +113,10 @@ function validateParams(params) {
         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.",
@@ -191,7 +191,8 @@ export async function handlePlanMilestone(rawParams, basePath) {
                 requirementCoverage: params.requirementCoverage,
                 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".
@@ -207,6 +208,7 @@ export async function handlePlanMilestone(rawParams, basePath) {
                     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/dist/resources/extensions/gsd/tools/reassess-roadmap.js

@@ -129,8 +129,10 @@ export async function handleReassessRoadmap(rawParams, basePath) {
                     demo: mod.demo,
                 });
             }
-            // 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,
@@ -139,6 +141,7 @@ export async function handleReassessRoadmap(rawParams, basePath) {
                     risk: added.risk,
                     depends: added.depends,
                     demo: added.demo ?? "",
+                    sequence: existingCount + i + 1,
                 });
             }
             // Delete removed slices

package/dist/resources/extensions/gsd/tools/reopen-milestone.js

@@ -0,0 +1,119 @@
+// 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 async function handleReopenMilestone(params, basePath) {
+    // ── 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 = 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.message}`);
+    }
+    return {
+        milestoneId: params.milestoneId,
+        slicesReset: slicesResetCount,
+        tasksReset: tasksResetCount,
+    };
+}

package/dist/resources/extensions/gsd/tools/reopen-slice.js

@@ -16,6 +16,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 async function handleReopenSlice(params, basePath) {
     // ── Validate required fields ────────────────────────────────────────────
     if (!params.sliceId || typeof params.sliceId !== "string" || params.sliceId.trim() === "") {
@@ -59,6 +62,33 @@ export async function handleReopenSlice(params, basePath) {
     }
     // ── 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.message}`);
+    }
+    clearPathCache();
     // ── Post-mutation hook ───────────────────────────────────────────────────
     try {
         await renderAllProjections(basePath, params.milestoneId);

package/dist/resources/extensions/gsd/tools/reopen-task.js

@@ -15,6 +15,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 async function handleReopenTask(params, basePath) {
     // ── Validate required fields ────────────────────────────────────────────
     if (!params.taskId || typeof params.taskId !== "string" || params.taskId.trim() === "") {
@@ -63,6 +66,21 @@ export async function handleReopenTask(params, basePath) {
     }
     // ── 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.message}`);
+    }
+    clearPathCache();
     // ── Post-mutation hook ───────────────────────────────────────────────────
     try {
         await renderAllProjections(basePath, params.milestoneId);