@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.84c56d87

package/src/resources/extensions/gsd/recovery-classification.ts

@@ -1,18 +1,23 @@
 // 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, type ErrorClass } from "./error-classifier.js";
+import { recoveryRemediation } from "./guidance.js";
 import { ReconciliationFailedError } from "./state-reconciliation.js";
+import { IllegalPhaseTransitionError } from "./state-transition-matrix.js";
 
 export type RecoveryFailureKind =
   | "tool-schema"
   | "tool-contract"
+  | "tool-unavailable"
   | "deterministic-policy"
   | "lifecycle-progression"
   | "stale-worker"
   | "worktree-invalid"
   | "verification-drift"
   | "reconciliation-drift"
+  | "illegal-transition"
   | "provider"
   | "runtime-unknown";
 
@@ -43,99 +48,53 @@ export function classifyFailure(input: RecoveryClassificationInput): RecoveryCla
   const failureKind =
     input.error instanceof ReconciliationFailedError
       ? "reconciliation-drift"
-      : input.failureKind ?? inferFailureKind(message);
+      : input.error instanceof IllegalPhaseTransitionError
+        ? "illegal-transition"
+        : 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.",
-      };
+  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: Record<
+  Exclude<RecoveryFailureKind, "provider">,
+  { action: RecoveryAction; label: string | null }
+> = {
+  "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: string): RecoveryFailureKind {
+  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)) return "lifecycle-progression";
   if (/schema|invalid.*tool|tool.*invalid|enum/i.test(message)) return "tool-schema";

package/src/resources/extensions/gsd/roadmap-slices.ts

