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

package/src/resources/extensions/gsd/state.ts

@@ -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.
 
 import type {
   GSDState,
@@ -13,6 +12,11 @@ import type {
   MilestoneRegistryEntry,
 } from './types.js';
 
+// 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
+// DB is populated, decision reads go through gsd-db queries — these parsers
+// must never be consulted when DB data is present.
 import {
   parseRoadmap,
   parsePlan,
@@ -26,6 +30,8 @@ import {
 } from './files.js';
 
 import {
+  buildMilestoneFileName,
+  resolveFile,
   resolveMilestonePath,
   resolveMilestoneFile,
   resolveSlicePath,
@@ -40,8 +46,6 @@ import { findMilestoneIds } from './milestone-ids.js';
 import { loadQueueOrder, sortByQueueOrder } from './queue-order.js';
 import { isClosedStatus, isDeferredStatus } from './status-guards.js';
 import { nativeBatchParseGsdFiles, type BatchParsedFile } 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';
@@ -49,45 +53,53 @@ 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 { interruptedWorkNextAction, detectInterruptedWork } from './state/derive/interrupted-work.js';
+import {
+  deriveState,
+  getDeriveTelemetry,
+  invalidateStateCache,
+  resetDeriveTelemetry,
+  type DeriveStateOptions,
+} 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,
+  type DeriveStateOptions,
+};
 
 import {
   isDbAvailable,
-  wasDbOpenAttempted,
   getAllMilestones,
   getMilestone,
   getMilestoneSlices,
+  getSlicesByMilestoneIds,
   getSliceTasks,
   getReplanHistory,
   getSlice,
   getRequirementCounts,
   getLatestAssessmentByScope,
   getPendingGateCountForTurn,
+  setMilestoneQueueOrder,
 } from './gsd-db.js';
+import { openExistingWorkflowDatabase, wasWorkflowDatabaseOpenAttempted } from './db-workspace.js';
 import { formatCompletePhaseNextAction, countUnmappedActiveRequirements } from './requirements-backlog.js';
 import type { MilestoneRow } from './db-milestone-artifact-rows.js';
 import type { SliceRow, TaskRow } from './db-task-slice-rows.js';
+import {
+  classifyMilestoneReadiness,
+  readinessNeedsDiscussion,
+} from './milestone-readiness.js';
 
-function formatNeedsAttentionBlocker(milestoneId: string): string {
-  return [
-    `Milestone ${milestoneId} is blocked because milestone validation returned needs-attention.`,
-    `Fix options:`,
-    `1. Review the validation details: \`/gsd status\``,
-    `2. If you fixed the missing evidence or issue, re-run milestone validation: \`/gsd validate-milestone\``,
-    `3. If the finding is acceptable, override it: \`/gsd verdict pass --rationale "why this is okay"\``,
-    `4. If this should wait, defer it explicitly: \`/gsd park ${milestoneId}\``,
-    `After validation or override passes, run \`/gsd auto\` to complete and merge the milestone.`,
-  ].join("\n");
-}
-
-function formatNeedsRemediationBlocker(milestoneId: string): string {
-  return [
-    `Milestone ${milestoneId} is blocked because milestone validation returned needs-remediation, but all slices are complete.`,
-    `Fix options:`,
-    `1. Run \`/gsd dispatch reassess\` to add remediation slices, then run \`/gsd auto\``,
-    `2. If the finding is acceptable, override it: \`/gsd verdict pass --rationale "why this is okay"\``,
-    `3. If this should wait, defer it explicitly: \`/gsd park ${milestoneId}\``,
-  ].join("\n");
-}
+import {
+  needsAttentionBlockerGuidance as formatNeedsAttentionBlocker,
+  needsRemediationBlockerGuidance as formatNeedsRemediationBlocker,
+} from './guidance.js';
 
 /**
  * A "ghost" milestone directory contains only META.json (and no substantive
@@ -210,79 +222,6 @@ async function isTerminalMilestoneSummaryFile(
   return content != null && isTerminalMilestoneSummaryContent(content);
 }
 
-// ─── State Derivation ──────────────────────────────────────────────────────
-
-// ── deriveState memoization ─────────────────────────────────────────────────
-// Cache the most recent deriveState() result keyed by basePath. Within a single
-// dispatch cycle (~100ms window), repeated calls return the cached value instead
-// of re-reading the entire .gsd/ tree from disk.
-
-interface StateCache {
-  basePath: string;
-  result: GSDState;
-  timestamp: number;
-}
-
-const CACHE_TTL_MS = 100;
-let _stateCache: StateCache | null = 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: string): Promise<string[]> {
-  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 is string => 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(): void {
-  _stateCache = null;
-}
-
-/**
- * Returns the ID of the first incomplete milestone, or null if all are complete.
- */
-function getRequestedMilestoneLock(): string | undefined {
-  const lock = process.env.GSD_MILESTONE_LOCK?.trim();
-  return lock || undefined;
-}
 
 export async function getActiveMilestoneId(basePath: string): Promise<string | null> {
   // Milestone-scoped execution. Parallel workers and explicit solo commands
@@ -306,6 +245,7 @@ export async function getActiveMilestoneId(basePath: string): Promise<string | n
 
   // 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) {
@@ -339,94 +279,6 @@ export async function getActiveMilestoneId(basePath: string): Promise<string | n
   return null;
 }
 
-/**
- * Options for deriveState read-path routing.
- *
- * `projectRootForReads`: canonical project root (e.g. from
- * `s.canonicalProjectRoot`) used for both the cache key and the artifact-read
- * root in `_deriveStateImpl`. When omitted, behavior is identical to the
- * single-arg signature (back-compat for all existing callers).
- *
- * Typed as an object literal (not `string | DeriveStateOptions`) so accidental
- * `deriveState(path, "string")` is rejected at compile time.
- */
-export interface DeriveStateOptions {
-  projectRootForReads?: string;
-}
-
-/**
- * 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: string,
-  opts?: DeriveStateOptions,
-): Promise<GSDState> {
-  // 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: GSDState;
-
-  // 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 (wasDbOpenAttempted()) {
-      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: string): string {
   return title.replace(/^M\d+(?:-[a-z0-9]{6})?[^:]*:\s*/, '') || title;
 }
