@opengsd/gsd-pi 1.3.0-dev.65546769 → 1.3.0-dev.72e3af2a

package/dist/resources/extensions/gsd/state/derive/from-db.js

@@ -0,0 +1,452 @@
+// Project/App: gsd-pi
+// File Purpose: DB-backed GSD state derivation pipeline stage.
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { isClosedStatus, isDeferredStatus } from '../../status-guards.js';
+import { buildMilestoneFileName, resolveFile, resolveMilestonePath, } from '../../paths.js';
+import { getAllMilestones, getLatestAssessmentByScope, getPendingGateCountForTurn, getReplanHistory, getRequirementCounts, getSlice, getSliceTasks, getSlicesByMilestoneIds, } from '../../gsd-db.js';
+import { classifyMilestoneReadiness, readinessNeedsDiscussion, } from '../../milestone-readiness.js';
+import { needsAttentionBlockerGuidance as formatNeedsAttentionBlocker, needsRemediationBlockerGuidance as formatNeedsRemediationBlocker, } from '../../guidance.js';
+import { detectPendingEscalation } from '../../escalation.js';
+import { countUnmappedActiveRequirements, formatCompletePhaseNextAction } from '../../requirements-backlog.js';
+import { logWarning } from '../../workflow-logger.js';
+import { buildDbUnavailableState, ensureExistingWorkflowDbOpen, getRequestedMilestoneLock, } from './db-open.js';
+const isStatusDone = isClosedStatus;
+function stripMilestonePrefix(title) {
+    return title.replace(/^M\d+(?:-[a-z0-9]{6})?[^:]*:\s*/, '') || title;
+}
+function buildCompletenessSet(basePath, milestones) {
+    const completeMilestoneIds = new Set();
+    const parkedMilestoneIds = new Set();
+    // DB-authoritative: a milestone is only "complete" when its DB row says so.
+    // SUMMARY-file presence is NOT a completion signal here — an orphan SUMMARY
+    // (crashed complete-milestone turn, partial merge, manual edit) must not
+    // flip derived state to complete and cascade into a false auto-merge (#4179).
+    for (const m of milestones) {
+        if (m.status === 'parked') {
+            parkedMilestoneIds.add(m.id);
+            continue;
+        }
+        if (isStatusDone(m.status)) {
+            completeMilestoneIds.add(m.id);
+            continue;
+        }
+    }
+    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;
+    let activeMilestoneSlices = [];
+    let activeMilestoneFound = false;
+    let activeMilestoneHasDraft = false;
+    let firstDeferredQueuedShell = null;
+    const activeMilestoneIds = milestones
+        .filter((m) => !parkedMilestoneIds.has(m.id))
+        .map((m) => m.id);
+    const slicesByMilestone = getSlicesByMilestoneIds(activeMilestoneIds);
+    for (const m of milestones) {
+        if (parkedMilestoneIds.has(m.id)) {
+            registry.push({ id: m.id, title: stripMilestonePrefix(m.title) || m.id, status: 'parked' });
+            continue;
+        }
+        const slices = slicesByMilestone.get(m.id) ?? [];
+        // DB-authoritative completeness (#4179): only trust completeMilestoneIds,
+        // which is itself derived from DB status. SUMMARY-file presence alone must
+        // not imply completion.
+        if (completeMilestoneIds.has(m.id)) {
+            const title = stripMilestonePrefix(m.title) || m.id;
+            registry.push({ id: m.id, title, status: 'complete' });
+            continue;
+        }
+        const allSlicesDone = slices.length > 0 && slices.every(s => isStatusDone(s.status));
+        const title = stripMilestonePrefix(m.title) || m.id;
+        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,
+            hasDraftContext,
+            sliceCount: slices.length,
+        });
+        if (!activeMilestoneFound) {
+            const deps = m.depends_on;
+            const depsUnmet = deps.some(dep => !completeMilestoneIds.has(dep));
+            if (depsUnmet) {
+                registry.push({ id: m.id, title, status: 'pending', dependsOn: deps });
+                continue;
+            }
+            if (readiness.kind === 'queued-shell') {
+                if (!firstDeferredQueuedShell) {
+                    firstDeferredQueuedShell = { id: m.id, title, deps, hasDraftContext: readiness.hasDraftContext };
+                }
+                registry.push({ id: m.id, title, status: 'pending', ...(deps.length > 0 ? { dependsOn: deps } : {}) });
+                continue;
+            }
+            if (allSlicesDone) {
+                activeMilestone = { id: m.id, title };
+                activeMilestoneSlices = slices;
+                activeMilestoneFound = true;
+                registry.push({ id: m.id, title, status: 'active', ...(deps.length > 0 ? { dependsOn: deps } : {}) });
+                continue;
+            }
+            if (readinessNeedsDiscussion(readiness))
+                activeMilestoneHasDraft = true;
+            activeMilestone = { id: m.id, title };
+            activeMilestoneSlices = slices;
+            activeMilestoneFound = true;
+            registry.push({ id: m.id, title, status: 'active', ...(deps.length > 0 ? { dependsOn: deps } : {}) });
+        }
+        else {
+            const deps = m.depends_on;
+            registry.push({ id: m.id, title, status: 'pending', ...(deps.length > 0 ? { dependsOn: deps } : {}) });
+        }
+    }
+    if (!activeMilestoneFound && firstDeferredQueuedShell) {
+        const shell = firstDeferredQueuedShell;
+        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';
+    }
+    return { registry, activeMilestone, activeMilestoneSlices, activeMilestoneHasDraft };
+}
+function handleNoActiveMilestone(registry, requirements, milestoneProgress) {
+    const pendingEntries = registry.filter(e => e.status === 'pending');
+    const parkedEntries = registry.filter(e => e.status === 'parked');
+    if (pendingEntries.length > 0) {
+        const blockerDetails = pendingEntries
+            .filter(e => e.dependsOn && e.dependsOn.length > 0)
+            .map(e => `${e.id} is waiting on unmet deps: ${e.dependsOn.join(', ')}`);
+        return {
+            activeMilestone: null, activeSlice: null, activeTask: null,
+            phase: 'blocked',
+            recentDecisions: [], blockers: blockerDetails.length > 0
+                ? blockerDetails
+                : ['All remaining milestones are dep-blocked but no deps listed — check CONTEXT.md files'],
+            nextAction: 'Resolve milestone dependencies before proceeding.',
+            registry, requirements,
+            progress: { milestones: milestoneProgress },
+        };
+    }
+    if (parkedEntries.length > 0) {
+        const parkedIds = parkedEntries.map(e => e.id).join(', ');
+        return {
+            activeMilestone: null, activeSlice: null, activeTask: null,
+            phase: 'pre-planning',
+            recentDecisions: [], blockers: [],
+            nextAction: `All remaining milestones are parked (${parkedIds}). Run /gsd unpark <id> or create a new milestone.`,
+            registry, requirements,
+            progress: { milestones: milestoneProgress },
+        };
+    }
+    if (registry.length === 0) {
+        return {
+            activeMilestone: null, activeSlice: null, activeTask: null,
+            phase: 'pre-planning',
+            recentDecisions: [], blockers: [],
+            nextAction: 'No milestones found. Run /gsd to create one.',
+            registry: [], requirements,
+            progress: { milestones: { done: 0, total: 0 } },
+        };
+    }
+    const lastEntry = registry[registry.length - 1];
+    const unmappedActive = countUnmappedActiveRequirements();
+    const completionNote = formatCompletePhaseNextAction(unmappedActive);
+    return {
+        activeMilestone: null,
+        lastCompletedMilestone: lastEntry ? { id: lastEntry.id, title: lastEntry.title } : null,
+        activeSlice: null, activeTask: null,
+        phase: 'complete',
+        recentDecisions: [], blockers: [],
+        nextAction: completionNote,
+        registry, requirements,
+        progress: { milestones: milestoneProgress },
+    };
+}
+async function handleAllSlicesDone(basePath, activeMilestone, registry, requirements, milestoneProgress, sliceProgress) {
+    const validation = getLatestAssessmentByScope(activeMilestone.id, "milestone-validation");
+    const verdict = typeof validation?.status === "string" ? validation.status : undefined;
+    const validationTerminal = verdict != null && verdict !== "";
+    if (!validationTerminal) {
+        return {
+            activeMilestone, activeSlice: null, activeTask: null,
+            phase: 'validating-milestone',
+            recentDecisions: [], blockers: [],
+            nextAction: `Validate milestone ${activeMilestone.id} before completion.`,
+            registry, requirements,
+            progress: { milestones: milestoneProgress, slices: sliceProgress },
+        };
+    }
+    // All roadmap slices are done (enforced by caller) and verdict is
+    // needs-remediation — remediation cannot progress without new slices.
+    // Return blocked instead of re-dispatching validate-milestone (#4506).
+    if (verdict === 'needs-attention') {
+        return {
+            activeMilestone, activeSlice: null, activeTask: null,
+            phase: 'blocked',
+            recentDecisions: [],
+            blockers: [formatNeedsAttentionBlocker(activeMilestone.id)],
+            nextAction: `Resolve ${activeMilestone.id} validation attention before proceeding.`,
+            registry, requirements,
+            progress: { milestones: milestoneProgress, slices: sliceProgress },
+        };
+    }
+    if (verdict === 'needs-remediation') {
+        return {
+            activeMilestone, activeSlice: null, activeTask: null,
+            phase: 'blocked',
+            recentDecisions: [],
+            blockers: [formatNeedsRemediationBlocker(activeMilestone.id)],
+            nextAction: `Resolve ${activeMilestone.id} remediation before proceeding.`,
+            registry, requirements,
+            progress: { milestones: milestoneProgress, slices: sliceProgress },
+        };
+    }
+    return {
+        activeMilestone, activeSlice: null, activeTask: null,
+        phase: 'completing-milestone',
+        recentDecisions: [], blockers: [],
+        nextAction: `All slices complete in ${activeMilestone.id}. Write milestone summary.`,
+        registry, requirements,
+        progress: { milestones: milestoneProgress, slices: sliceProgress },
+    };
+}
+function resolveSliceDependencies(activeMilestoneSlices) {
+    const doneSliceIds = new Set(activeMilestoneSlices.filter(s => isStatusDone(s.status)).map(s => s.id));
+    const sliceLock = process.env.GSD_PARALLEL_WORKER ? process.env.GSD_SLICE_LOCK : undefined;
+    if (sliceLock) {
+        const lockedSlice = activeMilestoneSlices.find(s => s.id === sliceLock);
+        if (lockedSlice) {
+            return { activeSlice: { id: lockedSlice.id, title: lockedSlice.title }, activeSliceRow: lockedSlice };
+        }
+        else {
+            logWarning("state", `GSD_SLICE_LOCK=${sliceLock} not found in active slices — worker has no assigned work`);
+            return { activeSlice: null, activeSliceRow: null };
+        }
+    }
+    for (const s of activeMilestoneSlices) {
+        if (isStatusDone(s.status))
+            continue;
+        if (isDeferredStatus(s.status))
+            continue;
+        if (s.depends.every(dep => doneSliceIds.has(dep))) {
+            return { activeSlice: { id: s.id, title: s.title }, activeSliceRow: s };
+        }
+    }
+    return { activeSlice: null, activeSliceRow: null };
+}
+async function detectBlockers(basePath, milestoneId, sliceId, tasks) {
+    const completedTasks = tasks.filter(t => isStatusDone(t.status));
+    for (const ct of completedTasks) {
+        if (ct.blocker_discovered) {
+            return ct.id;
+        }
+    }
+    return null;
+}
+function checkReplanTrigger(basePath, milestoneId, sliceId) {
+    const sliceRow = getSlice(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();
+    const milestones = milestoneLock
+        ? allMilestones.filter(m => m.id === milestoneLock)
+        : allMilestones;
+    if (milestones.length === 0) {
+        return {
+            activeMilestone: null, activeSlice: null, activeTask: null,
+            phase: 'pre-planning', recentDecisions: [], blockers: [],
+            nextAction: 'No milestones found. Run /gsd to create one.',
+            registry: [], requirements,
+            progress: { milestones: { done: 0, total: 0 } },
+        };
+    }
+    const { completeMilestoneIds, parkedMilestoneIds } = buildCompletenessSet(basePath, milestones);
+    const registryContext = await buildRegistryAndFindActive(basePath, milestones, completeMilestoneIds, parkedMilestoneIds);
+    const { registry, activeMilestone, activeMilestoneSlices, activeMilestoneHasDraft } = registryContext;
+    const milestoneProgress = {
+        done: registry.filter(e => e.status === 'complete').length,
+        total: registry.length,
+    };
+    if (!activeMilestone) {
+        return handleNoActiveMilestone(registry, requirements, milestoneProgress);
+    }
+    if (activeMilestoneSlices.length === 0) {
+        const phase = activeMilestoneHasDraft ? 'needs-discussion' : 'pre-planning';
+        const nextAction = activeMilestoneHasDraft
+            ? `Discuss draft context for milestone ${activeMilestone.id}.`
+            : `Plan milestone ${activeMilestone.id}.`;
+        return {
+            activeMilestone, activeSlice: null, activeTask: null,
+            phase, recentDecisions: [], blockers: [],
+            nextAction, registry, requirements,
+            progress: { milestones: milestoneProgress },
+        };
+    }
+    const allSlicesDone = activeMilestoneSlices.every(s => isStatusDone(s.status));
+    const sliceProgress = {
+        done: activeMilestoneSlices.filter(s => isStatusDone(s.status)).length,
+        total: activeMilestoneSlices.length,
+    };
+    if (allSlicesDone) {
+        return handleAllSlicesDone(basePath, activeMilestone, registry, requirements, milestoneProgress, sliceProgress);
+    }
+    const activeSliceContext = resolveSliceDependencies(activeMilestoneSlices);
+    if (!activeSliceContext.activeSlice) {
+        // If locked slice wasn't found, it returns null but logs warning, we need to return 'blocked'
+        const sliceLock = process.env.GSD_PARALLEL_WORKER ? process.env.GSD_SLICE_LOCK : undefined;
+        if (sliceLock) {
+            return {
+                activeMilestone, activeSlice: null, activeTask: null,
+                phase: 'blocked', recentDecisions: [], blockers: [`GSD_SLICE_LOCK=${sliceLock} not found in active milestone slices`],
+                nextAction: 'Slice lock references a non-existent slice — check orchestrator dispatch.',
+                registry, requirements,
+                progress: { milestones: milestoneProgress, slices: sliceProgress },
+            };
+        }
+        return {
+            activeMilestone, activeSlice: null, activeTask: null,
+            phase: 'blocked', recentDecisions: [], blockers: ['No slice eligible — check dependency ordering'],
+            nextAction: 'Resolve dependency blockers or plan next slice.',
+            registry, requirements,
+            progress: { milestones: milestoneProgress, slices: sliceProgress },
+        };
+    }
+    const { activeSlice } = activeSliceContext;
+    const activeSliceRow = activeSliceContext.activeSliceRow;
+    // ADR-011: DB slice metadata is authoritative for sketch refinement.
+    // Stale sketch flags (PLAN on disk but is_sketch=1) are repaired by
+    // sketchFlagHandler via reconcileBeforeDispatch — not during derivation.
+    // PLAN.md and preference flags are projections/configuration and are
+    // deliberately not used to infer whether the slice itself is a sketch.
+    if (activeSliceRow?.is_sketch === 1) {
+        return {
+            activeMilestone, activeSlice, activeTask: null,
+            phase: 'refining', recentDecisions: [], blockers: [],
+            nextAction: `Refine sketch slice ${activeSlice.id} (${activeSlice.title}) using prior slice context.`,
+            registry, requirements,
+            progress: { milestones: milestoneProgress, slices: sliceProgress },
+        };
+    }
+    const tasks = getSliceTasks(activeMilestone.id, activeSlice.id);
+    const taskProgress = {
+        done: tasks.filter(t => isStatusDone(t.status)).length,
+        total: tasks.length,
+    };
+    const activeTaskRow = tasks.find(t => !isStatusDone(t.status));
+    if (!activeTaskRow && tasks.length > 0) {
+        return {
+            activeMilestone, activeSlice, activeTask: null,
+            phase: 'summarizing', recentDecisions: [], blockers: [],
+            nextAction: `All tasks done in ${activeSlice.id}. Write slice summary and complete slice.`,
+            registry, requirements,
+            progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
+        };
+    }
+    if (!activeTaskRow) {
+        return {
+            activeMilestone, activeSlice, activeTask: null,
+            phase: 'planning', recentDecisions: [], blockers: [],
+            nextAction: `Slice ${activeSlice.id} has no DB tasks. Plan slice tasks before execution.`,
+            registry, requirements,
+            progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
+        };
+    }
+    const activeTask = { id: activeTaskRow.id, title: activeTaskRow.title };
+    // ── Quality gate evaluation check ──────────────────────────────────
+    // Pause before execution only when gates owned by the `gate-evaluate`
+    // turn (Q3/Q4) are still pending. Q8 is also `scope:"slice"` but is
+    // owned by `complete-slice`, so it must NOT block the evaluating-gates
+    // phase — otherwise auto-loop stalls forever waiting for a gate that
+    // this turn never evaluates. See gate-registry.ts for the ownership map.
+    // Slices with zero gate rows (pre-feature or simple) skip straight through.
+    const pendingGateCount = getPendingGateCountForTurn(activeMilestone.id, activeSlice.id, "gate-evaluate");
+    if (pendingGateCount > 0) {
+        return {
+            activeMilestone, activeSlice, activeTask: null,
+            phase: 'evaluating-gates', recentDecisions: [], blockers: [],
+            nextAction: `Evaluate ${pendingGateCount} quality gate(s) for ${activeSlice.id} before execution.`,
+            registry, requirements,
+            progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
+        };
+    }
+    const blockerTaskId = await detectBlockers(basePath, activeMilestone.id, activeSlice.id, tasks);
+    if (blockerTaskId) {
+        const replanHistory = getReplanHistory(activeMilestone.id, activeSlice.id);
+        if (replanHistory.length === 0) {
+            return {
+                activeMilestone, activeSlice, activeTask,
+                phase: 'replanning-slice', recentDecisions: [],
+                blockers: [`Task ${blockerTaskId} discovered a blocker requiring slice replan`],
+                nextAction: `Task ${blockerTaskId} reported blocker_discovered. Replan slice ${activeSlice.id} before continuing.`,
+                activeWorkspace: undefined,
+                registry, requirements,
+                progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
+            };
+        }
+    }
+    // ADR-011 Phase 2: pause-on-escalation takes precedence over dispatching the
+    // next task. `awaiting_review` tasks (continueWithDefault=true) still pause
+    // here so silence is never treated as consent.
+    //
+    // We do NOT gate this on `phases.mid_execution_escalation` — creation of
+    // new escalations is gated at the write site (tools/complete-task.ts:315),
+    // but any escalation_pending row already persisted in the DB must be
+    // honored even if the user later toggles the flag off. Otherwise those
+    // rows would silently orphan, the loop would advance past the paused task,
+    // and the user's prior resolution never lands.
+    const escalatingTaskId = detectPendingEscalation(tasks, basePath);
+    if (escalatingTaskId) {
+        return {
+            activeMilestone, activeSlice, activeTask,
+            phase: 'escalating-task', recentDecisions: [],
+            blockers: [`Task ${escalatingTaskId} requires a user decision before the loop can proceed`],
+            nextAction: `Run /gsd escalate show ${escalatingTaskId} to review, then /gsd escalate resolve ${escalatingTaskId} <choice> to proceed.`,
+            activeWorkspace: undefined,
+            registry, requirements,
+            progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
+        };
+    }
+    if (!blockerTaskId) {
+        const isTriggered = checkReplanTrigger(basePath, activeMilestone.id, activeSlice.id);
+        if (isTriggered) {
+            const replanHistory = getReplanHistory(activeMilestone.id, activeSlice.id);
+            if (replanHistory.length === 0) {
+                return {
+                    activeMilestone, activeSlice, activeTask,
+                    phase: 'replanning-slice', recentDecisions: [],
+                    blockers: ['Triage replan trigger detected — slice replan required'],
+                    nextAction: `Triage replan triggered for slice ${activeSlice.id}. Replan before continuing.`,
+                    activeWorkspace: undefined,
+                    registry, requirements,
+                    progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
+                };
+            }
+        }
+    }
+    return {
+        activeMilestone, activeSlice, activeTask,
+        phase: 'executing', recentDecisions: [], blockers: [],
+        nextAction: `Execute ${activeTask.id}: ${activeTask.title} in slice ${activeSlice.id}.`,
+        registry, requirements,
+        progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
+    };
+}

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

@@ -0,0 +1,75 @@
+// Project/App: gsd-pi
+// File Purpose: deriveState orchestrator — cache, DB open, pure DB projection.
+import { loadFile } from '../../files.js';
+import { resolveGsdRootFile } from '../../paths.js';
+import { isDbAvailable } from '../../gsd-db.js';
+import { wasWorkflowDatabaseOpenAttempted } from '../../db-workspace.js';
+import { debugCount, debugTime } from '../../debug-logger.js';
+import { logWarning } from '../../workflow-logger.js';
+import { getDeriveTelemetry, incrementDbDeriveCount, invalidateStateCache, readCachedDeriveState, resetDeriveTelemetry, writeCachedDeriveState, } from './cache.js';
+import { buildDbUnavailableState, ensureExistingWorkflowDbOpen, } from './db-open.js';
+import { deriveStateFromDb } from './from-db.js';
+export { getDeriveTelemetry, invalidateStateCache, resetDeriveTelemetry, };
+async function loadRecentDecisions(basePath) {
+    const decisionsPath = resolveGsdRootFile(basePath, "DECISIONS");
+    const content = await loadFile(decisionsPath);
+    if (!content)
+        return [];
+    const fromTable = content
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith("|"))
+        .map((line) => {
+        const cells = line
+            .split("|")
+            .map((cell) => cell.trim())
+            .filter((cell) => cell.length > 0);
+        if (cells.length < 6)
+            return null;
+        const id = cells[0];
+        if (!/^D\d+$/i.test(id))
+            return null;
+        const whenContext = cells[1];
+        const decision = cells[3];
+        const choice = cells[4];
+        if (!decision || !choice)
+            return null;
+        return `${id} (${whenContext}): ${decision} -> ${choice}`;
+    })
+        .filter((value) => value != null);
+    if (fromTable.length > 0)
+        return fromTable.slice(-5);
+    const fromBullets = content
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => /^-\s+/.test(line))
+        .map((line) => line.replace(/^-+\s+/, ""))
+        .filter((line) => /^D\d+\b/i.test(line));
+    return fromBullets.slice(-5);
+}
+export async function deriveState(basePath, opts) {
+    const cacheKey = opts?.projectRootForReads ?? basePath;
+    const cached = readCachedDeriveState(cacheKey);
+    if (cached)
+        return cached;
+    const stopTimer = debugTime("derive-state-impl");
+    let result;
+    ensureExistingWorkflowDbOpen(basePath);
+    if (isDbAvailable()) {
+        const stopDbTimer = debugTime("derive-state-db");
+        result = await deriveStateFromDb(basePath, opts?.projectRootForReads ?? basePath);
+        stopDbTimer({ phase: result.phase, milestone: result.activeMilestone?.id });
+        incrementDbDeriveCount();
+    }
+    else {
+        if (wasWorkflowDatabaseOpenAttempted()) {
+            logWarning("state", "DB unavailable — refusing implicit markdown state derivation");
+        }
+        result = buildDbUnavailableState();
+    }
+    result.recentDecisions = await loadRecentDecisions(cacheKey);
+    stopTimer({ phase: result.phase, milestone: result.activeMilestone?.id });
+    debugCount("deriveStateCalls");
+    writeCachedDeriveState(cacheKey, result);
+    return result;
+}

