gsd-pi 2.67.0-dev.46f9884 → 2.67.0-dev.a5b1d8f

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|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";
 
 export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -41,6 +41,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "skip", desc: "Prevent a unit from auto-mode dispatch" },
   { cmd: "export", desc: "Export milestone/slice results" },
   { cmd: "cleanup", desc: "Remove merged branches or snapshots" },
+  { cmd: "model", desc: "Switch the active session model or open a picker" },
   { cmd: "mode", desc: "Switch workflow mode (solo/team)" },
   { cmd: "prefs", desc: "Manage preferences (model selection, timeouts, etc.)" },
   { cmd: "config", desc: "Set API keys for external tools" },
@@ -72,7 +73,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "mcp", desc: "MCP server status and connectivity check (status, check <server>)" },
   { 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 and manage codebase map (.gsd/CODEBASE.md)" },
+  { cmd: "codebase", desc: "Generate, refresh, and inspect the codebase map cache (.gsd/CODEBASE.md)" },
 ];
 
 const NESTED_COMPLETIONS: CompletionMap = {
@@ -236,7 +237,7 @@ const NESTED_COMPLETIONS: CompletionMap = {
     { cmd: "generate", desc: "Generate or regenerate CODEBASE.md" },
     { cmd: "generate --max-files", desc: "Generate with custom file limit (default: 500)" },
     { cmd: "generate --collapse-threshold", desc: "Generate with custom collapse threshold (default: 20)" },
-    { cmd: "update", desc: "Incremental update (preserves descriptions)" },
+    { cmd: "update", desc: "Refresh the CODEBASE.md cache immediately (preserves descriptions)" },
     { cmd: "update --max-files", desc: "Update with custom file limit" },
     { cmd: "update --collapse-threshold", desc: "Update with custom collapse threshold" },
     { cmd: "stats", desc: "Show file count, description coverage, and generation time" },

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

@@ -14,7 +14,7 @@ export async function handleGSDCommand(
   const trimmed = (typeof args === "string" ? args : "").trim();
 
   const handlers = [
-    () => handleCoreCommand(trimmed, ctx),
+    () => handleCoreCommand(trimmed, ctx, pi),
     () => handleAutoCommand(trimmed, ctx, pi),
     () => handleParallelCommand(trimmed, ctx, pi),
     () => handleWorkflowCommand(trimmed, ctx, pi),
@@ -29,4 +29,3 @@ export async function handleGSDCommand(
 
   ctx.ui.notify(`Unknown: /gsd ${trimmed}. Run /gsd help for available commands.`, "warning");
 }
-

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

@@ -1,4 +1,5 @@
-import type { ExtensionCommandContext, ExtensionContext } from "@gsd/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@gsd/pi-coding-agent";
+import type { Model } from "@gsd/pi-ai";
 import type { GSDState } from "../../types.js";
 
 import { computeProgressScore, formatProgressLine } from "../../progress-score.js";
@@ -44,10 +45,12 @@ export function showHelp(ctx: ExtensionCommandContext): void {
     "",
     "PROJECT KNOWLEDGE",
     "  /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",
     "",
     "SETUP & CONFIGURATION",
     "  /gsd init           Project init wizard — detect, configure, bootstrap .gsd/",
     "  /gsd setup          Global setup status  [llm|search|remote|keys|prefs]",
+    "  /gsd model          Switch active session model  [provider/model|model-id]",
     "  /gsd mode           Set workflow mode (solo/team)  [global|project]",
     "  /gsd prefs          Manage preferences  [global|project|status|wizard|setup|import-claude]",
     "  /gsd cmux           Manage cmux integration  [status|on|off|notifications|sidebar|splits|browser]",
@@ -179,7 +182,106 @@ export async function handleSetup(args: string, ctx: ExtensionCommandContext): P
   );
 }
 
-export async function handleCoreCommand(trimmed: string, ctx: ExtensionCommandContext): Promise<boolean> {
+function sortModelsForSelection(models: Model<any>[], currentModel: Model<any> | undefined): Model<any>[] {
+  return [...models].sort((a, b) => {
+    const aCurrent = currentModel && a.provider === currentModel.provider && a.id === currentModel.id;
+    const bCurrent = currentModel && b.provider === currentModel.provider && b.id === currentModel.id;
+    if (aCurrent && !bCurrent) return -1;
+    if (!aCurrent && bCurrent) return 1;
+    const providerCmp = a.provider.localeCompare(b.provider);
+    if (providerCmp !== 0) return providerCmp;
+    return a.id.localeCompare(b.id);
+  });
+}
+
+async function resolveRequestedModel(
+  query: string,
+  ctx: ExtensionCommandContext,
+): Promise<Model<any> | undefined> {
+  const { resolveModelId } = await import("../../auto-model-selection.js");
+  const models = ctx.modelRegistry.getAvailable();
+  const exact = resolveModelId(query, models, ctx.model?.provider);
+  if (exact) return exact;
+
+  const lowerQuery = query.toLowerCase();
+  const partialMatches = models.filter((model) =>
+    model.id.toLowerCase().includes(lowerQuery)
+      || `${model.provider}/${model.id}`.toLowerCase().includes(lowerQuery),
+  );
+
+  if (partialMatches.length === 1) return partialMatches[0];
+  if (partialMatches.length === 0 || !ctx.hasUI) return undefined;
+
+  const sorted = sortModelsForSelection(partialMatches, ctx.model);
+  const optionToModel = new Map<string, Model<any>>();
+  const options = sorted.map((model) => {
+    const label = `${model.provider}/${model.id}`;
+    optionToModel.set(label, model);
+    return label;
+  });
+  options.push("(cancel)");
+
+  const choice = await ctx.ui.select(`Multiple models match "${query}" — choose one:`, options);
+  if (!choice || typeof choice !== "string" || choice === "(cancel)") return undefined;
+  return optionToModel.get(choice);
+}
+
+async function handleModel(trimmedArgs: string, ctx: ExtensionCommandContext, pi: ExtensionAPI | undefined): Promise<void> {
+  const availableModels = ctx.modelRegistry.getAvailable();
+  if (availableModels.length === 0) {
+    ctx.ui.notify("No available models found. Check provider auth and model discovery.", "warning");
+    return;
+  }
+  if (!pi) {
+    ctx.ui.notify("Model switching is unavailable in this context.", "warning");
+    return;
+  }
+
+  const trimmed = trimmedArgs.trim();
+  let targetModel: Model<any> | undefined;
+
+  if (!trimmed) {
+    if (!ctx.hasUI) {
+      const current = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "(none)";
+      ctx.ui.notify(`Current model: ${current}\nUsage: /gsd model <provider/model|model-id>`, "info");
+      return;
+    }
+
+    const optionToModel = new Map<string, Model<any>>();
+    const options = sortModelsForSelection(availableModels, ctx.model).map((model) => {
+      const isCurrent = ctx.model && model.provider === ctx.model.provider && model.id === ctx.model.id;
+      const label = `${isCurrent ? "* " : ""}${model.provider}/${model.id}`;
+      optionToModel.set(label, model);
+      return label;
+    });
+    options.push("(cancel)");
+
+    const choice = await ctx.ui.select("Select session model:", options);
+    if (!choice || typeof choice !== "string" || choice === "(cancel)") return;
+    targetModel = optionToModel.get(choice);
+  } else {
+    targetModel = await resolveRequestedModel(trimmed, ctx);
+  }
+
+  if (!targetModel) {
+    ctx.ui.notify(`Model "${trimmed}" not found. Use /gsd model with an exact provider/model or a unique model ID.`, "warning");
+    return;
+  }
+
+  const ok = await pi.setModel(targetModel);
+  if (!ok) {
+    ctx.ui.notify(`No API key for ${targetModel.provider}/${targetModel.id}`, "warning");
+    return;
+  }
+
+  ctx.ui.notify(`Model: ${targetModel.provider}/${targetModel.id}`, "info");
+}
+
+export async function handleCoreCommand(
+  trimmed: string,
+  ctx: ExtensionCommandContext,
+  pi?: ExtensionAPI,
+): Promise<boolean> {
   if (trimmed === "help" || trimmed === "h" || trimmed === "?") {
     showHelp(ctx);
     return true;
@@ -203,6 +305,10 @@ export async function handleCoreCommand(trimmed: string, ctx: ExtensionCommandCo
     ctx.ui.notify(`Widget: ${getWidgetMode()}`, "info");
     return true;
   }
+  if (trimmed === "model" || trimmed.startsWith("model ")) {
+    await handleModel(trimmed.replace(/^model\s*/, "").trim(), ctx, pi);
+    return true;
+  }
   if (trimmed === "mode" || trimmed.startsWith("mode ")) {
     const modeArgs = trimmed.replace(/^mode\s*/, "").trim();
     const scope = modeArgs === "project" ? "project" : "global";

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

@@ -45,6 +45,7 @@ const TOP_LEVEL_SUBCOMMANDS = [
   { cmd: "start", desc: "Start a workflow template" },
   { cmd: "templates", desc: "List available workflow templates" },
   { cmd: "extensions", desc: "Manage extensions" },
+  { cmd: "codebase", desc: "Generate, refresh, and inspect the codebase map cache" },
 ] as const;
 
 function filterStartsWith(
@@ -218,6 +219,15 @@ function getGsdArgumentCompletions(prefix: string) {
     ], "extensions");
   }
 
+  if (parts[0] === "codebase" && parts.length <= 2) {
+    return filterStartsWith(partial, [
+      { cmd: "generate", desc: "Generate or regenerate CODEBASE.md" },
+      { cmd: "update", desc: "Refresh the CODEBASE.md cache immediately" },
+      { cmd: "stats", desc: "Show codebase-map coverage and generation time" },
+      { cmd: "help", desc: "Show usage and subcommands" },
+    ], "codebase");
+  }
+
   if (parts[0] === "doctor" && parts.length <= 2) {
     return filterStartsWith(partial, [
       { cmd: "fix", desc: "Auto-fix detected issues" },

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

@@ -20,10 +20,11 @@ import type { CodebaseMapOptions } from "./codebase-generator.js";
 const USAGE =
   "Usage: /gsd codebase [generate|update|stats]\n\n" +
   "  generate [--max-files N] [--collapse-threshold N]  — Generate or regenerate CODEBASE.md\n" +
-  "  update [--max-files N] [--collapse-threshold N]    — Incremental update (preserves descriptions)\n" +
+  "  update [--max-files N] [--collapse-threshold N]    — Refresh the CODEBASE.md cache immediately\n" +
   "  stats                                              — Show file count, coverage, and generation time\n" +
   "  help                                               — Show this help\n\n" +
-  "With no subcommand, shows stats if a map exists or help if not.\n\n" +
+  "With no subcommand, shows stats if a map exists or help if not.\n" +
+  "GSD also refreshes CODEBASE.md automatically before prompt injection and after completed units when tracked files change.\n\n" +
   "Configure defaults via preferences.md:\n" +
   "  codebase:\n" +
   "    exclude_patterns: [\"docs/\", \"fixtures/\"]\n" +
@@ -141,7 +142,7 @@ function showStats(basePath: string, ctx: ExtensionCommandContext): void {
     `  Undescribed: ${stats.undescribedCount}\n` +
     `  Generated: ${stats.generatedAt ?? "unknown"}\n\n` +
     (stats.undescribedCount > 0
-      ? `Tip: Run /gsd codebase update to refresh after file changes.`
+      ? `Tip: Auto-refresh keeps the cache current, but /gsd codebase update forces an immediate refresh.`
       : `Coverage is complete.`),
     "info",
   );

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

@@ -165,10 +165,10 @@ export function buildCategorySummaries(prefs: Record<string, unknown>): Record<s
   const modeSummary = mode ?? "(not set)";
 
   // Models
-  const models = prefs.models as Record<string, string> | undefined;
+  const models = prefs.models as Record<string, unknown> | undefined;
   let modelsSummary = "(not configured)";
   if (models && Object.keys(models).length > 0) {
-    const parts = Object.entries(models).map(([phase, model]) => `${phase}: ${model}`);
+    const parts = Object.entries(models).map(([phase, model]) => `${phase}: ${formatConfiguredModel(model)}`);
     modelsSummary = parts.join(", ");
   }
 
@@ -255,9 +255,38 @@ export function buildCategorySummaries(prefs: Record<string, unknown>): Record<s
 
 // ─── Category configuration functions ────────────────────────────────────────
 
+export function formatConfiguredModel(config: unknown): string {
+  if (typeof config === "string") return config;
+  if (!config || typeof config !== "object") return "(invalid)";
+  const maybeConfig = config as { model?: unknown; provider?: unknown };
+  if (typeof maybeConfig.model !== "string" || maybeConfig.model.trim() === "") return "(invalid)";
+  if (typeof maybeConfig.provider === "string" && maybeConfig.provider && !maybeConfig.model.includes("/")) {
+    return `${maybeConfig.provider}/${maybeConfig.model}`;
+  }
+  return maybeConfig.model;
+}
+
+export function toPersistedModelId(provider: string, modelId: string): string {
+  if (!provider.trim()) return modelId;
+  const normalizedProvider = provider.trim();
+  const normalizedModelId = modelId.trim();
+  return normalizedModelId.startsWith(`${normalizedProvider}/`)
+    ? normalizedModelId
+    : `${normalizedProvider}/${normalizedModelId}`;
+}
+
 async function configureModels(ctx: ExtensionCommandContext, prefs: Record<string, unknown>): Promise<void> {
-  const modelPhases = ["research", "planning", "execution", "completion"] as const;
-  const models: Record<string, string> = (prefs.models as Record<string, string>) ?? {};
+  const modelPhases = [
+    "research",
+    "planning",
+    "discuss",
+    "execution",
+    "execution_simple",
+    "completion",
+    "validation",
+    "subagent",
+  ] as const;
+  const models: Record<string, unknown> = (prefs.models as Record<string, unknown>) ?? {};
 
   const availableModels = ctx.modelRegistry.getAvailable();
   if (availableModels.length > 0) {
@@ -292,7 +321,7 @@ async function configureModels(ctx: ExtensionCommandContext, prefs: Record<strin
     providerOptions.push("(keep current)", "(clear)", "(type manually)");
 
     for (const phase of modelPhases) {
-      const current = models[phase] ?? "";
+      const current = formatConfiguredModel(models[phase]);
       const phaseLabel = `Model for ${phase} phase${current ? ` (current: ${current})` : ""}`;
 
       // Step 1: pick provider
@@ -329,13 +358,13 @@ async function configureModels(ctx: ExtensionCommandContext, prefs: Record<strin
         if (modelChoice === "(clear)") {
           delete models[phase];
         } else {
-          models[phase] = modelChoice;
+          models[phase] = toPersistedModelId(providerName, modelChoice);
         }
       }
     }
   } else {
     for (const phase of modelPhases) {
-      const current = models[phase] ?? "";
+      const current = formatConfiguredModel(models[phase]);
       const input = await ctx.ui.input(
         `Model for ${phase} phase${current ? ` (current: ${current})` : ""}:`,
         current || "e.g. claude-sonnet-4-20250514",
@@ -352,6 +381,8 @@ async function configureModels(ctx: ExtensionCommandContext, prefs: Record<strin
   }
   if (Object.keys(models).length > 0) {
     prefs.models = models;
+  } else {
+    delete prefs.models;
   }
 }
 

package/src/resources/extensions/gsd/prompts/complete-slice.md

@@ -25,11 +25,11 @@ Then:
 4. If the slice plan includes observability/diagnostic surfaces, confirm they work. Skip this for simple slices that don't have observability sections.
 5. If the slice involved runtime behavior, fill the **Operational Readiness** section (Q8) in the slice summary: health signal, failure signal, recovery procedure, and monitoring gaps. Omit entirely for simple slices with no runtime concerns.
 6. If this slice produced evidence that a requirement changed status (Active → Validated, Active → Deferred, etc.), call `gsd_requirement_update` with the requirement ID, updated `status`, and `validation` evidence. Do NOT write `.gsd/REQUIREMENTS.md` directly — the engine renders it from the database.
-7. Write `{{sliceSummaryPath}}` (compress all task summaries).
-8. Write `{{sliceUatPath}}` — a concrete UAT script with real test cases derived from the slice plan and task summaries. Include preconditions, numbered steps with expected outcomes, and edge cases. This must NOT be a placeholder or generic template — tailor every test case to what this slice actually built.
+7. Prepare the slice completion content you will pass to `gsd_complete_slice` using the camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`. Do **not** manually write `{{sliceSummaryPath}}`. Do **not** manually write `{{sliceUatPath}}` — the DB-backed tool is the canonical write path for both artifacts.
+8. Draft the UAT content you will pass as `uatContent` — a concrete UAT script with real test cases derived from the slice plan and task summaries. Include preconditions, numbered steps with expected outcomes, and edge cases. This must NOT be a placeholder or generic template — tailor every test case to what this slice actually built.
 9. Review task summaries for `key_decisions`. Append any significant decisions to `.gsd/DECISIONS.md` if missing.
 10. Review task summaries for patterns, gotchas, or non-obvious lessons learned. If any would save future agents from repeating investigation or hitting the same issues, append them to `.gsd/KNOWLEDGE.md`. Only add entries that are genuinely useful — don't pad with obvious observations.
-11. Call `gsd_complete_slice` with milestoneId, sliceId, the slice summary, and the UAT result. Do NOT manually mark the roadmap checkbox — the tool writes to the DB and renders the ROADMAP.md projection automatically.
+11. Call `gsd_complete_slice` with the camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`, plus any optional enrichment fields you have. Do NOT manually mark the roadmap checkbox — the tool writes to the DB, renders `{{sliceSummaryPath}}` and `{{sliceUatPath}}`, and updates the ROADMAP.md projection automatically.
 12. Do not run git commands — the system commits your changes and handles any merge after this unit succeeds.
 13. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed: use the `write` tool with `path: ".gsd/PROJECT.md"` and `content` containing the full updated document reflecting current project state. Do NOT use the `edit` tool for this — PROJECT.md is a full-document refresh.
 

package/src/resources/extensions/gsd/prompts/execute-task.md

@@ -69,14 +69,14 @@ Then:
 16. If you made an architectural, pattern, library, or observability decision during this task that downstream work should know about, append it to `.gsd/DECISIONS.md` (read the template at `~/.gsd/agent/extensions/gsd/templates/decisions.md` if the file doesn't exist yet). Not every task produces decisions — only append when a meaningful choice was made.
 17. If you discover a non-obvious rule, recurring gotcha, or useful pattern during execution, append it to `.gsd/KNOWLEDGE.md`. Only add entries that would save future agents from repeating your investigation. Don't add obvious things.
 18. Read the template at `~/.gsd/agent/extensions/gsd/templates/task-summary.md`
-19. Write `{{taskSummaryPath}}`
-20. Call `gsd_complete_task` with milestoneId, sliceId, taskId, and a summary of what was accomplished. This is your final required step — do NOT manually edit PLAN.md checkboxes. The tool marks the task complete, updates the DB, and renders PLAN.md automatically.
+19. Use that template to prepare the completion content you will pass to `gsd_complete_task` using the camelCase fields `milestoneId`, `sliceId`, `taskId`, `oneLiner`, `narrative`, `verification`, and `verificationEvidence`. Do **not** manually write `{{taskSummaryPath}}` — the DB-backed tool is the canonical write path and renders the summary file for you.
+20. Call `gsd_complete_task` with milestoneId, sliceId, taskId, and the completion fields derived from the template. This is your final required step — do NOT manually edit PLAN.md checkboxes. The tool marks the task complete, updates the DB, renders `{{taskSummaryPath}}`, and updates PLAN.md automatically.
 21. Do not run git commands — the system reads your task summary after completion and creates a meaningful commit from it (type inferred from title, message from your one-liner, key files from frontmatter). Write a clear, specific one-liner in the summary — it becomes the commit message.
 
 All work stays in your working directory: `{{workingDirectory}}`.
 
 **Autonomous execution:** Do not call `ask_user_questions` or `secure_env_collect`. You are running in auto-mode — there is no human available to answer questions. Make reasonable assumptions and document them in the task summary. If a decision genuinely requires human input, note it in the summary and proceed with the best available option.
 
-**You MUST call `gsd_complete_task` AND write `{{taskSummaryPath}}` before finishing.**
+**You MUST call `gsd_complete_task` before finishing. Do not manually write `{{taskSummaryPath}}`.**
 
 When done, say: "Task {{taskId}} complete."

package/src/resources/extensions/gsd/prompts/system.md

@@ -62,6 +62,7 @@ Titles live inside file content (headings, frontmatter), not in file or director
   REQUIREMENTS.md       (requirement contract - tracks active/validated/deferred/out-of-scope)
   DECISIONS.md          (append-only register of architectural and pattern decisions)
   KNOWLEDGE.md          (append-only register of project-specific rules, patterns, and lessons learned)
+  CODEBASE.md           (generated codebase map cache — auto-refreshed when tracked files change)
   OVERRIDES.md          (user-issued overrides that supersede plan content via /gsd steer)
   QUEUE.md              (append-only log of queued milestones via /gsd queue)
   STATE.md
@@ -104,6 +105,7 @@ In all modes, slices commit sequentially on the active branch; there are no per-
 - **REQUIREMENTS.md** tracks the requirement contract — requirements move between Active, Validated, Deferred, Blocked, and Out of Scope as slices prove or invalidate them. Update at slice completion when evidence supports a status change.
 - **DECISIONS.md** is an append-only register of architectural and pattern decisions - read it during planning/research, append to it during execution when a meaningful decision is made
 - **KNOWLEDGE.md** is an append-only register of project-specific rules, patterns, and lessons learned. Read it at the start of every unit. Append to it when you discover a recurring issue, a non-obvious pattern, or a rule that future agents should follow.
+- **CODEBASE.md** is a generated structural cache of the tracked repository. GSD auto-refreshes it when tracked files change and injects it into system context when available. Use `/gsd codebase update` only when you need to force an immediate refresh.
 - **CONTEXT.md** files (milestone or slice level) capture the brief — scope, goals, constraints, and key decisions from discussion. When present, they are the authoritative source for what a milestone or slice is trying to achieve. Read them before planning or executing.
 - **Milestones** are major project phases (M001, M002, ...)
 - **Slices** are demoable vertical increments (S01, S02, ...) ordered by risk. After each slice completes, the roadmap is reassessed before the next slice begins.
@@ -131,6 +133,7 @@ Templates showing the expected format for each artifact type are in:
 - `/gsd status` - progress dashboard overlay
 - `/gsd queue` - queue future milestones (safe while auto-mode is running)
 - `/gsd quick <task>` - quick task with GSD guarantees (atomic commits, state tracking) but no milestone ceremony
+- `/gsd codebase [generate|update|stats]` - manage the `.gsd/CODEBASE.md` cache used for prompt context
 - `{{shortcutDashboard}}` - toggle dashboard overlay
 - `{{shortcutShell}}` - show shell processes
 

package/src/resources/extensions/gsd/prompts/validate-milestone.md

@@ -40,9 +40,9 @@ After all reviewers complete, aggregate their verdicts:
 - If any reviewer says NEEDS-ATTENTION → overall verdict: `needs-attention`
 - If any reviewer says FAIL → overall verdict: `needs-remediation`
 
-### Step 3 — Write VALIDATION File
+### Step 3 — Persist Validation
 
-Write to `{{validationPath}}`:
+Prepare the validation content you will pass to `gsd_validate_milestone`. Do **not** manually write `{{validationPath}}` — the DB-backed tool is the canonical write path and renders the validation file for you.
 
 ```markdown
 ---
@@ -69,13 +69,15 @@ reviewers: 3
 <if verdict is not pass: specific actions required>
 ```
 
+Call `gsd_validate_milestone` with the camelCase fields `milestoneId`, `verdict`, `remediationRound`, `successCriteriaChecklist`, `sliceDeliveryAudit`, `crossSliceIntegration`, `requirementCoverage`, `verdictRationale`, and `remediationPlan` when needed. If you include verification-class analysis, pass it in `verificationClasses`.
+
 **DB access safety:** Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')` — the engine owns the WAL connection. Use `gsd_milestone_status` to read milestone and slice state. All data you need is already inlined in the context above or accessible via the `gsd_*` tools. Direct DB access corrupts the WAL and bypasses tool-level validation.
 
 If verdict is `needs-remediation`:
-- Add new slices to `{{roadmapPath}}` with unchecked `[ ]` status
-- These slices will be planned and executed before validation re-runs
+- Use `gsd_reassess_roadmap` to add the remediation slices instead of editing `{{roadmapPath}}` manually
+- Those slices will be planned and executed before validation re-runs
 
-**You MUST write `{{validationPath}}` before finishing.**
+**You MUST call `gsd_validate_milestone` before finishing. Do not manually write `{{validationPath}}`.**
 
 **File system safety:** When scanning milestone directories for evidence, use `ls` or `find` to list directory contents first — never pass a directory path (e.g. `tasks/`, `slices/`) directly to the `read` tool. The `read` tool only accepts file paths, not directories.
 

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

@@ -8,11 +8,13 @@ import { execSync } from "node:child_process";
 
 import {
   parseCodebaseMap,
+  parseCodebaseMapMetadata,
   generateCodebaseMap,
   updateCodebaseMap,
   writeCodebaseMap,
   readCodebaseMap,
   getCodebaseMapStats,
+  ensureCodebaseMapFresh,
 } from "../codebase-generator.ts";
 
 // ─── Helpers ──────────────────────────────────────────────────────────────
@@ -212,6 +214,24 @@ test("generateCodebaseMap: preserves existing descriptions", () => {
   }
 });
 
+test("generateCodebaseMap: writes freshness metadata comment", () => {
+  const base = makeTmpRepo();
+  try {
+    addFile(base, "src/main.ts");
+
+    const result = generateCodebaseMap(base);
+    const metadata = parseCodebaseMapMetadata(result.content);
+
+    assert.ok(metadata, "metadata comment should be present");
+    assert.equal(metadata?.fileCount, 1);
+    assert.equal(metadata?.truncated, false);
+    assert.equal(typeof metadata?.fingerprint, "string");
+    assert.ok(metadata?.generatedAt?.endsWith("Z"));
+  } finally {
+    cleanup(base);
+  }
+});
+
 test("generateCodebaseMap: collapses large directories", () => {
   const base = makeTmpRepo();
   try {
@@ -571,3 +591,51 @@ test("updateCodebaseMap: respects excludePatterns option", () => {
     cleanup(base);
   }
 });
+
+test("ensureCodebaseMapFresh: generates CODEBASE.md when missing", () => {
+  const base = makeTmpRepo();
+  try {
+    addFile(base, "src/main.ts");
+
+    const result = ensureCodebaseMapFresh(base, undefined, { ttlMs: 0, force: true });
+    const written = readCodebaseMap(base);
+
+    assert.equal(result.status, "generated");
+    assert.ok(written?.includes("`src/main.ts`"));
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("ensureCodebaseMapFresh: updates CODEBASE.md when tracked files change", () => {
+  const base = makeTmpRepo();
+  try {
+    addFile(base, "src/main.ts");
+    const initial = ensureCodebaseMapFresh(base, undefined, { ttlMs: 0, force: true });
+    assert.equal(initial.status, "generated");
+
+    addFile(base, "src/new.ts");
+    const refreshed = ensureCodebaseMapFresh(base, undefined, { ttlMs: 0, force: true });
+    const written = readCodebaseMap(base);
+
+    assert.equal(refreshed.status, "updated");
+    assert.equal(refreshed.reason, "files-changed");
+    assert.ok(written?.includes("`src/new.ts`"));
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("ensureCodebaseMapFresh: returns fresh when metadata matches repository state", () => {
+  const base = makeTmpRepo();
+  try {
+    addFile(base, "src/main.ts");
+    ensureCodebaseMapFresh(base, undefined, { ttlMs: 0, force: true });
+
+    const refreshed = ensureCodebaseMapFresh(base, undefined, { ttlMs: 0, force: true });
+    assert.equal(refreshed.status, "fresh");
+    assert.equal(refreshed.fileCount, 1);
+  } finally {
+    cleanup(base);
+  }
+});

package/src/resources/extensions/gsd/tests/commands-workflow-custom.test.ts

@@ -100,6 +100,18 @@ steps: []
 // ─── Catalog Registration ────────────────────────────────────────────────
 
 describe("workflow catalog registration", () => {
+  it("model appears in TOP_LEVEL_SUBCOMMANDS", () => {
+    const entry = TOP_LEVEL_SUBCOMMANDS.find((c) => c.cmd === "model");
+    assert.ok(entry, "model should be in TOP_LEVEL_SUBCOMMANDS");
+    assert.match(entry!.desc, /session model/i);
+  });
+
+  it("getGsdArgumentCompletions('m') includes model", () => {
+    const completions = getGsdArgumentCompletions("m");
+    const labels = completions.map((c: any) => c.label);
+    assert.ok(labels.includes("model"), "should include model completion");
+  });
+
   it("workflow appears in TOP_LEVEL_SUBCOMMANDS", () => {
     const entry = TOP_LEVEL_SUBCOMMANDS.find((c) => c.cmd === "workflow");
     assert.ok(entry, "workflow should be in TOP_LEVEL_SUBCOMMANDS");

package/src/resources/extensions/gsd/tests/core-overlay-fallback.test.ts

@@ -42,3 +42,35 @@ test("show-config only falls back when ctx.ui.custom() is unavailable", async ()
   assert.equal(fallbackCtx.notices.length, 1, "unavailable overlay triggers text fallback");
   assert.match(fallbackCtx.notices[0]!.message, /GSD Configuration/);
 });
+
+test("model command resolves and persists exact provider-qualified selection", async () => {
+  const selectedModel = { provider: "openai", id: "gpt-5.4" };
+  let applied: typeof selectedModel | null = null;
+  const ctx = {
+    hasUI: true,
+    model: { provider: "anthropic", id: "claude-sonnet-4-6" },
+    modelRegistry: {
+      getAvailable: () => [
+        { provider: "anthropic", id: "claude-sonnet-4-6" },
+        selectedModel,
+      ],
+    },
+    ui: {
+      notify: (message: string, type?: string) => {
+        notices.push({ message, type });
+      },
+    },
+  } as any;
+  const notices: Array<{ message: string; type?: string }> = [];
+  const pi = {
+    setModel: async (model: typeof selectedModel) => {
+      applied = model;
+      return true;
+    },
+  } as any;
+
+  const handled = await handleCoreCommand("model openai/gpt-5.4", ctx, pi);
+  assert.equal(handled, true);
+  assert.deepEqual(applied, selectedModel);
+  assert.match(notices[0]!.message, /openai\/gpt-5\.4/);
+});

package/src/resources/extensions/gsd/tests/preferences.test.ts

@@ -17,6 +17,7 @@ import {
   parsePreferencesMarkdown,
   _resetParseWarningFlag,
 } from "../preferences.ts";
+import { formatConfiguredModel, toPersistedModelId } from "../commands-prefs-wizard.ts";
 import { _resetLogs, peekLogs } from "../workflow-logger.ts";
 import type { GSDPreferences, GSDModelConfigV2, GSDPhaseModelConfig } from "../preferences.ts";
 
@@ -347,6 +348,22 @@ test("handles model config with explicit provider field", () => {
   assert.equal(execution.provider, "bedrock");
 });
 
+test("formatConfiguredModel renders provider-qualified object config", () => {
+  assert.equal(
+    formatConfiguredModel({ model: "claude-opus-4-6", provider: "bedrock" }),
+    "bedrock/claude-opus-4-6",
+  );
+});
+
+test("toPersistedModelId prefixes provider chosen in prefs wizard", () => {
+  assert.equal(toPersistedModelId("openai", "gpt-5.4"), "openai/gpt-5.4");
+  assert.equal(
+    toPersistedModelId("openai", "openai/gpt-5.4"),
+    "openai/gpt-5.4",
+    "already-qualified IDs should be preserved",
+  );
+});
+
 test("handles empty models config", () => {
   const prefs = parsePreferencesMarkdown("---\nversion: 1\n---\n");
   assert.notEqual(prefs, null);