@opengsd/gsd-pi 1.3.0 → 1.4.0

package/src/resources/extensions/gsd/bootstrap/tool-call-loop-guard.ts

@@ -1,18 +1,30 @@
 /**
  * Tool-call loop guard.
  *
- * Detects when a model calls the same tool with identical arguments
- * repeatedly within a single agent turn. Works in both auto-mode and
- * interactive sessions by hooking into the `tool_call` event, which
- * fires before execution and can block the call.
+ * Detects when a model repeats tool calls within a single Agent Turn.
+ * Works in both auto-mode and interactive sessions by hooking into the
+ * native engine's `tool_call` event, which fires before execution and can
+ * block the call.
  *
- * The guard uses a sliding window: it tracks the last N tool signatures
- * and blocks when the same signature appears more than MAX_CONSECUTIVE
- * times in a row. Resets on each agent turn (session_start, agent_end)
- * and when a different tool call breaks the streak.
+ * The guard has two independent checks: a sliding window for identical
+ * tool signatures, and a per-tool-name cap for repeated calls with varied
+ * arguments. State resets at Agent Turn boundaries (session_start,
+ * agent_end) and the identical-signature streak also resets when a
+ * different tool call breaks the streak. Block messages instruct the model
+ * to stop tooling for the rest of that turn and answer in text.
+ *
+ * The per-tool-name check (#783 Brief C) tracks call counts within a
+ * turn regardless of args, decaying after successful state-mutating tools.
+ * This catches improvisation
+ * loops where the model attempts the same missing workflow tool through
+ * varied surfaces (bash → `node -e` → CLI), each with a different
+ * signature, so the identical-args streak never trips, while allowing
+ * tool-heavy turns that are making file-mutation progress. Whichever guard
+ * trips first blocks.
  */
 
 import { createHash } from "node:crypto";
+import { INHERENTLY_REPEATABLE_TOOL_SET } from "./core-session-tools.js";
 
 const MAX_CONSECUTIVE_IDENTICAL_CALLS = 4;
 
@@ -20,11 +32,31 @@ const MAX_CONSECUTIVE_IDENTICAL_CALLS = 4;
 const STRICT_LOOP_TOOLS = new Set(["ask_user_questions"]);
 const MAX_CONSECUTIVE_STRICT = 1;
 
+/**
+ * Per-turn cap on calls to the SAME tool name, regardless of args (#783).
+ *
+ * General-purpose execution tools are routinely called many times per turn
+ * (touching multiple files, running several commands), so they get a higher
+ * ceiling. Everything else — workflow one-shot tools (e.g. gsd_complete_milestone)
+ * and any non-allowlisted tool — gets the default cap. The default is generous
+ * enough to absorb legitimate retries but catches the reported improvisation
+ * loop (~51 calls) well before a cost spike.
+ */
+const PER_TOOL_DEFAULT_CAP = 6;
+const PER_TOOL_REPEATABLE_CAP = 15;
+const PER_TOOL_CAP_EXEMPT_TOOLS = new Set(["find", "glob", "grep", "ls", "read", "search_and_read"]);
+const STATE_MUTATING_TOOL_SET = new Set(["edit", "write", "multi_edit", "notebook_edit"]);
+
 let consecutiveCount = 0;
 let lastSignature = "";
 let lastToolName = "";
 let enabled = true;
 
