@opengsd/gsd-pi 1.2.0-dev.955e4da0 → 1.2.0-dev.d6c5343c

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

@@ -39,6 +39,7 @@ import { markLatestActiveForWorkerCanceled, type DispatchStatus } from "./db/uni
 import { getRuntimeKv, setRuntimeKv, deleteRuntimeKv } from "./db/runtime-kv.js";
 import { _getAdapter, isDbAvailable } from "./gsd-db.js";
 import { gsdRoot, normalizeRealPath } from "./paths.js";
+import { crashResumeHint } from "./guidance.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { effectiveLockFile } from "./session-lock.js";
 import { isInFlightRuntimePhase, listUnitRuntimeRecords, type AutoUnitRuntimeRecord } from "./unit-runtime.js";
@@ -321,15 +322,8 @@ export function formatCrashInfo(lock: LockData): string {
     `  PID: ${lock.pid}`,
   ];
 
-  if (lock.unitType === "starting" && lock.unitId === "bootstrap") {
-    lines.push(`No work was lost. Run /gsd auto to restart.`);
-  } else if (lock.unitType.includes("research") || lock.unitType.includes("plan")) {
-    lines.push(`The ${lock.unitType} unit may be incomplete. Run /gsd auto to re-run it.`);
-  } else if (lock.unitType.includes("execute")) {
-    lines.push(`Task execution was interrupted. Run /gsd auto to resume — completed work is preserved.`);
-  } else if (lock.unitType.includes("complete")) {
-    lines.push(`Slice/milestone completion was interrupted. Run /gsd auto to finish.`);
-  }
+  const hint = crashResumeHint(lock.unitType, lock.unitId);
+  if (hint) lines.push(hint);
 
   return lines.join("\n");
 }

package/src/resources/extensions/gsd/db/queries.ts

@@ -5,6 +5,7 @@
 // Read-only callers (forensics, dashboard, doctor) depend on this seam, not on
 // the single-writer surface.
 import { getDbOrNull } from "./engine.js";
