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

package/src/resources/extensions/gsd/commands-handlers.ts

@@ -9,7 +9,7 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent
 import { existsSync, readFileSync, mkdirSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { createRequire } from "node:module";
-import { join, resolve as resolvePath, sep } from "node:path";
+import { join, resolve as resolvePath, sep, win32 as pathWin32 } from "node:path";
 import { homedir } from "node:os";
 import { deriveState } from "./state.js";
 import { gsdRoot } from "./paths.js";
@@ -29,6 +29,7 @@ import { getAutoWorktreePath } from "./auto-worktree.js";
 import { currentDirectoryRoot, projectRoot } from "./commands/context.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { buildClaudeRuntimeFloorAdvisory } from "../../shared/claude-runtime-floor.js";
+import { reconcileGsdBrowserPathAfterInstall } from "../../shared/gsd-browser-path-sync.js";
 import { isPnpmInstall } from "../../shared/package-manager-detection.js";
 import {
   buildDoctorHealIssuePayload,
@@ -65,9 +66,33 @@ function isBunInstall(argv1: string | undefined = process.argv[1]): boolean {
 function resolveInstallCommand(pkg: string): string {
   if (isBunInstall()) return `bun add -g ${pkg}`;
   if (isPnpmInstall()) return `pnpm add -g ${pkg}`;
+  const npmPrefix = resolveWindowsNpmGlobalPrefix();
+  if (npmPrefix) return `npm --prefix ${quoteWindowsArg(npmPrefix)} install -g ${pkg}`;
   return `npm install -g ${pkg}`;
 }
 
+function resolveWindowsNpmGlobalPrefix(
+  argv1: string | undefined = process.argv[1],
+  platform: NodeJS.Platform = process.platform,
+): string | null {
+  if (platform !== "win32" || !argv1) return null;
+  const normalized = pathWin32.normalize(argv1);
+  const marker = `${pathWin32.sep}node_modules${pathWin32.sep}`;
+  const index = normalized.toLowerCase().lastIndexOf(marker);
+  if (index <= 0) return null;
+  const prefix = normalized.slice(0, index);
+  // Verify this is a real npm global prefix: such a directory always contains
+  // npm's own bin shim (`npm.cmd`) as a sibling of `node_modules/`. Local
+  // project `node_modules/`, npx caches, and other non-global layouts do not,
+  // so without this check `--prefix` would target the wrong directory.
+  if (!existsSync(pathWin32.join(prefix, "npm.cmd"))) return null;
+  return prefix;
+}
+
+function quoteWindowsArg(value: string): string {
+  return `"${value.replace(/"/g, '\\"')}"`;
+}
+
 function notifyClaudeRuntimeFloorAdvisory(ctx: ExtensionCommandContext): void {
   let advisory: string | null = null;
   try {
@@ -576,12 +601,30 @@ export async function handleUpdate(ctx: ExtensionCommandContext, args = ""): Pro
     execSync(installCmd, {
       stdio: ["ignore", "pipe", "ignore"],
     });
+    let reconcile: ReturnType<typeof reconcileGsdBrowserPathAfterInstall> | null = null;
+    if (browserUpdate) {
+      try {
+        reconcile = reconcileGsdBrowserPathAfterInstall({
+          latestVersion: latest,
+          compareSemver: compareSemverLocal,
+          resolvePathVersion: resolveGsdBrowserPathVersionForCommand,
+        });
+      } catch {
+        // Reconciliation is best-effort: the install above already succeeded,
+        // so a reconcile failure must not flip the result to "Update failed".
+        reconcile = null;
+      }
+    }
     const newPathVersion = browserUpdate ? resolveGsdBrowserPathVersionForCommand() : null;
-    const pathReady = !browserUpdate || (!!newPathVersion && compareSemverLocal(newPathVersion, latest) >= 0);
+    const pathNote = browserUpdate && !(newPathVersion && compareSemverLocal(newPathVersion, latest) >= 0)
+      ? (reconcile?.message
+        ?? "Ensure the npm global bin directory is on your PATH so MCP automation uses the updated binary.")
+      : "";
     ctx.ui.notify(
       browserUpdate
         ? `Updated gsd-browser to v${latest}. Restart your GSD session to use the new browser automation version.` +
-          (pathReady ? "" : "\nNote: Ensure the npm global bin directory is on your PATH so MCP automation uses the updated binary.")
+          (reconcile?.action === "synced" && reconcile.message ? `\n${reconcile.message}` : "") +
+          (pathNote ? `\nNote: ${pathNote}` : "")
         : `Updated to v${latest}. Restart your GSD session to use the new version.`,
       "info",
     );

package/src/resources/extensions/gsd/consent-question.ts

@@ -107,6 +107,20 @@ export function hasResearchDecisionQuestion(text: string): boolean {
   return hasQuestionMatching(text, [RESEARCH_DECISION_QUESTION_RE]);
 }
 
+/**
+ * Detect a plain-text "Next steps:" menu — numbered options with an "Other"
+ * choice — emitted as prose instead of a structured ask_user_questions call.
+ * Without this, auto-mode treats the menu as informational and loops on its
+ * own turn until tokens are exhausted (#454).
+ */
+export function hasPlainTextNextStepsMenu(lines: string[]): boolean {
+  const nextStepsIndex = lines.findIndex((line) => /^next steps\s*:?$/i.test(line));
+  if (nextStepsIndex < 0) return false;
+  const menuLines = lines.slice(nextStepsIndex + 1);
+  const numberedOptions = menuLines.filter((line) => /^\d+[.)]\s+\S/.test(line));
+  return numberedOptions.length >= 2 && numberedOptions.some((line) => /\bother\b/i.test(line));
+}
+
 // ── Message text extraction (moved from user-input-boundary) ────────────────
 
 function extractMessageText(msg: unknown, includeThinking: boolean): string {
@@ -347,6 +361,7 @@ export function isAwaitingUserInput(messages: unknown[] | undefined): boolean {
   if (!text) return false;
   const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
   if (lines.some((line) => line.endsWith("?"))) return true;
+  if (hasPlainTextNextStepsMenu(lines)) return true;
   return hasApprovalQuestion(text);
 }
 

package/src/resources/extensions/gsd/crash-recovery.ts

@@ -223,6 +223,7 @@ export function writeLock(
  * stale session-file pointer.
  */
 export function clearLock(basePath: string): void {
+  const legacyLock = readLegacyLock(basePath);
   clearLegacyLockFile(basePath);
 
   if (!isDbAvailable()) return;
@@ -235,8 +236,15 @@ export function clearLock(basePath: string): void {
       deleteRuntimeKv("worker", staleWorker.worker_id, SESSION_FILE_KV_KEY);
       return;
     }
-    const lock = readLegacyLock(basePath);
-    if (lock?.pid) markWorkerStoppingByPid(projectRoot, lock.pid);
+    if (legacyLock?.pid) {
+      markWorkerStoppingByPid(projectRoot, legacyLock.pid);
+      const workerByLegacyPid = getAllAutoWorkers().find(
+        (w) =>
+          w.pid === legacyLock.pid
+          && normalizeRealPath(w.project_root_realpath) === projectRoot,
+      );
+      if (workerByLegacyPid) forceReleaseLeasesForWorker(workerByLegacyPid.worker_id);
+    }
     const worker = findActiveWorkerForCurrentProcess(projectRoot);
     if (worker) deleteRuntimeKv("worker", worker.worker_id, SESSION_FILE_KV_KEY);
 

package/src/resources/extensions/gsd/doctor-engine-checks.ts

@@ -7,7 +7,7 @@ import { isAfter, latestExplicitReopenAt } from "./milestone-reopen-events.js";
 import { resolveGsdPathContract, resolveMilestoneFile } from "./paths.js";
 import { deriveState } from "./state.js";
 import { readEvents } from "./workflow-events.js";
-import { renderAllProjections } from "./workflow-projections.js";
+import { flushWorkflowProjections } from "./projection-flush.js";
 
 export async function checkEngineHealth(
   basePath: string,
@@ -270,7 +270,7 @@ export async function checkEngineHealth(
           const roadmapPath = resolveMilestoneFile(basePath, milestone.id, "ROADMAP");
           if (!roadmapPath || !existsSync(roadmapPath)) {
             try {
-              await renderAllProjections(basePath, milestone.id);
+              await flushWorkflowProjections(basePath, { milestoneId: milestone.id });
               fixesApplied.push(`re-rendered missing projections for ${milestone.id}`);
             } catch {
               // Non-fatal — projection re-render failed
@@ -280,7 +280,7 @@ export async function checkEngineHealth(
           const projectionMtime = statSync(roadmapPath).mtimeMs;
           if (lastEventTs > projectionMtime) {
             try {
-              await renderAllProjections(basePath, milestone.id);
+              await flushWorkflowProjections(basePath, { milestoneId: milestone.id });
               fixesApplied.push(`re-rendered stale projections for ${milestone.id}`);
             } catch {
               // Non-fatal — projection re-render failed

package/src/resources/extensions/gsd/doctor-git-checks.ts

@@ -5,10 +5,9 @@ import { dirname, join } from "node:path";
 
 import type { DoctorIssue, DoctorIssueCode } from "./doctor-types.js";
 import { loadFile } from "./files.js";
-import { parseRoadmap as parseLegacyRoadmap } from "./parsers-legacy.js";
-import { isDbAvailable, getMilestone } from "./gsd-db.js";
 import { resolveMilestoneFile } from "./paths.js";
-import { deriveState, isMilestoneComplete } from "./state.js";
+import { isCompletedMilestoneTerminal } from "./milestone-closeout.js";
+import { deriveState } from "./state.js";
 import { allWorktreesDirs, createWorktree, listWorktrees, resolveGitDir } from "./worktree-manager.js";
 import { abortAndReset } from "./git-self-heal.js";
 import { RUNTIME_EXCLUSION_PATHS, resolveMilestoneIntegrationBranch, writeIntegrationBranch } from "./git-service.js";
@@ -146,22 +145,6 @@ function getSnapshotDiffCheckFailure(basePath: string): string | null {
   return failures.length > 0 ? failures.join("\n") : null;
 }
 
-async function isCompletedMilestoneTerminal(basePath: string, milestoneId: string): Promise<boolean> {
-  const summaryPath = resolveMilestoneFile(basePath, milestoneId, "SUMMARY");
-  if (!summaryPath) return false;
-
-  if (isDbAvailable()) {
-    const milestone = getMilestone(milestoneId);
-    return !!milestone && milestone.status === "complete";
-  }
-
-  const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
-  const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
-  if (!roadmapContent) return false;
-  const roadmap = parseLegacyRoadmap(roadmapContent);
-  return isMilestoneComplete(roadmap);
-}
-
 export async function checkGitHealth(
   basePath: string,
   issues: DoctorIssue[],

package/src/resources/extensions/gsd/gsd-command-home.ts

@@ -66,7 +66,7 @@ function disabled(description: string, reason: string): string {
 
 export function buildGsdHomeModel(
   state: GSDState,
-  closeout?: Pick<CloseoutContext, "strandedQuick" | "unmergedMilestones">,
+  closeout?: Pick<CloseoutContext, "strandedQuick" | "unmergedMilestones" | "idleResidueHint">,
 ): GsdHomeModel {
   const blocked = isBlocked(state);
   const complete = state.phase === "complete";
@@ -74,10 +74,14 @@ export function buildGsdHomeModel(
   const workLabel = activeWorkLabel(state);
   const strandedQuick = closeout?.strandedQuick ?? null;
   const unmergedMilestone = closeout?.unmergedMilestones?.[0];
+  const idleResidueHint = closeout?.idleResidueHint ?? null;
+  const hasIdleResidue = Boolean(idleResidueHint);
   const nextReason = complete
     ? "all milestones are complete"
     : blocked
       ? "the active milestone is blocked"
+      : hasIdleResidue
+        ? "milestone git residue needs recovery"
       : !hasActiveWork
         ? "there is no active milestone"
         : "";
@@ -91,6 +95,8 @@ export function buildGsdHomeModel(
       ? "finish_milestone"
       : blocked
         ? "fix_recover"
+        : hasIdleResidue
+          ? "fix_recover"
         : canAdvance
           ? "continue_step"
           : complete && unmappedActive > 0
@@ -107,6 +113,8 @@ export function buildGsdHomeModel(
     ? [`Quick task Q${strandedQuick.taskNum} finished on ${strandedQuick.quickBranch} but is not merged to ${strandedQuick.originalBranch}.`]
     : unmergedMilestone
       ? [`${unmergedMilestone.milestoneId} is complete but not merged into ${unmergedMilestone.integrationBranch}.`]
+      : idleResidueHint
+        ? [idleResidueHint.message]
       : completionSummary;
 
   return {
@@ -181,10 +189,12 @@ export function buildGsdHomeModel(
         label: "Fix or recover",
         description: blocked
           ? "Review the blocker and recovery commands for the active milestone."
+          : hasIdleResidue
+            ? "Review stranded milestone worktrees/branches and run the suggested recovery command."
           : disabled("This becomes active when closeout, validation, or state recovery is needed.", "no blocker is active"),
-        enabled: blocked,
+        enabled: blocked || hasIdleResidue,
         recommended: recommended === "fix_recover",
-        disabledReason: blocked ? undefined : "no blocker is active",
+        disabledReason: blocked || hasIdleResidue ? undefined : "no blocker is active",
       },
       {
         id: "start_configure",

package/src/resources/extensions/gsd/gsd-db.ts

@@ -246,9 +246,9 @@ export function insertMilestone(m: {
   status?: string;
   depends_on?: string[];
   planning?: Partial<MilestonePlanningRecord>;
-}): void {
+}): boolean {
   if (!getDbOrNull()!) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
-  getDbOrNull()!.prepare(
+  const result = getDbOrNull()!.prepare(
     `INSERT OR IGNORE INTO milestones (
       id, title, status, depends_on, created_at,
       vision, success_criteria, key_risks, proof_strategy,
@@ -279,7 +279,8 @@ export function insertMilestone(m: {
     ":definition_of_done": JSON.stringify(m.planning?.definitionOfDone ?? []),
     ":requirement_coverage": m.planning?.requirementCoverage ?? "",
     ":boundary_map_markdown": m.planning?.boundaryMapMarkdown ?? "",
-  });
+  }) as { changes?: number };
+  return (result.changes ?? 0) > 0;
 }
 
 export function upsertMilestonePlanning(milestoneId: string, planning: Partial<MilestonePlanningRecord> & { title?: string; status?: string; depends_on?: string[] }): void {

package/src/resources/extensions/gsd/guided-flow.ts

@@ -78,11 +78,8 @@ import {
 } from "./requirements-backlog.js";
 import { selectAndApplyModel } from "./auto-model-selection.js";
 import { DISCUSS_TOOLS_ALLOWLIST } from "./constants.js";
-import {
-  getWorkflowTransportSupportError,
-  getRequiredWorkflowToolsForGuidedUnit,
-  supportsStructuredQuestions,
-} from "./workflow-mcp.js";
+import { supportsStructuredQuestions } from "./workflow-mcp.js";
+import { getUnitWorkflowDispatchReadinessError } from "./tool-contract.js";
 import {
   runPreparation,
   formatCodebaseBrief,
@@ -555,7 +552,7 @@ interface DispatchWorkflowOptions {
   deps?: {
     loadPreferences?: typeof loadEffectiveGSDPreferences;
     selectModel?: typeof selectAndApplyModel;
-    getTransportSupportError?: typeof getWorkflowTransportSupportError;
+    getDispatchReadinessError?: typeof getUnitWorkflowDispatchReadinessError;
   };
 }
 
@@ -584,7 +581,8 @@ async function dispatchWorkflow(
   const projectRoot = resolveGuidedDispatchProjectRoot(resolvedOptions.basePath);
   const loadPreferences = resolvedOptions.deps?.loadPreferences ?? loadEffectiveGSDPreferences;
   const selectModel = resolvedOptions.deps?.selectModel ?? selectAndApplyModel;
-  const getTransportSupportError = resolvedOptions.deps?.getTransportSupportError ?? getWorkflowTransportSupportError;
+  const getDispatchReadinessError = resolvedOptions.deps?.getDispatchReadinessError
+    ?? getUnitWorkflowDispatchReadinessError;
 
   // Route through the dynamic routing pipeline (complexity classification,
   // tier downgrade, fallback chains) — same path as auto-mode dispatches (#2958).
@@ -603,25 +601,22 @@ async function dispatchWorkflow(
       });
     }
 
-    const compatibilityError = getTransportSupportError(
-      result.appliedModel?.provider ?? ctx.model?.provider,
-      getRequiredWorkflowToolsForGuidedUnit(unitType),
-      {
-        projectRoot,
-        surface: "guided flow",
-        unitType,
-        authMode: result.appliedModel?.provider
-          ? ctx.modelRegistry.getProviderAuthMode(result.appliedModel.provider)
-          : ctx.model?.provider
-            ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider)
-            : undefined,
-        baseUrl: result.appliedModel?.baseUrl ?? ctx.model?.baseUrl,
-        // Guided flow starts the MCP workflow server as part of dispatch, so the
-        // parent session's activeTools doesn't include MCP tools yet. The MCP
-        // launch config check (detectWorkflowMcpLaunchConfig) is the right gate
-        // here — not whether MCP tools are pre-registered in the parent session.
-      },
-    );
+    const compatibilityError = getDispatchReadinessError({
+      provider: result.appliedModel?.provider ?? ctx.model?.provider,
+      projectRoot,
+      surface: "guided flow",
+      unitType,
+      authMode: result.appliedModel?.provider
+        ? ctx.modelRegistry.getProviderAuthMode(result.appliedModel.provider)
+        : ctx.model?.provider
+          ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider)
+          : undefined,
+      baseUrl: result.appliedModel?.baseUrl ?? ctx.model?.baseUrl,
+      // Guided flow starts the MCP workflow server as part of dispatch, so the
+      // parent session's activeTools doesn't include MCP tools yet. The MCP
+      // launch config check (detectWorkflowMcpLaunchConfig) is the right gate
+      // here — not whether MCP tools are pre-registered in the parent session.
+    });
     if (compatibilityError) {
       ctx.ui.notify(compatibilityError, "error");
       return;

package/src/resources/extensions/gsd/milestone-closeout.ts

@@ -5,10 +5,20 @@
 // - 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";
@@ -28,6 +38,76 @@ import {
 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: string,
+  milestoneId: string,
+): Promise<boolean> {
+  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: string,
+  milestoneId: string,
+): Promise<{ ok: true } | { ok: false; error: string }> {
+  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.
@@ -78,7 +158,22 @@ export async function evaluateCompleteMilestoneDispatch(
   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" };
+      }
     }
   }
 

package/src/resources/extensions/gsd/milestone-planning-persistence.ts

@@ -15,7 +15,7 @@ import {
 } 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";
@@ -171,7 +171,7 @@ async function renderPlanArtifacts(
 
 async function runPostPlanHooks(basePath: string, params: PersistMilestonePlanParams): Promise<void> {
   try {
-    await renderAllProjections(basePath, params.milestoneId);
+    await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
     writeManifest(basePath);
     appendEvent(basePath, {
       cmd: "plan-milestone",

package/src/resources/extensions/gsd/projection-flush.ts

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

package/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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.