gsd-pi 2.27.0 → 2.28.0-dev.346ee62

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

@@ -0,0 +1,747 @@
+/**
+ * GSD Preferences Wizard — TUI wizard for configuring GSD preferences.
+ *
+ * Contains: handlePrefsWizard, buildCategorySummaries, all configure* functions,
+ * serializePreferencesToFrontmatter, yamlSafeString, ensurePreferencesFile,
+ * handlePrefsMode, handleImportClaude, handlePrefs
+ */
+
+import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  getGlobalGSDPreferencesPath,
+  getLegacyGlobalGSDPreferencesPath,
+  getProjectGSDPreferencesPath,
+  loadGlobalGSDPreferences,
+  loadProjectGSDPreferences,
+  loadEffectiveGSDPreferences,
+  resolveAllSkillReferences,
+} from "./preferences.js";
+import { loadFile, saveFile, splitFrontmatter, parseFrontmatterMap } from "./files.js";
+import { runClaudeImportFlow } from "./claude-import.js";
+
+export async function handlePrefs(args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const trimmed = args.trim();
+
+  if (trimmed === "" || trimmed === "global" || trimmed === "wizard" || trimmed === "setup"
+    || trimmed === "wizard global" || trimmed === "setup global") {
+    await ensurePreferencesFile(getGlobalGSDPreferencesPath(), ctx, "global");
+    await handlePrefsWizard(ctx, "global");
+    return;
+  }
+
+  if (trimmed === "project" || trimmed === "wizard project" || trimmed === "setup project") {
+    await ensurePreferencesFile(getProjectGSDPreferencesPath(), ctx, "project");
+    await handlePrefsWizard(ctx, "project");
+    return;
+  }
+
+  if (trimmed === "import-claude" || trimmed === "import-claude global") {
+    await handleImportClaude(ctx, "global");
+    return;
+  }
+
+  if (trimmed === "import-claude project") {
+    await handleImportClaude(ctx, "project");
+    return;
+  }
+  if (trimmed === "status") {
+    const globalPrefs = loadGlobalGSDPreferences();
+    const projectPrefs = loadProjectGSDPreferences();
+    const canonicalGlobal = getGlobalGSDPreferencesPath();
+    const legacyGlobal = getLegacyGlobalGSDPreferencesPath();
+    const globalStatus = globalPrefs
+      ? `present: ${globalPrefs.path}${globalPrefs.path === legacyGlobal ? " (legacy fallback)" : ""}`
+      : `missing: ${canonicalGlobal}`;
+    const projectStatus = projectPrefs ? `present: ${projectPrefs.path}` : `missing: ${getProjectGSDPreferencesPath()}`;
+
+    const lines = [`GSD skill prefs — global ${globalStatus}; project ${projectStatus}`];
+
+    const effective = loadEffectiveGSDPreferences();
+    let hasUnresolved = false;
+    if (effective) {
+      const report = resolveAllSkillReferences(effective.preferences, process.cwd());
+      const resolved = [...report.resolutions.values()].filter(r => r.method !== "unresolved");
+      hasUnresolved = report.warnings.length > 0;
+      if (resolved.length > 0 || hasUnresolved) {
+        lines.push(`Skills: ${resolved.length} resolved, ${report.warnings.length} unresolved`);
+      }
+      if (hasUnresolved) {
+        lines.push(`Unresolved: ${report.warnings.join(", ")}`);
+      }
+    }
+
+    ctx.ui.notify(lines.join("\n"), hasUnresolved ? "warning" : "info");
+    return;
+  }
+
+  ctx.ui.notify("Usage: /gsd prefs [global|project|status|wizard|setup|import-claude [global|project]]", "info");
+}
+
+export async function handleImportClaude(ctx: ExtensionCommandContext, scope: "global" | "project"): Promise<void> {
+  const path = scope === "project" ? getProjectGSDPreferencesPath() : getGlobalGSDPreferencesPath();
+  if (!existsSync(path)) {
+    await ensurePreferencesFile(path, ctx, scope);
+  }
+
+  const readPrefs = (): Record<string, unknown> => {
+    if (!existsSync(path)) return { version: 1 };
+    const content = readFileSync(path, "utf-8");
+    const [frontmatterLines] = splitFrontmatter(content);
+    return frontmatterLines ? parseFrontmatterMap(frontmatterLines) : { version: 1 };
+  };
+
+  const writePrefs = async (prefs: Record<string, unknown>): Promise<void> => {
+    prefs.version = prefs.version || 1;
+    const frontmatter = serializePreferencesToFrontmatter(prefs);
+    let body = "\n# GSD Skill Preferences\n\nSee `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation and examples.\n";
+    if (existsSync(path)) {
+      const existingContent = readFileSync(path, "utf-8");
+      const closingIdx = existingContent.indexOf("\n---", existingContent.indexOf("---"));
+      if (closingIdx !== -1) {
+        const afterFrontmatter = existingContent.slice(closingIdx + 4);
+        if (afterFrontmatter.trim()) body = afterFrontmatter;
+      }
+    }
+    await saveFile(path, `---\n${frontmatter}---${body}`);
+  };
+
+  await runClaudeImportFlow(ctx, scope, readPrefs, writePrefs);
+}
+
+export async function handlePrefsMode(ctx: ExtensionCommandContext, scope: "global" | "project"): Promise<void> {
+  const path = scope === "project" ? getProjectGSDPreferencesPath() : getGlobalGSDPreferencesPath();
+  const existing = scope === "project" ? loadProjectGSDPreferences() : loadGlobalGSDPreferences();
+  const prefs: Record<string, unknown> = existing?.preferences ? { ...existing.preferences } : {};
+
+  await configureMode(ctx, prefs);
+
+  // Serialize and save
+  prefs.version = prefs.version || 1;
+  const frontmatter = serializePreferencesToFrontmatter(prefs);
+
+  let body = "\n# GSD Skill Preferences\n\nSee `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation and examples.\n";
+  if (existsSync(path)) {
+    const existingContent = readFileSync(path, "utf-8");
+    const closingIdx = existingContent.indexOf("\n---", existingContent.indexOf("---"));
+    if (closingIdx !== -1) {
+      const afterFrontmatter = existingContent.slice(closingIdx + 4);
+      if (afterFrontmatter.trim()) {
+        body = afterFrontmatter;
+      }
+    }
+  }
+
+  const content = `---\n${frontmatter}---${body}`;
+  await saveFile(path, content);
+  await ctx.waitForIdle();
+  await ctx.reload();
+  ctx.ui.notify(`Saved ${scope} preferences to ${path}`, "info");
+}
+
+/** Build short summary strings for each preference category. */
+export function buildCategorySummaries(prefs: Record<string, unknown>): Record<string, string> {
+  // Mode
+  const mode = prefs.mode as string | undefined;
+  const modeSummary = mode ?? "(not set)";
+
+  // Models
+  const models = prefs.models as Record<string, string> | undefined;
+  let modelsSummary = "(not configured)";
+  if (models && Object.keys(models).length > 0) {
+    const parts = Object.entries(models).map(([phase, model]) => `${phase}: ${model}`);
+    modelsSummary = parts.join(", ");
+  }
+
+  // Timeouts
+  const autoSup = prefs.auto_supervisor as Record<string, unknown> | undefined;
+  let timeoutsSummary = "(defaults)";
+  if (autoSup && Object.keys(autoSup).length > 0) {
+    const soft = autoSup.soft_timeout_minutes ?? "20";
+    const idle = autoSup.idle_timeout_minutes ?? "10";
+    const hard = autoSup.hard_timeout_minutes ?? "30";
+    timeoutsSummary = `soft: ${soft}m, idle: ${idle}m, hard: ${hard}m`;
+  }
+
+  // Git
+  const git = prefs.git as Record<string, unknown> | undefined;
+  let gitSummary = "(defaults)";
+  if (git && Object.keys(git).length > 0) {
+    const branch = git.main_branch ?? "main";
+    const push = git.auto_push ? "on" : "off";
+    gitSummary = `main: ${branch}, push: ${push}`;
+  }
+
+  // Skills
+  const discovery = prefs.skill_discovery as string | undefined;
+  const uat = prefs.uat_dispatch;
+  let skillsSummary = "(not configured)";
+  if (discovery || uat !== undefined) {
+    const parts: string[] = [];
+    if (discovery) parts.push(`discovery: ${discovery}`);
+    if (uat !== undefined) parts.push(`uat: ${uat}`);
+    skillsSummary = parts.join(", ");
+  }
+
+  // Budget
+  const ceiling = prefs.budget_ceiling;
+  const enforcement = prefs.budget_enforcement as string | undefined;
+  let budgetSummary = "(no limit)";
+  if (ceiling !== undefined) {
+    budgetSummary = `$${ceiling}`;
+    if (enforcement) budgetSummary += ` / ${enforcement}`;
+  } else if (enforcement) {
+    budgetSummary = enforcement;
+  }
+
+  // Notifications
+  const notif = prefs.notifications as Record<string, boolean> | undefined;
+  let notifSummary = "(defaults)";
+  if (notif && Object.keys(notif).length > 0) {
+    const allKeys = ["enabled", "on_complete", "on_error", "on_budget", "on_milestone", "on_attention"];
+    const enabledCount = allKeys.filter(k => notif[k] !== false).length;
+    notifSummary = `${enabledCount}/${allKeys.length} enabled`;
+  }
+
+  // Advanced
+  const uniqueIds = prefs.unique_milestone_ids;
+  let advancedSummary = "(defaults)";
+  if (uniqueIds !== undefined) {
+    advancedSummary = `unique IDs: ${uniqueIds ? "on" : "off"}`;
+  }
+
+  return {
+    mode: modeSummary,
+    models: modelsSummary,
+    timeouts: timeoutsSummary,
+    git: gitSummary,
+    skills: skillsSummary,
+    budget: budgetSummary,
+    notifications: notifSummary,
+    advanced: advancedSummary,
+  };
+}
+
+// ─── Category configuration functions ────────────────────────────────────────
+
+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 availableModels = ctx.modelRegistry.getAvailable();
+  if (availableModels.length > 0) {
+    // Group models by provider, sorted alphabetically
+    const byProvider = new Map<string, typeof availableModels>();
+    for (const m of availableModels) {
+      let group = byProvider.get(m.provider);
+      if (!group) {
+        group = [];
+        byProvider.set(m.provider, group);
+      }
+      group.push(m);
+    }
+    const providers = Array.from(byProvider.keys()).sort((a, b) => a.localeCompare(b));
+
+    const modelOptions: string[] = [];
+    for (const provider of providers) {
+      const group = byProvider.get(provider)!;
+      modelOptions.push(`─── ${provider} (${group.length}) ───`);
+      for (const m of group) {
+        modelOptions.push(`${m.id} · ${m.provider}`);
+      }
+    }
+    modelOptions.push("(keep current)", "(clear)");
+
+    for (const phase of modelPhases) {
+      const current = models[phase] ?? "";
+      const title = `Model for ${phase} phase${current ? ` (current: ${current})` : ""}:`;
+      const choice = await ctx.ui.select(title, modelOptions);
+
+      if (choice && typeof choice === "string" && choice !== "(keep current)") {
+        if (choice === "(clear)") {
+          delete models[phase];
+        } else {
+          models[phase] = choice.split(" · ")[0];
+        }
+      }
+    }
+  } else {
+    for (const phase of modelPhases) {
+      const current = models[phase] ?? "";
+      const input = await ctx.ui.input(
+        `Model for ${phase} phase${current ? ` (current: ${current})` : ""}:`,
+        current || "e.g. claude-sonnet-4-20250514",
+      );
+      if (input !== null && input !== undefined) {
+        const val = input.trim();
+        if (val) {
+          models[phase] = val;
+        } else if (current) {
+          delete models[phase];
+        }
+      }
+    }
+  }
+  if (Object.keys(models).length > 0) {
+    prefs.models = models;
+  }
+}
+
+async function configureTimeouts(ctx: ExtensionCommandContext, prefs: Record<string, unknown>): Promise<void> {
+  const autoSup: Record<string, unknown> = (prefs.auto_supervisor as Record<string, unknown>) ?? {};
+  const timeoutFields = [
+    { key: "soft_timeout_minutes", label: "Soft timeout (minutes)", defaultVal: "20" },
+    { key: "idle_timeout_minutes", label: "Idle timeout (minutes)", defaultVal: "10" },
+    { key: "hard_timeout_minutes", label: "Hard timeout (minutes)", defaultVal: "30" },
+  ] as const;
+
+  for (const field of timeoutFields) {
+    const current = autoSup[field.key];
+    const currentStr = current !== undefined && current !== null ? String(current) : "";
+    const input = await ctx.ui.input(
+      `${field.label}${currentStr ? ` (current: ${currentStr})` : ` (default: ${field.defaultVal})`}:`,
+      currentStr || field.defaultVal,
+    );
+    if (input !== null && input !== undefined) {
+      const val = input.trim();
+      if (val && /^\d+$/.test(val)) {
+        autoSup[field.key] = Number(val);
+      } else if (val && !/^\d+$/.test(val)) {
+        ctx.ui.notify(`Invalid value "${val}" for ${field.label} — must be a whole number. Keeping previous value.`, "warning");
+      } else if (!val && currentStr) {
+        delete autoSup[field.key];
+      }
+    }
+  }
+  if (Object.keys(autoSup).length > 0) {
+    prefs.auto_supervisor = autoSup;
+  }
+}
+
+async function configureGit(ctx: ExtensionCommandContext, prefs: Record<string, unknown>): Promise<void> {
+  const git: Record<string, unknown> = (prefs.git as Record<string, unknown>) ?? {};
+
+  // main_branch
+  const currentBranch = git.main_branch ? String(git.main_branch) : "";
+  const branchInput = await ctx.ui.input(
+    `Git main branch${currentBranch ? ` (current: ${currentBranch})` : ""}:`,
+    currentBranch || "main",
+  );
+  if (branchInput !== null && branchInput !== undefined) {
+    const val = branchInput.trim();
+    if (val) {
+      git.main_branch = val;
+    } else if (currentBranch) {
+      delete git.main_branch;
+    }
+  }
+
+  // Boolean git toggles
+  const gitBooleanFields = [
+    { key: "auto_push", label: "Auto-push commits after committing", defaultVal: false },
+    { key: "push_branches", label: "Push milestone branches to remote", defaultVal: false },
+    { key: "snapshots", label: "Create WIP snapshot commits during long tasks", defaultVal: false },
+  ] as const;
+
+  for (const field of gitBooleanFields) {
+    const current = git[field.key];
+    const currentStr = current !== undefined ? String(current) : "";
+    const choice = await ctx.ui.select(
+      `${field.label}${currentStr ? ` (current: ${currentStr})` : ` (default: ${field.defaultVal})`}:`,
+      ["true", "false", "(keep current)"],
+    );
+    if (choice && choice !== "(keep current)") {
+      git[field.key] = choice === "true";
+    }
+  }
+
+  // remote
+  const currentRemote = git.remote ? String(git.remote) : "";
+  const remoteInput = await ctx.ui.input(
+    `Git remote name${currentRemote ? ` (current: ${currentRemote})` : " (default: origin)"}:`,
+    currentRemote || "origin",
+  );
+  if (remoteInput !== null && remoteInput !== undefined) {
+    const val = remoteInput.trim();
+    if (val && val !== "origin") {
+      git.remote = val;
+    } else if (!val && currentRemote) {
+      delete git.remote;
+    }
+  }
+
+  // pre_merge_check
+  const currentPreMerge = git.pre_merge_check !== undefined ? String(git.pre_merge_check) : "";
+  const preMergeChoice = await ctx.ui.select(
+    `Pre-merge check${currentPreMerge ? ` (current: ${currentPreMerge})` : " (default: false)"}:`,
+    ["true", "false", "auto", "(keep current)"],
+  );
+  if (preMergeChoice && preMergeChoice !== "(keep current)") {
+    if (preMergeChoice === "auto") {
+      git.pre_merge_check = "auto";
+    } else {
+      git.pre_merge_check = preMergeChoice === "true";
+    }
+  }
+
+  // commit_type
+  const currentCommitType = git.commit_type ? String(git.commit_type) : "";
+  const commitTypes = ["feat", "fix", "refactor", "docs", "test", "chore", "perf", "ci", "build", "style", "(inferred — default)", "(keep current)"];
+  const commitChoice = await ctx.ui.select(
+    `Default commit type${currentCommitType ? ` (current: ${currentCommitType})` : ""}:`,
+    commitTypes,
+  );
+  if (commitChoice && typeof commitChoice === "string" && commitChoice !== "(keep current)") {
+    if ((commitChoice as string).startsWith("(inferred")) {
+      delete git.commit_type;
+    } else {
+      git.commit_type = commitChoice;
+    }
+  }
+
+  // merge_strategy
+  const currentMerge = git.merge_strategy ? String(git.merge_strategy) : "";
+  const mergeChoice = await ctx.ui.select(
+    `Merge strategy${currentMerge ? ` (current: ${currentMerge})` : ""}:`,
+    ["squash", "merge", "(keep current)"],
+  );
+  if (mergeChoice && mergeChoice !== "(keep current)") {
+    git.merge_strategy = mergeChoice;
+  }
+
+  // isolation
+  const currentIsolation = git.isolation ? String(git.isolation) : "";
+  const isolationChoice = await ctx.ui.select(
+    `Git isolation strategy${currentIsolation ? ` (current: ${currentIsolation})` : " (default: worktree)"}:`,
+    ["worktree", "branch", "none", "(keep current)"],
+  );
+  if (isolationChoice && isolationChoice !== "(keep current)") {
+    git.isolation = isolationChoice;
+  }
+
+  // commit_docs
+  const currentCommitDocs = git.commit_docs;
+  const commitDocsChoice = await ctx.ui.select(
+    `Track .gsd/ planning docs in git${currentCommitDocs !== undefined ? ` (current: ${currentCommitDocs})` : ""}:`,
+    ["true", "false", "(keep current)"],
+  );
+  if (commitDocsChoice && commitDocsChoice !== "(keep current)") {
+    git.commit_docs = commitDocsChoice === "true";
+  }
+
+  if (Object.keys(git).length > 0) {
+    prefs.git = git;
+  }
+}
+
+async function configureSkills(ctx: ExtensionCommandContext, prefs: Record<string, unknown>): Promise<void> {
+  // Skill discovery mode
+  const currentDiscovery = (prefs.skill_discovery as string) ?? "";
+  const discoveryChoice = await ctx.ui.select(
+    `Skill discovery mode${currentDiscovery ? ` (current: ${currentDiscovery})` : ""}:`,
+    ["auto", "suggest", "off", "(keep current)"],
+  );
+  if (discoveryChoice && discoveryChoice !== "(keep current)") {
+    prefs.skill_discovery = discoveryChoice;
+  }
+
+  // UAT dispatch
+  const currentUat = prefs.uat_dispatch;
+  const uatChoice = await ctx.ui.select(
+    `UAT dispatch mode${currentUat !== undefined ? ` (current: ${currentUat})` : " (default: false)"}:`,
+    ["true", "false", "(keep current)"],
+  );
+  if (uatChoice && uatChoice !== "(keep current)") {
+    prefs.uat_dispatch = uatChoice === "true";
+  }
+}
+
+async function configureBudget(ctx: ExtensionCommandContext, prefs: Record<string, unknown>): Promise<void> {
+  const currentCeiling = prefs.budget_ceiling;
+  const ceilingStr = currentCeiling !== undefined ? String(currentCeiling) : "";
+  const ceilingInput = await ctx.ui.input(
+    `Budget ceiling (USD)${ceilingStr ? ` (current: $${ceilingStr})` : " (default: no limit)"}:`,
+    ceilingStr || "",
+  );
+  if (ceilingInput !== null && ceilingInput !== undefined) {
+    const val = ceilingInput.trim().replace(/^\$/, "");
+    if (val && !isNaN(Number(val)) && isFinite(Number(val))) {
+      prefs.budget_ceiling = Number(val);
+    } else if (val && (isNaN(Number(val)) || !isFinite(Number(val)))) {
+      ctx.ui.notify(`Invalid budget ceiling "${val}" — must be a number. Keeping previous value.`, "warning");
+    } else if (!val && ceilingStr) {
+      delete prefs.budget_ceiling;
+    }
+  }
+
+  const currentEnforcement = (prefs.budget_enforcement as string) ?? "";
+  const enforcementChoice = await ctx.ui.select(
+    `Budget enforcement${currentEnforcement ? ` (current: ${currentEnforcement})` : " (default: pause)"}:`,
+    ["warn", "pause", "halt", "(keep current)"],
+  );
+  if (enforcementChoice && enforcementChoice !== "(keep current)") {
+    prefs.budget_enforcement = enforcementChoice;
+  }
+
+  const currentContextPause = prefs.context_pause_threshold;
+  const contextPauseStr = currentContextPause !== undefined ? String(currentContextPause) : "";
+  const contextPauseInput = await ctx.ui.input(
+    `Context pause threshold (0-100%, 0=disabled)${contextPauseStr ? ` (current: ${contextPauseStr}%)` : " (default: 0)"}:`,
+    contextPauseStr || "0",
+  );
+  if (contextPauseInput !== null && contextPauseInput !== undefined) {
+    const val = contextPauseInput.trim().replace(/%$/, "");
+    if (val && !isNaN(Number(val)) && Number(val) >= 0 && Number(val) <= 100) {
+      const num = Number(val);
+      if (num === 0) {
+        delete prefs.context_pause_threshold;
+      } else {
+        prefs.context_pause_threshold = num;
+      }
+    } else if (val && (isNaN(Number(val)) || Number(val) < 0 || Number(val) > 100)) {
+      ctx.ui.notify(`Invalid context pause threshold "${val}" — must be 0-100. Keeping previous value.`, "warning");
+    }
+  }
+}
+
+async function configureNotifications(ctx: ExtensionCommandContext, prefs: Record<string, unknown>): Promise<void> {
+  const notif: Record<string, boolean> = (prefs.notifications as Record<string, boolean>) ?? {};
+  const notifFields = [
+    { key: "enabled", label: "Notifications enabled (master toggle)", defaultVal: true },
+    { key: "on_complete", label: "Notify on unit completion", defaultVal: true },
+    { key: "on_error", label: "Notify on errors", defaultVal: true },
+    { key: "on_budget", label: "Notify on budget thresholds", defaultVal: true },
+    { key: "on_milestone", label: "Notify on milestone completion", defaultVal: true },
+    { key: "on_attention", label: "Notify when manual attention needed", defaultVal: true },
+  ] as const;
+
+  for (const field of notifFields) {
+    const current = notif[field.key];
+    const currentStr = current !== undefined && typeof current === "boolean" ? String(current) : "";
+    const choice = await ctx.ui.select(
+      `${field.label}${currentStr ? ` (current: ${currentStr})` : ` (default: ${field.defaultVal})`}:`,
+      ["true", "false", "(keep current)"],
+    );
+    if (choice && choice !== "(keep current)") {
+      notif[field.key] = choice === "true";
+    }
+  }
+  if (Object.keys(notif).length > 0) {
+    prefs.notifications = notif;
+  }
+}
+
+export async function configureMode(ctx: ExtensionCommandContext, prefs: Record<string, unknown>): Promise<void> {
+  const currentMode = prefs.mode as string | undefined;
+  const modeChoice = await ctx.ui.select(
+    `Workflow mode${currentMode ? ` (current: ${currentMode})` : ""}:`,
+    [
+      "solo — auto-push, squash, simple IDs (personal projects)",
+      "team — unique IDs, push branches, pre-merge checks (shared repos)",
+      "(none) — configure everything manually",
+      "(keep current)",
+    ],
+  );
+  const modeStr = typeof modeChoice === "string" ? modeChoice : "";
+  if (modeStr && modeStr !== "(keep current)") {
+    if (modeStr.startsWith("solo")) {
+      prefs.mode = "solo";
+      ctx.ui.notify(
+        "Mode: solo — defaults: auto_push=true, push_branches=false, pre_merge_check=false, merge_strategy=squash, isolation=worktree, commit_docs=true, unique_milestone_ids=false",
+        "info",
+      );
+    } else if (modeStr.startsWith("team")) {
+      prefs.mode = "team";
+      ctx.ui.notify(
+        "Mode: team — defaults: auto_push=false, push_branches=true, pre_merge_check=true, merge_strategy=squash, isolation=worktree, commit_docs=true, unique_milestone_ids=true",
+        "info",
+      );
+    } else {
+      delete prefs.mode;
+    }
+  }
+}
+
+async function configureAdvanced(ctx: ExtensionCommandContext, prefs: Record<string, unknown>): Promise<void> {
+  const currentUnique = prefs.unique_milestone_ids;
+  const uniqueChoice = await ctx.ui.select(
+    `Unique milestone IDs${currentUnique !== undefined ? ` (current: ${currentUnique})` : ""}:`,
+    ["true", "false", "(keep current)"],
+  );
+  if (uniqueChoice && uniqueChoice !== "(keep current)") {
+    prefs.unique_milestone_ids = uniqueChoice === "true";
+  }
+}
+
+// ─── Main wizard with category menu ─────────────────────────────────────────
+
+export async function handlePrefsWizard(
+  ctx: ExtensionCommandContext,
+  scope: "global" | "project",
+): Promise<void> {
+  const path = scope === "project" ? getProjectGSDPreferencesPath() : getGlobalGSDPreferencesPath();
+  const existing = scope === "project" ? loadProjectGSDPreferences() : loadGlobalGSDPreferences();
+  const prefs: Record<string, unknown> = existing?.preferences ? { ...existing.preferences } : {};
+
+  ctx.ui.notify(`GSD preferences (${scope}) — pick a category to configure.`, "info");
+
+  while (true) {
+    const summaries = buildCategorySummaries(prefs);
+    const options = [
+      `Workflow Mode   ${summaries.mode}`,
+      `Models          ${summaries.models}`,
+      `Timeouts        ${summaries.timeouts}`,
+      `Git             ${summaries.git}`,
+      `Skills          ${summaries.skills}`,
+      `Budget          ${summaries.budget}`,
+      `Notifications   ${summaries.notifications}`,
+      `Advanced        ${summaries.advanced}`,
+      `── Save & Exit ──`,
+    ];
+
+    const raw = await ctx.ui.select("GSD Preferences", options);
+    const choice = typeof raw === "string" ? raw : "";
+    if (!choice || choice.includes("Save & Exit")) break;
+
+    if (choice.startsWith("Workflow Mode"))      await configureMode(ctx, prefs);
+    else if (choice.startsWith("Models"))        await configureModels(ctx, prefs);
+    else if (choice.startsWith("Timeouts"))      await configureTimeouts(ctx, prefs);
+    else if (choice.startsWith("Git"))           await configureGit(ctx, prefs);
+    else if (choice.startsWith("Skills"))        await configureSkills(ctx, prefs);
+    else if (choice.startsWith("Budget"))        await configureBudget(ctx, prefs);
+    else if (choice.startsWith("Notifications")) await configureNotifications(ctx, prefs);
+    else if (choice.startsWith("Advanced"))      await configureAdvanced(ctx, prefs);
+  }
+
+  // ─── Serialize to frontmatter ───────────────────────────────────────────
+  prefs.version = prefs.version || 1;
+  const frontmatter = serializePreferencesToFrontmatter(prefs);
+
+  // Preserve existing body content (everything after closing ---)
+  let body = "\n# GSD Skill Preferences\n\nSee `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation and examples.\n";
+  if (existsSync(path)) {
+    const existingContent = readFileSync(path, "utf-8");
+    const closingIdx = existingContent.indexOf("\n---", existingContent.indexOf("---"));
+    if (closingIdx !== -1) {
+      const afterFrontmatter = existingContent.slice(closingIdx + 4); // skip past "\n---"
+      if (afterFrontmatter.trim()) {
+        body = afterFrontmatter;
+      }
+    }
+  }
+
+  const content = `---\n${frontmatter}---${body}`;
+
+  await saveFile(path, content);
+  await ctx.waitForIdle();
+  await ctx.reload();
+  ctx.ui.notify(`Saved ${scope} preferences to ${path}`, "info");
+}
+
+/** Wrap a YAML value in double quotes if it contains special characters. */
+export function yamlSafeString(val: unknown): string {
+  if (typeof val !== "string") return String(val);
+  if (/[:#{\[\]'"`,|>&*!?@%]/.test(val) || val.trim() !== val || val === "") {
+    return `"${val.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  }
+  return val;
+}
+
+export function serializePreferencesToFrontmatter(prefs: Record<string, unknown>): string {
+  const lines: string[] = [];
+
+  function serializeValue(key: string, value: unknown, indent: number): void {
+    const prefix = "  ".repeat(indent);
+    if (value === null || value === undefined) return;
+
+    if (Array.isArray(value)) {
+      if (value.length === 0) {
+        return; // Omit empty arrays — avoids parse/serialize cycle bug with "[]" strings
+      }
+      lines.push(`${prefix}${key}:`);
+      for (const item of value) {
+        if (typeof item === "object" && item !== null) {
+          const entries = Object.entries(item as Record<string, unknown>);
+          if (entries.length > 0) {
+            const [firstKey, firstVal] = entries[0];
+            lines.push(`${prefix}  - ${firstKey}: ${yamlSafeString(firstVal)}`);
+            for (let i = 1; i < entries.length; i++) {
+              const [k, v] = entries[i];
+              if (Array.isArray(v)) {
+                lines.push(`${prefix}    ${k}:`);
+                for (const arrItem of v) {
+                  lines.push(`${prefix}      - ${yamlSafeString(arrItem)}`);
+                }
+              } else {
+                lines.push(`${prefix}    ${k}: ${yamlSafeString(v)}`);
+              }
+            }
+          }
+        } else {
+          lines.push(`${prefix}  - ${yamlSafeString(item)}`);
+        }
+      }
+      return;
+    }
+
+    if (typeof value === "object") {
+      const entries = Object.entries(value as Record<string, unknown>);
+      if (entries.length === 0) {
+        return; // Omit empty objects — avoids parse/serialize cycle bug with "{}" strings
+      }
+      lines.push(`${prefix}${key}:`);
+      for (const [k, v] of entries) {
+        serializeValue(k, v, indent + 1);
+      }
+      return;
+    }
+
+    lines.push(`${prefix}${key}: ${yamlSafeString(value)}`);
+  }
+
+  // Ordered keys for consistent output
+  const orderedKeys = [
+    "version", "mode", "always_use_skills", "prefer_skills", "avoid_skills",
+    "skill_rules", "custom_instructions", "models", "skill_discovery",
+    "auto_supervisor", "uat_dispatch", "unique_milestone_ids",
+    "budget_ceiling", "budget_enforcement", "context_pause_threshold",
+    "notifications", "remote_questions", "git",
+    "post_unit_hooks", "pre_dispatch_hooks",
+  ];
+
+  const seen = new Set<string>();
+  for (const key of orderedKeys) {
+    if (key in prefs) {
+      serializeValue(key, prefs[key], 0);
+      seen.add(key);
+    }
+  }
+  // Any remaining keys not in the ordered list
+  for (const [key, value] of Object.entries(prefs)) {
+    if (!seen.has(key)) {
+      serializeValue(key, value, 0);
+    }
+  }
+
+  return lines.join("\n") + "\n";
+}
+
+export async function ensurePreferencesFile(
+  path: string,
+  ctx: ExtensionCommandContext,
+  scope: "global" | "project",
+): Promise<void> {
+  if (!existsSync(path)) {
+    const template = await loadFile(join(dirname(fileURLToPath(import.meta.url)), "templates", "preferences.md"));
+    if (!template) {
+      ctx.ui.notify("Could not load GSD preferences template.", "error");
+      return;
+    }
+    await saveFile(path, template);
+    ctx.ui.notify(`Created ${scope} GSD skill preferences at ${path}`, "info");
+  } else {
+    ctx.ui.notify(`Using existing ${scope} GSD skill preferences at ${path}`, "info");
+  }
+}