@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

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

@@ -180,6 +180,73 @@ export function isDoctorHealActionable(issue: { fixable: boolean; severity: stri
   return issue.fixable && issue.severity !== "info";
 }
 
+/**
+ * Compat-health line for `/gsd doctor`. Reports the gsd-core compat marker's
+ * presence and the count of projection files whose on-disk sha has drifted
+ * from the recorded baseline. Returns "" if the marker module is unavailable
+ * (defensive — doctor must never fail because of compat reporting).
+ *
+ * Exported for unit testing.
+ */
+export async function formatCompatHealthLine(basePath: string): Promise<string> {
+  try {
+    const { readCompatMarker, computeProjectionSha } = await import("./compat/compat-marker.js");
+    const marker = readCompatMarker(basePath);
+
+    const countDrifted = (
+      entries: Record<string, { sha: string }>,
+      root: string,
+    ): number => {
+      let drifted = 0;
+      for (const [rel, entry] of Object.entries(entries)) {
+        const abs = join(basePath, root, rel);
+        if (!existsSync(abs)) continue;
+        if (computeProjectionSha(readFileSync(abs, "utf-8")) !== entry.sha) drifted++;
+      }
+      return drifted;
+    };
+
+    const lines: string[] = [];
+    const gsdEntryCount = Object.keys(marker.projections).length;
+    const planningActive = marker.planning?.active ?? false;
+    const planningEntryCount = planningActive
+      ? Object.keys(marker.planning!.projections).length +
+        Object.keys(marker.planning!.passthrough).length
+      : 0;
+
+    if (gsdEntryCount === 0 && !planningActive) {
+      return "  Compat health:      no baseline (run /gsd sync to establish)";
+    }
+
+    if (gsdEntryCount === 0) {
+      lines.push("  Compat health (.gsd):    no baseline (run /gsd sync to establish)");
+    } else {
+      const gsdDrifted = countDrifted(marker.projections, ".gsd");
+      lines.push(
+        `  Compat health (.gsd):    ${gsdDrifted === 0 ? "OK" : `${gsdDrifted} file(s) drifted — run /gsd sync`}`,
+      );
+    }
+
+    if (planningActive) {
+      if (planningEntryCount === 0) {
+        lines.push("  Compat health (.planning): no baseline (run /gsd sync to establish)");
+      } else {
+        const planningDrifted =
+          countDrifted(marker.planning!.projections, ".planning") +
+          countDrifted(marker.planning!.passthrough, ".planning");
+        lines.push(
+          `  Compat health (.planning): ${planningDrifted === 0 ? "OK" : `${planningDrifted} file(s) drifted — run /gsd sync`}`,
+        );
+      }
+    } else {
+      lines.push(`  Compat health (.planning): not active`);
+    }
+    return lines.join("\n");
+  } catch {
+    return "";
+  }
+}
+
 export async function handleDoctor(args: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
   const { jsonMode, dryRun, fixFlag, includeBuild, includeTests, mode, requestedScope } = parseDoctorArgs(args);
   const scope = await selectDoctorScope(projectRoot(), requestedScope);
@@ -206,7 +273,13 @@ export async function handleDoctor(args: string, ctx: ExtensionCommandContext, p
     title: mode === "audit" ? "GSD doctor audit." : mode === "heal" ? "GSD doctor heal prep." : undefined,
   });
 
-  ctx.ui.notify(reportText, report.ok ? "info" : "warning");
+  // Compat health: marker presence + drift vs current projections. Appended to
+  // the formatted report so it surfaces in every doctor run without touching
+  // the doctor report internals.
+  const compatLine = await formatCompatHealthLine(projectRoot());
+  const fullReport = compatLine ? `${reportText}\n${compatLine}` : reportText;
+
+  ctx.ui.notify(fullReport, report.ok ? "info" : "warning");
 
   if (mode === "heal") {
     const unresolved = filterDoctorIssues(report.issues, {
@@ -426,6 +499,8 @@ export async function handleKnowledge(args: string, ctx: ExtensionCommandContext
 
   const type = typeArg as "rule" | "pattern" | "lesson";
   const basePath = currentDirectoryRoot();
+  const { ensureDbOpen } = await import("./bootstrap/dynamic-tools.js");
+  await ensureDbOpen(basePath);
   const state = await deriveState(basePath);
   const scope = state.activeMilestone?.id
     ? `${state.activeMilestone.id}${state.activeSlice ? `/${state.activeSlice.id}` : ""}`

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

@@ -806,11 +806,107 @@ export async function rebuildMarkdownProjectionsFromDb(
   };
 }
 
+/**
+ * `/gsd sync` — pull in external (gsd-core) markdown edits and re-project.
+ *
+ * Non-destructive cousin of `/gsd recover`: does NOT clear the DB. Runs the
+ * ADR-017 reconcile pipeline (which picks up the external-markdown-edit handler
+ * automatically), then re-projects via renderAllFromDb, then refreshes the
+ * compat marker. Use this when switching from gsd-core mid-session.
+ *
+ * Accepts `--dry-run` to report what would change without writing.
+ */
+export async function handleSync(
+  ctx: ExtensionCommandContext,
+  basePath: string,
+  args = "",
+): Promise<void> {
+  const { isDbAvailable } = await import("./gsd-db.js");
+  const { reconcileBeforeDispatch } = await import("./state-reconciliation/index.js");
+  const { renderAllFromDb } = await import("./markdown-renderer.js");
+  const { writeCompatMarker, readCompatMarker } = await import("./compat/compat-marker.js");
+
+  const dryRun = args.trim() === "--dry-run";
+
+  if (!isDbAvailable()) {
+    ctx.ui.notify("gsd sync: No database open. Run a GSD command first to initialize the DB.", "error");
+    return;
+  }
+
+  const lines: string[] = ["gsd sync: reconciling .gsd/ for cross-tool edits…"];
+
+  try {
+    const result = await reconcileBeforeDispatch(basePath, { dryRun });
+    const repairedExternal = result.repaired.filter((r) => r.kind === "external-markdown-edit");
+    lines.push(
+      `  External .gsd/ edits ${dryRun ? "to import" : "imported"}: ${repairedExternal.length}`,
+    );
+    for (const r of repairedExternal) {
+      const e = r as { kind: "external-markdown-edit"; projectionPath: string };
+      lines.push(`    • ${e.projectionPath}`);
+    }
+    const repairedPlanningExternal = result.repaired.filter((r) => r.kind === "external-planning-edit");
+    if (repairedPlanningExternal.length > 0) {
+      lines.push(
+        `  External .planning/ edits ${dryRun ? "to import" : "imported"}: ${repairedPlanningExternal.length}`,
+      );
+      for (const r of repairedPlanningExternal) {
+        const e = r as { kind: "external-planning-edit"; projectionPath: string; passthrough: boolean };
+        const tag = e.passthrough ? " (passthrough)" : "";
+        lines.push(`    • ${e.projectionPath}${tag}`);
+      }
+    }
+    if (result.blockers.length > 0) {
+      lines.push("", "  ⚠ Blockers:");
+      for (const b of result.blockers) lines.push(`    • ${b}`);
+    }
+
+    if (dryRun) {
+      lines.push("", "  (dry-run: no repairs, projection, or marker writes performed)");
+      ctx.ui.notify(lines.join("\n"), "info");
+      return;
+    }
+
+    const renderResult = await renderAllFromDb(basePath);
+    if (renderResult.errors.length > 0) {
+      lines.push("", "  ⚠ Projection errors:");
+      for (const e of renderResult.errors) lines.push(`    • ${e}`);
+    }
+
+    // Refresh the marker to reflect the freshly re-projected state. The
+    // planning hook inside renderAllFromDb already recorded per-file SHAs
+    // into marker.planning.projections; we read back the fully-populated
+    // marker here so the timestamp is the last thing written.
+    const marker = readCompatMarker(basePath);
+    marker.lastWriter = "gsd-pi";
+    marker.lastProjectedAt = new Date().toISOString();
+    writeCompatMarker(basePath, marker);
+    const planningShaCnt = Object.keys(marker.planning?.projections ?? {}).length;
+    const planningNote = planningShaCnt > 0
+      ? ` + ${planningShaCnt} .planning/ SHA${planningShaCnt !== 1 ? "s" : ""}`
+      : "";
+
+    const state = await deriveState(basePath);
+    lines.push(
+      "",
+      `  Phase:  ${state.phase}`,
+      `  Marker: .gsd/.compat.json refreshed${planningNote}`,
+    );
+    if (state.activeMilestone) {
+      lines.push(`  Active: ${state.activeMilestone.id}: ${state.activeMilestone.title}`);
+    }
+
+    ctx.ui.notify(lines.join("\n"), "info");
+  } catch (err) {
+    ctx.ui.notify(`gsd sync failed: ${(err as Error).message}`, "error");
+  }
+}
+
 /**
  * `gsd rebuild markdown` — Re-render markdown projections from the authoritative DB.
  *
- * This is the DB-first realignment command. It does not import markdown into
- * the DB. Completion SUMMARY files that contradict open DB rows are preserved
+ * This is the DB-first realignment command. It does not import markdown into the
+ * DB. Completion SUMMARY files that contradict open DB rows are preserved
  * under `.gsd/quarantine/projections/` before DB projections are rendered.
  */
 export async function handleRebuild(ctx: ExtensionCommandContext, basePath: string, args = ""): Promise<void> {

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

@@ -19,6 +19,7 @@ import {
   loadEffectiveGSDPreferences,
   normalizePreferencesShape,
   resolveAllSkillReferences,
+  clearGSDPreferencesCache,
 } from "./preferences.js";
 import { loadFile, saveFile, splitFrontmatter, parseFrontmatterMap } from "./files.js";
 import { runClaudeImportFlow } from "./claude-import.js";
@@ -298,6 +299,7 @@ export async function handleImportClaude(ctx: ExtensionCommandContext, scope: "g
       if (preserved) body = preserved;
     }
     await saveFile(path, `---\n${frontmatter}---${body}`);
+    clearGSDPreferencesCache();
   };
 
   await runClaudeImportFlow(ctx, scope, readPrefs, writePrefs);
@@ -322,6 +324,7 @@ export async function handlePrefsMode(ctx: ExtensionCommandContext, scope: "glob
 
   const content = `---\n${frontmatter}---${body}`;
   await saveFile(path, content);
+  clearGSDPreferencesCache();
   await ctx.waitForIdle();
   await ctx.reload();
   ctx.ui.notify(`Saved ${scope} preferences to ${path}`, "info");
@@ -548,6 +551,17 @@ export function buildCategorySummaries(prefs: Record<string, unknown>): Record<s
     if (parts.length > 0) integrationsSummary = parts.join(", ");
   }
 
+  // Workspace (parent-workspace multi-repo)
+  const workspace = prefs.workspace as Record<string, unknown> | undefined;
+  const workspaceRepos = workspace?.repositories as Record<string, unknown> | undefined;
+  let workspaceSummary = "(single-repo)";
+  {
+    const parts: string[] = [];
+    if (workspace?.mode) parts.push(`mode: ${workspace.mode}`);
+    if (workspaceRepos && Object.keys(workspaceRepos).length > 0) parts.push(`${Object.keys(workspaceRepos).length} repo(s)`);
+    if (parts.length > 0) workspaceSummary = parts.join(", ");
+  }
+
   return {
     mode: modeSummary,
     models: modelsSummary,
@@ -565,6 +579,7 @@ export function buildCategorySummaries(prefs: Record<string, unknown>): Record<s
     hooks: hooksSummary,
     uok: uokSummary,
     integrations: integrationsSummary,
+    workspace: workspaceSummary,
   };
 }
 
@@ -755,7 +770,10 @@ async function configureDynamicRouting(ctx: ExtensionCommandContext, prefs: Reco
   const hooks = await promptBoolean(ctx, "Route hook sessions dynamically", dr.hooks, true);
   if (hooks !== undefined) dr.hooks = hooks;
 
-  const flatRate = await promptBoolean(ctx, "Allow dynamic routing for flat-rate providers", dr.allow_flat_rate_providers, false);
+  // Opt-out flag (#1115): routing is allowed for flat-rate providers by
+  // default; only an explicit `false` suppresses it. The default hint reflects
+  // that allow-by-default behavior.
+  const flatRate = await promptBoolean(ctx, "Allow dynamic routing for flat-rate providers", dr.allow_flat_rate_providers, true);
   if (flatRate !== undefined) dr.allow_flat_rate_providers = flatRate;
 
   // tier_models.light / standard / heavy — optional model IDs
@@ -965,6 +983,114 @@ async function configureSkills(ctx: ExtensionCommandContext, prefs: Record<strin
   applyNumber(prefs, "skill_staleness_days", staleness);
 }
 
+async function configureWorkspace(ctx: ExtensionCommandContext, prefs: Record<string, unknown>): Promise<void> {
+  type RepoConfig = { path: string; role?: string; verification?: string[]; commit_policy?: "auto" | "skip" };
+  let workspace = (prefs.workspace ?? {}) as { mode?: "project" | "parent"; repositories?: Record<string, RepoConfig> };
+
+  // Mode
+  const mode = await promptEnum(ctx, "Workspace mode", workspace.mode, ["project", "parent"]);
+  if (mode !== undefined) workspace = { ...workspace, mode: mode as "project" | "parent" };
+
+  if (workspace.mode !== "parent") {
+    // Single-repo mode: drop any declared repositories and persist.
+    if (workspace.repositories && Object.keys(workspace.repositories).length > 0) {
+      const clear = await promptBoolean(ctx, "Clear declared repositories (switch to single-repo)?", false, false);
+      if (clear) workspace = { mode: workspace.mode };
+    }
+    persistWorkspace(prefs, workspace);
+    return;
+  }
+
+  // Parent mode — edit child repositories via a sub-menu.
+  let repositories = { ...(workspace.repositories ?? {}) };
+  while (true) {
+    const ids = Object.keys(repositories).sort();
+    const summary = ids.length === 0 ? "(no repositories — parent mode requires at least one)" : `${ids.length} repo(s)`;
+    const listLabels = ids.map((id) => {
+      const r = repositories[id];
+      const roleStr = r.role ? ` — ${r.role}` : "";
+      const policyStr = r.commit_policy === "skip" ? " [skip]" : "";
+      return `${id} (${r.path})${roleStr}${policyStr}`;
+    });
+    const choice = await ctx.ui.select(`Declared repositories — ${summary}`, [...listLabels, "Add repository", "Done"]);
+    const pick = typeof choice === "string" ? choice : "";
+    if (!pick || pick === "Done") break;
+    if (pick === "Add repository") {
+      const idInput = await ctx.ui.input("Repository id (letters, digits, . _ -; 'project' is reserved):", "");
+      const id = typeof idInput === "string" ? idInput.trim() : "";
+      if (!id || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id)) {
+        ctx.ui.notify("Invalid repository id — must match ^[A-Za-z0-9][A-Za-z0-9._-]*$ and cannot be 'project'.", "warning");
+        continue;
+      }
+      if (id === "project" || repositories[id]) {
+        ctx.ui.notify(`Repository id "${id}" is reserved or already declared.`, "warning");
+        continue;
+      }
+      const pathInput = await ctx.ui.input("Repository path (relative to project root, e.g. frontend):", "");
+      const path = typeof pathInput === "string" ? pathInput.trim() : "";
+      if (!path) { ctx.ui.notify("Repository path is required.", "warning"); continue; }
+      const repo: RepoConfig = { path };
+      const roleInput = await ctx.ui.input("Role/label (optional):", "");
+      if (typeof roleInput === "string" && roleInput.trim()) repo.role = roleInput.trim();
+      const verifyInput = await ctx.ui.input("Verification commands (comma- or newline-separated, optional):", "");
+      if (typeof verifyInput === "string" && verifyInput.trim()) {
+        const cmds = parseStringList(verifyInput);
+        if (cmds.length > 0) repo.verification = cmds;
+      }
+      const policy = await promptEnum(ctx, "Commit policy", undefined, ["auto", "skip"]);
+      if (policy === "skip") repo.commit_policy = "skip";
+      repositories[id] = repo;
+    } else {
+      // Edit/delete an existing repo (the first token is the id).
+      const id = pick.split(" ")[0];
+      if (!repositories[id]) continue;
+      const editChoice = await ctx.ui.select(
+        `Repository ${id}`,
+        ["Edit path", "Edit role", "Edit verification", "Edit commit policy", "Delete repository", "Cancel"],
+      );
+      const ec = typeof editChoice === "string" ? editChoice : "";
+      if (!ec || ec === "Cancel") continue;
+      if (ec === "Delete repository") {
+        delete repositories[id];
+      } else if (ec === "Edit path") {
+        const v = await ctx.ui.input("Repository path:", repositories[id].path);
+        if (typeof v === "string" && v.trim()) repositories[id] = { ...repositories[id], path: v.trim() };
+      } else if (ec === "Edit role") {
+        const v = await ctx.ui.input("Role/label (blank to clear):", repositories[id].role ?? "");
+        if (typeof v === "string" && v.trim()) repositories[id] = { ...repositories[id], role: v.trim() };
+        else if (typeof v === "string") { const { role, ...rest } = repositories[id]; void role; repositories[id] = rest; }
+      } else if (ec === "Edit verification") {
+        const v = await ctx.ui.input("Verification commands (blank to clear):", (repositories[id].verification ?? []).join(", "));
+        if (typeof v === "string" && v.trim()) {
+          const cmds = parseStringList(v);
+          if (cmds.length > 0) repositories[id] = { ...repositories[id], verification: cmds };
+        } else if (typeof v === "string") {
+          const { verification, ...rest } = repositories[id]; void verification; repositories[id] = rest;
+        }
+      } else if (ec === "Edit commit policy") {
+        const policy = await promptEnum(ctx, "Commit policy", repositories[id].commit_policy, ["auto", "skip"]);
+        if (policy === "skip") repositories[id] = { ...repositories[id], commit_policy: "skip" };
+        else { const { commit_policy, ...rest } = repositories[id]; void commit_policy; repositories[id] = rest; }
+      }
+    }
+  }
+
+  if (Object.keys(repositories).length === 0) {
+    ctx.ui.notify("Parent mode requires at least one repository — mode not saved.", "warning");
+    return;
+  }
+  persistWorkspace(prefs, { mode: "parent", repositories });
+}
+
+/** Persist the workspace config onto prefs, dropping it entirely when empty. */
+function persistWorkspace(prefs: Record<string, unknown>, workspace: { mode?: string; repositories?: Record<string, unknown> }): void {
+  if (!workspace.mode && (!workspace.repositories || Object.keys(workspace.repositories).length === 0)) {
+    delete prefs.workspace;
+    return;
+  }
+  prefs.workspace = workspace;
+}
+
 async function configureSkillRules(ctx: ExtensionCommandContext, prefs: Record<string, unknown>): Promise<void> {
   type Rule = { when: string; use?: string[]; prefer?: string[]; avoid?: string[] };
   let rules: Rule[] = Array.isArray(prefs.skill_rules) ? [...prefs.skill_rules as Rule[]] : [];
@@ -1173,6 +1299,14 @@ async function configureVerification(ctx: ExtensionCommandContext, prefs: Record
   const maxRetries = await promptInteger(ctx, "Verification max retries", prefs.verification_max_retries, "2");
   applyNumber(prefs, "verification_max_retries", maxRetries);
 
+  const perUnitCap = await promptNumber(
+    ctx,
+    "Per-unit cost cap (USD; retry cost ceiling, blank = clear to default)",
+    prefs.per_unit_cost_cap_usd,
+    "5.0",
+  );
+  applyNumber(prefs, "per_unit_cost_cap_usd", perUnitCap);
+
   const ev = await promptBoolean(ctx, "Enhanced verification (master toggle)", prefs.enhanced_verification, true);
   if (ev !== undefined) prefs.enhanced_verification = ev;
   const evPre = await promptBoolean(ctx, "Enhanced verification — pre-execution checks", prefs.enhanced_verification_pre, true);
@@ -1225,7 +1359,7 @@ async function configureContextCodebase(ctx: ExtensionCommandContext, prefs: Rec
   const maskTurns = await promptInteger(ctx, "Observation mask turns (1–50)", cm.observation_mask_turns, "8");
   if (maskTurns !== undefined && maskTurns !== "clear") cm.observation_mask_turns = maskTurns;
   else if (maskTurns === "clear") delete cm.observation_mask_turns;
-  const thresh = await promptNumber(ctx, "Compaction threshold percent (0.5–0.95)", cm.compaction_threshold_percent, "0.60");
+  const thresh = await promptNumber(ctx, "Soft context warning threshold percent (0.5–0.95)", cm.compaction_threshold_percent, "0.60");
   if (thresh !== undefined && thresh !== "clear") cm.compaction_threshold_percent = thresh;
   else if (thresh === "clear") delete cm.compaction_threshold_percent;
   const toolMax = await promptInteger(ctx, "Tool result max chars (200–10000)", cm.tool_result_max_chars, "800");
@@ -1618,6 +1752,7 @@ export async function handlePrefsWizard(
       `Hooks           ${summaries.hooks}`,
       `UoK             ${summaries.uok}`,
       `Integrations    ${summaries.integrations}`,
+      `Workspace       ${summaries.workspace}`,
       `Advanced        ${summaries.advanced}`,
       `── Save & Exit ──`,
     ];
@@ -1641,6 +1776,7 @@ export async function handlePrefsWizard(
     else if (choice.startsWith("Hooks"))         await configureHooks(ctx, prefs);
     else if (choice.startsWith("UoK"))           await configureUoK(ctx, prefs);
     else if (choice.startsWith("Integrations"))  await configureIntegrations(ctx, prefs);
+    else if (choice.startsWith("Workspace"))     await configureWorkspace(ctx, prefs);
     else if (choice.startsWith("Advanced"))      await configureAdvanced(ctx, prefs);
   }
 
@@ -1677,6 +1813,7 @@ export async function writePreferencesFile(
 
   const content = `---\n${frontmatter}---${body}`;
   await saveFile(path, content);
+  clearGSDPreferencesCache();
 
   if (ctx) {
     // Per-phase model prefs must beat an earlier /gsd model session pin.
@@ -1720,17 +1857,22 @@ export function serializePreferencesToFrontmatter(prefs: Record<string, unknown>
           const entries = Object.entries(item as Record<string, unknown>);
           if (entries.length > 0) {
             const [firstKey, firstVal] = entries[0];
-            lines.push(`${prefix}  - ${firstKey}: ${yamlSafeString(firstVal)}`);
+            if (Array.isArray(firstVal)) {
+              lines.push(`${prefix}  - ${firstKey}:`);
+              for (const arrItem of firstVal) {
+                lines.push(`${prefix}      - ${yamlSafeString(arrItem)}`);
+              }
+            } else if (typeof firstVal === "object" && firstVal !== null) {
+              lines.push(`${prefix}  - ${firstKey}:`);
+              for (const [k, v] of Object.entries(firstVal as Record<string, unknown>)) {
+                serializeValue(k, v, indent + 3);
+              }
+            } else {
+              lines.push(`${prefix}  - ${firstKey}: ${yamlSafeString(firstVal)}`);
+            }
             for (let i = 1; i < entries.length; i++) {
               const [k, v] = entries[i];
-              if (Array.isArray(v)) {
-                lines.push(`${prefix}    ${k}:`);
-                for (const arrItem of v) {
-                  lines.push(`${prefix}      - ${yamlSafeString(arrItem)}`);
-                }
-              } else {
-                lines.push(`${prefix}    ${k}: ${yamlSafeString(v)}`);
-              }
+              serializeValue(k, v, indent + 2);
             }
           }
         } else {
@@ -1771,6 +1913,7 @@ export function serializePreferencesToFrontmatter(prefs: Record<string, unknown>
     "reactive_execution", "gate_evaluation",
     "auto_visualize", "auto_report",
     "verification_commands", "verification_auto_fix", "verification_max_retries",
+    "per_unit_cost_cap_usd",
     "enhanced_verification", "enhanced_verification_pre",
     "enhanced_verification_post", "enhanced_verification_strict",
     "safety_harness",
@@ -1810,6 +1953,7 @@ export async function ensurePreferencesFile(
       return;
     }
     await saveFile(path, template);
+    clearGSDPreferencesCache();
     ctx.ui.notify(`Created ${scope} GSD skill preferences at ${path}`, "info");
   } else {
     ctx.ui.notify(`Using existing ${scope} GSD skill preferences at ${path}`, "info");
@@ -1866,6 +2010,7 @@ export async function handleLanguage(args: string, ctx: ExtensionCommandContext)
   const body = extractBodyAfterFrontmatter(rawContent)
     ?? "\n# GSD Skill Preferences\n\nSee `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation and examples.\n";
   await saveFile(path, `---\n${frontmatter}---${body}`);
+  clearGSDPreferencesCache();
   await ctx.waitForIdle();
   await ctx.reload();
 }

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

@@ -112,7 +112,7 @@ function formatThresholdLines(): string[] {
 
   const compactionThreshold = prefs?.context_management?.compaction_threshold_percent;
   if (typeof compactionThreshold === "number") {
-    lines.push(`Compaction: ${Math.round(compactionThreshold * 100)}%`);
+    lines.push(`Soft context warning: ${Math.round(compactionThreshold * 100)}%`);
   }
 
   return lines;

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

@@ -4,9 +4,8 @@
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
 
 import { loadFile } from "./files.js";
-import { gsdProjectionRoot, resolveMilestoneFile } from "./paths.js";
+import { resolveMilestoneFile } from "./paths.js";
 import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
-import { join } from "node:path";
 import { deriveState } from "./state.js";
 import { executeValidateMilestone } from "./tools/workflow-tool-executors.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
@@ -125,22 +124,24 @@ async function loadExistingValidation(
   basePath: string,
   milestoneId: string,
 ): Promise<ExistingValidation | null> {
+  // Layout-aware lookup against the canonical milestone root first (handles the
+  // worktree case via resolveCanonicalMilestoneRoot), then against the raw
+  // basePath if they differ. See open-gsd/gsd-pi#876.
   const canonicalBase = resolveCanonicalMilestoneRoot(basePath, milestoneId);
-  const canonicalValidationPath = join(
-    gsdProjectionRoot(canonicalBase),
-    "milestones",
-    milestoneId,
-    `${milestoneId}-VALIDATION.md`,
-  );
-  const canonicalContent = await loadFile(canonicalValidationPath);
-  if (canonicalContent) {
-    return { content: canonicalContent, source: canonicalValidationPath };
+  const canonicalValidationPath = resolveMilestoneFile(canonicalBase, milestoneId, "VALIDATION");
+  if (canonicalValidationPath) {
+    const canonicalContent = await loadFile(canonicalValidationPath);
+    if (canonicalContent) {
+      return { content: canonicalContent, source: canonicalValidationPath };
+    }
   }
 
-  const validationPath = resolveMilestoneFile(basePath, milestoneId, "VALIDATION");
-  if (validationPath && validationPath !== canonicalValidationPath) {
-    const content = await loadFile(validationPath);
-    if (content) return { content, source: validationPath };
+  if (basePath !== canonicalBase) {
+    const validationPath = resolveMilestoneFile(basePath, milestoneId, "VALIDATION");
+    if (validationPath && validationPath !== canonicalValidationPath) {
+      const content = await loadFile(validationPath);
+      if (content) return { content, source: validationPath };
+    }
   }
 
   await ensureDbOpen(basePath);

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

@@ -42,9 +42,9 @@ export interface WorktreeStatus {
 
 // ─── Status helper ─────────────────────────────────────────────────────────
 
-function getStatus(basePath: string, name: string, wtPath: string): WorktreeStatus {
-  const diff = diffWorktreeAll(basePath, name);
-  const numstat = diffWorktreeNumstat(basePath, name);
+function getStatus(basePath: string, name: string, wtPath: string, mainBranch: string): WorktreeStatus {
+  const diff = diffWorktreeAll(basePath, name, undefined, mainBranch);
+  const numstat = diffWorktreeNumstat(basePath, name, undefined, mainBranch);
   const filesChanged = diff.added.length + diff.modified.length + diff.removed.length;
   let linesAdded = 0;
   let linesRemoved = 0;
@@ -62,8 +62,7 @@ function getStatus(basePath: string, name: string, wtPath: string): WorktreeStat
 
   let commits = 0;
   try {
-    const main = nativeDetectMainBranch(basePath);
-    commits = nativeCommitCountBetween(basePath, main, worktreeBranchName(name));
+    commits = nativeCommitCountBetween(basePath, mainBranch, worktreeBranchName(name));
   } catch {
     // commit count unavailable → leave at 0
   }
@@ -129,7 +128,8 @@ export function formatCleanKeepReason(status: WorktreeStatus): string {
 async function handleList(ctx: ExtensionCommandContext): Promise<void> {
   const basePath = projectRoot();
   const worktrees = listWorktrees(basePath);
-  const statuses = worktrees.map((wt) => getStatus(basePath, wt.name, wt.path));
+  const mainBranch = worktrees.length > 0 ? nativeDetectMainBranch(basePath) : "";
+  const statuses = worktrees.map((wt) => getStatus(basePath, wt.name, wt.path, mainBranch));
   ctx.ui.notify(formatWorktreeList(statuses), "info");
 }
 
@@ -161,7 +161,8 @@ async function handleMerge(args: string, ctx: ExtensionCommandContext): Promise<
     return;
   }
 
-  const status = getStatus(basePath, target, wt.path);
+  const mainBranch = nativeDetectMainBranch(basePath);
+  const status = getStatus(basePath, target, wt.path, mainBranch);
   if (status.filesChanged === 0 && !status.uncommitted) {
     try {
       removeWorktree(basePath, target, { deleteBranch: true });
@@ -194,7 +195,6 @@ async function handleMerge(args: string, ctx: ExtensionCommandContext): Promise<
   }
 
   const commitType = inferCommitType(target);
-  const mainBranch = nativeDetectMainBranch(basePath);
   const commitMessage = `${commitType}: merge worktree ${target}\n\nGSD-Worktree: ${target}`;
 
   try {
@@ -250,8 +250,9 @@ async function handleClean(ctx: ExtensionCommandContext): Promise<void> {
 
   const removed: string[] = [];
   const kept: string[] = [];
+  const mainBranch = nativeDetectMainBranch(basePath);
   for (const wt of worktrees) {
-    const status = getStatus(basePath, wt.name, wt.path);
+    const status = getStatus(basePath, wt.name, wt.path, mainBranch);
     if (status.filesChanged === 0 && !status.uncommitted) {
       try {
         removeWorktree(basePath, wt.name, { deleteBranch: true });
@@ -298,7 +299,8 @@ async function handleRemove(args: string, ctx: ExtensionCommandContext): Promise
     return;
   }
 
-  const status = getStatus(basePath, name, wt.path);
+  const mainBranch = nativeDetectMainBranch(basePath);
+  const status = getStatus(basePath, name, wt.path, mainBranch);
   if ((status.filesChanged > 0 || status.uncommitted) && !force) {
     ctx.ui.notify(
       [
@@ -313,8 +315,19 @@ async function handleRemove(args: string, ctx: ExtensionCommandContext): Promise
   }
 
   try {
-    removeWorktree(basePath, name, { deleteBranch: true });
-    ctx.ui.notify(`Removed worktree ${name}.`, "info");
+    const removed = removeWorktree(basePath, name, { deleteBranch: true });
+    if (removed) {
+      ctx.ui.notify(`Removed worktree ${name}.`, "info");
+    } else {
+      ctx.ui.notify(
+        [
+          `Worktree removal aborted for "${name}" to preserve uncommitted changes.`,
+          "",
+          "Manual quarantine recovery may be needed before retrying removal.",
+        ].join("\n"),
+        "warning",
+      );
+    }
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     ctx.ui.notify(