gsd-pi 2.81.0 → 2.82.0-dev.ed17d078d

package/dist/resources/extensions/gsd/provider-switch-observer.js

@@ -0,0 +1,146 @@
+// GSD-2 — ADR-005 Phase 3b: surface ProviderSwitchReport from pi-ai.
+//
+// pi-ai builds a ProviderSwitchReport on every cross-provider transform but
+// only logs it to stderr when GSD_VERBOSE=1. This module installs a
+// single-subscriber observer that surfaces non-empty reports through GSD's
+// three usual telemetry surfaces:
+//
+//   1. UOK audit event (category model-policy, type provider-switch) — only
+//      when an auto trace is active.
+//   2. Persistent notification (.gsd/notifications.jsonl, severity warning) —
+//      whenever the GSD basePath is known, so users see the loss in the
+//      dashboard / status surface without GSD_VERBOSE.
+//   3. In-memory counter, exposed via getProviderSwitchStats() so any
+//      caller (dashboard, doctor, tests) can read the rollup.
+import { setProviderSwitchObserver } from "@gsd/pi-ai";
+import { autoSession } from "./auto-runtime-state.js";
+import { appendNotification } from "./notification-store.js";
+import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
+const INTERACTIVE_TRACE_KEY = "interactive";
+let installed = false;
+let totalSwitches = 0;
+const totals = {
+    thinkingBlocksDropped: 0,
+    thinkingBlocksDowngraded: 0,
+    toolCallIdsRemapped: 0,
+    syntheticToolResultsInserted: 0,
+    thoughtSignaturesDropped: 0,
+};
+const byTrace = new Map();
+let lastReport = null;
+let lastAt = null;
+/** Format a one-line summary suitable for a notification message. */
+function summarize(report) {
+    const parts = [];
+    if (report.thinkingBlocksDropped > 0)
+        parts.push(`${report.thinkingBlocksDropped} thinking dropped`);
+    if (report.thinkingBlocksDowngraded > 0)
+        parts.push(`${report.thinkingBlocksDowngraded} thinking downgraded`);
+    if (report.toolCallIdsRemapped > 0)
+        parts.push(`${report.toolCallIdsRemapped} tool ids remapped`);
+    if (report.syntheticToolResultsInserted > 0)
+        parts.push(`${report.syntheticToolResultsInserted} synthetic tool results`);
+    if (report.thoughtSignaturesDropped > 0)
+        parts.push(`${report.thoughtSignaturesDropped} thought signatures dropped`);
+    return `Provider switch ${report.fromApi} → ${report.toApi}: ${parts.join(", ")}`;
+}
+function recordReport(report) {
+    const now = new Date().toISOString();
+    totalSwitches += 1;
+    totals.thinkingBlocksDropped += report.thinkingBlocksDropped;
+    totals.thinkingBlocksDowngraded += report.thinkingBlocksDowngraded;
+    totals.toolCallIdsRemapped += report.toolCallIdsRemapped;
+    totals.syntheticToolResultsInserted += report.syntheticToolResultsInserted;
+    totals.thoughtSignaturesDropped += report.thoughtSignaturesDropped;
+    lastReport = report;
+    lastAt = now;
+    const traceKey = autoSession.currentTraceId ?? INTERACTIVE_TRACE_KEY;
+    const existing = byTrace.get(traceKey);
+    if (existing) {
+        existing.switches += 1;
+        existing.lastReport = report;
+        existing.lastAt = now;
+    }
+    else {
+        byTrace.set(traceKey, { switches: 1, lastReport: report, lastAt: now });
+    }
+}
+function emitAudit(report) {
+    const traceId = autoSession.currentTraceId;
+    const basePath = autoSession.basePath;
+    if (!traceId || !basePath)
+        return;
+    try {
+        emitUokAuditEvent(basePath, buildAuditEnvelope({
+            traceId,
+            category: "model-policy",
+            type: "provider-switch",
+            payload: {
+                fromApi: report.fromApi,
+                toApi: report.toApi,
+                thinkingBlocksDropped: report.thinkingBlocksDropped,
+                thinkingBlocksDowngraded: report.thinkingBlocksDowngraded,
+                toolCallIdsRemapped: report.toolCallIdsRemapped,
+                syntheticToolResultsInserted: report.syntheticToolResultsInserted,
+                thoughtSignaturesDropped: report.thoughtSignaturesDropped,
+            },
+        }));
+    }
+    catch {
+        // Audit emission is best-effort. Counter + notification still fire.
+    }
+}
+function emitNotification(report) {
+    try {
+        appendNotification(summarize(report), "warning", "workflow-logger");
+    }
+    catch {
+        // Notification persistence is best-effort.
+    }
+}
+function handleReport(report) {
+    recordReport(report);
+    emitAudit(report);
+    emitNotification(report);
+}
+/**
+ * Install the pi-ai observer. Idempotent — calling more than once is a no-op
+ * after the first install.
+ */
+export function installProviderSwitchObserver() {
+    if (installed)
+        return;
+    setProviderSwitchObserver(handleReport);
+    installed = true;
+}
+/** Uninstall the observer. Intended for tests. */
+export function uninstallProviderSwitchObserver() {
+    setProviderSwitchObserver(undefined);
+    installed = false;
+}
+/** Read-only snapshot of the in-memory rollup. */
+export function getProviderSwitchStats() {
+    const trace = {};
+    for (const [key, value] of byTrace) {
+        trace[key] = { switches: value.switches, lastReport: { ...value.lastReport }, lastAt: value.lastAt };
+    }
+    return {
+        totalSwitches,
+        totals: { ...totals },
+        byTrace: trace,
+        lastReport: lastReport ? { ...lastReport } : null,
+        lastAt,
+    };
+}
+/** Reset the in-memory rollup. Intended for tests. */
+export function _resetProviderSwitchStats() {
+    totalSwitches = 0;
+    totals.thinkingBlocksDropped = 0;
+    totals.thinkingBlocksDowngraded = 0;
+    totals.toolCallIdsRemapped = 0;
+    totals.syntheticToolResultsInserted = 0;
+    totals.thoughtSignaturesDropped = 0;
+    byTrace.clear();
+    lastReport = null;
+    lastAt = null;
+}

