@opengsd/gsd-pi 1.3.0 → 1.4.0

package/dist/resources/extensions/gsd/commands-handlers.js

@@ -158,6 +158,65 @@ export function parseDoctorArgs(args) {
 export function isDoctorHealActionable(issue) {
     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) {
+    try {
+        const { readCompatMarker, computeProjectionSha } = await import("./compat/compat-marker.js");
+        const marker = readCompatMarker(basePath);
+        const countDrifted = (entries, root) => {
+            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 = [];
+        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, ctx, pi) {
     const { jsonMode, dryRun, fixFlag, includeBuild, includeTests, mode, requestedScope } = parseDoctorArgs(args);
     const scope = await selectDoctorScope(projectRoot(), requestedScope);
@@ -181,7 +240,12 @@ export async function handleDoctor(args, ctx, pi) {
         maxIssues: mode === "audit" ? 50 : 12,
         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, {
             scope: effectiveScope,
@@ -362,6 +426,8 @@ export async function handleKnowledge(args, ctx) {
     }
     const type = typeArg;
     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/dist/resources/extensions/gsd/commands-maintenance.js

@@ -699,11 +699,88 @@ export async function rebuildMarkdownProjectionsFromDb(basePath) {
         quarantinedPaths: quarantined,
     };
 }
+/**
+ * `/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, basePath, args = "") {
+    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 = ["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;
+            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;
+                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.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, basePath, args = "") {

package/dist/resources/extensions/gsd/commands-prefs-wizard.js

@@ -8,7 +8,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { getGlobalGSDPreferencesPath, getLegacyGlobalGSDPreferencesPath, getProjectGSDPreferencesPath, loadGlobalGSDPreferences, loadProjectGSDPreferences, loadEffectiveGSDPreferences, normalizePreferencesShape, resolveAllSkillReferences, } from "./preferences.js";
+import { getGlobalGSDPreferencesPath, getLegacyGlobalGSDPreferencesPath, getProjectGSDPreferencesPath, loadGlobalGSDPreferences, loadProjectGSDPreferences, 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";
@@ -246,6 +246,7 @@ export async function handleImportClaude(ctx, scope) {
                 body = preserved;
         }
         await saveFile(path, `---\n${frontmatter}---${body}`);
+        clearGSDPreferencesCache();
     };
     await runClaudeImportFlow(ctx, scope, readPrefs, writePrefs);
 }
@@ -265,6 +266,7 @@ export async function handlePrefsMode(ctx, scope) {
     }
     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");
@@ -1162,7 +1164,7 @@ async function configureContextCodebase(ctx, prefs) {
         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")
@@ -1627,6 +1629,7 @@ export async function writePreferencesFile(path, prefs, ctx, opts) {
     }
     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;
@@ -1668,19 +1671,25 @@ export function serializePreferencesToFrontmatter(prefs) {
                     const entries = Object.entries(item);
                     if (entries.length > 0) {
                         const [firstKey, firstVal] = entries[0];
-                        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)}`);
-                                }
+                        if (Array.isArray(firstVal)) {
+                            lines.push(`${prefix}  - ${firstKey}:`);
+                            for (const arrItem of firstVal) {
+                                lines.push(`${prefix}      - ${yamlSafeString(arrItem)}`);
                             }
-                            else {
-                                lines.push(`${prefix}    ${k}: ${yamlSafeString(v)}`);
+                        }
+                        else if (typeof firstVal === "object" && firstVal !== null) {
+                            lines.push(`${prefix}  - ${firstKey}:`);
+                            for (const [k, v] of Object.entries(firstVal)) {
+                                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];
+                            serializeValue(k, v, indent + 2);
+                        }
                     }
                 }
                 else {
@@ -1750,6 +1759,7 @@ export async function ensurePreferencesFile(path, ctx, scope) {
             return;
         }
         await saveFile(path, template);
+        clearGSDPreferencesCache();
         ctx.ui.notify(`Created ${scope} GSD skill preferences at ${path}`, "info");
     }
     else {
@@ -1800,6 +1810,7 @@ export async function handleLanguage(args, ctx) {
     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/dist/resources/extensions/gsd/commands-usage.js

@@ -83,7 +83,7 @@ function formatThresholdLines() {
     }
     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/dist/resources/extensions/gsd/commands-verdict.js

@@ -1,9 +1,8 @@
 // Project/App: gsd-pi
 // File Purpose: Handles manual milestone validation verdict overrides.
 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";
@@ -89,17 +88,24 @@ export function parseValidationFile(content) {
     };
 }
 async function loadExistingValidation(basePath, milestoneId) {
+    // 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);
     const assessment = getLatestAssessmentByScope(milestoneId, "milestone-validation");

package/dist/resources/extensions/gsd/commands-worktree.js

@@ -12,9 +12,9 @@ import { inferCommitType } from "./git-service.js";
 import { autoCommitCurrentBranch } from "./worktree.js";
 import { GSDError, GSD_GIT_ERROR } from "./errors.js";
 // ─── Status helper ─────────────────────────────────────────────────────────
-function getStatus(basePath, name, wtPath) {
-    const diff = diffWorktreeAll(basePath, name);
-    const numstat = diffWorktreeNumstat(basePath, name);
+function getStatus(basePath, name, wtPath, mainBranch) {
+    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;
@@ -31,8 +31,7 @@ function getStatus(basePath, name, wtPath) {
     }
     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
@@ -88,7 +87,8 @@ export function formatCleanKeepReason(status) {
 async function handleList(ctx) {
     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");
 }
 // ─── Subcommand: merge ──────────────────────────────────────────────────────
@@ -117,7 +117,8 @@ async function handleMerge(args, ctx) {
         ctx.ui.notify(`Worktree "${target}" not found.\n\nAvailable: ${available}`, "error");
         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 });
@@ -144,7 +145,6 @@ async function handleMerge(args, ctx) {
         }
     }
     const commitType = inferCommitType(target);
-    const mainBranch = nativeDetectMainBranch(basePath);
     const commitMessage = `${commitType}: merge worktree ${target}\n\nGSD-Worktree: ${target}`;
     try {
         mergeWorktreeToMain(basePath, target, commitMessage);
@@ -191,8 +191,9 @@ async function handleClean(ctx) {
     }
     const removed = [];
     const kept = [];
+    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 });
@@ -238,7 +239,8 @@ async function handleRemove(args, ctx) {
         ctx.ui.notify(`Worktree "${name}" not found.\n\nAvailable: ${available}`, "error");
         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([
             `Worktree "${name}" has pending changes (${formatCleanKeepReason(status)}).`,

package/dist/resources/extensions/gsd/compat/compat-marker.js

@@ -0,0 +1,172 @@
+// 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;
+/** Marker returned when no marker exists yet (fresh project, first gsd-pi run). */
+export const EMPTY_MARKER = {
+    schema: COMPAT_MARKER_SCHEMA,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "",
+    projections: {},
+    planning: { active: false, layout: null, projections: {}, passthrough: {} },
+    piVersion: "",
+};
+export function compatMarkerPath(basePath) {
+    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) {
+    return content.replace(/\r\n/g, "\n").replace(/[ \t]+\n/g, "\n");
+}
+export function computeProjectionSha(content) {
+    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) {
+    const path = compatMarkerPath(basePath);
+    if (!existsSync(path))
+        return emptyMarker();
+    let raw;
+    try {
+        raw = readFileSync(path, "utf-8");
+    }
+    catch {
+        return emptyMarker();
+    }
+    let parsed;
+    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() {
+    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, marker) {
+    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, raw) {
+    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) {
+    if (typeof x !== "object" || x === null)
+        return false;
+    const e = x;
+    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) {
+    if (typeof x !== "object" || x === null)
+        return false;
+    for (const v of Object.values(x)) {
+        if (!isValidProjectionEntry(v))
+            return false;
+    }
+    return true;
+}
+function isValidPlanningMarker(x) {
+    if (typeof x !== "object" || x === null)
+        return false;
+    const p = x;
+    if (typeof p.active !== "boolean")
+        return false;
+    if (p.layout !== null &&
+        !["flat-phases", "multi-milestone", "legacy-milestone-dir"].includes(p.layout)) {
+        return false;
+    }
+    if (!isValidProjectionMap(p.projections))
+        return false;
+    if (!isValidProjectionMap(p.passthrough))
+        return false;
+    return true;
+}
+function isValidMarker(x) {
+    if (typeof x !== "object" || x === null)
+        return false;
+    const m = x;
+    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/dist/resources/extensions/gsd/compat/index.js

@@ -0,0 +1,3 @@
+// 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";