@opengsd/gsd-pi 1.1.1-dev.a5a2de8 → 1.1.1-dev.b2556262

package/dist/resources/extensions/gsd/source-observations.js

@@ -0,0 +1,306 @@
+// Project/App: gsd-pi
+// File Purpose: Active-unit source observations for provider payload context.
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { extractPlanningPathReference, normalizeFilePath } from "./pre-execution-checks.js";
+export const WHOLE_FILE_OBSERVATION_MAX_BYTES = 50 * 1024;
+export const WHOLE_FILE_OBSERVATION_MAX_LINES = 2000;
+const SOURCE_CONTEXT_TITLE = "## Source Context Block";
+const SOURCE_OBSERVATION_UNIT_TYPE = "execute-task";
+export function supportsSourceObservationsForUnit(unitType) {
+    return unitType === SOURCE_OBSERVATION_UNIT_TYPE;
+}
+export class SourceObservationStore {
+    active = null;
+    beginUnit(unit) {
+        if (!supportsSourceObservationsForUnit(unit.unitType)) {
+            this.clear();
+            return;
+        }
+        if (this.matches(unit))
+            return;
+        this.active = { unit: { ...unit }, observations: new Map() };
+    }
+    clear() {
+        this.active = null;
+    }
+    degradeUnit(unit) {
+        if (!this.active)
+            return;
+        const current = this.active.unit;
+        if (current.unitType === unit.unitType &&
+            current.unitId === unit.unitId &&
+            current.startedAt === unit.startedAt) {
+            this.active = null;
+        }
+    }
+    observePlanTask(task) {
+        if (!this.active)
+            return;
+        for (const entry of planDeclaredSourceEntries(task)) {
+            this.observePath(entry.path, "plan");
+        }
+    }
+    observeRead(input) {
+        if (!this.active)
+            return;
+        const rawPath = readPathFromInput(input);
+        if (!rawPath.trim())
+            return;
+        this.observePath(rawPath, "read");
+    }
+    observeMutation(input) {
+        if (!this.active)
+            return;
+        const rawPath = readPathFromInput(input);
+        if (!rawPath.trim())
+            return;
+        this.observePath(rawPath, "mutation", { replaceExisting: true });
+    }
+    renderActiveBlock() {
+        if (!this.active || this.active.observations.size === 0)
+            return null;
+        if (!supportsSourceObservationsForUnit(this.active.unit.unitType))
+            return null;
+        const observations = [...this.active.observations.values()]
+            .sort((a, b) => a.path.localeCompare(b.path));
+        const lines = [
+            SOURCE_CONTEXT_TITLE,
+            `Active Unit: ${this.active.unit.unitType} ${this.active.unit.unitId}`,
+            "",
+            "The files below are protected active-Unit source context. " +
+                "Use this block instead of rereading small files just to recover line windows.",
+        ];
+        const wholeFiles = observations.filter((observation) => observation.status === "whole");
+        const unavailable = observations.filter((observation) => observation.status !== "whole");
+        if (wholeFiles.length > 0) {
+            lines.push("", "### Whole-File Observations");
+            for (const observation of wholeFiles) {
+                lines.push("", `#### ${observation.path}`, `Status: whole-file (${observation.lines ?? 0} lines, ${formatSize(observation.bytes ?? 0)})`, fencedSource(observation.text ?? ""));
+            }
+        }
+        if (unavailable.length > 0) {
+            lines.push("", "### Unavailable Source Observations");
+            for (const observation of unavailable) {
+                const detail = observation.reason ? ` - ${observation.reason}` : "";
+                lines.push(`- ${observation.path}: ${observation.status}${detail}`);
+            }
+        }
+        return lines.join("\n");
+    }
+    matches(unit) {
+        if (!this.active)
+            return false;
+        const current = this.active.unit;
+        return current.unitType === unit.unitType &&
+            current.unitId === unit.unitId &&
+            current.startedAt === unit.startedAt &&
+            current.basePath === unit.basePath;
+    }
+    observePath(rawPath, source, options = {}) {
+        if (!this.active)
+            return;
+        const observation = observeSourcePath(this.active.unit.basePath, rawPath, source);
+        const key = observation.absolutePath ?? `${observation.status}:${observation.path}`;
+        const existing = this.active.observations.get(key);
+        if (options.replaceExisting || !existing || observation.status === "whole" || existing.status !== "whole") {
+            this.active.observations.set(key, observation);
+        }
+    }
+}
+export function planDeclaredSourceEntries(task) {
+    const entries = [];
+    for (const file of task.files) {
+        const path = extractPlanningPathReference(file) ?? file.trim();
+        if (path)
+            entries.push({ path, field: "files" });
+    }
+    for (const input of task.inputs) {
+        const path = extractPlanningPathReference(input);
+        if (path)
+            entries.push({ path, field: "inputs" });
+    }
+    return entries;
+}
+export function observeSourcePath(basePath, rawPath, source) {
+    const normalizedRaw = normalizeFilePath(rawPath.trim());
+    const displayPath = normalizedRaw || rawPath.trim();
+    if (!normalizedRaw) {
+        return unavailable(displayPath || "<empty>", null, "unresolved selector", source);
+    }
+    if (containsGlobPattern(normalizedRaw)) {
+        return unavailable(displayPath, null, "glob", source, "glob selectors are not whole files");
+    }
+    if (rawPath.trim().endsWith("/")) {
+        return unavailable(displayPath, null, "directory", source, "directory selectors are not whole files");
+    }
+    const rootPath = resolve(basePath);
+    const absolutePath = isAbsolute(normalizedRaw) ? resolve(normalizedRaw) : resolve(rootPath, normalizedRaw);
+    const path = formatObservationPath(rootPath, absolutePath, displayPath);
+    if (!isPathInsideRoot(rootPath, absolutePath)) {
+        return unavailable(displayPath, absolutePath, "unresolved selector", source, "path is outside active Unit root");
+    }
+    if (!existsSync(absolutePath)) {
+        return unavailable(path, absolutePath, "missing", source, "file does not exist in the active Unit root");
+    }
+    let stat;
+    try {
+        stat = statSync(absolutePath);
+    }
+    catch {
+        return unavailable(path, absolutePath, "missing", source, "file could not be inspected");
+    }
+    if (stat.isDirectory()) {
+        return unavailable(path, absolutePath, "directory", source, "directory selectors are not whole files");
+    }
+    if (!stat.isFile()) {
+        return unavailable(path, absolutePath, "unresolved selector", source, "path is not a regular file");
+    }
+    if (stat.size > WHOLE_FILE_OBSERVATION_MAX_BYTES) {
+        return unavailable(path, absolutePath, "over-threshold", source, `${formatSize(stat.size)} exceeds ${formatSize(WHOLE_FILE_OBSERVATION_MAX_BYTES)}`);
+    }
+    let buffer;
+    try {
+        buffer = readFileSync(absolutePath);
+    }
+    catch {
+        return unavailable(path, absolutePath, "missing", source, "file could not be read");
+    }
+    if (isBinaryOrImage(buffer)) {
+        return unavailable(path, absolutePath, "binary/image", source, "binary or image files are not inlined as source text");
+    }
+    const text = buffer.toString("utf8");
+    const lines = countLines(text);
+    if (lines > WHOLE_FILE_OBSERVATION_MAX_LINES) {
+        return unavailable(path, absolutePath, "over-threshold", source, `${lines} lines exceeds ${WHOLE_FILE_OBSERVATION_MAX_LINES}`);
+    }
+    return {
+        path,
+        absolutePath,
+        status: "whole",
+        source,
+        text,
+        bytes: buffer.byteLength,
+        lines,
+    };
+}
+export function injectSourceContextBlockIntoPayload(payload, block) {
+    const messages = payload.messages;
+    if (Array.isArray(messages)) {
+        return {
+            ...payload,
+            messages: [
+                ...withoutExistingSourceContextMessages(messages),
+                { role: "user", content: [{ type: "text", text: block }] },
+            ],
+        };
+    }
+    const input = payload.input;
+    if (Array.isArray(input)) {
+        return {
+            ...payload,
+            input: [
+                ...withoutExistingSourceContextItems(input),
+                { role: "user", content: [{ type: "input_text", text: block }] },
+            ],
+        };
+    }
+    return payload;
+}
+function unavailable(path, absolutePath, status, source, reason) {
+    return { path, absolutePath, status, source, reason };
+}
+function formatObservationPath(basePath, absolutePath, fallback) {
+    const rel = relative(basePath, absolutePath);
+    if (rel && !rel.startsWith("..") && !isAbsolute(rel)) {
+        return rel.split(sep).join("/");
+    }
+    return fallback;
+}
+function isPathInsideRoot(rootPath, absolutePath) {
+    const rel = relative(rootPath, absolutePath);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+function containsGlobPattern(candidate) {
+    return ["*", "?", "[", "]", "{", "}"].some((char) => candidate.includes(char));
+}
+function readPathFromInput(input) {
+    if (typeof input.path === "string")
+        return input.path;
+    if (typeof input.file_path === "string")
+        return input.file_path;
+    return "";
+}
+function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes}B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+function isBinaryOrImage(buffer) {
+    if (buffer.includes(0))
+        return true;
+    if (startsWith(buffer, [0xff, 0xd8, 0xff]))
+        return true;
+    if (startsWith(buffer, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))
+        return true;
+    if (startsWithAscii(buffer, "GIF"))
+        return true;
+    if (startsWithAscii(buffer, "RIFF") &&
+        buffer.length >= 12 &&
+        buffer.subarray(8, 12).toString("ascii") === "WEBP")
+        return true;
+    return false;
+}
+function startsWith(buffer, signature) {
+    if (buffer.length < signature.length)
+        return false;
+    return signature.every((byte, index) => buffer[index] === byte);
+}
+function startsWithAscii(buffer, text) {
+    return buffer.length >= text.length && buffer.subarray(0, text.length).toString("ascii") === text;
+}
+function countLines(text) {
+    if (text.length === 0)
+        return 0;
+    return text.endsWith("\n") ? text.split("\n").length - 1 : text.split("\n").length;
+}
+function fencedSource(text) {
+    const longest = longestBacktickRun(text);
+    const fence = longest >= 3 ? "`".repeat(longest + 1) : "```";
+    return `${fence}\n${text}\n${fence}`;
+}
+function longestBacktickRun(text) {
+    let longest = 0;
+    let current = 0;
+    for (const char of text) {
+        if (char === "`") {
+            current += 1;
+            longest = Math.max(longest, current);
+        }
+        else {
+            current = 0;
+        }
+    }
+    return longest;
+}
+function firstText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return null;
+    const block = content.find((entry) => entry && typeof entry === "object" && "text" in entry);
+    return typeof block?.text === "string" ? block.text : null;
+}
+function isSourceContextMessage(message) {
+    if (!message || typeof message !== "object")
+        return false;
+    return firstText(message.content)?.startsWith(SOURCE_CONTEXT_TITLE) === true;
+}
+function withoutExistingSourceContextMessages(messages) {
+    return messages.filter((message) => !isSourceContextMessage(message));
+}
+function withoutExistingSourceContextItems(items) {
+    return items.filter((item) => !isSourceContextMessage(item));
+}

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