package/dist/resources/extensions/gsd/state/derive/interrupted-work.js

@@ -0,0 +1,21 @@
+// Project/App: gsd-pi
+// File Purpose: Detect interrupted slice work from CONTINUE artifacts (legacy path).
+import { join } from 'node:path';
+import { loadFile } from '../../files.js';
+import { resolveSliceFile, resolveSlicePath } from '../../paths.js';
+export async function detectInterruptedWork(basePath, milestoneId, sliceId) {
+    const sliceDir = resolveSlicePath(basePath, milestoneId, sliceId);
+    const continueFile = sliceDir
+        ? resolveSliceFile(basePath, milestoneId, sliceId, "CONTINUE")
+        : null;
+    if (continueFile && await loadFile(continueFile))
+        return true;
+    if (sliceDir && await loadFile(join(sliceDir, "continue.md")))
+        return true;
+    return false;
+}
+export function interruptedWorkNextAction(taskId, taskTitle, sliceId, interrupted) {
+    return interrupted
+        ? `Resume interrupted work on ${taskId}: ${taskTitle} in slice ${sliceId}. Read continue.md first.`
+        : `Execute ${taskId}: ${taskTitle} in slice ${sliceId}.`;
+}

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

@@ -6,9 +6,11 @@
 // had zero callers in production code — wiring it through
 // reconcileBeforeDispatch closes that gap.
 import { detectStaleRenders, renderPlanCheckboxes, renderRoadmapFromDb, renderSliceSummary, renderTaskSummary, } from "../../markdown-renderer.js";
