@opengsd/gsd-pi 1.2.0-dev.fbdca60b → 1.3.0-dev.65546769

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,9 +19,11 @@ import {
   loadEffectiveGSDPreferences,
   normalizePreferencesShape,
   resolveAllSkillReferences,
+  clearGSDPreferencesCache,
 } from "./preferences.js";
 import { loadFile, saveFile, splitFrontmatter, parseFrontmatterMap } from "./files.js";
 import { runClaudeImportFlow } from "./claude-import.js";
+import { clearSessionModelOverride } from "./session-model-override.js";
 
 const DEFAULT_WIDGET_MODE = "small";
 const WIDGET_MODE_OPTIONS = [DEFAULT_WIDGET_MODE, "full", "min", "off"] as const;
@@ -297,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);
@@ -321,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");
@@ -1676,8 +1680,15 @@ 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.
+    const models = prefs.models;
+    if (models && typeof models === "object" && Object.keys(models as object).length > 0) {
+      const sessionId = ctx.sessionManager?.getSessionId?.();
+      if (sessionId) clearSessionModelOverride(sessionId);
+    }
     await ctx.waitForIdle();
     await ctx.reload();
     if (opts?.notifyOnSave !== false) {
@@ -1803,6 +1814,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");
@@ -1859,6 +1871,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-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/compat/compat-marker.ts

@@ -0,0 +1,210 @@
+// Project/App: gsd-pi
+// File Purpose: gsd-core ↔ gsd-pi compatibility marker (`.gsd/.compat.json`).
+//
+// Records per-projection content hashes so the ADR-017 reconcile pipeline can
+// distinguish gsd-pi's own writes (expected) from external edits made by gsd-core
+// (drift to import). gsd-core is oblivious to this file and ignores it.
+
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** Current marker schema version. Bump on breaking format changes + migrate. */
+export const COMPAT_MARKER_SCHEMA = 2;
+
+/**
+ * Which `.planning/` layout a project uses. Captured on first read so the
+ * round-trip writer recreates the same structure gsd-core wrote. Priority
+ * matches migrate/transformer.ts transformToGSD.
+ */
+export type PlanningLayout = "flat-phases" | "multi-milestone" | "legacy-milestone-dir";
+
+/**
+ * `.planning/` projection tracking. `projections` are modeled files (roadmap,
+ * plans, summaries, state) that get re-imported on drift; `passthrough` are
+ * un-modeled docs (DISCUSSION-LOG, PATTERNS, REVIEWS, codebase/) that get sha-
+ * refreshed only — content never re-rendered.
+ */
+export interface PlanningMarker {
+  active: boolean;
+  layout: PlanningLayout | null;
+  projections: Record<string, ProjectionEntry>;
+  passthrough: Record<string, ProjectionEntry>;
+}
+
+/**
+ * Per-file projection entry. `sha` is a normalized-content SHA-256; `entities`
+ * is the list of DB entity ids (milestone/slice/task) that the file projects,
+ * so repair can scope re-import rather than re-importing the whole tree.
+ */
+export interface ProjectionEntry {
+  sha: string;
+  entities: string[];
+}
+
+export interface CompatMarker {
+  schema: number;
+  lastWriter: "gsd-pi";
+  lastProjectedAt: string;
+  projections: Record<string, ProjectionEntry>;
+  /** Optional: `.planning/` layout tracking for gsd-core parity. */
+  planning?: PlanningMarker;
+  piVersion: string;
+}
+
+/** Marker returned when no marker exists yet (fresh project, first gsd-pi run). */
+export const EMPTY_MARKER: CompatMarker = {
+  schema: COMPAT_MARKER_SCHEMA,
+  lastWriter: "gsd-pi",
+  lastProjectedAt: "",
+  projections: {},
+  planning: { active: false, layout: null, projections: {}, passthrough: {} },
+  piVersion: "",
+};
+
+export function compatMarkerPath(basePath: string): string {
+  return join(basePath, ".gsd", ".compat.json");
+}
+
+/**
+ * Normalize markdown content before hashing so cosmetic differences (trailing
+ * whitespace, CRLF) don't produce false-positive drift. Conservative: only
+ * transforms that are provably round-trippable through gsd-pi's projection.
+ */
+export function normalizeForHash(content: string): string {
+  return content.replace(/\r\n/g, "\n").replace(/[ \t]+\n/g, "\n");
+}
+
+export function computeProjectionSha(content: string): string {
+  return createHash("sha256").update(normalizeForHash(content)).digest("hex").slice(0, 16);
+}
+
+/**
+ * Read & validate the marker. A missing marker → EMPTY_MARKER (treat every
+ * projection as external on next reconcile). A malformed marker is quarantined
+ * to `.compat.json.bad-<ts>` (never overwrite without backup) then returns
+ * EMPTY_MARKER. A schema-mismatch returns EMPTY_MARKER (forward-compat: refuse
+ * to act on a future format we don't understand).
+ */
+export function readCompatMarker(basePath: string): CompatMarker {
+  const path = compatMarkerPath(basePath);
+  if (!existsSync(path)) return emptyMarker();
+
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    return emptyMarker();
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    quarantine(basePath, raw);
+    return emptyMarker();
+  }
+
+  if (!isValidMarker(parsed)) {
+    quarantine(basePath, raw);
+    return emptyMarker();
+  }
+  // Promote older markers by defaulting absent fields. Schema 1 → 2 only adds
+  // the optional `planning` field; treat its absence as planning-inactive so
+  // existing PR #802 users upgrade transparently. (A future schema 3 would
+  // need an explicit migration here; for now anything that passes isValidMarker
+  // is safe to read.)
+  if (!parsed.planning) {
+    parsed.planning = { active: false, layout: null, projections: {}, passthrough: {} };
+  }
+  return parsed;
+}
+
+/**
+ * Fresh deep copy of EMPTY_MARKER. Callers mutate the returned `projections`
+ * object (e.g. repair refreshes an entry), so a shallow copy would share the
+ * reference and pollute the module constant across calls. Always deep-copy.
+ */
+function emptyMarker(): CompatMarker {
+  return {
+    schema: EMPTY_MARKER.schema,
+    lastWriter: EMPTY_MARKER.lastWriter,
+    lastProjectedAt: EMPTY_MARKER.lastProjectedAt,
+    projections: {},
+    planning: { active: false, layout: null, projections: {}, passthrough: {} },
+    piVersion: EMPTY_MARKER.piVersion,
+  };
+}
+
+/**
+ * Write the marker atomically (write-temp then rename) so a crash mid-write
+ * can't leave a half-written file that next startup would quarantine.
+ */
+export function writeCompatMarker(basePath: string, marker: CompatMarker): void {
+  const path = compatMarkerPath(basePath);
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp-${process.pid}`;
+  writeFileSync(tmp, JSON.stringify(marker, null, 2), "utf-8");
+  renameSync(tmp, path);
+}
+
+function quarantine(basePath: string, raw: string): void {
+  const path = compatMarkerPath(basePath);
+  const badPath = `${path}.bad-${Date.now()}`;
+  try {
+    mkdirSync(dirname(badPath), { recursive: true });
+    try {
+      renameSync(path, badPath);
+    } catch {
+      writeFileSync(badPath, raw, "utf-8");
+      unlinkSync(path);
+    }
+  } catch {
+    // Best-effort: if we can't quarantine, leave the original in place — next
+    // read will quarantine. Never throw out of marker I/O.
+  }
+}
+
+function isValidProjectionEntry(x: unknown): x is ProjectionEntry {
+  if (typeof x !== "object" || x === null) return false;
+  const e = x as Record<string, unknown>;
+  if (typeof e.sha !== "string") return false;
+  if (!Array.isArray(e.entities) || !e.entities.every((s) => typeof s === "string")) return false;
+  return true;
+}
+
+function isValidProjectionMap(x: unknown): boolean {
+  if (typeof x !== "object" || x === null) return false;
+  for (const v of Object.values(x as Record<string, unknown>)) {
+    if (!isValidProjectionEntry(v)) return false;
+  }
+  return true;
+}
+
+function isValidPlanningMarker(x: unknown): x is PlanningMarker {
+  if (typeof x !== "object" || x === null) return false;
+  const p = x as Record<string, unknown>;
+  if (typeof p.active !== "boolean") return false;
+  if (
+    p.layout !== null &&
+    !["flat-phases", "multi-milestone", "legacy-milestone-dir"].includes(p.layout as string)
+  ) {
+    return false;
+  }
+  if (!isValidProjectionMap(p.projections)) return false;
+  if (!isValidProjectionMap(p.passthrough)) return false;
+  return true;
+}
+
+function isValidMarker(x: unknown): x is CompatMarker {
+  if (typeof x !== "object" || x === null) return false;
+  const m = x as Record<string, unknown>;
+  if (m.lastWriter !== "gsd-pi") return false;
+  if (typeof m.schema !== "number") return false;
+  if (typeof m.lastProjectedAt !== "string") return false;
+  if (typeof m.piVersion !== "string") return false;
+  if (!isValidProjectionMap(m.projections)) return false;
+  // planning is optional; when present, must validate.
+  if (m.planning !== undefined && !isValidPlanningMarker(m.planning)) return false;
+  return true;
+}

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

@@ -0,0 +1,12 @@
+// Project/App: gsd-pi
+// File Purpose: Public exports for the gsd-core compat module.
+export {
+  COMPAT_MARKER_SCHEMA,
+  EMPTY_MARKER,
+  compatMarkerPath,
+  computeProjectionSha,
+  normalizeForHash,
+  readCompatMarker,
+  writeCompatMarker,
+} from "./compat-marker.js";
+export type { CompatMarker, PlanningLayout, PlanningMarker, ProjectionEntry } from "./compat-marker.js";