@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

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

@@ -1,8 +1,7 @@
 // Project/App: gsd-pi
 // File Purpose: Runtime state derivation from GSD workflow database and legacy files.
 // GSD Extension — State Derivation
-// DB-authoritative runtime derivation with explicit legacy filesystem fallback.
-// Pure TypeScript, zero Pi dependencies.
+// DB-authoritative runtime derivation; legacy filesystem fallback in _deriveStateImpl only.
 // Pre-migration fallback ONLY (ADR-017): deriveState must work on projects
 // whose DB does not exist yet (before md-importer runs), so it parses markdown
 // projections when `isDbAvailable()` is false or the DB has no rows. Once the
@@ -10,23 +9,23 @@
 // 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 { resolveMilestoneFile, 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';
+import { isClosedStatus } from './status-guards.js';
 import { nativeBatchParseGsdFiles } from './native-parser-bridge.js';
-import { autoHealSketchFlags } from './state-reconciliation/drift/sketch-flag.js';
 import { join, resolve } from 'path';
 import { existsSync, readdirSync } from 'node:fs';
-import { debugCount, debugTime } from './debug-logger.js';
 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 { interruptedWorkNextAction, detectInterruptedWork } from './state/derive/interrupted-work.js';
+import { deriveState, getDeriveTelemetry, invalidateStateCache, resetDeriveTelemetry, } from './state/derive/index.js';
+import { deriveStateFromDb } from './state/derive/from-db.js';
+import { getRequestedMilestoneLock, syncQueueOrderProjectionToDb } from './state/derive/db-open.js';
+export { deriveState, deriveStateFromDb, getDeriveTelemetry, invalidateStateCache, resetDeriveTelemetry, };
+import { isDbAvailable, getAllMilestones, getMilestone, } from './gsd-db.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';
 /**
  * A "ghost" milestone directory contains only META.json (and no substantive
@@ -139,63 +138,6 @@ async function isTerminalMilestoneSummaryFile(path, loader) {
     const content = await loader(path);
     return content != null && isTerminalMilestoneSummaryContent(content);
 }
-const CACHE_TTL_MS = 100;
-let _stateCache = null;
-// ── Telemetry counters for derive-path observability ────────────────────────
-let _telemetry = { dbDeriveCount: 0 };
-export function getDeriveTelemetry() { return { ..._telemetry }; }
-export function resetDeriveTelemetry() { _telemetry = { dbDeriveCount: 0 }; }
-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);
-}
-/**
- * Invalidate the deriveState() cache. Call this whenever planning files on disk
- * may have changed (unit completion, merges, file writes).
- */
-export function invalidateStateCache() {
-    _stateCache = null;
-}
-/**
- * Returns the ID of the first incomplete milestone, or null if all are complete.
- */
-function getRequestedMilestoneLock() {
-    const lock = process.env.GSD_MILESTONE_LOCK?.trim();
-    return lock || undefined;
-}
 export async function getActiveMilestoneId(basePath) {
     // Milestone-scoped execution. Parallel workers and explicit solo commands
     // such as `/gsd auto M002` both set GSD_MILESTONE_LOCK; state derivation must
@@ -219,6 +161,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) {
@@ -255,70 +198,6 @@ export async function getActiveMilestoneId(basePath) {
     }
     return null;
 }
