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

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, isTerminalToolSurfaceError } from "./tool-surface-readiness.js";
+
 // ── ErrorClass discriminated union ──────────────────────────────────────────
 
 export type ErrorClass =
@@ -58,7 +60,7 @@ const AFFORDABILITY_RE = /requires more credits|can only afford|insufficient cre
 // are emitted by SDK/harness transports for mid-stream disconnects.
 // These indicate transient network-level interruptions.
 // See: https://github.com/open-gsd/gsd-pi/issues/4558
-const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|web ?socket|fetch failed|connection.*reset|dns|unexpected eof|stream idle timeout|partial response received/i;
+const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|web ?socket|fetch failed|connection.*reset|dns|unexpected eof|stream idle timeout|partial response received|stream ended without finish_reason/i;
 // Context overflow errors (context window/length exceeded) should be treated as server-class
 // transient errors so auto-mode can retry with reduced budget or fall back to a larger-context model.
 // See: https://github.com/open-gsd/gsd-pi/issues/4528
@@ -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,24 @@ export function classifyError(errorMsg: string, retryAfterMs?: number): ErrorCla
     return { kind: "tool-schema", retryAfterMs: 0 };
   }
 
+  // Terminal tool-surface failure: the workflow MCP server is in a
+  // non-self-healing status (failed / needs-auth / disabled). This is NOT
+  // transient — retrying the same model cannot repair a dead server, so it
+  // must escalate / pause rather than retrying every ~3s into the per-unit
+  // cost cap. Checked ahead of the transient readiness branch below, which
+  // shares the TOOL_SURFACE_NOT_READY prefix and would otherwise collapse the
+  // terminal case into a transient `network` retry. See #783.
+  if (isTerminalToolSurfaceError(errorMsg)) {
+    return { kind: "permanent" };
+  }
+
+  // Tool-surface readiness abort — transient; retry the same model shortly.
+  // This covers the not-yet-connected variants (absent, pending, connected but
+  // not registered); terminal statuses were handled by the branch above.
+  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/escalation.ts

@@ -10,7 +10,7 @@ import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import type { EscalationArtifact, EscalationOption } from "./types.js";
-import { resolveSlicePath } from "./paths.js";
+import { legacyMilestonesDir, resolveSlicePath, resolveTasksDir } from "./paths.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import {
   getTask,
@@ -35,9 +35,14 @@ import { logWarning } from "./workflow-logger.js";
 export function escalationArtifactPath(
   basePath: string, milestoneId: string, sliceId: string, taskId: string,
 ): string | null {
-  const sDir = resolveSlicePath(basePath, milestoneId, sliceId);
-  if (!sDir) return null;
-  return join(sDir, "tasks", `${taskId}-ESCALATION.json`);
+  const tDir = resolveTasksDir(basePath, milestoneId, sliceId);
+  if (tDir) return join(tDir, `${taskId}-ESCALATION.json`);
+  // Flat-phase: tasks live in plan files; escalation artifacts sit in the phase dir.
+  // Legacy without tasks/: return null so writeEscalationArtifact throws (run doctor).
+  if (existsSync(legacyMilestonesDir(basePath))) return null;
+  const phaseDir = resolveSlicePath(basePath, milestoneId, sliceId);
+  if (!phaseDir) return null;
+  return join(phaseDir, `${taskId}-ESCALATION.json`);
 }
 
 // ─── Artifact I/O ─────────────────────────────────────────────────────────

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,19 @@ export interface ExecSandboxOptions {
   now?: () => Date;
   /** Optional override for id generation (tests). */
   generateId?: () => string;
+  /** Optional request cancellation signal. Aborting kills the child process tree. */
+  signal?: AbortSignal;
+  /**
+   * 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 +69,14 @@ export interface ExecSandboxResult {
   exit_code: number | null;
   signal: NodeJS.Signals | null;
   timed_out: boolean;
+  /** True when an external AbortSignal terminated the child process tree. */
+  aborted?: 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 +90,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 +206,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 +260,51 @@ 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;
-    const timer = setTimeout(() => {
-      timedOut = true;
-      if (useProcessGroup && child.pid != null) {
-        try {
-          process.kill(-child.pid, "SIGKILL");
-        } catch {
-          child.kill("SIGKILL");
-        }
+    let aborted = false;
+    let settled = false;
+    let killInitiated = false;
+    let timer: NodeJS.Timeout | undefined;
+    let forceResolveTimer: NodeJS.Timeout | undefined;
+    let abortListener: (() => void) | undefined;
+
+    const removeAbortListener = () => {
+      if (opts.signal && abortListener) {
+        opts.signal.removeEventListener("abort", abortListener);
+        abortListener = undefined;
+      }
+    };
+
+    const initiateKill = () => {
+      if (killInitiated) return;
+      killInitiated = true;
+      // 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");
       }
-    }, timeoutMs);
-    timer.unref?.();
+      // 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?.();
+    };
 
-    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);
+      removeAbortListener();
       const duration = Date.now() - started;
       const stdoutBuf = Buffer.concat(stdoutChunks);
       const stderrBuf = Buffer.concat(stderrChunks);