@@ -189,9 +189,15 @@ export function parseRoadmapSlices(content: string): RoadmapSliceEntry[] {
       const risk = (riskMatch ? riskMatch[1] : "low") as RiskLevel;
 
       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

package/src/resources/extensions/gsd/safety/evidence-collector.ts

@@ -57,9 +57,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 ───────────────────────────────────────────────────────────
 
@@ -206,11 +207,17 @@ export function clearEvidenceFromDisk(
  * Exit codes and output are filled in by recordToolResult after execution.
  */
 export function recordToolCall(toolCallId: string, toolName: string, input: Record<string, unknown>): void {
+  // 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(),
@@ -249,11 +256,36 @@ export function recordToolResult(
   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: string, isError: boolean): number {
+  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")) as Record<string, unknown>;
+      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: unknown): string {

package/src/resources/extensions/gsd/safety/evidence-cross-ref.ts

@@ -121,9 +121,14 @@ function findMatches(
   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
+  // 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.includes(normalized) || normalized.includes(b.command),
+    b => b.command.trim().length > 0 &&
+      (b.command.includes(normalized) || normalized.includes(b.command)),
   );
   if (substring.length > 0) return substring;
 

package/src/resources/extensions/gsd/safety/file-change-validator.ts

@@ -39,6 +39,20 @@ export interface FileChangeAudit {
 
 // ─── 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: string[],
+  manageGitignore: boolean | undefined,
+): string[] {
+  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/src/resources/extensions/gsd/slice-parallel-orchestrator.ts

@@ -30,7 +30,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 { autoWorktreeBranch, runWorktreePostCreateHook, syncGsdStateToWorktree } from "./auto-worktree.js";
+import { autoWorktreeBranch, runWorktreePostCreateHook, syncGsdStateToWorktreeByScope } from "./auto-worktree.js";
+import { createWorkspace, scopeMilestone } from "./workspace.js";
 import {
   writeSessionStatus,
   removeSessionStatus,
@@ -163,7 +164,10 @@ function createSliceWorktree(basePath: string, milestoneId: string, sliceId: str
   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/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

@@ -52,7 +52,6 @@ import { isTerminalMilestoneSummaryContent } from './milestone-summary-classifie
 
 import {
   isDbAvailable,
-  wasDbOpenAttempted,
   getAllMilestones,
   getMilestone,
   getMilestoneSlices,
@@ -63,31 +62,19 @@ import {
   getLatestAssessmentByScope,
   getPendingGateCountForTurn,
 } from './gsd-db.js';
+import { 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
@@ -395,7 +382,7 @@ export async function deriveState(
     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 = {
@@ -507,6 +494,12 @@ async function buildRegistryAndFindActive(
     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;
@@ -517,9 +510,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 +526,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;

package/src/resources/extensions/gsd/status-guards.ts

@@ -1,17 +1,68 @@
 /**
- * Status predicates for GSD state-machine guards.
+ * Status predicates and the canonical status vocabulary for GSD state-machine
+ * guards (ADR-030).
  *
- * The DB stores status as free-form strings. Three values indicate
- * "closed": "complete" (canonical), "done" (legacy / alias),
- * "closed" (legacy/imported), and
- * "skipped" (user-directed skip via rethink or backtrack).
- * Every inline `status === "complete" || status === "done"` should
- * use isClosedStatus() instead.
+ * The DB column is free-form `string` so legacy/imported rows still load. Three
+ * raw values besides canonical "complete"/"skipped" indicate "closed": "done"
+ * (legacy alias), "closed" (legacy/imported), and "skipped" (user-directed skip
+ * via rethink or backtrack). `RAW_CLOSED_STATUSES` is the single source for both
+ * `isClosedStatus()` and the SQL terminal-status fragment
+ * (`db/sql-constants.ts` derives `TERMINAL_STATUS_SQL` from it), replacing the
+ * prior independent definitions.
+ *
+ * `toStatus()` is the single seam where a free-form string becomes the canonical
+ * `Status` vocabulary; the Status Transition Core writes canonical, so the store
+ * converges over time without a forced migration.
+ */
+
+/**
+ * Canonical, normalized entity-status vocabulary across milestones, slices, and
+ * tasks — the single source for both the `Status` type and the runtime
+ * membership set. The in-memory domain speaks `Status`; the DB column stays
+ * free-form.
+ */
+export const CANONICAL_STATUSES = [
+  "pending", "queued", "active", "parked", "in_progress", "blocked", "complete", "skipped", "deferred",
+] as const;
+export type Status = (typeof CANONICAL_STATUSES)[number];
+const CANONICAL_STATUS_SET: ReadonlySet<string> = new Set(CANONICAL_STATUSES);
+
+/**
+ * Raw status values that mean a unit is closed — the single source of truth.
+ * Includes legacy/imported aliases ("done", "closed") alongside canonical
+ * "complete"/"skipped" because the DB column is free-form and older rows /
+ * imports still carry them. Order matters: `TERMINAL_STATUS_SQL` is derived
+ * from this array verbatim.
+ */
+export const RAW_CLOSED_STATUSES = ["complete", "done", "skipped", "closed"] as const;
+const RAW_CLOSED_SET: ReadonlySet<string> = new Set(RAW_CLOSED_STATUSES);
+
+/** Free-form aliases mapped to their canonical Status on read. */
+const ALIAS_TO_CANONICAL: Readonly<Record<string, Status>> = {
+  done: "complete",
+  closed: "complete",
+  planned: "pending",
+  "in-progress": "in_progress",
+};
+
+/**
+ * Normalize a free-form DB status string into the canonical `Status`
+ * vocabulary. Maps known aliases (done/closed → complete, planned → pending,
+ * in-progress → in_progress). An unrecognized/legacy value is **quarantined** —
+ * preserved verbatim rather than silently remapped to a wrong canonical state —
+ * so reads never fail and reconciliation/telemetry can surface it.
  */
+export function toStatus(raw: string): Status {
+  const value = raw.trim();
+  if (CANONICAL_STATUS_SET.has(value)) return value as Status;
+  const alias = ALIAS_TO_CANONICAL[value];
+  if (alias) return alias;
+  return value as Status;
+}
 
 /** Returns true when a milestone, slice, or task status indicates closure. */
 export function isClosedStatus(status: string): boolean {
-  return status === "complete" || status === "done" || status === "skipped" || status === "closed";
+  return RAW_CLOSED_SET.has(status);
 }
 
 /** Returns true when a slice status indicates it was deferred by a decision. */

package/src/resources/extensions/gsd/stop-notice.ts

@@ -0,0 +1,75 @@
+// Project/App: gsd-pi
+// File Purpose: Stop Notice module — single owner of the auto/step-mode
+// stop/pause notice vocabulary. Both sides of the wire live here: the
+// formatters that produce the canonical prefixes (used by stopAuto/pauseAuto)
+// and the classifiers that recognize them (used by the headless host to pick
+// exit codes). Wording changes in this file keep emitter and detector in
+// lockstep; round-trip tests enforce it.
+
+export type StopNoticeKind = "stopped" | "blocked";
+
+/** A reason string of the form "Blocked: …" marks a blocked stop. */
+export function isBlockedStopReason(reason?: string | null): boolean {
+  return /^Blocked:\s*/i.test(reason ?? "");
+}
+
+/** Strip the "Blocked: " marker for display. */
+export function stopNoticeDisplayReason(reason?: string | null): string {
+  return (reason ?? "").replace(/^Blocked:\s*/i, "").trim();
+}
+
+export function stopNoticeKind(reason?: string | null): StopNoticeKind {
+  return isBlockedStopReason(reason) ? "blocked" : "stopped";
+}
+
+/** Canonical stop-notice prefix: "Auto-mode blocked — reason" / "Auto-mode stopped". */
+export function formatStopNoticePrefix(reason?: string | null): string {
+  const displayReason = stopNoticeDisplayReason(reason);
+  const prefix = stopNoticeKind(reason) === "blocked" ? "Auto-mode blocked" : "Auto-mode stopped";
+  return displayReason ? `${prefix} — ${displayReason}` : prefix;
+}
+
+// ─── Classification (headless host side) ────────────────────────────────
+// The canonical lowercase prefixes the headless event loop recognizes in
+// notify messages. Emitters above and ad-hoc emitters elsewhere must start
+// their terminal notices with one of these.
+
+export const PAUSED_NOTICE_PREFIXES = ["auto-mode paused", "step-mode paused"] as const;
+
+export const TERMINAL_NOTICE_PREFIXES = [
+  "auto-mode stopped",
+  "step-mode stopped",
+  "auto-mode complete",
+  "no active milestone",
+  "auto-mode idle",
+] as const;
+
+/** Manual-resolution notices emitted before auto-mode can formally pause/stop. */
+export function isManualResolutionNotice(message: string): boolean {
+  return (
+    message.includes("resolve manually and re-run /gsd auto") ||
+    message.includes("resolve conflicts manually and run /gsd auto to resume") ||
+    message.includes("resolve and run /gsd auto to resume")
+  );
+}
+
+export function isPauseNotice(message: string): boolean {
+  return PAUSED_NOTICE_PREFIXES.some((prefix) => message.startsWith(prefix));
+}
+
+export function isTerminalNotice(message: string): boolean {
+  return TERMINAL_NOTICE_PREFIXES.some((prefix) => message.startsWith(prefix));
+}
+
+/** Pauses that do not require operator intervention in headless mode. */
+export function isNonBlockingPauseNotice(message: string): boolean {
+  return message.includes("idempotent advance: unit already active");
+}
+
+export function isBlockedNoticeMessage(message: string): boolean {
+  return (
+    message.includes("blocked:") ||
+    (isPauseNotice(message) && !isNonBlockingPauseNotice(message)) ||
+    isManualResolutionNotice(message)
+  );
+}

package/src/resources/extensions/gsd/templates/plan.md

@@ -46,6 +46,13 @@
      For simple projects or scripts:
      - Executable verification commands (bash assertions, curl checks, etc.) are sufficient
 
+     For browser-facing web apps (React, Next, Vue, Vite, static HTML, etc.):
+     - Prefer `npx playwright test <spec>` in Verification when `@playwright/test` exists
+     - If Playwright is not set up yet, the first UI slice should add `playwright.config.ts`,
+       a minimal smoke spec (for example `e2e/smoke.spec.ts`), and a safe verify command
+     - Slice closeout UAT must declare `browser-executable` or `runtime-executable` — not
+       `artifact-driven` — when checks navigate to localhost or exercise the live UI
+
      If the project has no test framework and the work is non-trivial,
      the first task should set one up. A test runner costs 2 minutes
      and pays for itself immediately.

package/src/resources/extensions/gsd/templates/project.md

@@ -20,6 +20,7 @@
 
 - **Complexity:** {{simple | complex}}
 - **Why:** {{one-line rationale citing the signals that decided it}}
+- **Web stack:** {{browser-facing framework or "not a web UI" — e.g. Next.js + Playwright, static HTML, N/A for CLI/API-only}}
 
 ## Current State
 

package/src/resources/extensions/gsd/templates/roadmap.md

@@ -42,7 +42,7 @@
 - Contract verification: {{tests / shell verifiers / fixtures / artifact checks}}
 - Integration verification: {{real subsystem interaction that must be exercised, or none}}
 - Operational verification: {{service lifecycle / restart / reconnect / supervision / deploy-install behavior, or none}}
-- UAT / human verification: {{what needs real human judgment, or none}}
+- UAT / human verification: {{what needs real human judgment, or none — for web apps prefer browser-executable / runtime-executable Playwright checks over deferring UI proof to humans}}
 
 ## Milestone Definition of Done
 

package/src/resources/extensions/gsd/templates/uat.md

@@ -5,9 +5,13 @@
 
 ## UAT Type
 
-- UAT mode: {{artifact-driven | live-runtime | human-experience | mixed}}
+- UAT mode: {{artifact-driven | browser-executable | runtime-executable | live-runtime | human-experience | mixed}}
 - Why this mode is sufficient: {{reason}}
 
+<!-- Web apps: never use artifact-driven when steps open a browser, navigate to localhost,
+     or capture screenshots. Use browser-executable (browser_* tools) or runtime-executable
+     (npx playwright test). Name dev-server preconditions below. -->
+
 ## Preconditions
 
 {{whatMustBeTrueBeforeTesting — server running, data seeded, etc.}}