@opengsd/gsd-pi 1.3.0 → 1.4.0

package/dist/resources/extensions/gsd/bootstrap/tool-call-loop-guard.js

@@ -1,25 +1,55 @@
 /**
  * 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;
 /** Interactive/user-facing tools where even 1 duplicate is confusing. */
 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();
+let mutationEpoch = 0;
+const perToolLastMutationEpoch = new Map();
 /** Hash tool name + args into a compact signature for comparison. */
 function hashToolCall(toolName, args) {
     const h = createHash("sha256");
@@ -38,6 +68,13 @@ function hashToolCall(toolName, args) {
  *
  * 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, args) {
     if (!enabled)
@@ -51,26 +88,65 @@ export function checkToolCallLoop(toolName, args) {
         lastSignature = sig;
         lastToolName = toolName;
     }
+    // ── Guard 1: identical-signature streak ──
     const threshold = STRICT_LOOP_TOOLS.has(toolName)
         ? MAX_CONSECUTIVE_STRICT
         : MAX_CONSECUTIVE_IDENTICAL_CALLS;
     if (consecutiveCount > threshold) {
         return {
             block: true,
-            reason: `Tool loop detected: ${toolName} called ${consecutiveCount} times ` +
+            reason: `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) {
+    if (!enabled)
+        return;
+    if (!STATE_MUTATING_TOOL_SET.has(toolName))
+        return;
+    mutationEpoch++;
+}
 /** Reset the guard state. Call at agent turn boundaries. */
 export function resetToolCallLoopGuard() {
     consecutiveCount = 0;
     lastSignature = "";
     lastToolName = "";
     enabled = true;
+    perToolCounts.clear();
+    mutationEpoch = 0;
+    perToolLastMutationEpoch.clear();
 }
 /** Disable the guard (e.g. during shutdown). */
 export function disableToolCallLoopGuard() {
@@ -78,8 +154,18 @@ export function disableToolCallLoopGuard() {
     consecutiveCount = 0;
     lastSignature = "";
     lastToolName = "";
+    perToolCounts.clear();
+    mutationEpoch = 0;
+    perToolLastMutationEpoch.clear();
 }
 /** Get current consecutive count for diagnostics. */
 export function getToolCallLoopCount() {
     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) {
+    return perToolCounts.get(toolName) ?? 0;
+}

package/dist/resources/extensions/gsd/bootstrap/tool-search-shim.js

@@ -26,8 +26,27 @@ export function registerToolSearchShim(pi) {
             return new Text(theme.fg("warning", text), 0, 0);
         },
     });
-    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/dist/resources/extensions/gsd/bootstrap/write-gate.js

@@ -21,6 +21,12 @@ import { evaluateGateAnswer } from "../consent-verdict.js";
 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) {
+    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.
@@ -75,8 +81,18 @@ function createEmptyWriteGateState() {
     };
 }
 const writeGateStatesByBasePath = new Map();
+/**
+ * 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) {
+    return resolve(resolveWorktreeProjectRoot(basePath));
+}
 function writeGateStateKey(basePath) {
-    return resolve(basePath);
+    return resolveWriteGateSnapshotRoot(basePath);
 }
 function getWriteGateState(basePath = process.cwd()) {
     const key = writeGateStateKey(basePath);
@@ -117,16 +133,17 @@ function shouldPersistWriteGateSnapshot(env = process.env) {
     return v !== "0" && v !== "false";
 }
 function writeGateSnapshotPath(basePath) {
-    return join(basePath, ".gsd", "runtime", "write-gate-state.json");
+    return join(resolveWriteGateSnapshotRoot(basePath), ".gsd", "runtime", "write-gate-state.json");
 }
 function ensureWriteGateSnapshotDirectory(basePath) {
-    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 {
@@ -135,7 +152,7 @@ function ensureWriteGateSnapshotDirectory(basePath) {
     }
     mkdirSync(join(gsdPath, "runtime"), { recursive: true });
 }
-function currentWriteGateSnapshot(basePath = process.cwd()) {
+export function currentWriteGateSnapshot(basePath = process.cwd()) {
     const state = getWriteGateState(basePath);
     return {
         verifiedDepthMilestones: [...state.verifiedDepthMilestones].sort(),
@@ -190,7 +207,9 @@ function clearPersistedWriteGateSnapshot(basePath) {
 function normalizeWriteGateSnapshot(value) {
     const record = value && typeof value === "object" ? value : {};
     const verified = Array.isArray(record.verifiedDepthMilestones)
-        ? record.verifiedDepthMilestones.filter((item) => typeof item === "string")
+        ? record.verifiedDepthMilestones
+            .filter((item) => typeof item === "string")
+            .map(normalizeMilestoneId)
         : [];
     const verifiedGates = Array.isArray(record.verifiedApprovalGates)
         ? record.verifiedApprovalGates.filter((item) => typeof item === "string")
@@ -246,7 +265,7 @@ export function loadWriteGateSnapshot(basePath) {
  */
 function mergeSnapshotIntoState(state, disk) {
     for (const milestone of disk.verifiedDepthMilestones)
-        state.verifiedDepthMilestones.add(milestone);
+        state.verifiedDepthMilestones.add(normalizeMilestoneId(milestone));
     for (const gate of disk.verifiedApprovalGates ?? [])
         state.verifiedApprovalGates.add(gate);
     state.activeQueuePhase = disk.activeQueuePhase;
@@ -344,12 +363,12 @@ export function isMilestoneDepthVerified(milestoneId, basePath = process.cwd())
     if (!milestoneId)
         return false;
     refreshWriteGateStateFromDisk(basePath);
-    return getWriteGateState(basePath).verifiedDepthMilestones.has(milestoneId);
+    return getWriteGateState(basePath).verifiedDepthMilestones.has(normalizeMilestoneId(milestoneId));
 }
 export function isMilestoneDepthVerifiedInSnapshot(snapshot, milestoneId) {
     if (!milestoneId)
         return false;
-    return snapshot.verifiedDepthMilestones.includes(milestoneId);
+    return snapshot.verifiedDepthMilestones.includes(normalizeMilestoneId(milestoneId));
 }
 export function isQueuePhaseActive(basePath = process.cwd()) {
     return getWriteGateState(basePath).activeQueuePhase;
@@ -401,14 +420,14 @@ export function isGateQuestionId(questionId) {
  */
 export function extractDepthVerificationMilestoneId(questionId) {
     const match = questionId.match(DEPTH_VERIFICATION_MILESTONE_RE);
-    return match?.[1] ?? null;
+    return match?.[1] ? normalizeMilestoneId(match[1]) : null;
 }
 /**
  * Extract the milestone ID from a milestone CONTEXT file path.
  */
 function extractContextMilestoneId(inputPath) {
     const match = inputPath.match(CONTEXT_MILESTONE_RE);
-    return match?.[1] ?? null;
+    return match?.[1] ? normalizeMilestoneId(match[1]) : null;
 }
 /**
  * Mark a gate as pending (called when ask_user_questions is invoked with a
@@ -465,7 +484,7 @@ export const hostWriteGateAdapter = {
         if (!milestoneId)
             return;
         mutateWriteGateState(basePath, (state) => {
-            state.verifiedDepthMilestones.add(milestoneId);
+            state.verifiedDepthMilestones.add(normalizeMilestoneId(milestoneId));
         }, { writer: "host" });
     },
     markApprovalGateVerified(gateId, basePath) {
@@ -509,7 +528,7 @@ export const childWriteGateAdapter = {
         if (!milestoneId)
             return;
         childMutate(basePath, (state) => {
-            state.verifiedDepthMilestones.add(milestoneId);
+            state.verifiedDepthMilestones.add(normalizeMilestoneId(milestoneId));
         });
     },
     markApprovalGateVerified(gateId, basePath) {
@@ -622,6 +641,17 @@ function verifyAnsweredGate(basePath, question, fallbackMilestoneId) {
 function unresolvedGateResult(verdict, gateId, details) {
     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 {
@@ -646,6 +676,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",
@@ -662,6 +702,8 @@ export function applyAskUserQuestionsGateResult(options) {
             return unresolvedGateResult(verdict, currentPendingGate, details);
         }
     }
+    if (details.timed_out)
+        return { status: "not-gate" };
     if (details.cancelled || !details.response)
         return { status: "not-gate" };
     for (const question of questions) {
@@ -691,12 +733,27 @@ export function formatPendingAskUserQuestionsGateMessage(pendingGateId, interrup
         `Re-call ask_user_questions with the same gate question id ("${pendingGateId}") and wait for the user's response.`,
     ].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) {
+    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, inputPath, milestoneId, _queuePhaseActive, basePath = process.cwd()) {
     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,
@@ -714,8 +771,8 @@ export function shouldBlockContextWrite(toolName, inputPath, milestoneId, _queue
         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/dist/resources/extensions/gsd/closeout-consistency-gate.js

@@ -1,10 +1,14 @@
 // Project/App: gsd-pi
 // File Purpose: Shared DB-backed guard for milestone closeout finalization.
-import { dirname } from "node:path";
-import { getLatestAssessmentByScope, getMilestone, getMilestoneSlices, getPendingGates, getSliceTasks, isDbAvailable, } from "./gsd-db.js";
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getLatestAssessmentByScope, getMilestone, 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";
 function blocked(reason, message) {
     return {
@@ -23,6 +27,80 @@ function artifactBasePathFromDb() {
         return undefined;
     return dirname(dirname(dbPath));
 }
+function allSlicesHaveCloseoutSummaryEvidence(milestoneId, artifactBasePath) {
+    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) {
+    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, artifactBasePath) {
+    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, options = {}) {
     if (!isDbAvailable()) {
         return blocked("db-unavailable", `Closeout consistency blocked for ${milestoneId}: canonical DB is unavailable.`);
@@ -37,12 +115,22 @@ export function checkCloseoutConsistencyGate(milestoneId, options = {}) {
     if (!isClosedStatus(milestone.status) && !options.allowOpenMilestone) {
         return blocked("milestone-open", `Closeout consistency blocked for ${milestoneId}: canonical DB milestone status is "${milestone.status}".`);
     }
-    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") {
-            return blocked("validation-not-pass", `Closeout consistency blocked for ${milestoneId}: latest milestone validation is "${validation?.status ?? "absent"}".`);
+            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 "${validationStatus}".${recovery}`);
         }
     }
     const slices = getMilestoneSlices(milestoneId);
@@ -56,6 +144,8 @@ export function checkCloseoutConsistencyGate(milestoneId, options = {}) {
         });
     }
     for (const slice of slices) {
+        if (isDeferredStatus(slice.status))
+            continue;
         if (!isClosedStatus(slice.status)) {
             return blocked("slice-open", `Closeout consistency blocked for ${milestoneId}: slice ${slice.id} status is "${slice.status}".`);
         }

package/dist/resources/extensions/gsd/codebase-generator.js

@@ -330,19 +330,16 @@ export function ensureCodebaseMapFresh(basePath, options, ensureOptions) {
     const ttlMs = ensureOptions?.ttlMs ?? DEFAULT_REFRESH_TTL_MS;
     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) => {
         freshnessCache.set(cacheKey, { checkedAt: now, result });
         return result;

package/dist/resources/extensions/gsd/commands/catalog.js

@@ -4,6 +4,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 const GSD_COMMAND_DESCRIPTION = "GSD — Git Ship Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|brief|report|queue|quick|discuss|capture|triage|dispatch|verdict|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|closeout|rebuild|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|debug|logs|forensics|changelog|migrate|remote|steer|knowledge|memory|new-milestone|new-project|parallel|cmux|park|unpark|init|setup|onboarding|inspect|extensions|update|upgrade|fast|mcp|rethink|workflow|codebase|notifications|ship|do|usage|context|session-report|backlog|pr-branch|add-tests|scan|language|worktree|eval-review";
 export const TOP_LEVEL_SUBCOMMANDS = [
     { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -84,6 +86,10 @@ export const TOP_LEVEL_SUBCOMMANDS = [
     { 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 = {
     brief: VISUAL_BRIEF_MODES.map((mode) => ({ cmd: mode.mode, desc: mode.description })),

package/dist/resources/extensions/gsd/commands/dispatcher.js

@@ -6,6 +6,7 @@ import { handleCoreCommand } from "./handlers/core.js";
 import { handleOpsCommand } from "./handlers/ops.js";
 import { handleParallelCommand } from "./handlers/parallel.js";
 import { handleWorkflowCommand } from "./handlers/workflow.js";
+import { handleGsdCoreAlias } from "./gsd-core-aliases-handler.js";
 import { getValidationBlockMessageForBase, isValidationBlockAllowedCommand, } from "../validation-block-guard.js";
 import { getUnmergedMilestoneBlockMessageForBase, isUnmergedMilestoneAllowedCommand, } from "../unmerged-milestone-guard.js";
 import { getWorkspaceGitBlockMessageForBase } from "../workspace-git-guard.js";
@@ -24,6 +25,8 @@ function emitVisibleCommandBlock(ctx, pi, message) {
 export async function handleGSDCommand(args, ctx, pi) {
     const trimmed = (typeof args === "string" ? args : "").trim();
     const handlers = [
+        // Namespace alias redirects (ns-*) run first so they resolve before the standard handlers.
+        () => handleGsdCoreAlias(trimmed, ctx, pi),
         () => handleCoreCommand(trimmed, ctx, pi),
         () => handleAutoCommand(trimmed, ctx, pi),
         () => handleParallelCommand(trimmed, ctx, pi),

package/dist/resources/extensions/gsd/commands/gsd-core-aliases-handler.js

@@ -0,0 +1,39 @@
+// Project/App: gsd-pi
+// File Purpose: Handler that resolves namespace alias redirects (ns-*).
+//
+// Returns true (handled) when the input matches a namespace alias. Redirects
+// re-dispatch through the main dispatcher so safety guards apply to the target
+// command too. Unavailable aliases print a helpful message and stop.
+import { matchGsdCoreAlias } from "./gsd-core-aliases.js";
+function formatUnavailable(cmd, alias) {
+    const lines = [
+        `/gsd ${cmd} is not available.`,
+        `Previously it: ${alias.legacy}`,
+    ];
+    if (alias.alternative)
+        lines.push(`Alternative: ${alias.alternative}`);
+    lines.push("Run /gsd help for the command reference.");
+    return lines.join("\n");
+}
+export async function handleGsdCoreAlias(trimmed, ctx, pi) {
+    const match = matchGsdCoreAlias(trimmed);
+    if (!match)
+        return false;
+    const { alias, cmd, rest } = match;
+    if (alias.kind === "unavailable") {
+        ctx.ui.notify(formatUnavailable(cmd, alias), "warning");
+        return true;
+    }
+    // Redirect: rebuild the target command with any trailing args, then re-dispatch
+    // through the main dispatcher so guards + handlers run against the target.
+    const targetWithArgs = rest ? `${alias.target} ${rest}` : alias.target;
+    if (alias.note) {
+        ctx.ui.notify(`${cmd} → /gsd ${alias.target} (${alias.note})`, "info");
+    }
+    else {
+        ctx.ui.notify(`${cmd} → /gsd ${alias.target}`, "info");
+    }
+    const { handleGSDCommand } = await import("./dispatcher.js");
+    await handleGSDCommand(targetWithArgs, ctx, pi);
+    return true;
+}