gsd-pi 2.28.0 → 2.29.0-dev.7612840

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

@@ -13,11 +13,14 @@
  *   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";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -40,6 +43,7 @@ export interface UnitMetrics {
   toolCalls: number;
   assistantMessages: number;
   userMessages: number;
+  apiRequests?: number;    // total API requests made (useful for copilot users where cost is always 0)
   // Budget fields (optional — absent in pre-M009 metrics data)
   contextWindowTokens?: number;
   truncationSections?: number;
@@ -49,6 +53,8 @@ export interface UnitMetrics {
   tier?: string;           // complexity tier (light/standard/heavy) if dynamic routing active
   modelDowngraded?: boolean; // true if dynamic routing used a cheaper model
   skills?: string[];       // skill names available/loaded during this unit (#599)
+  cacheHitRate?: number;       // percentage 0-100, computed from cacheRead/(cacheRead+input)
+  compressionSavings?: number; // percentage 0-100, char savings from prompt compression
 }
 
 /** Budget state passed to snapshotUnitMetrics for persistence in the metrics ledger. */
@@ -174,6 +180,7 @@ export function snapshotUnitMetrics(
     toolCalls,
     assistantMessages,
     userMessages,
+    apiRequests: assistantMessages, // each assistant message = one API request
     ...(opts?.tier ? { tier: opts.tier } : {}),
     ...(opts?.modelDowngraded !== undefined ? { modelDowngraded: opts.modelDowngraded } : {}),
     ...(opts?.contextWindowTokens !== undefined ? { contextWindowTokens: opts.contextWindowTokens } : {}),
@@ -189,6 +196,12 @@ export function snapshotUnitMetrics(
     unit.skills = skills;
   }
 
+  // Compute cache hit rate
+  if (tokens.cacheRead > 0 || tokens.input > 0) {
+    const totalInput = tokens.cacheRead + tokens.input;
+    unit.cacheHitRate = totalInput > 0 ? Math.round((tokens.cacheRead / totalInput) * 100) : 0;
+  }
+
   ledger.units.push(unit);
   saveLedger(basePath, ledger);
 
@@ -236,6 +249,7 @@ export interface ProjectTotals {
   toolCalls: number;
   assistantMessages: number;
   userMessages: number;
+  apiRequests: number;
   totalTruncationSections: number;
   continueHereFiredCount: number;
 }
@@ -319,6 +333,7 @@ export function getProjectTotals(units: UnitMetrics[]): ProjectTotals {
     toolCalls: 0,
     assistantMessages: 0,
     userMessages: 0,
+    apiRequests: 0,
     totalTruncationSections: 0,
     continueHereFiredCount: 0,
   };
@@ -329,6 +344,7 @@ export function getProjectTotals(units: UnitMetrics[]): ProjectTotals {
     totals.toolCalls += u.toolCalls;
     totals.assistantMessages += u.assistantMessages;
     totals.userMessages += u.userMessages;
+    totals.apiRequests += u.apiRequests ?? u.assistantMessages; // fallback for pre-existing data
     totals.totalTruncationSections += u.truncationSections ?? 0;
     if (u.continueHereFired) totals.continueHereFiredCount++;
   }
@@ -378,6 +394,22 @@ export function formatTierSavings(units: UnitMetrics[]): string {
   return `Dynamic routing: ${downgraded.length}/${totalUnits} units downgraded (${pct}%), cost: ${formatCost(downgradedCost)}`;
 }
 
+/**
+ * Compute aggregate cache hit rate across all units.
+ * Returns percentage 0-100.
+ */
+export function aggregateCacheHitRate(): number {
+  if (!ledger || ledger.units.length === 0) return 0;
+  let totalInput = 0;
+  let totalCacheRead = 0;
+  for (const unit of ledger.units) {
+    totalInput += unit.tokens.input;
+    totalCacheRead += unit.tokens.cacheRead;
+  }
+  const total = totalInput + totalCacheRead;
+  return total > 0 ? Math.round((totalCacheRead / total) * 100) : 0;
+}
+
 // ─── Formatting helpers ───────────────────────────────────────────────────────
 
 export function formatCost(cost: number): string {
@@ -463,11 +495,6 @@ export function formatCostProjection(
   return result;
 }
 
-export function formatTokenCount(count: number): string {
-  if (count < 1000) return `${count}`;
-  if (count < 1_000_000) return `${(count / 1000).toFixed(1)}k`;
-  return `${(count / 1_000_000).toFixed(2)}M`;
-}
 
 // ─── Disk I/O ─────────────────────────────────────────────────────────────────
 
@@ -475,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/migrate/command.ts

@@ -13,7 +13,7 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent
 import { existsSync, readFileSync } from "node:fs";
 import { resolve, join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { showNextAction } from "../../shared/next-action-ui.js";
+import { showNextAction } from "../../shared/mod.js";
 import {
   validatePlanningDirectory,
   parsePlanningDirectory,

package/src/resources/extensions/gsd/migrate/parsers.ts

@@ -3,6 +3,7 @@
 // Zero Pi dependencies — uses only exported helpers from files.ts.
 
 import { splitFrontmatter, parseFrontmatterMap, extractBoldField } from '../files.js';
+import { normalizeStringArray } from '../../shared/mod.js';
 
 import type {
   PlanningRoadmap,
@@ -366,107 +367,21 @@ function parseRequiresArray(raw: unknown): PlanningSummaryRequires[] {
   });
 }
 
-function toStringArray(val: unknown): string[] {
-  if (Array.isArray(val)) return val.map(String);
-  return [];
-}
-
-/**
- * Parse YAML-like frontmatter lines into a flat key-value map.
- * Like parseFrontmatterMap but supports hyphenated keys (e.g. `tech-stack:`).
- */
-function parseFrontmatterMapHyphen(lines: string[]): Record<string, unknown> {
-  const result: Record<string, unknown> = {};
-  let currentKey: string | null = null;
-  let currentArray: unknown[] | null = null;
-  let currentObj: Record<string, string> | null = null;
-
-  for (const line of lines) {
-    // Nested object property (4-space indent with key: value)
-    const nestedMatch = line.match(/^    ([\w][\w_-]*)\s*:\s*(.*)$/);
-    if (nestedMatch && currentArray && currentObj) {
-      currentObj[nestedMatch[1]] = nestedMatch[2].trim();
-      continue;
-    }
-
-    // Array item (2-space indent)
-    const arrayMatch = line.match(/^  - (.*)$/);
-    if (arrayMatch && currentKey) {
-      if (currentObj && Object.keys(currentObj).length > 0) {
-        currentArray!.push(currentObj);
-      }
-      currentObj = null;
-
-      const val = arrayMatch[1].trim();
-      if (!currentArray) currentArray = [];
-
-      const nestedStart = val.match(/^([\w][\w_-]*)\s*:\s*(.*)$/);
-      if (nestedStart) {
-        currentObj = { [nestedStart[1]]: nestedStart[2].trim() };
-      } else {
-        currentArray.push(val);
-      }
-      continue;
-    }
-
-    // Flush previous key
-    if (currentKey) {
-      if (currentObj && Object.keys(currentObj).length > 0 && currentArray) {
-        currentArray.push(currentObj);
-        currentObj = null;
-      }
-      if (currentArray) {
-        result[currentKey] = currentArray;
-      }
-      currentArray = null;
-    }
-
-    // Top-level key: value (supports hyphens in key names)
-    const kvMatch = line.match(/^([\w][\w_-]*)\s*:\s*(.*)$/);
-    if (kvMatch) {
-      currentKey = kvMatch[1];
-      const val = kvMatch[2].trim();
-
-      if (val === '' || val === '[]') {
-        currentArray = [];
-      } else if (val.startsWith('[') && val.endsWith(']')) {
-        const inner = val.slice(1, -1).trim();
-        result[currentKey] = inner ? inner.split(',').map(s => s.trim()) : [];
-        currentKey = null;
-      } else {
-        result[currentKey] = val;
-        currentKey = null;
-      }
-    }
-  }
-
-  // Flush final key
-  if (currentKey) {
-    if (currentObj && Object.keys(currentObj).length > 0 && currentArray) {
-      currentArray.push(currentObj);
-      currentObj = null;
-    }
-    if (currentArray) {
-      result[currentKey] = currentArray;
-    }
-  }
-
-  return result;
-}
+// parseFrontmatterMap from shared now supports hyphenated keys natively
 
 function parseSummaryFrontmatter(fm: Record<string, unknown>): PlanningSummaryFrontmatter {
   return {
     phase: unquote(fm.phase),
     plan: unquote(fm.plan),
     subsystem: unquote(fm.subsystem),
-    tags: toStringArray(fm.tags),
+    tags: normalizeStringArray(fm.tags),
     requires: parseRequiresArray(fm.requires),
-    provides: toStringArray(fm.provides),
-    affects: toStringArray(fm.affects),
-    'tech-stack': toStringArray(fm['tech-stack']),
-    'key-files': toStringArray(fm['key-files']),
-    'key-decisions': toStringArray(fm['key-decisions']),
-    'patterns-established': toStringArray(fm['patterns-established']),
+    provides: normalizeStringArray(fm.provides),
+    affects: normalizeStringArray(fm.affects),
+    'tech-stack': normalizeStringArray(fm['tech-stack']),
+    'key-files': normalizeStringArray(fm['key-files']),
+    'key-decisions': normalizeStringArray(fm['key-decisions']),
+    'patterns-established': normalizeStringArray(fm['patterns-established']),
     duration: unquote(fm.duration),
     completed: unquote(fm.completed),
   };
@@ -477,7 +392,7 @@ function parseSummaryFrontmatter(fm: Record<string, unknown>): PlanningSummaryFr
  */
 export function parseOldSummary(content: string, fileName: string = '', planNumber: string = ''): PlanningSummary {
   const [fmLines, body] = splitFrontmatter(content);
-  const fm = fmLines ? parseFrontmatterMapHyphen(fmLines) : {};
+  const fm = fmLines ? parseFrontmatterMap(fmLines) : {};
 
   return {
     fileName,

package/src/resources/extensions/gsd/milestone-actions.ts

@@ -0,0 +1,126 @@
+/**
+ * GSD Milestone Actions — Park, Unpark, and Discard operations.
+ *
+ * Park: Creates a PARKED.md marker file. deriveState() skips parked milestones
+ * when finding the active milestone, but keeps them in the registry.
+ *
+ * Unpark: Removes the PARKED.md marker. The milestone resumes normal state
+ * derivation (active/pending depending on position and dependencies).
+ *
+ * Discard: Permanently removes the milestone directory. Also prunes
+ * QUEUE-ORDER.json if the discarded milestone was in it.
+ */
+
+import { existsSync, rmSync, writeFileSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import {
+  resolveMilestonePath,
+  resolveMilestoneFile,
+  buildMilestoneFileName,
+} from "./paths.js";
+import { invalidateAllCaches } from "./cache.js";
+import { loadQueueOrder, saveQueueOrder } from "./queue-order.js";
+
+// ─── Park ──────────────────────────────────────────────────────────────────
+
+/**
+ * Park a milestone — creates a PARKED.md marker file with reason and timestamp.
+ * Parked milestones are skipped during active-milestone discovery but stay on disk.
+ * Returns true if successfully parked, false if milestone not found or already parked.
+ */
+export function parkMilestone(basePath: string, milestoneId: string, reason: string): boolean {
+  const mDir = resolveMilestonePath(basePath, milestoneId);
+  if (!mDir || !existsSync(mDir)) return false;
+
+  // Guard: do not park a completed milestone — it would corrupt depends_on satisfaction
+  const summaryFile = resolveMilestoneFile(basePath, milestoneId, "SUMMARY");
+  if (summaryFile) return false;
+
+  const parkedPath = join(mDir, buildMilestoneFileName(milestoneId, "PARKED"));
+  if (existsSync(parkedPath)) return false; // already parked
+
+  const content = [
+    "---",
+    `parked_at: ${new Date().toISOString()}`,
+    `reason: "${reason.replace(/"/g, '\\"')}"`,
+    "---",
+    "",
+    `# ${milestoneId} — Parked`,
+    "",
+    `> ${reason}`,
+    "",
+  ].join("\n");
+
+  writeFileSync(parkedPath, content, "utf-8");
+  invalidateAllCaches();
+  return true;
+}
+
+// ─── Unpark ────────────────────────────────────────────────────────────────
+
+/**
+ * Unpark a milestone — removes the PARKED.md marker file.
+ * Returns true if successfully unparked, false if milestone not found or not parked.
+ */
+export function unparkMilestone(basePath: string, milestoneId: string): boolean {
+  const mDir = resolveMilestonePath(basePath, milestoneId);
+  if (!mDir || !existsSync(mDir)) return false;
+
+  const parkedPath = join(mDir, buildMilestoneFileName(milestoneId, "PARKED"));
+  if (!existsSync(parkedPath)) return false; // not parked
+
+  unlinkSync(parkedPath);
+  invalidateAllCaches();
+  return true;
+}
+
+// ─── Discard ───────────────────────────────────────────────────────────────
+
+/**
+ * Discard a milestone — permanently removes the milestone directory and
+ * prunes it from QUEUE-ORDER.json if present.
+ * Returns true if successfully discarded, false if milestone not found.
+ */
+export function discardMilestone(basePath: string, milestoneId: string): boolean {
+  const mDir = resolveMilestonePath(basePath, milestoneId);
+  if (!mDir || !existsSync(mDir)) return false;
+
+  rmSync(mDir, { recursive: true, force: true });
+
+  // Prune from queue order if present
+  const order = loadQueueOrder(basePath);
+  if (order && order.includes(milestoneId)) {
+    saveQueueOrder(basePath, order.filter(id => id !== milestoneId));
+  }
+
+  invalidateAllCaches();
+  return true;
+}
+
+// ─── Query ─────────────────────────────────────────────────────────────────
+
+/**
+ * Check whether a milestone is parked (PARKED.md exists).
+ */
+export function isParked(basePath: string, milestoneId: string): boolean {
+  return !!resolveMilestoneFile(basePath, milestoneId, "PARKED");
+}
+
+/**
+ * Read the park reason from PARKED.md frontmatter.
+ * Returns null if the milestone is not parked or the reason can't be extracted.
+ */
+export function getParkedReason(basePath: string, milestoneId: string): string | null {
+  const parkedFile = resolveMilestoneFile(basePath, milestoneId, "PARKED");
+  if (!parkedFile) return null;
+
+  try {
+    const content = readFileSync(parkedFile, "utf-8");
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) return null;
+    const reasonMatch = match[1].match(/reason:\s*"([^"]*?)"/);
+    return reasonMatch ? reasonMatch[1] : null;
+  } catch {
+    return null;
+  }
+}

package/src/resources/extensions/gsd/milestone-ids.ts

@@ -0,0 +1,95 @@
+/**
+ * Milestone ID primitives — pure utilities for generating, parsing, sorting,
+ * and discovering milestone identifiers.
+ *
+ * Consumed by 15+ modules across the GSD extension. Zero side-effects.
+ */
+
+import { randomInt } from "node:crypto";
+import { readdirSync, existsSync } from "node:fs";
+import { milestonesDir } from "./paths.js";
+import { loadQueueOrder, sortByQueueOrder } from "./queue-order.js";
+
+// ─── Regex ──────────────────────────────────────────────────────────────────
+
+/** Matches both classic `M001` and unique `M001-abc123` formats (anchored). */
+export const MILESTONE_ID_RE = /^M\d{3}(?:-[a-z0-9]{6})?$/;
+
+// ─── Parsing & Extraction ───────────────────────────────────────────────────
+
+/** Extract the trailing sequential number from a milestone ID. Returns 0 for non-matches. */
+export function extractMilestoneSeq(id: string): number {
+  const m = id.match(/^M(\d{3})(?:-[a-z0-9]{6})?$/);
+  return m ? parseInt(m[1], 10) : 0;
+}
+
+/** Structured parse of a milestone ID into optional suffix and sequence number. */
+export function parseMilestoneId(id: string): { suffix?: string; num: number } {
+  const m = id.match(/^M(\d{3})(?:-([a-z0-9]{6}))?$/);
+  if (!m) return { num: 0 };
+  return {
+    ...(m[2] ? { suffix: m[2] } : {}),
+    num: parseInt(m[1], 10),
+  };
+}
+
+// ─── Sorting ────────────────────────────────────────────────────────────────
+
+/** Comparator for sorting milestone IDs by sequential number. */
+export function milestoneIdSort(a: string, b: string): number {
+  return extractMilestoneSeq(a) - extractMilestoneSeq(b);
+}
+
+// ─── Generation ─────────────────────────────────────────────────────────────
+
+/** Generate a 6-char lowercase `[a-z0-9]` suffix using crypto.randomInt(). */
+export function generateMilestoneSuffix(): string {
+  const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+  let result = "";
+  for (let i = 0; i < 6; i++) {
+    result += chars[randomInt(36)];
+  }
+  return result;
+}
+
+/** Return the highest numeric suffix among milestone IDs (0 when the list is empty or has no numeric IDs). */
+export function maxMilestoneNum(milestoneIds: string[]): number {
+  return milestoneIds.reduce((max, id) => {
+    const num = extractMilestoneSeq(id);
+    return num > max ? num : max;
+  }, 0);
+}
+
+/** Derive the next milestone ID from existing IDs using max-based approach to avoid collisions after deletions. */
+export function nextMilestoneId(milestoneIds: string[], uniqueEnabled?: boolean): string {
+  const seq = String(maxMilestoneNum(milestoneIds) + 1).padStart(3, "0");
+  if (uniqueEnabled) {
+    return `M${seq}-${generateMilestoneSuffix()}`;
+  }
+  return `M${seq}`;
+}
+
+// ─── Discovery ──────────────────────────────────────────────────────────────
+
+/** Scan the milestones directory and return IDs sorted by queue order (or numeric fallback). */
+export function findMilestoneIds(basePath: string): string[] {
+  const dir = milestonesDir(basePath);
+  try {
+    const ids = readdirSync(dir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => {
+        const match = d.name.match(/^(M\d+(?:-[a-z0-9]{6})?)/);
+        return match ? match[1] : d.name;
+      });
+
+    // Apply custom queue order if available, else fall back to numeric sort
+    const customOrder = loadQueueOrder(basePath);
+    return sortByQueueOrder(ids, customOrder);
+  } catch (err) {
+    // Log why milestone scanning failed — silent [] here causes infinite loops (#456)
+    if (existsSync(dir)) {
+      console.error(`[gsd] findMilestoneIds: .gsd/milestones/ exists but readdirSync failed — ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return [];
+  }
+}

package/src/resources/extensions/gsd/native-git-bridge.ts

@@ -8,14 +8,8 @@
 import { execSync, execFileSync } from "node:child_process";
 import { existsSync, readFileSync, unlinkSync, rmSync } from "node:fs";
 import { join } from "node:path";
-
-/** Env overlay that suppresses interactive git credential prompts and git-svn noise. */
-const GIT_NO_PROMPT_ENV = {
-  ...process.env,
-  GIT_TERMINAL_PROMPT: "0",
-  GIT_ASKPASS: "",
-  GIT_SVN_ID: "",
-};
+import { GSDError, GSD_GIT_ERROR } from "./errors.js";
+import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 
 // Issue #453: keep auto-mode bookkeeping on the stable git CLI path unless a
 // caller explicitly opts into the native helper.
@@ -148,7 +142,7 @@ function gitExec(basePath: string, args: string[], allowFailure = false): string
     }).trim();
   } catch {
     if (allowFailure) return "";
-    throw new Error(`git ${args.join(" ")} failed in ${basePath}`);
+    throw new GSDError(GSD_GIT_ERROR, `git ${args.join(" ")} failed in ${basePath}`);
   }
 }
 
@@ -159,10 +153,11 @@ function gitFileExec(basePath: string, args: string[], allowFailure = false): st
       cwd: basePath,
       stdio: ["ignore", "pipe", "pipe"],
       encoding: "utf-8",
+      env: GIT_NO_PROMPT_ENV,
     }).trim();
   } catch {
     if (allowFailure) return "";
-    throw new Error(`git ${args.join(" ")} failed in ${basePath}`);
+    throw new GSDError(GSD_GIT_ERROR, `git ${args.join(" ")} failed in ${basePath}`);
   }
 }
 

package/src/resources/extensions/gsd/parallel-eligibility.ts

@@ -118,13 +118,13 @@ export async function analyzeParallelEligibility(
     const title = entry?.title ?? mid;
     const status = entry?.status ?? "pending";
 
-    // Rule 1: skip complete milestones
-    if (status === "complete") {
+    // Rule 1: skip complete and parked milestones
+    if (status === "complete" || status === "parked") {
       ineligible.push({
         milestoneId: mid,
         title,
         eligible: false,
-        reason: "Already complete.",
+        reason: status === "parked" ? "Milestone is parked." : "Already complete.",
       });
       continue;
     }

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

@@ -12,12 +12,10 @@
 import { readdirSync, existsSync, Dirent } from "node:fs";
 import { join } from "node:path";
 import { nativeScanGsdTree, type GsdTreeEntry } from "./native-parser-bridge.js";
+import { DIR_CACHE_MAX } from "./constants.js";
 
 // ─── Directory Listing Cache ──────────────────────────────────────────────────
 
-/** Max entries before eviction. Prevents unbounded growth in long sessions (#611). */
-const DIR_CACHE_MAX = 200;
-
 const dirEntryCache = new Map<string, Dirent[]>();
 const dirListCache = new Map<string, string[]>();
 
@@ -139,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/plugin-importer.ts

@@ -19,6 +19,7 @@ import {
 	type MarketplaceDiscoveryResult,
 	type DiscoveredPlugin,
 } from './marketplace-discovery.js';
+import { GSDError, GSD_STALE_STATE } from './errors.js';
 import {
 	NamespacedRegistry,
 	componentsFromDiscovery,
@@ -252,7 +253,7 @@ export class PluginImporter {
 		componentFilter: (component: NamespacedComponent) => boolean
 	): NamespacedComponent[] {
 		if (!this.registry) {
-			throw new Error('Must call discover() before selectComponents()');
+			throw new GSDError(GSD_STALE_STATE, 'Must call discover() before selectComponents()');
 		}
 
 		return this.registry.getAll().filter(componentFilter);
@@ -270,7 +271,7 @@ export class PluginImporter {
 	 */
 	validateImport(selected: NamespacedComponent[]): ValidationResult {
 		if (!this.registry) {
-			throw new Error('Must call discover() before validateImport()');
+			throw new GSDError(GSD_STALE_STATE, 'Must call discover() before validateImport()');
 		}
 
 		// Create a temporary resolver for the selected components