@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.72e3af2a

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

@@ -10,7 +10,7 @@
  * statements continue to work without modification.
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
@@ -20,7 +20,12 @@ import type { PostUnitHookConfig, PreDispatchHookConfig, TokenProfile } from "./
 import type { DynamicRoutingConfig } from "./model-router.js";
 import { normalizeStringArray } from "../shared/format-utils.js";
 import { logWarning } from "./workflow-logger.js";
-import { resolveProfileDefaults as _resolveProfileDefaults } from "./preferences-models.js";
+import {
+  DEFAULT_TOKEN_PROFILE,
+  resolveProfileDefaults as _resolveProfileDefaults,
+  VALID_TOKEN_PROFILES,
+  resolveDisabledModelProvidersFromPreferences,
+} from "./preferences-models.js";
 import { nativeHasCommittedHead, nativeIsRepo } from "./native-git-bridge.js";
 
 import {
@@ -29,6 +34,7 @@ import {
   type WorkflowMode,
   type GSDPreferences,
   type LoadedGSDPreferences,
+  type PreferenceDiagnostic,
   type SkillResolution,
   type SkillDiscoveryMode,
   formatSkillRef,
@@ -59,6 +65,7 @@ export type {
   ClaudeCodeMcpConfig,
   GSDPreferences,
   LoadedGSDPreferences,
+  PreferenceDiagnostic,
   SkillResolution,
   SkillResolutionReport,
 } from "./preferences-types.js";
@@ -140,6 +147,94 @@ export function getProjectGSDPreferencesPath(basePath?: string): string {
   return projectPreferencesPath(basePath);
 }
 
+/** Minimal model-registry surface for provider-aware preference resolution. */
+export type PreferencesModelRegistry = {
+  getAvailable: () => ReadonlyArray<{ provider: string; id: string }>;
+};
+
+/** Format registry models the same way tier resolution and prefs persistence use. */
+export function availableModelIdsFromRegistry(registry: PreferencesModelRegistry): string[] {
+  return registry.getAvailable().map((m) => `${m.provider}/${m.id}`);
+}
+
+/**
+ * Keep only provider-qualified model IDs for a single provider (case-insensitive).
+ * Bare IDs are excluded — tier resolution requires provider/model form.
+ */
+export function restrictModelIdsToProvider(modelIds: string[], provider: string): string[] {
+  const normalized = provider.trim().toLowerCase();
+  if (!normalized) return modelIds;
+  return modelIds.filter((id) => {
+    const slash = id.indexOf("/");
+    if (slash <= 0) return false;
+    return id.slice(0, slash).toLowerCase() === normalized;
+  });
+}
+
+/**
+ * Model IDs for token-profile tier resolution. When an anchor provider is known
+ * (session model / auto-start snapshot), stay on that provider instead of picking
+ * the globally cheapest tier match across every logged-in provider (e.g. Gemini
+ * Flash beating GPT mini on cost).
+ */
+export function modelIdsForProfileResolution(
+  registry: PreferencesModelRegistry,
+  anchorProvider?: string,
+  disabledProviders?: string[],
+): string[] | undefined {
+  let all = availableModelIdsFromRegistry(registry);
+  if (disabledProviders?.length) {
+    const blocked = new Set(
+      disabledProviders.map((p) => p.trim().toLowerCase()).filter((p) => p.length > 0),
+    );
+    all = all.filter((id) => {
+      const slash = id.indexOf("/");
+      if (slash <= 0) return true;
+      return !blocked.has(id.slice(0, slash).toLowerCase());
+    });
+  }
+  if (all.length === 0) return undefined;
+  if (!anchorProvider?.trim()) return all;
+  // Stay on the anchor provider — do not fall back to the full registry when the
+  // scoped list is empty (that reintroduces cross-provider cost picks like Gemini).
+  return restrictModelIdsToProvider(all, anchorProvider);
+}
+
+/** Provider anchor for token-profile tier resolution (auto-start model wins). */
+export function resolveProfileAnchorProvider(
+  sessionProvider?: string,
+  autoModeStartProvider?: string | null,
+): string | undefined {
+  const start = autoModeStartProvider?.trim();
+  if (start) return start;
+  const session = sessionProvider?.trim();
+  return session || undefined;
+}
+
+/**
+ * Load effective preferences with token-profile tiers resolved against models
+ * the user can actually call (from the live registry), not canonical Anthropic
+ * fallbacks.
+ */
+export function loadEffectiveGSDPreferencesWithRegistry(
+  registry: PreferencesModelRegistry | undefined,
+  basePath?: string,
+  anchorProvider?: string,
+  preferredModelId?: string,
+): LoadedGSDPreferences | null {
+  const preferenceOpts = preferredModelId !== undefined
+    ? { preferredModelId }
+    : undefined;
+  if (!registry) {
+    return loadEffectiveGSDPreferences(basePath, preferenceOpts);
+  }
+  const disabledProviders = resolveDisabledModelProvidersFromPreferences();
+  const availableModelIds = modelIdsForProfileResolution(registry, anchorProvider, disabledProviders);
+  if (!availableModelIds) {
+    return loadEffectiveGSDPreferences(basePath, preferenceOpts);
+  }
+  return loadEffectiveGSDPreferences(basePath, { availableModelIds, preferredModelId });
+}
 
 /**
  * Normalize a value loaded from disk (or passed from another component) into
@@ -172,58 +267,136 @@ export function normalizePreferencesShape(
 }
 // ─── Loading ────────────────────────────────────────────────────────────────
 
+const EFFECTIVE_PREFERENCES_CACHE_MAX = 64;
+const effectivePreferencesCache = new Map<string, LoadedGSDPreferences | null>();
+
+export function clearGSDPreferencesCache(): void {
+  effectivePreferencesCache.clear();
+}
+
+function globalPreferencesCandidatePaths(): string[] {
+  return [
+    globalPreferencesPath(),
+    legacyGlobalPreferencesPathLowercase(),
+    legacyGlobalPreferencesPath(),
+  ];
+}
+
+function projectPreferencesCandidatePaths(basePath?: string): string[] {
+  return [
+    projectPreferencesPath(basePath),
+    legacyProjectPreferencesPathLowercase(basePath),
+  ];
+}
+
+function preferencesFileSignature(path: string): string {
+  try {
+    const stats = statSync(path);
+    return `${path}:${stats.size}:${stats.mtimeMs}`;
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code ?? "unknown";
+    return `${path}:missing:${code}`;
+  }
+}
+
+function effectivePreferencesCacheKey(
+  basePath?: string,
+  opts?: { availableModelIds?: string[]; preferredModelId?: string },
+): string {
+  return JSON.stringify({
+    basePath: basePath ?? null,
+    global: globalPreferencesCandidatePaths().map(preferencesFileSignature),
+    project: projectPreferencesCandidatePaths(basePath).map(preferencesFileSignature),
+    availableModelIds: opts?.availableModelIds ?? null,
+    preferredModelId: opts?.preferredModelId ?? null,
+  });
+}
+
+function cloneLoadedPreferences(
+  loaded: LoadedGSDPreferences | null,
+): LoadedGSDPreferences | null {
+  return loaded ? structuredClone(loaded) : null;
+}
+
+function cacheEffectivePreferences(
+  key: string,
+  loaded: LoadedGSDPreferences | null,
+): void {
+  if (!effectivePreferencesCache.has(key) && effectivePreferencesCache.size >= EFFECTIVE_PREFERENCES_CACHE_MAX) {
+    effectivePreferencesCache.clear();
+  }
+  effectivePreferencesCache.set(key, cloneLoadedPreferences(loaded));
+}
+
 export function loadGlobalGSDPreferences(): LoadedGSDPreferences | null {
-  return loadPreferencesFile(globalPreferencesPath(), "global")
-    ?? loadPreferencesFile(legacyGlobalPreferencesPathLowercase(), "global")
-    ?? loadPreferencesFile(legacyGlobalPreferencesPath(), "global");
+  return loadFirstUsablePreferencesFile(globalPreferencesCandidatePaths(), "global");
 }
 
 export function loadProjectGSDPreferences(basePath?: string): LoadedGSDPreferences | null {
-  return loadPreferencesFile(projectPreferencesPath(basePath), "project")
-    ?? loadPreferencesFile(legacyProjectPreferencesPathLowercase(basePath), "project");
+  return loadFirstUsablePreferencesFile(projectPreferencesCandidatePaths(basePath), "project");
 }
 
 export function loadEffectiveGSDPreferences(
   basePath?: string,
-  opts?: { availableModelIds?: string[] },
+  opts?: { availableModelIds?: string[]; preferredModelId?: string },
 ): LoadedGSDPreferences | null {
+  const cacheKey = effectivePreferencesCacheKey(basePath, opts);
+  if (effectivePreferencesCache.has(cacheKey)) {
+    return cloneLoadedPreferences(effectivePreferencesCache.get(cacheKey)!);
+  }
+
   const globalPreferences = loadGlobalGSDPreferences();
   const projectPreferences = loadProjectGSDPreferences(basePath);
-  const projectHasPlanningDepth = projectPreferences?.preferences.planning_depth !== undefined;
+  const effectiveGlobalPreferences = globalPreferences?.ignored ? null : globalPreferences;
+  const effectiveProjectPreferences = projectPreferences?.ignored ? null : projectPreferences;
+  const projectHasPlanningDepth = effectiveProjectPreferences?.preferences.planning_depth !== undefined;
 
-  if (!globalPreferences && !projectPreferences) return null;
+  if (!effectiveGlobalPreferences && !effectiveProjectPreferences) {
+    cacheEffectivePreferences(cacheKey, null);
+    return null;
+  }
 
   let result: LoadedGSDPreferences;
-  if (!globalPreferences) {
-    result = projectPreferences!;
-  } else if (!projectPreferences) {
-    result = globalPreferences;
+  if (!effectiveGlobalPreferences) {
+    result = effectiveProjectPreferences!;
+  } else if (!effectiveProjectPreferences) {
+    result = mergePreferenceMetadata(effectiveGlobalPreferences, projectPreferences);
   } else {
-    const mergedWarnings = [
-      ...(globalPreferences.warnings ?? []),
-      ...(projectPreferences.warnings ?? []),
-    ];
+    const metadata = mergePreferenceMetadata(effectiveGlobalPreferences, effectiveProjectPreferences);
     result = {
-      path: projectPreferences.path,
+      path: effectiveProjectPreferences.path,
       scope: "project",
-      preferences: mergePreferences(globalPreferences.preferences, projectPreferences.preferences),
-      ...(mergedWarnings.length > 0 ? { warnings: mergedWarnings } : {}),
+      preferences: mergePreferences(effectiveGlobalPreferences.preferences, effectiveProjectPreferences.preferences),
+      ...(metadata.warnings ? { warnings: metadata.warnings } : {}),
+      ...(metadata.diagnostics ? { diagnostics: metadata.diagnostics } : {}),
     };
   }
 
   // Apply token-profile defaults as the lowest-priority layer so that
   // `token_profile: budget` sets models and phase-skips automatically.
   // Explicit user preferences always override profile defaults.
-  const profile = result.preferences.token_profile as TokenProfile | undefined;
-  if (profile) {
+  const explicitProfile = result.preferences.token_profile as TokenProfile | undefined;
+  let profileForDefaults: TokenProfile | undefined;
+  if (explicitProfile) {
+    if (VALID_TOKEN_PROFILES.has(explicitProfile)) {
+      profileForDefaults = explicitProfile;
+    }
+  } else {
+    profileForDefaults = DEFAULT_TOKEN_PROFILE;
+  }
+  if (profileForDefaults) {
     const profileDefaults = _resolveProfileDefaults(
-      profile,
+      profileForDefaults,
       opts?.availableModelIds,
       result.preferences.dynamic_routing,
+      opts?.preferredModelId,
     );
+    const defaultsToApply = explicitProfile
+      ? profileDefaults
+      : withoutProfilePhaseDefaults(profileDefaults);
     result = {
       ...result,
-      preferences: mergePreferences(profileDefaults as GSDPreferences, result.preferences),
+      preferences: mergePreferences(defaultsToApply as GSDPreferences, result.preferences),
     };
   }
 
@@ -237,9 +410,53 @@ export function loadEffectiveGSDPreferences(
 
   result = stripInheritedPlanningDepth(result, projectHasPlanningDepth);
 
+  cacheEffectivePreferences(cacheKey, result);
   return result;
 }
 
+function withoutProfilePhaseDefaults(defaults: Partial<GSDPreferences>): Partial<GSDPreferences> {
+  if (defaults.phases === undefined) return defaults;
+  const { phases: _phases, ...rest } = defaults;
+  return rest;
+}
+
+function mergePreferenceMetadata(
+  primary: LoadedGSDPreferences,
+  secondary: LoadedGSDPreferences | null,
+): LoadedGSDPreferences {
+  const mergedWarnings = [
+    ...(primary.warnings ?? []),
+    ...(secondary?.warnings ?? []),
+  ];
+  const mergedDiagnostics = [
+    ...(primary.diagnostics ?? []),
+    ...(secondary?.diagnostics ?? []),
+  ];
+  return {
+    ...primary,
+    ...(mergedWarnings.length > 0 ? { warnings: mergedWarnings } : {}),
+    ...(mergedDiagnostics.length > 0 ? { diagnostics: mergedDiagnostics } : {}),
+  };
+}
+
+function loadFirstUsablePreferencesFile(
+  paths: string[],
+  scope: "global" | "project",
+): LoadedGSDPreferences | null {
+  let ignoredPreferences: LoadedGSDPreferences | null = null;
+
+  for (const path of paths) {
+    const loaded = loadPreferencesFile(path, scope);
+    if (!loaded) continue;
+    if (!loaded.ignored) return mergePreferenceMetadata(loaded, ignoredPreferences);
+    ignoredPreferences = ignoredPreferences
+      ? mergePreferenceMetadata(ignoredPreferences, loaded)
+      : loaded;
+  }
+
+  return ignoredPreferences;
+}
+
 function stripInheritedPlanningDepth(
   loaded: LoadedGSDPreferences,
   projectHasPlanningDepth: boolean,
@@ -260,17 +477,40 @@ function loadPreferencesFile(path: string, scope: "global" | "project"): LoadedG
   if (!existsSync(path)) return null;
 
   const raw = readFileSync(path, "utf-8");
-  const preferences = parsePreferencesMarkdown(raw);
-  if (!preferences) return null;
+  const parsed = parsePreferencesMarkdownWithDiagnostics(raw);
+  if (!parsed.preferences && parsed.diagnostics.length === 0) return null;
 
+  const ignored = parsed.diagnostics.some((diagnostic) => diagnostic.ignored === true);
+  const preferences = parsed.preferences ?? {};
   const validation = validatePreferences(preferences);
   const allWarnings = [...validation.warnings, ...validation.errors];
+  const diagnostics: PreferenceDiagnostic[] = [
+    ...parsed.diagnostics.map((diagnostic) => ({ ...diagnostic, path, scope })),
+    ...validation.errors.map((message): PreferenceDiagnostic => ({
+      path,
+      scope,
+      severity: "error",
+      kind: "validation",
+      message,
+      sanitized: true,
+    })),
+    ...validation.warnings.map((message): PreferenceDiagnostic => ({
+      path,
+      scope,
+      severity: "warning",
+      kind: "validation",
+      message,
+      sanitized: true,
+    })),
+  ];
 
   return {
     path,
     scope,
     preferences: validation.preferences,
+    ...(ignored ? { ignored: true } : {}),
     ...(allWarnings.length > 0 ? { warnings: allWarnings } : {}),
+    ...(diagnostics.length > 0 ? { diagnostics } : {}),
   };
 }
 
@@ -286,20 +526,44 @@ export function _resetParseWarningFlag(): void {
 
 /** @internal Exported for testing only */
 export function parsePreferencesMarkdown(content: string): GSDPreferences | null {
+  return parsePreferencesMarkdownWithDiagnostics(content).preferences;
+}
+
+type PreferenceParseDiagnostic = Omit<PreferenceDiagnostic, "path" | "scope">;
+
+interface PreferenceParseResult {
+  preferences: GSDPreferences | null;
+  diagnostics: PreferenceParseDiagnostic[];
+}
+
+function parsePreferencesMarkdownWithDiagnostics(content: string): PreferenceParseResult {
   // Use indexOf instead of [\s\S]*? regex to avoid backtracking (#468)
   const startMarker = content.startsWith('---\r\n') ? '---\r\n' : '---\n';
   if (content.startsWith(startMarker)) {
     const searchStart = startMarker.length;
     const endIdx = content.indexOf('\n---', searchStart);
-    if (endIdx === -1) return null;
+    if (endIdx === -1) {
+      return {
+        preferences: null,
+        diagnostics: [{
+          severity: "error",
+          kind: "parse",
+          message: "preferences frontmatter is missing a closing --- delimiter",
+          ignored: true,
+        }],
+      };
+    }
     const block = content.slice(searchStart, endIdx);
-    return parseFrontmatterBlock(block.replace(/\r/g, ''));
+    return parseFrontmatterBlockWithDiagnostics(block.replace(/\r/g, ''), 1);
   }
 
   // Fallback: heading+list format (e.g. "## Git\n- isolation: none") (#2036)
   // GSD agents may write preferences files without frontmatter delimiters.
   if (/^##\s+\w/m.test(content)) {
-    return parseHeadingListFormat(content);
+    return {
+      preferences: parseHeadingListFormat(content),
+      diagnostics: [],
+    };
   }
 
   // Warn when a non-empty file exists but lacks frontmatter delimiters (#2036).
@@ -310,27 +574,82 @@ export function parsePreferencesMarkdown(content: string): GSDPreferences | null
       "Wrap your preferences in --- fences. See https://github.com/open-gsd/gsd-pi/issues/2036",
     );
   }
-  return null;
+  return {
+    preferences: null,
+    diagnostics: content.trim().length > 0
+      ? [{
+          severity: "error",
+          kind: "parse",
+          message: "preferences file has unrecognized format; expected YAML frontmatter delimiters (---) or markdown preference sections",
+          ignored: true,
+        }]
+      : [],
+  };
 }
 
 let _warnedFrontmatterParse = false;