package/dist/resources/extensions/gsd/recovery-classification.js

@@ -1,9 +1,15 @@
 // Project/App: GSD-2
 // File Purpose: ADR-015 Recovery Classification module for runtime failure taxonomy.
 import { classifyError, isTransient } from "./error-classifier.js";
+import { ReconciliationFailedError } from "./state-reconciliation.js";
 export function classifyFailure(input) {
     const message = errorMessage(input.error);
-    const failureKind = input.failureKind ?? inferFailureKind(message);
+    // ADR-017: ReconciliationFailedError is a typed throw from the State
+    // Reconciliation Module. Recognize it by class regardless of caller-supplied
+    // failureKind so the taxonomy stays consistent.
+    const failureKind = input.error instanceof ReconciliationFailedError
+        ? "reconciliation-drift"
+        : input.failureKind ?? inferFailureKind(message);
     switch (failureKind) {
         case "tool-schema":
             return {
@@ -45,6 +51,14 @@ export function classifyFailure(input) {
                 exitReason: "verification-drift",
                 remediation: "Inspect the verification artifact and reconcile the state snapshot before resuming.",
             };
+        case "reconciliation-drift":
+            return {
+                failureKind,
+                action: "escalate",
+                reason: `Reconciliation drift${unitSuffix(input)}: ${message}`,
+                exitReason: "reconciliation-drift",
+                remediation: "Inspect the persistent or repair-failed drift kinds reported by the State Reconciliation Module before resuming.",
+            };
         case "provider": {
             const providerClass = classifyError(message, input.retryAfterMs);
             return {

package/dist/resources/extensions/gsd/session-lock.js

@@ -521,6 +521,46 @@ export function readSessionLockData(basePath) {
 export function isSessionLockProcessAlive(data) {
     return isPidAlive(data.pid);
 }
+/**
+ * ADR-017 raw primitive: remove orphaned lock artifacts (lock dir + lock file)
+ * when the recorded PID is dead or no metadata is present. Mirrors the
+ * pre-flight cleanup logic in acquireSessionLock so the stale-worker drift
+ * handler can clear the orphan proactively without going through the full
+ * acquire path. No-op when the lock is held by an alive process.
+ *
+ * Returns true when artifacts were removed (drift was present).
+ */
+export function removeStaleSessionLock(basePath) {
+    const lp = lockPath(basePath);
+    const gsdDir = gsdRoot(basePath);
+    const lockTarget = effectiveLockTarget(gsdDir);
+    const lockDir = lockTarget + ".lock";
+    const existingData = readExistingLockData(lp);
+    const isOrphan = !existingData ||
+        (typeof existingData.pid === "number" && !isPidAlive(existingData.pid));
+    if (!isOrphan)
+        return false;
+    let removed = false;
+    if (existsSync(lockDir)) {
+        try {
+            rmSync(lockDir, { recursive: true, force: true });
+            removed = true;
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    if (existsSync(lp)) {
+        try {
+            unlinkSync(lp);
+            removed = true;
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    return removed;
+}
 /**
  * Returns true if we currently hold a session lock for the given path.
  */

package/dist/resources/extensions/gsd/state-reconciliation/drift/completion.js

@@ -0,0 +1,131 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 missing-completion-timestamp drift handler. Detects
+// tasks/slices/milestones marked complete (status = 'complete' | 'done') in
+// the DB but whose `completed_at` column is null, and where the on-disk
+// SUMMARY.md attests to completion. Backfills `completed_at` from the
+// SUMMARY.md mtime — deterministic and idempotent (re-running yields the
+// same value).
+import { existsSync, statSync } from "node:fs";
+import { getMilestone, getMilestoneSlices, getSliceTasks, isDbAvailable, updateMilestoneStatus, updateSliceStatus, updateTaskStatus, } from "../../gsd-db.js";
+import { resolveMilestoneFile, resolveSliceFile, resolveTaskFile, } from "../../paths.js";
+const COMPLETE_STATUSES = new Set(["complete", "done"]);
+function summaryMtimeIso(path) {
+    try {
+        return statSync(path).mtime.toISOString();
+    }
+    catch {
+        return null;
+    }
+}
+export function detectMissingCompletionTimestampDrift(state, ctx) {
+    if (!isDbAvailable())
+        return [];
+    const mid = state.activeMilestone?.id;
+    if (!mid)
+        return [];
+    const milestone = getMilestone(mid);
+    if (!milestone)
+        return [];
+    const drifts = [];
+    // Milestone-level
+    if (COMPLETE_STATUSES.has(milestone.status) &&
+        milestone.completed_at === null) {
+        const summary = resolveMilestoneFile(ctx.basePath, mid, "SUMMARY");
+        if (summary && existsSync(summary)) {
+            drifts.push({
+                kind: "missing-completion-timestamp",
+                entity: "milestone",
+                ids: [mid],
+            });
+        }
+    }
+    // Slice and task levels iterate independently — tasks can complete before
+    // the parent slice closes, so task drift must be checked even when the
+    // slice is still pending.
+    for (const slice of getMilestoneSlices(mid)) {
+        if (COMPLETE_STATUSES.has(slice.status) &&
+            slice.completed_at === null) {
+            const summary = resolveSliceFile(ctx.basePath, mid, slice.id, "SUMMARY");
+            if (summary && existsSync(summary)) {
+                drifts.push({
+                    kind: "missing-completion-timestamp",
+                    entity: "slice",
+                    ids: [`${mid}/${slice.id}`],
+                });
+            }
+        }
+        for (const task of getSliceTasks(mid, slice.id)) {
+            if (!COMPLETE_STATUSES.has(task.status))
+                continue;
+            if (task.completed_at !== null)
+                continue;
+            const taskSummary = resolveTaskFile(ctx.basePath, mid, slice.id, task.id, "SUMMARY");
+            if (taskSummary && existsSync(taskSummary)) {
+                drifts.push({
+                    kind: "missing-completion-timestamp",
+                    entity: "task",
+                    ids: [`${mid}/${slice.id}/${task.id}`],
+                });
+            }
+        }
+    }
+    return drifts;
+}
+export function repairMissingCompletionTimestamp(record, ctx) {
+    const composite = record.ids[0];
+    if (!composite)
+        return;
+    const parts = composite.split("/");
+    if (record.entity === "milestone") {
+        const [mid] = parts;
+        if (!mid)
+            return;
+        const milestone = getMilestone(mid);
+        if (!milestone ||
+            milestone.completed_at !== null ||
+            !COMPLETE_STATUSES.has(milestone.status))
+            return;
+        const summary = resolveMilestoneFile(ctx.basePath, mid, "SUMMARY");
+        const ts = summary ? summaryMtimeIso(summary) : null;
+        if (!ts)
+            return;
+        updateMilestoneStatus(mid, milestone.status, ts);
+        return;
+    }
+    if (record.entity === "slice") {
+        const [mid, sid] = parts;
+        if (!mid || !sid)
+            return;
+        const slice = getMilestoneSlices(mid).find((s) => s.id === sid);
+        if (!slice ||
+            slice.completed_at !== null ||
+            !COMPLETE_STATUSES.has(slice.status))
+            return;
+        const summary = resolveSliceFile(ctx.basePath, mid, sid, "SUMMARY");
+        const ts = summary ? summaryMtimeIso(summary) : null;
+        if (!ts)
+            return;
+        updateSliceStatus(mid, sid, slice.status, ts);
+        return;
+    }
+    if (record.entity === "task") {
+        const [mid, sid, tid] = parts;
+        if (!mid || !sid || !tid)
+            return;
+        const task = getSliceTasks(mid, sid).find((t) => t.id === tid);
+        if (!task ||
+            task.completed_at !== null ||
+            !COMPLETE_STATUSES.has(task.status))
+            return;
+        const summary = resolveTaskFile(ctx.basePath, mid, sid, tid, "SUMMARY");
+        const ts = summary ? summaryMtimeIso(summary) : null;
+        if (!ts)
+            return;
+        updateTaskStatus(mid, sid, tid, task.status, ts);
+    }
+}
+export const completionTimestampHandler = {
+    kind: "missing-completion-timestamp",
+    detect: detectMissingCompletionTimestampDrift,
+    repair: repairMissingCompletionTimestamp,
+};

package/dist/resources/extensions/gsd/state-reconciliation/drift/merge-state.js

@@ -0,0 +1,247 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 unmerged-merge-state drift handler. Relocated from
+// auto-recovery.ts as part of issue #5701. Owns:
+//   - rebase/cherry-pick/revert leftover cleanup (#4980 HIGH-7)
+//   - MERGE_HEAD / SQUASH_MSG reconciliation with auto-resolve of .gsd/
+//     conflicts (#530, #2542)
+import { execFileSync } from "node:child_process";
+import { existsSync, unlinkSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { getErrorMessage } from "../../error-utils.js";
+import { nativeAddPaths, nativeCheckoutTheirs, nativeCommit, nativeConflictFiles, nativeMergeAbort, nativeRebaseAbort, nativeResetHard, } from "../../native-git-bridge.js";
+import { logError, logWarning } from "../../workflow-logger.js";
+const SILENT_NOTIFY = () => { };
+function resolveGitDir(basePath) {
+    try {
+        const gitDir = execFileSync("git", ["rev-parse", "--git-dir"], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        }).trim();
+        if (gitDir.length > 0) {
+            return isAbsolute(gitDir) ? gitDir : resolve(basePath, gitDir);
+        }
+    }
+    catch (err) {
+        logWarning("recovery", `gitdir resolution failed: ${getErrorMessage(err)}`);
+    }
+    return join(basePath, ".git");
+}
+/**
+ * Best-effort abort of a pending merge/squash and hard-reset to HEAD.
+ * Handles both real merges (MERGE_HEAD) and squash merges (SQUASH_MSG).
+ */
+function abortAndResetMerge(basePath, hasMergeHead, squashMsgPath) {
+    if (hasMergeHead) {
+        try {
+            nativeMergeAbort(basePath);
+        }
+        catch (err) {
+            /* best-effort */
+            logWarning("recovery", `git merge-abort failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    else if (squashMsgPath) {
+        try {
+            unlinkSync(squashMsgPath);
+        }
+        catch (err) {
+            /* best-effort */
+            logWarning("recovery", `file unlink failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    try {
+        nativeResetHard(basePath);
+    }
+    catch (err) {
+        /* best-effort */
+        logError("recovery", `git reset failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Detect and abort other in-progress git operations left behind by a SIGKILL'd
+ * worker (rebase, cherry-pick, revert). Without this, a killed worker
+ * mid-rebase leaves `.git/rebase-merge/` or `.git/CHERRY_PICK_HEAD` and the
+ * worktree is wedged until the user manually runs the matching `--abort`.
+ *
+ * Called before merge-state reconciliation because these states block any
+ * subsequent merge/commit operation. (#4980 HIGH-7)
+ */
+function reconcileOtherInProgressGitOps(basePath, notify) {
+    const gitDir = resolveGitDir(basePath);
+    const states = [
+        {
+            label: "rebase",
+            indicators: [join(gitDir, "rebase-merge"), join(gitDir, "rebase-apply")],
+            abort: () => nativeRebaseAbort(basePath),
+        },
+        {
+            label: "cherry-pick",
+            indicators: [join(gitDir, "CHERRY_PICK_HEAD")],
+            abort: () => {
+                try {
+                    execFileSync("git", ["cherry-pick", "--abort"], {
+                        cwd: basePath,
+                        stdio: ["ignore", "pipe", "pipe"],
+                        encoding: "utf-8",
+                    });
+                }
+                catch (err) {
+                    throw new Error(`cherry-pick --abort failed: ${getErrorMessage(err)}`);
+                }
+            },
+        },
+        {
+            label: "revert",
+            indicators: [join(gitDir, "REVERT_HEAD")],
+            abort: () => {
+                try {
+                    execFileSync("git", ["revert", "--abort"], {
+                        cwd: basePath,
+                        stdio: ["ignore", "pipe", "pipe"],
+                        encoding: "utf-8",
+                    });
+                }
+                catch (err) {
+                    throw new Error(`revert --abort failed: ${getErrorMessage(err)}`);
+                }
+            },
+        },
+    ];
+    let reconciled = false;
+    for (const s of states) {
+        const present = s.indicators.some((p) => existsSync(p));
+        if (!present)
+            continue;
+        try {
+            s.abort();
+            notify(`Detected leftover ${s.label} state from prior session — aborted.`, "warning");
+            reconciled = true;
+        }
+        catch (err) {
+            logError("recovery", `${s.label} abort failed: ${getErrorMessage(err)}`);
+            notify(`Detected leftover ${s.label} state but auto-abort failed. ` +
+                `Run \`git ${s.label} --abort\` manually before retrying.`, "error");
+            return "blocked";
+        }
+    }
+    return reconciled ? "reconciled" : "clean";
+}
+/**
+ * Core: detect leftover merge state and reconcile it. Takes a NotifyFn so the
+ * legacy reconcileMergeState(basePath, ctx) wrapper and the drift handler can
+ * both call it — the drift handler uses SILENT_NOTIFY.
+ */
+function reconcileMergeStateCore(basePath, notify) {
+    // First, abort any rebase/cherry-pick/revert left over from a SIGKILL'd
+    // worker. Doing this before the merge-state check unblocks any merge that
+    // would otherwise refuse with "you have unfinished operation". (HIGH-7)
+    const otherOpsResult = reconcileOtherInProgressGitOps(basePath, notify);
+    if (otherOpsResult === "blocked")
+        return "blocked";
+    const gitDir = resolveGitDir(basePath);
+    const mergeHeadPath = join(gitDir, "MERGE_HEAD");
+    const squashMsgPath = join(gitDir, "SQUASH_MSG");
+    const hasMergeHead = existsSync(mergeHeadPath);
+    const hasSquashMsg = existsSync(squashMsgPath);
+    if (!hasMergeHead && !hasSquashMsg) {
+        return otherOpsResult === "reconciled" ? "reconciled" : "clean";
+    }
+    const conflictedFiles = nativeConflictFiles(basePath);
+    if (conflictedFiles.length === 0) {
+        // All conflicts resolved — finalize the merge/squash commit
+        try {
+            const commitSha = nativeCommit(basePath, "chore(gsd): reconcile merge state");
+            if (commitSha) {
+                const mode = hasMergeHead ? "merge" : "squash commit";
+                notify(`Finalized leftover ${mode} from prior session.`, "info");
+            }
+            else {
+                notify("No new commit needed for leftover merge/squash state — already committed.", "info");
+            }
+        }
+        catch (err) {
+            const errorMessage = getErrorMessage(err);
+            notify(`Failed to finalize leftover merge/squash commit: ${errorMessage}`, "error");
+            return "blocked";
+        }
+    }
+    else {
+        // Still conflicted — try auto-resolving .gsd/ state file conflicts (#530)
+        const gsdConflicts = conflictedFiles.filter((f) => f.startsWith(".gsd/"));
+        const codeConflicts = conflictedFiles.filter((f) => !f.startsWith(".gsd/"));
+        if (gsdConflicts.length > 0 && codeConflicts.length === 0) {
+            let resolved = true;
+            try {
+                nativeCheckoutTheirs(basePath, gsdConflicts);
+                nativeAddPaths(basePath, gsdConflicts);
+            }
+            catch (e) {
+                logError("recovery", `auto-resolve .gsd/ conflicts failed: ${e.message}`);
+                resolved = false;
+            }
+            if (resolved) {
+                try {
+                    nativeCommit(basePath, "chore: auto-resolve .gsd/ state file conflicts");
+                    notify(`Auto-resolved ${gsdConflicts.length} .gsd/ state file conflict(s) from prior merge.`, "info");
+                }
+                catch (e) {
+                    logError("recovery", `auto-commit .gsd/ conflict resolution failed: ${e.message}`);
+                    resolved = false;
+                }
+            }
+            if (!resolved) {
+                abortAndResetMerge(basePath, hasMergeHead, squashMsgPath);
+                notify("Detected leftover merge state — auto-resolve failed, cleaned up. Re-deriving state.", "warning");
+            }
+        }
+        else {
+            // Code conflicts present — fail safe and preserve any manual resolution
+            // work instead of discarding it with merge --abort/reset --hard.
+            notify("Detected leftover merge state with unresolved code conflicts. Auto-mode will pause without modifying the worktree so manual conflict resolution is preserved.", "error");
+            return "blocked";
+        }
+    }
+    return "reconciled";
+}
+/**
+ * Legacy entry point preserved for existing callers (auto.ts, auto/phases.ts
+ * via loop-deps, integration tests). New code prefers the drift handler.
+ */
+export function reconcileMergeState(basePath, ctx) {
+    return reconcileMergeStateCore(basePath, (message, severity) => ctx.ui.notify(message, severity));
+}
+function hasMergeStateLeftovers(basePath) {
+    const gitDir = resolveGitDir(basePath);
+    return (existsSync(join(gitDir, "MERGE_HEAD")) ||
+        existsSync(join(gitDir, "SQUASH_MSG")) ||
+        existsSync(join(gitDir, "rebase-merge")) ||
+        existsSync(join(gitDir, "rebase-apply")) ||
+        existsSync(join(gitDir, "CHERRY_PICK_HEAD")) ||
+        existsSync(join(gitDir, "REVERT_HEAD")));
+}
+export function detectMergeStateDrift(_state, ctx) {
+    if (hasMergeStateLeftovers(ctx.basePath)) {
+        return [{ kind: "unmerged-merge-state", basePath: ctx.basePath }];
+    }
+    return [];
+}
+/**
+ * Repair: invoke the reconciliation core with a silent notify. If the
+ * underlying reconciliation reports "blocked" (e.g., unresolved code
+ * conflicts present), throw so reconcileBeforeDispatch surfaces the drift
+ * via ReconciliationFailedError.
+ */
+export function repairMergeStateDrift(record) {
+    const result = reconcileMergeStateCore(record.basePath, SILENT_NOTIFY);
+    if (result === "blocked") {
+        throw new Error(`Merge state reconciliation blocked for ${record.basePath} — likely unresolved code conflicts. Manual intervention required.`);
+    }
+}
+export const mergeStateHandler = {
+    kind: "unmerged-merge-state",
+    detect: detectMergeStateDrift,
+    repair: (record) => {
+        repairMergeStateDrift(record);
+    },
+};

package/dist/resources/extensions/gsd/state-reconciliation/drift/project-md.js

@@ -0,0 +1,50 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 unregistered-milestone drift handler. Detects
+// milestones whose on-disk directory has meaningful content (ROADMAP/
+// CONTEXT/SUMMARY) but no DB row, then runs the markdown importer to
+// reconcile. PROJECT.md is the human-facing index — the importer's source
+// of truth is the .gsd/milestones/ directory tree.
+import { existsSync } from "node:fs";
+import { getMilestone, isDbAvailable } from "../../gsd-db.js";
+import { migrateHierarchyToDb } from "../../md-importer.js";
+import { findMilestoneIds } from "../../milestone-ids.js";
+import { resolveMilestoneFile } from "../../paths.js";
+function milestoneHasContent(basePath, milestoneId) {
+    const roadmap = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+    const context = resolveMilestoneFile(basePath, milestoneId, "CONTEXT");
+    const summary = resolveMilestoneFile(basePath, milestoneId, "SUMMARY");
+    return ((roadmap !== null && existsSync(roadmap)) ||
+        (context !== null && existsSync(context)) ||
+        (summary !== null && existsSync(summary)));
+}
+export function detectUnregisteredMilestoneDrift(_state, ctx) {
+    if (!isDbAvailable())
+        return [];
+    const drifts = [];
+    for (const milestoneId of findMilestoneIds(ctx.basePath)) {
+        if (getMilestone(milestoneId))
+            continue;
+        if (!milestoneHasContent(ctx.basePath, milestoneId))
+            continue;
+        drifts.push({ kind: "unregistered-milestone", milestoneId });
+    }
+    return drifts;
+}
+/**
+ * Repair: invoke the markdown importer. migrateHierarchyToDb walks the same
+ * findMilestoneIds list the detector uses and INSERTs OR IGNOREs every
+ * missing milestone (and its slices/tasks) — idempotent under cap=2 retry.
+ *
+ * Note: even though we receive one record at a time, the importer is a
+ * project-wide operation. Repeated invocation across multiple drift records
+ * in the same pass is wasteful but safe; a future optimization could
+ * coalesce by checking whether the importer has already run this pass.
+ */
+export function repairUnregisteredMilestone(_record, ctx) {
+    migrateHierarchyToDb(ctx.basePath);
+}
+export const unregisteredMilestoneHandler = {
+    kind: "unregistered-milestone",
+    detect: detectUnregisteredMilestoneDrift,
+    repair: repairUnregisteredMilestone,
+};