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

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

@@ -7,7 +7,7 @@
 import { existsSync } from "node:fs";
 import { getMilestone, isDbAvailable } from "../../gsd-db.js";
 import { findMilestoneIds } from "../../milestone-ids.js";
-import { resolveMilestoneFile } from "../../paths.js";
+import { resolveMilestoneFile, resolveMilestonePath } from "../../paths.js";
 function milestoneHasContent(basePath, milestoneId) {
     const roadmap = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
     const context = resolveMilestoneFile(basePath, milestoneId, "CONTEXT");
@@ -31,12 +31,25 @@ export function detectUnregisteredMilestoneDrift(_state, ctx) {
 }
 /**
  * Repair intentionally fails closed. The project-root DB is authoritative at
- * runtime; markdown-only milestones must be imported through an explicit
- * migration/recovery command so operators opt into changing canonical state.
+ * runtime; markdown-only milestones must be reconciled through an explicit,
+ * operator-controlled action so operators opt into changing canonical state.
+ *
+ * The hint deliberately leads with the *targeted*, non-destructive options. The
+ * common cause of this drift is a directory left under an old ID after a
+ * `unique_milestone_ids` rename, where the right fix is to rename (move) the
+ * directory — not a full DB reimport. `/gsd recover --confirm` is a destructive
+ * clear-and-reimport of the entire DB and is offered only as a last resort, so
+ * users do not reach for it expecting a targeted repair (see issue #826).
  */
-export function repairUnregisteredMilestone(record, _ctx) {
-    throw new Error(`Milestone ${record.milestoneId} exists only as markdown projection. ` +
-        "Runtime reconciliation will not import markdown into the authoritative DB; run `/gsd recover --confirm` if this markdown should repopulate the database.");
+export function repairUnregisteredMilestone(record, ctx) {
+    const dir = resolveMilestonePath(ctx.basePath, record.milestoneId);
+    const dirHint = dir ?? `the .gsd directory for ${record.milestoneId}`;
+    throw new Error(`Milestone ${record.milestoneId} exists only as markdown projection ` +
+        "(on-disk ROADMAP/CONTEXT/SUMMARY with no authoritative DB row). " +
+        "Runtime reconciliation will not import markdown into the DB. Choose one:\n" +
+        `  • Rename: if this directory is the same milestone under an old ID (e.g. a unique_milestone_ids rename), move \`${dirHint}\` to the current ID's directory and re-run.\n` +
+        `  • Discard: if this milestone is no longer relevant, delete \`${dirHint}\` and re-run.\n` +
+        "  • Last resort: `/gsd recover --confirm` performs a destructive full DB clear-and-reimport — it does NOT do a targeted import and can replace or duplicate existing DB milestones.");
 }
 export const unregisteredMilestoneHandler = {
     kind: "unregistered-milestone",

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

@@ -40,6 +40,7 @@ function milestoneHasDivergence(basePath, milestoneId) {
     }
     const dbSlices = getMilestoneSlices(milestoneId);
     const dbSliceMap = new Map(dbSlices.map((s) => [s.id, s]));
+    const dbSliceOrder = new Map(dbSlices.map((s, index) => [s.id, index]));
     const readySliceIds = getSlicesReadyForDivergenceCheck(milestoneId, dbSlices);
     if (dbSlices.length > 0 && readySliceIds.size === 0) {
         return false;
@@ -48,13 +49,12 @@ function milestoneHasDivergence(basePath, milestoneId) {
     for (let i = 0; i < roadmap.slices.length; i++) {
         const roadmapSlice = roadmap.slices[i];
         roadmapSliceIds.add(roadmapSlice.id);
-        const expectedSequence = i + 1;
         const dbSlice = dbSliceMap.get(roadmapSlice.id);
         if (!dbSlice)
             return true; // Roadmap has a slice the DB doesn't.
         if (!readySliceIds.has(dbSlice.id))
             continue;
-        if (dbSlice.sequence !== expectedSequence)
+        if (dbSliceOrder.get(dbSlice.id) !== i)
             return true;
         if (!arraysEqual(dbSlice.depends, roadmapSlice.depends))
             return true;

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

@@ -5,11 +5,9 @@
 // the detect+repair composition moves here. The previous repairStaleRenders
 // had zero callers in production code — wiring it through
 // reconcileBeforeDispatch closes that gap.
-import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
 import { detectStaleRenders, renderPlanCheckboxes, renderRoadmapFromDb, renderSliceSummary, renderTaskSummary, } from "../../markdown-renderer.js";
-import { getMilestone, getSlice, setSliceSummaryMd } from "../../gsd-db.js";
-import { buildSliceFileName } from "../../paths.js";
+import { getMilestone, getMilestoneSlices, getSlice, getSliceTasks, setSliceSummaryMd } from "../../gsd-db.js";
+import { resolveSliceFile } from "../../paths.js";
 import { logWarning } from "../../workflow-logger.js";
 // ─── Core (basePath-only — usable by both drift API and legacy wrapper) ──────
 function detectStaleRenderDriftFromBasePath(basePath) {
@@ -50,17 +48,31 @@ function canonicalizeMilestoneId(dirSegment) {
     const baseId = dirSegment.match(/^(M\d+)(?:$|-)/i)?.[1];
     if (baseId && getMilestone(baseId))
         return baseId;
+    // Flat-phase: e.g. 01-test → M001
+    const phaseMatch = dirSegment.match(/^(\d+)-/);
+    if (phaseMatch) {
+        const flatId = `M${String(parseInt(phaseMatch[1], 10)).padStart(3, "0")}`;
+        if (getMilestone(flatId))
+            return flatId;
+    }
     return suffixId ?? baseId ?? dirSegment;
 }
 function resolveRoadmapMilestoneIdFromPath(normPath) {
-    const milestoneMatch = normPath.match(/milestones\/([^/]+)\//);
+    // Flat-phase: phases/NN-slug/NN-ROADMAP.md
+    // Legacy: milestones/MID/MID-ROADMAP.md
+    const milestoneMatch = normPath.match(/phases\/([^/]+)\//)
+        || normPath.match(/milestones\/([^/]+)\//);
     if (!milestoneMatch) {
         throw new Error(`stale-render drift: roadmap path missing milestone segment: ${normPath}`);
     }
     const fileMatch = normPath.match(/(?:^|\/)([^/]+)-ROADMAP\.md$/i);
+    // For flat-phase, derive milestone id from phase number prefix
+    const phaseNumMatch = milestoneMatch[1].match(/^(\d+)-/);
+    const phaseDerivedId = phaseNumMatch ? `M${String(parseInt(phaseNumMatch[1], 10)).padStart(3, "0")}` : null;
     const candidates = [
         fileMatch?.[1],
         milestoneMatch[1],
+        phaseDerivedId,
         fileMatch?.[1]?.match(/^(M\d+)/i)?.[1],
         milestoneMatch[1].match(/^(M\d+)/i)?.[1],
     ].filter((candidate) => !!candidate);
@@ -78,12 +90,18 @@ async function repairStaleRenderFromBasePath(record, basePath) {
         return;
     }
     if (reason.includes("in plan")) {
-        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
+        // Flat-phase: phases/NN-slug/NN-MM-PLAN.md
+        // Legacy: milestones/X/slices/Y/PLAN.md
+        const pathMatch = normPath.match(/phases\/([^/]+)\/(\d+)-(\d+)-PLAN/)
+            || normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
         if (!pathMatch) {
             throw new Error(`stale-render drift: plan path missing milestone/slice segments: ${record.renderPath}`);
         }
         const milestoneId = canonicalizeMilestoneId(pathMatch[1]);
-        const wrote = await renderPlanCheckboxes(basePath, milestoneId, pathMatch[2], record.renderPath);
+        const sliceId = pathMatch[2] && pathMatch[3] && /^\d+$/.test(pathMatch[2])
+            ? `S${String(parseInt(pathMatch[3], 10)).padStart(2, "0")}`
+            : pathMatch[2];
+        const wrote = await renderPlanCheckboxes(basePath, milestoneId, sliceId, record.renderPath);
         if (!wrote) {
             throw new Error(`stale-render drift: plan re-render wrote nothing for ${milestoneId}/${pathMatch[2]} ` +
                 `(${record.renderPath}); slice has no tasks or its path is unresolvable`);
@@ -91,31 +109,77 @@ async function repairStaleRenderFromBasePath(record, basePath) {
         return;
     }
     if (reason.includes("SUMMARY.md missing") && /^T\d+/.test(reason)) {
-        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\/tasks\//);
+        // Flat-phase: phases/NN-slug/ (no tasks/ subdir, task summaries in phase dir)
+        // Legacy: milestones/X/slices/Y/tasks/
+        const pathMatch = normPath.match(/phases\/([^/]+)\//)
+            || normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\/tasks\//);
         const taskMatch = reason.match(/^(T\d+)/);
         if (!pathMatch || !taskMatch) {
             throw new Error(`stale-render drift: task summary path/reason malformed: ${record.renderPath} reason=${reason}`);
         }
         const milestoneId = canonicalizeMilestoneId(pathMatch[1]);
-        const wrote = await renderTaskSummary(basePath, milestoneId, pathMatch[2], taskMatch[1]);
+        // In flat-phase there's no slice segment in the path; find the task's slice from DB.
+        let sliceId;
+        if (pathMatch[2]) {
+            sliceId = pathMatch[2];
+        }
+        else {
+            // Flat-phase: scan milestone's slices for the task
+            let foundSliceId;
+            for (const s of getMilestoneSlices(milestoneId)) {
+                if (getSliceTasks(milestoneId, s.id).some(t => t.id === taskMatch[1])) {
+                    foundSliceId = s.id;
+                    break;
+                }
+            }
+            if (!foundSliceId) {
+                throw new Error(`stale-render drift: task ${taskMatch[1]} not found in any slice of ${milestoneId} (${record.renderPath})`);
+            }
+            sliceId = foundSliceId;
+        }
+        const wrote = await renderTaskSummary(basePath, milestoneId, sliceId, taskMatch[1]);
         if (!wrote) {
             throw new Error(`stale-render drift: task summary re-render wrote nothing for ` +
-                `${milestoneId}/${pathMatch[2]}/${taskMatch[1]} (${record.renderPath}); ` +
+                `${milestoneId}/${sliceId}/${taskMatch[1]} (${record.renderPath}); ` +
                 `task has no summary in DB or its slice path is unresolvable`);
         }
         return;
     }
     if (reason.includes("SUMMARY.md missing") && /^S\d+/.test(reason)) {
-        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
+        // Flat-phase: phases/NN-slug/NN-MM-SUMMARY.md or phases/NN-slug/NN-SUMMARY.md
+        // Legacy: milestones/X/slices/Y/SUMMARY.md
+        const pathMatch = normPath.match(/phases\/([^/]+)\/(\d+)-(\d+)-SUMMARY/)
+            || normPath.match(/phases\/([^/]+)\/(\d+)-SUMMARY/)
+            || normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
         if (!pathMatch) {
             throw new Error(`stale-render drift: slice summary path missing milestone/slice segments: ${record.renderPath}`);
         }
-        const milestoneId = canonicalizeMilestoneId(pathMatch[1]);
-        const sliceId = pathMatch[2];
+        // Flat-phase: groups are (phaseDir, phaseNum, planNum) for NN-MM-SUMMARY,
+        // or (phaseDir, phaseNum) for NN-SUMMARY (phase-level). In the latter case,
+        // derive slice from the reason text which starts with S\d+.
+        // Legacy: groups are (milestoneDir, sliceDir).
+        let milestoneId;
+        let sliceId;
+        milestoneId = canonicalizeMilestoneId(pathMatch[1]);
+        if (pathMatch[3] && /^\d+$/.test(pathMatch[2])) {
+            // NN-MM-SUMMARY: pathMatch[3] is the plan number
+            sliceId = `S${String(parseInt(pathMatch[3], 10)).padStart(2, "0")}`;
+        }
+        else if (pathMatch[2] && /^S\d+/.test(pathMatch[2])) {
+            // Legacy: pathMatch[2] is the slice dir name
+            sliceId = pathMatch[2];
+        }
+        else {
+            // NN-SUMMARY (phase-level): derive slice from reason
+            const reasonSlice = reason.match(/^(S\d+)/);
+            sliceId = reasonSlice ? reasonSlice[1] : "S01";
+        }
         const slice = getSlice(milestoneId, sliceId);
-        const uatPath = join(dirname(record.renderPath), buildSliceFileName(sliceId, "UAT"));
+        // Use resolveSliceFile so the UAT existence check matches the NN-MM-UAT.md
+        // name that renderSliceSummary actually writes (buildSliceFileName only yields MM-UAT.md).
+        const uatPath = resolveSliceFile(basePath, milestoneId, sliceId, "UAT");
         // renderSliceSummary writes both artifacts, so clear deleted UAT first.
-        if (slice?.full_uat_md && !existsSync(uatPath)) {
+        if (slice?.full_uat_md && !uatPath) {
             setSliceSummaryMd(milestoneId, sliceId, slice.full_summary_md ?? "", "");
         }
         const wrote = await renderSliceSummary(basePath, milestoneId, sliceId);
@@ -127,14 +191,26 @@ async function repairStaleRenderFromBasePath(record, basePath) {
         return;
     }
     if (reason.includes("UAT.md missing")) {
-        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
+        // Flat-phase: phases/NN-slug/NN-MM-UAT.md or phases/NN-slug/NN-UAT.md
+        // Legacy: milestones/X/slices/Y/UAT.md
+        const pathMatch = normPath.match(/phases\/([^/]+)\/(\d+)-(\d+)-UAT/)
+            || normPath.match(/phases\/([^/]+)\/(\d+)-UAT/)
+            || normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
         if (!pathMatch) {
             throw new Error(`stale-render drift: UAT path missing milestone/slice segments: ${record.renderPath}`);
         }
-        // When UAT.md is removed from disk, mirror that intent by clearing stale
-        // persisted UAT content instead of rehydrating it back onto disk.
         const milestoneId = canonicalizeMilestoneId(pathMatch[1]);
-        const sliceId = pathMatch[2];
+        let sliceId;
+        if (pathMatch[3] && /^\d+$/.test(pathMatch[2])) {
+            sliceId = `S${String(parseInt(pathMatch[3], 10)).padStart(2, "0")}`;
+        }
+        else if (pathMatch[2] && /^S\d+/.test(pathMatch[2])) {
+            sliceId = pathMatch[2];
+        }
+        else {
+            const reasonSlice = reason.match(/(S\d+)/);
+            sliceId = reasonSlice ? reasonSlice[1] : "S01";
+        }
         const slice = getSlice(milestoneId, sliceId);
         if (!slice) {
             throw new Error(`stale-render drift: missing slice for UAT clear ${milestoneId}/${sliceId}`);

package/dist/resources/extensions/gsd/state-reconciliation/index.js

@@ -29,16 +29,49 @@ const defaultDeps = {
  *   - any repair function throws within a pass, or
  *   - drift persists after the cap.
  */
-export async function reconcileBeforeDispatch(basePath, deps = defaultDeps) {
+export async function reconcileBeforeDispatch(basePath, partialDeps = {}) {
+    const deps = { ...defaultDeps, ...partialDeps };
     const registry = deps.registry ?? DRIFT_REGISTRY;
     const clearParseCache = deps.clearParseCache ?? defaultClearParseCache;
     const repaired = [];
+    // Capture-on-first-read: infer .planning/ layout, import content into DB, and
+    // activate the compat marker. Skipped in dry-run mode to keep the reconcile
+    // pass fully read-only — no marker writes.
+    if (!deps.dryRun) {
+        const { capturePlanningCompatIfNeeded } = await import("../compat/planning-compat.js");
+        await capturePlanningCompatIfNeeded(basePath);
+    }
     for (let pass = 0; pass < MAX_PASSES; pass++) {
         deps.invalidateStateCache();
         const stateSnapshot = await deps.deriveState(basePath, deps.deriveStateOptions);
-        const ctx = { basePath, state: stateSnapshot };
+        const ctx = { basePath, state: stateSnapshot, dryRun: deps.dryRun };
         const detection = await detectAllDrift(stateSnapshot, ctx, registry);
         const drift = detection.records;
+        if (deps.dryRun && drift.length > 0) {
+            const wouldRepair = [];
+            const blockers = [...detection.detectBlockers];
+            for (const record of drift) {
+                const handler = registry.find((h) => h.kind === record.kind);
+                const blocker = handler?.blocker ? await handler.blocker(record, ctx) : null;
+                if (blocker) {
+                    blockers.push(blocker);
+                }
+                else {
+                    wouldRepair.push(record);
+                }
+            }
+            return {
+                ok: true,
+                stateSnapshot,
+                repaired: wouldRepair,
+                blockers: [
+                    ...new Set([
+                        ...(stateSnapshot.blockers ?? []),
+                        ...blockers,
+                    ]),
+                ],
+            };
+        }
         if (drift.length === 0) {
             return {
                 ok: true,
@@ -106,7 +139,7 @@ export async function reconcileBeforeDispatch(basePath, deps = defaultDeps) {
     // After MAX_PASSES, one more derive+detect to verify nothing persists.
     deps.invalidateStateCache();
     const finalState = await deps.deriveState(basePath, deps.deriveStateOptions);
-    const finalCtx = { basePath, state: finalState };
+    const finalCtx = { basePath, state: finalState, dryRun: deps.dryRun };
     const finalDetection = await detectAllDrift(finalState, finalCtx, registry);
     const persistent = finalDetection.records;
     if (persistent.length > 0) {

package/dist/resources/extensions/gsd/state-reconciliation/registry.js

@@ -4,6 +4,8 @@
 import { completionTimestampHandler } from "./drift/completion.js";
 import { artifactDbStatusDivergenceHandler, completedMilestoneReopenedHandler, diskSliceIdDivergenceHandler, } from "./drift/artifact-db.js";
 import { mergeStateHandler } from "./drift/merge-state.js";
+import { externalMarkdownEditHandler } from "./drift/external-markdown-edit.js";
+import { externalPlanningEditHandler } from "./drift/external-planning-edit.js";
 import { unregisteredMilestoneHandler } from "./drift/project-md.js";
 import { roadmapDivergenceHandler } from "./drift/roadmap.js";
 import { sketchFlagHandler } from "./drift/sketch-flag.js";
@@ -15,6 +17,16 @@ import { staleWorkerHandler } from "./drift/stale-worker.js";
 // by kind before invoking repair, so this is sound at runtime.
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const DRIFT_REGISTRY = [
+    // ⚠ ORDER IS SIGNIFICANT for repairs within a single pass.
+    // external-markdown-edit MUST run before any handler that re-projects
+    // markdown from DB (stale-render, roadmap-divergence). If a DB-projection
+    // handler runs first it overwrites the gsd-core file and the subsequent
+    // external-markdown-edit repair imports the already-overwritten content —
+    // silently discarding the cross-tool edit. With external-markdown-edit first
+    // the DB is updated to reflect the gsd-core edit before stale-render
+    // re-renders, so the canonical re-projection preserves the edit's intent.
+    externalMarkdownEditHandler,
+    externalPlanningEditHandler,
     sketchFlagHandler,
     mergeStateHandler,
     staleRenderHandler,

package/dist/resources/extensions/gsd/state.js

@@ -10,7 +10,7 @@
 // must never be consulted when DB data is present.
 import { parseRoadmap, parsePlan, } from './parsers-legacy.js';
 import { parseSummary, loadFile, parseRequirementCounts, parseContextDependsOn, } from './files.js';
-import { resolveMilestoneFile, resolveSlicePath, resolveSliceFile, resolveTaskFile, resolveTasksDir, resolveGsdRootFile, gsdRoot, } from './paths.js';
+import { buildMilestoneFileName, resolveFile, resolveMilestonePath, resolveMilestoneFile, resolveSlicePath, resolveSliceFile, resolveTaskFile, resolveTasksDir, resolveGsdRootFile, gsdRoot, } from './paths.js';
 import { findMilestoneIds } from './milestone-ids.js';
 import { loadQueueOrder, sortByQueueOrder } from './queue-order.js';
 import { isClosedStatus, isDeferredStatus } from './status-guards.js';
@@ -23,8 +23,8 @@ import { logWarning } from './workflow-logger.js';
 import { extractVerdict } from './verdict-parser.js';
 import { detectPendingEscalation } from './escalation.js';
 import { isTerminalMilestoneSummaryContent } from './milestone-summary-classifier.js';
-import { isDbAvailable, getAllMilestones, getMilestone, getSlicesByMilestoneIds, getSliceTasks, getReplanHistory, getSlice, getRequirementCounts, getLatestAssessmentByScope, getPendingGateCountForTurn, } from './gsd-db.js';
-import { wasWorkflowDatabaseOpenAttempted } from './db-workspace.js';
+import { isDbAvailable, getAllMilestones, getMilestone, getSlicesByMilestoneIds, getSliceTasks, getReplanHistory, getSlice, getRequirementCounts, getLatestAssessmentByScope, getPendingGateCountForTurn, setMilestoneQueueOrder, } from './gsd-db.js';
+import { openExistingWorkflowDatabase, wasWorkflowDatabaseOpenAttempted } from './db-workspace.js';
 import { formatCompletePhaseNextAction, countUnmappedActiveRequirements } from './requirements-backlog.js';
 import { classifyMilestoneReadiness, readinessNeedsDiscussion, } from './milestone-readiness.js';
 import { needsAttentionBlockerGuidance as formatNeedsAttentionBlocker, needsRemediationBlockerGuidance as formatNeedsRemediationBlocker, } from './guidance.js';
@@ -189,6 +189,36 @@ async function loadRecentDecisions(basePath) {
 export function invalidateStateCache() {
     _stateCache = null;
 }
+function syncQueueOrderProjectionToDb(basePath) {
+    const queueOrder = loadQueueOrder(basePath);
+    if (!queueOrder)
+        return;
+    const currentIds = getAllMilestones().map((m) => m.id);
+    const desiredIds = sortByQueueOrder(currentIds, queueOrder);
+    if (currentIds.length === desiredIds.length && currentIds.every((id, i) => id === desiredIds[i]))
+        return;
+    setMilestoneQueueOrder(desiredIds);
+}
+function ensureExistingWorkflowDbOpen(basePath) {
+    const opened = isDbAvailable() || openExistingWorkflowDatabase(basePath).ok;
+    if (opened)
+        syncQueueOrderProjectionToDb(basePath);
+    return opened;
+}
+function buildDbUnavailableState() {
+    return {
+        activeMilestone: null,
+        activeSlice: null,
+        activeTask: null,
+        phase: "pre-planning",
+        recentDecisions: [],
+        blockers: ["DB unavailable — runtime markdown state derivation is disabled"],
+        nextAction: "Open or create the canonical GSD database before deriving workflow state. If this project only has markdown state, run /gsd migrate explicitly.",
+        registry: [],
+        requirements: { active: 0, validated: 0, deferred: 0, outOfScope: 0, blocked: 0, total: 0 },
+        progress: { milestones: { done: 0, total: 0 } },
+    };
+}
 /**
  * Returns the ID of the first incomplete milestone, or null if all are complete.
  */
@@ -219,6 +249,7 @@ export async function getActiveMilestoneId(basePath) {
     }
     // DB-first: query milestones table for the first non-complete, non-parked milestone
     if (isDbAvailable()) {
+        syncQueueOrderProjectionToDb(basePath);
         const allMilestones = getAllMilestones();
         if (allMilestones.length > 0) {
             for (const m of allMilestones) {
@@ -282,6 +313,7 @@ export async function deriveState(basePath, opts) {
     // DB-backed derivation is authoritative whenever the DB is open. Runtime
     // degrade must not infer state from ROADMAP.md, PLAN.md, SUMMARY.md,
     // REQUIREMENTS.md, or flag files.
+    ensureExistingWorkflowDbOpen(basePath);
     if (isDbAvailable()) {
         const stopDbTimer = debugTime("derive-state-db");
         result = await deriveStateFromDb(basePath, opts?.projectRootForReads ?? basePath);
@@ -292,18 +324,7 @@ export async function deriveState(basePath, opts) {
         if (wasWorkflowDatabaseOpenAttempted()) {
             logWarning("state", "DB unavailable — refusing implicit markdown state derivation");
         }
-        result = {
-            activeMilestone: null,
-            activeSlice: null,
-            activeTask: null,
-            phase: "pre-planning",
-            recentDecisions: [],
-            blockers: ["DB unavailable — runtime markdown state derivation is disabled"],
-            nextAction: "Open or create the canonical GSD database before deriving workflow state. If this project only has markdown state, run /gsd migrate explicitly.",
-            registry: [],
-            requirements: { active: 0, validated: 0, deferred: 0, outOfScope: 0, blocked: 0, total: 0 },
-            progress: { milestones: { done: 0, total: 0 } },
-        };
+        result = buildDbUnavailableState();
     }
     result.recentDecisions = await loadRecentDecisions(cacheKey);
     stopTimer({ phase: result.phase, milestone: result.activeMilestone?.id });
@@ -359,6 +380,12 @@ function buildCompletenessSet(basePath, milestones) {
     }
     return { completeMilestoneIds, parkedMilestoneIds };
 }
+function milestoneArtifactExistsInResolvedDir(milestoneDir, milestoneId, suffix) {
+    if (!milestoneDir)
+        return false;
+    const flatPath = join(milestoneDir, buildMilestoneFileName(milestoneId, suffix));
+    return existsSync(flatPath) || resolveFile(milestoneDir, milestoneId, suffix) !== null;
+}
 async function buildRegistryAndFindActive(basePath, milestones, completeMilestoneIds, parkedMilestoneIds) {
     const registry = [];
     let activeMilestone = null;
@@ -386,8 +413,9 @@ async function buildRegistryAndFindActive(basePath, milestones, completeMileston
         }
         const allSlicesDone = slices.length > 0 && slices.every(s => isStatusDone(s.status));
         const title = stripMilestonePrefix(m.title) || m.id;
-        const hasContext = !!resolveMilestoneFile(basePath, m.id, "CONTEXT");
-        const hasDraftContext = !hasContext && !!resolveMilestoneFile(basePath, m.id, "CONTEXT-DRAFT");
+        const milestoneDir = resolveMilestonePath(basePath, m.id);
+        const hasContext = milestoneArtifactExistsInResolvedDir(milestoneDir, m.id, "CONTEXT");
+        const hasDraftContext = !hasContext && milestoneArtifactExistsInResolvedDir(milestoneDir, m.id, "CONTEXT-DRAFT");
         const readiness = classifyMilestoneReadiness({
             status: m.status,
             hasContext,
@@ -579,6 +607,9 @@ function checkReplanTrigger(basePath, milestoneId, sliceId) {
     return !!sliceRow?.replan_triggered_at;
 }
 export async function deriveStateFromDb(basePath, artifactReadRoot = basePath) {
+    if (!ensureExistingWorkflowDbOpen(basePath)) {
+        return buildDbUnavailableState();
+    }
     const requirements = getRequirementCounts();
     const allMilestones = getAllMilestones();
     const milestoneLock = getRequestedMilestoneLock();

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

@@ -1,21 +1,14 @@
 // GSD Extension — Advisory Sync Lock
 // Prevents concurrent worktree syncs from colliding via a simple file lock.
 // Stale locks (mtime > 60s, owner PID confirmed dead) are overridden. Lock
-// acquisition waits up to 5 seconds then skips non-fatally.
+// acquisition skips non-fatally when a live lock is already held.
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeSync } from "node:fs";
 import { dirname, join } from "node:path";
 const STALE_THRESHOLD_MS = 60_000; // 60 seconds
-const DEFAULT_TIMEOUT_MS = 5_000; // 5 seconds
-const SPIN_INTERVAL_MS = 100; // 100ms polling interval
-// SharedArrayBuffer for synchronous sleep via Atomics.wait
-const SLEEP_BUFFER = new SharedArrayBuffer(4);
-const SLEEP_VIEW = new Int32Array(SLEEP_BUFFER);
+const DEFAULT_TIMEOUT_MS = 0; // fail fast; sync waits block the JS event loop
 function lockFilePath(basePath) {
     return join(basePath, ".gsd", "sync.lock");
 }
-function sleepSync(ms) {
-    Atomics.wait(SLEEP_VIEW, 0, 0, ms);
-}
 /** True if the given PID is alive in the current process namespace. */
 function isPidAlive(pid) {
     try {
@@ -62,7 +55,7 @@ function tryCreateLockFile(lp, payload) {
 }
 /**
  * Acquire an advisory sync lock for the given basePath.
- * Returns { acquired: true } on success, { acquired: false } after timeout.
+ * Returns { acquired: true } on success, { acquired: false } when a live lock is held.
  *
  * Replaces a non-atomic `existsSync` + `atomicWriteSync` (write-temp+rename,
  * which is not exclusive-create) sequence that allowed two callers to both
@@ -73,10 +66,13 @@ function tryCreateLockFile(lp, payload) {
  * before stealing — prevents a slow event-loop pause (>60s under heavy I/O)
  * from making a legitimately-held lock appear stale and get stolen.
  * (Issue #4980 M-concurrency-3)
+ *
+ * Contended live locks fail fast. A synchronous wait here would freeze timers,
+ * I/O, and UI work on Node's single JS thread. The timeout argument remains
+ * accepted for compatibility but is intentionally not used for sync waiting.
  */
-export function acquireSyncLock(basePath, timeoutMs = DEFAULT_TIMEOUT_MS) {
+export function acquireSyncLock(basePath, _timeoutMs = DEFAULT_TIMEOUT_MS) {
     const lp = lockFilePath(basePath);
-    const deadline = Date.now() + timeoutMs;
     const lockData = JSON.stringify({ pid: process.pid, acquired_at: new Date().toISOString() }, null, 2);
     while (true) {
         // First try the fast path: atomic create. No check-then-write race.
@@ -88,7 +84,7 @@ export function acquireSyncLock(basePath, timeoutMs = DEFAULT_TIMEOUT_MS) {
         catch {
             /* unexpected — fall through to retry */
         }
-        // File exists. Decide whether to steal (stale + owner dead) or wait.
+        // File exists. Decide whether to steal (stale + owner dead) or skip.
         let canSteal = false;
         try {
             const stat = statSync(lp);
@@ -122,11 +118,8 @@ export function acquireSyncLock(basePath, timeoutMs = DEFAULT_TIMEOUT_MS) {
             // Loop back to retry create.
             continue;
         }
-        // Lock is held and not stale (or owner is alive) — wait or give up.
-        if (Date.now() >= deadline) {
-            return { acquired: false };
-        }
-        sleepSync(SPIN_INTERVAL_MS);
+        // Lock is held and not stale (or owner is alive) — skip non-fatally.
+        return { acquired: false };
     }
 }
 /**