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

package/src/resources/extensions/gsd/state-reconciliation/drift/stale-render.ts

@@ -6,9 +6,6 @@
 // had zero callers in production code — wiring it through
 // reconcileBeforeDispatch closes that gap.
 
-import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-
 import {
   detectStaleRenders,
   renderPlanCheckboxes,
@@ -16,8 +13,8 @@ import {
   renderSliceSummary,
   renderTaskSummary,
 } from "../../markdown-renderer.js";
-import { getMilestone, getSlice, setSliceSummaryMd } from "../../gsd-db.js";
-import { buildSliceFileName } from "../../paths.js";
+import { getMilestone, getMilestoneSlices, getSlice, getSliceTasks, setSliceSummaryMd } from "../../gsd-db.js";
+import { resolveSliceFile } from "../../paths.js";
 import type { GSDState } from "../../types.js";
 import { logWarning } from "../../workflow-logger.js";
 import type { DriftContext, DriftHandler, DriftRecord } from "../types.js";
@@ -70,11 +67,21 @@ function canonicalizeMilestoneId(dirSegment: string): string {
   const baseId = dirSegment.match(/^(M\d+)(?:$|-)/i)?.[1];
   if (baseId && getMilestone(baseId)) return baseId;
 
+  // Flat-phase: e.g. 01-test → M001
+  const phaseMatch = dirSegment.match(/^(\d+)-/);
+  if (phaseMatch) {
+    const flatId = `M${String(parseInt(phaseMatch[1]!, 10)).padStart(3, "0")}`;
+    if (getMilestone(flatId)) return flatId;
+  }
+
   return suffixId ?? baseId ?? dirSegment;
 }
 
 function resolveRoadmapMilestoneIdFromPath(normPath: string): string {
-  const milestoneMatch = normPath.match(/milestones\/([^/]+)\//);
+  // Flat-phase: phases/NN-slug/NN-ROADMAP.md
+  // Legacy: milestones/MID/MID-ROADMAP.md
+  const milestoneMatch = normPath.match(/phases\/([^/]+)\//)
+    || normPath.match(/milestones\/([^/]+)\//);
   if (!milestoneMatch) {
     throw new Error(
       `stale-render drift: roadmap path missing milestone segment: ${normPath}`,
@@ -82,11 +89,15 @@ function resolveRoadmapMilestoneIdFromPath(normPath: string): string {
   }
 
   const fileMatch = normPath.match(/(?:^|\/)([^/]+)-ROADMAP\.md$/i);
+  // For flat-phase, derive milestone id from phase number prefix
+  const phaseNumMatch = milestoneMatch[1]!.match(/^(\d+)-/);
+  const phaseDerivedId = phaseNumMatch ? `M${String(parseInt(phaseNumMatch[1]!, 10)).padStart(3, "0")}` : null;
   const candidates = [
     fileMatch?.[1],
     milestoneMatch[1],
+    phaseDerivedId,
     fileMatch?.[1]?.match(/^(M\d+)/i)?.[1],
-    milestoneMatch[1].match(/^(M\d+)/i)?.[1],
+    milestoneMatch[1]!.match(/^(M\d+)/i)?.[1],
   ].filter((candidate): candidate is string => !!candidate);
 
   for (const candidate of candidates) {
@@ -112,17 +123,23 @@ async function repairStaleRenderFromBasePath(
   }
 
   if (reason.includes("in plan")) {
-    const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
+    // Flat-phase: phases/NN-slug/NN-MM-PLAN.md
+    // Legacy: milestones/X/slices/Y/PLAN.md
+    const pathMatch = normPath.match(/phases\/([^/]+)\/(\d+)-(\d+)-PLAN/)
+      || normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
     if (!pathMatch) {
       throw new Error(
         `stale-render drift: plan path missing milestone/slice segments: ${record.renderPath}`,
       );
     }
-    const milestoneId = canonicalizeMilestoneId(pathMatch[1]);
+    const milestoneId = canonicalizeMilestoneId(pathMatch[1]!);
+    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,
-      pathMatch[2],
+      sliceId,
       record.renderPath,
     );
     if (!wrote) {
@@ -135,21 +152,44 @@ async function repairStaleRenderFromBasePath(
   }
 
   if (reason.includes("SUMMARY.md missing") && /^T\d+/.test(reason)) {
-    const pathMatch = normPath.match(
-      /milestones\/([^/]+)\/slices\/([^/]+)\/tasks\//,
-    );
+    // Flat-phase: phases/NN-slug/ (no tasks/ subdir, task summaries in phase dir)
+    // Legacy: milestones/X/slices/Y/tasks/
+    const pathMatch = normPath.match(/phases\/([^/]+)\//)
+      || normPath.match(
+        /milestones\/([^/]+)\/slices\/([^/]+)\/tasks\//,
+      );
     const taskMatch = reason.match(/^(T\d+)/);
     if (!pathMatch || !taskMatch) {
       throw new Error(
         `stale-render drift: task summary path/reason malformed: ${record.renderPath} reason=${reason}`,
       );
     }
-    const milestoneId = canonicalizeMilestoneId(pathMatch[1]);
-    const wrote = await renderTaskSummary(basePath, milestoneId, pathMatch[2], taskMatch[1]);
+    const milestoneId = canonicalizeMilestoneId(pathMatch[1]!);
+    // In flat-phase there's no slice segment in the path; find the task's slice from DB.
+    let sliceId: string;
+    if (pathMatch[2]) {
+      sliceId = pathMatch[2];
+    } else {
+      // Flat-phase: scan milestone's slices for the task
+      let foundSliceId: string | undefined;
+      for (const s of getMilestoneSlices(milestoneId)) {
+        if (getSliceTasks(milestoneId, s.id).some(t => t.id === taskMatch[1])) {
+          foundSliceId = s.id;
+          break;
+        }
+      }
+      if (!foundSliceId) {
+        throw new Error(
+          `stale-render drift: task ${taskMatch[1]} not found in any slice of ${milestoneId} (${record.renderPath})`,
+        );
+      }
+      sliceId = foundSliceId;
+    }
+    const wrote = await renderTaskSummary(basePath, milestoneId, sliceId, taskMatch[1]!);
     if (!wrote) {
       throw new Error(
         `stale-render drift: task summary re-render wrote nothing for ` +
-          `${milestoneId}/${pathMatch[2]}/${taskMatch[1]} (${record.renderPath}); ` +
+          `${milestoneId}/${sliceId}/${taskMatch[1]} (${record.renderPath}); ` +
           `task has no summary in DB or its slice path is unresolvable`,
       );
     }
@@ -157,18 +197,40 @@ async function repairStaleRenderFromBasePath(
   }
 
   if (reason.includes("SUMMARY.md missing") && /^S\d+/.test(reason)) {
-    const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
+    // Flat-phase: phases/NN-slug/NN-MM-SUMMARY.md or phases/NN-slug/NN-SUMMARY.md
+    // Legacy: milestones/X/slices/Y/SUMMARY.md
+    const pathMatch = normPath.match(/phases\/([^/]+)\/(\d+)-(\d+)-SUMMARY/)
+      || normPath.match(/phases\/([^/]+)\/(\d+)-SUMMARY/)
+      || normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
     if (!pathMatch) {
       throw new Error(
         `stale-render drift: slice summary path missing milestone/slice segments: ${record.renderPath}`,
       );
     }
-    const milestoneId = canonicalizeMilestoneId(pathMatch[1]);
-    const sliceId = pathMatch[2];
+    // Flat-phase: groups are (phaseDir, phaseNum, planNum) for NN-MM-SUMMARY,
+    // or (phaseDir, phaseNum) for NN-SUMMARY (phase-level). In the latter case,
+    // derive slice from the reason text which starts with S\d+.
+    // Legacy: groups are (milestoneDir, sliceDir).
+    let milestoneId: string;
+    let sliceId: string;
+    milestoneId = canonicalizeMilestoneId(pathMatch[1]!);
+    if (pathMatch[3] && /^\d+$/.test(pathMatch[2]!)) {
+      // NN-MM-SUMMARY: pathMatch[3] is the plan number
+      sliceId = `S${String(parseInt(pathMatch[3]!, 10)).padStart(2, "0")}`;
+    } else if (pathMatch[2] && /^S\d+/.test(pathMatch[2])) {
+      // Legacy: pathMatch[2] is the slice dir name
+      sliceId = pathMatch[2];
+    } else {
+      // NN-SUMMARY (phase-level): derive slice from reason
+      const reasonSlice = reason.match(/^(S\d+)/);
+      sliceId = reasonSlice ? reasonSlice[1] : "S01";
+    }
     const slice = getSlice(milestoneId, sliceId);
-    const uatPath = join(dirname(record.renderPath), buildSliceFileName(sliceId, "UAT"));
+    // Use resolveSliceFile so the UAT existence check matches the NN-MM-UAT.md
+    // name that renderSliceSummary actually writes (buildSliceFileName only yields MM-UAT.md).
+    const uatPath = resolveSliceFile(basePath, milestoneId, sliceId, "UAT");
     // renderSliceSummary writes both artifacts, so clear deleted UAT first.
-    if (slice?.full_uat_md && !existsSync(uatPath)) {
+    if (slice?.full_uat_md && !uatPath) {
       setSliceSummaryMd(milestoneId, sliceId, slice.full_summary_md ?? "", "");
     }
     const wrote = await renderSliceSummary(basePath, milestoneId, sliceId);
@@ -183,16 +245,26 @@ async function repairStaleRenderFromBasePath(
   }
 
   if (reason.includes("UAT.md missing")) {
-    const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
+    // Flat-phase: phases/NN-slug/NN-MM-UAT.md or phases/NN-slug/NN-UAT.md
+    // Legacy: milestones/X/slices/Y/UAT.md
+    const pathMatch = normPath.match(/phases\/([^/]+)\/(\d+)-(\d+)-UAT/)
+      || normPath.match(/phases\/([^/]+)\/(\d+)-UAT/)
+      || normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
     if (!pathMatch) {
       throw new Error(
         `stale-render drift: UAT path missing milestone/slice segments: ${record.renderPath}`,
       );
     }
-    // When UAT.md is removed from disk, mirror that intent by clearing stale
-    // persisted UAT content instead of rehydrating it back onto disk.
-    const milestoneId = canonicalizeMilestoneId(pathMatch[1]);
-    const sliceId = pathMatch[2];
+    const milestoneId = canonicalizeMilestoneId(pathMatch[1]!);
+    let sliceId: string;
+    if (pathMatch[3] && /^\d+$/.test(pathMatch[2]!)) {
+      sliceId = `S${String(parseInt(pathMatch[3]!, 10)).padStart(2, "0")}`;
+    } else if (pathMatch[2] && /^S\d+/.test(pathMatch[2])) {
+      sliceId = pathMatch[2];
+    } else {
+      const reasonSlice = reason.match(/(S\d+)/);
+      sliceId = reasonSlice ? reasonSlice[1] : "S01";
+    }
     const slice = getSlice(milestoneId, sliceId);
     if (!slice) {
       throw new Error(

package/src/resources/extensions/gsd/state-reconciliation/index.ts

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

package/src/resources/extensions/gsd/state-reconciliation/registry.ts

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

package/src/resources/extensions/gsd/state-reconciliation/types.ts

@@ -43,6 +43,21 @@ export type DriftRecord =
       kind: "missing-completion-timestamp";
       entity: "task" | "slice" | "milestone";
       ids: string[];
+    }
+  | {
+      kind: "external-markdown-edit";
+      projectionPath: string;       // relative to basePath, e.g. "m1/plan.md"
+      expectedSha: string;          // sha recorded in .compat.json
+      actualSha: string;            // freshly computed from disk
+      entities: string[];           // DB entity ids to re-import
+    }
+  | {
+      kind: "external-planning-edit";
+      projectionPath: string;       // relative to .planning/, e.g. "phases/01-foo/01-01-PLAN.md"
+      expectedSha: string;
+      actualSha: string;
+      entities: string[];
+      passthrough: boolean;         // true = content-only, no re-import, just refresh sha
     };
 
 /**
@@ -52,6 +67,8 @@ export type DriftRecord =
 export interface DriftContext {
   basePath: string;
   state: GSDState;
+  /** When true, detectors must not persist compat marker changes. */
+  dryRun?: boolean;
 }
 
 /**
@@ -111,4 +128,6 @@ export interface ReconciliationDeps {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   registry?: ReadonlyArray<DriftHandler<any>>;
   deriveStateOptions?: DeriveStateOptions;
+  /** When true, detect drift but do not run repairs (read-only preview). */
+  dryRun?: boolean;
 }

package/src/resources/extensions/gsd/state-transition-matrix.ts

@@ -131,6 +131,48 @@ export function findTransition(
   );
 }
 
+/**
+ * Edge-keyed legality check for the Phase Transition Invariant (ADR-030).
+ * `advance()` derives the next Phase and asserts the (from → to) edge here.
+ *
+ * The matrix is an assertion, not a decision-maker — `deriveState` already
+ * chose the Phase. A self-edge is trivially legal (no transition to assert). An
+ * edge is legal when some matrix entry permits it, honoring the `*` wildcard
+ * rows (e.g. any → blocked via manual-block, any → executing via
+ * retryable-failure).
+ *
+ * Note: the matrix is currently a sparse hardening spec, not a complete
+ * legal-edge graph, so `advance()` consumes this in advisory mode (telemetry
+ * only). It must be expanded to cover every edge `deriveState` emits before
+ * enforcement flips on.
+ */
+export function isLegalEdge(from: Phase, to: Phase): boolean {
+  if (from === to) return true;
+  return STATE_TRANSITION_MATRIX.some(
+    (entry) => (entry.from === from || entry.from === "*") && entry.to === to,
+  );
+}
+
+/**
+ * Thrown when an illegal derived Phase edge survives reconciliation. Carries
+ * both endpoints so Recovery Classification can report them. Recognized by
+ * class in `classifyFailure` and mapped to the `illegal-transition` kind.
+ */
+export class IllegalPhaseTransitionError extends Error {
+  // Explicit fields, not constructor parameter properties — strip-types
+  // consumers (workspace-index subprocess, integration tests) reject the
+  // parameter-property syntax with ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX.
+  readonly from: Phase;
+  readonly to: Phase;
+
+  constructor(from: Phase, to: Phase) {
+    super(`Illegal phase transition ${from} -> ${to} survived reconciliation`);
+    this.name = "IllegalPhaseTransitionError";
+    this.from = from;
+    this.to = to;
+  }
+}
+
 export function validateTransitionMatrix(requiredEvents: readonly string[]): MatrixValidationResult {
   const seen = new Set<string>();
   const duplicateKeys: string[] = [];

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

@@ -13,6 +13,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 +31,8 @@ import {
 } from './files.js';
 
 import {
+  buildMilestoneFileName,
+  resolveFile,
   resolveMilestonePath,
   resolveMilestoneFile,
   resolveSlicePath,
@@ -52,42 +59,31 @@ import { isTerminalMilestoneSummaryContent } from './milestone-summary-classifie
 
 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
@@ -276,6 +272,38 @@ export function invalidateStateCache(): void {
   _stateCache = null;
 }
 
+function syncQueueOrderProjectionToDb(basePath: string): void {
+  const queueOrder = loadQueueOrder(basePath);
+  if (!queueOrder) return;
+
+  const currentIds = getAllMilestones().map((m) => m.id);
+  const desiredIds = sortByQueueOrder(currentIds, queueOrder);
+  if (currentIds.length === desiredIds.length && currentIds.every((id, i) => id === desiredIds[i])) return;
+
+  setMilestoneQueueOrder(desiredIds);
+}
+
+function ensureExistingWorkflowDbOpen(basePath: string): boolean {
+  const opened = isDbAvailable() || openExistingWorkflowDatabase(basePath).ok;
+  if (opened) syncQueueOrderProjectionToDb(basePath);
+  return opened;
+}
+
+function buildDbUnavailableState(): GSDState {
+  return {
+    activeMilestone: null,
+    activeSlice: null,
+    activeTask: null,
+    phase: "pre-planning",
+    recentDecisions: [],
+    blockers: ["DB unavailable — runtime markdown state derivation is disabled"],
+    nextAction: "Open or create the canonical GSD database before deriving workflow state. If this project only has markdown state, run /gsd migrate explicitly.",
+    registry: [],
+    requirements: { active: 0, validated: 0, deferred: 0, outOfScope: 0, blocked: 0, total: 0 },
+    progress: { milestones: { done: 0, total: 0 } },
+  };
+}
+
 /**
  * Returns the ID of the first incomplete milestone, or null if all are complete.
  */
@@ -306,6 +334,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) {
@@ -389,27 +418,18 @@ export async function deriveState(
   // DB-backed derivation is authoritative whenever the DB is open. Runtime
   // degrade must not infer state from ROADMAP.md, PLAN.md, SUMMARY.md,
   // REQUIREMENTS.md, or flag files.
+  ensureExistingWorkflowDbOpen(basePath);
+
   if (isDbAvailable()) {
     const stopDbTimer = debugTime("derive-state-db");
     result = await deriveStateFromDb(basePath, opts?.projectRootForReads ?? basePath);
     stopDbTimer({ phase: result.phase, milestone: result.activeMilestone?.id });
     _telemetry.dbDeriveCount++;
   } else {
-    if (wasDbOpenAttempted()) {
+    if (wasWorkflowDatabaseOpenAttempted()) {
       logWarning("state", "DB unavailable — refusing implicit markdown state derivation");
     }
-    result = {
-      activeMilestone: null,
-      activeSlice: null,
-      activeTask: null,
-      phase: "pre-planning",
-      recentDecisions: [],
-      blockers: ["DB unavailable — runtime markdown state derivation is disabled"],
-      nextAction: "Open or create the canonical GSD database before deriving workflow state. If this project only has markdown state, run /gsd migrate explicitly.",
-      registry: [],
-      requirements: { active: 0, validated: 0, deferred: 0, outOfScope: 0, blocked: 0, total: 0 },
-      progress: { milestones: { done: 0, total: 0 } },
-    };
+    result = buildDbUnavailableState();
   }
 
   result.recentDecisions = await loadRecentDecisions(cacheKey);
@@ -472,6 +492,16 @@ function buildCompletenessSet(basePath: string, milestones: MilestoneRow[]) {
   return { completeMilestoneIds, parkedMilestoneIds };
 }
 
+function milestoneArtifactExistsInResolvedDir(
+  milestoneDir: string | null,
+  milestoneId: string,
+  suffix: string,
+): boolean {
+  if (!milestoneDir) return false;
+  const flatPath = join(milestoneDir, buildMilestoneFileName(milestoneId, suffix));
+  return existsSync(flatPath) || resolveFile(milestoneDir, milestoneId, suffix) !== null;
+}
+
 async function buildRegistryAndFindActive(
   basePath: string,
   milestones: MilestoneRow[],
@@ -485,13 +515,18 @@ async function buildRegistryAndFindActive(
   let activeMilestoneHasDraft = false;
   let firstDeferredQueuedShell: { id: string; title: string; deps: string[]; hasDraftContext: boolean } | null = 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 = getMilestoneSlices(m.id);
+    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
@@ -505,8 +540,15 @@ async function buildRegistryAndFindActive(
     const allSlicesDone = slices.length > 0 && slices.every(s => isStatusDone(s.status));
 
     const title = stripMilestonePrefix(m.title) || m.id;
-    const hasContext = !!resolveMilestoneFile(basePath, m.id, "CONTEXT");
-    const hasDraftContext = !hasContext && !!resolveMilestoneFile(basePath, m.id, "CONTEXT-DRAFT");
+    const milestoneDir = resolveMilestonePath(basePath, m.id);
+    const hasContext = milestoneArtifactExistsInResolvedDir(milestoneDir, m.id, "CONTEXT");
+    const hasDraftContext = !hasContext && milestoneArtifactExistsInResolvedDir(milestoneDir, m.id, "CONTEXT-DRAFT");
+    const readiness = classifyMilestoneReadiness({
+      status: m.status,
+      hasContext,
+      hasDraftContext,
+      sliceCount: slices.length,
+    });
 
     if (!activeMilestoneFound) {
       const deps = m.depends_on;
@@ -517,9 +559,9 @@ async function buildRegistryAndFindActive(
         continue;
       }
 
-      if (m.status === 'queued' && slices.length === 0 && !hasContext) {
+      if (readiness.kind === 'queued-shell') {
         if (!firstDeferredQueuedShell) {
-          firstDeferredQueuedShell = { id: m.id, title, deps, hasDraftContext };
+          firstDeferredQueuedShell = { id: m.id, title, deps, hasDraftContext: readiness.hasDraftContext };
         }
         registry.push({ id: m.id, title, status: 'pending', ...(deps.length > 0 ? { dependsOn: deps } : {}) });
         continue;
@@ -533,7 +575,7 @@ async function buildRegistryAndFindActive(
         continue;
       }
 
-      if ((m.status === 'needs-discussion' && !hasContext) || hasDraftContext) activeMilestoneHasDraft = true;
+      if (readinessNeedsDiscussion(readiness)) activeMilestoneHasDraft = true;
 
       activeMilestone = { id: m.id, title };
       activeMilestoneSlices = slices;
@@ -726,6 +768,10 @@ export async function deriveStateFromDb(
   basePath: string,
   artifactReadRoot: string = basePath,
 ): Promise<GSDState> {
+  if (!ensureExistingWorkflowDbOpen(basePath)) {
+    return buildDbUnavailableState();
+  }
+
   const requirements = getRequirementCounts();
 
   const allMilestones = getAllMilestones();