@@ -6,7 +6,7 @@
 // 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 { getAllMilestones, 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) {
@@ -17,16 +17,24 @@ function summaryMtimeIso(path) {
         return null;
     }
 }
-export function detectMissingCompletionTimestampDrift(state, ctx) {
+export function detectMissingCompletionTimestampDrift(_state, ctx) {
     if (!isDbAvailable())
         return [];
-    const mid = state.activeMilestone?.id;
-    if (!mid)
-        return [];
+    // Scan every milestone, not just the active one. Markdown artifacts exist on
+    // disk for all milestones, so a user can manually complete a queued/parked
+    // milestone (edit the roadmap + drop a SUMMARY) and leave completed_at=null
+    // in the DB. Gating on the active milestone left that drift unrepaired until
+    // the milestone happened to become active.
+    const drifts = [];
+    for (const { id: mid } of getAllMilestones()) {
+        collectMilestoneCompletionDrift(mid, ctx, drifts);
+    }
+    return drifts;
+}
+function collectMilestoneCompletionDrift(mid, ctx, drifts) {
     const milestone = getMilestone(mid);
     if (!milestone)
-        return [];
-    const drifts = [];
+        return;
     // Milestone-level
     if (COMPLETE_STATUSES.has(milestone.status) &&
         milestone.completed_at === null) {
@@ -69,7 +77,6 @@ export function detectMissingCompletionTimestampDrift(state, ctx) {
             }
         }
     }
-    return drifts;
 }
 export function repairMissingCompletionTimestamp(record, ctx) {
     const composite = record.ids[0];

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

@@ -40,6 +40,18 @@ function isRepairableStaleRenderReason(reason) {
         (reason.includes("SUMMARY.md missing") && /^S\d+/.test(reason)) ||
         reason.includes("UAT.md missing"));
 }