-/**
- * Reconstruct GSD state from the authoritative DB.
- * STATE.md is a rendered cache of this output.
- *
- * When DB is available, queries milestone/slice/task tables directly.
- * Runtime must not silently infer state from markdown. Use explicit recovery
- * or `/gsd migrate` when markdown is the intended source.
- */
-export async function deriveState(basePath, opts) {
-    // Use the canonical project root (when provided) as the cache key so that
-    // two calls with different basePath strings (e.g. worktree path vs project
-    // root) but the same canonical .gsd/ share a single cache entry. The same
-    // key is used for both the lookup AND the write below — keying lookup on
-    // canonical-root while writing on basePath would silently return stale
-    // results across path-form alternation.
-    const cacheKey = opts?.projectRootForReads ?? basePath;
-    // Return cached result if within the TTL window for the same cacheKey
-    if (_stateCache &&
-        _stateCache.basePath === cacheKey &&
-        Date.now() - _stateCache.timestamp < CACHE_TTL_MS) {
-        return _stateCache.result;
-    }
-    const stopTimer = debugTime("derive-state-impl");
-    let result;
-    // 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.
-    if (isDbAvailable()) {
-        const stopDbTimer = debugTime("derive-state-db");
-        result = await deriveStateFromDb(basePath, opts?.projectRootForReads ?? basePath);
-        stopDbTimer({ phase: result.phase, milestone: result.activeMilestone?.id });
-        _telemetry.dbDeriveCount++;
-    }
-    else {
-        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.recentDecisions = await loadRecentDecisions(cacheKey);
-    stopTimer({ phase: result.phase, milestone: result.activeMilestone?.id });
-    debugCount("deriveStateCalls");
-    _stateCache = { basePath: cacheKey, result, timestamp: Date.now() };
-    return result;
-}
-/**
- * Extract milestone title from CONTEXT.md or CONTEXT-DRAFT.md heading.
- * Falls back to the provided fallback (usually the milestone ID).
- */
-/**
- * Strip the "M001: " prefix from a milestone title to get the human-readable name.
- * Used by both DB and filesystem paths for consistency.
- */
 function stripMilestonePrefix(title) {
     return title.replace(/^M\d+(?:-[a-z0-9]{6})?[^:]*:\s*/, '') || title;
 }
@@ -331,447 +210,6 @@ function extractContextTitle(content, fallback) {
     // Extract title from "# M005: Platform Foundation & Separation" format
     return stripMilestonePrefix(h1.slice(2).trim()) || fallback;
 }
-// ─── DB-backed State Derivation ────────────────────────────────────────────
-// isStatusDone replaced by isClosedStatus from status-guards.ts (single source of truth).
-// Alias kept for backward compatibility within this file.
-const isStatusDone = isClosedStatus;
-/**
- * Derive GSD state from the milestones/slices/tasks DB tables.
- * Markdown files are projections only in this path; they are never imported,
- * reconciled, or used as completion signals.
- */
-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 };
-}
-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 hasContext = !!resolveMilestoneFile(basePath, m.id, "CONTEXT");
-        const hasDraftContext = !hasContext && !!resolveMilestoneFile(basePath, 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) {
-    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;
-    let activeSliceRow = activeSliceContext.activeSliceRow;
-    // Heal stale sketch flags before honoring the DB-authoritative sketch gate.
-    // This recovers if PLAN.md exists but is_sketch was never flipped to 0.
-    if (activeMilestone?.id) {
-        autoHealSketchFlags(activeMilestone.id, (sid) => {
-            const planPath = resolveSliceFile(artifactReadRoot, activeMilestone.id, sid, "PLAN");
-            return planPath !== null && existsSync(planPath);
-        });
-        activeSliceRow = getSlice(activeMilestone.id, activeSlice.id);
-    }
-    // ADR-011: DB slice metadata is authoritative for sketch refinement.
-    // 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 },
-    };
-}
 // LEGACY: Filesystem-based state derivation for unmigrated projects.
 // DB-backed projects use deriveStateFromDb() above. Target: extract to
 // state-legacy.ts when all projects are DB-backed.
@@ -1488,12 +926,8 @@ export async function _deriveStateImpl(basePath, opts) {
             }
         }
     }
-    // Check for interrupted work
-    const sDir = resolveSlicePath(basePath, activeMilestone.id, activeSlice.id);
-    const continueFile = sDir ? resolveSliceFile(basePath, activeMilestone.id, activeSlice.id, "CONTINUE") : null;
-    // Also check legacy continue.md
-    const hasInterrupted = !!(continueFile && await cachedLoadFile(continueFile)) ||
-        !!(sDir && await cachedLoadFile(join(sDir, "continue.md")));
+    // Check for interrupted work (legacy filesystem path only)
+    const hasInterrupted = await detectInterruptedWork(basePath, activeMilestone.id, activeSlice.id);
     return {
         activeMilestone,
         activeSlice,
@@ -1501,9 +935,7 @@ export async function _deriveStateImpl(basePath, opts) {
         phase: 'executing',
         recentDecisions: [],
         blockers: [],
-        nextAction: hasInterrupted
-            ? `Resume interrupted work on ${activeTask.id}: ${activeTask.title} in slice ${activeSlice.id}. Read continue.md first.`
-            : `Execute ${activeTask.id}: ${activeTask.title} in slice ${activeSlice.id}.`,
+        nextAction: interruptedWorkNextAction(activeTask.id, activeTask.title, activeSlice.id, hasInterrupted),
         registry,
         requirements,
         progress: {