gsd-pi 2.74.0-dev.2b524c3 → 2.74.0-dev.703eabc

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.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/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);
@@ -93,7 +100,50 @@ export function registerHooks(pi: ExtensionAPI): void {
   });
 
   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 +175,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;

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";
 
 export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -74,6 +74,12 @@ 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" },
 ];
 
 const NESTED_COMPLETIONS: CompletionMap = {
@@ -244,6 +250,25 @@ 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" },
+  ],
 };
 
 function filterOptions(

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

@@ -11,6 +11,9 @@ import { handleExport } from "../../export.js";
 import { handleHistory } from "../../history.js";
 import { handleUndo } from "../../undo.js";
 import { handleRemote } from "../../../remote-questions/mod.js";
+import { handleShip } from "../../commands-ship.js";
+import { handleSessionReport } from "../../commands-session-report.js";
+import { handlePrBranch } from "../../commands-pr-branch.js";
 import { projectRoot } from "../context.js";
 
 export async function handleOpsCommand(trimmed: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<boolean> {
@@ -216,5 +219,27 @@ Examples:
     await handleCodebase(trimmed.replace(/^codebase\s*/, "").trim(), ctx, pi);
     return true;
   }
+  if (trimmed === "ship" || trimmed.startsWith("ship ")) {
+    await handleShip(trimmed.replace(/^ship\s*/, "").trim(), ctx, pi);
+    return true;
+  }
+  if (trimmed === "session-report" || trimmed.startsWith("session-report ")) {
+    await handleSessionReport(trimmed.replace(/^session-report\s*/, "").trim(), ctx);
+    return true;
+  }
+  if (trimmed === "pr-branch" || trimmed.startsWith("pr-branch ")) {
+    await handlePrBranch(trimmed.replace(/^pr-branch\s*/, "").trim(), ctx);
+    return true;
+  }
+  if (trimmed === "add-tests" || trimmed.startsWith("add-tests ")) {
+    const { handleAddTests } = await import("../../commands-add-tests.js");
+    await handleAddTests(trimmed.replace(/^add-tests\s*/, "").trim(), ctx, pi);
+    return true;
+  }
+  if (trimmed === "extract-learnings" || trimmed.startsWith("extract-learnings ")) {
+    const { handleExtractLearnings } = await import("../../commands-extract-learnings.js");
+    await handleExtractLearnings(trimmed.replace(/^extract-learnings\s*/, "").trim(), ctx, pi);
+    return true;
+  }
   return false;
 }

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

@@ -38,6 +38,67 @@ const WORKFLOW_USAGE = [
   "  resume            — Resume paused custom workflow auto-mode",
 ].join("\n");
 
+function splitWorkflowRunArgs(input: string): string[] {
+  const tokens: string[] = [];
+  let current = "";
+  let quote: '"' | "'" | null = null;
+  let escapeNext = false;
+
+  for (const ch of input) {
+    if (escapeNext) {
+      current += ch;
+      escapeNext = false;
+      continue;
+    }
+
+    if (ch === "\\") {
+      escapeNext = true;
+      continue;
+    }
+
+    if (quote) {
+      if (ch === quote) {
+        quote = null;
+      } else {
+        current += ch;
+      }
+      continue;
+    }
+
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+
+    if (/\s/.test(ch)) {
+      if (current) {
+        tokens.push(current);
+        current = "";
+      }
+      continue;
+    }
+
+    current += ch;
+  }
+
+  if (escapeNext) current += "\\";
+  if (current) tokens.push(current);
+  return tokens;
+}
+
+export function parseWorkflowRunArgs(args: string): { defName: string; overrides: Record<string, string> } {
+  const parts = splitWorkflowRunArgs(args);
+  const defName = parts[0] ?? "";
+  const overrides: Record<string, string> = {};
+  for (let i = 1; i < parts.length; i++) {
+    const eqIdx = parts[i].indexOf("=");
+    if (eqIdx > 0) {
+      overrides[parts[i].slice(0, eqIdx)] = parts[i].slice(eqIdx + 1);
+    }
+  }
+  return { defName, overrides };
+}
+
 async function handleCustomWorkflow(
   sub: string,
   ctx: ExtensionCommandContext,
@@ -62,15 +123,7 @@ async function handleCustomWorkflow(
       ctx.ui.notify("Usage: /gsd workflow run <name> [param=value ...]", "warning");
       return true;
     }
-    const parts = args.split(/\s+/);
-    const defName = parts[0];
-    const overrides: Record<string, string> = {};
-    for (let i = 1; i < parts.length; i++) {
-      const eqIdx = parts[i].indexOf("=");
-      if (eqIdx > 0) {
-        overrides[parts[i].slice(0, eqIdx)] = parts[i].slice(eqIdx + 1);
-      }
-    }
+    const { defName, overrides } = parseWorkflowRunArgs(args);
     try {
       const base = projectRoot();
       const runDir = createRun(base, defName, Object.keys(overrides).length > 0 ? overrides : undefined);
@@ -168,6 +221,18 @@ async function handleCustomWorkflow(
 }
 
 export async function handleWorkflowCommand(trimmed: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<boolean> {
+  // ── /gsd do — natural language routing (must be early to route to other commands) ──
+  if (trimmed === "do" || trimmed.startsWith("do ")) {
+    const { handleDo } = await import("../../commands-do.js");
+    await handleDo(trimmed.replace(/^do\s*/, "").trim(), ctx, pi);
+    return true;
+  }
+  // ── Backlog management ──
+  if (trimmed === "backlog" || trimmed.startsWith("backlog ")) {
+    const { handleBacklog } = await import("../../commands-backlog.js");
+    await handleBacklog(trimmed.replace(/^backlog\s*/, "").trim(), ctx, pi);
+    return true;
+  }
   // ── Custom workflow commands (`/gsd workflow ...`) ──
   if (trimmed === "workflow" || trimmed.startsWith("workflow ")) {
     const sub = trimmed.slice("workflow".length).trim();