+function canonicalizeMilestoneId(dirSegment) {
+    if (getMilestone(dirSegment))
+        return dirSegment;
+    const suffixId = dirSegment.match(/^(M\d+-[a-z0-9]{6})(?:$|-)/)?.[1];
+    if (suffixId && getMilestone(suffixId))
+        return suffixId;
+    // Descriptor layout: e.g. M001-DESCRIPTOR → M001
+    const baseId = dirSegment.match(/^(M\d+)(?:$|-)/i)?.[1];
+    if (baseId && getMilestone(baseId))
+        return baseId;
+    return suffixId ?? baseId ?? dirSegment;
+}
 function resolveRoadmapMilestoneIdFromPath(normPath) {
     const milestoneMatch = normPath.match(/milestones\/([^/]+)\//);
     if (!milestoneMatch) {
@@ -70,7 +82,12 @@ async function repairStaleRenderFromBasePath(record, basePath) {
         if (!pathMatch) {
             throw new Error(`stale-render drift: plan path missing milestone/slice segments: ${record.renderPath}`);
         }
-        await renderPlanCheckboxes(basePath, pathMatch[1], pathMatch[2]);
+        const milestoneId = canonicalizeMilestoneId(pathMatch[1]);
+        const wrote = await renderPlanCheckboxes(basePath, milestoneId, pathMatch[2], 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`);
+        }
         return;
     }
     if (reason.includes("SUMMARY.md missing") && /^T\d+/.test(reason)) {
@@ -79,7 +96,13 @@ async function repairStaleRenderFromBasePath(record, basePath) {
         if (!pathMatch || !taskMatch) {
             throw new Error(`stale-render drift: task summary path/reason malformed: ${record.renderPath} reason=${reason}`);
         }
-        await renderTaskSummary(basePath, pathMatch[1], pathMatch[2], taskMatch[1]);
+        const milestoneId = canonicalizeMilestoneId(pathMatch[1]);
+        const wrote = await renderTaskSummary(basePath, milestoneId, pathMatch[2], taskMatch[1]);
+        if (!wrote) {
+            throw new Error(`stale-render drift: task summary re-render wrote nothing for ` +
+                `${milestoneId}/${pathMatch[2]}/${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)) {
@@ -87,7 +110,7 @@ async function repairStaleRenderFromBasePath(record, basePath) {
         if (!pathMatch) {
             throw new Error(`stale-render drift: slice summary path missing milestone/slice segments: ${record.renderPath}`);
         }
-        const milestoneId = pathMatch[1];
+        const milestoneId = canonicalizeMilestoneId(pathMatch[1]);
         const sliceId = pathMatch[2];
         const slice = getSlice(milestoneId, sliceId);
         const uatPath = join(dirname(record.renderPath), buildSliceFileName(sliceId, "UAT"));
@@ -95,7 +118,12 @@ async function repairStaleRenderFromBasePath(record, basePath) {
         if (slice?.full_uat_md && !existsSync(uatPath)) {
             setSliceSummaryMd(milestoneId, sliceId, slice.full_summary_md ?? "", "");
         }
-        await renderSliceSummary(basePath, milestoneId, sliceId);
+        const wrote = await renderSliceSummary(basePath, milestoneId, sliceId);
+        if (!wrote) {
+            throw new Error(`stale-render drift: slice summary re-render wrote nothing for ` +
+                `${milestoneId}/${sliceId} (${record.renderPath}); slice has no summary/UAT ` +
+                `in DB or its path is unresolvable`);
+        }
         return;
     }
     if (reason.includes("UAT.md missing")) {
@@ -105,7 +133,7 @@ async function repairStaleRenderFromBasePath(record, basePath) {
         }
         // 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 = pathMatch[1];
+        const milestoneId = canonicalizeMilestoneId(pathMatch[1]);
         const sliceId = pathMatch[2];
         const slice = getSlice(milestoneId, sliceId);
         if (!slice) {

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

@@ -4,26 +4,47 @@
 // laptop sleep where the heartbeat wasn't released cleanly), and clears them
 // before the next dispatch attempts to acquire the lock.
 import { effectiveLockFile, isSessionLockProcessAlive, readSessionLockData, removeStaleSessionLock, } from "../../session-lock.js";
+import { clearStaleWorkerLock } from "../../crash-recovery.js";
+import { findStaleWorkerForProject } from "../../db/auto-workers.js";
+import { isDbAvailable } from "../../gsd-db.js";
+import { normalizeRealPath } from "../../paths.js";
+import { logWarning } from "../../workflow-logger.js";
 export function detectStaleWorkerDrift(_state, ctx) {
     const data = readSessionLockData(ctx.basePath);
-    if (!data)
-        return [];
-    if (typeof data.pid !== "number")
-        return [];
-    if (isSessionLockProcessAlive(data))
-        return [];
-    return [
-        {
-            kind: "stale-worker",
-            lockPath: effectiveLockFile(),
-            pid: data.pid,
-        },
-    ];
+    if (data && typeof data.pid === "number") {
+        return isSessionLockProcessAlive(data)
+            ? []
+            : [{ kind: "stale-worker", lockPath: effectiveLockFile(), pid: data.pid }];
+    }
+    // The lock file is missing or unparseable. It is not the only source of
+    // truth: a crashed worker can leave a workers row 'active' with held leases
+    // and in-flight dispatches even when its lock file is gone. Fall back to the
+    // DB worker registry so that state is still detected and repaired.
+    if (isDbAvailable()) {
+        try {
+            const stale = findStaleWorkerForProject(normalizeRealPath(ctx.basePath));
+            if (stale && typeof stale.pid === "number") {
+                return [{ kind: "stale-worker", lockPath: effectiveLockFile(), pid: stale.pid }];
+            }
+        }
+        catch (err) {
+            // Best-effort: detection must never throw and abort the reconcile cycle.
+            logWarning("reconcile", `stale-worker DB fallback detection failed: ${err.message}`);
+        }
+    }
+    return [];
 }
 export function repairStaleWorker(_record, ctx) {
     // removeStaleSessionLock is idempotent: it re-reads lock state and is a
     // no-op when the lock is held by an alive process. Safe under cap=2 retry.
     removeStaleSessionLock(ctx.basePath);
+    // Removing the lock file alone leaves the DB-side worker state dangling: the
+    // dead worker's milestone_leases stay 'held' and its unit_dispatches stay
+    // 'running'/'claimed', blocking new claims until the lease TTL expires.
+    // clearStaleWorkerLock cancels those dispatches, releases the leases, and
+    // marks the worker stopping — the same cleanup the startup crash-recovery
+    // path performs. It is DB-gated, idempotent, and best-effort.
+    clearStaleWorkerLock(ctx.basePath);
 }
 export const staleWorkerHandler = {
     kind: "stale-worker",

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

@@ -3,6 +3,8 @@
 // reconcileBeforeDispatch runs before every Dispatch decision and worker spawn.
 import { deriveState as defaultDeriveState, invalidateStateCache as defaultInvalidate, } from "../state.js";
 import { clearParseCache as defaultClearParseCache } from "../files.js";
+import { clearPathCache } from "../paths.js";
+import { logWarning } from "../workflow-logger.js";
 import { ReconciliationFailedError, } from "./errors.js";
 import { DRIFT_REGISTRY } from "./registry.js";
 export { ReconciliationFailedError } from "./errors.js";
@@ -35,17 +37,23 @@ export async function reconcileBeforeDispatch(basePath, deps = defaultDeps) {
         deps.invalidateStateCache();
         const stateSnapshot = await deps.deriveState(basePath, deps.deriveStateOptions);
         const ctx = { basePath, state: stateSnapshot };
-        const drift = await detectAllDrift(stateSnapshot, ctx, registry, pass);
+        const detection = await detectAllDrift(stateSnapshot, ctx, registry);
+        const drift = detection.records;
         if (drift.length === 0) {
             return {
                 ok: true,
                 stateSnapshot,
                 repaired,
-                blockers: stateSnapshot.blockers ?? [],
+                blockers: [
+                    ...new Set([
+                        ...(stateSnapshot.blockers ?? []),
+                        ...detection.detectBlockers,
+                    ]),
+                ],
             };
         }
         const failures = [];
-        const blockers = [];
+        const blockers = [...detection.detectBlockers];
         let repairedThisPass = false;
         for (const record of drift) {
             const handler = registry.find((h) => h.kind === record.kind);
@@ -71,7 +79,11 @@ export async function reconcileBeforeDispatch(basePath, deps = defaultDeps) {
             }
         }
         if (repairedThisPass) {
+            // A repair may have mutated on-disk structure (e.g. quarantined a slice
+            // dir). Clear both the parse cache and the path/dir cache centrally so
+            // later passes and any subsequent repair see fresh filesystem state.
             clearParseCache();
+            clearPathCache();
         }
         if (blockers.length > 0) {
             let blockerState = stateSnapshot;
@@ -95,9 +107,10 @@ export async function reconcileBeforeDispatch(basePath, deps = defaultDeps) {
     deps.invalidateStateCache();
     const finalState = await deps.deriveState(basePath, deps.deriveStateOptions);
     const finalCtx = { basePath, state: finalState };
-    const persistent = await detectAllDrift(finalState, finalCtx, registry);
+    const finalDetection = await detectAllDrift(finalState, finalCtx, registry);
+    const persistent = finalDetection.records;
     if (persistent.length > 0) {
-        const blockers = [];
+        const blockers = [...finalDetection.detectBlockers];
         const unblockedPersistent = [];
         for (const record of persistent) {
             const handler = registry.find((h) => h.kind === record.kind);
@@ -123,24 +136,36 @@ export async function reconcileBeforeDispatch(basePath, deps = defaultDeps) {
         ok: true,
         stateSnapshot: finalState,
         repaired,
-        blockers: finalState.blockers ?? [],
+        blockers: [
+            ...new Set([
+                ...(finalState.blockers ?? []),
+                ...finalDetection.detectBlockers,
+            ]),
+        ],
     };
 }
+/**
+ * Run every detector. A single detector throwing (e.g. a transient file read
+ * error) must NOT abort the whole cycle and hide every later handler's drift —
+ * it is collected as a blocker so dispatch is still gated, while the remaining
+ * detectors run and their drift gets repaired (graceful degradation, ADR-017).
+ */
 async function detectAllDrift(state, ctx, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-registry, pass) {
-    const collected = [];
+registry) {
+    const records = [];
+    const detectBlockers = [];
     for (const handler of registry) {
         try {
             const detected = await handler.detect(state, ctx);
-            collected.push(...detected);
+            records.push(...detected);
         }
         catch (cause) {
-            throw new ReconciliationFailedError({
-                failures: [{ drift: { kind: handler.kind }, cause }],
-                pass,
-            });
+            const message = cause instanceof Error ? cause.message : String(cause);
+            const blocker = `Drift detection failed for "${handler.kind}": ${message}`;
+            logWarning("reconcile", blocker);
+            detectBlockers.push(blocker);
         }
     }
-    return collected;
+    return { records, detectBlockers };
 }

package/dist/resources/extensions/gsd/state-reconciliation/spawn-gate.js

@@ -7,10 +7,10 @@
 // startSliceParallel) share one contract.
 import { reconcileBeforeDispatch, ReconciliationFailedError, } from "./index.js";
 /**
- * Run reconciliation before spawning workers. Returns ok=true when the run
- * completed without throwing (blockers ride along but don't fail the gate —
- * spawn callers can choose how to handle them). On
- * ReconciliationFailedError, returns ok=false with the error message so the
+ * Run reconciliation before spawning workers. Returns ok=true only when the run
+ * completed without throwing AND surfaced no blockers; any blocker fails the
+ * gate (ok=false, reason carries the first blocker) so callers must not spawn.
+ * On ReconciliationFailedError, returns ok=false with the error message so the
  * caller can surface it to the user without re-throwing.
  *
  * Other unexpected errors propagate; they are not part of the drift

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

@@ -394,6 +394,8 @@ 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");
         if (!activeMilestoneFound) {
             const deps = m.depends_on;
             const depsUnmet = deps.some(dep => !completeMilestoneIds.has(dep));
@@ -401,9 +403,9 @@ async function buildRegistryAndFindActive(basePath, milestones, completeMileston
                 registry.push({ id: m.id, title, status: 'pending', dependsOn: deps });
                 continue;
             }
-            if (m.status === 'queued' && slices.length === 0) {
+            if (m.status === 'queued' && slices.length === 0 && !hasContext) {
                 if (!firstDeferredQueuedShell) {
-                    firstDeferredQueuedShell = { id: m.id, title, deps };
+                    firstDeferredQueuedShell = { id: m.id, title, deps, hasDraftContext };
                 }
                 registry.push({ id: m.id, title, status: 'pending', ...(deps.length > 0 ? { dependsOn: deps } : {}) });
                 continue;
@@ -415,7 +417,7 @@ async function buildRegistryAndFindActive(basePath, milestones, completeMileston
                 registry.push({ id: m.id, title, status: 'active', ...(deps.length > 0 ? { dependsOn: deps } : {}) });
                 continue;
             }
-            if (m.status === 'needs-discussion')
+            if ((m.status === 'needs-discussion' && !hasContext) || hasDraftContext)
                 activeMilestoneHasDraft = true;
             activeMilestone = { id: m.id, title };
             activeMilestoneSlices = slices;
@@ -432,6 +434,8 @@ async function buildRegistryAndFindActive(basePath, milestones, completeMileston
         activeMilestone = { id: shell.id, title: shell.title };
         activeMilestoneSlices = [];
         activeMilestoneFound = true;
+        if (shell.hasDraftContext)
+            activeMilestoneHasDraft = true;
         const entry = registry.find(e => e.id === shell.id);
         if (entry)
             entry.status = 'active';