@@ -439,515 +291,6 @@ function extractContextTitle(content: string | null, fallback: string): string {
   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: string, milestones: MilestoneRow[]) {
-  const completeMilestoneIds = new Set<string>();
-  const parkedMilestoneIds = new Set<string>();
-
-  // 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: string,
-  milestones: MilestoneRow[],
-  completeMilestoneIds: Set<string>,
-  parkedMilestoneIds: Set<string>
-) {
-  const registry: MilestoneRegistryEntry[] = [];
-  let activeMilestone: ActiveRef | null = null;
-  let activeMilestoneSlices: SliceRow[] = [];
-  let activeMilestoneFound = false;
-  let activeMilestoneHasDraft = false;
-  let firstDeferredQueuedShell: { id: string; title: string; deps: string[]; hasDraftContext: boolean } | null = null;
-
-  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 = getMilestoneSlices(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");
-
-    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 (m.status === 'queued' && slices.length === 0 && !hasContext) {
-        if (!firstDeferredQueuedShell) {
-          firstDeferredQueuedShell = { id: m.id, title, deps, 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 ((m.status === 'needs-discussion' && !hasContext) || hasDraftContext) 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: MilestoneRegistryEntry[],
-  requirements: any,
-  milestoneProgress: { done: number, total: number }
-): GSDState {
-  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: string,
-  activeMilestone: ActiveRef,
-  registry: MilestoneRegistryEntry[],
-  requirements: any,
-  milestoneProgress: { done: number, total: number },
-  sliceProgress: { done: number, total: number }
-): Promise<GSDState> {
-  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: SliceRow[]): { activeSlice: ActiveRef | null, activeSliceRow: SliceRow | null } {
-  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: string, milestoneId: string, sliceId: string, tasks: TaskRow[]): Promise<string | null> {
-  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: string, milestoneId: string, sliceId: string): boolean {
-  const sliceRow = getSlice(milestoneId, sliceId);
-  return !!sliceRow?.replan_triggered_at;
-}
-
-export async function deriveStateFromDb(
-  basePath: string,
-  artifactReadRoot: string = basePath,
-): Promise<GSDState> {
-  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' as const : 'pre-planning' as const;
-    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: ActiveRef = { 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
@@ -1698,12 +1041,12 @@ export async function _deriveStateImpl(
     }
   }
 
-  // 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,
@@ -1712,9 +1055,12 @@ export async function _deriveStateImpl(
     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: {