-function parseFrontmatterBlock(frontmatter: string): GSDPreferences {
+function parseFrontmatterBlockWithDiagnostics(
+  frontmatter: string,
+  lineOffset: number,
+): { preferences: GSDPreferences; diagnostics: PreferenceParseDiagnostic[] } {
   try {
     const parsed = parseYaml(frontmatter);
     if (typeof parsed !== 'object' || parsed === null) {
-      return {} as GSDPreferences;
+      return {
+        preferences: {} as GSDPreferences,
+        diagnostics: [{
+          severity: "error",
+          kind: "validation",
+          message: "preferences frontmatter must be a YAML object",
+          ignored: true,
+        }],
+      };
     }
-    return normalizeParsedPreferences(parsed as GSDPreferences);
+    return {
+      preferences: normalizeParsedPreferences(parsed as GSDPreferences),
+      diagnostics: [],
+    };
   } catch (e) {
     // Warn at most once per session to avoid flooding TUI (#3376)
     if (!_warnedFrontmatterParse) {
       _warnedFrontmatterParse = true;
       logWarning("guided", `YAML parse error in preferences frontmatter (suppressing further): ${(e as Error).message}`);
     }
-    return {} as GSDPreferences;
+    const location = extractYamlErrorLocation(e, lineOffset);
+    return {
+      preferences: {} as GSDPreferences,
+      diagnostics: [{
+        severity: "error",
+        kind: "parse",
+        message: cleanYamlErrorMessage(e),
+        ...(location.line !== undefined ? { line: location.line } : {}),
+        ...(location.column !== undefined ? { column: location.column } : {}),
+        ignored: true,
+      }],
+    };
   }
 }
 
+function cleanYamlErrorMessage(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  const firstLine = message.split("\n")[0]?.trim() ?? "unknown YAML parse error";
+  return firstLine.replace(/\s+at line \d+, column \d+:?$/, "");
+}
+
+function extractYamlErrorLocation(
+  error: unknown,
+  lineOffset: number,
+): { line?: number; column?: number } {
+  const linePos = (error as { linePos?: Array<{ line?: unknown; col?: unknown }> })?.linePos;
+  const first = Array.isArray(linePos) ? linePos[0] : undefined;
+  const line = typeof first?.line === "number" ? first.line + lineOffset : undefined;
+  const column = typeof first?.col === "number" ? first.col : undefined;
+  return {
+    ...(line !== undefined ? { line } : {}),
+    ...(column !== undefined ? { column } : {}),
+  };
+}
+
 function normalizeParsedPreferences(preferences: GSDPreferences): GSDPreferences {
   const remoteQuestions = preferences.remote_questions;
   if (remoteQuestions && typeof remoteQuestions === "object" && typeof remoteQuestions.channel_id === "number") {
@@ -722,6 +1041,24 @@ export function getIsolationMode(basePath?: string): "none" | "worktree" | "bran
   return "none"; // default — no isolation, work on current branch
 }
 
+/**
+ * Resolve the isolation mode a unit actually runs under. A session whose
+ * worktree isolation has degraded (worktree creation failed) falls back to
+ * the milestone branch in the project root, so configured "worktree" becomes
+ * effective "branch". A stranded-work recovery session likewise runs under
+ * the adopted mode (`strandedRecoveryIsolationMode`) rather than the
+ * configured one until the recovered milestone merges — adopting the
+ * milestone branch in the project root is intentional, not degraded.
+ */
+export function resolveEffectiveUnitIsolationMode(
+  configuredMode: ReturnType<typeof getIsolationMode>,
+  isolationDegraded: boolean,
+  strandedRecoveryIsolationMode: "worktree" | "branch" | null = null,
+): ReturnType<typeof getIsolationMode> {
+  if (configuredMode === "worktree" && isolationDegraded) return "branch";
+  return strandedRecoveryIsolationMode ?? configuredMode;
+}
+
 export function resolveParallelConfig(prefs: GSDPreferences | undefined): import("./types.js").ParallelConfig {
   return {
     enabled: prefs?.parallel?.enabled ?? false,

package/src/resources/extensions/gsd/projection-flush.ts

@@ -0,0 +1,20 @@
+// Project/App: gsd-pi
+// File Purpose: Single workflow projection flush seam for mutation exits.
+
+import { renderAllProjections } from "./workflow-projections.js";
+
+export interface ProjectionFlushScope {
+  milestoneId: string;
+}
+
+export interface ProjectionFlushResult {
+  milestoneId: string;
+}
+
+export async function flushWorkflowProjections(
+  basePath: string,
+  scope: ProjectionFlushScope,
+): Promise<ProjectionFlushResult> {
+  await renderAllProjections(basePath, scope.milestoneId);
+  return { milestoneId: scope.milestoneId };
+}

package/src/resources/extensions/gsd/prompts/ai-integration-phase.md

@@ -0,0 +1,28 @@
+You are running the GSD **ai-integration-phase** workflow — produce an AI design contract (AI-SPEC) for a milestone/slice that builds an AI system.
+
+## Target
+
+{{target}}
+
+## Process
+
+1. **Load intent.** Read the milestone/slice goal and requirements for the AI capability.
+
+2. **Define the AI capability contract:**
+   - **Inputs:** what the model receives (schema, context, examples) and any preprocessing.
+   - **Outputs:** the expected response shape, how it's parsed/validated, and how failures are handled.
+   - **Model & parameters:** which model/provider, temperature, max tokens, fallback chain — never hardcode; reference config.
+   - **Prompt/contract:** the system/user prompt strategy, or tool/function calling schema.
+   - **Evaluation:** how quality is measured (eval set, rubric, human-in-the-loop checkpoints).
+   - **Cost & latency budget:** expected per-call cost and latency, and the ceiling that triggers a redesign.
+
+3. **Risk register.** Hallucination/grounding, prompt injection, data leakage, cost runaway, model deprecation. For each, the mitigation.
+
+4. **Write the AI-SPEC** to the milestone/slice artifact in `.gsd/`. Recommend `/gsd plan-phase` or `/gsd spike` for high-uncertainty model behaviors.
+
+## Success criteria
+
+- Inputs/outputs are schema-defined, not prose-only.
+- Evaluation is concrete (eval set + rubric), not "it looks good".
+- Cost/latency has a budget and a ceiling.
+- The risk register covers the standard AI failure modes.

package/src/resources/extensions/gsd/prompts/audit-fix.md

@@ -0,0 +1,39 @@
+You are running the GSD **audit-fix** workflow — autonomous audit-to-fix pipeline: find issues, classify them, fix the auto-fixable ones, test after each fix, and commit atomically.
+
+## Source
+
+{{source}}
+
+## Severity filter
+
+{{severity}}
+
+## Max fixes
+
+{{maxFixes}}
+
+## Dry run
+
+{{dryRun}}
+
+## Process
+
+1. **Run the audit.** Use the named source audit (default: the most recent audit-uat / scan findings). If no audit exists, run a fresh `/gsd scan --focus concerns` first and use those findings.
+
+2. **Parse and classify findings.** For each finding, decide: `auto-fixable` (deterministic, localized, no public-behavior change) or `manual-only` (ambiguous, risky, or behavior-changing). Apply the severity filter and the `--max` cap.
+
+3. **Fix loop** (skip entirely if `--dry-run`). For each auto-fixable finding, in priority order:
+   - Apply the fix.
+   - Run the project's tests.
+   - If tests pass, stage the change and record the finding id.
+   - If tests fail, revert that fix, mark it manual-only, and continue.
+   Commit atomically, referencing the finding ids in the commit message for traceability.
+
+4. **Report.** List: fixed (with finding ids + commits), deferred to manual (with reasons), and any that were attempted but reverted due to test failure.
+
+## Success criteria
+
+- Every fix is tested before it's kept; failing fixes are reverted, not left half-applied.
+- Commits are atomic and reference finding ids.
+- `--dry-run` shows what would be fixed without changing anything.
+- Manual-only findings are reported, not silently ignored.

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

@@ -0,0 +1,26 @@
+You are running the GSD **audit-milestone** workflow — verify a milestone achieved its definition of done before it is archived.
+
+## Target
+
+{{target}}
+
+## Process
+
+1. **Load the milestone.** Read the milestone's ROADMAP entry, its slices' plans and SUMMARY/ASSESSMENT artifacts, and the requirements/acceptance criteria. If a specific milestone id was given, target it; otherwise target the active or most-recently-completed milestone.
+
+2. **Aggregate per-slice verification.** For each slice, confirm its tasks were completed and its verification strategy was satisfied (tests pass, UAT recorded). Flag slices with incomplete verification.
+
+3. **Check requirements coverage.** Map each requirement/acceptance criterion to the slice(s) and tasks that delivered it. Flag any requirement with no covering evidence.
+
+4. **Check cross-slice integration.** Identify slices that touch shared resources (APIs, data models, state) and confirm their integration points are consistent — no broken handoffs, conflicting schemas, or sequencing gaps.
+
+5. **Aggregate debt and deferred items.** Collect tech debt, deferred tasks, and known gaps into a single list with severity and owner-hint.
+
+6. **Produce the verdict.** Report: `PASS` (done-of-definition met), `NEEDS-ATTENTION` (gaps that need a human call), or `NEEDS-REMEDIATION` (gaps that block archival). Recommend the matching gsd-pi next step (`/gsd verdict`, `/gsd dispatch validate`, or scheduling remediation).
+
+## Success criteria
+
+- Every requirement is mapped to covering evidence or flagged as uncovered.
+- Cross-slice integration risks are explicit, not assumed away.
+- The verdict is one of the three canonical values with supporting evidence.
+- Debt/deferred items are listed, not silently dropped.