gsd-pi 2.50.0 → 2.51.0-dev.7d435fe

package/src/resources/extensions/gsd/observability-validator.ts

@@ -0,0 +1,456 @@
+import { loadFile } from "./files.js";
+import { resolveSliceFile, resolveTaskFile, resolveTasksDir, resolveTaskFiles } from "./paths.js";
+
+export interface ValidationIssue {
+  severity: "info" | "warning" | "error";
+  scope: "slice-plan" | "task-plan" | "task-summary" | "slice-summary";
+  file: string;
+  ruleId: string;
+  message: string;
+  suggestion?: string;
+}
+
+function getSection(content: string, heading: string, level: number = 2): string | null {
+  const prefix = "#".repeat(level) + " ";
+  const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const regex = new RegExp(`^${prefix}${escaped}\\s*$`, "m");
+  const match = regex.exec(content);
+  if (!match) return null;
+
+  const start = match.index + match[0].length;
+  const rest = content.slice(start);
+  const nextHeading = rest.match(new RegExp(`^#{1,${level}} `, "m"));
+  const end = nextHeading ? nextHeading.index! : rest.length;
+  return rest.slice(0, end).trim();
+}
+
+function getFrontmatter(content: string): string | null {
+  const trimmed = content.trimStart();
+  if (!trimmed.startsWith("---")) return null;
+  const afterFirst = trimmed.indexOf("\n");
+  if (afterFirst === -1) return null;
+  const rest = trimmed.slice(afterFirst + 1);
+  const endIdx = rest.indexOf("\n---");
+  if (endIdx === -1) return null;
+  return rest.slice(0, endIdx);
+}
+
+function hasFrontmatterKey(content: string, key: string): boolean {
+  const fm = getFrontmatter(content);
+  if (!fm) return false;
+  return new RegExp(`^${key}:`, "m").test(fm);
+}
+
+function normalizeMeaningfulLines(text: string): string[] {
+  return text
+    .split("\n")
+    .map(line => line.trim())
+    .filter(line => line.length > 0)
+    .filter(line => !line.startsWith("<!--"))
+    .filter(line => !line.endsWith("-->"))
+    .filter(line => !/^[-*]\s*\{\{.+\}\}$/.test(line))
+    .filter(line => !/^\{\{.+\}\}$/.test(line));
+}
+
+function sectionLooksPlaceholderOnly(text: string | null): boolean {
+  if (!text) return true;
+  const lines = normalizeMeaningfulLines(text)
+    .map(line => line.replace(/^[-*]\s+/, "").trim())
+    .filter(line => line.length > 0);
+
+  if (lines.length === 0) return true;
+
+  return lines.every(line => {
+    const lower = line.toLowerCase();
+    return lower === "none" ||
+      lower.endsWith(": none") ||
+      lower.includes("{{") ||
+      lower.includes("}}") ||
+      lower.startsWith("required for non-trivial") ||
+      lower.startsWith("describe how a future agent") ||
+      lower.startsWith("prefer:") ||
+      lower.startsWith("keep this section concise");
+  });
+}
+
+function textSuggestsObservabilityRelevant(content: string): boolean {
+  const lower = content.toLowerCase();
+  const needles = [
+    " api", "route", "server", "worker", "queue", "job", "sync", "import",
+    "webhook", "auth", "db", "database", "migration", "cache", "background",
+    "polling", "realtime", "socket", "stateful", "integration", "ui", "form",
+    "submit", "status", "service", "pipeline", "health endpoint", "error path"
+  ];
+  return needles.some(needle => lower.includes(needle));
+}
+
+function verificationMentionsDiagnostics(section: string | null): boolean {
+  if (!section) return false;
+  const lower = section.toLowerCase();
+  const needles = [
+    "error", "failure", "diagnostic", "status", "health", "inspect", "log",
+    "network", "console", "retry", "last error", "correlation", "readiness"
+  ];
+  return needles.some(needle => lower.includes(needle));
+}
+
+export function validateSlicePlanContent(file: string, content: string): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  // ── Plan quality rules (always run, not gated by runtime relevance) ──
+
+  const tasksSection = getSection(content, "Tasks", 2);
+  if (tasksSection) {
+    const lines = tasksSection.split("\n");
+    const taskLinePattern = /^- \[[ x]\] \*\*T\d+:/;
+    const taskLineIndices: number[] = [];
+    for (let i = 0; i < lines.length; i++) {
+      if (taskLinePattern.test(lines[i])) taskLineIndices.push(i);
+    }
+
+    for (let t = 0; t < taskLineIndices.length; t++) {
+      const start = taskLineIndices[t];
+      const end = t + 1 < taskLineIndices.length ? taskLineIndices[t + 1] : lines.length;
+      // Check lines between this task header and the next (or section end)
+      const bodyLines = lines.slice(start + 1, end);
+      const meaningful = bodyLines.filter(l => l.trim().length > 0);
+      if (meaningful.length === 0) {
+        issues.push({
+          severity: "warning",
+          scope: "slice-plan",
+          file,
+          ruleId: "empty_task_entry",
+          message: "Inline task entry has no description content beneath the checkbox line.",
+          suggestion: "Add at least a Why/Files/Do/Verify summary so the task is self-describing.",
+        });
+      }
+    }
+  }
+
+  // ── Observability rules (gated by runtime relevance) ──
+
+  const relevant = textSuggestsObservabilityRelevant(content);
+  if (!relevant) return issues;
+
+  const obs = getSection(content, "Observability / Diagnostics", 2);
+  const verification = getSection(content, "Verification", 2);
+
+  if (!obs) {
+    issues.push({
+      severity: "warning",
+      scope: "slice-plan",
+      file,
+      ruleId: "missing_observability_section",
+      message: "Slice plan appears non-trivial but is missing `## Observability / Diagnostics`.",
+      suggestion: "Add runtime signals, inspection surfaces, failure visibility, and redaction constraints.",
+    });
+  } else if (sectionLooksPlaceholderOnly(obs)) {
+    issues.push({
+      severity: "warning",
+      scope: "slice-plan",
+      file,
+      ruleId: "observability_section_placeholder_only",
+      message: "Slice plan has `## Observability / Diagnostics` but it still looks like placeholder text.",
+      suggestion: "Replace placeholders with concrete signals and inspection surfaces a future agent should trust.",
+    });
+  }
+
+  if (!verificationMentionsDiagnostics(verification)) {
+    issues.push({
+      severity: "warning",
+      scope: "slice-plan",
+      file,
+      ruleId: "verification_missing_diagnostic_check",
+      message: "Slice verification does not appear to include any diagnostic or failure-path check.",
+      suggestion: "Add at least one verification step for inspectable failure state, structured error output, status surface, or equivalent.",
+    });
+  }
+
+  return issues;
+}
+
+export function validateTaskPlanContent(file: string, content: string): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  // ── Plan quality rules (always run, not gated by runtime relevance) ──
+
+  // Rule: empty or missing Steps section
+  const stepsSection = getSection(content, "Steps", 2);
+  if (stepsSection === null || sectionLooksPlaceholderOnly(stepsSection)) {
+    issues.push({
+      severity: "warning",
+      scope: "task-plan",
+      file,
+      ruleId: "empty_steps_section",
+      message: "Task plan has an empty or missing `## Steps` section.",
+      suggestion: "Add concrete numbered implementation steps so execution has a clear sequence.",
+    });
+  }
+
+  // Rule: placeholder-only Verification section
+  const verificationSection = getSection(content, "Verification", 2);
+  if (verificationSection !== null && sectionLooksPlaceholderOnly(verificationSection)) {
+    issues.push({
+      severity: "warning",
+      scope: "task-plan",
+      file,
+      ruleId: "placeholder_verification",
+      message: "Task plan has `## Verification` but it still looks like placeholder text.",
+      suggestion: "Replace placeholders with concrete verification commands, test runs, or observable checks.",
+    });
+  }
+
+  // Rule: scope estimate thresholds
+  const fm = getFrontmatter(content);
+  if (fm) {
+    const stepsMatch = fm.match(/^estimated_steps:\s*(\d+)/m);
+    const filesMatch = fm.match(/^estimated_files:\s*(\d+)/m);
+
+    if (stepsMatch) {
+      const estimatedSteps = parseInt(stepsMatch[1], 10);
+      if (estimatedSteps >= 10) {
+        issues.push({
+          severity: "warning",
+          scope: "task-plan",
+          file,
+          ruleId: "scope_estimate_steps_high",
+          message: `Task plan estimates ${estimatedSteps} steps (threshold: 10). Consider splitting into smaller tasks.`,
+          suggestion: "Break the task into sub-tasks or reduce scope so each task stays focused and completable in one pass.",
+        });
+      }
+    }
+
+    if (filesMatch) {
+      const estimatedFiles = parseInt(filesMatch[1], 10);
+      if (estimatedFiles >= 12) {
+        issues.push({
+          severity: "warning",
+          scope: "task-plan",
+          file,
+          ruleId: "scope_estimate_files_high",
+          message: `Task plan estimates ${estimatedFiles} files (threshold: 12). Consider splitting into smaller tasks.`,
+          suggestion: "Break the task into sub-tasks or reduce scope to keep the change footprint manageable.",
+        });
+      }
+    }
+  }
+
+  // Rule: Inputs and Expected Output should contain backtick-wrapped file paths
+  const inputsSection = getSection(content, "Inputs", 2);
+  const outputSection = getSection(content, "Expected Output", 2);
+  const backtickPathPattern = /`[^`]*[./][^`]*`/;
+
+  if (outputSection === null || !backtickPathPattern.test(outputSection)) {
+    issues.push({
+      severity: "warning",
+      scope: "task-plan",
+      file,
+      ruleId: "missing_output_file_paths",
+      message: "Task plan `## Expected Output` is missing or has no backtick-wrapped file paths.",
+      suggestion: "List concrete output file paths in backticks (e.g. `src/types.ts`). These are machine-parsed to derive task dependencies.",
+    });
+  }
+
+  if (inputsSection !== null && inputsSection.trim().length > 0 && !backtickPathPattern.test(inputsSection)) {
+    issues.push({
+      severity: "info",
+      scope: "task-plan",
+      file,
+      ruleId: "missing_input_file_paths",
+      message: "Task plan `## Inputs` has content but no backtick-wrapped file paths.",
+      suggestion: "List input file paths in backticks (e.g. `src/config.json`). These are machine-parsed to derive task dependencies.",
+    });
+  }
+
+  // ── Observability rules (gated by runtime relevance) ──
+
+  const relevant = textSuggestsObservabilityRelevant(content);
+  if (!relevant) return issues;
+
+  const obs = getSection(content, "Observability Impact", 2);
+  if (!obs) {
+    issues.push({
+      severity: "warning",
+      scope: "task-plan",
+      file,
+      ruleId: "missing_observability_impact",
+      message: "Task plan appears runtime-relevant but is missing `## Observability Impact`.",
+      suggestion: "Explain what signals change, how a future agent inspects this task, and what failure state becomes visible.",
+    });
+  } else if (sectionLooksPlaceholderOnly(obs)) {
+    issues.push({
+      severity: "warning",
+      scope: "task-plan",
+      file,
+      ruleId: "observability_impact_placeholder_only",
+      message: "Task plan has `## Observability Impact` but it still looks empty or placeholder-only.",
+      suggestion: "Fill in concrete inspection surfaces or explicitly justify why observability is not applicable.",
+    });
+  }
+
+  return issues;
+}
+
+export function validateTaskSummaryContent(file: string, content: string): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  if (!hasFrontmatterKey(content, "observability_surfaces")) {
+    issues.push({
+      severity: "warning",
+      scope: "task-summary",
+      file,
+      ruleId: "missing_observability_frontmatter",
+      message: "Task summary is missing `observability_surfaces` in frontmatter.",
+      suggestion: "List the durable status/log/error surfaces a future agent should use.",
+    });
+  }
+
+  const diagnostics = getSection(content, "Diagnostics", 2);
+  if (!diagnostics) {
+    issues.push({
+      severity: "warning",
+      scope: "task-summary",
+      file,
+      ruleId: "missing_diagnostics_section",
+      message: "Task summary is missing `## Diagnostics`.",
+      suggestion: "Document how to inspect what this task built later.",
+    });
+  } else if (sectionLooksPlaceholderOnly(diagnostics)) {
+    issues.push({
+      severity: "warning",
+      scope: "task-summary",
+      file,
+      ruleId: "diagnostics_placeholder_only",
+      message: "Task summary diagnostics section still looks like placeholder text.",
+      suggestion: "Replace placeholders with concrete commands, endpoints, logs, error shapes, or failure artifacts.",
+    });
+  }
+
+  const evidence = getSection(content, "Verification Evidence", 2);
+  if (!evidence) {
+    issues.push({
+      severity: "warning",
+      scope: "task-summary",
+      file,
+      ruleId: "evidence_block_missing",
+      message: "Task summary is missing `## Verification Evidence`.",
+      suggestion: "Add a verification evidence table showing gate check results (command, exit code, verdict, duration).",
+    });
+  } else if (sectionLooksPlaceholderOnly(evidence)) {
+    issues.push({
+      severity: "warning",
+      scope: "task-summary",
+      file,
+      ruleId: "evidence_block_placeholder",
+      message: "Task summary verification evidence section still looks like placeholder text.",
+      suggestion: "Replace placeholders with actual gate results or note that no verification commands were discovered.",
+    });
+  }
+
+  return issues;
+}
+
+export function validateSliceSummaryContent(file: string, content: string): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  if (!hasFrontmatterKey(content, "observability_surfaces")) {
+    issues.push({
+      severity: "warning",
+      scope: "slice-summary",
+      file,
+      ruleId: "missing_observability_frontmatter",
+      message: "Slice summary is missing `observability_surfaces` in frontmatter.",
+      suggestion: "List the authoritative diagnostics and durable inspection surfaces for this slice.",
+    });
+  }
+
+  const diagnostics = getSection(content, "Authoritative diagnostics", 3);
+  if (!diagnostics) {
+    issues.push({
+      severity: "warning",
+      scope: "slice-summary",
+      file,
+      ruleId: "missing_authoritative_diagnostics",
+      message: "Slice summary is missing `### Authoritative diagnostics` in Forward Intelligence.",
+      suggestion: "Tell future agents where to look first and why that signal is trustworthy.",
+    });
+  } else if (sectionLooksPlaceholderOnly(diagnostics)) {
+    issues.push({
+      severity: "warning",
+      scope: "slice-summary",
+      file,
+      ruleId: "authoritative_diagnostics_placeholder_only",
+      message: "Slice summary includes authoritative diagnostics but it still looks like placeholder text.",
+      suggestion: "Replace placeholders with the real first-stop diagnostic surface for this slice.",
+    });
+  }
+
+  return issues;
+}
+
+export async function validatePlanBoundary(basePath: string, milestoneId: string, sliceId: string): Promise<ValidationIssue[]> {
+  const issues: ValidationIssue[] = [];
+  const slicePlan = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN");
+  if (slicePlan) {
+    const content = await loadFile(slicePlan);
+    if (content) issues.push(...validateSlicePlanContent(slicePlan, content));
+  }
+
+  const tasksDir = resolveTasksDir(basePath, milestoneId, sliceId);
+  const taskPlans = tasksDir ? resolveTaskFiles(tasksDir, "PLAN") : [];
+  for (const file of taskPlans) {
+    const taskId = file.split("-")[0];
+    const taskPlan = resolveTaskFile(basePath, milestoneId, sliceId, taskId, "PLAN");
+    if (!taskPlan) continue;
+    const content = await loadFile(taskPlan);
+    if (content) issues.push(...validateTaskPlanContent(taskPlan, content));
+  }
+
+  return issues;
+}
+
+export async function validateExecuteBoundary(basePath: string, milestoneId: string, sliceId: string, taskId: string): Promise<ValidationIssue[]> {
+  const issues: ValidationIssue[] = [];
+  const slicePlan = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN");
+  if (slicePlan) {
+    const content = await loadFile(slicePlan);
+    if (content) issues.push(...validateSlicePlanContent(slicePlan, content));
+  }
+
+  const taskPlan = resolveTaskFile(basePath, milestoneId, sliceId, taskId, "PLAN");
+  if (taskPlan) {
+    const content = await loadFile(taskPlan);
+    if (content) issues.push(...validateTaskPlanContent(taskPlan, content));
+  }
+
+  return issues;
+}
+
+export async function validateCompleteBoundary(basePath: string, milestoneId: string, sliceId: string): Promise<ValidationIssue[]> {
+  const issues: ValidationIssue[] = [];
+  const tasksDir = resolveTasksDir(basePath, milestoneId, sliceId);
+  const taskSummaries = tasksDir ? resolveTaskFiles(tasksDir, "SUMMARY") : [];
+  for (const file of taskSummaries) {
+    const taskId = file.split("-")[0];
+    const taskSummary = resolveTaskFile(basePath, milestoneId, sliceId, taskId, "SUMMARY");
+    if (!taskSummary) continue;
+    const content = await loadFile(taskSummary);
+    if (content) issues.push(...validateTaskSummaryContent(taskSummary, content));
+  }
+
+  const sliceSummary = resolveSliceFile(basePath, milestoneId, sliceId, "SUMMARY");
+  if (sliceSummary) {
+    const content = await loadFile(sliceSummary);
+    if (content) issues.push(...validateSliceSummaryContent(sliceSummary, content));
+  }
+
+  return issues;
+}
+
+export function formatValidationIssues(issues: ValidationIssue[], limit: number = 4): string {
+  if (issues.length === 0) return "";
+  const lines = issues.slice(0, limit).map(issue => {
+    const fileName = issue.file.split("/").pop() || issue.file;
+    return `- ${fileName}: ${issue.message}`;
+  });
+  if (issues.length > limit) lines.push(`- ...and ${issues.length - limit} more`);
+  return lines.join("\n");
+}

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

