@opengsd/gsd-pi 1.3.0-dev.65546769 → 1.3.0-dev.72e3af2a

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

@@ -13,6 +13,7 @@ import {
   diffWorktreeNumstat,
   getWorktreeGSDDiff,
   getWorktreeLog,
+  mergeWorktreeToMain,
   worktreeBranchName,
   worktreePath,
   pruneEphemeralGhostWorktreeDirectories,
@@ -333,6 +334,44 @@ describe("getWorktreeLog", () => {
   });
 });
 
+// ─── mergeWorktreeToMain ─────────────────────────────────────────────────────
+
+describe("mergeWorktreeToMain", () => {
+  let base: string;
+  let wtPath: string;
+
+  beforeEach(() => {
+    base = makeBaseRepo();
+    wtPath = worktreePath(base, "M900");
+    mkdirSync(join(base, ".gsd-worktrees"), { recursive: true });
+    run(`git worktree add -b milestone/M900 "${wtPath}"`, base);
+  });
+
+  afterEach(() => { rmSync(base, { recursive: true, force: true }); });
+
+  test("cleans failed milestone squash state and deletes orphan branch", () => {
+    writeFileSync(join(wtPath, "README.md"), "# Milestone change\n", "utf-8");
+    run("git add README.md", wtPath);
+    run('git commit -m "feat: milestone change"', wtPath);
+
+    writeFileSync(join(base, "README.md"), "# Main change\n", "utf-8");
+    run("git add README.md", base);
+    run('git commit -m "feat: main change"', base);
+
+    assert.throws(
+      () => mergeWorktreeToMain(base, "M900", "feat: merge M900", "milestone/M900"),
+      /Merge conflicts detected/,
+    );
+
+    assert.equal(run("git status --porcelain", base), "", "failed squash cleanup should leave main clean");
+    assert.ok(!existsSync(wtPath), "failed milestone worktree should be removed");
+    assert.ok(
+      !run("git branch", base).includes("milestone/M900"),
+      "failed milestone branch should be deleted after worktree removal",
+    );
+  });
+});
+
 // ─── removeWorktree ───────────────────────────────────────────────────────────
 
 describe("removeWorktree", () => {

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

@@ -30,7 +30,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 { flushWorkflowProjections } from "../projection-flush.js";
+import { renderMilestoneShellProjections } from "../workflow-projections.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
@@ -540,7 +540,7 @@ export async function handleCompleteSlice(
   // Separate try/catch per step so a projection failure doesn't prevent
   // the event log entry (critical for worktree reconciliation).
   try {
-    await flushWorkflowProjections(artifactBasePath, { milestoneId: params.milestoneId });
+    await renderMilestoneShellProjections(artifactBasePath, params.milestoneId);
   } catch (projErr) {
     logWarning("tool", `complete-slice projection warning for ${params.milestoneId}/${params.sliceId}: ${(projErr as Error).message}`);
   }

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

@@ -6,11 +6,12 @@
  *
  * Validates inputs, writes task row and rendered SUMMARY.md to DB in a
  * transaction, then renders projections to disk and invalidates caches.
- * Projection write failures are reported as stale projections and do not roll
- * back committed DB state.
+ * If the critical task summary / plan projection write fails, the DB
+ * completion is compensated back to pending so DB state does not drift ahead
+ * of PLAN.md.
  */
 
-import { existsSync } from "node:fs";
+import { existsSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 
 import type { CompleteTaskParams, EscalationArtifact } from "../types.js";
@@ -29,6 +30,7 @@ import {
   saveGateResult,
   getPendingGatesForTurn,
 } from "../gsd-db.js";
+import { getWorkflowDatabasePath, ensureWorkflowDbAtPath } from "../db-workspace.js";
 import { getGatesForTurn } from "../gate-registry.js";
 import { gsdProjectionRoot, clearPathCache, resolveMilestonePath, resolveSlicePath } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
@@ -36,8 +38,10 @@ 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 { renderSummaryContent } from "../workflow-projections.js";
-import { flushWorkflowProjections } from "../projection-flush.js";
+import {
+  renderMilestoneShellProjections,
+  renderSummaryContent,
+} from "../workflow-projections.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
@@ -131,7 +135,7 @@ async function repairMissingTaskSummaryProjection(
   clearParseCache();
 
   try {
-    await flushWorkflowProjections(artifactBasePath, { milestoneId: taskRow.milestone_id });
+    await renderMilestoneShellProjections(artifactBasePath, taskRow.milestone_id);
   } catch (projErr) {
     logWarning("tool", `complete-task repair projection warning: ${(projErr as Error).message}`);
   }
@@ -267,6 +271,7 @@ export async function handleCompleteTask(
   let guardError: string | null = null;
   let summaryMd = "";
   let repairTaskSummaryRow: TaskRow | null = null;
+  const rollbackDbPath = getWorkflowDatabasePath();
 
   // ── ADR-011 Phase 2: validate escalation payload BEFORE any side effects ─
   // Building the artifact runs the full shape validation (2-4 options, unique
@@ -423,8 +428,6 @@ export async function handleCompleteTask(
     return { error: guardError };
   }
 
-  let projectionStale = false;
-
   // Resolve and write summary to disk
   const summaryPath = taskSummaryPath(
     artifactBasePath,
@@ -438,12 +441,48 @@ export async function handleCompleteTask(
 
     // Toggle or regenerate the plan projection from DB. Missing projection
     // files are rebuilt by the renderer instead of being skipped.
-    await renderPlanCheckboxes(artifactBasePath, params.milestoneId, params.sliceId);
+    if (!ensureWorkflowDbAtPath(rollbackDbPath)) {
+      throw new Error(`database unavailable before plan projection render for ${params.milestoneId}/${params.sliceId}`);
+    }
+    const wrotePlan = await renderPlanCheckboxes(artifactBasePath, params.milestoneId, params.sliceId);
+    if (!wrotePlan) {
+      throw new Error(`plan projection write returned false for ${params.milestoneId}/${params.sliceId}`);
+    }
   } catch (renderErr) {
-    projectionStale = true;
-    logWarning("projection", `complete_task projection write failed for ${params.milestoneId}/${params.sliceId}/${params.taskId}; DB completion remains committed`, {
-      error: (renderErr as Error).message,
-    });
+    logWarning(
+      "projection",
+      `complete_task projection write failed for ${params.milestoneId}/${params.sliceId}/${params.taskId}`,
+      { error: (renderErr as Error).message },
+    );
+    let rollbackSucceeded = false;
+    try {
+      ensureWorkflowDbAtPath(rollbackDbPath);
+      deleteVerificationEvidence(params.milestoneId, params.sliceId, params.taskId);
+      updateTaskStatus(params.milestoneId, params.sliceId, params.taskId, "pending");
+      invalidateStateCache();
+      rollbackSucceeded = true;
+    } catch (rollbackErr) {
+      logWarning(
+        "projection",
+        `complete_task rollback failed after projection write failure for ${params.milestoneId}/${params.sliceId}/${params.taskId}: ${(rollbackErr as Error).message}`,
+      );
+    }
+    try {
+      if (existsSync(summaryPath)) unlinkSync(summaryPath);
+    } catch (summaryErr) {
+      logWarning(
+        "projection",
+        `complete_task could not remove SUMMARY.md after projection write failure for ${params.milestoneId}/${params.sliceId}/${params.taskId}: ${(summaryErr as Error).message}`,
+      );
+    }
+    // Clear path/parse caches regardless of rollback outcome so stale
+    // entries from the failed write attempt don't leak into subsequent calls.
+    clearPathCache();
+    clearParseCache();
+    const returnMsg = rollbackSucceeded
+      ? `complete_task projection write failed for ${params.milestoneId}/${params.sliceId}/${params.taskId}; rolled completion back to pending`
+      : `complete_task projection write failed for ${params.milestoneId}/${params.sliceId}/${params.taskId}; rollback also failed — task may remain complete with stale plan`;
+    return { error: returnMsg };
   }
 
   // ── Close gates owned by execute-task (Q5/Q6/Q7) for this task ────────
@@ -569,7 +608,7 @@ export async function handleCompleteTask(
   // Separate try/catch per step so a projection failure doesn't prevent
   // the event log entry (critical for worktree reconciliation).
   try {
-    await flushWorkflowProjections(artifactBasePath, { milestoneId: params.milestoneId });
+    await renderMilestoneShellProjections(artifactBasePath, params.milestoneId);
   } catch (projErr) {
     logWarning("tool", `complete-task projection warning: ${(projErr as Error).message}`);
   }
@@ -597,6 +636,5 @@ export async function handleCompleteTask(
     milestoneId: params.milestoneId,
     summaryPath,
     ...(escalationMetadata ? { escalation: escalationMetadata } : {}),
-    ...(projectionStale ? { stale: true } : {}),
   };
 }

package/src/resources/extensions/gsd/tools/exec-tool.ts

@@ -31,6 +31,7 @@ export interface ExecToolDeps {
   env?: NodeJS.ProcessEnv;
   now?: () => Date;
   generateId?: () => string;
+  signal?: AbortSignal;
 }
 
 export type UatExecIntent =
@@ -74,7 +75,7 @@ const UAT_EXEC_INTENT_ALIASES: Record<string, UatExecIntent> = {
 export function buildExecOptions(
   baseDir: string,
   cfg: ContextModeConfig | undefined,
-  extras?: Pick<ExecSandboxOptions, "env" | "now" | "generateId">,
+  extras?: Pick<ExecSandboxOptions, "env" | "now" | "generateId" | "signal">,
 ): ExecSandboxOptions {
   const allowlist = Array.isArray(cfg?.exec_env_allowlist) ? cfg!.exec_env_allowlist! : EXEC_DEFAULTS.envAllowlist;
   const stdoutCap = clampNumber(
@@ -209,7 +210,7 @@ export async function executeGsdExec(
   const opts = buildExecOptions(
     deps.baseDir,
     deps.preferences?.context_mode,
-    { env: deps.env, now: deps.now, generateId: deps.generateId },
+    { env: deps.env, now: deps.now, generateId: deps.generateId, signal: deps.signal },
   );
   const run = deps.run ?? runExecSandbox;
 
@@ -308,6 +309,7 @@ function formatResult(result: ExecSandboxResult): ToolExecutionResult {
       exit_code: result.exit_code,
       signal: result.signal,
       timed_out: result.timed_out,
+      aborted: result.aborted === true,
       force_resolved: result.force_resolved,
       duration_ms: result.duration_ms,
       stdout_bytes: result.stdout_bytes,
@@ -318,13 +320,15 @@ function formatResult(result: ExecSandboxResult): ToolExecutionResult {
       stderr_path: result.stderr_path,
       meta_path: result.meta_path,
     },
-    isError: result.timed_out || result.signal !== null || result.exit_code !== 0,
+    isError: result.aborted === true || result.timed_out || result.signal !== null || result.exit_code !== 0,
   };
 }
 
 function formatExit(result: ExecSandboxResult): string {
   // force_resolved means a non-closing (D-state) child was force-resolved past its
   // hard deadline rather than observed exiting; distinguish it from a clean timeout.
+  if (result.aborted && result.force_resolved) return "aborted(force-killed)";
+  if (result.aborted) return "aborted";
   if (result.force_resolved) return "timeout(force-killed)";
   if (result.timed_out) return "timeout";
   if (result.signal) return `signal:${result.signal}`;

package/src/resources/extensions/gsd/unit-context-composer.ts

@@ -135,14 +135,38 @@ const CONTEXT_MODE_GUIDANCE_BY_LANE: Record<Exclude<ContextModePolicy, "none">,
     "Use `gsd_resume` for prior context, `gsd_exec_search` for saved evidence, and `gsd_exec` for noisy doc validation commands.",
 };
 
-// Per-unit overrides win over the lane default. run-uat's tool contract
-// forbids `gsd_exec`/`gsd_exec_search` (acceptance evidence must flow through
-// `gsd_uat_exec`) and Claude Code dispatch strips the tools entirely, so the
-// shared verification-lane guidance would steer the agent into calling an
-// unavailable tool.
-const CONTEXT_MODE_GUIDANCE_BY_UNIT: Record<string, string> = {
+// Per-unit overrides win over the lane default. Some units intentionally run
+// with narrower tool contracts than their shared Context Mode lane, so their
+// guidance must name only tools the unit can actually call.
+export const CONTEXT_MODE_GUIDANCE_BY_UNIT: Readonly<Record<string, string>> = {
+  "discuss-milestone":
+    "Use `ask_user_questions` to continue the milestone interview, then persist outcomes with `gsd_summary_save`, `gsd_decision_save`, `gsd_requirement_save`, `gsd_requirement_update`, `gsd_plan_milestone`, or `gsd_milestone_generate_id` as appropriate.",
+  "discuss-slice":
+    "Use `ask_user_questions` to continue the slice interview, then persist outcomes with `gsd_summary_save` or `gsd_decision_save` as appropriate.",
+  "discuss-project":
+    "Use `ask_user_questions` to continue the project interview, then persist outcomes with `gsd_summary_save`, `gsd_decision_save`, or `gsd_requirement_save` as appropriate.",
+  "discuss-requirements":
+    "Use `ask_user_questions` to continue the requirements interview, then persist outcomes with `gsd_requirement_save` or `gsd_summary_save` as appropriate.",
+  "replan-slice":
+    "Use `gsd_replan_slice` to persist the revised slice plan, and `gsd_decision_save` for planning decisions that need durable rationale.",
+  "reassess-roadmap":
+    "Use `gsd_milestone_status` to inspect current milestone state, then `gsd_reassess_roadmap` to persist the roadmap reassessment.",
   "run-uat":
     "Use `gsd_uat_exec` for acceptance checks so evidence is typed as UAT-owned, and `gsd_resume` after compaction or resume.",
+  "research-project":
+    "Dispatch parallel scout subagents for stack, features, architecture, and pitfalls research; each writes one file under `.gsd/research/` (`STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md`).",
+  "gate-evaluate":
+    "Use `subagent` to dispatch tester agents, then persist each gate with `gsd_save_gate_result`; rely on testers for verification evidence.",
+};
+
+// Per-unit guidance for the nested render mode (renderMode: "nested"), used when this
+// unit's Context Mode line is embedded into a subagent prompt — e.g. the tester prompts
+// dispatched by gate-evaluate. Must instruct the subagent on what IT should do, not
+// re-state the parent coordinator's dispatch instructions. Falls back to
+// CONTEXT_MODE_GUIDANCE_BY_UNIT then the lane default when no nested entry exists.
+export const CONTEXT_MODE_NESTED_GUIDANCE_BY_UNIT: Readonly<Record<string, string>> = {
+  "gate-evaluate":
+    "Run verification checks to answer the gate question, then persist the verdict with `gsd_save_gate_result`.",
 };
 
 /**
@@ -160,7 +184,9 @@ export function composeContextModeInstructions(
 
   const lane = CONTEXT_MODE_LANE_LABELS[manifest.contextMode];
   const guidance =
-    CONTEXT_MODE_GUIDANCE_BY_UNIT[unitType] ?? CONTEXT_MODE_GUIDANCE_BY_LANE[manifest.contextMode];
+    (opts.renderMode === "nested" ? CONTEXT_MODE_NESTED_GUIDANCE_BY_UNIT[unitType] : undefined)
+    ?? CONTEXT_MODE_GUIDANCE_BY_UNIT[unitType]
+    ?? CONTEXT_MODE_GUIDANCE_BY_LANE[manifest.contextMode];
   if (opts.renderMode === "nested") {
     return `Context Mode (${lane} lane): ${guidance}`;
   }

package/src/resources/extensions/gsd/unit-registry.ts

@@ -98,7 +98,13 @@ export const UNIT_REGISTRY = {
     scopeClass: "standard",
     phaseChain: ["research"],
     toolContract: {
-      allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+      allowedGsdTools: [
+        "gsd_summary_save",
+        "gsd_decision_save",
+        "gsd_exec",
+        "gsd_exec_search",
+        "gsd_resume",
+      ],
       requiredWorkflowTools: ["gsd_summary_save"],
     },
   },
@@ -154,7 +160,15 @@ export const UNIT_REGISTRY = {
     scopeClass: "section-close",
     phaseChain: ["validation", "planning"],
     toolContract: {
-      allowedGsdTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap", "subagent"],
+      allowedGsdTools: [
+        "gsd_milestone_status",
+        "gsd_exec",
+        "gsd_exec_search",
+        "gsd_resume",
+        "gsd_validate_milestone",
+        "gsd_reassess_roadmap",
+        "subagent",
+      ],
       requiredWorkflowTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap"],
     },
   },
@@ -165,6 +179,9 @@ export const UNIT_REGISTRY = {
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
+        "gsd_exec",
+        "gsd_exec_search",
+        "gsd_resume",
         "gsd_requirement_update",
         "gsd_summary_save",
         "gsd_complete_milestone",
@@ -244,6 +261,8 @@ export const UNIT_REGISTRY = {
       allowedGsdTools: [
         "gsd_milestone_status",
         "gsd_exec",
+        "gsd_exec_search",
+        "gsd_resume",
         "gsd_slice_complete",
         "gsd_task_reopen",
         "gsd_replan_slice",
@@ -326,7 +345,13 @@ export const UNIT_REGISTRY = {
     scopeClass: "execute-task",
     phaseChain: ["execution"],
     toolContract: {
-      allowedGsdTools: ["gsd_task_complete", "gsd_summary_save", "gsd_decision_save"],
+      allowedGsdTools: [
+        "gsd_milestone_status",
+        "gsd_task_complete",
+        "gsd_exec",
+        "gsd_summary_save",
+        "gsd_decision_save",
+      ],
       requiredWorkflowTools: ["gsd_task_complete", "gsd_summary_save"],
     },
   },
@@ -413,12 +438,15 @@ export const UNIT_REGISTRY = {
       requiredWorkflowTools: ["ask_user_questions"],
     },
   },
+  // research-project dispatches 4 parallel scout subagents (Task calls); each scout
+  // writes one file under .gsd/research/ directly. The parent coordinator does not
+  // call gsd_summary_save or gsd_decision_save — the scouts own their own output.
   "research-project": {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["research"],
     toolContract: {
-      allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+      allowedGsdTools: [],
       requiredWorkflowTools: [],
     },
   },

package/src/resources/extensions/gsd/unmerged-milestone-guard.ts

@@ -1,6 +1,8 @@
 // Project/App: gsd-pi
 // File Purpose: Block new workflow entry when completed milestone branches are still unmerged.
 
+import { execFileSync } from "node:child_process";
+
 import {
   nativeBranchExists,
   nativeDetectMainBranch,
@@ -12,17 +14,23 @@ import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import { getAllMilestones } from "./gsd-db.js";
 import { resolveMilestoneIntegrationBranch } from "./git-service.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { captureRootDirtySnapshot, type RootDirtyEntry } from "./root-write-leak-guard.js";
 import { isClosedStatus } from "./status-guards.js";
 
+export interface UnmergedMilestoneDirtyEntry {
+  path: string;
+  status: string;
+}
+
 export interface UnmergedMilestoneBlocker {
   milestoneId: string;
   branch: string;
   integrationBranch: string;
   files: string[];
-  dirtyOverlap: RootDirtyEntry[];
+  dirtyOverlap: UnmergedMilestoneDirtyEntry[];
 }
 
+type UnmergedMilestoneDirtySnapshot = Map<string, UnmergedMilestoneDirtyEntry>;
+
 const BLOCKED_COMMANDS = new Set([
   "auto",
   "next",
@@ -67,6 +75,32 @@ function isRuntimePath(path: string): boolean {
   return path === ".gsd" || path.startsWith(".gsd/");
 }
 
+function captureDirtyPathStatusSnapshot(rootPath: string): UnmergedMilestoneDirtySnapshot {
+  const snapshot: UnmergedMilestoneDirtySnapshot = new Map();
+  let status = "";
+  try {
+    status = execFileSync("git", ["status", "--porcelain", "--untracked-files=all"], {
+      cwd: rootPath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    });
+  } catch {
+    return snapshot;
+  }
+
+  for (const line of status.split("\n")) {
+    if (!line.trim()) continue;
+    const code = line.slice(0, 2);
+    const path = line.slice(3).replace(/^"|"$/g, "");
+    if (!path || isRuntimePath(path)) continue;
+    snapshot.set(path, {
+      path,
+      status: code.trim() || code,
+    });
+  }
+  return snapshot;
+}
+
 function formatCommandLabel(attemptedCommand: string): string {
   const trimmed = attemptedCommand.trim();
   return trimmed ? `/gsd ${trimmed}` : "/gsd";
@@ -132,7 +166,7 @@ export async function findUnmergedCompletedMilestones(base: string): Promise<Unm
   await ensureDbOpen(base);
 
   const blockers: UnmergedMilestoneBlocker[] = [];
-  const dirtyByPath = captureRootDirtySnapshot(base);
+  let dirtyByPath: UnmergedMilestoneDirtySnapshot | null = null;
 
   for (const milestone of getAllMilestones()) {
     if (!isClosedStatus(milestone.status)) continue;
@@ -158,14 +192,16 @@ export async function findUnmergedCompletedMilestones(base: string): Promise<Unm
     const uniqueFiles = [...new Set(files)].sort();
     if (uniqueFiles.length === 0) continue;
 
+    if (!dirtyByPath) dirtyByPath = captureDirtyPathStatusSnapshot(base);
+    const dirtySnapshot = dirtyByPath;
     blockers.push({
       milestoneId: milestone.id,
       branch,
       integrationBranch,
       files: uniqueFiles,
       dirtyOverlap: uniqueFiles
-        .map((path) => dirtyByPath.get(path))
-        .filter((entry): entry is RootDirtyEntry => Boolean(entry)),
+        .map((path) => dirtySnapshot.get(path))
+        .filter((entry): entry is UnmergedMilestoneDirtyEntry => Boolean(entry)),
     });
   }
 

package/src/resources/extensions/gsd/validation-block-guard.ts

@@ -7,7 +7,7 @@ import { getAutoWorktreePath, isInAutoWorktree } from "./auto-worktree.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import { refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 import { getIsolationMode } from "./preferences.js";
-import { deriveState } from "./state.js";
+import { deriveState, invalidateStateCache } from "./state.js";
 import type { GSDState } from "./types.js";
 import { detectWorktreeName } from "./worktree.js";
 
@@ -133,12 +133,7 @@ export function formatValidationBlockedMessage(
   ].join("\n\n");
 }
 
-export async function getValidationBlockMessageForBase(
-  base: string,
-  attemptedCommand = "",
-): Promise<string | null> {
-  await ensureDbOpen(base);
-  refreshWorkflowDatabaseFromDisk();
+async function deriveValidationBlockState(base: string): Promise<GSDState> {
   let state = await deriveState(base);
 
   if (
@@ -153,5 +148,16 @@ export async function getValidationBlockMessageForBase(
     }
   }
 
+  return state;
+}
+
+export async function getValidationBlockMessageForBase(
+  base: string,
+  attemptedCommand = "",
+): Promise<string | null> {
+  await ensureDbOpen(base);
+  refreshWorkflowDatabaseFromDisk();
+  invalidateStateCache();
+  const state = await deriveValidationBlockState(base);
   return formatValidationBlockedMessage(state, attemptedCommand);
 }

package/src/resources/extensions/gsd/workflow-projections.ts

@@ -451,16 +451,14 @@ export async function renderStateProjection(basePath: string): Promise<void> {
   }
 }
 
-// ─── renderAllProjections ───────────────────────────────────────────────
+// ─── renderMilestoneShellProjections ─────────────────────────────────────
 
 /**
- * Regenerate all projection files for a milestone from DB state.
- * All calls are wrapped in try/catch — projection failure is non-fatal per D-02.
+ * Regenerate milestone-level projections (roadmap, top-level views, STATE.md).
+ * Does not touch slice PLAN.md or task SUMMARY.md — those have authoritative
+ * renderers in plan-slice / complete-task.
  */
-export async function renderAllProjections(basePath: string, milestoneId: string): Promise<void> {
-  // Delegate to the authoritative roadmap renderer — the reduced
-  // renderRoadmapProjection omits sections like ## Boundary Map and would
-  // clobber the output written by plan-milestone / reassess-roadmap.
+export async function renderMilestoneShellProjections(basePath: string, milestoneId: string): Promise<void> {
   try {
     await renderRoadmapFromDb(basePath, milestoneId);
   } catch (err) {
@@ -476,6 +474,21 @@ export async function renderAllProjections(basePath: string, milestoneId: string
   } catch (err) {
     logWarning("projection", `renderTopLevelQueueFromDb failed: ${(err as Error).message}`);
   }
+  try {
+    await renderStateProjection(basePath);
+  } catch (err) {
+    logWarning("projection", `renderStateProjection failed: ${(err as Error).message}`);
+  }
+}
+
+// ─── renderAllProjections ───────────────────────────────────────────────
+
+/**
+ * Regenerate all projection files for a milestone from DB state.
+ * All calls are wrapped in try/catch — projection failure is non-fatal per D-02.
+ */
+export async function renderAllProjections(basePath: string, milestoneId: string): Promise<void> {
+  await renderMilestoneShellProjections(basePath, milestoneId);
 
   // Query all slices for this milestone
   const sliceRows = getMilestoneSlices(milestoneId);
@@ -498,13 +511,6 @@ export async function renderAllProjections(basePath: string, milestoneId: string
       }
     }
   }
-
-  // Render STATE.md
-  try {
-    await renderStateProjection(basePath);
-  } catch (err) {
-    logWarning("projection", `renderStateProjection failed: ${(err as Error).message}`);
-  }
 }
 
 // ─── regenerateIfMissing ────────────────────────────────────────────────

package/src/resources/extensions/gsd/workspace-git-preflight.ts

@@ -7,6 +7,7 @@ import { getAutoWorktreePath } from "./auto-worktree.js";
 import { isSafeToAutoResolve } from "./auto-worktree.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import {
+  listMergeStateBlockers,
   probeGitConflictState,
   reconcileGitConflictsOnSignal,
   type GitConflictProbeResult,
@@ -30,6 +31,9 @@ export type WorkspaceGitReadyResult =
       targets: string[];
     };
 
+const CLEAN_TARGET_CACHE_TTL_MS = 10_000;
+const cleanTargetProbeCache = new Map<string, number>();
+
 function normalizeTargetPath(path: string): string {
   try {
     return realpathSync(path);
@@ -110,6 +114,25 @@ function formatBlockReason(
 
 async function ensureTargetGitReady(target: string): Promise<WorkspaceGitReadyResult> {
   const fixesApplied: string[] = [];
+  const cacheKey = normalizeTargetPath(target);
+  const cachedCleanAt = cleanTargetProbeCache.get(cacheKey);
+  if (cachedCleanAt !== undefined) {
+    if (Date.now() - cachedCleanAt < CLEAN_TARGET_CACHE_TTL_MS) {
+      // Merge-state markers (MERGE_HEAD, rebase-apply, rebase-merge) are the most
+      // common way a repo transitions from clean to dirty within the TTL window,
+      // including when a non-git folder is initialized as a repo mid-TTL and a
+      // merge immediately introduces conflicts. Check them here — they are pure
+      // existsSync calls with no git subprocess — and fall through to a full probe
+      // only when markers are present.
+      if (listMergeStateBlockers(cacheKey).length === 0) {
+        return { ok: true, fixesApplied };
+      }
+      cleanTargetProbeCache.delete(cacheKey);
+    } else {
+      cleanTargetProbeCache.delete(cacheKey);
+    }
+  }
+
   let probe = probeGitConflictState(target);
 
   for (let attempt = 0; attempt < 3 && probe.status === "dirty"; attempt++) {
@@ -129,6 +152,7 @@ async function ensureTargetGitReady(target: string): Promise<WorkspaceGitReadyRe
   }
 
   if (probe.status === "unknown") {
+    cleanTargetProbeCache.delete(cacheKey);
     return {
       ok: false,
       reason: formatBlockReason("unrecoverable", [], [target]),
@@ -141,6 +165,7 @@ async function ensureTargetGitReady(target: string): Promise<WorkspaceGitReadyRe
 
   const conflictedPaths = productConflictPaths(probe);
   if (conflictedPaths.length > 0 || probe.checkFailures.length > 0) {
+    cleanTargetProbeCache.delete(cacheKey);
     return {
       ok: false,
       reason: formatBlockReason("product-conflicts", conflictedPaths, [target]),
@@ -151,6 +176,12 @@ async function ensureTargetGitReady(target: string): Promise<WorkspaceGitReadyRe
     };
   }
 
+  if (probe.status === "clean") {
+    cleanTargetProbeCache.set(cacheKey, Date.now());
+  } else {
+    cleanTargetProbeCache.delete(cacheKey);
+  }
+
   return { ok: true, fixesApplied };
 }