+/** Per-tool-name call counts within the current turn (#783 Brief C). */
+const perToolCounts = new Map<string, number>();
+let mutationEpoch = 0;
+const perToolLastMutationEpoch = new Map<string, number>();
+
 /** Hash tool name + args into a compact signature for comparison. */
 function hashToolCall(toolName: string, args: Record<string, unknown>): string {
   const h = createHash("sha256");
@@ -46,6 +78,13 @@ function hashToolCall(toolName: string, args: Record<string, unknown>): string {
  *
  * Returns `{ block: false }` for allowed calls.
  * Returns `{ block: true, reason }` when the loop threshold is exceeded.
+ *
+ * Two independent guards run; whichever trips first blocks:
+ *  1. Identical-signature streak (MAX_CONSECUTIVE_IDENTICAL_CALLS, strict for
+ *     ask_user_questions).
+ *  2. Per-tool-name cap (PER_TOOL_DEFAULT_CAP / PER_TOOL_REPEATABLE_CAP),
+ *     independent of args, reset after file-mutation progress — catches
+ *     improvisation loops (#783).
  */
 export function checkToolCallLoop(
   toolName: string,
@@ -63,6 +102,7 @@ export function checkToolCallLoop(
     lastToolName = toolName;
   }
 
+  // ── Guard 1: identical-signature streak ──
   const threshold = STRICT_LOOP_TOOLS.has(toolName)
     ? MAX_CONSECUTIVE_STRICT
     : MAX_CONSECUTIVE_IDENTICAL_CALLS;
@@ -71,22 +111,65 @@ export function checkToolCallLoop(
     return {
       block: true,
       reason:
-        `Tool loop detected: ${toolName} called ${consecutiveCount} times ` +
+        `Tool loop detected (identical args): ${toolName} called ${consecutiveCount} times ` +
         `with identical arguments. Blocking to prevent infinite loop. ` +
-        `Try a different approach or modify your arguments.`,
+        `Do not retry this tool or call other tools this turn — stop and respond to the user in text.`,
       count: consecutiveCount,
     };
   }
 
+  // ── Guard 2: per-tool-name cap, independent of args (#783 Brief C) ──
+  // Catches improvisation loops where the same tool is invoked many times with
+  // varied args (e.g. retrying a missing workflow tool via bash/node -e/CLI).
+  const priorPerToolCount =
+    (perToolLastMutationEpoch.get(toolName) ?? mutationEpoch) < mutationEpoch
+      ? 0
+      : (perToolCounts.get(toolName) ?? 0);
+  const perToolCount = priorPerToolCount + 1;
+  perToolCounts.set(toolName, perToolCount);
+  perToolLastMutationEpoch.set(toolName, mutationEpoch);
+
+  // Read-only navigation tools are normal context gathering; Guard 1 still
+  // catches true reread loops with identical arguments.
+  if (PER_TOOL_CAP_EXEMPT_TOOLS.has(toolName)) {
+    return { block: false, count: consecutiveCount };
+  }
+
+  const perToolCap = INHERENTLY_REPEATABLE_TOOL_SET.has(toolName)
+    ? PER_TOOL_REPEATABLE_CAP
+    : PER_TOOL_DEFAULT_CAP;
+
+  if (perToolCount > perToolCap) {
+    return {
+      block: true,
+      reason:
+        `Tool loop detected (repeated tool): ${toolName} called ${perToolCount} times ` +
+        `this turn (cap ${perToolCap}). Blocking to prevent infinite loop. ` +
+        `The tool may be unavailable or failing repeatedly. ` +
+        `Do not retry this tool or pivot to other tools this turn — stop and respond to the user in text.`,
+      count: perToolCount,
+    };
+  }
+
   return { block: false, count: consecutiveCount };
 }
 
+/** Record successful mutation progress so Guard 2 can decay on the next count. */
+export function recordToolCallLoopMutation(toolName: string): void {
+  if (!enabled) return;
+  if (!STATE_MUTATING_TOOL_SET.has(toolName)) return;
+  mutationEpoch++;
+}
+
 /** Reset the guard state. Call at agent turn boundaries. */
 export function resetToolCallLoopGuard(): void {
   consecutiveCount = 0;
   lastSignature = "";
   lastToolName = "";
   enabled = true;
+  perToolCounts.clear();
+  mutationEpoch = 0;
+  perToolLastMutationEpoch.clear();
 }
 
 /** Disable the guard (e.g. during shutdown). */
@@ -95,9 +178,20 @@ export function disableToolCallLoopGuard(): void {
   consecutiveCount = 0;
   lastSignature = "";
   lastToolName = "";
+  perToolCounts.clear();
+  mutationEpoch = 0;
+  perToolLastMutationEpoch.clear();
 }
 
 /** Get current consecutive count for diagnostics. */
 export function getToolCallLoopCount(): number {
   return consecutiveCount;
 }
+
+/**
+ * Get the per-tool-name call count for the current turn (#783 Brief C).
+ * Returns 0 for tools not yet called. Diagnostic only.
+ */
+export function getToolCallCountForTool(toolName: string): number {
+  return perToolCounts.get(toolName) ?? 0;
+}

package/src/resources/extensions/gsd/bootstrap/tool-search-shim.ts

@@ -31,8 +31,26 @@ export function registerToolSearchShim(pi: ExtensionAPI): void {
 		},
 	});
 
-	const active = pi.getActiveTools();
-	if (!active.includes("ToolSearch")) {
-		pi.setActiveTools([...active, "ToolSearch"]);
+	// Ensure the shim is part of the active tool set. registerTool() is valid
+	// during extension loading, but getActiveTools()/setActiveTools() are stubs
+	// that throw "Extension runtime not initialized" until runner.bindCore() runs
+	// (after all registerExtension() calls return). When the throw was hit, the
+	// catch in register-extension.ts swallowed it — leaving the whole bootstrap
+	// partially failed and, under Claude Code CLI, the workflow tools could end
+	// up missing from the model's surface, which traps plan-milestone in a
+	// finalize-retry loop with no gsd_plan_milestone available.
+	//
+	// The activation here is also redundant post-bind: ToolSearch is in
+	// MINIMAL_AUTO_BASE_TOOL_NAMES, so buildMinimalAutoGsdToolSet adds it during
+	// adjust_tool_set (before_agent_start). Tolerate the loading-stub throw so
+	// the shim always registers; activation is completed by post-bind scoping.
+	try {
+		const active = pi.getActiveTools();
+		if (!active.includes("ToolSearch")) {
+			pi.setActiveTools([...active, "ToolSearch"]);
+		}
+	} catch {
+		// Pre-bind runtime: getActiveTools/setActiveTools are not yet wired.
+		// The tool is registered; activation happens at adjust_tool_set.
 	}
 }

package/src/resources/extensions/gsd/bootstrap/write-gate.ts

@@ -25,6 +25,12 @@ export const MILESTONE_CONTEXT_RE = /M\d+(?:-[a-z0-9]{6})?-CONTEXT\.md$/;
 const CONTEXT_MILESTONE_RE = /(?:^|[/\\])(M\d+(?:-[a-z0-9]{6})?)-CONTEXT\.md$/i;
 const DEPTH_VERIFICATION_MILESTONE_RE = /depth_verification[_-](M\d+(?:-[a-z0-9]{6})?)/i;
 
+function normalizeMilestoneId(milestoneId: string): string {
+  const match = milestoneId.match(/^(M)(\d+)(?:-([a-z0-9]{6}))?$/i);
+  if (!match) return milestoneId;
+  return `M${match[2]}${match[3] ? `-${match[3].toLowerCase()}` : ""}`;
+}
+
 /**
  * Path segment that identifies .gsd/ planning artifacts.
  * Writes to these paths are allowed during queue mode.
@@ -91,8 +97,19 @@ function createEmptyWriteGateState(): InMemoryWriteGateState {
 
 const writeGateStatesByBasePath = new Map<string, InMemoryWriteGateState>();
 
+/**
+ * Write-gate snapshots are project-scoped, not worktree-scoped. When auto-mode
+ * routes MCP tool writes to `.gsd-worktrees/<MID>/`, depth verification still
+ * lands in the authoritative project `.gsd/runtime/` tree (or external-state
+ * symlink target). Without this canonicalization, `loadWriteGateSnapshot(worktree)`
+ * sees an empty snapshot and CONTEXT saves loop forever (#M020 gate loop).
+ */
+function resolveWriteGateSnapshotRoot(basePath: string): string {
+  return resolve(resolveWorktreeProjectRoot(basePath));
+}
+
 function writeGateStateKey(basePath: string): string {
-  return resolve(basePath);
+  return resolveWriteGateSnapshotRoot(basePath);
 }
 
 function getWriteGateState(basePath: string = process.cwd()): InMemoryWriteGateState {
@@ -155,17 +172,18 @@ function shouldPersistWriteGateSnapshot(env: NodeJS.ProcessEnv = process.env): b
 }
 
 function writeGateSnapshotPath(basePath: string): string {
-  return join(basePath, ".gsd", "runtime", "write-gate-state.json");
+  return join(resolveWriteGateSnapshotRoot(basePath), ".gsd", "runtime", "write-gate-state.json");
 }
 
 function ensureWriteGateSnapshotDirectory(basePath: string): void {
-  const gsdPath = join(basePath, ".gsd");
+  const snapshotRoot = resolveWriteGateSnapshotRoot(basePath);
+  const gsdPath = join(snapshotRoot, ".gsd");
   if (!existsSync(gsdPath)) {
     try {
       const stat = lstatSync(gsdPath);
       if (stat.isSymbolicLink()) {
         const target = readlinkSync(gsdPath);
-        mkdirSync(isAbsolute(target) ? target : resolve(basePath, target), { recursive: true });
+        mkdirSync(isAbsolute(target) ? target : resolve(snapshotRoot, target), { recursive: true });
       }
     } catch {
       // If .gsd truly does not exist, the runtime mkdir below will create it.
@@ -174,7 +192,7 @@ function ensureWriteGateSnapshotDirectory(basePath: string): void {
   mkdirSync(join(gsdPath, "runtime"), { recursive: true });
 }
 
-function currentWriteGateSnapshot(basePath: string = process.cwd()): WriteGateSnapshot {
+export function currentWriteGateSnapshot(basePath: string = process.cwd()): WriteGateSnapshot {
   const state = getWriteGateState(basePath);
   return {
     verifiedDepthMilestones: [...state.verifiedDepthMilestones].sort(),
@@ -228,7 +246,9 @@ function clearPersistedWriteGateSnapshot(basePath: string): void {
 function normalizeWriteGateSnapshot(value: unknown): WriteGateSnapshot {
   const record = value && typeof value === "object" ? value as Record<string, unknown> : {};
   const verified = Array.isArray(record.verifiedDepthMilestones)
-    ? record.verifiedDepthMilestones.filter((item): item is string => typeof item === "string")
+    ? record.verifiedDepthMilestones
+        .filter((item): item is string => typeof item === "string")
+        .map(normalizeMilestoneId)
     : [];
   const verifiedGates = Array.isArray(record.verifiedApprovalGates)
     ? record.verifiedApprovalGates.filter((item): item is string => typeof item === "string")
@@ -289,7 +309,7 @@ export function loadWriteGateSnapshot(basePath: string): WriteGateSnapshot {
  *     guard that previously protected only the tool_execution_start window.
  */
 function mergeSnapshotIntoState(state: InMemoryWriteGateState, disk: WriteGateSnapshot): void {
-  for (const milestone of disk.verifiedDepthMilestones) state.verifiedDepthMilestones.add(milestone);
+  for (const milestone of disk.verifiedDepthMilestones) state.verifiedDepthMilestones.add(normalizeMilestoneId(milestone));
   for (const gate of disk.verifiedApprovalGates ?? []) state.verifiedApprovalGates.add(gate);
   state.activeQueuePhase = disk.activeQueuePhase;
   state.pendingGateId = disk.pendingGateId;
@@ -395,7 +415,7 @@ export function isMilestoneDepthVerified(
 ): boolean {
   if (!milestoneId) return false;
   refreshWriteGateStateFromDisk(basePath);
-  return getWriteGateState(basePath).verifiedDepthMilestones.has(milestoneId);
+  return getWriteGateState(basePath).verifiedDepthMilestones.has(normalizeMilestoneId(milestoneId));
 }
 
 export function isMilestoneDepthVerifiedInSnapshot(
@@ -403,7 +423,7 @@ export function isMilestoneDepthVerifiedInSnapshot(
   milestoneId: string | null | undefined,
 ): boolean {
   if (!milestoneId) return false;
-  return snapshot.verifiedDepthMilestones.includes(milestoneId);
+  return snapshot.verifiedDepthMilestones.includes(normalizeMilestoneId(milestoneId));
 }
 
 export function isQueuePhaseActive(basePath: string = process.cwd()): boolean {
@@ -466,7 +486,7 @@ export function isGateQuestionId(questionId: string): boolean {
  */
 export function extractDepthVerificationMilestoneId(questionId: string): string | null {
   const match = questionId.match(DEPTH_VERIFICATION_MILESTONE_RE);
-  return match?.[1] ?? null;
+  return match?.[1] ? normalizeMilestoneId(match[1]) : null;
 }
 
 /**
@@ -474,7 +494,7 @@ export function extractDepthVerificationMilestoneId(questionId: string): string
  */
 function extractContextMilestoneId(inputPath: string): string | null {
   const match = inputPath.match(CONTEXT_MILESTONE_RE);
-  return match?.[1] ?? null;
+  return match?.[1] ? normalizeMilestoneId(match[1]) : null;
 }
 
 /**
@@ -560,7 +580,7 @@ export const hostWriteGateAdapter: WriteGateStateAdapter = {
   markDepthVerified(milestoneId, basePath): void {
     if (!milestoneId) return;
     mutateWriteGateState(basePath, (state) => {
-      state.verifiedDepthMilestones.add(milestoneId);
+      state.verifiedDepthMilestones.add(normalizeMilestoneId(milestoneId));
     }, { writer: "host" });
   },
   markApprovalGateVerified(gateId, basePath): void {
@@ -601,7 +621,7 @@ export const childWriteGateAdapter: WriteGateStateAdapter = {
   markDepthVerified(milestoneId, basePath): void {
     if (!milestoneId) return;
     childMutate(basePath, (state) => {
-      state.verifiedDepthMilestones.add(milestoneId);
+      state.verifiedDepthMilestones.add(normalizeMilestoneId(milestoneId));
     });
   },
   markApprovalGateVerified(gateId, basePath): void {
@@ -735,6 +755,13 @@ export interface AskUserQuestionsGateQuestion {
 export interface AskUserQuestionsGateDetails {
   cancelled?: boolean;
   interrupted?: boolean;
+  /**
+   * True when the host elicitation channel timed out before the user answered.
+   * Distinct from `cancelled` (deliberate dismissal): the gate verdict maps
+   * this to "timeout" so callers pause-and-wait instead of letting the model
+   * re-ask into the same timeout loop (#852).
+   */
+  timed_out?: boolean;
   response?: {
     answers?: Record<string, { selected?: unknown } | undefined>;
   } | null;
@@ -744,7 +771,8 @@ export type AskUserQuestionsGateResult =
   | { status: "not-gate" }
   | { status: "waiting"; pendingGateId: string; interrupted: boolean }
   | { status: "verified"; gateId: string; milestoneId: string | null }
-  | { status: "declined"; gateId: string };
+  | { status: "declined"; gateId: string }
+  | { status: "timeout"; pendingGateId: string; interrupted: boolean };
 
 function findGateQuestion(
   questions: AskUserQuestionsGateQuestion[],
@@ -768,11 +796,22 @@ function verifyAnsweredGate(
 
 /** Map an unresolved (non-verified) gate verdict to the caller-facing result. */
 function unresolvedGateResult(
-  verdict: "declined" | "waiting" | "cancelled",
+  verdict: "declined" | "waiting" | "cancelled" | "timeout",
   gateId: string,
   details: AskUserQuestionsGateDetails,
 ): AskUserQuestionsGateResult {
   if (verdict === "declined") return { status: "declined", gateId };
+  if (verdict === "timeout") {
+    // Host elicitation expired before the user answered. The gate stays
+    // pending (fail-closed — a timeout is never approval), but the status is
+    // "timeout" so the caller pauses-and-waits instead of re-asking into the
+    // same timeout loop (#852).
+    return {
+      status: "timeout",
+      pendingGateId: gateId,
+      interrupted: details.interrupted === true,
+    };
+  }
   // "waiting" (and the unreachable post-cancel case): an empty selection is
   // not an answer — keep the gate pending and make the caller pause.
   return {
@@ -803,6 +842,16 @@ export function applyAskUserQuestionsGateResult(options: {
   const { basePath, questions, details, fallbackMilestoneId } = options;
   const currentPendingGate = getPendingGate(basePath);
   if (currentPendingGate) {
+    if (details.timed_out) {
+      // Host elicitation timed out before the user answered. Keep the gate
+      // pending (fail-closed) but report "timeout" so the caller pauses-and-
+      // waits instead of re-asking into the same timeout loop (#852).
+      return {
+        status: "timeout",
+        pendingGateId: currentPendingGate,
+        interrupted: details.interrupted === true,
+      };
+    }
     if (details.cancelled || !details.response) {
       return {
         status: "waiting",
@@ -821,6 +870,7 @@ export function applyAskUserQuestionsGateResult(options: {
     }
   }
 
+  if (details.timed_out) return { status: "not-gate" };
   if (details.cancelled || !details.response) return { status: "not-gate" };
 
   for (const question of questions) {
@@ -855,6 +905,24 @@ export function formatPendingAskUserQuestionsGateMessage(
   ].join(" ");
 }
 
+/**
+ * Format the LLM-facing message returned when a depth-confirmation gate
+ * elicitation times out. Distinct from {@link formatPendingAskUserQuestionsGateMessage}:
+ * a timeout must NOT tell the model to immediately re-ask (that re-triggers
+ * the same timeout loop). Instead it tells the model to stop, that auto-mode
+ * is paused, and that the user will respond on their own (#852).
+ */
+export function formatTimedOutAskUserQuestionsGateMessage(
+  pendingGateId: string,
+): string {
+  return [
+    `Depth confirmation on gate "${pendingGateId}" timed out waiting for a response.`,
+    "The user did not answer within the host elicitation window — do not re-ask in this turn, it will time out again.",
+    "Auto-mode is paused. Stop calling tools and wait for the user to respond on a new turn.",
+    "When the user replies with confirmation, the gate will be satisfied and work will resume.",
+  ].join(" ");
+}
+
 export function shouldBlockContextWrite(
   toolName: string,
   inputPath: string,
@@ -865,7 +933,7 @@ export function shouldBlockContextWrite(
   if (toolName !== "write") return { block: false };
   if (!MILESTONE_CONTEXT_RE.test(inputPath)) return { block: false };
 
-  const targetMilestoneId = extractContextMilestoneId(inputPath) ?? milestoneId;
+  const targetMilestoneId = extractContextMilestoneId(inputPath) ?? (milestoneId ? normalizeMilestoneId(milestoneId) : null);
   if (!targetMilestoneId) {
     return {
       block: true,
@@ -884,8 +952,8 @@ export function shouldBlockContextWrite(
     reason: [
       `HARD BLOCK: Cannot write to milestone CONTEXT.md without depth verification.`,
       `This is a mechanical gate — you MUST NOT proceed, retry, or rationalize past this block.`,
-      `Required action: call ask_user_questions with question id containing "depth_verification".`,
-      `The user MUST select the "(Recommended)" confirmation option to unlock this gate.`,
+      `Required action: call ask_user_questions with question id "depth_verification_${targetMilestoneId}_confirm".`,
+      `The user MUST select the first "(Recommended)" confirmation option to unlock this gate.`,
       `If the user declines, cancels, or the tool fails, you must re-ask — not bypass.`,
     ].join(" "),
   };

package/src/resources/extensions/gsd/closeout-consistency-gate.ts

@@ -1,7 +1,8 @@
 // Project/App: gsd-pi
 // File Purpose: Shared DB-backed guard for milestone closeout finalization.
 
-import { dirname } from "node:path";
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 
 import {
   getLatestAssessmentByScope,
@@ -9,14 +10,19 @@ import {
   getMilestoneSlices,
   getPendingGates,
   getSliceTasks,
+  insertAssessment,
   isDbAvailable,
+  transaction,
 } from "./gsd-db.js";
 import {
   getWorkflowDatabasePath,
   refreshWorkflowDatabaseFromDisk,
 } from "./db-workspace.js";
-import { isClosedStatus } from "./status-guards.js";
+import { isClosedStatus, isDeferredStatus } from "./status-guards.js";
 import { closeQualityGatesFromEvidence } from "./quality-gate-closure.js";
+import { insertMilestoneValidationGates } from "./milestone-validation-gates.js";
+import { relMilestoneFile, resolveSliceFile } from "./paths.js";
+import { invalidateAllCaches } from "./cache.js";
 
 export const CLOSEOUT_CONSISTENCY_BLOCKED_REASON = "closeout-consistency-blocked";
 
@@ -44,6 +50,7 @@ export interface CloseoutConsistencyOptions {
   refreshFromDisk?: boolean;
   allowOpenMilestone?: boolean;
   artifactBasePath?: string;
+  allowPassThroughValidation?: boolean;
 }
 
 function blocked(reason: CloseoutConsistencyFailureReason, message: string): CloseoutConsistencyResult {
@@ -65,6 +72,87 @@ function artifactBasePathFromDb(): string | undefined {
   return dirname(dirname(dbPath!));
 }
 
+function allSlicesHaveCloseoutSummaryEvidence(milestoneId: string, artifactBasePath: string): boolean {
+  const slices = getMilestoneSlices(milestoneId);
+  if (slices.length === 0) return false;
+
+  return slices.every((slice) => {
+    if (!isClosedStatus(slice.status)) return false;
+    for (const task of getSliceTasks(milestoneId, slice.id)) {
+      if (!isClosedStatus(task.status)) return false;
+    }
+    const summaryPath = resolveSliceFile(artifactBasePath, milestoneId, slice.id, "SUMMARY");
+    return Boolean(summaryPath && existsSync(summaryPath));
+  });
+}
+
+function renderCloseoutPassThroughValidation(milestoneId: string): string {
+  return [
+    "---",
+    "verdict: pass",
+    "skip_validation: true",
+    "skip_validation_reason: closeout-recovery",
+    "remediation_round: 0",
+    "---",
+    "",
+    "# Milestone Validation (skipped)",
+    "",
+    `Milestone validation was recorded during closeout for ${milestoneId} because all slices already had SUMMARY evidence and no milestone-validation assessment was present.`,
+    "",
+  ].join("\n");
+}
+
+function recordCloseoutPassThroughValidationIfReady(
+  milestoneId: string,
+  artifactBasePath?: string,
+): boolean {
+  const basePath = artifactBasePath ?? artifactBasePathFromDb();
+  if (!basePath) return false;
+
+  const existing = getLatestAssessmentByScope(milestoneId, "milestone-validation");
+  if (existing?.status === "pass") return true;
+  if (existing) return false;
+  if (!allSlicesHaveCloseoutSummaryEvidence(milestoneId, basePath)) return false;
+
+  const validationPath = join(basePath, relMilestoneFile(basePath, milestoneId, "VALIDATION"));
+  const content = renderCloseoutPassThroughValidation(milestoneId);
+  mkdirSync(dirname(validationPath), { recursive: true });
+  writeFileSync(validationPath, content, "utf-8");
+
+  try {
+    transaction(() => {
+      insertAssessment({
+        path: validationPath,
+        milestoneId,
+        sliceId: null,
+        taskId: null,
+        status: "pass",
+        scope: "milestone-validation",
+        fullContent: content,
+      });
+      const gateSliceId = getMilestoneSlices(milestoneId)[0]?.id;
+      if (gateSliceId) {
+        insertMilestoneValidationGates(
+          milestoneId,
+          gateSliceId,
+          "pass",
+          new Date().toISOString(),
+        );
+      }
+    });
+  } catch (err) {
+    try {
+      unlinkSync(validationPath);
+    } catch {
+      // best effort cleanup
+    }
+    throw err;
+  }
+
+  invalidateAllCaches();
+  return true;
+}
+
 export function checkCloseoutConsistencyGate(
   milestoneId: string,
   options: CloseoutConsistencyOptions = {},
@@ -97,14 +185,30 @@ export function checkCloseoutConsistencyGate(
     );
   }
 
-  const validation = milestone.status === "skipped"
+  let validation = milestone.status === "skipped"
     ? null
     : getLatestAssessmentByScope(milestoneId, "milestone-validation");
+  if (
+    milestone.status !== "skipped" &&
+    validation?.status !== "pass" &&
+    options.allowPassThroughValidation &&
+    recordCloseoutPassThroughValidationIfReady(
+      milestoneId,
+      options.artifactBasePath ?? artifactBasePathFromDb(),
+    )
+  ) {
+    validation = getLatestAssessmentByScope(milestoneId, "milestone-validation");
+  }
   if (milestone.status !== "skipped") {
     if (validation?.status !== "pass") {
+      const validationStatus = validation?.status ?? "absent";
+      const recovery =
+        validationStatus === "absent"
+          ? ` Run \`/gsd validate-milestone ${milestoneId}\` to create the validation, or set \`phases.skip_milestone_validation: true\` in .gsd/PREFERENCES.md to skip it.`
+          : "";
       return blocked(
         "validation-not-pass",
-        `Closeout consistency blocked for ${milestoneId}: latest milestone validation is "${validation?.status ?? "absent"}".`,
+        `Closeout consistency blocked for ${milestoneId}: latest milestone validation is "${validationStatus}".${recovery}`,
       );
     }
   }
@@ -125,6 +229,7 @@ export function checkCloseoutConsistencyGate(
   }
 
   for (const slice of slices) {
+    if (isDeferredStatus(slice.status)) continue;
     if (!isClosedStatus(slice.status)) {
       return blocked(
         "slice-open",

package/src/resources/extensions/gsd/codebase-generator.ts

@@ -472,21 +472,18 @@ export function ensureCodebaseMapFresh(
   const force = ensureOptions?.force === true;
   const now = Date.now();
 
-  // Enumerate files and compute fingerprint before the TTL check so that
-  // file changes are always detected, even within the TTL window.
-  const existing = readCodebaseMap(basePath);
-  const listed = enumerateFiles(basePath, resolved.excludes, resolved.maxFiles);
-  const fingerprint = computeCodebaseFingerprint(listed.files, resolved, listed.truncated);
-
-  // TTL short-circuit: only bypass regeneration when the fingerprint matches,
-  // confirming that no tracked files changed since the last check.
+  // TTL short-circuit: avoid spawning git on the per-turn freshness path.
   if (!force && ttlMs > 0) {
     const cached = freshnessCache.get(cacheKey);
-    if (cached && now - cached.checkedAt < ttlMs && cached.result.fingerprint === fingerprint) {
+    if (cached && now - cached.checkedAt < ttlMs) {
       return cached.result;
     }
   }
 
+  const existing = readCodebaseMap(basePath);
+  const listed = enumerateFiles(basePath, resolved.excludes, resolved.maxFiles);
+  const fingerprint = computeCodebaseFingerprint(listed.files, resolved, listed.truncated);
+
   const cacheAndReturn = (result: EnsureCodebaseMapResult): EnsureCodebaseMapResult => {
     freshnessCache.set(cacheKey, { checkedAt: now, result });
     return result;

package/src/resources/extensions/gsd/commands/catalog.ts

@@ -5,6 +5,8 @@ import { loadRegistry } from "../workflow-templates.js";
 import { gsdHome } from "../gsd-home.js";
 import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { VISUAL_BRIEF_MODES } from "../../visual-brief/prompts.js";
+import { GSD_CORE_ALIAS_CATALOG } from "./gsd-core-aliases.js";
+import { GSD_CORE_IMPLEMENTED_CATALOG } from "../commands-gsd-core.js";
 
 
 export interface GsdCommandDefinition {
@@ -96,6 +98,10 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "language", desc: "Set or clear the global response language (e.g. /gsd language Chinese)" },
   { cmd: "worktree", desc: "Manage worktrees from the TUI (list, merge, clean, remove)" },
   { cmd: "eval-review", desc: "Audit a slice's AI evaluation strategy and write a scored EVAL-REVIEW.md (--force, --show)" },
+  // Additional commands (commands-gsd-core.ts) run real prompt-driven workflows;
+  // namespace aliases (gsd-core-aliases.ts) redirect to /gsd help.
+  ...GSD_CORE_IMPLEMENTED_CATALOG,
+  ...GSD_CORE_ALIAS_CATALOG,
 ];
 
 const NESTED_COMPLETIONS: CompletionMap = {