@opengsd/gsd-pi 1.1.1-dev.b2556262 → 1.2.0-dev.0b870afa

package/dist/resources/extensions/gsd/recovery-classification.js

@@ -1,7 +1,10 @@
 // Project/App: gsd-pi
 // File Purpose: ADR-015 Recovery Classification module for runtime failure taxonomy.
+import { isToolUnavailableError } from "./auto-tool-tracking.js";
 import { classifyError, isTransient } from "./error-classifier.js";
+import { recoveryRemediation } from "./guidance.js";
 import { ReconciliationFailedError } from "./state-reconciliation.js";
+import { IllegalPhaseTransitionError } from "./state-transition-matrix.js";
 export function classifyFailure(input) {
     const message = errorMessage(input.error);
     // ADR-017: ReconciliationFailedError is a typed throw from the State
@@ -9,96 +12,47 @@ export function classifyFailure(input) {
     // failureKind so the taxonomy stays consistent.
     const failureKind = input.error instanceof ReconciliationFailedError
         ? "reconciliation-drift"
-        : input.failureKind ?? inferFailureKind(message);
-    switch (failureKind) {
-        case "tool-schema":
-            return {
-                failureKind,
-                action: "stop",
-                reason: `Tool schema failure${unitSuffix(input)}: ${message}`,
-                exitReason: "tool-schema",
-                remediation: "Fix the Unit Tool Contract or tool schema before retrying.",
-            };
-        case "tool-contract":
-            return {
-                failureKind,
-                action: "stop",
-                reason: `Tool Contract failure${unitSuffix(input)}: ${message}`,
-                exitReason: "tool-contract",
-                remediation: "Fix the Unit Tool Contract or prompt so the Unit is only asked to use tools owned by its phase.",
-            };
-        case "deterministic-policy":
-            return {
-                failureKind,
-                action: "stop",
-                reason: `Deterministic policy failure${unitSuffix(input)}: ${message}`,
-                exitReason: "deterministic-policy",
-                remediation: "Resolve the policy blocker; retrying the same Unit will repeat the failure.",
-            };
-        case "lifecycle-progression":
-            return {
-                failureKind,
-                action: "stop",
-                reason: `Lifecycle progression failure${unitSuffix(input)}: ${message}`,
-                exitReason: "lifecycle-progression",
-                remediation: "Route to the required owning Unit or restore the missing artifact before advancing lifecycle state.",
-            };
-        case "stale-worker":
-            return {
-                failureKind,
-                action: "stop",
-                reason: `Stale worker failure${unitSuffix(input)}: ${message}`,
-                exitReason: "stale-worker",
-                remediation: "Clear or reconcile the stale worker before dispatching another Unit.",
-            };
-        case "worktree-invalid":
-            return {
-                failureKind,
-                action: "stop",
-                reason: `Worktree invalid${unitSuffix(input)}: ${message}`,
-                exitReason: "worktree-invalid",
-                remediation: "Repair or recreate the milestone worktree before launching source-writing Units.",
-            };
-        case "verification-drift":
-            return {
-                failureKind,
-                action: "escalate",
-                reason: `Verification drift${unitSuffix(input)}: ${message}`,
-                exitReason: "verification-drift",
-                remediation: "Inspect the verification artifact and reconcile the state snapshot before resuming.",
-            };
-        case "reconciliation-drift":
-            return {
-                failureKind,
-                action: "escalate",
-                reason: `Reconciliation drift${unitSuffix(input)}: ${message}`,
-                exitReason: "reconciliation-drift",
-                remediation: "Inspect the persistent or repair-failed drift kinds reported by the State Reconciliation Module before resuming.",
-            };
-        case "provider": {
-            const providerClass = classifyError(message, input.retryAfterMs);
-            return {
-                failureKind,
-                action: isTransient(providerClass) ? "retry" : "escalate",
-                reason: message,
-                exitReason: `provider-${providerClass.kind}`,
-                remediation: isTransient(providerClass)
-                    ? "Retry after the provider/network condition clears."
-                    : "Inspect provider credentials, model entitlement, or request shape.",
-                providerClass: providerClass.kind,
-            };
-        }
-        case "runtime-unknown":
-            return {
-                failureKind,
-                action: "escalate",
-                reason: message,
-                exitReason: "runtime-unknown",
-                remediation: "Inspect the runtime error and add a dedicated classification if it is repeatable.",
-            };
+        : input.error instanceof IllegalPhaseTransitionError
+            ? "illegal-transition"
+            : input.failureKind ?? inferFailureKind(message);
+    if (failureKind === "provider") {
+        const providerClass = classifyError(message, input.retryAfterMs);
+        const transient = isTransient(providerClass);
+        return {
+            failureKind,
+            action: transient ? "retry" : "escalate",
+            reason: message,
+            exitReason: `provider-${providerClass.kind}`,
+            remediation: recoveryRemediation(transient ? "provider-transient" : "provider-permanent"),
+            providerClass: providerClass.kind,
+        };
     }
+    const { action, label } = FAILURE_TAXONOMY[failureKind];
+    return {
+        failureKind,
+        action,
+        reason: label ? `${label}${unitSuffix(input)}: ${message}` : message,
+        exitReason: failureKind,
+        remediation: recoveryRemediation(failureKind),
+    };
 }
+/** Per-kind action and reason label. Remediation lives in the Guidance module. */
+const FAILURE_TAXONOMY = {
+    "tool-schema": { action: "stop", label: "Tool schema failure" },
+    "tool-contract": { action: "stop", label: "Tool Contract failure" },
+    "tool-unavailable": { action: "retry", label: "Tool unavailable" },
+    "deterministic-policy": { action: "stop", label: "Deterministic policy failure" },
+    "lifecycle-progression": { action: "stop", label: "Lifecycle progression failure" },
+    "stale-worker": { action: "stop", label: "Stale worker failure" },
+    "worktree-invalid": { action: "stop", label: "Worktree invalid" },
+    "verification-drift": { action: "escalate", label: "Verification drift" },
+    "reconciliation-drift": { action: "escalate", label: "Reconciliation drift" },
+    "illegal-transition": { action: "escalate", label: "Illegal phase transition" },
+    "runtime-unknown": { action: "escalate", label: null },
+};
 function inferFailureKind(message) {
+    if (isToolUnavailableError(message))
+        return "tool-unavailable";
     if (/tool contract|auto-unit tool scope|phase-boundary gate|not permitted.*own/i.test(message))
         return "tool-contract";
     if (/lifecycle progression|required artifact|missing .*assessment|missing .*closeout|cannot legally (?:advance|progress)/i.test(message))

package/dist/resources/extensions/gsd/roadmap-slices.js

@@ -161,6 +161,26 @@ function parseTableSlices(section) {
     }
     return slices;
 }
+function looksLikeTable(section) {
+    const lines = section.split("\n");
+    // Checkbox format takes precedence — embedded demo tables must not switch mode (#721).
+    if (lines.some(line => /^\s*-\s+\[[ xX]\]/.test(line))) {
+        return false;
+    }
+    const pipeLines = lines.filter(line => /^\s*\|/.test(line));
+    if (pipeLines.length < 2)
+        return false;
+    const hasSeparatorRow = pipeLines.some((line, index) => {
+        if (index === 0)
+            return false;
+        const cells = line.split("|").map(c => c.trim()).filter(Boolean);
+        return /^\s*\|[\s:-]+\|/.test(line) && cells.length >= 2 && cells.every(c => /^[\s:-]+$/.test(c));
+    });
+    if (hasSeparatorRow)
+        return true;
+    // Tables without a separator row still expose slice IDs in data rows.
+    return pipeLines.some(line => /\bS\d+\b/.test(line));
+}
 export function parseRoadmapSlices(content) {
     const slicesSection = extractSlicesSection(content);
     if (!slicesSection) {
@@ -171,9 +191,11 @@ export function parseRoadmapSlices(content) {
     }
     // Try table format first — if the section contains pipe-delimited rows with
     // slice IDs, parse them as a table (#1736).
-    const tableSlices = parseTableSlices(slicesSection);
-    if (tableSlices.length > 0) {
-        return tableSlices;
+    if (looksLikeTable(slicesSection)) {
+        const tableSlices = parseTableSlices(slicesSection);
+        if (tableSlices.length > 0) {
+            return tableSlices;
+        }
     }
     // Standard checkbox format
     const slices = [];
@@ -191,9 +213,15 @@ export function parseRoadmapSlices(content) {
             const riskMatch = rest.match(/`risk:(\w+)`/);
             const risk = (riskMatch ? riskMatch[1] : "low");
             const depsMatch = rest.match(/`depends:\[([^\]]*)\]`/);
-            const depends = depsMatch && depsMatch[1].trim()
-                ? expandDependencies(depsMatch[1].split(",").map(s => s.trim()))
+            // Recovery fallback: double-bracket form `[[id]]` from serialized bracket-wrapped IDs
+            const fallbackDepsMatch = depsMatch ? null : rest.match(/`depends:\[(\[(?:[^\]]*)\](?:,\[(?:[^\]]*)\])*)\]`/);
+            const rawDepContent = (depsMatch ?? fallbackDepsMatch)?.[1] ?? "";
+            const SLICE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9-]*$/;
+            const RANGE_RE = /^[A-Za-z]+\d+(?:-|\.\.)[A-Za-z]+\d+$/;
+            const rawDepParts = rawDepContent.trim()
+                ? rawDepContent.replace(/\[|\]/g, "").split(",").map(s => s.trim()).filter(s => SLICE_ID_RE.test(s) || RANGE_RE.test(s))
                 : [];
+            const depends = expandDependencies(rawDepParts);
             // ADR-011: the renderer writes a `[sketch]` badge for sketch slices.
             // Parse it back so the is_sketch flag survives a markdown → DB re-import
             // (e.g. /gsd recover); otherwise the flag was silently lost.

package/dist/resources/extensions/gsd/safety/destructive-confirmation.js

@@ -0,0 +1,108 @@
+/**
+ * One-shot confirmation token for destructive bash commands.
+ *
+ * The destructive-command guard hard-blocks classified commands (force push,
+ * rm -rf, SQL drop, etc.) in all modes. The block instructs the model to
+ * confirm via ask_user_questions and re-issue the command. This module is the
+ * missing escape hatch: it records the user's confirmation and lets the exact
+ * confirmed command through exactly once.
+ *
+ * Design constraints:
+ *  - In-memory only, never persisted. A confirmation token written to disk
+ *    could silently auto-approve a destructive command in a later session —
+ *    confirmation must be re-obtained every process lifetime.
+ *  - One-shot. Consuming a token clears it, so a second destructive command
+ *    (even an identical one) re-blocks and re-prompts.
+ *  - Command-bound. The token only matches the exact (normalized) command
+ *    string the user confirmed. A reworded command re-blocks, which is safe.
+ *  - Per basePath, so concurrent workspaces in one process never share tokens.
+ *
+ * Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+ */
+import { resolve } from "node:path";
+/**
+ * Question-id substring that marks an ask_user_questions call as a
+ * destructive-command confirmation. The tool_result handler promotes the
+ * pending command to a confirmed token when an affirmative answer arrives for
+ * a question whose id contains this marker.
+ */
+export const DESTRUCTIVE_CONFIRM_GATE_MARKER = "destructive_confirm";
+const statesByBasePath = new Map();
+function stateKey(basePath) {
+    return resolve(basePath);
+}
+function getState(basePath) {
+    const key = stateKey(basePath);
+    let state = statesByBasePath.get(key);
+    if (!state) {
+        state = { pendingCommand: null, confirmedCommand: null };
+        statesByBasePath.set(key, state);
+    }
+    return state;
+}
+/**
+ * Normalize a command for stable matching across block → confirm → retry.
+ * Trims surrounding whitespace and collapses internal runs of whitespace so
+ * cosmetic reformatting of the same command still matches the token.
+ */
+export function normalizeDestructiveCommand(command) {
+    return command.replace(/\s+/g, " ").trim();
+}
+/**
+ * Whether an ask_user_questions question id is a destructive-confirm gate.
+ */
+export function isDestructiveConfirmGateId(questionId) {
+    return typeof questionId === "string" && questionId.includes(DESTRUCTIVE_CONFIRM_GATE_MARKER);
+}
+/**
+ * Record that a destructive command was blocked and is awaiting confirmation.
+ * Called by the guard at block time. Overwrites any prior pending command —
+ * only the most recently blocked command can be confirmed.
+ */
+export function requestDestructiveConfirmation(command, basePath = process.cwd()) {
+    const state = getState(basePath);
+    state.pendingCommand = normalizeDestructiveCommand(command);
+    // A fresh request invalidates any stale confirmed token for a different
+    // command so confirmation cannot leak across distinct destructive actions.
+    state.confirmedCommand = null;
+}
+/**
+ * Promote the pending command to a confirmed, one-shot token. Called by the
+ * tool_result handler when the user gives an affirmative answer to a
+ * destructive-confirm gate. Returns the confirmed command, or null if there
+ * was nothing pending (e.g. confirmation arrived without a preceding block).
+ */
+export function confirmDestructiveCommand(basePath = process.cwd()) {
+    const state = getState(basePath);
+    if (!state.pendingCommand)
+        return null;
+    state.confirmedCommand = state.pendingCommand;
+    state.pendingCommand = null;
+    return state.confirmedCommand;
+}
+/**
+ * Check whether the given command has been confirmed, consuming the token if
+ * so. Returns true exactly once per confirmation; subsequent calls (or a
+ * non-matching command) return false. Called by the guard before blocking.
+ */
+export function consumeDestructiveConfirmation(command, basePath = process.cwd()) {
+    const state = getState(basePath);
+    if (!state.confirmedCommand)
+        return false;
+    if (state.confirmedCommand !== normalizeDestructiveCommand(command))
+        return false;
+    state.confirmedCommand = null;
+    return true;
+}
+/**
+ * Inspect the pending command without consuming it (diagnostics/tests).
+ */
+export function peekPendingDestructiveCommand(basePath = process.cwd()) {
+    return getState(basePath).pendingCommand;
+}
+/**
+ * Clear all destructive-confirmation state for a basePath (tests / flow reset).
+ */
+export function resetDestructiveConfirmation(basePath = process.cwd()) {
+    statesByBasePath.delete(stateKey(basePath));
+}

package/dist/resources/extensions/gsd/safety/evidence-collector.js

@@ -21,9 +21,10 @@ const EXECUTION_TOOL_NAMES = new Set([
     "functions.exec_command",
     "gsd_exec",
     "gsd_exec_search",
+    "gsd_uat_exec",
     "powershell",
 ]);
-const MCP_EXECUTION_TOOL_RE = /^mcp__.+__gsd_exec(?:_search)?$/;
+const MCP_EXECUTION_TOOL_RE = /^mcp__.+__gsd_(?:uat_)?exec(?:_search)?$/;
 // ─── Module State ───────────────────────────────────────────────────────────
 let unitEvidence = [];
 // ─── Public API ─────────────────────────────────────────────────────────────
@@ -146,11 +147,18 @@ export function clearEvidenceFromDisk(basePath, milestoneId, sliceId, taskId) {
  * Exit codes and output are filled in by recordToolResult after execution.
  */
 export function recordToolCall(toolCallId, toolName, input) {
+    // Idempotent by toolCallId: native tools reach this via both
+    // tool_execution_start and tool_call; external (pre-executed) tools only
+    // via tool_execution_start. First recording wins.
+    if (unitEvidence.some(e => e.toolCallId === toolCallId))
+        return;
     if (isExecutionToolName(toolName)) {
         unitEvidence.push({
             kind: "bash",
             toolCallId,
-            command: String(input.command ?? input.cmd ?? input.query ?? ""),
+            // gsd_exec / gsd_uat_exec carry the script body in `script` (or `code`);
+            // bash-style tools use `command`/`cmd`; gsd_exec_search uses `query`.
+            command: String(input.command ?? input.script ?? input.cmd ?? input.code ?? input.query ?? ""),
             exitCode: -1,
             outputSnippet: "",
             timestamp: Date.now(),
@@ -185,9 +193,34 @@ export function recordToolResult(toolCallId, toolName, result, isError) {
     if (entry.kind === "bash") {
         const text = extractResultText(result);
         entry.outputSnippet = text.slice(0, 500);
-        const exitMatch = text.match(/Command exited with code (\d+)/);
-        entry.exitCode = exitMatch ? Number(exitMatch[1]) : (isError ? 1 : 0);
+        entry.exitCode = resolveExitCode(text, isError);
+    }
+}
+/**
+ * Resolve the exit code from a tool result's text. Handles the bash tool's
+ * prose marker, the gsd_exec / gsd_uat_exec JSON envelope (`"exit_code": N`),
+ * and a last-resort read of the run's persisted `.gsd/exec/<id>.meta.json`
+ * (covers truncated result text).
+ */
+function resolveExitCode(text, isError) {
+    const proseMatch = text.match(/Command exited with code (\d+)/);
+    if (proseMatch)
+        return Number(proseMatch[1]);
+    const jsonMatch = text.match(/"exit_code"\s*:\s*(-?\d+)/);
+    if (jsonMatch)
+        return Number(jsonMatch[1]);
+    const metaMatch = text.match(/"meta_path"\s*:\s*"([^"]+)"/);
+    if (metaMatch) {
+        try {
+            const meta = JSON.parse(readFileSync(metaMatch[1], "utf-8"));
+            if (typeof meta.exit_code === "number")
+                return meta.exit_code;
+        }
+        catch {
+            // Fall through to the isError heuristic
+        }
     }
+    return isError ? 1 : 0;
 }
 // ─── Internals ──────────────────────────────────────────────────────────────
 function extractResultText(result) {

package/dist/resources/extensions/gsd/safety/evidence-cross-ref.js

@@ -80,8 +80,13 @@ function findMatches(claimedCommand, bashCalls) {
     const exact = bashCalls.filter(b => b.command.trim() === normalized);
     if (exact.length > 0)
         return exact;
-    // Substring match: claimed is contained in actual or actual in claimed
-    const substring = bashCalls.filter(b => b.command.includes(normalized) || normalized.includes(b.command));
+    // Substring match: claimed is contained in actual or actual in claimed.
+    // A claimed verification command typically appears verbatim inside a
+    // larger gsd_exec script body (cd prefix, multi-line scripts), so
+    // script-containing-claim is the common direction. Blank-command entries
+    // must be excluded — `"x".includes("")` is true, so they'd match anything.
+    const substring = bashCalls.filter(b => b.command.trim().length > 0 &&
+        (b.command.includes(normalized) || normalized.includes(b.command)));
     if (substring.length > 0)
         return substring;
     // Token match: split on whitespace and check significant overlap

package/dist/resources/extensions/gsd/safety/file-change-validator.js

@@ -17,6 +17,16 @@ import { logWarning } from "../workflow-logger.js";
 const _require = createRequire(import.meta.url);
 const picomatch = _require("picomatch");
 // ─── Public API ─────────────────────────────────────────────────────────────
+/**
+ * Build the effective allowlist for a unit's file-change audit.
+ *
+ * When GSD manages .gitignore (manage_gitignore unset or true), ensureGitignore()
+ * appends baseline patterns at auto-start and the edit rides into the task's
+ * auto-commit — so .gitignore changes must not be attributed to the task.
+ */
+export function effectiveFileChangeAllowlist(baseAllowlist, manageGitignore) {
+    return manageGitignore === false ? baseAllowlist : [...baseAllowlist, ".gitignore"];
+}
 /**
  * Validate file changes after auto-commit for an execute-task unit.
  * Returns null if task data is unavailable or DB is not loaded.

package/dist/resources/extensions/gsd/schemas/parsers.js

@@ -6,7 +6,12 @@
 const TEMPLATE_TOKEN_RE = /\{\{[^}]+\}\}/;
 const H2_RE = /^##\s+(.+)$/gm;
 const H3_RE = /^###\s+(.+)$/gm;
-const MILESTONE_LINE_RE = /^-\s+\[([ x])\]\s+(M\d{3}):\s+(.+?)\s+(?:—|--|-)\s+(.+)$/gm;
+// A milestone line is single-line by construction. Every inter-token gap uses
+// horizontal-whitespace classes (`[^\S\n]`) rather than `\s`, because `\s`
+// matches newlines: a line missing a valid separator would otherwise let the
+// `\s+(?:—|--|-)\s+` clause "bridge" onto the NEXT bullet's `- `, consuming it
+// as the separator and silently swallowing the following well-formed milestone.
+const MILESTONE_LINE_RE = /^-[^\S\n]+\[([ x])\][^\S\n]+(M\d{3}):[^\S\n]+(.+?)[^\S\n]+(?:—|--|-)[^\S\n]+(.+)$/gm;
 const SLICE_HEADER_RE = /^###\s+(S\d{2})\s*(?:—|--|-)\s+(.+)$/m;
 const REQUIREMENT_HEADER_RE = /^###\s+(R\d{3})\s*(?:—|--|-)\s+(.+)$/m;
 function splitH2Sections(content) {

package/dist/resources/extensions/gsd/session-lock.js

@@ -329,7 +329,7 @@ export function acquireSessionLock(basePath) {
         // #3218: Provide actionable workaround when lock recovery fails
         const lockDirPath = lockTarget + ".lock";
         const reason = existingPid
-            ? `Another auto-mode session (PID ${existingPid}) appears to be running.\nStop it with \`kill ${existingPid}\` before starting a new session.`
+            ? `Another auto-mode session (PID ${existingPid}) appears to be running.\nRun \`/gsd stop\` for graceful shutdown, or choose "Force start" from \`/gsd auto\` to terminate it.`
             : `Another auto-mode session lock is stuck on this project.\nRun: rm -rf "${lockDirPath}" && rm -f "${lp}"`;
         return { acquired: false, reason, existingPid };
     }

package/dist/resources/extensions/gsd/slice-parallel-orchestrator.js

@@ -19,7 +19,8 @@ import { isAbsolute, join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { gsdRoot } from "./paths.js";
 import { createWorktree, worktreePath, removeWorktree } from "./worktree-manager.js";
-import { runWorktreePostCreateHook, syncGsdStateToWorktree } from "./auto-worktree.js";
+import { runWorktreePostCreateHook, syncGsdStateToWorktreeByScope } from "./auto-worktree.js";
+import { createWorkspace, scopeMilestone } from "./workspace.js";
 import { writeSessionStatus, } from "./session-status-io.js";
 import { hasFileConflict } from "./slice-parallel-conflict.js";
 import { getErrorMessage } from "./error-utils.js";
@@ -108,7 +109,7 @@ function createSliceWorktree(basePath, milestoneId, sliceId) {
     if (hookError) {
         throw new Error(`slice worktree post-create hook failed (${wtName}): ${hookError}`);
     }
-    syncGsdStateToWorktree(basePath, wtPath);
+    syncGsdStateToWorktreeByScope(scopeMilestone(createWorkspace(basePath), milestoneId), scopeMilestone(createWorkspace(wtPath), milestoneId));
     if (!existsSync(join(wtPath, ".gsd"))) {
         throw new Error(`slice worktree preflight failed (${wtName}): missing .gsd in worktree`);
     }

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

@@ -250,7 +250,27 @@ function detectDiskSliceIdDivergenceForMilestone(basePath, milestoneId) {
     }
     return drifts;
 }
-export function detectArtifactDbDrift(_state, ctx) {
+// #442 Phase 1.6: the three artifact/DB drift handlers (disk-slice-id,
+// artifact-db-status, completed-milestone-reopened) each call
+// detectArtifactDbDrift and then filter for their own kind — so the full
+// milestone→slice→task walk + artifact SQL + disk scan would run THREE times
+// per detection pass and discard 2/3 of the work. Memoize the result per
+// DriftContext so the three handlers share one computation. The key is the
+// ctx object, which detectAllDrift rebuilds for every pass (and which is
+// unreferenced once the pass ends, so the WeakMap entry is GC'd) — DB/disk
+// state is immutable within a single pass (repairs run only after detection),
+// so this is behavior-preserving. A fresh ctx (e.g. the maintenance command's
+// inline { basePath, state }) always recomputes.
+const _artifactDbDriftMemo = new WeakMap();
+export function detectArtifactDbDrift(state, ctx) {
+    const cached = _artifactDbDriftMemo.get(ctx);
+    if (cached)
+        return cached;
+    const computed = computeArtifactDbDrift(state, ctx);
+    _artifactDbDriftMemo.set(ctx, computed);
+    return computed;
+}
+function computeArtifactDbDrift(_state, ctx) {
     if (!isDbAvailable())
         return [];
     const drifts = [];

package/dist/resources/extensions/gsd/state-transition-matrix.js

@@ -99,6 +99,44 @@ export const STATE_TRANSITION_MATRIX = [
 export function findTransition(from, event) {
     return STATE_TRANSITION_MATRIX.find((entry) => (entry.from === from || entry.from === "*") && entry.event === event);
 }
+/**
+ * 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, to) {
+    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.
+    from;
+    to;
+    constructor(from, to) {
+        super(`Illegal phase transition ${from} -> ${to} survived reconciliation`);
+        this.name = "IllegalPhaseTransitionError";
+        this.from = from;
+        this.to = to;
+    }
+}
 export function validateTransitionMatrix(requiredEvents) {
     const seen = new Set();
     const duplicateKeys = [];

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

@@ -3,6 +3,11 @@
 // GSD Extension — State Derivation
 // DB-authoritative runtime derivation with explicit legacy filesystem fallback.
 // Pure TypeScript, zero Pi dependencies.
+// 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, } from './parsers-legacy.js';
 import { parseSummary, loadFile, parseRequirementCounts, parseContextDependsOn, } from './files.js';
 import { resolveMilestoneFile, resolveSlicePath, resolveSliceFile, resolveTaskFile, resolveTasksDir, resolveGsdRootFile, gsdRoot, } from './paths.js';
@@ -18,28 +23,11 @@ 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, wasDbOpenAttempted, getAllMilestones, getMilestone, getMilestoneSlices, getSliceTasks, getReplanHistory, getSlice, getRequirementCounts, getLatestAssessmentByScope, getPendingGateCountForTurn, } from './gsd-db.js';
+import { isDbAvailable, getAllMilestones, getMilestone, getMilestoneSlices, getSliceTasks, getReplanHistory, getSlice, getRequirementCounts, getLatestAssessmentByScope, getPendingGateCountForTurn, } from './gsd-db.js';
+import { wasWorkflowDatabaseOpenAttempted } from './db-workspace.js';
 import { formatCompletePhaseNextAction, countUnmappedActiveRequirements } from './requirements-backlog.js';
-function formatNeedsAttentionBlocker(milestoneId) {
-    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) {
-    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 { 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
  * files like CONTEXT, CONTEXT-DRAFT, ROADMAP, or SUMMARY).  These appear when
@@ -301,7 +289,7 @@ export async function deriveState(basePath, opts) {
         _telemetry.dbDeriveCount++;
     }
     else {
-        if (wasDbOpenAttempted()) {
+        if (wasWorkflowDatabaseOpenAttempted()) {
             logWarning("state", "DB unavailable — refusing implicit markdown state derivation");
         }
         result = {
@@ -396,6 +384,12 @@ async function buildRegistryAndFindActive(basePath, milestones, completeMileston
         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));
@@ -403,9 +397,9 @@ async function buildRegistryAndFindActive(basePath, milestones, completeMileston
                 registry.push({ id: m.id, title, status: 'pending', dependsOn: deps });
                 continue;
             }
-            if (m.status === 'queued' && slices.length === 0 && !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;
@@ -417,7 +411,7 @@ async function buildRegistryAndFindActive(basePath, milestones, completeMileston
                 registry.push({ id: m.id, title, status: 'active', ...(deps.length > 0 ? { dependsOn: deps } : {}) });
                 continue;
             }
-            if ((m.status === 'needs-discussion' && !hasContext) || hasDraftContext)
+            if (readinessNeedsDiscussion(readiness))
                 activeMilestoneHasDraft = true;
             activeMilestone = { id: m.id, title };
             activeMilestoneSlices = slices;