gsd-pi 2.74.0 → 2.75.0-dev.063e5a3

package/src/resources/extensions/gsd/auto-verification.ts

@@ -33,6 +33,8 @@ import { runPostExecutionChecks, type PostExecutionResult } from "./post-executi
 import type { AutoSession } from "./auto/session.js";
 import type { VerificationResult as VerificationGateResult } from "./types.js";
 import { join } from "node:path";
+import { resolveUokFlags } from "./uok/flags.js";
+import { UokGateRunner } from "./uok/gate-runner.js";
 
 export interface VerificationContext {
   s: AutoSession;
@@ -67,6 +69,37 @@ async function runValidateMilestonePostCheck(
   pauseAuto: (ctx?: ExtensionContext, pi?: ExtensionAPI) => Promise<void>,
 ): Promise<VerificationResult> {
   const { s, ctx, pi } = vctx;
+  const prefs = loadEffectiveGSDPreferences()?.preferences;
+  const uokFlags = resolveUokFlags(prefs);
+  const persistMilestoneValidationGate = async (
+    outcome: "pass" | "fail" | "retry" | "manual-attention",
+    failureClass: "none" | "verification" | "manual-attention",
+    rationale: string,
+    findings = "",
+    milestoneId?: string,
+  ): Promise<void> => {
+    if (!uokFlags.gates || !s.currentUnit) return;
+    const gateRunner = new UokGateRunner();
+    gateRunner.register({
+      id: "milestone-validation-post-check",
+      type: "verification",
+      execute: async () => ({
+        outcome,
+        failureClass,
+        rationale,
+        findings,
+      }),
+    });
+    await gateRunner.run("milestone-validation-post-check", {
+      basePath: s.basePath,
+      traceId: `validation-post-check:${s.currentUnit.id}`,
+      turnId: s.currentUnit.id,
+      milestoneId,
+      unitType: s.currentUnit.type,
+      unitId: s.currentUnit.id,
+    });
+  };
+
   if (!s.currentUnit) return "continue";
 
   const { milestone: mid } = parseUnitId(s.currentUnit.id);
@@ -79,14 +112,32 @@ async function runValidateMilestonePostCheck(
   if (!validationContent) return "continue";
 
   const verdict = extractVerdict(validationContent);
-  if (verdict !== "needs-remediation") return "continue";
+  if (verdict !== "needs-remediation") {
+    await persistMilestoneValidationGate(
+      "pass",
+      "none",
+      `milestone validation verdict is ${verdict}; no remediation loop risk`,
+      "",
+      mid,
+    );
+    return "continue";
+  }
 
   const incompleteSliceCount = await countIncompleteSlices(s.basePath, mid);
 
   // If any non-closed slices exist, the agent successfully queued remediation
   // work — proceed normally. The state machine will execute those slices and
   // re-validate per the #3596/#3670 fix.
-  if (incompleteSliceCount > 0) return "continue";
+  if (incompleteSliceCount > 0) {
+    await persistMilestoneValidationGate(
+      "pass",
+      "none",
+      `remediation slices present (${incompleteSliceCount}); validation can continue`,
+      "",
+      mid,
+    );
+    return "continue";
+  }
 
   ctx.ui.notify(
     `Milestone ${mid} validation returned verdict=needs-remediation but no remediation slices were added. Pausing for human review.`,
@@ -96,6 +147,13 @@ async function runValidateMilestonePostCheck(
     `validate-milestone: pausing — verdict=needs-remediation with no incomplete slices for ${mid}. ` +
       `The agent must call gsd_reassess_roadmap to add remediation slices before re-validation.\n`,
   );
+  await persistMilestoneValidationGate(
+    "manual-attention",
+    "manual-attention",
+    "needs-remediation verdict without queued remediation slices",
+    `No incomplete slices found for ${mid} while verdict=needs-remediation`,
+    mid,
+  );
   await pauseAuto(ctx, pi);
   return "pause";
 }
@@ -158,6 +216,7 @@ export async function runPostUnitVerification(
   try {
     const effectivePrefs = loadEffectiveGSDPreferences();
     const prefs = effectivePrefs?.preferences;
+    const uokFlags = resolveUokFlags(prefs);
 
     // Read task plan verify field
     const { milestone: mid, slice: sid, task: tid } = parseUnitId(s.currentUnit.id);
@@ -196,6 +255,37 @@ export async function runPostUnitVerification(
       }
     }
 
+    if (uokFlags.gates) {
+      const gateRunner = new UokGateRunner();
+      gateRunner.register({
+        id: "verification-gate",
+        type: "verification",
+        execute: async () => ({
+          outcome: result.passed ? "pass" : "fail",
+          failureClass: result.runtimeErrors?.some((e) => e.blocking)
+            ? "execution"
+            : "verification",
+          rationale: result.passed
+            ? "verification checks passed"
+            : "verification checks failed",
+          findings: result.passed
+            ? ""
+            : formatFailureContext(result),
+        }),
+      });
+
+      await gateRunner.run("verification-gate", {
+        basePath: s.basePath,
+        traceId: `verification:${s.currentUnit.id}`,
+        turnId: s.currentUnit.id,
+        milestoneId: mid ?? undefined,
+        sliceId: sid ?? undefined,
+        taskId: tid ?? undefined,
+        unitType: s.currentUnit.type,
+        unitId: s.currentUnit.id,
+      });
+    }
+
     // Auto-fix retry preferences
     const autoFixEnabled = prefs?.verification_auto_fix !== false;
     const maxRetries =
@@ -338,6 +428,43 @@ export async function runPostUnitVerification(
               );
             }
 
+            if (uokFlags.gates) {
+              const strictMode = prefs?.enhanced_verification_strict === true;
+              const warnEscalated = postExecResult.status === "warn" && strictMode;
+              const blockingFailure = postExecResult.status === "fail" || warnEscalated;
+              const findings = postExecResult.checks
+                .filter((check) => !check.passed)
+                .map((check) => `[${check.category}] ${check.target}: ${check.message}`)
+                .join("\n");
+              const gateRunner = new UokGateRunner();
+              gateRunner.register({
+                id: "post-execution-checks",
+                type: "artifact",
+                execute: async () => ({
+                  outcome: blockingFailure ? "fail" : "pass",
+                  failureClass: postExecResult.status === "fail"
+                    ? "artifact"
+                    : warnEscalated
+                      ? "policy"
+                      : "none",
+                  rationale: blockingFailure
+                    ? `post-execution checks ${postExecResult.status}${warnEscalated ? " (strict)" : ""}`
+                    : "post-execution checks passed",
+                  findings,
+                }),
+              });
+              await gateRunner.run("post-execution-checks", {
+                basePath: s.basePath,
+                traceId: `verification:${s.currentUnit.id}`,
+                turnId: s.currentUnit.id,
+                milestoneId: mid,
+                sliceId: sid,
+                taskId: tid,
+                unitType: s.currentUnit.type,
+                unitId: s.currentUnit.id,
+              });
+            }
+
             // Check for blocking failures
             if (postExecResult.status === "fail") {
               postExecBlockingFailure = true;

package/src/resources/extensions/gsd/auto-worktree.ts

@@ -102,6 +102,7 @@ function isSamePath(a: string, b: string): boolean {
   try {
     return realpathSync(a) === realpathSync(b);
   } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === "ENOENT") return false;
     logWarning("worktree", `isSamePath failed: ${(e as Error).message}`);
     return false;
   }

package/src/resources/extensions/gsd/auto.ts

@@ -195,12 +195,15 @@ import { clearCmuxSidebar, logCmuxEvent, syncCmuxSidebar } from "../cmux/index.j
 import { startUnitSupervision } from "./auto-timers.js";
 import { runPostUnitVerification } from "./auto-verification.js";
 import {
+  autoCommitUnit,
   postUnitPreVerification,
   postUnitPostVerification,
 } from "./auto-post-unit.js";
 import { bootstrapAutoSession, openProjectDbIfPresent, type BootstrapDeps } from "./auto-start.js";
 import { initHealthWidget } from "./health-widget.js";
 import { autoLoop, resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSessionSwitchInFlight, type LoopDeps, type ErrorContext } from "./auto-loop.js";
+import { runAutoLoopWithUok } from "./uok/kernel.js";
+import { resolveUokFlags } from "./uok/flags.js";
 // Slice-level parallelism (#2340)
 import { getEligibleSlices } from "./slice-parallel-eligibility.js";
 import { startSliceParallel } from "./slice-parallel-orchestrator.js";
@@ -604,11 +607,29 @@ function buildSnapshotOpts(
   continueHereFired?: boolean;
   promptCharCount?: number;
   baselineCharCount?: number;
+  traceId?: string;
+  turnId?: string;
+  gitAction?: "commit" | "snapshot" | "status-only";
+  gitPush?: boolean;
+  gitStatus?: "ok" | "failed";
+  gitError?: string;
 } & Record<string, unknown> {
+  const prefs = loadEffectiveGSDPreferences()?.preferences;
+  const uokFlags = resolveUokFlags(prefs);
   return {
     ...(s.autoStartTime > 0 ? { autoSessionKey: String(s.autoStartTime) } : {}),
     promptCharCount: s.lastPromptCharCount,
     baselineCharCount: s.lastBaselineCharCount,
+    traceId: s.currentTraceId ?? undefined,
+    turnId: s.currentTurnId ?? undefined,
+    ...(uokFlags.gitops
+      ? {
+          gitAction: uokFlags.gitopsTurnAction,
+          gitPush: uokFlags.gitopsTurnPush,
+          gitStatus: s.lastGitActionStatus ?? undefined,
+          gitError: s.lastGitActionFailure ?? undefined,
+        }
+      : {}),
     ...(s.currentUnitRouting ?? {}),
   };
 }
@@ -1180,6 +1201,7 @@ function buildLoopDeps(): LoopDeps {
     getMainBranch,
     // Unit closeout + runtime records
     closeoutUnit,
+    autoCommitUnit,
     recordOutcome,
     writeLock,
     captureAvailableSkills,
@@ -1400,6 +1422,11 @@ export async function startAuto(
     s.stepMode = requestedStepMode;
     s.cmdCtx = ctx;
     s.basePath = base;
+    // Ensure the workflow-logger audit log is pinned to the project root
+    // even when auto-mode is entered via a path that bypasses the
+    // bootstrap/dynamic-tools ensureDbOpen() → setLogBasePath() chain
+    // (e.g. /clear resume, hot-reload).
+    setLogBasePath(base);
     s.unitDispatchCount.clear();
     s.unitLifetimeDispatches.clear();
     if (!getLedger()) initMetrics(base);
@@ -1506,7 +1533,13 @@ export async function startAuto(
     logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "progress");
 
     captureProjectRootEnv(s.originalBasePath || s.basePath);
-    await autoLoop(ctx, pi, s, buildLoopDeps());
+    await runAutoLoopWithUok({
+      ctx,
+      pi,
+      s,
+      deps: buildLoopDeps(),
+      runLegacyLoop: autoLoop,
+    });
     cleanupAfterLoopExit(ctx);
     return;
   }
@@ -1541,7 +1574,13 @@ export async function startAuto(
   logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, requestedStepMode ? "Step-mode started." : "Auto-mode started.", "progress");
 
   // Dispatch the first unit
-  await autoLoop(ctx, pi, s, buildLoopDeps());
+  await runAutoLoopWithUok({
+    ctx,
+    pi,
+    s,
+    deps: buildLoopDeps(),
+    runLegacyLoop: autoLoop,
+  });
   cleanupAfterLoopExit(ctx);
 }
 

package/src/resources/extensions/gsd/bootstrap/provider-error-resume.ts

@@ -6,6 +6,7 @@ import type {
 
 import { getAutoDashboardData, startAuto, type AutoDashboardData } from "../auto.js";
 import { resetTransientRetryState } from "./agent-end-recovery.js";
+import { resetSessionTimeoutState } from "../auto/phases.js";
 
 type AutoResumeSnapshot = Pick<AutoDashboardData, "active" | "paused" | "stepMode" | "basePath">;
 
@@ -43,10 +44,11 @@ export async function resumeAutoAfterProviderDelay(
     return "missing-base";
   }
 
-  // Reset the transient retry counter before restarting — without this,
-  // consecutiveTransientCount accumulates across pause/resume cycles and
-  // permanently locks out auto-resume after MAX_TRANSIENT_AUTO_RESUMES errors.
+  // Reset retry counters before restarting — without this, counters
+  // accumulate across pause/resume cycles and permanently lock out
+  // auto-resume after their respective MAX thresholds.
   resetTransientRetryState();
+  resetSessionTimeoutState();
 
   await deps.startAuto(
     ctx as ExtensionCommandContext,

package/src/resources/extensions/gsd/bootstrap/register-extension.ts

@@ -2,9 +2,10 @@
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
 
-import { registerGSDCommand } from "../commands.js";
 import { registerExitCommand } from "../exit-command.js";
 import { registerWorktreeCommand } from "../worktree-command.js";
+import type { GSDEcosystemBeforeAgentStartHandler } from "../ecosystem/gsd-extension-api.js";
+import { loadEcosystemExtensions } from "../ecosystem/loader.js";
 import { registerDbTools } from "./db-tools.js";
 import { registerDynamicTools } from "./dynamic-tools.js";
 import { registerJournalTools } from "./journal-tools.js";
@@ -12,6 +13,7 @@ import { registerQueryTools } from "./query-tools.js";
 import { registerHooks } from "./register-hooks.js";
 import { registerShortcuts } from "./register-shortcuts.js";
 import { writeCrashLog } from "./crash-log.js";
+import { logWarning } from "../workflow-logger.js";
 
 export { writeCrashLog } from "./crash-log.js";
 
@@ -58,12 +60,17 @@ function installEpipeGuard(): void {
 }
 
 export function registerGsdExtension(pi: ExtensionAPI): void {
-  registerGSDCommand(pi);
+  // Note: registerGSDCommand is called by index.ts before this function,
+  // so we intentionally skip it here to avoid double-registration.
   registerWorktreeCommand(pi);
   registerExitCommand(pi);
 
   installEpipeGuard();
 
+  // Ecosystem handlers captured by the GSDExtensionAPI wrapper for the
+  // GSD-owned `before_agent_start` dispatch step (#3338).
+  const ecosystemHandlers: GSDEcosystemBeforeAgentStartHandler[] = [];
+
   pi.registerCommand("kill", {
     description: "Exit GSD immediately (no cleanup)",
     handler: async (_args: string, _ctx: ExtensionCommandContext) => {
@@ -71,10 +78,33 @@ export function registerGsdExtension(pi: ExtensionAPI): void {
     },
   });
 
-  registerDynamicTools(pi);
-  registerDbTools(pi);
-  registerJournalTools(pi);
-  registerQueryTools(pi);
-  registerShortcuts(pi);
-  registerHooks(pi);
+  // Wrap non-critical registrations individually so one failure
+  // doesn't prevent the others from loading.
+  const nonCriticalRegistrations: Array<[string, () => void]> = [
+    ["dynamic-tools", () => registerDynamicTools(pi)],
+    ["db-tools", () => registerDbTools(pi)],
+    ["journal-tools", () => registerJournalTools(pi)],
+    ["query-tools", () => registerQueryTools(pi)],
+    ["shortcuts", () => registerShortcuts(pi)],
+    ["hooks", () => registerHooks(pi, ecosystemHandlers)],
+    ["ecosystem", () => {
+      void loadEcosystemExtensions(pi, ecosystemHandlers).catch((err) => {
+        logWarning(
+          "ecosystem",
+          `loader failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      });
+    }],
+  ];
+
+  for (const [name, register] of nonCriticalRegistrations) {
+    try {
+      register();
+    } catch (err) {
+      logWarning(
+        "bootstrap",
+        `Failed to register ${name}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
 }

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -3,6 +3,10 @@ import { join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 import { isToolCallEventType } from "@gsd/pi-coding-agent";
 
+import type { GSDEcosystemBeforeAgentStartHandler } from "../ecosystem/gsd-extension-api.js";
+import { updateSnapshot } from "../ecosystem/gsd-extension-api.js";
+import { getEcosystemReadyPromise } from "../ecosystem/loader.js";
+
 import { buildMilestoneFileName, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
 import { buildBeforeAgentStartResult } from "./system-context.js";
 import { handleAgentEnd } from "./agent-end-recovery.js";
@@ -35,7 +39,10 @@ async function syncServiceTierStatus(ctx: ExtensionContext): Promise<void> {
   ctx.ui.setStatus("gsd-fast", formatServiceTierFooterStatus(getEffectiveServiceTier(), ctx.model?.id));
 }
 
-export function registerHooks(pi: ExtensionAPI): void {
+export function registerHooks(
+  pi: ExtensionAPI,
+  ecosystemHandlers: GSDEcosystemBeforeAgentStartHandler[],
+): void {
   pi.on("session_start", async (_event, ctx) => {
     initNotificationStore(process.cwd());
     installNotifyInterceptor(ctx);
@@ -45,8 +52,12 @@ export function registerHooks(pi: ExtensionAPI): void {
     resetToolCallLoopGuard();
     resetAskUserQuestionsCache();
     await syncServiceTierStatus(ctx);
-    const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
-    prepareWorkflowMcpForProject(ctx, process.cwd());
+    // Skip MCP auto-prep when running inside an auto-worktree (see session_switch below).
+    const { isInAutoWorktree } = await import("../auto-worktree.js");
+    if (!isInAutoWorktree(process.cwd())) {
+      const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
+      prepareWorkflowMcpForProject(ctx, process.cwd());
+    }
 
     // Apply show_token_cost preference (#1515)
     try {
@@ -87,13 +98,63 @@ export function registerHooks(pi: ExtensionAPI): void {
     resetAskUserQuestionsCache();
     clearDiscussionFlowState();
     await syncServiceTierStatus(ctx);
-    const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
-    prepareWorkflowMcpForProject(ctx, process.cwd());
+    // Skip MCP auto-prep when running inside an auto-worktree. The worktree
+    // already has .mcp.json from createAutoWorktree, and re-running the writer
+    // post-chdir rewrites the file mid-run (non-idempotent due to cwd-relative
+    // CLI path resolution), dirtying the tree and breaking the milestone merge.
+    const { isInAutoWorktree } = await import("../auto-worktree.js");
+    if (!isInAutoWorktree(process.cwd())) {
+      const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
+      prepareWorkflowMcpForProject(ctx, process.cwd());
+    }
     loadToolApiKeys();
   });
 
   pi.on("before_agent_start", async (event, ctx: ExtensionContext) => {
-    return buildBeforeAgentStartResult(event, ctx);
+    // Wait for ecosystem loader to finish (no-op after first turn).
+    await getEcosystemReadyPromise();
+
+    // GSD's own context injection (existing behavior — unchanged).
+    const gsdResult = await buildBeforeAgentStartResult(event, ctx);
+
+    // Refresh the snapshot used by ecosystem getPhase()/getActiveUnit().
+    // deriveState has its own ~100ms cache so this is cheap on repeat calls.
+    try {
+      const state = await deriveState(process.cwd());
+      updateSnapshot(state);
+    } catch {
+      updateSnapshot(null);
+    }
+
+    // Chain ecosystem handlers using pi's runner.ts chaining protocol:
+    // each handler sees the systemPrompt mutated by prior handlers.
+    let currentSystemPrompt = gsdResult?.systemPrompt ?? event.systemPrompt;
+    // `any` because pi's BeforeAgentStartEventResult.message uses an internal
+    // CustomMessage type that's not re-exported (see ecosystem/gsd-extension-api.ts).
+    let lastMessage: any = gsdResult?.message;
+
+    for (const handler of ecosystemHandlers) {
+      try {
+        const r = await handler(
+          { ...event, systemPrompt: currentSystemPrompt },
+          ctx,
+        );
+        if (r?.systemPrompt !== undefined) currentSystemPrompt = r.systemPrompt;
+        if (r?.message) lastMessage = r.message;
+      } catch (err) {
+        safetyLogWarning(
+          "ecosystem",
+          `before_agent_start handler failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+
+    // Compose result. Return undefined if nothing changed (preserves runner contract).
+    if (currentSystemPrompt === event.systemPrompt && !lastMessage) return undefined;
+    return {
+      systemPrompt: currentSystemPrompt !== event.systemPrompt ? currentSystemPrompt : undefined,
+      message: lastMessage,
+    };
   });
 
   pi.on("agent_end", async (event, ctx: ExtensionContext) => {
@@ -125,7 +186,10 @@ export function registerHooks(pi: ExtensionAPI): void {
     await ensureDbOpen();
     const state = await deriveState(basePath);
     if (!state.activeMilestone || !state.activeSlice || !state.activeTask) return;
-    if (state.phase !== "executing") return;
+    // Write checkpoint for ALL phases, not just "executing" — discuss, research,
+    // and planning also carry in-memory state (user answers, gate verification)
+    // that would be lost on compaction (#4258).
+    // if (state.phase !== "executing") return;
 
     const sliceDir = resolveSlicePath(basePath, state.activeMilestone.id, state.activeSlice.id);
     if (!sliceDir) return;
@@ -261,7 +325,7 @@ export function registerHooks(pi: ExtensionAPI): void {
   // ── Safety harness: evidence collection + destructive command warnings ──
   pi.on("tool_call", async (event, ctx) => {
     if (!isAutoActive()) return;
-    safetyRecordToolCall(event.toolName, event.input as Record<string, unknown>);
+    safetyRecordToolCall(event.toolCallId, event.toolName, event.input as Record<string, unknown>);
 
     // Destructive command classification (warn only, never block)
     if (isToolCallEventType("bash", event)) {

package/src/resources/extensions/gsd/cache.ts

@@ -1,6 +1,6 @@
 // GSD Extension — Unified Cache Invalidation
 //
-// Three module-scoped caches exist across the GSD extension:
+// Three module-scoped read caches exist across the GSD extension:
 //   1. State cache (state.ts)  — memoized deriveState() result
 //   2. Path cache  (paths.ts)  — directory listing results (readdirSync)
 //   3. Parse cache (files.ts)  — parsed markdown file results
@@ -8,22 +8,33 @@
 // After any file write that changes .gsd/ contents, all three must be
 // invalidated together to prevent stale reads. This module provides a
 // single function that clears all three atomically.
+//
+// NOTE: The DB `artifacts` table is NOT included here. Earlier versions
+// called clearArtifacts() as part of this bundle (#793), intending to
+// force deriveState() to re-parse from disk when files were edited
+// out-of-band. But invalidateAllCaches() fires on every post-unit pass,
+// so bundling a DESTRUCTIVE `DELETE FROM artifacts` with routine cache
+// invalidation meant every row written by saveArtifactToDb / writeAndStore
+// was wiped within seconds — leaving the milestone completed on disk but
+// the `artifacts` table empty and the agent looping on "file exists but
+// DB record missing" recovery calls. If a call site genuinely needs the
+// artifact table cleared after an out-of-band file mutation, it should
+// invoke clearArtifacts() from gsd-db.js explicitly — do not add it back
+// here.
 
 import { invalidateStateCache } from './state.js';
 import { clearPathCache } from './paths.js';
 import { clearParseCache } from './files.js';
-import { clearArtifacts } from './gsd-db.js';
 
 /**
- * Invalidate all GSD runtime caches in one call.
+ * Invalidate all GSD runtime read caches in one call.
  *
  * Call this after file writes, milestone transitions, merge reconciliation,
  * or any operation that changes .gsd/ contents on disk. Forgetting to clear
- * any single cache causes stale reads (see #431, #793).
+ * any single cache causes stale reads (see #431).
  */
 export function invalidateAllCaches(): void {
   invalidateStateCache();
   clearPathCache();
   clearParseCache();
-  clearArtifacts();
 }

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

@@ -15,7 +15,7 @@ export interface GsdCommandDefinition {
 type CompletionMap = Record<string, readonly GsdCommandDefinition[]>;
 
 export const GSD_COMMAND_DESCRIPTION =
-  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update|fast|mcp|rethink|codebase|notifications";
+  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update|fast|mcp|rethink|codebase|notifications|ship|do|session-report|backlog|pr-branch|add-tests|language";
 
 export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -74,6 +74,13 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "rethink", desc: "Conversational project reorganization — reorder, park, discard, add milestones" },
   { cmd: "workflow", desc: "Custom workflow lifecycle (new, run, list, validate, pause, resume)" },
   { cmd: "codebase", desc: "Generate, refresh, and inspect the codebase map cache (.gsd/CODEBASE.md)" },
+  { cmd: "ship", desc: "Create PR from milestone artifacts and open for review" },
+  { cmd: "do", desc: "Route freeform text to the right GSD command" },
+  { cmd: "session-report", desc: "Session cost, tokens, and work summary" },
+  { cmd: "backlog", desc: "Manage backlog items (add, promote, remove, list)" },
+  { cmd: "pr-branch", desc: "Create clean PR branch filtering .gsd/ commits" },
+  { cmd: "add-tests", desc: "Generate tests for completed slices" },
+  { cmd: "language", desc: "Set or clear the global response language (e.g. /gsd language Chinese)" },
 ];
 
 const NESTED_COMPLETIONS: CompletionMap = {
@@ -244,6 +251,29 @@ const NESTED_COMPLETIONS: CompletionMap = {
     { cmd: "stats", desc: "Show file count, description coverage, and generation time" },
     { cmd: "help", desc: "Show usage and available subcommands" },
   ],
+  ship: [
+    { cmd: "--dry-run", desc: "Preview PR without creating" },
+    { cmd: "--draft", desc: "Open as draft PR" },
+    { cmd: "--base", desc: "Override target branch (default: main)" },
+    { cmd: "--force", desc: "Ship even with pending tasks" },
+  ],
+  "session-report": [
+    { cmd: "--json", desc: "Machine-readable JSON output" },
+    { cmd: "--save", desc: "Save report to .gsd/reports/" },
+  ],
+  backlog: [
+    { cmd: "add", desc: "Add item to backlog" },
+    { cmd: "promote", desc: "Promote backlog item to active slice" },
+    { cmd: "remove", desc: "Remove backlog item" },
+  ],
+  "pr-branch": [
+    { cmd: "--dry-run", desc: "Preview what would be filtered" },
+    { cmd: "--name", desc: "Custom branch name" },
+  ],
+  language: [
+    { cmd: "off",   desc: "Clear the language preference (revert to default)" },
+    { cmd: "clear", desc: "Alias for off — clear the language preference" },
+  ],
 };
 
 function filterOptions(

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

@@ -4,7 +4,7 @@ import type { GSDState } from "../../types.js";
 
 import { computeProgressScore, formatProgressLine } from "../../progress-score.js";
 import { loadEffectiveGSDPreferences, getGlobalGSDPreferencesPath, getProjectGSDPreferencesPath } from "../../preferences.js";
-import { ensurePreferencesFile, handlePrefs, handlePrefsMode, handlePrefsWizard } from "../../commands-prefs-wizard.js";
+import { ensurePreferencesFile, handlePrefs, handlePrefsMode, handlePrefsWizard, handleLanguage } from "../../commands-prefs-wizard.js";
 import { runEnvironmentChecks } from "../../doctor-environment.js";
 import { deriveState } from "../../state.js";
 import { handleCmux } from "../../commands-cmux.js";
@@ -395,6 +395,10 @@ export async function handleCoreCommand(
     await handlePrefs(trimmed.replace(/^prefs\s*/, "").trim(), ctx);
     return true;
   }
+  if (trimmed === "language" || trimmed.startsWith("language ")) {
+    await handleLanguage(trimmed.replace(/^language\s*/, "").trim(), ctx);
+    return true;
+  }
   if (trimmed === "cmux" || trimmed.startsWith("cmux ")) {
     await handleCmux(trimmed.replace(/^cmux\s*/, "").trim(), ctx);
     return true;