gsd-pi 2.28.0-dev.e19bf89 → 2.29.0-dev.2ccf3fb

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

@@ -13,7 +13,8 @@ import { deriveState } from "./state.js";
 import { GSDDashboardOverlay } from "./dashboard-overlay.js";
 import { GSDVisualizerOverlay } from "./visualizer-overlay.js";
 import { showQueue, showDiscuss, showHeadlessMilestoneCreation } from "./guided-flow.js";
-import { startAuto, stopAuto, pauseAuto, isAutoActive, isAutoPaused, isStepMode, stopAutoRemote, dispatchDirectPhase } from "./auto.js";
+import { startAuto, stopAuto, pauseAuto, isAutoActive, isAutoPaused, isStepMode, stopAutoRemote } from "./auto.js";
+import { dispatchDirectPhase } from "./auto-direct-dispatch.js";
 import { resolveProjectRoot } from "./worktree.js";
 import { assertSafeDirectory } from "./validate-directory.js";
 import {
@@ -21,8 +22,6 @@ import {
   getProjectGSDPreferencesPath,
   loadEffectiveGSDPreferences,
 } from "./preferences.js";
-import { loadPrompt } from "./prompt-loader.js";
-
 import { handleRemote } from "../remote-questions/mod.js";
 import { handleQuick } from "./quick.js";
 import { handleHistory } from "./history.js";
@@ -43,31 +42,9 @@ import { handleConfig } from "./commands-config.js";
 import { handleInspect } from "./commands-inspect.js";
 import { handleCleanupBranches, handleCleanupSnapshots, handleSkip, handleDryRun } from "./commands-maintenance.js";
 import { handleDoctor, handleSteer, handleCapture, handleTriage, handleKnowledge, handleRunHook, handleUpdate, handleSkillHealth } from "./commands-handlers.js";
+import { handleLogs } from "./commands-logs.js";
+import { handleStart, handleTemplates, getTemplateCompletions } from "./commands-workflow-templates.js";
 
-// ─── Re-exports (preserve public API surface) ───────────────────────────────
-export { handlePrefs, handlePrefsMode, handlePrefsWizard, ensurePreferencesFile, handleImportClaude, buildCategorySummaries, serializePreferencesToFrontmatter, yamlSafeString, configureMode } from "./commands-prefs-wizard.js";
-export { TOOL_KEYS, loadToolApiKeys, getConfigAuthStorage, handleConfig } from "./commands-config.js";
-export { type InspectData, formatInspectOutput, handleInspect } from "./commands-inspect.js";
-export { handleCleanupBranches, handleCleanupSnapshots, handleSkip, handleDryRun } from "./commands-maintenance.js";
-export { handleDoctor, handleSteer, handleCapture, handleTriage, handleKnowledge, handleRunHook, handleUpdate, handleSkillHealth } from "./commands-handlers.js";
-
-export function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined, reportText: string, structuredIssues: string): void {
-  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".pi", "GSD-WORKFLOW.md");
-  const workflow = readFileSync(workflowPath, "utf-8");
-  const prompt = loadPrompt("doctor-heal", {
-    doctorSummary: reportText,
-    structuredIssues,
-    scopeLabel: scope ?? "active milestone / blocking scope",
-    doctorCommandSuffix: scope ? ` ${scope}` : "",
-  });
-
-  const content = `Read the following GSD workflow protocol and execute exactly.\n\n${workflow}\n\n## Your Task\n\n${prompt}`;
-
-  pi.sendMessage(
-    { customType: "gsd-doctor-heal", content, display: false },
-    { triggerTurn: true },
-  );
-}
 
 /** Resolve the effective project root, accounting for worktree paths. */
 export function projectRoot(): string {
@@ -78,7 +55,7 @@ export function projectRoot(): string {
 
 export function registerGSDCommand(pi: ExtensionAPI): void {
   pi.registerCommand("gsd", {
-    description: "GSD — Get Shit Done: /gsd help|next|auto|stop|pause|status|visualize|queue|quick|capture|triage|dispatch|history|undo|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|forensics|migrate|remote|steer|knowledge|new-milestone|parallel|update",
+    description: "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|visualize|queue|quick|capture|triage|dispatch|history|undo|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|forensics|migrate|remote|steer|knowledge|new-milestone|parallel|update",
     getArgumentCompletions: (prefix: string) => {
       const subcommands = [
         { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -107,6 +84,7 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         { cmd: "run-hook", desc: "Manually trigger a specific hook" },
         { cmd: "skill-health", desc: "Skill lifecycle dashboard" },
         { cmd: "doctor", desc: "Runtime health checks with auto-fix" },
+        { cmd: "logs", desc: "Browse activity logs, debug logs, and metrics" },
         { cmd: "forensics", desc: "Examine execution logs" },
         { cmd: "init", desc: "Project init wizard — detect, configure, bootstrap .gsd/" },
         { cmd: "setup", desc: "Global setup status and configuration" },
@@ -120,6 +98,8 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         { cmd: "park", desc: "Park a milestone — skip without deleting" },
         { cmd: "unpark", desc: "Reactivate a parked milestone" },
         { cmd: "update", desc: "Update GSD to the latest version" },
+        { cmd: "start", desc: "Start a workflow template (bugfix, spike, feature, etc.)" },
+        { cmd: "templates", desc: "List available workflow templates" },
       ];
       const parts = prefix.trim().split(/\s+/);
 
@@ -184,6 +164,18 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
           .map((s) => ({ value: `setup ${s.cmd}`, label: s.cmd, description: s.desc }));
       }
 
+      if (parts[0] === "logs" && parts.length <= 2) {
+        const subPrefix = parts[1] ?? "";
+        const subs = [
+          { cmd: "debug", desc: "List or view debug log files" },
+          { cmd: "tail", desc: "Show last N activity log summaries" },
+          { cmd: "clear", desc: "Remove old activity and debug logs" },
+        ];
+        return subs
+          .filter((s) => s.cmd.startsWith(subPrefix))
+          .map((s) => ({ value: `logs ${s.cmd}`, label: s.cmd, description: s.desc }));
+      }
+
       if (parts[0] === "keys" && parts.length <= 2) {
         const subPrefix = parts[1] ?? "";
         const subs = [
@@ -293,6 +285,42 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
           .map((s) => ({ value: `knowledge ${s.cmd}`, label: s.cmd, description: s.desc }));
       }
 
+      if (parts[0] === "start" && parts.length <= 2) {
+        const subPrefix = parts[1] ?? "";
+        const subs = [
+          { cmd: "bugfix", desc: "Triage, fix, test, and ship a bug fix" },
+          { cmd: "small-feature", desc: "Lightweight feature with optional discussion" },
+          { cmd: "spike", desc: "Research, prototype, and document findings" },
+          { cmd: "hotfix", desc: "Minimal: fix it, test it, ship it" },
+          { cmd: "refactor", desc: "Inventory, plan waves, migrate, verify" },
+          { cmd: "security-audit", desc: "Scan, triage, remediate, re-scan" },
+          { cmd: "dep-upgrade", desc: "Assess, upgrade, fix breaks, verify" },
+          { cmd: "full-project", desc: "Complete GSD workflow with full ceremony" },
+          { cmd: "resume", desc: "Resume an in-progress workflow" },
+          { cmd: "--list", desc: "List all available templates" },
+          { cmd: "--dry-run", desc: "Preview workflow without executing" },
+        ];
+        return subs
+          .filter((s) => s.cmd.startsWith(subPrefix))
+          .map((s) => ({ value: `start ${s.cmd}`, label: s.cmd, description: s.desc }));
+      }
+
+      if (parts[0] === "templates" && parts.length <= 2) {
+        const subPrefix = parts[1] ?? "";
+        const subs = [
+          { cmd: "info", desc: "Show detailed template info" },
+        ];
+        return subs
+          .filter((s) => s.cmd.startsWith(subPrefix))
+          .map((s) => ({ value: `templates ${s.cmd}`, label: s.cmd, description: s.desc }));
+      }
+
+      if (parts[0] === "templates" && parts[1] === "info" && parts.length <= 3) {
+        const namePrefix = parts[2] ?? "";
+        return getTemplateCompletions(namePrefix)
+          .map((c) => ({ value: `templates ${c.value}`, label: c.label, description: c.description }));
+      }
+
       if (parts[0] === "doctor") {
         const modePrefix = parts[1] ?? "";
         const modes = [
@@ -392,6 +420,11 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         return;
       }
 
+      if (trimmed === "logs" || trimmed.startsWith("logs ")) {
+        await handleLogs(trimmed.replace(/^logs\s*/, "").trim(), ctx);
+        return;
+      }
+
       if (trimmed === "forensics" || trimmed.startsWith("forensics ")) {
         const { handleForensics } = await import("./forensics.js");
         await handleForensics(trimmed.replace(/^forensics\s*/, "").trim(), ctx, pi);
@@ -779,6 +812,17 @@ Examples:
         return;
       }
 
+      // ─── Workflow Templates ────────────────────────────────────────
+      if (trimmed === "start" || trimmed.startsWith("start ")) {
+        await handleStart(trimmed.replace(/^start\s*/, "").trim(), ctx, pi);
+        return;
+      }
+
+      if (trimmed === "templates" || trimmed.startsWith("templates ")) {
+        await handleTemplates(trimmed.replace(/^templates\s*/, "").trim(), ctx);
+        return;
+      }
+
       if (trimmed === "") {
         // Bare /gsd defaults to step mode
         await startAuto(ctx, pi, projectRoot(), false, { step: true });
@@ -797,6 +841,8 @@ function showHelp(ctx: ExtensionCommandContext): void {
   const lines = [
     "GSD — Get Shit Done\n",
     "WORKFLOW",
+    "  /gsd start <tpl>   Start a workflow template (bugfix, spike, feature, hotfix, etc.)",
+    "  /gsd templates     List available workflow templates  [info <name>]",
     "  /gsd               Run next unit in step mode (same as /gsd next)",
     "  /gsd next           Execute next task, then pause  [--dry-run] [--verbose]",
     "  /gsd auto           Run all queued units continuously  [--verbose]",
@@ -827,7 +873,7 @@ function showHelp(ctx: ExtensionCommandContext): void {
     "  /gsd init           Project init wizard — detect, configure, bootstrap .gsd/",
     "  /gsd setup          Global setup status  [llm|search|remote|keys|prefs]",
     "  /gsd mode           Set workflow mode (solo/team)  [global|project]",
-    "  /gsd prefs          Manage preferences  [global|project|status|wizard|setup]",
+    "  /gsd prefs          Manage preferences  [global|project|status|wizard|setup|import-claude]",
     "  /gsd config         Set API keys for external tools",
     "  /gsd keys           API key manager  [list|add|remove|test|rotate|doctor]",
     "  /gsd hooks          Show post-unit hook configuration",

package/src/resources/extensions/gsd/dashboard-overlay.ts

@@ -11,7 +11,8 @@ import { truncateToWidth, visibleWidth, matchesKey, Key } from "@gsd/pi-tui";
 import { deriveState } from "./state.js";
 import { loadFile, parseRoadmap, parsePlan } from "./files.js";
 import { resolveMilestoneFile, resolveSliceFile } from "./paths.js";
-import { getAutoDashboardData, type AutoDashboardData } from "./auto.js";
+import { getAutoDashboardData } from "./auto.js";
+import type { AutoDashboardData } from "./auto-dashboard.js";
 import {
   getLedger, getProjectTotals, aggregateByPhase, aggregateBySlice,
   aggregateByModel, aggregateCacheHitRate, formatCost, formatTokenCount, formatCostProjection,

package/src/resources/extensions/gsd/doctor-types.ts

@@ -32,6 +32,19 @@ export type DoctorIssueCode =
   | "gitignore_missing_patterns"
   | "unresolvable_dependency";
 
+/**
+ * Issue codes that represent expected completion-transition states.
+ * These are detected by the doctor but should NOT be auto-fixed at task level —
+ * they are resolved by the complete-slice/complete-milestone dispatch units.
+ * Consumers (e.g. auto-post-unit health tracking) should exclude these from
+ * error counts when running at task fixLevel to avoid false escalation.
+ */
+export const COMPLETION_TRANSITION_CODES = new Set<DoctorIssueCode>([
+  "all_tasks_done_missing_slice_summary",
+  "all_tasks_done_missing_slice_uat",
+  "all_tasks_done_roadmap_not_checked",
+]);
+
 export interface DoctorIssue {
   severity: DoctorSeverity;
   code: DoctorIssueCode;

package/src/resources/extensions/gsd/doctor.ts

@@ -8,6 +8,7 @@ import { invalidateAllCaches } from "./cache.js";
 import { loadEffectiveGSDPreferences, type GSDPreferences } from "./preferences.js";
 
 import type { DoctorIssue, DoctorIssueCode } from "./doctor-types.js";
+import { COMPLETION_TRANSITION_CODES } from "./doctor-types.js";
 import { checkGitHealth, checkRuntimeHealth } from "./doctor-checks.js";
 
 // ── Re-exports ─────────────────────────────────────────────────────────────
@@ -356,16 +357,11 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
   // dispatch lifecycle (complete-slice, complete-milestone units), not to
   // mechanical post-hook bookkeeping. When fixLevel is "task", these are
   // detected and reported but never auto-fixed.
-  const completionTransitionCodes = new Set<DoctorIssueCode>([
-    "all_tasks_done_missing_slice_summary",
-    "all_tasks_done_missing_slice_uat",
-    "all_tasks_done_roadmap_not_checked",
-  ]);
 
   /** Whether a given issue code should be auto-fixed at the current fixLevel. */
   const shouldFix = (code: DoctorIssueCode): boolean => {
     if (!fix) return false;
-    if (fixLevel === "task" && completionTransitionCodes.has(code)) return false;
+    if (fixLevel === "task" && COMPLETION_TRANSITION_CODES.has(code)) return false;
     return true;
   };
 

package/src/resources/extensions/gsd/export.ts

@@ -4,6 +4,7 @@
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
 import { writeFileSync, mkdirSync } from "node:fs";
 import { join, basename } from "node:path";
+import { exec } from "node:child_process";
 import {
   getLedger, getProjectTotals, aggregateByPhase, aggregateBySlice,
   aggregateByModel, formatCost, formatTokenCount, loadLedgerFromDisk,
@@ -12,6 +13,28 @@ import type { UnitMetrics } from "./metrics.js";
 import { gsdRoot } from "./paths.js";
 import { formatDuration, fileLink } from "../shared/mod.js";
 
+/**
+ * Open a file in the user's default browser.
+ * Uses platform-specific commands: `open` (macOS), `xdg-open` (Linux), `start` (Windows).
+ * Non-blocking, non-fatal — failures are silently ignored.
+ */
+export function openInBrowser(filePath: string): void {
+  const cmd =
+    process.platform === "darwin" ? "open" :
+    process.platform === "win32" ? "start" :
+    "xdg-open";
+
+  // On Windows, `start` needs an empty title argument when the path has spaces
+  const args = process.platform === "win32"
+    ? `"" "${filePath}"`
+    : `"${filePath}"`;
+
+  exec(`${cmd} ${args}`, (err) => {
+    // Non-fatal — if the browser can't be opened, the file path is still shown
+    if (err) void err;
+  });
+}
+
 /**
  * Write an export file directly, without requiring an ExtensionCommandContext.
  * Used by the visualizer overlay export tab.
@@ -167,10 +190,12 @@ export async function handleExport(args: string, ctx: ExtensionCommandContext, b
           paths.push(bn(outPath));
         }
 
+        const indexPath = join(gsdRoot(basePath), "reports", "index.html");
         ctx.ui.notify(
-          `Generated ${paths.length} report snapshot${paths.length !== 1 ? "s" : ""}:\n${paths.map(p => `  ${p}`).join("\n")}\nBrowse all reports: .gsd/reports/index.html`,
+          `Generated ${paths.length} report snapshot${paths.length !== 1 ? "s" : ""}:\n${paths.map(p => `  ${p}`).join("\n")}\nOpening reports index in browser...`,
           "success",
         );
+        openInBrowser(indexPath);
       } else {
         // Single report for the active milestone (existing behavior)
         const doneSlices = data.milestones.reduce((s, m) => s + m.slices.filter(sl => sl.done).length, 0);
@@ -194,9 +219,10 @@ export async function handleExport(args: string, ctx: ExtensionCommandContext, b
           phase: data.phase,
         });
         ctx.ui.notify(
-          `HTML report saved: .gsd/reports/${bn(outPath)}\nBrowse all reports: .gsd/reports/index.html`,
+          `HTML report saved: .gsd/reports/${bn(outPath)}\nOpening in browser...`,
           "success",
         );
+        openInBrowser(outPath);
       }
     } catch (err) {
       ctx.ui.notify(

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

@@ -348,6 +348,8 @@ function migrateSchema(db: DbAdapter): void {
 
 let currentDb: DbAdapter | null = null;
 let currentPath: string | null = null;
+/** PID that opened the current connection — used for diagnostic logging. */
+let currentPid: number = 0;
 
 // ─── Public API ────────────────────────────────────────────────────────────
 
@@ -395,6 +397,7 @@ export function openDatabase(path: string): boolean {
 
   currentDb = adapter;
   currentPath = path;
+  currentPid = process.pid;
   return true;
 }
 
@@ -410,6 +413,7 @@ export function closeDatabase(): void {
     }
     currentDb = null;
     currentPath = null;
+    currentPid = 0;
   }
 }
 
@@ -724,6 +728,21 @@ export function reconcileWorktreeDb(
   }
 }
 
+/**
+ * Returns the PID of the process that opened the current DB connection.
+ * Returns 0 if no connection is open.
+ */
+export function getDbOwnerPid(): number {
+  return currentPid;
+}
+
+/**
+ * Returns the path of the currently open database, or null if none.
+ */
+export function getDbPath(): string | null {
+  return currentPath;
+}
+
 // ─── Internal Access (for testing) ─────────────────────────────────────────
 
 /**

package/src/resources/extensions/gsd/index.ts

@@ -27,7 +27,8 @@ import { createBashTool, createWriteTool, createReadTool, createEditTool, isTool
 import { Type } from "@sinclair/typebox";
 
 import { debugLog, debugTime } from "./debug-logger.js";
-import { registerGSDCommand, loadToolApiKeys } from "./commands.js";
+import { registerGSDCommand } from "./commands.js";
+import { loadToolApiKeys } from "./commands-config.js";
 import { registerExitCommand } from "./exit-command.js";
 import { registerWorktreeCommand, getWorktreeOriginalCwd, getActiveWorktreeName } from "./worktree-command.js";
 import { getActiveAutoWorktreeContext } from "./auto-worktree.js";

package/src/resources/extensions/gsd/json-persistence.ts

@@ -0,0 +1,67 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { dirname } from "node:path";
+
+/**
+ * Load a JSON file with validation, returning a default on failure.
+ * Handles missing files, corrupt JSON, and schema mismatches uniformly.
+ */
+export function loadJsonFile<T>(
+  filePath: string,
+  validate: (data: unknown) => data is T,
+  defaultFactory: () => T,
+): T {
+  try {
+    if (!existsSync(filePath)) return defaultFactory();
+    const raw = readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    return validate(parsed) ? parsed : defaultFactory();
+  } catch {
+    return defaultFactory();
+  }
+}
+
+/**
+ * Load a JSON file with validation, returning null on failure.
+ * For callers that distinguish "no data" from "default data".
+ */
+export function loadJsonFileOrNull<T>(
+  filePath: string,
+  validate: (data: unknown) => data is T,
+): T | null {
+  try {
+    if (!existsSync(filePath)) return null;
+    const raw = readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    return validate(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save a JSON file, creating parent directories as needed.
+ * Non-fatal — swallows errors to prevent persistence from breaking operations.
+ */
+export function saveJsonFile<T>(filePath: string, data: T): void {
+  try {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n", "utf-8");
+  } catch {
+    // Non-fatal — don't let persistence failures break operation
+  }
+}
+
+/**
+ * Write a JSON file atomically (write to .tmp, then rename).
+ * Creates parent directories as needed. Non-fatal on error.
+ */
+export function writeJsonFileAtomic<T>(filePath: string, data: T): void {
+  try {
+    mkdirSync(dirname(filePath), { recursive: true });
+    const tmp = filePath + ".tmp";
+    writeFileSync(tmp, JSON.stringify(data, null, 2), "utf-8");
+    renameSync(tmp, filePath);
+  } catch {
+    // Non-fatal — don't let persistence failures break operation
+  }
+}

package/src/resources/extensions/gsd/metrics.ts

@@ -13,11 +13,11 @@
  *   4. On crash recovery or fresh start, the ledger is loaded from disk
  */
 
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import type { ExtensionContext } from "@gsd/pi-coding-agent";
 import { gsdRoot } from "./paths.js";
 import { getAndClearSkills } from "./skill-telemetry.js";
+import { loadJsonFile, loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
 
 // Re-export from shared — canonical implementation lives in format-utils.
 export { formatTokenCount } from "../shared/mod.js";
@@ -502,45 +502,31 @@ function metricsPath(base: string): string {
   return join(gsdRoot(base), "metrics.json");
 }
 
+function isMetricsLedger(data: unknown): data is MetricsLedger {
+  return (
+    typeof data === "object" &&
+    data !== null &&
+    (data as MetricsLedger).version === 1 &&
+    Array.isArray((data as MetricsLedger).units)
+  );
+}
+
+function defaultLedger(): MetricsLedger {
+  return { version: 1, projectStartedAt: Date.now(), units: [] };
+}
+
 /**
  * Load ledger from disk without initializing in-memory state.
  * Used by history/export commands outside of auto-mode.
  */
 export function loadLedgerFromDisk(base: string): MetricsLedger | null {
-  try {
-    const raw = readFileSync(metricsPath(base), "utf-8");
-    const parsed = JSON.parse(raw);
-    if (parsed.version === 1 && Array.isArray(parsed.units)) {
-      return parsed as MetricsLedger;
-    }
-  } catch {
-    // File doesn't exist or is corrupt
-  }
-  return null;
+  return loadJsonFileOrNull(metricsPath(base), isMetricsLedger);
 }
 
 function loadLedger(base: string): MetricsLedger {
-  try {
-    const raw = readFileSync(metricsPath(base), "utf-8");
-    const parsed = JSON.parse(raw);
-    if (parsed.version === 1 && Array.isArray(parsed.units)) {
-      return parsed as MetricsLedger;
-    }
-  } catch {
-    // File doesn't exist or is corrupt — start fresh
-  }
-  return {
-    version: 1,
-    projectStartedAt: Date.now(),
-    units: [],
-  };
+  return loadJsonFile(metricsPath(base), isMetricsLedger, defaultLedger);
 }
 
 function saveLedger(base: string, data: MetricsLedger): void {
-  try {
-    mkdirSync(gsdRoot(base), { recursive: true });
-    writeFileSync(metricsPath(base), JSON.stringify(data, null, 2) + "\n", "utf-8");
-  } catch {
-    // Don't let metrics failures break auto-mode
-  }
+  saveJsonFile(metricsPath(base), data);
 }

package/src/resources/extensions/gsd/paths.ts

@@ -137,14 +137,6 @@ export function clearPathCache(): void {
 
 // ─── Name Builders ─────────────────────────────────────────────────────────
 
-/**
- * Build a directory name from an ID.
- * ("M001") → "M001"
- */
-export function buildDirName(id: string): string {
-  return id;
-}
-
 /**
  * Build a milestone-level file name.
  * ("M001", "CONTEXT") → "M001-CONTEXT.md"

package/src/resources/extensions/gsd/prompts/guided-discuss-milestone.md

@@ -91,7 +91,7 @@ Before moving to the wrap-up gate, verify you have covered:
 - options: "Yes, you got it (Recommended)", "Not quite — let me clarify"
 - **The question ID must contain `depth_verification`** (e.g. `depth_verification_confirm`) — this enables the write-gate downstream.
 
-**If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text: "Did I capture that correctly? Anything I missed?" Wait for confirmation before proceeding.
+**If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text: "Did I capture that correctly? If not, tell me what I missed." Wait for confirmation before proceeding.
 
 If they clarify, absorb the correction and re-verify.
 

package/src/resources/extensions/gsd/prompts/workflow-start.md

@@ -0,0 +1,28 @@
+# Workflow Template: {{templateName}}
+
+You are executing a **{{templateName}}** workflow (template: `{{templateId}}`).
+
+## Context
+
+- **Description:** {{description}}
+- **Issue reference:** {{issueRef}}
+- **Date:** {{date}}
+- **Branch:** {{branch}}
+- **Artifact directory:** {{artifactDir}}
+- **Phases:** {{phases}}
+- **Complexity:** {{complexity}}
+
+## Workflow Definition
+
+Follow the workflow defined below. Execute each phase in order, completing one before moving to the next. At each phase gate, confirm with the user before proceeding.
+
+{{workflowContent}}
+
+## Execution Rules
+
+1. **Follow the phases in order.** Do not skip phases unless the workflow explicitly allows it.
+2. **Artifact discipline.** If an artifact directory is specified, write all planning/summary documents there.
+3. **Atomic commits.** Commit working code after each meaningful change. Use conventional commit format: `<type>(<scope>): <description>`.
+4. **Verify before shipping.** Run the project's test suite and build before marking the workflow complete.
+5. **Gate between phases.** After each phase, summarize what was done and ask the user to confirm before moving to the next phase.
+6. **Stay focused.** This is a {{complexity}}-complexity workflow. Match your ceremony level to the task — don't over-engineer or under-deliver.

package/src/resources/extensions/gsd/queue-order.ts

@@ -9,10 +9,10 @@
  * survives branch switches and is shared across sessions.
  */
 
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { milestoneIdSort } from "./milestone-ids.js";
+import { loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -45,6 +45,12 @@ function queueOrderPath(basePath: string): string {
   return join(gsdRoot(basePath), "QUEUE-ORDER.json");
 }
 
+// ─── Type Guards ─────────────────────────────────────────────────────────────
+
+function isQueueOrderFile(data: unknown): data is QueueOrderFile {
+  return data !== null && typeof data === "object" && "order" in data! && Array.isArray((data as QueueOrderFile).order);
+}
+
 // ─── Read / Write ────────────────────────────────────────────────────────────
 
 /**
@@ -52,15 +58,8 @@ function queueOrderPath(basePath: string): string {
  * the file is corrupt/unreadable.
  */
 export function loadQueueOrder(basePath: string): string[] | null {
-  const p = queueOrderPath(basePath);
-  if (!existsSync(p)) return null;
-  try {
-    const data: QueueOrderFile = JSON.parse(readFileSync(p, "utf-8"));
-    if (!Array.isArray(data.order)) return null;
-    return data.order;
-  } catch {
-    return null;
-  }
+  const data = loadJsonFileOrNull(queueOrderPath(basePath), isQueueOrderFile);
+  return data?.order ?? null;
 }
 
 /**
@@ -71,7 +70,7 @@ export function saveQueueOrder(basePath: string, order: string[]): void {
     order,
     updatedAt: new Date().toISOString(),
   };
-  writeFileSync(queueOrderPath(basePath), JSON.stringify(data, null, 2) + "\n", "utf-8");
+  saveJsonFile(queueOrderPath(basePath), data);
 }
 
 // ─── Sorting ─────────────────────────────────────────────────────────────────

package/src/resources/extensions/gsd/routing-history.ts

@@ -2,10 +2,10 @@
 // Tracks success/failure per tier per unit-type pattern to improve
 // classification accuracy over time.
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import type { ComplexityTier } from "./types.js";
+import { loadJsonFile, saveJsonFile } from "./json-persistence.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -267,24 +267,20 @@ function historyPath(base: string): string {
   return join(gsdRoot(base), HISTORY_FILE);
 }
 
+function isRoutingHistoryData(data: unknown): data is RoutingHistoryData {
+  return (
+    typeof data === "object" &&
+    data !== null &&
+    (data as RoutingHistoryData).version === 1 &&
+    typeof (data as RoutingHistoryData).patterns === "object" &&
+    (data as RoutingHistoryData).patterns !== null
+  );
+}
+
 function loadHistory(base: string): RoutingHistoryData {
-  try {
-    const raw = readFileSync(historyPath(base), "utf-8");
-    const parsed = JSON.parse(raw);
-    if (parsed.version === 1 && parsed.patterns) {
-      return parsed as RoutingHistoryData;
-    }
-  } catch {
-    // File doesn't exist or is corrupt — start fresh
-  }
-  return createEmptyHistory();
+  return loadJsonFile(historyPath(base), isRoutingHistoryData, createEmptyHistory);
 }
 
 function saveHistory(base: string, data: RoutingHistoryData): void {
-  try {
-    mkdirSync(gsdRoot(base), { recursive: true });
-    writeFileSync(historyPath(base), JSON.stringify(data, null, 2) + "\n", "utf-8");
-  } catch {
-    // Non-fatal — don't let history failures break auto-mode
-  }
+  saveJsonFile(historyPath(base), data);
 }