gsd-pi 2.78.0 → 2.78.1-dev.8a893322c

package/src/resources/extensions/gsd/bootstrap/subagent-input.ts

@@ -0,0 +1,20 @@
+export function extractSubagentAgentClasses(input: unknown): string[] {
+  if (!input || typeof input !== "object") return [];
+
+  const record = input as Record<string, unknown>;
+  const agentClasses: string[] = [];
+  const addAgentClass = (value: unknown): void => {
+    if (typeof value === "string" && value.trim().length > 0) agentClasses.push(value.trim());
+  };
+  const addFromItems = (value: unknown): void => {
+    if (!Array.isArray(value)) return;
+    for (const item of value) {
+      if (item && typeof item === "object") addAgentClass((item as Record<string, unknown>).agent);
+    }
+  };
+
+  addAgentClass(record.agent);
+  addFromItems(record.tasks);
+  addFromItems(record.chain);
+  return agentClasses;
+}

package/src/resources/extensions/gsd/bootstrap/system-context.ts

@@ -15,7 +15,7 @@ import { resolveGsdRootFile, resolveSliceFile, resolveSlicePath, resolveTaskFile
 import { ensureCodebaseMapFresh, readCodebaseMap } from "../codebase-generator.js";
 import { hasSkillSnapshot, detectNewSkills, formatSkillsXml } from "../skill-discovery.js";
 import { getActiveAutoWorktreeContext } from "../auto-worktree.js";
-import { getActiveWorktreeName, getWorktreeOriginalCwd } from "../worktree-command.js";
+import { getActiveWorktreeName, getWorktreeOriginalCwd } from "../worktree-session-state.js";
 import { deriveState } from "../state.js";
 import { formatOverridesSection, formatShortcut, loadActiveOverrides, loadFile, parseContinue, parseSummary } from "../files.js";
 import { toPosixPath } from "../../shared/mod.js";
@@ -52,6 +52,17 @@ export const BUNDLED_SKILL_TRIGGERS: Array<{ trigger: string; skill: string }> =
   { trigger: "HTTP/REST/GraphQL API design — verbs, status codes, pagination, errors, idempotency, versioning", skill: "api-design" },
   { trigger: "Dependency upgrades — risk-batched, verified between batches, one major per commit", skill: "dependency-upgrade" },
   { trigger: "Agent-first observability — structured logs, persisted failure state, health surfaces, explicit failure modes", skill: "observability" },
+  { trigger: "React/Next.js performance — components, data fetching, bundle optimization, rendering patterns from Vercel Engineering", skill: "react-best-practices" },
+  { trigger: "Core Web Vitals — fix LCP, CLS, INP; layout shifts; page experience optimization", skill: "core-web-vitals" },
+  { trigger: "GitHub Actions CI/CD — write, run, and debug workflow files; live syntax and run monitoring", skill: "github-workflows" },
+  { trigger: "Comprehensive web quality audit — performance, accessibility, SEO, and best-practices (Lighthouse-style)", skill: "web-quality-audit" },
+  { trigger: "Browser automation — open sites, fill forms, click, screenshot, scrape, or test web apps programmatically", skill: "agent-browser" },
+  { trigger: "Review UI code for Web Interface Guidelines compliance — UX, design, and accessibility patterns", skill: "web-design-guidelines" },
+  { trigger: "UI/UX patterns reference — animations, CSS, typography, prefetching, icons (file:line findings)", skill: "userinterface-wiki" },
+  { trigger: "Author or refine a GSD skill — SKILL.md structure, frontmatter, and best practices", skill: "create-skill" },
+  { trigger: "Create or debug a GSD extension — tools, commands, event hooks, custom TUI, providers", skill: "create-gsd-extension" },
+  { trigger: "Author a YAML workflow definition — steps, triggers, and templates", skill: "create-workflow" },
+  { trigger: "Deep code optimization audit — perf anti-patterns, memory leaks, algorithmic complexity, bundle size, I/O, caching, dead code (parallel pattern-based hunt)", skill: "code-optimizer" },
 ];
 
 function buildBundledSkillsTable(): string {
@@ -207,7 +218,14 @@ export async function buildBeforeAgentStartResult(
     ? `\n\n## Subagent Model\n\nWhen spawning subagents via the \`subagent\` tool, always pass \`model: "${subagentModelConfig.primary}"\` in the tool call parameters. Never omit this — always specify it explicitly.`
     : "";
 
-  const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${codebaseBlock}${memoryBlock}${newSkillsBlock}${worktreeBlock}${subagentModelBlock}`;
+  // memoryBlock is FTS-queried against the user prompt and changes per call.
+  // Removing it from `fullSystem` keeps the system-prompt cache breakpoint
+  // stable across calls — the only scoped goal of this fix. The pi-ai
+  // Anthropic adapter additionally cache-marks the last user turn, so the
+  // memoryBlock injected via the context message may itself be cached up to
+  // that boundary; that's orthogonal and unchanged from prior behavior. The
+  // load-bearing win here is preserving the system+tools cache hit. (#5019)
+  const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${codebaseBlock}${newSkillsBlock}${worktreeBlock}${subagentModelBlock}`;
 
   stopContextTimer({
     systemPromptSize: fullSystem.length,
@@ -216,12 +234,7 @@ export async function buildBeforeAgentStartResult(
     hasNewSkills: newSkillsBlock.length > 0,
   });
 
-  // Determine which context message to inject (guided execute takes priority)
-  const contextMessage = injection
-    ? { customType: "gsd-guided-context", content: injection, display: false as const }
-    : forensicsInjection
-      ? { customType: "gsd-forensics", content: forensicsInjection, display: false as const }
-      : null;
+  const contextMessage = buildContextMessage({ memoryBlock, injection, forensicsInjection });
 
   return {
     systemPrompt: fullSystem,
@@ -229,6 +242,35 @@ export async function buildBeforeAgentStartResult(
   };
 }
 
+/**
+ * Route the per-call dynamic blocks (memory, guided-execute, forensics) into a
+ * single user-message context payload so they ride the volatile suffix instead
+ * of the cached system prefix. Priority when both memory and an injection are
+ * present: guided > forensics > memory-only. (#5019)
+ *
+ * Exported for direct unit testing — the surrounding bootstrap has too many
+ * filesystem and DB dependencies to exercise this routing logic in-place.
+ */
+export function buildContextMessage(opts: {
+  memoryBlock: string;
+  injection: string | null;
+  forensicsInjection: string | null;
+}): { customType: string; content: string; display: false } | null {
+  const memoryContent = opts.memoryBlock.trim();
+  if (opts.injection) {
+    const content = memoryContent ? `${memoryContent}\n\n${opts.injection}` : opts.injection;
+    return { customType: "gsd-guided-context", content, display: false as const };
+  }
+  if (opts.forensicsInjection) {
+    const content = memoryContent ? `${memoryContent}\n\n${opts.forensicsInjection}` : opts.forensicsInjection;
+    return { customType: "gsd-forensics", content, display: false as const };
+  }
+  if (memoryContent) {
+    return { customType: "gsd-memory", content: memoryContent, display: false as const };
+  }
+  return null;
+}
+
 /**
  * ADR-013 step 4 — auto-injection parity for the memories table.
  *

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

@@ -3,15 +3,8 @@ import { isAbsolute, join, relative, resolve, sep } from "node:path";
 
 import { minimatch } from "minimatch";
 
-/**
- * Declarative tools-policy for a unit. Inlined here because the worktree
- * branch predates the full unit-context-manifest export (#4934).
- */
-export type ToolsPolicy =
-  | { mode: "all" }
-  | { mode: "read-only" }
-  | { mode: "planning" }
-  | { mode: "docs"; allowedPathGlobs: readonly string[] };
+import type { ToolsPolicy } from "../unit-context-manifest.js";
+import { logWarning } from "../workflow-logger.js";
 
 /**
  * Regex matching milestone CONTEXT.md file names in both legacy M001
@@ -535,10 +528,76 @@ export function shouldBlockQueueExecutionInSnapshot(
 }
 
 // ─── Planning-unit tools-policy enforcement (#4934) ───────────────────────
+//
+// Runtime half of the declarative ToolsPolicy on UnitContextManifest. The
+// manifest assigns each unit type a tools mode; this predicate is what
+// actually rejects a tool call that violates it.
+//
+// Forensics: a discuss-milestone LLM turn used the host Edit tool to modify
+// index.html in test app b23 (~/Github/test-apps/b23). With this predicate
+// wired into the tool_call hook, the same call returns block=true with a
+// HARD BLOCK reason that the model cannot rationalize past.
+//
+// Activation: the hook supplies the policy resolved from the active unit's
+// manifest. When no unit is active (interactive sessions, unknown unit
+// types), the hook passes null and this predicate is a no-op — falling
+// through to the existing pendingGate / queue-execution / context-write
+// guards.
 
 const PLANNING_WRITE_TOOLS = new Set(["write", "edit", "multi_edit", "notebook_edit"]);
 const PLANNING_SUBAGENT_TOOLS = new Set(["subagent", "task"]);
 
+/**
+ * Canonical registry for agents that planning-dispatch may consider. Unit
+ * manifests still declare per-unit subsets via ToolsPolicy.allowedSubagents.
+ */
+const PLANNING_DISPATCH_AGENT_REGISTRY = {
+  scout: { readOnlySpecialist: true },
+  planner: { readOnlySpecialist: true },
+  reviewer: { readOnlySpecialist: true },
+  security: { readOnlySpecialist: true },
+  tester: { readOnlySpecialist: true },
+} as const satisfies Record<string, { readonly readOnlySpecialist: boolean }>;
+
+export const ALLOWED_PLANNING_DISPATCH_AGENTS = new Set<string>(
+  Object.entries(PLANNING_DISPATCH_AGENT_REGISTRY)
+    .filter(([, metadata]) => metadata.readOnlySpecialist)
+    .map(([agentId]) => agentId),
+);
+
+let warnedMissingPlanningDispatchAgentClasses = false;
+
+function isReadOnlySpecialist(agentId: string): boolean {
+  const metadata = PLANNING_DISPATCH_AGENT_REGISTRY[agentId as keyof typeof PLANNING_DISPATCH_AGENT_REGISTRY];
+  return metadata?.readOnlySpecialist === true;
+}
+
+function allowedPlanningDispatchAgentsList(): string {
+  return [...ALLOWED_PLANNING_DISPATCH_AGENTS].join(", ");
+}
+
+function warnMissingPlanningDispatchAgentClasses(unitType: string, mode: string, toolName: string): void {
+  if (warnedMissingPlanningDispatchAgentClasses) return;
+  warnedMissingPlanningDispatchAgentClasses = true;
+  // TODO(#5060): Remove this migration shim once all subagent/task callers are verified to forward agent identities.
+  const message = `[write-gate] planning-dispatch: shouldBlockPlanningUnit called for tool "${toolName}" ` +
+    `on unit "${unitType}" without agentClasses - stale caller; blocking dispatch.`;
+  console.warn(message);
+  logWarning("intercept", message, {
+    unitType,
+    mode,
+    toolName,
+  });
+}
+
+/**
+ * Read-only / planning-safe tools that any non-"all" mode allows. Mirrors
+ * QUEUE_SAFE_TOOLS / GATE_SAFE_TOOLS but is the inclusive default for
+ * planning units (which need their full discussion + research surface).
+ *
+ * gsd_* MCP tools are passed through unconditionally — they have their own
+ * domain validation (e.g. depth-verification gate, single-writer DB).
+ */
 const PLANNING_SAFE_TOOLS = new Set([
   "read", "grep", "find", "ls", "glob",
   "ask_user_questions",
@@ -555,6 +614,7 @@ function isPathUnderGsd(absPath: string, basePath: string): boolean {
 function matchesAllowedGlob(absPath: string, basePath: string, globs: readonly string[]): boolean {
   const rel = relative(basePath, absPath);
   if (rel.startsWith("..") || isAbsolute(rel)) return false;
+  // Normalize Windows separators for minimatch.
   const posix = rel.split(sep).join("/");
   return globs.some(g => minimatch(posix, g, { dot: false, nocase: false }));
 }
@@ -576,10 +636,24 @@ function blockReason(unitType: string, mode: string, what: string): string {
  *   - "read-only"  → blocks all writes, bash, and subagent dispatch.
  *   - "planning"   → blocks writes to paths outside <basePath>/.gsd/,
  *                    bash that isn't read-only, and subagent dispatch.
+ *   - "planning-dispatch"
+ *                  → like "planning", but permits subagent dispatch only
+ *                    when every forwarded agent class is globally allowed
+ *                    and listed in the policy's allowedSubagents.
  *   - "docs"       → like "planning" but also allows writes to paths
  *                    matching `allowedPathGlobs` relative to basePath.
  *
- * `policy` of null means "no manifest resolved" — pass-through.
+ * `pathOrCommand` is the file path for write/edit-shaped tools and the
+ * shell command for bash. Other tools ignore this argument.
+ *
+ * `policy` of null means "no manifest resolved" — pass-through. Callers
+ * that have no active unit (interactive sessions) pass null and this
+ * predicate is a no-op.
+ *
+ * `agentClasses` is supplied by the tool hook for subagent-shaped calls. If
+ * absent, planning-dispatch fails closed so stale callers cannot silently
+ * bypass the agent allowlists. An explicitly supplied-but-empty list is
+ * allowed through so the downstream tool call can reject the malformed input.
  */
 export function shouldBlockPlanningUnit(
   toolName: string,
@@ -587,26 +661,77 @@ export function shouldBlockPlanningUnit(
   basePath: string,
   unitType: string,
   policy: ToolsPolicy | null | undefined,
+  agentClasses?: readonly string[],
 ): { block: boolean; reason?: string } {
   if (!policy) return { block: false };
   if (policy.mode === "all") return { block: false };
 
   const tool = toolName;
 
+  // Read-only mode: only Read-class tools are permitted.
   if (policy.mode === "read-only") {
     if (PLANNING_SAFE_TOOLS.has(tool)) return { block: false };
     if (tool.startsWith("gsd_")) return { block: false };
     if (PLANNING_WRITE_TOOLS.has(tool) || tool === "bash" || PLANNING_SUBAGENT_TOOLS.has(tool)) {
       return { block: true, reason: blockReason(unitType, policy.mode, `${tool} is not permitted (read-only)`) };
     }
+    // Unknown tool in read-only mode — block by default.
     return { block: true, reason: blockReason(unitType, policy.mode, `tool "${tool}" is not on the read-only allowlist`) };
   }
 
-  // planning / docs modes
+  // planning / planning-dispatch / docs modes share the same surface for safe tools, bash, and subagent.
   if (PLANNING_SAFE_TOOLS.has(tool)) return { block: false };
   if (tool.startsWith("gsd_")) return { block: false };
 
   if (PLANNING_SUBAGENT_TOOLS.has(tool)) {
+    if (policy.mode === "planning-dispatch") {
+      const requested = (agentClasses ?? []).map(a => a.trim()).filter(Boolean);
+      const allowedSubagents = Array.isArray(policy.allowedSubagents) ? policy.allowedSubagents : [];
+      const allowed = new Set(allowedSubagents);
+      // When agentClasses is undefined, the caller has not been updated to extract
+      // agent identities yet. Block and warn so stale callers surface in telemetry
+      // instead of silently bypassing the gate.
+      if (agentClasses === undefined) {
+        warnMissingPlanningDispatchAgentClasses(unitType, policy.mode, tool);
+        return {
+          block: true,
+          reason: blockReason(
+            unitType,
+            policy.mode,
+            `subagent dispatch blocked: stale caller did not supply agent identities for "${tool}"; update extractSubagentAgentClasses to handle this input shape`,
+          ),
+        };
+      }
+      // agentClasses was explicitly provided but resolved to an empty list (for
+      // example, a bare tool call with no agent field). Pass through; no agents
+      // to validate means the downstream tool call itself will fail.
+      if (requested.length === 0) {
+        return { block: false };
+      }
+      const globallyDisallowed = requested.find(a => !isReadOnlySpecialist(a));
+      if (globallyDisallowed) {
+        return {
+          block: true,
+          reason: blockReason(
+            unitType,
+            policy.mode,
+            `subagent dispatch of "${globallyDisallowed}" not permitted; only read-only specialists (${allowedPlanningDispatchAgentsList()}) may be dispatched from planning-dispatch units`,
+          ),
+        };
+      }
+      const disallowedByPolicy = requested.find(a => !allowed.has(a));
+      if (disallowedByPolicy) {
+        return {
+          block: true,
+          reason: blockReason(
+            unitType,
+            policy.mode,
+            `subagent dispatch of "${disallowedByPolicy}" not permitted by ToolsPolicy.allowedSubagents; permitted agents for this unit: ${allowedSubagents.join(", ")}`,
+          ),
+        };
+      }
+      return { block: false };
+    }
     return { block: true, reason: blockReason(unitType, policy.mode, `subagent dispatch is not permitted in planning units`) };
   }
 
@@ -628,8 +753,10 @@ export function shouldBlockPlanningUnit(
     }
     const absPath = isAbsolute(pathOrCommand) ? pathOrCommand : resolve(basePath, pathOrCommand);
 
+    // Always allow .gsd/ writes — that's where planning artifacts live.
     if (isPathUnderGsd(absPath, basePath)) return { block: false };
 
+    // docs mode additionally allows the manifest's allowedPathGlobs.
     if (policy.mode === "docs" && matchesAllowedGlob(absPath, basePath, policy.allowedPathGlobs)) {
       return { block: false };
     }
@@ -644,5 +771,8 @@ export function shouldBlockPlanningUnit(
     };
   }
 
+  // Unknown tool name — pass through. Other layers (queue, pending-gate,
+  // CONTEXT.md write) catch known mutating shapes; defaulting to allow here
+  // avoids breaking gsd_* MCP tools or future safe additions.
   return { block: false };
 }

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

@@ -1,9 +1,8 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 
 import { loadRegistry } from "../workflow-templates.js";
-import { resolveProjectRoot } from "../worktree.js";
 
 const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 
@@ -15,7 +14,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|debug|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|onboarding|inspect|extensions|update|fast|mcp|rethink|codebase|notifications|ship|do|session-report|backlog|pr-branch|add-tests|scan|language";
+  "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|debug|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|onboarding|inspect|extensions|update|fast|mcp|rethink|workflow|codebase|notifications|ship|do|session-report|backlog|pr-branch|add-tests|scan|language|worktree";
 
 export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -84,6 +83,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "add-tests", desc: "Generate tests for completed slices" },
   { cmd: "scan", desc: "Rapid codebase assessment — lightweight alternative to full map (--focus tech|arch|quality|concerns|tech+arch)" },
   { 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)" },
 ];
 
 const NESTED_COMPLETIONS: CompletionMap = {
@@ -300,6 +300,12 @@ const NESTED_COMPLETIONS: CompletionMap = {
     { cmd: "off",   desc: "Clear the language preference (revert to default)" },
     { cmd: "clear", desc: "Alias for off — clear the language preference" },
   ],
+  worktree: [
+    { cmd: "list",   desc: "Show all worktrees with status" },
+    { cmd: "merge",  desc: "Merge a worktree into main and clean up" },
+    { cmd: "clean",  desc: "Remove all merged/empty worktrees" },
+    { cmd: "remove", desc: "Remove a worktree (--force to skip safety checks)" },
+  ],
 };
 
 function filterOptions(
@@ -346,6 +352,77 @@ function getExtensionCompletions(prefix: string, action: string) {
   }
 }
 
+function normalizePathForCompare(path: string): string {
+  return path.replaceAll("\\", "/").replace(/\/+$/, "");
+}
+
+function findWorktreeSegment(normalizedPath: string): { gsdIdx: number; afterWorktrees: number } | null {
+  const directMarker = "/.gsd/worktrees/";
+  const directIdx = normalizedPath.indexOf(directMarker);
+  if (directIdx !== -1) {
+    return { gsdIdx: directIdx, afterWorktrees: directIdx + directMarker.length };
+  }
+
+  const symlinkMatch = normalizedPath.match(/\/\.gsd\/projects\/[a-f0-9]+\/worktrees\//);
+  if (symlinkMatch?.index !== undefined) {
+    return { gsdIdx: symlinkMatch.index, afterWorktrees: symlinkMatch.index + symlinkMatch[0].length };
+  }
+
+  return null;
+}
+
+function resolveProjectRootFromGitFile(worktreePath: string): string | null {
+  try {
+    let dir = worktreePath;
+    for (let i = 0; i < 30; i++) {
+      const gitPath = join(dir, ".git");
+      if (existsSync(gitPath)) {
+        const content = readFileSync(gitPath, "utf8").trim();
+        if (content.startsWith("gitdir: ")) {
+          const gitDir = resolve(dir, content.slice(8));
+          const dotGitDir = resolve(gitDir, "..", "..");
+          if (dotGitDir.endsWith(".git") || dotGitDir.endsWith(".git/") || dotGitDir.endsWith(".git\\")) {
+            return resolve(dotGitDir, "..");
+          }
+          const commonDirPath = join(gitDir, "commondir");
+          if (existsSync(commonDirPath)) {
+            const commonDir = readFileSync(commonDirPath, "utf8").trim();
+            return resolve(resolve(gitDir, commonDir), "..");
+          }
+        }
+        break;
+      }
+      const parent = resolve(dir, "..");
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch {
+    // Completion must stay best-effort.
+  }
+  return null;
+}
+
+function resolveProjectRootForCompletion(basePath: string): string {
+  if (process.env.GSD_PROJECT_ROOT) return process.env.GSD_PROJECT_ROOT;
+
+  const normalizedPath = normalizePathForCompare(basePath);
+  const segment = findWorktreeSegment(normalizedPath);
+  if (!segment) return basePath;
+
+  const separator = basePath.includes("\\") ? "\\" : "/";
+  const gsdMarker = `${separator}.gsd${separator}`;
+  const gsdIdx = basePath.indexOf(gsdMarker);
+  const candidate = gsdIdx !== -1 ? basePath.slice(0, gsdIdx) : basePath.slice(0, segment.gsdIdx);
+
+  const normalizedGsdHome = normalizePathForCompare(gsdHome);
+  const candidateGsdPath = normalizePathForCompare(join(candidate, ".gsd"));
+  if (candidateGsdPath === normalizedGsdHome || candidateGsdPath.startsWith(`${normalizedGsdHome}/`)) {
+    return resolveProjectRootFromGitFile(basePath) ?? basePath;
+  }
+
+  return candidate;
+}
+
 export function getGsdArgumentCompletions(prefix: string) {
   const hasTrailingSpace = prefix.endsWith(" ");
   const parts = prefix.trim().split(/\s+/);
@@ -406,7 +483,7 @@ export function getGsdArgumentCompletions(prefix: string) {
   // Workflow definition-name completion for `workflow run <name>` and `workflow validate <name>`
   if (command === "workflow" && (subcommand === "run" || subcommand === "validate") && parts.length <= 3) {
     try {
-      const defsDir = join(resolveProjectRoot(process.cwd()), ".gsd", "workflow-defs");
+      const defsDir = join(resolveProjectRootForCompletion(process.cwd()), ".gsd", "workflow-defs");
       if (existsSync(defsDir)) {
         return readdirSync(defsDir)
           .filter((f) => f.endsWith(".yaml") && f.startsWith(third))
@@ -443,7 +520,7 @@ export function getGsdArgumentCompletions(prefix: string) {
       } catch { /* ignore */ }
     };
     try {
-      const base = resolveProjectRoot(process.cwd());
+      const base = resolveProjectRootForCompletion(process.cwd());
       scanDir(join(base, ".gsd", "workflows"), "project");
       scanDir(join(base, ".gsd", "workflow-defs"), "project-legacy");
       scanDir(join(gsdHome, "workflows"), "global");

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

@@ -64,16 +64,21 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     "  /gsd pause          Pause auto-mode (preserves state, /gsd auto to resume)",
     "  /gsd discuss        Start guided milestone/slice discussion",
     "  /gsd new-milestone  Create milestone from headless context (used by gsd headless)",
+    "  /gsd quick          Execute a quick task without full planning overhead",
+    "  /gsd dispatch       Dispatch a specific phase directly  [research|plan|execute|complete|uat|replan]",
+    "  /gsd parallel       Parallel milestone orchestration  [start|status|stop|pause|resume|merge|watch]",
+    "  /gsd workflow       Custom workflow lifecycle  [new|run|list|validate|pause|resume]",
     "",
     "VISIBILITY",
     `  /gsd status         Show progress dashboard  (${formattedShortcutPair("dashboard")})`,
     `  /gsd parallel watch Open parallel worker monitor  (${formattedShortcutPair("parallel")})`,
+    "  /gsd widget         Cycle status widget  [full|small|min|off]",
     "  /gsd visualize      Interactive 10-tab TUI (progress, timeline, deps, metrics, health, agent, changes, knowledge, captures, export)",
     "  /gsd queue          Show queued/dispatched units and execution order",
     "  /gsd history        View execution history  [--cost] [--phase] [--model] [N]",
     "  /gsd changelog      Show categorized release notes  [version]",
     `  /gsd notifications  View persistent notification history  [clear|tail|filter]  (${formattedShortcutPair("notifications")})`,
-    "  /gsd logs           Browse activity logs, debug logs, and metrics",
+    "  /gsd logs           Browse activity logs, debug logs, and metrics  [debug|tail|clear]",
     "  /gsd debug          Create/list/continue persistent debug sessions",
     "",
     "COURSE CORRECTION",
@@ -82,6 +87,9 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     "  /gsd triage         Classify and route pending captures",
     "  /gsd skip <unit>    Prevent a unit from auto-mode dispatch",
     "  /gsd undo           Revert last completed unit  [--force]",
+    "  /gsd undo-task      Reset a specific task's completion state  [DB + markdown]",
+    "  /gsd reset-slice    Reset a slice and all its tasks  [DB + markdown]",
+    "  /gsd rate           Rate last unit's model tier  [over|ok|under]",
     "  /gsd rethink        Conversational project reorganization — reorder, park, discard, add milestones",
     "  /gsd park [id]      Park a milestone — skip without deleting  [reason]",
     "  /gsd unpark [id]    Reactivate a parked milestone",
@@ -90,6 +98,15 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     "  /gsd knowledge <type> <text>   Add rule, pattern, or lesson to KNOWLEDGE.md",
     "  /gsd codebase [generate|update|stats]   Manage the CODEBASE.md cache used in prompt context",
     "",
+    "SHIPPING & BACKLOG",
+    "  /gsd ship           Create a PR from milestone artifacts  [--dry-run|--draft|--base|--force]",
+    "  /gsd do <text>      Route freeform text to the right GSD command",
+    "  /gsd session-report Show session cost, tokens, and work summary  [--json|--save]",
+    "  /gsd backlog        Manage backlog items  [add|promote|remove|list]",
+    "  /gsd pr-branch      Create a clean PR branch filtering .gsd/ commits  [--dry-run|--name]",
+    "  /gsd add-tests      Generate tests for completed slices",
+    "  /gsd scan           Rapid codebase assessment  [--focus tech|arch|quality|concerns|tech+arch]",
+    "",
     "SETUP & CONFIGURATION",
     "  /gsd onboarding     Re-run setup wizard  [--resume|--reset|--step <name>]",
     "  /gsd setup          Configuration hub  [llm|model|search|remote|keys|prefs|onboarding]",
@@ -102,18 +119,23 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     "  /gsd config         (deprecated) Set tool API keys — use /gsd keys instead",
     "  /gsd show-config    Show effective configuration (models, routing, toggles)",
     "  /gsd hooks          Show post-unit hook configuration",
+    "  /gsd run-hook       Manually trigger a specific hook",
+    "  /gsd skill-health   Skill lifecycle dashboard",
     "  /gsd extensions     Manage extensions  [list|enable|disable|info]",
     "  /gsd fast           Toggle OpenAI service tier  [on|off|flex|status]",
     "  /gsd mcp            MCP server status and connectivity  [status|check <server>|init [dir]]",
     "",
     "MAINTENANCE",
     "  /gsd doctor         Diagnose and repair .gsd/ state  [audit|fix|heal] [scope]",
+    "  /gsd forensics      Examine execution logs and post-mortem analysis",
     "  /gsd export         Export milestone/slice results  [--json|--markdown|--html] [--all]",
     "  /gsd cleanup        Remove merged branches or snapshots  [branches|snapshots]",
+    "  /gsd worktree       Manage worktrees from the TUI  [list|merge|clean|remove]",
     "  /gsd migrate        Migrate .planning/ (v1) to .gsd/ (v2) format",
     "  /gsd remote         Control remote auto-mode  [slack|discord|status|disconnect]",
     "  /gsd inspect        Show SQLite DB diagnostics (schema, row counts, recent entries)",
     "  /gsd update         Update GSD to the latest version via npm",
+    "  /gsd language       Set or clear the global response language  [off|clear|<language>]",
   ];
   const full = ["full", "--full", "all"].includes(args.trim().toLowerCase());
   ctx.ui.notify((full ? fullLines : summaryLines).join("\n"), "info");

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

@@ -262,5 +262,15 @@ Examples:
     await handleScan(trimmed.replace(/^scan\s*/, "").trim(), ctx, pi);
     return true;
   }
+  if (
+    trimmed === "worktree" ||
+    trimmed.startsWith("worktree ") ||
+    trimmed === "wt" ||
+    trimmed.startsWith("wt ")
+  ) {
+    const { handleWorktree } = await import("../../commands-worktree.js");
+    await handleWorktree(trimmed.replace(/^(worktree|wt)\s*/, "").trim(), ctx);
+    return true;
+  }
   return false;
 }

package/src/resources/extensions/gsd/commands-config.ts

@@ -8,6 +8,7 @@ import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
 import { AuthStorage } from "@gsd/pi-coding-agent";
 import { existsSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
+import { getHomeDir } from "./home-dir.js";
 
 /**
  * Tool API key configurations.
@@ -34,7 +35,7 @@ function getStoredToolKey(auth: AuthStorage, providerId: string): string | undef
  */
 export function loadToolApiKeys(): void {
   try {
-    const authPath = join(process.env.HOME ?? "", ".gsd", "agent", "auth.json");
+    const authPath = join(getHomeDir(), ".gsd", "agent", "auth.json");
     if (!existsSync(authPath)) return;
 
     const auth = AuthStorage.create(authPath);
@@ -50,7 +51,7 @@ export function loadToolApiKeys(): void {
 }
 
 export function getConfigAuthStorage(): AuthStorage {
-  const authPath = join(process.env.HOME ?? "", ".gsd", "agent", "auth.json");
+  const authPath = join(getHomeDir(), ".gsd", "agent", "auth.json");
   mkdirSync(dirname(authPath), { recursive: true });
   return AuthStorage.create(authPath);
 }

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

@@ -12,7 +12,47 @@ import { dirname, join, resolve } from "node:path";
 import { homedir, tmpdir } from "node:os";
 import { execFileSync } from "node:child_process";
 import { lockSync, unlockSync } from "proper-lockfile";
-import semver from "semver";
+
+/**
+ * Strict numeric comparison of two npm-style version strings.
+ *
+ * Returns true when `a` is strictly greater than `b`. Compares the dotted
+ * release components numerically (so `1.10.0` > `1.9.0`) and treats any
+ * prerelease suffix (`-beta.1`, `-rc.2`) as less than the equivalent
+ * release version (`1.0.0` > `1.0.0-beta.1`). Sufficient for npm package
+ * version comparison in the extension installer; we don't need the full
+ * semver range/intersect machinery here.
+ *
+ * Replaces the earlier `import semver from "semver"` — that import broke
+ * `tsc -p tsconfig.json` whenever `@types/semver` failed to install
+ * (Issue #4946) because the file is pulled in transitively despite being
+ * under the `src/resources` exclude.
+ */
+export function isVersionGreater(a: string, b: string): boolean {
+  const split = (v: string): { release: number[]; pre: string | null } => {
+    const dash = v.indexOf("-");
+    const release = (dash === -1 ? v : v.slice(0, dash))
+      .split(".")
+      .map(part => Number.parseInt(part, 10) || 0);
+    const pre = dash === -1 ? null : v.slice(dash + 1);
+    return { release, pre };
+  };
+  const sa = split(a);
+  const sb = split(b);
+  const len = Math.max(sa.release.length, sb.release.length);
+  for (let i = 0; i < len; i++) {
+    const ai = sa.release[i] ?? 0;
+    const bi = sb.release[i] ?? 0;
+    if (ai !== bi) return ai > bi;
+  }
+  // Release components equal — a release version beats any prerelease,
+  // and prerelease strings are compared lexicographically (good enough
+  // for `beta.1` vs `beta.2`, the only realistic case here).
+  if (sa.pre === null && sb.pre !== null) return true;
+  if (sa.pre !== null && sb.pre === null) return false;
+  if (sa.pre !== null && sb.pre !== null) return sa.pre > sb.pre;
+  return false;
+}
 
 const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 
@@ -538,7 +578,7 @@ async function updateSingleExtension(
     return;
   }
 
-  if (semver.gt(latest, current)) {
+  if (isVersionGreater(latest, current)) {
     ctx.ui.notify(`Updating "${id}": v${current} → v${latest}...`, "info");
     await handleInstall(packageName, ctx);
   } else {
@@ -599,7 +639,7 @@ async function updateAllExtensions(
       continue;
     }
 
-    if (semver.gt(latest, current)) {
+    if (isVersionGreater(latest, current)) {
       ctx.ui.notify(`  ${entry.id}: v${current} → v${latest} (updating)`, "info");
       await handleInstall(packageName, ctx);
       updated++;