@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.5fc22c6f

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

@@ -10,10 +10,15 @@
 
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { join, dirname, extname } from "node:path";
+import { join, dirname, extname, relative, sep } from "node:path";
 
 import { execSync } from "node:child_process";
 import { gsdRoot } from "./paths.js";
+import {
+  createRepositoryRegistryFromPreferences,
+  type RepositoryRegistry,
+} from "./repository-registry.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -28,6 +33,8 @@ export interface CodebaseMapMetadata {
   fingerprint: string;
   fileCount: number;
   truncated: boolean;
+  /** Repo ids whose files appear in a workspace-aware map (parent mode only). */
+  repositories?: string[];
 }
 
 export interface EnsureCodebaseMapOptions {
@@ -48,12 +55,16 @@ export interface EnsureCodebaseMapResult {
 interface FileEntry {
   path: string;
   description: string;
+  /** Declaring repo id for workspace-aware maps (parent mode); undefined otherwise. */
+  repo?: string;
 }
 
 interface DirectoryGroup {
   path: string;
   files: FileEntry[];
   collapsed: boolean;
+  /** Repo id this group belongs to for workspace-aware maps; undefined otherwise. */
+  repo?: string;
 }
 
 interface ResolvedCodebaseMapOptions {
@@ -66,6 +77,8 @@ interface ResolvedCodebaseMapOptions {
 interface EnumeratedFiles {
   files: string[];
   truncated: boolean;
+  /** Per-file repo labels aligned with `files` (workspace-aware maps only). */
+  repos?: string[];
 }
 
 // ─── Defaults ────────────────────────────────────────────────────────────────
@@ -209,13 +222,99 @@ function lsFiles(basePath: string): string[] {
  * Enumerate tracked files, applying exclusions and the maxFiles cap.
  * Returns both the file list and whether truncation occurred.
  */
-function enumerateFiles(basePath: string, excludes: string[], maxFiles: number): { files: string[]; truncated: boolean } {
+function enumerateFiles(basePath: string, excludes: string[], maxFiles: number): EnumeratedFiles {
   const allFiles = lsFiles(basePath);
   const filtered = allFiles.filter((f) => !shouldExclude(f, excludes));
   const truncated = filtered.length > maxFiles;
   return { files: truncated ? filtered.slice(0, maxFiles) : filtered, truncated };
 }
 
+/**
+ * Build a workspace-aware registry for parent mode, or null when the project is
+ * single-repo (no declared child repositories). Returns null so the caller falls
+ * back to the legacy single-root enumeration and produces byte-identical output.
+ */
+function loadWorkspaceRegistry(basePath: string): RepositoryRegistry | null {
+  const preferences = loadEffectiveGSDPreferences(basePath)?.preferences;
+  const workspace = preferences?.workspace;
+  const mode = workspace?.mode ?? "project";
+  // Parent mode is only meaningful with at least one declared child repo; the
+  // implicit "project" repo is always present, so require a declared non-project id.
+  const hasDeclaredChildRepo = workspace?.repositories
+    ? Object.keys(workspace.repositories).some((id) => id !== "project")
+    : false;
+  if (mode !== "parent" || !hasDeclaredChildRepo) {
+    return null;
+  }
+  return createRepositoryRegistryFromPreferences(basePath, preferences);
+}
+
+/** Stable key fragment for workspace-aware enumeration inputs (mode + declared repos). */
+function workspaceEnumerationSignature(basePath: string): string {
+  const registry = loadWorkspaceRegistry(basePath);
+  if (!registry) return "single-root";
+  return JSON.stringify({
+    mode: registry.mode,
+    repositories: registry.repositories
+      .map((repo) => ({ id: repo.id, root: repo.root }))
+      .sort((a, b) => a.id.localeCompare(b.id)),
+  });
+}
+
+/**
+ * Enumerate tracked files across every declared repository in a parent workspace.
+ * Child-repo paths are rewritten to be workspace-relative (e.g. `frontend/src/x`)
+ * and tagged with their declaring repo id so the map can render repo-labelled
+ * sections. The maxFiles cap is applied across the union of all repositories.
+ */
+function enumerateWorkspaceFiles(
+  registry: RepositoryRegistry,
+  excludes: string[],
+  maxFiles: number,
+): EnumeratedFiles {
+  type WorkspaceEntry = { workspacePath: string; repoId: string };
+  const perRepo: WorkspaceEntry[][] = [];
+  const seen = new Set<string>();
+  let totalEligible = 0;
+
+  for (const repo of registry.repositories) {
+    const rawFiles = lsFiles(repo.root);
+    const repoPrefix = relative(registry.projectRoot, repo.root).split(sep).join("/");
+    const repoEntries: WorkspaceEntry[] = [];
+
+    for (const file of rawFiles) {
+      // Rewrite before exclusion so workspace-relative patterns (e.g. frontend/…) apply.
+      const workspacePath = repoPrefix ? `${repoPrefix}/${file}` : file;
+      if (shouldExclude(workspacePath, excludes)) continue;
+      if (seen.has(workspacePath)) continue;
+      seen.add(workspacePath);
+      totalEligible++;
+      repoEntries.push({ workspacePath, repoId: repo.id });
+    }
+    perRepo.push(repoEntries);
+  }
+
+  const files: string[] = [];
+  const repos: string[] = [];
+  const indices = new Array(perRepo.length).fill(0);
+
+  while (files.length < maxFiles) {
+    let progressed = false;
+    for (let i = 0; i < perRepo.length; i++) {
+      if (indices[i] < perRepo[i].length) {
+        const entry = perRepo[i][indices[i]++];
+        files.push(entry.workspacePath);
+        repos.push(entry.repoId);
+        progressed = true;
+        if (files.length >= maxFiles) break;
+      }
+    }
+    if (!progressed) break;
+  }
+
+  return { files, repos, truncated: totalEligible > files.length };
+}
+
 function resolveGeneratorOptions(options?: CodebaseMapOptions): ResolvedCodebaseMapOptions {
   const excludes = [...DEFAULT_EXCLUDES, ...(options?.excludePatterns ?? [])];
   const maxFiles = options?.maxFiles ?? DEFAULT_MAX_FILES;
@@ -236,10 +335,12 @@ function computeCodebaseFingerprint(
   files: string[],
   resolved: ResolvedCodebaseMapOptions,
   truncated: boolean,
+  repos?: string[],
 ): string {
   return createHash("sha1")
     .update(JSON.stringify({
       files,
+      ...(repos ? { repos } : {}),
       truncated,
       optionSignature: resolved.optionSignature,
     }))
@@ -252,32 +353,61 @@ function groupByDirectory(
   files: string[],
   descriptions: Map<string, string>,
   collapseThreshold: number,
+  repos?: string[],
 ): DirectoryGroup[] {
   const dirMap = new Map<string, FileEntry[]>();
 
-  for (const file of files) {
+  for (let i = 0; i < files.length; i++) {
+    const file = files[i];
     const dir = dirname(file);
-    const dirKey = dir === "." ? "" : dir;
-    if (!dirMap.has(dirKey)) {
-      dirMap.set(dirKey, []);
+    const dirPath = dir === "." ? "" : dir;
+    const repoId = repos?.[i];
+    const groupKey = repoId !== undefined ? `${repoId}\0${dirPath}` : dirPath;
+    if (!dirMap.has(groupKey)) {
+      dirMap.set(groupKey, []);
     }
-    dirMap.get(dirKey)!.push({
+    dirMap.get(groupKey)!.push({
       path: file,
       description: descriptions.get(file) ?? "",
+      repo: repoId,
     });
   }
 
   const groups: DirectoryGroup[] = [];
-  const sortedDirs = [...dirMap.keys()].sort();
+  const repoOrder = new Map<string, number>();
+  if (repos) {
+    for (let i = 0; i < repos.length; i++) {
+      if (!repoOrder.has(repos[i])) {
+        repoOrder.set(repos[i], repoOrder.size);
+      }
+    }
+  }
+  const sortedDirs = [...dirMap.keys()].sort((a, b) => {
+    // Single-repo (project) mode must stay byte-identical to the pre-workspace
+    // output, which ordered directories with a bare `.sort()` (UTF-16 code-unit
+    // order, so uppercase sorts before lowercase). localeCompare would diverge
+    // for mixed-case names (e.g. "Zoo" before "apple" flips), so preserve
+    // code-unit ordering here; only the repo-partitioning key is added on top.
+    if (!repos) return a < b ? -1 : a > b ? 1 : 0;
+    const repoA = dirMap.get(a)![0]?.repo ?? "";
+    const repoB = dirMap.get(b)![0]?.repo ?? "";
+    const orderA = repoOrder.get(repoA) ?? 0;
+    const orderB = repoOrder.get(repoB) ?? 0;
+    if (orderA !== orderB) return orderA - orderB;
+    return a.localeCompare(b);
+  });
 
-  for (const dir of sortedDirs) {
-    const dirFiles = dirMap.get(dir)!;
+  for (const groupKey of sortedDirs) {
+    const dirFiles = dirMap.get(groupKey)!;
     dirFiles.sort((a, b) => a.path.localeCompare(b.path));
+    const dirPath = repos ? groupKey.slice(groupKey.indexOf("\0") + 1) : groupKey;
 
     groups.push({
-      path: dir,
+      path: dirPath,
       files: dirFiles,
       collapsed: dirFiles.length > collapseThreshold,
+      // Each group is scoped to one repo in workspace-aware mode.
+      repo: dirFiles[0]?.repo,
     });
   }
 
@@ -304,7 +434,19 @@ function renderCodebaseMap(
   }
   lines.push("");
 
+  let emittedRepo: string | undefined;
   for (const group of groups) {
+    // In a workspace-aware map, partition directories under their declaring
+    // repository. `## [repo-id]` headings are used (not `###`) so they never
+    // collide with the per-directory `### <dir>/` headings or the
+    // `parseCodebaseMap` list-item regexes. Groups are sorted by declaring
+    // repo (enumeration order) then directory path so each repo is contiguous.
+    if (group.repo && group.repo !== emittedRepo) {
+      emittedRepo = group.repo;
+      lines.push(`## [${group.repo}]`);
+      lines.push("");
+    }
+
     const heading = group.path || "(root)";
     lines.push(`### ${heading}/`);
 
@@ -361,13 +503,15 @@ function buildCodebaseMap(
 } {
   const listed = enumerated ?? enumerateFiles(basePath, resolved.excludes, resolved.maxFiles);
   const descriptions = existingDescriptions ?? new Map<string, string>();
-  const groups = groupByDirectory(listed.files, descriptions, resolved.collapseThreshold);
+  const groups = groupByDirectory(listed.files, descriptions, resolved.collapseThreshold, listed.repos);
   const generatedAt = new Date().toISOString().split(".")[0] + "Z";
+  const repoIds = listed.repos ? Array.from(new Set(listed.repos)) : undefined;
   const metadata: CodebaseMapMetadata = {
     generatedAt,
-    fingerprint: computeCodebaseFingerprint(listed.files, resolved, listed.truncated),
+    fingerprint: computeCodebaseFingerprint(listed.files, resolved, listed.truncated, listed.repos),
     fileCount: listed.files.length,
     truncated: listed.truncated,
+    ...(repoIds ? { repositories: repoIds } : {}),
   };
   const content = renderCodebaseMap(groups, listed.files.length, listed.truncated, metadata);
 
@@ -387,13 +531,28 @@ function buildCodebaseMap(
  * Generate a fresh CODEBASE.md from scratch.
  * Preserves existing descriptions if `existingDescriptions` is provided.
  */
+/**
+ * Resolve workspace-aware enumeration for parent mode, or undefined to fall
+ * back to the legacy single-root enumeration. Centralized so all three public
+ * entry points (generate/update/ensure) share one discovery path.
+ */
+function resolveWorkspaceEnumeration(
+  basePath: string,
+  resolved: ResolvedCodebaseMapOptions,
+): EnumeratedFiles | undefined {
+  const registry = loadWorkspaceRegistry(basePath);
+  if (!registry) return undefined;
+  return enumerateWorkspaceFiles(registry, resolved.excludes, resolved.maxFiles);
+}
+
 export function generateCodebaseMap(
   basePath: string,
   options?: CodebaseMapOptions,
   existingDescriptions?: Map<string, string>,
 ): { content: string; fileCount: number; truncated: boolean; files: string[]; fingerprint: string; generatedAt: string } {
   const resolved = resolveGeneratorOptions(options);
-  return buildCodebaseMap(basePath, resolved, existingDescriptions);
+  const enumerated = resolveWorkspaceEnumeration(basePath, resolved);
+  return buildCodebaseMap(basePath, resolved, existingDescriptions, enumerated);
 }
 
 /**
@@ -427,7 +586,8 @@ export function updateCodebaseMap(
 
   // Generate new map preserving descriptions — reuse the returned file list
   // to avoid a second enumeration (prevents race between content and stats).
-  const result = buildCodebaseMap(basePath, resolved, existingDescriptions);
+  const enumerated = resolveWorkspaceEnumeration(basePath, resolved);
+  const result = buildCodebaseMap(basePath, resolved, existingDescriptions, enumerated);
   const currentSet = new Set(result.files);
 
   // Count changes
@@ -467,26 +627,24 @@ export function ensureCodebaseMapFresh(
   ensureOptions?: EnsureCodebaseMapOptions,
 ): EnsureCodebaseMapResult {
   const resolved = resolveGeneratorOptions(options);
-  const cacheKey = `${basePath}::${resolved.optionSignature}`;
+  const cacheKey = `${basePath}::${resolved.optionSignature}::${workspaceEnumerationSignature(basePath)}`;
   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 = resolveWorkspaceEnumeration(basePath, resolved)
+    ?? enumerateFiles(basePath, resolved.excludes, resolved.maxFiles);
+  const fingerprint = computeCodebaseFingerprint(listed.files, resolved, listed.truncated, listed.repos);
+
   const cacheAndReturn = (result: EnsureCodebaseMapResult): EnsureCodebaseMapResult => {
     freshnessCache.set(cacheKey, { checkedAt: now, result });
     return result;

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

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

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

@@ -9,6 +9,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,
@@ -44,6 +45,8 @@ export async function handleGSDCommand(
   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/src/resources/extensions/gsd/commands/gsd-core-aliases-handler.ts

@@ -0,0 +1,48 @@
+// 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 type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { matchGsdCoreAlias, type GsdCoreAlias } from "./gsd-core-aliases.js";
+
+function formatUnavailable(cmd: string, alias: Extract<GsdCoreAlias, { kind: "unavailable" }>): string {
+  const lines: string[] = [
+    `/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: string,
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+): Promise<boolean> {
+  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;
+}

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

@@ -0,0 +1,63 @@
+// Project/App: gsd-pi
+// File Purpose: Alias redirects for namespace-grouping commands (ns-*).
+//
+// The ns-* names were command-grouping menus in an earlier CLI; gsd-pi uses a flat
+// `/gsd help`, so these redirect there. Every other additional command is implemented
+// natively as an adapted workflow in commands-gsd-core.ts.
+
+export interface GsdCoreAliasRedirect {
+  kind: "redirect";
+  /** gsd-pi command (and args) to re-dispatch through the main dispatcher. */
+  target: string;
+  /** Short note shown to the user before re-dispatch. */
+  note?: string;
+}
+
+export interface GsdCoreAliasUnavailable {
+  kind: "unavailable";
+  /** One-line description of what the command did previously. */
+  legacy: string;
+  /** Suggested gsd-pi alternative(s), if any. */
+  alternative?: string;
+}
+
+export type GsdCoreAlias = GsdCoreAliasRedirect | GsdCoreAliasUnavailable;
+
+/**
+ * Namespace-grouping aliases (ns-*). Each redirects to the flat /gsd help.
+ */
+export const GSD_CORE_ALIASES: ReadonlyMap<string, GsdCoreAlias> = new Map<string, GsdCoreAlias>([
+  ["ns-context", { kind: "redirect", target: "help", note: "Namespace command — use /gsd help to browse all commands." }],
+  ["ns-ideate", { kind: "redirect", target: "help", note: "Namespace command — use /gsd help to browse all commands." }],
+  ["ns-manage", { kind: "redirect", target: "help", note: "Namespace command — use /gsd help to browse all commands." }],
+  ["ns-project", { kind: "redirect", target: "help", note: "Namespace command — use /gsd help to browse all commands." }],
+  ["ns-review", { kind: "redirect", target: "help", note: "Namespace command — use /gsd help to browse all commands." }],
+  ["ns-workflow", { kind: "redirect", target: "help", note: "Namespace command — use /gsd help to browse all commands." }],
+]);
+
+/**
+ * Catalog entries (for autocomplete) derived from the alias table.
+ * Surfaced as top-level subcommands so users discover them while typing.
+ */
+export const GSD_CORE_ALIAS_CATALOG: ReadonlyArray<{ cmd: string; desc: string }> = [
+  { cmd: "ns-context", desc: "Alias for /gsd help" },
+  { cmd: "ns-ideate", desc: "Alias for /gsd help" },
+  { cmd: "ns-manage", desc: "Alias for /gsd help" },
+  { cmd: "ns-project", desc: "Alias for /gsd help" },
+  { cmd: "ns-review", desc: "Alias for /gsd help" },
+  { cmd: "ns-workflow", desc: "Alias for /gsd help" },
+];
+
+/**
+ * Tries to resolve a `/gsd <cmd> [args]` string against the namespace alias table.
+ * Returns the matched alias (and remaining args) or null if no alias matches.
+ */
+export function matchGsdCoreAlias(trimmed: string): { alias: GsdCoreAlias; cmd: string; rest: string } | null {
+  const spaceIdx = trimmed.indexOf(" ");
+  const cmd = (spaceIdx === -1 ? trimmed : trimmed.slice(0, spaceIdx)).trim();
+  if (!cmd) return null;
+  const alias = GSD_CORE_ALIASES.get(cmd);
+  if (!alias) return null;
+  const rest = spaceIdx === -1 ? "" : trimmed.slice(spaceIdx + 1).trim();
+  return { alias, cmd, rest };
+}

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

@@ -200,7 +200,7 @@ export async function handleAutoCommand(trimmed: string, ctx: ExtensionCommandCo
       }
       return true;
     }
-    await pauseAuto(ctx, pi);
+    await pauseAuto(ctx, pi, undefined, { abortActiveTurn: true });
     return true;
   }
 

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

@@ -4,7 +4,9 @@ import type { GSDState } from "../../types.js";
 import { createRequire } from "node:module";
 
 import { computeProgressScore, formatProgressLine } from "../../progress-score.js";
+import { isRepositoryDirty } from "../../git-service.js";
 import { loadEffectiveGSDPreferences, getGlobalGSDPreferencesPath, getProjectGSDPreferencesPath, availableModelIdsFromRegistry, modelIdsForProfileResolution, resolveProfileAnchorProvider, resolveDisabledModelProvidersFromPreferences } from "../../preferences.js";
+import { createRepositoryRegistryFromPreferences } from "../../repository-registry.js";
 import { ensurePreferencesFile, handlePrefs, handlePrefsMode, handlePrefsWizard, handleLanguage } from "../../commands-prefs-wizard.js";
 import { runEnvironmentChecks } from "../../doctor-environment.js";
 import { deriveState } from "../../state.js";
@@ -14,6 +16,8 @@ import { projectRoot } from "../context.js";
 import { formattedShortcutPair } from "../../shortcut-defs.js";
 import { getVisualBriefOutputDir } from "../../../visual-brief/artifact-policy.js";
 import { buildVisualBriefPrompt, parseVisualBriefArgs, VISUAL_BRIEF_USAGE } from "../../../visual-brief/prompts.js";
+import { GSD_CORE_IMPLEMENTED_CATALOG } from "../../commands-gsd-core.js";
+import { GSD_CORE_ALIAS_CATALOG } from "../gsd-core-aliases.js";
 
 export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
   const summaryLines = [
@@ -58,6 +62,11 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     "  /gsd closeout       Recover failed git closeout actions",
     "  /gsd rebuild        Rebuild markdown projections from the DB  [markdown]",
     "",
+    "ADDITIONAL COMMANDS",
+    "  /gsd map-codebase, /gsd stats, /gsd code-review, /gsd spike, /gsd explore …",
+    "  Additional workflows for exploration, review, codebase intel, and more.",
+    "  See /gsd help full for the complete list.",
+    "",
     "Use /gsd help full for the complete command reference.",
   ];
 
@@ -158,11 +167,34 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     "  /gsd update         Update GSD to the latest version via npm",
     "  /gsd upgrade        Alias for /gsd update",
     "  /gsd language       Set or clear the global response language  [off|clear|<language>]",
+    "",
+    // The ADDITIONAL COMMANDS block is generated below from the implemented + alias catalogs
+    // so it can never drift from TOP_LEVEL_SUBCOMMANDS (which the help-coverage test asserts).
+    ...buildAdditionalCommandsHelpLines(),
   ];
   const full = ["full", "--full", "all"].includes(args.trim().toLowerCase());
   ctx.ui.notify((full ? fullLines : summaryLines).join("\n"), "info");
 }
 
+/**
+ * Build the ADDITIONAL COMMANDS help lines from the implemented-workflow and alias catalogs.
+ * Kept in sync with TOP_LEVEL_SUBCOMMANDS automatically — every command appears here.
+ */
+function buildAdditionalCommandsHelpLines(): string[] {
+  const lines: string[] = [
+    "ADDITIONAL COMMANDS",
+    "  Additional workflows for exploration, review, codebase intel, and project management.",
+  ];
+  const pad = (cmd: string, width = 20) => cmd.padEnd(width);
+  for (const entry of GSD_CORE_IMPLEMENTED_CATALOG) {
+    lines.push(`  /gsd ${pad(entry.cmd)} ${entry.desc}`);
+  }
+  for (const entry of GSD_CORE_ALIAS_CATALOG) {
+    lines.push(`  /gsd ${pad(entry.cmd)} ${entry.desc}`);
+  }
+  return lines;
+}
+
 export async function handleStatus(ctx: ExtensionCommandContext): Promise<void> {
   const basePath = projectRoot();
   // Open DB in cold sessions so status uses DB-backed state, not filesystem fallback (#3385)
@@ -190,7 +222,7 @@ export async function handleStatus(ctx: ExtensionCommandContext): Promise<void>
   );
 
   if (result === undefined) {
-    ctx.ui.notify(formatTextStatus(state), "info");
+    ctx.ui.notify(formatTextStatus(state, basePath), "info");
   }
 }
 
@@ -549,6 +581,7 @@ export async function handleCoreCommand(
     const configOptions = {
       basePath,
       ...(availableModelIds && availableModelIds.length > 0 ? { availableModelIds } : {}),
+      ...(ctx.model ? { preferredModelId: `${ctx.model.provider}/${ctx.model.id}` } : {}),
     };
     const result = await ctx.ui.custom<boolean>(
       (tui, theme, _kb, done) => new GSDConfigOverlay(tui, theme, () => done(true), configOptions),
@@ -579,7 +612,8 @@ export async function handleCoreCommand(
   return false;
 }
 
-export function formatTextStatus(state: GSDState): string {
+export function formatTextStatus(state: GSDState, basePath?: string): string {
+  const root = basePath ?? projectRoot();
   const lines: string[] = ["GSD Status\n"];
   lines.push(formatProgressLine(computeProgressScore()));
   lines.push("");
@@ -622,7 +656,7 @@ export function formatTextStatus(state: GSDState): string {
     }
   }
 
-  const envResults = runEnvironmentChecks(projectRoot());
+  const envResults = runEnvironmentChecks(root);
   const envIssues = envResults.filter((result) => result.status !== "ok");
   if (envIssues.length > 0) {
     lines.push("");
@@ -632,5 +666,38 @@ export function formatTextStatus(state: GSDState): string {
     }
   }
 
+  // Parent-workspace per-repository git health (#818). No-op for single-repo
+  // projects; surfaces which declared child repos have uncommitted changes.
+  const repoBlock = buildWorkspaceRepoStatusBlock(root);
+  if (repoBlock) {
+    lines.push("");
+    lines.push("Repositories:");
+    lines.push(repoBlock);
+  }
+
   return lines.join("\n");
 }
+
+/**
+ * Build a per-repository dirty/clean summary for parent-workspace status.
+ * Returns "" for single-repo (project-mode) projects so the status output is
+ * unchanged; otherwise one line per declared child repository.
+ */
+function buildWorkspaceRepoStatusBlock(basePath: string): string {
+  let registry;
+  try {
+    registry = createRepositoryRegistryFromPreferences(basePath, loadEffectiveGSDPreferences(basePath)?.preferences);
+  } catch {
+    return "";
+  }
+  if (registry.mode !== "parent") return "";
+  const childRepos = registry.repositories.filter((repo) => repo.id !== "project");
+  if (childRepos.length === 0) return "";
+
+  return childRepos
+    .map((repo) => {
+      const dirty = isRepositoryDirty(repo.root);
+      return `  ${dirty ? "✗" : "✓"} ${repo.id}${repo.role ? ` — ${repo.role}` : ""}${dirty ? " (uncommitted changes)" : " (clean)"}`;
+    })
+    .join("\n");
+}