@@ -125,18 +125,6 @@ export function getNextFallbackModel(
   }
 }
 
-/**
- * Detect whether an error message indicates a transient network error
- * (worth retrying the same model) vs a permanent provider error
- * (auth failure, quota exceeded, etc. -- should fall back immediately).
- */
-export function isTransientNetworkError(errorMsg: string): boolean {
-  if (!errorMsg) return false;
-  const hasNetworkSignal = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|fetch failed|connection.*reset|dns/i.test(errorMsg);
-  const hasPermanentSignal = /auth|unauthorized|forbidden|invalid.*key|quota|billing/i.test(errorMsg);
-  return hasNetworkSignal && !hasPermanentSignal;
-}
-
 /**
  * Validate a model ID string.
  * Returns true if the ID looks like a valid model identifier.
@@ -308,7 +296,7 @@ export function resolveContextSelection(): import("./types.js").ContextSelection
 }
 
 /**
- * Resolve the search provider preference from preferences.md.
+ * Resolve the search provider preference from PREFERENCES.md.
  * Returns undefined if not configured (caller falls back to existing behavior).
  */
 export function resolveSearchProviderFromPreferences(): GSDPreferences["search_provider"] | undefined {

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

@@ -8,7 +8,6 @@
 import { existsSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
-import { getAgentDir } from "@gsd/pi-coding-agent";
 import { statSync } from "node:fs";
 
 import type {
@@ -25,13 +24,20 @@ export type { GSDSkillRule, SkillDiscoveryMode, SkillResolution, SkillResolution
 
 /**
  * Known skill directories, in priority order.
- * User skills (~/.gsd/agent/skills/) take precedence over project skills.
+ * Global skills (~/.agents/skills/) take precedence over project skills.
+ * Legacy ~/.gsd/agent/skills/ is included as a fallback for pre-migration installs.
  */
 export function getSkillSearchDirs(cwd: string): Array<{ dir: string; method: SkillResolution["method"] }> {
-  return [
-    { dir: join(getAgentDir(), "skills"), method: "user-skill" },
-    { dir: join(cwd, ".pi", "agent", "skills"), method: "project-skill" },
+  const dirs: Array<{ dir: string; method: SkillResolution["method"] }> = [
+    { dir: join(homedir(), ".agents", "skills"), method: "user-skill" },
+    { dir: join(cwd, ".agents", "skills"), method: "project-skill" },
   ];
+  // Legacy fallback — read skills from old GSD directory only if migration hasn't completed
+  const legacyDir = join(homedir(), ".gsd", "agent", "skills");
+  if (existsSync(legacyDir) && !existsSync(join(legacyDir, ".migrated-to-agents"))) {
+    dirs.push({ dir: legacyDir, method: "user-skill" });
+  }
+  return dirs;
 }
 
 /**

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

@@ -93,6 +93,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "service_tier",
   "forensics_dedup",
   "show_token_cost",
+  "experimental",
 ]);
 
 /** Canonical list of all dispatch unit types. */
@@ -182,6 +183,20 @@ export interface CmuxPreferences {
   browser?: boolean;
 }
 
+/**
+ * Opt-in experimental features. All features in this block are disabled by
+ * default and must be explicitly enabled. They may change or be removed without
+ * a deprecation cycle while in experimental status.
+ */
+export interface ExperimentalPreferences {
+  /**
+   * Enable RTK (Real-Time Kompression) shell-command compression.
+   * RTK wraps shell commands to reduce token usage during command execution.
+   * Default: false (opt-in required).
+   */
+  rtk?: boolean;
+}
+
 export interface GSDPreferences {
   version?: number;
   mode?: WorkflowMode;
@@ -233,6 +248,11 @@ export interface GSDPreferences {
   forensics_dedup?: boolean;
   /** Opt-in: show per-prompt and cumulative session token cost in the footer. Default: false. */
   show_token_cost?: boolean;
+  /**
+   * Opt-in experimental features. All features here are disabled by default.
+   * See the preferences reference for details on each feature.
+   */
+  experimental?: ExperimentalPreferences;
 }
 
 export interface LoadedGSDPreferences {

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

@@ -793,5 +793,31 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Experimental Features ────────────────────────────────────────
+  if (preferences.experimental !== undefined) {
+    if (typeof preferences.experimental === "object" && preferences.experimental !== null) {
+      const exp = preferences.experimental as unknown as Record<string, unknown>;
+      const validExp: import("./preferences-types.js").ExperimentalPreferences = {};
+
+      if (exp.rtk !== undefined) {
+        if (typeof exp.rtk === "boolean") validExp.rtk = exp.rtk;
+        else errors.push("experimental.rtk must be a boolean");
+      }
+
+      const knownExpKeys = new Set(["rtk"]);
+      for (const key of Object.keys(exp)) {
+        if (!knownExpKeys.has(key)) {
+          warnings.push(`unknown experimental key "${key}" — ignored`);
+        }
+      }
+
+      if (Object.keys(validExp).length > 0) {
+        validated.experimental = validExp;
+      }
+    } else {
+      errors.push("experimental must be an object");
+    }
+  }
+
   return { preferences: validated, errors, warnings };
 }

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

@@ -68,7 +68,6 @@ export {
   resolveModelForUnit,
   resolveModelWithFallbacksForUnit,
   getNextFallbackModel,
-  isTransientNetworkError,
   validateModelId,
   updatePreferencesModels,
   resolveDynamicRoutingConfig,
@@ -87,7 +86,7 @@ function gsdHome(): string {
 }
 
 function globalPreferencesPath(): string {
-  return join(gsdHome(), "preferences.md");
+  return join(gsdHome(), "PREFERENCES.md");
 }
 
 function legacyGlobalPreferencesPath(): string {
@@ -95,15 +94,15 @@ function legacyGlobalPreferencesPath(): string {
 }
 
 function projectPreferencesPath(): string {
-  return join(gsdRoot(process.cwd()), "preferences.md");
+  return join(gsdRoot(process.cwd()), "PREFERENCES.md");
 }
-// Bootstrap in gitignore.ts historically created PREFERENCES.md (uppercase) by mistake.
-// Check uppercase as a fallback so those files aren't silently ignored.
-function globalPreferencesPathUppercase(): string {
-  return join(gsdHome(), "PREFERENCES.md");
+// Legacy: older versions used lowercase preferences.md.
+// Check lowercase as a fallback so those files aren't silently ignored.
+function globalPreferencesPathLegacy(): string {
+  return join(gsdHome(), "preferences.md");
 }
-function projectPreferencesPathUppercase(): string {
-  return join(gsdRoot(process.cwd()), "PREFERENCES.md");
+function projectPreferencesPathLegacy(): string {
+  return join(gsdRoot(process.cwd()), "preferences.md");
 }
 
 export function getGlobalGSDPreferencesPath(): string {
@@ -122,13 +121,13 @@ export function getProjectGSDPreferencesPath(): string {
 
 export function loadGlobalGSDPreferences(): LoadedGSDPreferences | null {
   return loadPreferencesFile(globalPreferencesPath(), "global")
-    ?? loadPreferencesFile(globalPreferencesPathUppercase(), "global")
+    ?? loadPreferencesFile(globalPreferencesPathLegacy(), "global")
     ?? loadPreferencesFile(legacyGlobalPreferencesPath(), "global");
 }
 
 export function loadProjectGSDPreferences(): LoadedGSDPreferences | null {
   return loadPreferencesFile(projectPreferencesPath(), "project")
-    ?? loadPreferencesFile(projectPreferencesPathUppercase(), "project");
+    ?? loadPreferencesFile(projectPreferencesPathLegacy(), "project");
 }
 
 export function loadEffectiveGSDPreferences(): LoadedGSDPreferences | null {
@@ -223,7 +222,7 @@ export function parsePreferencesMarkdown(content: string): GSDPreferences | null
 
   if (!_warnedUnrecognizedFormat) {
     _warnedUnrecognizedFormat = true;
-    console.warn("[parsePreferencesMarkdown] preferences.md exists but uses an unrecognized format — skipping.");
+    console.warn("[parsePreferencesMarkdown] PREFERENCES.md exists but uses an unrecognized format — skipping.");
   }
   return null;
 }
@@ -353,6 +352,9 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
     service_tier: override.service_tier ?? base.service_tier,
     forensics_dedup: override.forensics_dedup ?? base.forensics_dedup,
     show_token_cost: override.show_token_cost ?? base.show_token_cost,
+    experimental: (base.experimental || override.experimental)
+      ? { ...(base.experimental ?? {}), ...(override.experimental ?? {}) }
+      : undefined,
   };
 }
 
@@ -499,7 +501,7 @@ export function resolvePreDispatchHooks(): PreDispatchHookConfig[] {
  * Resolve the effective git isolation mode from preferences.
  * Returns "none" (default), "worktree", or "branch".
  *
- * Default is "none" so GSD works out of the box without preferences.md.
+ * Default is "none" so GSD works out of the box without PREFERENCES.md.
  * Worktree isolation requires explicit opt-in because it depends on git
  * branch infrastructure that must be set up before use.
  */