@opengsd/gsd-pi 1.2.0-dev.d6c5343c → 1.2.0-dev.ddc97c10

package/dist/resources/extensions/gsd/milestone-closeout.js

@@ -4,10 +4,13 @@
 // - preflight: dispatch git clean before complete-milestone agent (auto-dispatch)
 // - postUnit: git commit, artifact verify, DB settle, then GitHub finalize
 // - recovery: DB repair from artifacts, then GitHub finalize
+import { existsSync } from "node:fs";
 import { loadFile } from "./files.js";
 import { resolveMilestoneFile } from "./paths.js";
-import { getMilestone, getClosedSliceIds, isDbAvailable } from "./gsd-db.js";
+import { getMilestone, getClosedSliceIds, getLatestAssessmentByScope, getMilestoneSlices, isDbAvailable, } from "./gsd-db.js";
 import { isClosedStatus } from "./status-guards.js";
+import { resolveExpectedArtifactPath } from "./auto-artifact-paths.js";
+import { handleCompleteMilestone } from "./tools/complete-milestone.js";
 import { runSafely } from "./auto-utils.js";
 import { extractVerdict, isAcceptableUatVerdict } from "./verdict-parser.js";
 import { uatSignoffBlockerGuidance } from "./guidance.js";
@@ -19,6 +22,60 @@ import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
 import { commitPendingMilestoneCloseoutChanges, findMissingSummaries, isVerificationNotApplicable, readUatGateVerdict, } from "./auto-dispatch.js";
 const COMPLETE_MILESTONE_DB_SETTLE_MS = 1500;
 const COMPLETE_MILESTONE_DB_SETTLE_POLL_MS = 100;