-import { getMilestone, getMilestoneSlices, getSlice, getSliceTasks, setSliceSummaryMd } from "../../gsd-db.js";
+import { getMilestone, getMilestoneSlices, getSlice, getSliceTasks, setSliceSummaryMd, } from "../../gsd-db.js";
+import { ensureWorkflowDbForBase, } from "../../db-workspace.js";
 import { resolveSliceFile } from "../../paths.js";
 import { logWarning } from "../../workflow-logger.js";
+const VALIDATION_BLOCK_RE = /milestone validation returned needs-(?:attention|remediation)|validation verdict is needs-(?:attention|remediation)/i;
 // ─── Core (basePath-only — usable by both drift API and legacy wrapper) ──────
 function detectStaleRenderDriftFromBasePath(basePath) {
     const entries = detectStaleRenders(basePath);
@@ -38,6 +40,17 @@ function isRepairableStaleRenderReason(reason) {
         (reason.includes("SUMMARY.md missing") && /^S\d+/.test(reason)) ||
         reason.includes("UAT.md missing"));
 }
+function validationBlocker(state) {
+    if (state.phase !== "blocked")
+        return null;
+    return state.blockers.find((blocker) => VALIDATION_BLOCK_RE.test(blocker)) ?? null;
+}
+function isMilestoneSummaryMissing(record) {
+    const normPath = record.renderPath.replace(/\\/g, "/");
+    return (record.reason.includes("SUMMARY.md missing") &&
+        (/^M\d+(?:\b|[-_:])/.test(record.reason) ||
+            /(?:^|\/)M\d+(?:-[a-z0-9]+)?-SUMMARY\.md$/i.test(normPath)));
+}
 function canonicalizeMilestoneId(dirSegment) {
     if (getMilestone(dirSegment))
         return dirSegment;
@@ -82,7 +95,16 @@ function resolveRoadmapMilestoneIdFromPath(normPath) {
     }
     return fileMatch?.[1] ?? milestoneMatch[1];
 }