@@ -262,11 +317,13 @@ export function runExecSandbox(
       const digest =
         digestBody.length > 0
           ? digestBody
-          : timedOut
-            ? "[no stdout — timed out]"
-            : stderrBuf.length > 0
-              ? `[no stdout — tail of stderr]\n${tail(stderrBuf, opts.digest_chars)}`
-              : "[no output]";
+          : aborted
+            ? "[no stdout — aborted]"
+            : timedOut
+              ? "[no stdout — timed out]"
+              : stderrBuf.length > 0
+                ? `[no stdout — tail of stderr]\n${tail(stderrBuf, opts.digest_chars)}`
+                : "[no output]";
 
       const result: ExecSandboxResult = {
         id,
@@ -274,6 +331,8 @@ export function runExecSandbox(
         exit_code: exitCode,
         signal,
         timed_out: timedOut,
+        aborted,
+        force_resolved: forceResolved,
         duration_ms: duration,
         stdout_bytes: stdoutBytes,
         stderr_bytes: stderrBytes,
@@ -288,6 +347,26 @@ export function runExecSandbox(
       resolveP(result);
     };
 
+    timer = setTimeout(() => {
+      timedOut = true;
+      initiateKill();
+    }, timeoutMs);
+    timer.unref?.();
+
+    if (opts.signal) {
+      abortListener = () => {
+        if (settled || timedOut) return;
+        aborted = true;
+        clearTimeout(timer);
+        initiateKill();
+      };
+      if (opts.signal.aborted) {
+        abortListener();
+      } else {
+        opts.signal.addEventListener("abort", abortListener, { once: true });
+      }
+    }
+
     child.on("error", (err) => {
       const message = err instanceof Error ? err.message : String(err);
       const line = `child error: ${message}\n`;
@@ -324,6 +403,8 @@ function writeMeta(
     exit_code: result.exit_code,
     signal: result.signal,
     timed_out: result.timed_out,
+    aborted: result.aborted === true,
+    force_resolved: result.force_resolved,
     duration_ms: result.duration_ms,
     stdout_bytes: result.stdout_bytes,
     stderr_bytes: result.stderr_bytes,
@@ -331,7 +412,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/export-html.ts

@@ -874,9 +874,10 @@ function buildChangelogSection(data: VisualizerData): string {
 
 function buildKnowledgeSection(data: VisualizerData): string {
   const k = data.knowledge;
-  if (!k.exists) return section('knowledge', 'Knowledge', '<p class="empty">No KNOWLEDGE.md found.</p>');
+  const memories = data.memories;
+  if (!k.exists && memories.entries.length === 0) return section('knowledge', 'Knowledge', '<p class="empty">No KNOWLEDGE.md found.</p>');
   const total = k.rules.length + k.patterns.length + k.lessons.length;
-  if (total === 0) return section('knowledge', 'Knowledge', '<p class="empty">KNOWLEDGE.md exists but no entries parsed.</p>');
+  if (total === 0 && memories.entries.length === 0) return section('knowledge', 'Knowledge', '<p class="empty">KNOWLEDGE.md exists but no entries parsed.</p>');
 
   const rulesHtml = k.rules.length > 0 ? `
     <h3>Rules <span class="count">${k.rules.length}</span></h3>
@@ -899,7 +900,14 @@ function buildKnowledgeSection(data: VisualizerData): string {
       <tbody>${k.lessons.map(l => `<tr><td class="mono">${esc(l.id)}</td><td>${esc(l.content)}</td></tr>`).join('')}</tbody>
     </table>` : '';
 
-  return section('knowledge', `Knowledge <span class="count">${total}</span>`, `${rulesHtml}${patternsHtml}${lessonsHtml}`);
+  const memoriesHtml = memories.entries.length > 0 ? `
+    <h3>Memories <span class="count">${memories.entries.length}/${memories.totalCount}</span></h3>
+    <table class="tbl">
+      <thead><tr><th>ID</th><th>Category</th><th>Scope</th><th>Memory</th></tr></thead>
+      <tbody>${memories.entries.map(m => `<tr><td class="mono">${esc(m.id)}</td><td>${esc(m.category)}</td><td>${esc(m.scope)}</td><td>${esc(m.content)}</td></tr>`).join('')}</tbody>
+    </table>` : '';
+
+  return section('knowledge', `Knowledge <span class="count">${total + memories.totalCount}</span>`, `${rulesHtml}${patternsHtml}${lessonsHtml}${memoriesHtml}`);
 }
 
 // ─── Section: Captures ────────────────────────────────────────────────────────
@@ -1005,4 +1013,3 @@ function hRow(label: string, value: string, status?: 'ok' | 'caution' | 'warn'):
 
 function shortModel(m: string) { return m.replace(/^claude-/, '').replace(/^anthropic\//, ''); }
 function truncStr(s: string, n: number) { return s.length > n ? s.slice(0, n - 1) + '\u2026' : s; }
-

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

@@ -13,6 +13,84 @@ import type { UnitMetrics } from "./metrics.js";
 import { gsdRoot } from "./paths.js";
 import { formatDuration, fileLink } from "../shared/format-utils.js";
 import { getErrorMessage } from "./error-utils.js";
+import { isDbAvailable } from "./gsd-db.js";
+import { openExistingWorkflowDatabase } from "./db-workspace.js";
+import { getActiveMemories, getActiveMemoriesRanked } from "./memory-store.js";
+import type { MemoryInfo } from "./visualizer-data.js";
+
+const EXPORT_MEMORY_LIMIT = 20;
+const EXPORT_MEMORY_CONTENT_LIMIT = 2000;
+
+interface ExportVisualizerData {
+  totals: any;
+  byPhase: any[];
+  bySlice: any[];
+  byModel: any[];
+  units: any[];
+  criticalPath?: any;
+  remainingSliceCount?: number;
+  memories?: MemoryInfo;
+}
+
+function ensureExportDb(basePath: string): void {
+  if (isDbAvailable()) return;
+  openExistingWorkflowDatabase(basePath);
+}
+
+function loadExportMemories(basePath: string, visualizerData?: ExportVisualizerData): MemoryInfo {
+  if (visualizerData?.memories) return limitMemoryInfo(visualizerData.memories);
+  ensureExportDb(basePath);
+  try {
+    const allActive = getActiveMemories();
+    const ranked = getActiveMemoriesRanked(EXPORT_MEMORY_LIMIT);
+    return {
+      totalCount: allActive.length,
+      entries: ranked.map((memory) => ({
+        id: memory.id,
+        category: memory.category,
+        content: limitMemoryContent(memory.content),
+        confidence: memory.confidence,
+        hitCount: memory.hit_count,
+        scope: memory.scope,
+        tags: memory.tags,
+        updatedAt: memory.updated_at,
+      })),
+    };
+  } catch {
+    return { entries: [], totalCount: 0 };
+  }
+}
+
+function limitMemoryInfo(memories: MemoryInfo): MemoryInfo {
+  return {
+    totalCount: memories.totalCount,
+    entries: memories.entries.map((memory) => ({
+      ...memory,
+      content: limitMemoryContent(memory.content),
+    })),
+  };
+}
+
+function limitMemoryContent(content: string): string {
+  if (content.length <= EXPORT_MEMORY_CONTENT_LIMIT) return content;
+  return `${content.slice(0, EXPORT_MEMORY_CONTENT_LIMIT).trimEnd()}...`;
+}
+
+function formatMemoryLines(memories: MemoryInfo): string[] {
+  if (memories.entries.length === 0) return [];
+  return [
+    `## Memories`,
+    ``,
+    `Active memories: ${memories.totalCount}`,
+    ``,
+    ...memories.entries.map((memory) => {
+      const scope = memory.scope ? `, scope ${memory.scope}` : "";
+      const tags = memory.tags.length > 0 ? `, tags ${memory.tags.join(", ")}` : "";
+      return `- **${memory.id}** (${memory.category}, confidence ${Math.round(memory.confidence * 100)}%, hits ${memory.hitCount}${scope}${tags}): ${memory.content}`;
+    }),
+    ``,
+  ];
+}
 
 /**
  * Open a file in the user's default browser.
@@ -37,7 +115,7 @@ export function openInBrowser(filePath: string): void {
 export function writeExportFile(
   basePath: string,
   format: "markdown" | "json",
-  visualizerData?: { totals: any; byPhase: any[]; bySlice: any[]; byModel: any[]; units: any[]; criticalPath?: any; remainingSliceCount?: number },
+  visualizerData?: ExportVisualizerData,
 ): string | null {
   const ledger = getLedger();
   let units: UnitMetrics[];
@@ -58,6 +136,7 @@ export function writeExportFile(
   const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
 
   if (format === "json") {
+    const memories = loadExportMemories(basePath, visualizerData);
     const report = {
       exportedAt: new Date().toISOString(),
       project: projectName,
@@ -65,6 +144,7 @@ export function writeExportFile(
       byPhase: visualizerData?.byPhase ?? aggregateByPhase(units),
       bySlice: visualizerData?.bySlice ?? aggregateBySlice(units),
       byModel: visualizerData?.byModel ?? aggregateByModel(units),
+      memories,
       units,
     };
     const outPath = join(exportDir, `export-${timestamp}.json`);
@@ -75,6 +155,8 @@ export function writeExportFile(
     const phases = visualizerData?.byPhase ?? aggregateByPhase(units);
     const slices = visualizerData?.bySlice ?? aggregateBySlice(units);
 
+    const memories = loadExportMemories(basePath, visualizerData);
+
     const md = [
       `# GSD Session Report — ${projectName}`,
       ``,
@@ -101,6 +183,7 @@ export function writeExportFile(
         `| ${s.sliceId} | ${s.units} | ${formatCost(s.cost)} | ${formatTokenCount(s.tokens.total)} | ${formatDuration(s.duration)} |`,
       ),
       ``,
+      ...formatMemoryLines(memories),
     ].join("\n");
 
     const outPath = join(exportDir, `export-${timestamp}.md`);
@@ -258,6 +341,7 @@ export async function handleExport(args: string, ctx: ExtensionCommandContext, b
   const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
 
   if (format === "json") {
+    const memories = loadExportMemories(basePath);
     const report = {
       exportedAt: new Date().toISOString(),
       project: projectName,
@@ -265,6 +349,7 @@ export async function handleExport(args: string, ctx: ExtensionCommandContext, b
       byPhase: aggregateByPhase(units),
       bySlice: aggregateBySlice(units),
       byModel: aggregateByModel(units),
+      memories,
       units,
     };
     const outPath = join(exportDir, `export-${timestamp}.json`);
@@ -274,6 +359,7 @@ export async function handleExport(args: string, ctx: ExtensionCommandContext, b
     const totals = getProjectTotals(units);
     const phases = aggregateByPhase(units);
     const slices = aggregateBySlice(units);
+    const memories = loadExportMemories(basePath);
 
     const md = [
       `# GSD Session Report — ${projectName}`,
@@ -301,6 +387,7 @@ export async function handleExport(args: string, ctx: ExtensionCommandContext, b
         `| ${s.sliceId} | ${s.units} | ${formatCost(s.cost)} | ${formatTokenCount(s.tokens.total)} | ${formatDuration(s.duration)} |`,
       ),
       ``,
+      ...formatMemoryLines(memories),
       `## Unit History`,
       ``,
       `| Type | ID | Model | Cost | Tokens | Duration |`,

package/src/resources/extensions/gsd/file-lock.ts

@@ -56,9 +56,9 @@ export function withFileLockSync<T>(
 ): T {
   if (!existsSync(filePath)) return fn();
 
-  const retries = opts.retries ?? DEFAULT_RETRIES;
   const stale = opts.stale ?? DEFAULT_STALE_MS;
   const onLocked: OnLocked = opts.onLocked ?? "fail";
+  const retries = onLocked === "skip" ? 0 : (opts.retries ?? DEFAULT_RETRIES);
 
   try {
     const release = acquireLockSyncWithRetry(filePath, retries, stale);

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;
 }