+/**
+ * True when a milestone is terminal for git cleanup (orphaned worktrees, stale branches).
+ * DB-authoritative (ADR-017): closed status, or validation-pass with all slices closed.
+ * When the DB is unavailable we cannot make this decision and conservatively
+ * return false so callers leave the worktree/branch alone instead of cleaning
+ * up based on parsed projections.
+ */
+export async function isCompletedMilestoneTerminal(_basePath, milestoneId) {
+    if (!isDbAvailable())
+        return false;
+    const milestone = getMilestone(milestoneId);
+    if (!milestone)
+        return false;
+    if (isClosedStatus(milestone.status)) {
+        return true;
+    }
+    const validation = getLatestAssessmentByScope(milestoneId, "milestone-validation");
+    if (validation?.status !== "pass") {
+        return false;
+    }
+    const slices = getMilestoneSlices(milestoneId);
+    if (slices.length === 0)
+        return false;
+    return slices.every((slice) => isClosedStatus(slice.status));
+}
+/** Write a missing milestone SUMMARY projection when canonical DB closeout already settled. */
+export async function repairMissingMilestoneSummaryProjection(basePath, milestoneId) {
+    const milestone = getMilestone(milestoneId);
+    if (!milestone) {
+        return { ok: false, error: `milestone not found: ${milestoneId}` };
+    }
+    const artifactBasePath = resolveCanonicalMilestoneRoot(basePath, milestoneId);
+    const summaryPath = resolveExpectedArtifactPath("complete-milestone", milestoneId, artifactBasePath);
+    if (summaryPath && existsSync(summaryPath)) {
+        return { ok: true };
+    }
+    const result = await handleCompleteMilestone({
+        milestoneId,
+        title: milestone.title,
+        oneLiner: "Canonical closeout completed; summary projection repaired automatically.",
+        narrative: "The workflow database recorded this milestone as complete, but the milestone SUMMARY artifact was missing on disk. " +
+            "Dispatch policy repaired the projection so closeout proof and cleanup can proceed.",
+        verificationPassed: true,
+        triggerReason: "closeout-projection-repair",
+    }, basePath);
+    if ("error" in result) {
+        return { ok: false, error: result.error };
+    }
+    const writtenSummaryPath = result.summaryPath;
+    if (result.stale || !writtenSummaryPath || !existsSync(writtenSummaryPath)) {
+        return { ok: false, error: "milestone SUMMARY projection write failed" };
+    }
+    return { ok: true };
+}
 /**
  * True when the milestone is closed in the DB and the completion summary artifact exists.
  * Polls briefly so post-unit verification can observe the tool's DB write.
@@ -65,7 +122,21 @@ export async function evaluateCompleteMilestoneDispatch(ctx) {
     if (isDbAvailable()) {
         const milestone = getMilestone(mid);
         if (milestone && isClosedStatus(milestone.status)) {
-            return { action: "skip" };
+            const artifactBasePath = resolveCanonicalMilestoneRoot(basePath, mid);
+            const summaryPath = resolveExpectedArtifactPath("complete-milestone", mid, artifactBasePath);
+            const summaryMissing = !summaryPath || !existsSync(summaryPath);
+            if (summaryMissing) {
+                const repair = await repairMissingMilestoneSummaryProjection(basePath, mid);
+                if (!repair.ok) {
+                    logWarning("dispatch", `Milestone ${mid} is closed in DB but SUMMARY repair failed: ${repair.error}. Dispatching complete-milestone to retry.`);
+                }
+                else {
+                    return { action: "skip" };
+                }
+            }
+            else {
+                return { action: "skip" };
+            }
         }
     }
     const closeoutGitStop = commitPendingMilestoneCloseoutChanges(basePath, mid);

package/dist/resources/extensions/gsd/milestone-planning-persistence.js

@@ -5,7 +5,7 @@ import { isClosedStatus } from "./status-guards.js";
 import { transaction, getMilestone, getMilestoneSlices, getSlice, insertMilestone, insertSlice, upsertMilestonePlanning, upsertSlicePlanning, } from "./gsd-db.js";
 import { invalidateStateCache } from "./state.js";
 import { renderRoadmapFromDb } from "./markdown-renderer.js";
-import { renderAllProjections } from "./workflow-projections.js";
+import { flushWorkflowProjections } from "./projection-flush.js";
 import { writeManifest } from "./workflow-manifest.js";
 import { appendEvent } from "./workflow-events.js";
 import { logWarning } from "./workflow-logger.js";
@@ -109,7 +109,7 @@ async function renderPlanArtifacts(basePath, params) {
 }
 async function runPostPlanHooks(basePath, params) {
     try {
-        await renderAllProjections(basePath, params.milestoneId);
+        await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
         writeManifest(basePath);
         appendEvent(basePath, {
             cmd: "plan-milestone",

package/dist/resources/extensions/gsd/projection-flush.js

@@ -0,0 +1,7 @@
+// Project/App: gsd-pi
+// File Purpose: Single workflow projection flush seam for mutation exits.
+import { renderAllProjections } from "./workflow-projections.js";
+export async function flushWorkflowProjections(basePath, scope) {
+    await renderAllProjections(basePath, scope.milestoneId);
+    return { milestoneId: scope.milestoneId };
+}

package/dist/resources/extensions/gsd/prompts/complete-slice.md

@@ -49,4 +49,4 @@ Use `subagent` only when useful: reviewer, security, or tester. Apply findings b
 
 **You MUST call `gsd_slice_complete` with summary and UAT content only after verification passes.**
 
-When done, say: "Slice {{sliceId}} complete."
+When done, say: "Slice {{sliceId}} complete." Say this exactly once — if you already said it in a prior message, do not repeat it.

package/dist/resources/extensions/gsd/prompts/execute-task.md

@@ -76,4 +76,4 @@ Keep about **{{verificationBudget}}** for verification and summary. If context i
 
 **You MUST call `gsd_task_complete` before finishing, including when the stale-path safety rule stops execution.**
 
-When done, say: "Task {{taskId}} complete."
+When done, say: "Task {{taskId}} complete." Say this exactly once — if you already said it in a prior message, do not repeat it.

package/dist/resources/extensions/gsd/prompts/plan-milestone.md

@@ -118,4 +118,4 @@ If external API keys or secrets are required, use the inlined **Secrets Manifest
 
 If no external API keys or secrets are required, skip this step; do not create an empty manifest.
 
-When done, say: "Milestone {{milestoneId}} planned."
+When done, say: "Milestone {{milestoneId}} planned." Say this exactly once — if you already said it in a prior message, do not repeat it.

package/dist/resources/extensions/gsd/prompts/plan-slice.md

@@ -57,4 +57,4 @@ The slice directory already exists. Do not mkdir.
 
 **You MUST call `gsd_plan_slice` to persist planning state before finishing, unless the stale-path safety rule above stops the unit before safe planning can occur.**
 
-When done, say: "Slice {{sliceId}} planned."
+When done, say: "Slice {{sliceId}} planned." Say this exactly once — if you already said it in a prior message, do not repeat it.

package/dist/resources/extensions/gsd/prompts/quick-task.md

@@ -37,4 +37,4 @@ You are executing a GSD quick task — a lightweight, focused unit of work outsi
 - <what was tested/verified>
 ```
 
-When done, say: "Quick task {{taskNum}} complete."
+When done, say: "Quick task {{taskNum}} complete." Say this exactly once — if you already said it in a prior message, do not repeat it.

package/dist/resources/extensions/gsd/prompts/reassess-roadmap.md

@@ -67,4 +67,4 @@ If `.gsd/REQUIREMENTS.md` exists and requirement ownership or status changed, up
 
 **DB access safety:** Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')`. Use `gsd_milestone_status` to read current milestone and slice state. All roadmap mutations go through `gsd_reassess_roadmap` — the tool writes to the DB and re-renders ROADMAP.md atomically.
 
-When done, say: "Roadmap reassessed."
+When done, say: "Roadmap reassessed." Say this exactly once — if you already said it in a prior message, do not repeat it.

package/dist/resources/extensions/gsd/prompts/refine-slice.md

@@ -77,4 +77,4 @@ The slice directory and tasks/ subdirectory already exist. Do NOT mkdir.
 
 **You MUST call `gsd_plan_slice` to persist planning state before finishing.** After success, the pipeline clears the sketch flag on next state derivation; the on-disk PLAN file is the signal.
 
-When done, say: "Slice {{sliceId}} refined."
+When done, say: "Slice {{sliceId}} refined." Say this exactly once — if you already said it in a prior message, do not repeat it.

package/dist/resources/extensions/gsd/prompts/replan-slice.md

@@ -38,4 +38,4 @@ Consider these captures when rewriting the remaining tasks — they represent th
 4. If any incomplete task had a `T0x-PLAN.md`, remove or rewrite it to match the new task description.
 5. Do not commit manually — the system auto-commits your changes after this unit completes.
 
-When done, say: "Slice {{sliceId}} replanned."
+When done, say: "Slice {{sliceId}} replanned." Say this exactly once — if you already said it in a prior message, do not repeat it.

package/dist/resources/extensions/gsd/prompts/research-milestone.md

@@ -46,4 +46,4 @@ Then research the codebase and relevant technologies. Narrate key findings and s
 
 **You MUST call `gsd_summary_save` with the research content before finishing.**
 
-When done, say: "Milestone {{milestoneId}} researched."
+When done, say: "Milestone {{milestoneId}} researched." Say this exactly once — if you already said it in a prior message, do not repeat it.

package/dist/resources/extensions/gsd/prompts/research-slice.md

@@ -55,4 +55,4 @@ The slice directory already exists at `{{slicePath}}/`. Do NOT mkdir.
 
 **You MUST call `gsd_summary_save` with the research content before finishing.**
 
-When done, say: "Slice {{sliceId}} researched."
+When done, say: "Slice {{sliceId}} researched." Say this exactly once — if you already said it in a prior message, do not repeat it.

package/dist/resources/extensions/gsd/prompts/rewrite-docs.md

@@ -30,4 +30,4 @@ An override was issued by the user that changes a fundamental decision or approa
 
 **You MUST update the relevant documents AND mark overrides as resolved in `{{overridesPath}}` before finishing.**
 
-When done, say: "Override applied across all documents."
+When done, say: "Override applied across all documents." Say this exactly once — if you already said it in a prior message, do not repeat it.

package/dist/resources/extensions/gsd/prompts/run-uat.md

@@ -100,4 +100,4 @@ checks: [{
 
 **You MUST call `gsd_uat_result_save` before finishing. Do not write the assessment file directly, and do not call `gsd_summary_save` as a substitute.**
 
-When done, say: "UAT {{sliceId}} complete."
+When done, say: "UAT {{sliceId}} complete." Say this exactly once — if you already said it in a prior message, do not repeat it.

package/dist/resources/extensions/gsd/prompts/triage-captures.md

@@ -65,4 +65,4 @@ Classify each capture as one of:
 
 **Important:** Do NOT execute any resolutions. Only classify and update CAPTURES.md. Resolution execution happens separately (in auto-mode dispatch or manually by the user).
 
-When done, say: "Triage complete."
+When done, say: "Triage complete." Say this exactly once — if you already said it in a prior message, do not repeat it.

package/dist/resources/extensions/gsd/prompts/validate-milestone.md

@@ -87,4 +87,4 @@ If verdict is `needs-remediation`:
 
 **File system safety:** When scanning milestone directories, use `ls` or `find` first. Never pass a directory path such as `tasks/` or `slices/` directly to `read`; it only accepts files.
 
-When done, say: "Milestone {{milestoneId}} validation complete — verdict: <verdict>."
+When done, say: "Milestone {{milestoneId}} validation complete — verdict: <verdict>." Say this exactly once — if you already said it in a prior message, do not repeat it.

package/dist/resources/extensions/gsd/roadmap-slices.js

@@ -161,6 +161,26 @@ function parseTableSlices(section) {
     }
     return slices;
 }
+function looksLikeTable(section) {
+    const lines = section.split("\n");
+    // Checkbox format takes precedence — embedded demo tables must not switch mode (#721).
+    if (lines.some(line => /^\s*-\s+\[[ xX]\]/.test(line))) {
+        return false;
+    }
+    const pipeLines = lines.filter(line => /^\s*\|/.test(line));
+    if (pipeLines.length < 2)
+        return false;
+    const hasSeparatorRow = pipeLines.some((line, index) => {
+        if (index === 0)
+            return false;
+        const cells = line.split("|").map(c => c.trim()).filter(Boolean);
+        return /^\s*\|[\s:-]+\|/.test(line) && cells.length >= 2 && cells.every(c => /^[\s:-]+$/.test(c));
+    });
+    if (hasSeparatorRow)
+        return true;
+    // Tables without a separator row still expose slice IDs in data rows.
+    return pipeLines.some(line => /\bS\d+\b/.test(line));
+}
 export function parseRoadmapSlices(content) {
     const slicesSection = extractSlicesSection(content);
     if (!slicesSection) {
@@ -171,9 +191,11 @@ export function parseRoadmapSlices(content) {
     }
     // Try table format first — if the section contains pipe-delimited rows with
     // slice IDs, parse them as a table (#1736).
-    const tableSlices = parseTableSlices(slicesSection);
-    if (tableSlices.length > 0) {
-        return tableSlices;
+    if (looksLikeTable(slicesSection)) {
+        const tableSlices = parseTableSlices(slicesSection);
+        if (tableSlices.length > 0) {
+            return tableSlices;
+        }
     }
     // Standard checkbox format
     const slices = [];

package/dist/resources/extensions/gsd/session-lock.js

@@ -329,7 +329,7 @@ export function acquireSessionLock(basePath) {
         // #3218: Provide actionable workaround when lock recovery fails
         const lockDirPath = lockTarget + ".lock";
         const reason = existingPid
-            ? `Another auto-mode session (PID ${existingPid}) appears to be running.\nStop it with \`kill ${existingPid}\` before starting a new session.`
+            ? `Another auto-mode session (PID ${existingPid}) appears to be running.\nRun \`/gsd stop\` for graceful shutdown, or choose "Force start" from \`/gsd auto\` to terminate it.`
             : `Another auto-mode session lock is stuck on this project.\nRun: rm -rf "${lockDirPath}" && rm -f "${lp}"`;
         return { acquired: false, reason, existingPid };
     }

package/dist/resources/extensions/gsd/tool-contract.js

@@ -1,8 +1,8 @@
 // Project/App: gsd-pi
 // File Purpose: ADR-015 Tool Contract module for Unit prompt, policy, and tool parity.
 import { resolveManifest, } from "./unit-context-manifest.js";
-import { getRequiredWorkflowToolsForAutoUnit } from "./workflow-mcp.js";
-import { getUnitToolSurfaceContract } from "./unit-tool-contracts.js";
+import { getWorkflowTransportSupportError, } from "./workflow-mcp.js";
+import { getRequiredWorkflowToolsForUnit, getUnitToolSurfaceContract, } from "./unit-tool-contracts.js";
 import { WHOLE_FILE_OBSERVATION_MAX_BYTES, WHOLE_FILE_OBSERVATION_MAX_LINES, } from "./source-observations.js";
 export function compileUnitContextContract(unitType) {
     const manifest = resolveManifest(unitType);
@@ -15,6 +15,17 @@ export function compileUnitContextContract(unitType) {
     }
     return { ok: true, contract: buildPromptContextContract(unitType, manifest) };
 }
+export function getUnitWorkflowDispatchReadinessError(input) {
+    return getWorkflowTransportSupportError(input.provider, getRequiredWorkflowToolsForUnit(input.unitType), {
+        projectRoot: input.projectRoot,
+        env: input.env,
+        surface: input.surface,
+        unitType: input.unitType,
+        authMode: input.authMode,
+        baseUrl: input.baseUrl,
+        activeTools: input.activeTools,
+    });
+}
 export function compileUnitToolContract(unitType) {
     const manifest = resolveManifest(unitType);
     const surfaceContract = getUnitToolSurfaceContract(unitType);
@@ -25,7 +36,7 @@ export function compileUnitToolContract(unitType) {
             detail: `No Unit manifest is registered for ${unitType}`,
         };
     }
-    const requiredWorkflowTools = getRequiredWorkflowToolsForAutoUnit(unitType);
+    const requiredWorkflowTools = getRequiredWorkflowToolsForUnit(unitType);
     const forbiddenWorkflowTools = Object.entries(surfaceContract?.forbiddenGsdTools ?? {})
         .map(([name, reason]) => ({ name, reason }));
     const closeoutTools = requiredWorkflowTools.filter((tool) => /^gsd_(?:task|slice|milestone|complete|validate|save|summary|uat)/.test(tool));

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

@@ -16,7 +16,8 @@ import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { isClosedStatus } from "../status-guards.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
-import { renderAllProjections, stripIdPrefix } from "../workflow-projections.js";
+import { stripIdPrefix } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
@@ -166,7 +167,7 @@ export async function handleCompleteMilestone(params, basePath) {
     // Separate try/catch per step so a projection failure doesn't prevent
     // the event log entry (critical for worktree reconciliation).
     try {
-        await renderAllProjections(artifactBasePath, params.milestoneId);
+        await flushWorkflowProjections(artifactBasePath, { milestoneId: params.milestoneId });
     }
     catch (projErr) {
         logWarning("tool", `complete-milestone projection warning: ${projErr.message}`);

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

@@ -21,7 +21,7 @@ import { classifyUatContent, escalatesArtifactUatToBrowser } from "../uat-policy
 import { invalidateStateCache } from "../state.js";
 import { renderRoadmapFromDb, roadmapRenderMarksSliceDone } from "../markdown-renderer.js";
 import { isStaleWrite } from "../auto/turn-epoch.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
@@ -448,7 +448,7 @@ export async function handleCompleteSlice(params, basePath) {
     // Separate try/catch per step so a projection failure doesn't prevent
     // the event log entry (critical for worktree reconciliation).
     try {
-        await renderAllProjections(artifactBasePath, params.milestoneId);
+        await flushWorkflowProjections(artifactBasePath, { milestoneId: params.milestoneId });
     }
     catch (projErr) {
         logWarning("tool", `complete-slice projection warning for ${params.milestoneId}/${params.sliceId}: ${projErr.message}`);

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

@@ -18,7 +18,8 @@ import { checkOwnership, taskUnitKey } from "../unit-ownership.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { renderPlanCheckboxes } from "../markdown-renderer.js";
-import { renderAllProjections, renderSummaryContent } from "../workflow-projections.js";
+import { renderSummaryContent } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
@@ -358,7 +359,7 @@ export async function handleCompleteTask(params, basePath) {
     // Separate try/catch per step so a projection failure doesn't prevent
     // the event log entry (critical for worktree reconciliation).
     try {
-        await renderAllProjections(artifactBasePath, params.milestoneId);
+        await flushWorkflowProjections(artifactBasePath, { milestoneId: params.milestoneId });
     }
     catch (projErr) {
         logWarning("tool", `complete-task projection warning: ${projErr.message}`);

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

@@ -7,7 +7,7 @@ import { getGateIdsForTurn } from "../gate-registry.js";
 import { transaction, getMilestone, getSlice, getSliceTasks, insertTask, upsertSlicePlanning, upsertTaskPlanning, insertGateRow, updateSliceStatus, setSliceSketchFlag, deleteTask, deleteArtifactByPath, } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { renderPlanFromDb } from "../markdown-renderer.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -367,7 +367,7 @@ export async function handlePlanSlice(rawParams, basePath) {
         clearParseCache();
         // ── Post-mutation hook: projections, manifest, event log ─────────────
         try {
-            await renderAllProjections(basePath, params.milestoneId);
+            await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
             writeManifest(basePath);
             appendEvent(basePath, {
                 cmd: "plan-slice",

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

@@ -4,7 +4,7 @@ import { isNonEmptyString, validateStringArray } from "../validation.js";
 import { transaction, getSlice, getTask, insertTask, upsertTaskPlanning } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { renderTaskPlanFromDb } from "../markdown-renderer.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -110,7 +110,7 @@ export async function handlePlanTask(rawParams, basePath) {
         clearParseCache();
         // ── Post-mutation hook: projections, manifest, event log ─────────────
         try {
-            await renderAllProjections(basePath, params.milestoneId);
+            await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
             writeManifest(basePath);
             appendEvent(basePath, {
                 cmd: "plan-task",

package/dist/resources/extensions/gsd/tools/reassess-roadmap.js

@@ -6,7 +6,7 @@ import { isNonEmptyString } from "../validation.js";
 import { transaction, getMilestone, getMilestoneSlices, getSlice, insertSlice, updateSliceFields, insertAssessment, deleteAssessmentByScope, deleteSlice, } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { renderRoadmapFromDb, renderAssessmentFromDb } from "../markdown-renderer.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -234,7 +234,7 @@ export async function handleReassessRoadmap(rawParams, basePath) {
         clearParseCache();
         // ── Post-mutation hook: projections, manifest, event log ─────
         try {
-            await renderAllProjections(basePath, params.milestoneId);
+            await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
             writeManifest(basePath);
             appendEvent(basePath, {
                 cmd: "reassess-roadmap",

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

@@ -9,7 +9,7 @@
  */
 import { getMilestoneSlices, getSliceTasks, reopenMilestoneCascade, } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -74,7 +74,7 @@ export async function handleReopenMilestone(params, basePath) {
     clearPathCache();
     // ── Post-mutation hook ───────────────────────────────────────────────────
     try {
-        await renderAllProjections(basePath, params.milestoneId);
+        await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
         writeManifest(basePath);
         appendEvent(basePath, {
             cmd: "reopen-milestone",

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

@@ -11,7 +11,7 @@
 // Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
 import { getSliceTasks, reopenSliceCascade, } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -72,7 +72,7 @@ export async function handleReopenSlice(params, basePath) {
     clearPathCache();
     // ── Post-mutation hook ───────────────────────────────────────────────────
     try {
-        await renderAllProjections(basePath, params.milestoneId);
+        await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
         writeManifest(basePath);
         appendEvent(basePath, {
             cmd: "reopen-slice",

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

@@ -11,7 +11,7 @@
 import { getMilestone, getSlice, getTask, updateTaskStatus, transaction, } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { isClosedStatus } from "../status-guards.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -83,7 +83,7 @@ export async function handleReopenTask(params, basePath) {
     clearPathCache();
     // ── Post-mutation hook ───────────────────────────────────────────────────
     try {
-        await renderAllProjections(basePath, params.milestoneId);
+        await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
         writeManifest(basePath);
         appendEvent(basePath, {
             cmd: "reopen-task",

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

@@ -4,7 +4,7 @@ import { invalidateStateCache } from "../state.js";
 import { isClosedStatus } from "../status-guards.js";
 import { isNonEmptyString } from "../validation.js";
 import { renderPlanFromDb, renderReplanFromDb } from "../markdown-renderer.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -162,7 +162,7 @@ export async function handleReplanSlice(rawParams, basePath) {
         clearParseCache();
         // ── Post-mutation hook: projections, manifest, event log ─────
         try {
-            await renderAllProjections(basePath, params.milestoneId);
+            await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
             writeManifest(basePath);
             appendEvent(basePath, {
                 cmd: "replan-slice",

package/dist/resources/extensions/gsd/tools/workflow-tool-executors.js

@@ -6,9 +6,10 @@ import { loadWriteGateSnapshot, shouldBlockContextArtifactSaveInSnapshot, should
 import { getActiveRequirements, getAllMilestones, getMilestone, getSliceStatusSummary, getSliceTaskCounts, insertMilestone, insertAssessment, insertGateRun, readTransaction, saveGateResult, upsertQualityGate, } from "../gsd-db.js";
 import { GATE_REGISTRY } from "../gate-registry.js";
 import { generateRequirementsMd, saveArtifactToDb } from "../db-writer.js";
-import { clearPathCache, relSliceFile, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
+import { clearPathCache, normalizeRealPath, relSliceFile, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { unlinkSync } from "node:fs";
+import { hostname } from "node:os";
 import { join } from "node:path";
 import { handleCompleteMilestone } from "./complete-milestone.js";
 import { handleCompleteTask } from "./complete-task.js";
@@ -25,9 +26,11 @@ import { logError, logWarning } from "../workflow-logger.js";
 import { invalidateStateCache } from "../state.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { parseProject } from "../schemas/parsers.js";
-import { getAutoRuntimeSnapshot } from "../auto-runtime-state.js";
+import { autoSession, getAutoRuntimeSnapshot, isAutoActive } from "../auto-runtime-state.js";
 import { renderPlanFromDb } from "../markdown-renderer.js";
 import { prepareUatRun, saveUatAttemptArtifact, } from "../uat-run.js";
+import { registerAutoWorker, markWorkerStopping, getAutoWorker } from "../db/auto-workers.js";
+import { claimMilestoneLease, releaseMilestoneLease, getMilestoneLease, refreshMilestoneLease, milestoneLeaseTtlSeconds, } from "../db/milestone-leases.js";
 export const SUPPORTED_SUMMARY_ARTIFACT_TYPES = [
     "SUMMARY",
     "RESEARCH",
@@ -61,6 +64,19 @@ function blockIfWrongAutoUnit(requiredUnitType, operation) {
         isError: true,
     };
 }
+function milestoneLeaseConflictResult(milestoneId, byWorker, expiresAt) {
+    return {
+        content: [{ type: "text", text: `Milestone ${milestoneId} is currently leased by ${byWorker}. Retry after ${expiresAt}.` }],
+        details: {
+            operation: "plan_milestone",
+            error: "milestone_lease_conflict",
+            milestoneId,
+            byWorker,
+            expiresAt,
+        },
+        isError: true,
+    };
+}
 function registerProjectMilestoneSequence(content) {
     const parsed = parseProject(content);
     const registered = [];
@@ -1066,7 +1082,45 @@ export async function executePlanMilestone(params, basePath = process.cwd()) {
             isError: true,
         };
     }
+    let workerId = null;
+    let acquiredToken = null;
+    let leaseRefreshTimer;
     try {
+        // Re-read at the gate so a peer-created milestone is not treated as fresh.
+        const milestoneExists = getMilestone(params.milestoneId) !== null;
+        if (milestoneExists) {
+            const heldLease = getMilestoneLease(params.milestoneId);
+            if (heldLease?.status === "held" && Date.parse(heldLease.expires_at) > Date.now()) {
+                const holder = getAutoWorker(heldLease.worker_id);
+                // Let the one-shot claim path recover stale same-process worker rows.
+                const projectRoot = normalizeRealPath(basePath);
+                const isOurAutoLease = isAutoActive() && heldLease.worker_id === autoSession.workerId;
+                const holderIsOneShotReentrantPeer = !isAutoActive()
+                    && !!holder
+                    && holder.host === hostname()
+                    && holder.pid === process.pid
+                    && holder.project_root_realpath === projectRoot;
+                if (holder?.status === "active" && !isOurAutoLease && !holderIsOneShotReentrantPeer) {
+                    return milestoneLeaseConflictResult(params.milestoneId, heldLease.worker_id, heldLease.expires_at);
+                }
+            }
+        }
+        // Fresh creation cannot claim a lease because the FK row does not exist.
+        // In-process auto already owns its lease; re-claiming would bump its token.
+        if (!isAutoActive() && milestoneExists) {
+            workerId = registerAutoWorker({ projectRootRealpath: normalizeRealPath(basePath) });
+            const lease = claimMilestoneLease(workerId, params.milestoneId);
+            if (!lease.ok) {
+                return milestoneLeaseConflictResult(params.milestoneId, lease.byWorker, lease.expiresAt);
+            }
+            acquiredToken = lease.token;
+            const leaseRefreshMs = (milestoneLeaseTtlSeconds() / 2) * 1000;
+            leaseRefreshTimer = setInterval(() => {
+                if (acquiredToken !== null && workerId !== null) {
+                    refreshMilestoneLease(workerId, params.milestoneId, acquiredToken);
+                }
+            }, leaseRefreshMs);
+        }
         const result = await handlePlanMilestone(params, basePath);
         if ("error" in result) {
             return {
@@ -1093,6 +1147,17 @@ export async function executePlanMilestone(params, basePath = process.cwd()) {
             isError: true,
         };
     }
+    finally {
+        if (leaseRefreshTimer !== undefined) {
+            clearInterval(leaseRefreshTimer);
+        }
+        if (workerId !== null && acquiredToken !== null) {
+            releaseMilestoneLease(workerId, params.milestoneId, acquiredToken);
+        }
+        if (workerId !== null) {
+            markWorkerStopping(workerId);
+        }
+    }
 }
 export async function executePlanSlice(params, basePath = process.cwd()) {
     const dbAvailable = await ensureDbOpen(basePath);