+import { isClosedStatus } from "../status-guards.js";
 import { getGateIdsForTurn, type OwnerTurn } from "../gate-registry.js";
 import type { Decision, Requirement, GateRow, GateScope } from "../types.js";
 import {
@@ -269,6 +270,42 @@ export function getMilestoneSlices(milestoneId: string): SliceRow[] {
   return rows.map(rowToSlice);
 }
 
+/** Dispatch-eligibility shape consumed by decision-path callers (ADR-017). */
+export interface MilestoneSliceSummary {
+  id: string;
+  title: string;
+  /** Closed per the canonical status vocabulary (complete/done/skipped/closed). */
+  done: boolean;
+  depends: string[];
+}
+
+/**
+ * Consolidated DB read for dispatch/gate/completion decisions (ADR-017).
+ * `done` uses the canonical closed-status predicate (`isClosedStatus`) — the
+ * same vocabulary the SQL terminal-status fragment derives from. Decision
+ * paths must consume this instead of parsing `.gsd/*.md` projections.
+ * Rows keep `getMilestoneSlices` ordering (sequence, then id).
+ */
+export function getMilestoneSliceSummaries(milestoneId: string): MilestoneSliceSummary[] {
+  return getMilestoneSlices(milestoneId).map((s) => ({
+    id: s.id,
+    title: s.title,
+    done: isClosedStatus(s.status),
+    depends: s.depends ?? [],
+  }));
+}
+
+/**
+ * Ids of slices closed per the canonical status vocabulary (ADR-017), in
+ * milestone order. Thin wrapper over `getMilestoneSliceSummaries` for the
+ * common "which slices are done?" decision-path read.
+ */
+export function getClosedSliceIds(milestoneId: string): string[] {
+  return getMilestoneSliceSummaries(milestoneId)
+    .filter((s) => s.done)
+    .map((s) => s.id);
+}
+
 export function getArtifact(path: string): ArtifactRow | null {
   if (!getDbOrNull()!) return null;
   const row = getDbOrNull()!.prepare("SELECT * FROM artifacts WHERE path = :path").get({ ":path": path });

package/src/resources/extensions/gsd/dispatch-guard.ts

@@ -3,9 +3,8 @@
 import { resolveMilestoneFile } from "./paths.js";
 import { findMilestoneIds } from "./guided-flow.js";
 import { parseUnitId } from "./unit-id.js";
-import { isDbAvailable, getMilestoneSlices, getMilestone } from "./gsd-db.js";
-import { parseRoadmap } from "./parsers-legacy.js";
-import { isClosedStatus, isSkippedForDispatch } from "./status-guards.js";
+import { isDbAvailable, getMilestoneSliceSummaries, getMilestone } from "./gsd-db.js";
+import { isSkippedForDispatch } from "./status-guards.js";
 import { classifyMilestoneSummaryContent } from "./milestone-summary-classifier.js";
 import { readFileSync } from "node:fs";
 import type { LoopState } from "./auto/types.js";
@@ -117,34 +116,12 @@ export function getPriorSliceCompletionBlocker(
       }
     }
 
-    // Normalised slice list from DB or file fallback
-    type NormSlice = { id: string; done: boolean; depends: string[] };
-    let slices: NormSlice[] | null = null;
-
-    if (isDbAvailable()) {
-      const rows = getMilestoneSlices(mid);
-      if (rows.length > 0) {
-        slices = rows.map((r) => ({
-          id: r.id,
-          done: isClosedStatus(r.status),
-          depends: r.depends ?? [],
-        }));
-      }
-    }
-    if (!slices) {
-      // File-based fallback: parse roadmap checkboxes
-      const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
-      if (!roadmapPath) continue;
-      let roadmapContent: string;
-      try { roadmapContent = readFileSync(roadmapPath, "utf-8"); } catch { continue; }
-      const parsed = parseRoadmap(roadmapContent);
-      if (parsed.slices.length === 0) continue;
-      slices = parsed.slices.map((s) => ({
-        id: s.id,
-        done: s.done,
-        depends: s.depends ?? [],
-      }));
-    }
+    // DB-authoritative eligibility list (ADR-017) — markdown projections are
+    // never parsed for dispatch decisions. No DB / no rows → skip this
+    // milestone's check (unknown is not a blocker).
+    if (!isDbAvailable()) continue;
+    const slices = getMilestoneSliceSummaries(mid);
+    if (slices.length === 0) continue;
 
     if (mid !== targetMid) {
       const incomplete = slices.find((slice) => !slice.done);

package/src/resources/extensions/gsd/doctor-environment.ts

@@ -15,7 +15,7 @@ import { join } from "node:path";
 
 import type { DoctorIssue, DoctorIssueCode } from "./doctor-types.js";
 import { detectPythonExecutable } from "./python-resolver.js";
-import { findWorktreeSegment } from "./worktree-root.js";
+import { projectRootFromWorktreePath } from "./worktree-root.js";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -50,12 +50,7 @@ const CMD_TIMEOUT = 5_000;
 function resolveWorktreeProjectRoot(basePath: string): string | null {
   const envRoot = process.env.GSD_WORKTREE;
   if (envRoot) return envRoot;
-
-  const segment = findWorktreeSegment(basePath.replace(/\\/g, "/"));
-  if (!segment) return null;
-
-  // Everything before the worktree segment is the project root
-  return basePath.slice(0, segment.gsdIdx);
+  return projectRootFromWorktreePath(basePath);
 }
 
 function tryExec(cmd: string, cwd: string): string | null {

package/src/resources/extensions/gsd/doctor-format.ts

@@ -1,4 +1,9 @@
-import type { DoctorIssue, DoctorIssueCode, DoctorReport, DoctorSummary } from "./doctor-types.js";
+import type { DoctorIssue, DoctorIssueCode, DoctorReport, DoctorSummary, DoctorSeverity } from "./doctor-types.js";
+import { doctorFixHint } from "./guidance.js";
+
+function severityTag(severity: DoctorSeverity): string {
+  return severity === "error" ? "ERROR" : severity === "warning" ? "WARN" : "INFO";
+}
 
 function matchesScope(unitId: string, scope?: string): boolean {
   if (!scope) return true;
@@ -53,8 +58,9 @@ export function formatDoctorReport(
   if (scopedIssues.length > 0) {
     lines.push("Priority issues:");
     for (const issue of scopedIssues.slice(0, maxIssues)) {
-      const prefix = issue.severity === "error" ? "ERROR" : issue.severity === "warning" ? "WARN" : "INFO";
-      lines.push(`- [${prefix}] ${issue.unitId}: ${issue.message}${issue.file ? ` (${issue.file})` : ""}`);
+      lines.push(`- [${severityTag(issue.severity)}] ${issue.unitId}: ${issue.message}${issue.file ? ` (${issue.file})` : ""}`);
+      const hint = doctorFixHint(issue.code);
+      if (hint && issue.severity !== "info") lines.push(`  Fix: ${hint}`);
     }
     if (scopedIssues.length > maxIssues) {
       lines.push(`- ...and ${scopedIssues.length - maxIssues} more in scope`);
@@ -72,10 +78,9 @@ export function formatDoctorReport(
 
 export function formatDoctorIssuesForPrompt(issues: DoctorIssue[]): string {
   if (issues.length === 0) return "- No remaining issues in scope.";
-  return issues.map(issue => {
-    const prefix = issue.severity === "error" ? "ERROR" : issue.severity === "warning" ? "WARN" : "INFO";
-    return `- [${prefix}] ${issue.unitId} | ${issue.code} | ${issue.message}${issue.file ? ` | file: ${issue.file}` : ""} | fixable: ${issue.fixable ? "yes" : "no"}`;
-  }).join("\n");
+  return issues.map(issue =>
+    `- [${severityTag(issue.severity)}] ${issue.unitId} | ${issue.code} | ${issue.message}${issue.file ? ` | file: ${issue.file}` : ""} | fixable: ${issue.fixable ? "yes" : "no"}`
+  ).join("\n");
 }
 
 /**

package/src/resources/extensions/gsd/doctor-runtime-checks.ts

@@ -425,22 +425,20 @@ export async function checkRuntimeHealth(
         missing.push(...criticalPatterns.filter(p => !existingLines.has(p)));
       }
 
-      {
-        if (missing.length > 0) {
-          issues.push({
-            severity: "warning",
-            code: "gitignore_missing_patterns",
-            scope: "project",
-            unitId: "project",
-            message: `${missing.length} critical GSD runtime pattern(s) missing from .gitignore: ${missing.join(", ")}`,
-            file: ".gitignore",
-            fixable: true,
-          });
+      if (missing.length > 0) {
+        issues.push({
+          severity: "warning",
+          code: "gitignore_missing_patterns",
+          scope: "project",
+          unitId: "project",
+          message: `${missing.length} critical GSD runtime pattern(s) missing from .gitignore: ${missing.join(", ")}`,
+          file: ".gitignore",
+          fixable: true,
+        });
 
-          if (shouldFix("gitignore_missing_patterns")) {
-            ensureGitignore(basePath, { manageGitignore });
-            fixesApplied.push("added missing GSD runtime patterns to .gitignore");
-          }
+        if (shouldFix("gitignore_missing_patterns")) {
+          ensureGitignore(basePath, { manageGitignore });
+          fixesApplied.push("added missing GSD runtime patterns to .gitignore");
         }
       }
     }

package/src/resources/extensions/gsd/engine-hook-contract.ts

@@ -0,0 +1,79 @@
+// Project/App: gsd-pi
+// File Purpose: Typed contract for which tool lifecycle hooks fire under which
+// engine, plus the single seam for tool-name normalization.
+//
+// ── Why this contract exists ────────────────────────────────────────────────
+// External engines (claude-code-cli) pre-execute tools inside the vendor CLI
+// and hand the agent loop a `toolCall.externalResult`. The loop short-circuits
+// before `beforeToolCall`/`afterToolCall` ever run for those calls
+// (packages/pi-agent-core/src/agent-loop.ts, prepareToolCall: the
+// externalResult branch returns an "immediate" outcome before the
+// config.beforeToolCall invocation, and "immediate" outcomes skip
+// finalizeExecutedToolCall where config.afterToolCall lives).
+// `beforeToolCall`/`afterToolCall` are exactly what the extension runner maps
+// to the `tool_call`/`tool_result` extension events
+// (packages/gsd-agent-core/src/session/agent-session-extensions.ts,
+// installAgentToolHooks).
+//
+// `tool_execution_start` is emitted unconditionally before prepareToolCall
+// and `tool_execution_end` after every finalized outcome — immediate or
+// executed — so those two are the ONLY tool lifecycle hooks that fire for
+// every tool call on every engine.
+//
+// Consequence: any enforcement attached only to `tool_call` (blocking) or
+// `tool_result` (rewriting) is silently dead under external engines. Safety
+// enforcement must ride `tool_execution_start`/`tool_execution_end`, or
+// mirror across both with toolCallId dedup. See the per-registration contract
+// comments in bootstrap/register-hooks.ts for how each registered hook
+// honors (or knowingly violates) this contract.
+
+import { stripMcpToolPrefix } from "./mcp-tool-name.js";
+import { canonicalWorkflowSurfaceToolName } from "./workflow-tool-surface.js";
+
+/**
+ * Tool lifecycle hooks that fire for EVERY tool call on EVERY engine,
+ * including external engines (claude-code-cli) that pre-execute tools.
+ * Attach safety-critical enforcement and evidence collection here.
+ */
+export const UNIVERSAL_TOOL_HOOKS = ["tool_execution_start", "tool_execution_end"] as const;
+
+/**
+ * Tool lifecycle hooks that fire ONLY for natively executed tools. External
+ * engines pre-execute tools (externalResult), short-circuiting the agent
+ * loop's beforeToolCall/afterToolCall — so handlers on these events never run
+ * for those calls. Blocking guards attached only here are dead under external
+ * engines; they need a tool_execution_start mirror to be universal.
+ */
+export const NATIVE_ONLY_TOOL_HOOKS = ["tool_call", "tool_result"] as const;
+
+export type UniversalToolHook = (typeof UNIVERSAL_TOOL_HOOKS)[number];
+export type NativeOnlyToolHook = (typeof NATIVE_ONLY_TOOL_HOOKS)[number];
+
+// Non-tool lifecycle events (session_start, agent_end, message_update, ...)
+// are intentionally NOT classified here: they are emitted by the session
+// host / extension runner independent of tool execution, so the external
+// engine short-circuit above does not apply to them. Only classify events
+// whose engine behavior has been verified against the agent loop.
+
+/**
+ * Canonical tool name: strips the `mcp__<server>__` prefix when present,
+ * nothing else. Use for identity checks against host/native tool names and
+ * for any guard that must NOT conflate workflow aliases with their canonical
+ * tools (e.g. write gates, evidence keys).
+ *
+ * Malformed MCP names (empty server or empty tool segment, e.g.
+ * `mcp____tool` or `mcp__server__`) are returned unchanged.
+ */
+export function canonicalToolName(toolName: string): string {
+  return stripMcpToolPrefix(toolName);
+}
+
+/**
+ * Workflow-aware canonical tool name: strips the MCP prefix AND resolves
+ * workflow tool aliases to their canonical contract names. Use whenever the
+ * name is compared against the workflow tool surface (scoping, presentation,
+ * dispatch) — plain {@link canonicalToolName} would miss alias spellings.
+ */
+export function canonicalWorkflowToolName(toolName: string): string {
+  return canonicalWorkflowSurfaceToolName(toolName);
+}

package/src/resources/extensions/gsd/error-classifier.ts

@@ -10,6 +10,8 @@
  * @see https://github.com/open-gsd/gsd-pi/issues/2577
  */
 
+import { TOOL_SURFACE_NOT_READY } from "./tool-surface-readiness.js";
+
 // ── ErrorClass discriminated union ──────────────────────────────────────────
 
 export type ErrorClass =
@@ -70,6 +72,10 @@ const CONNECTION_RE = /terminated|connection.?(?:refused|error)|other side close
 const STREAM_RE = /in JSON at position \d+|Unexpected end of JSON|SyntaxError.*JSON/i;
 const RESET_DELAY_RE = /reset in (\d+)s/i;
 const TOOL_SCHEMA_RE = /schema overload|consecutive tool validation failures/i;
+// GSD tool-surface readiness abort (claude-code stream adapter): the workflow
+// MCP server had not registered the Unit's required tools at SDK init. The
+// server typically finishes connecting within seconds — same-model retry.
+const TOOL_SURFACE_NOT_READY_RE = new RegExp(TOOL_SURFACE_NOT_READY, "i");
 // Provider rejected the request shape for the selected model (400 bad request,
 // grammar limits, etc.). Not transient — try a different model/fallback.
 // Context-window 400s stay in SERVER_RE (checked earlier).
@@ -108,6 +114,11 @@ export function classifyError(errorMsg: string, retryAfterMs?: number): ErrorCla
     return { kind: "tool-schema", retryAfterMs: 0 };
   }
 
+  // Tool-surface readiness abort — transient; retry the same model shortly.
+  if (TOOL_SURFACE_NOT_READY_RE.test(errorMsg)) {
+    return { kind: "network", retryAfterMs: retryAfterMs ?? 3_000 };
+  }
+
   const isPermanent = PERMANENT_RE.test(errorMsg);
   const isRateLimit = RATE_LIMIT_RE.test(errorMsg) || AFFORDABILITY_RE.test(errorMsg);
   const isUnsupportedModel =

package/src/resources/extensions/gsd/exec-sandbox.ts

@@ -12,6 +12,7 @@ import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { resolve } from "node:path";
+import { killProcessTree, SIGKILL_GRACE_MS, HARD_DEADLINE_MS } from "@gsd/pi-coding-agent";
 
 export interface ExecSandboxRequest {
   /** Interpreter to use. */
@@ -47,6 +48,17 @@ export interface ExecSandboxOptions {
   now?: () => Date;
   /** Optional override for id generation (tests). */
   generateId?: () => string;
+  /**
+   * Grace period (ms) between SIGTERM and SIGKILL on timeout.
+   * Defaults to SIGKILL_GRACE_MS. Exposed as a test seam.
+   */
+  kill_grace_ms?: number;
+  /**
+   * Delay (ms) after a kill is initiated before the hard-deadline force-resolves
+   * the promise (handles D-state / non-closing children).
+   * Defaults to SIGKILL_GRACE_MS + HARD_DEADLINE_MS. Exposed as a test seam.
+   */
+  force_resolve_delay_ms?: number;
 }
 
 export interface ExecSandboxResult {
@@ -55,6 +67,12 @@ export interface ExecSandboxResult {
   exit_code: number | null;
   signal: NodeJS.Signals | null;
   timed_out: boolean;
+  /**
+   * True when the result came from the hard-deadline force-resolve (a non-closing
+   * D-state child that never emitted 'close') rather than an observed process exit.
+   * In that case `signal` is the synthetic "SIGKILL" marker, not a delivered signal.
+   */
+  force_resolved: boolean;
   duration_ms: number;
   stdout_bytes: number;
   stderr_bytes: number;
@@ -68,6 +86,10 @@ export interface ExecSandboxResult {
 
 const ALWAYS_FORWARD_ENV = ["PATH", "HOME"] as const;
 
+// SIGKILL_GRACE_MS / HARD_DEADLINE_MS are imported from @gsd/pi-coding-agent
+// (shell.ts) — the single source of truth for the graceful-kill timing ladder —
+// so this sandbox can never drift from the canonical kill path it delegates to.
+
 export const EXEC_DEFAULTS = {
   clampTimeoutMs: 600_000,
   defaultTimeoutMs: 30_000,
@@ -180,6 +202,7 @@ export function runExecSandbox(
         exit_code: null,
         signal: null,
         timed_out: false,
+        force_resolved: false,
         duration_ms: duration,
         stdout_bytes: 0,
         stderr_bytes: Buffer.byteLength(`spawn error: ${message}\n`),
@@ -233,23 +256,39 @@ export function runExecSandbox(
       }
     });
 
+    const effectiveGraceMs = opts.kill_grace_ms ?? SIGKILL_GRACE_MS;
+    const effectiveForceResolveDelay = opts.force_resolve_delay_ms ?? (effectiveGraceMs + HARD_DEADLINE_MS);
+
     let timedOut = false;
+    let settled = false;
+    let forceResolveTimer: NodeJS.Timeout | undefined;
+
     const timer = setTimeout(() => {
       timedOut = true;
-      if (useProcessGroup && child.pid != null) {
-        try {
-          process.kill(-child.pid, "SIGKILL");
-        } catch {
-          child.kill("SIGKILL");
-        }
+      // killProcessTree handles both platforms and kills the whole tree: on Unix
+      // it signals the process group (SIGTERM -> grace -> SIGKILL); on Windows it
+      // force-kills the tree via taskkill /F /T. Using child.kill("SIGTERM") here
+      // would only terminate the direct child on Windows, orphaning grandchildren.
+      if (child.pid != null) {
+        killProcessTree(child.pid, { graceMs: effectiveGraceMs });
       } else {
-        child.kill("SIGKILL");
+        child.kill("SIGTERM");
       }
+      // Arm hard-deadline force-resolve in case child never closes (D-state).
+      // The "SIGKILL" here is a synthetic marker (the process may not have actually
+      // received it); force_resolved=true records that this was a deadline, not an exit.
+      forceResolveTimer = setTimeout(() => {
+        finalize(null, "SIGKILL", true);
+      }, effectiveForceResolveDelay);
+      forceResolveTimer.unref?.();
     }, timeoutMs);
     timer.unref?.();
 
-    const finalize = (exitCode: number | null, signal: NodeJS.Signals | null) => {
+    const finalize = (exitCode: number | null, signal: NodeJS.Signals | null, forceResolved = false) => {
+      if (settled) return;
+      settled = true;
       clearTimeout(timer);
+      clearTimeout(forceResolveTimer);
       const duration = Date.now() - started;
       const stdoutBuf = Buffer.concat(stdoutChunks);
       const stderrBuf = Buffer.concat(stderrChunks);
@@ -274,6 +313,7 @@ export function runExecSandbox(
         exit_code: exitCode,
         signal,
         timed_out: timedOut,
+        force_resolved: forceResolved,
         duration_ms: duration,
         stdout_bytes: stdoutBytes,
         stderr_bytes: stderrBytes,
@@ -324,6 +364,7 @@ function writeMeta(
     exit_code: result.exit_code,
     signal: result.signal,
     timed_out: result.timed_out,
+    force_resolved: result.force_resolved,
     duration_ms: result.duration_ms,
     stdout_bytes: result.stdout_bytes,
     stderr_bytes: result.stderr_bytes,
@@ -331,7 +372,6 @@ function writeMeta(
     stderr_truncated: result.stderr_truncated,
     stdout_path: result.stdout_path,
     stderr_path: result.stderr_path,
-    ...(request.metadata ? { metadata: request.metadata } : {}),
   };
   writeFileSync(path, `${JSON.stringify(meta, null, 2)}\n`);
 }

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

@@ -671,33 +671,54 @@ export function parseTaskPlanIO(content: string): { inputFiles: string[]; output
  */
 export type UatType = 'artifact-driven' | 'live-runtime' | 'human-experience' | 'mixed' | 'browser-executable' | 'runtime-executable';
 
+/** Canonical list of recognised UAT types — uat-policy.ts re-exports this as UAT_TYPES. */
+export const UAT_TYPE_KEYWORDS: readonly UatType[] = [
+  'artifact-driven',
+  'browser-executable',
+  'runtime-executable',
+  'live-runtime',
+  'mixed',
+  'human-experience',
+];
+
+/** Match a value against the recognised UAT type keywords (leading-keyword-only). */
+function matchUatTypeKeyword(value: string): UatType | undefined {
+  const normalized = value.trim().toLowerCase();
+  return UAT_TYPE_KEYWORDS.find(keyword => normalized.startsWith(keyword));
+}
+
 /**
  * Extract the UAT type from a UAT file's raw content.
  *
  * UAT files have no YAML frontmatter - pass raw file content directly.
  * Classification is leading-keyword-only: e.g. `mixed (artifact-driven + live-runtime)` → `'mixed'`.
  *
+ * The canonical form is a `- UAT mode: <type>` bullet under `## UAT Type`
+ * (case-insensitive prefix, `**bold**` tolerated). When no such line exists,
+ * a line that itself starts with a recognised keyword — e.g. a bare
+ * `browser-executable` under the heading — is accepted, so agent-authored
+ * format drift does not silently fall back to artifact-driven.
+ *
  * Returns `undefined` when:
  * - the `## UAT Type` section is absent
- * - no `UAT mode:` bullet is found in the section
- * - the value does not start with a recognised keyword
+ * - a `UAT mode:` line exists but its value starts with no recognised keyword
+ * - no line in the section starts with `UAT mode:` or a recognised keyword
  */
 export function extractUatType(content: string): UatType | undefined {
   const sectionText = extractSection(content, 'UAT Type');
   if (!sectionText) return undefined;
 
-  const bullets = parseBullets(sectionText);
-  const modeBullet = bullets.find(b => b.startsWith('UAT mode:'));
-  if (!modeBullet) return undefined;
+  const lines = parseBullets(sectionText).map(line => line.replace(/\*\*/g, ''));
 
-  const rawValue = modeBullet.slice('UAT mode:'.length).trim().toLowerCase();
+  for (const line of lines) {
+    const declared = /^uat mode:\s*(.*)$/i.exec(line);
+    if (declared) return matchUatTypeKeyword(declared[1]);
+  }
 
-  if (rawValue.startsWith('artifact-driven')) return 'artifact-driven';
-  if (rawValue.startsWith('browser-executable')) return 'browser-executable';
-  if (rawValue.startsWith('runtime-executable')) return 'runtime-executable';
-  if (rawValue.startsWith('live-runtime')) return 'live-runtime';
-  if (rawValue.startsWith('human-experience')) return 'human-experience';
-  if (rawValue.startsWith('mixed')) return 'mixed';
+  for (const line of lines) {
+    const matched = matchUatTypeKeyword(line);
+    if (matched) return matched;
+  }
 
   return undefined;
 }