+function ensureDbForStaleRenderRepair(basePath) {
+    return ensureWorkflowDbForBase(basePath);
+}
+function retryDbForStaleRenderRepair(basePath) {
+    return ensureWorkflowDbForBase(basePath, { refresh: true });
+}
 async function repairStaleRenderFromBasePath(record, basePath) {
+    if (!ensureDbForStaleRenderRepair(basePath)) {
+        throw new Error(`stale-render drift: database unavailable for repair (${basePath})`);
+    }
     const normPath = record.renderPath.replace(/\\/g, "/");
     const reason = record.reason;
     if (reason.includes("in roadmap")) {
@@ -101,7 +123,18 @@ async function repairStaleRenderFromBasePath(record, basePath) {
         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);
+        let wrote = false;
+        try {
+            wrote = await renderPlanCheckboxes(basePath, milestoneId, sliceId, record.renderPath);
+        }
+        catch (err) {
+            if (!retryDbForStaleRenderRepair(basePath))
+                throw err;
+            wrote = await renderPlanCheckboxes(basePath, milestoneId, sliceId, record.renderPath);
+        }
+        if (!wrote && retryDbForStaleRenderRepair(basePath)) {
+            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`);
@@ -227,9 +260,19 @@ export function detectStaleRenderDrift(_state, ctx) {
 export async function repairStaleRender(record, ctx) {
     await repairStaleRenderFromBasePath(record, ctx.basePath);
 }
+export function staleRenderBlocker(record, ctx) {
+    const blocker = validationBlocker(ctx.state);
+    if (!blocker || !isMilestoneSummaryMissing(record))
+        return null;
+    return [
+        `Stale milestone summary render at ${record.renderPath} is blocked by milestone validation.`,
+        blocker,
+    ].join("\n");
+}
 export const staleRenderHandler = {
     kind: "stale-render",
     detect: detectStaleRenderDrift,
+    blocker: staleRenderBlocker,
     repair: repairStaleRender,
 };
 // ─── Legacy entry point ──────────────────────────────────────────────────────