mandrel 1.57.0

package/.agents/scripts/lib/crap-utils.js

@@ -0,0 +1,479 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import escomplex from 'typhonjs-escomplex';
+import { canonicalise as canonicalisePath } from './baselines/path-canon.js';
+import {
+  coverageForMethodInEntry,
+  findCoverageEntry,
+} from './coverage-utils.js';
+import { runOnPool } from './cpu-pool.js';
+import { crapFormula } from './crap-engine.js';
+import { Logger } from './Logger.js';
+import {
+  resolveTsTranspilerVersion,
+  scanDirectory,
+  transpileIfNeeded,
+} from './maintainability-utils.js';
+
+const CRAP_WORKER_URL = new URL('./workers/crap-worker.js', import.meta.url);
+
+// Below this batch size the pool's spawn overhead dominates — fall
+// back to in-process serial scoring. The full repo (~200+ files)
+// always takes the pool path; tests with handful-of-files fixtures
+// stay serial and remain byte-identical to the pre-pool output.
+const SERIAL_THRESHOLD = 8;
+// 1.1.0 — TypeScript support landed in 5.29.0. Bumped from 1.0.0 because
+// the scanner now emits CRAP rows for TS/TSX paths that the previous
+// kernel could never reach. The CRAP formula and per-method scoring
+// shape are unchanged for JS sources.
+export const KERNEL_VERSION = '1.1.0';
+export { resolveTsTranspilerVersion };
+
+const SCHEMA_REF = '.agents/schemas/crap-baseline.schema.json';
+
+/**
+ * Resolve the running `typhonjs-escomplex` version by walking up from `cwd`
+ * and reading the nearest `node_modules/typhonjs-escomplex/package.json`.
+ * Returns `'0.0.0'` when the dependency cannot be found — callers treat that
+ * sentinel as "unknown environment" and may refuse to persist a baseline.
+ *
+ * @param {string} [cwd]
+ * @returns {string}
+ */
+export function resolveEscomplexVersion(cwd = process.cwd()) {
+  let dir = path.resolve(cwd);
+  const { root } = path.parse(dir);
+  while (true) {
+    const pkgPath = path.join(
+      dir,
+      'node_modules',
+      'typhonjs-escomplex',
+      'package.json',
+    );
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const parsed = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        if (parsed && typeof parsed.version === 'string') {
+          return parsed.version;
+        }
+      } catch {
+        // fall through to parent lookup
+      }
+    }
+    if (dir === root) break;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return '0.0.0';
+}
+
+function resolveBaselinePath({ cwd = process.cwd(), baselinePath } = {}) {
+  if (typeof baselinePath !== 'string' || baselinePath.length === 0) {
+    throw new TypeError(
+      'crap-utils: opts.baselinePath is required (Epic #730 Story 5.5 — ' +
+        'callers resolve the path via getBaselines(config).crap.path).',
+    );
+  }
+  return path.isAbsolute(baselinePath)
+    ? baselinePath
+    : path.join(cwd, baselinePath);
+}
+
+/**
+ * Load the CRAP baseline envelope from disk.
+ *
+ * Returns the parsed envelope on success, or `null` when the file is missing,
+ * unreadable, or structurally unusable. Version-mismatch detection is a
+ * caller concern — this loader never silently rescores or mutates the
+ * envelope.
+ *
+ * @param {{cwd?: string, baselinePath?: string}} [opts]
+ * @returns {{
+ *   kernelVersion: string,
+ *   escomplexVersion: string,
+ *   rows: Array<{file: string, method: string, startLine: number, crap: number}>,
+ * }|null}
+ */
+/**
+ * Story #1895: shipped baseline switched to the canonical envelope shape
+ * (`$schema`, `kernelVersion`, `generatedAt`, `rollup`, `rows` keyed on
+ * `path`). Backfill the legacy `escomplexVersion`/`tsTranspilerVersion`
+ * version fields from the running scorer and re-key rows by `file` so
+ * existing comparators keep working until Story #1912 lands the unified
+ * gate. Detection probes the first row for the new `path` key — the
+ * legacy envelope also carries `$schema` but keys rows by `file`.
+ */
+function projectCrapEnvelopeToLegacy(parsed) {
+  if (
+    !Array.isArray(parsed.rows) ||
+    parsed.rows.length === 0 ||
+    typeof parsed.rows[0]?.path !== 'string'
+  ) {
+    return null;
+  }
+  return {
+    kernelVersion: parsed.kernelVersion,
+    escomplexVersion: resolveEscomplexVersion(),
+    tsTranspilerVersion: resolveTsTranspilerVersion(),
+    rows: parsed.rows.map((row) => ({
+      crap: row.crap,
+      file: row.path,
+      method: row.method,
+      startLine: row.startLine,
+    })),
+  };
+}
+
+export function getCrapBaseline(opts = {}) {
+  const filePath = resolveBaselinePath(opts);
+  if (!fs.existsSync(filePath)) return null;
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf-8');
+  } catch (err) {
+    Logger.warn(`[crap-utils] unable to read baseline: ${err.message}`);
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    Logger.warn(`[crap-utils] baseline is not valid JSON: ${err.message}`);
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return null;
+  }
+  const projected = projectCrapEnvelopeToLegacy(parsed);
+  if (projected) return projected;
+  if (typeof parsed.kernelVersion !== 'string') return null;
+  if (typeof parsed.escomplexVersion !== 'string') return null;
+  if (!Array.isArray(parsed.rows)) return null;
+  // tsTranspilerVersion landed in kernel 1.1.0. Older envelopes (1.0.0)
+  // do not carry it; we surface that as the sentinel '0.0.0' so the
+  // version-drift detector can warn on first 1.1.0 check without
+  // crashing on a missing field.
+  if (typeof parsed.tsTranspilerVersion !== 'string') {
+    parsed.tsTranspilerVersion = '0.0.0';
+  }
+  return parsed;
+}
+
+/**
+ * Project rich scan rows onto the minimal baseline row shape and assemble an
+ * envelope ready for the shared V2 writer.
+ *
+ * `tsTranspilerVersion` stamps the resolved `typescript` package version so
+ * consumers can detect transpiler drift on TS rows. Defaults to the
+ * sentinel `'0.0.0'` when typescript is unresolvable — drift detection
+ * then becomes a no-op rather than failing the bake.
+ *
+ * @param {{
+ *   rows: Array<{file: string, method: string, startLine: number, crap: number|null}>,
+ *   escomplexVersion: string,
+ *   kernelVersion?: string,
+ *   tsTranspilerVersion?: string,
+ * }} params
+ */
+export function buildBaselineEnvelope({
+  rows,
+  escomplexVersion,
+  kernelVersion = KERNEL_VERSION,
+  tsTranspilerVersion = resolveTsTranspilerVersion(),
+}) {
+  if (typeof escomplexVersion !== 'string' || !escomplexVersion) {
+    throw new TypeError('buildBaselineEnvelope: escomplexVersion is required');
+  }
+  const scored = (rows ?? []).filter(
+    (r) => typeof r?.crap === 'number' && Number.isFinite(r.crap),
+  );
+  return {
+    $schema: SCHEMA_REF,
+    escomplexVersion,
+    kernelVersion,
+    rows: scored.map((r) => ({
+      crap: r.crap,
+      file: r.file,
+      method: r.method,
+      startLine: r.startLine,
+    })),
+    tsTranspilerVersion,
+  };
+}
+
+/**
+ * Parse `source` exactly once with escomplex and derive both the
+ * maintainability score and the raw CRAP method rows from that single report.
+ *
+ * Callers that need both scores for the same source string (e.g. a combined
+ * CRAP + MI scan) MUST use this helper rather than calling `calculateCrapForSource`
+ * and `calculateForSource` separately — doing so would parse the AST twice.
+ *
+ * Coverage-dependent CRAP values require a `coverageForFile` entry (the value
+ * from `coverage-final.json` for this file). Pass `null` when no coverage is
+ * available; method rows whose coverage cannot be resolved will carry
+ * `coverage: null` and `crap: null`.
+ *
+ * @param {string} source Prepared (possibly transpiled) JavaScript source text.
+ * @param {object|null} coverageForFile Istanbul coverage entry for this file.
+ * @returns {{
+ *   report: object,
+ *   miScore: number,
+ *   crapRows: Array<{
+ *     method: string,
+ *     startLine: number,
+ *     cyclomatic: number,
+ *     coverage: number|null,
+ *     crap: number|null,
+ *   }>,
+ *   parseError: boolean,
+ * }}
+ */
+export function analyzeOnce(source, coverageForFile) {
+  let report;
+  try {
+    report = escomplex.analyzeModule(source);
+  } catch {
+    return { report: null, miScore: 0, crapRows: [], parseError: true };
+  }
+  const miScore =
+    typeof report.maintainability === 'number' ? report.maintainability : 0;
+  const methods = report?.methods ?? [];
+  const crapRows = [];
+  for (const m of methods) {
+    const startLine = m?.lineStart;
+    if (typeof startLine !== 'number') continue;
+    const cyclomatic = m?.cyclomatic ?? 0;
+    const coverage = coverageForFile
+      ? coverageForMethodInEntry(coverageForFile, startLine)
+      : null;
+    const crap = coverage === null ? null : crapFormula(cyclomatic, coverage);
+    crapRows.push({ method: m.name, startLine, cyclomatic, coverage, crap });
+  }
+  return { report, miScore, crapRows, parseError: false };
+}
+
+/**
+ * Scan `targetDirs` for JS files, score each method via the CRAP kernel, and
+ * return enriched rows plus skip counters. Does not write to disk.
+ *
+ * Files without a coverage entry are skipped when `requireCoverage` is `true`
+ * (the default); methods whose coverage cannot be resolved are always
+ * skipped from the returned rows so the baseline never contains
+ * partially-scored entries. Both counters surface for reporting.
+ *
+ * When `scopeFiles` is provided (the `--changed-since` code path) files
+ * discovered via directory walking are filtered against that set before any
+ * I/O or scoring happens — so pre-push / PR-CI runs never pay the
+ * parse-and-score cost on untouched files.
+ *
+ * When `preScannedFiles` is provided (an array of absolute paths already
+ * collected by a prior `scanDirectory` pass over the same `targetDirs`), the
+ * directory walk is skipped entirely — the supplied list is used as-is.
+ * Callers that run both CRAP and MI passes over the same target dirs (e.g.
+ * `regenerateMainFromTree`) SHOULD pass the MI scan's file list here so the
+ * tree is walked only once per run.
+ *
+ * @param {{
+ *   targetDirs: string[],
+ *   coverage: object|null,
+ *   requireCoverage?: boolean,
+ *   cwd?: string,
+ *   scopeFiles?: Set<string>|string[]|null,
+ *   preScannedFiles?: string[]|null,
+ * }} params
+ * @returns {{
+ *   rows: Array<{
+ *     file: string,
+ *     method: string,
+ *     startLine: number,
+ *     cyclomatic: number,
+ *     coverage: number,
+ *     crap: number,
+ *   }>,
+ *   scannedFiles: number,
+ *   skippedFilesNoCoverage: number,
+ *   skippedMethodsNoCoverage: number,
+ * }}
+ */
+export async function scanAndScore({
+  targetDirs,
+  coverage,
+  requireCoverage = true,
+  cwd = process.cwd(),
+  scopeFiles = null,
+  ignoreGlobs = [],
+  preScannedFiles = null,
+}) {
+  if (!Array.isArray(targetDirs)) {
+    throw new TypeError('scanAndScore: targetDirs must be an array');
+  }
+  const scopeSet =
+    scopeFiles == null
+      ? null
+      : scopeFiles instanceof Set
+        ? scopeFiles
+        : new Set(scopeFiles);
+  // When the caller supplies a pre-walked file list (e.g. from a prior MI
+  // scan over the same target dirs), skip the directory walk entirely.
+  const files = preScannedFiles != null ? [...preScannedFiles] : [];
+  if (preScannedFiles == null) {
+    for (const dir of targetDirs) {
+      const abs = path.isAbsolute(dir) ? dir : path.resolve(cwd, dir);
+      scanDirectory(abs, files, { cwd, ignoreGlobs });
+    }
+  }
+  files.sort();
+
+  // Build the work-queue first so scopeFile filtering happens before
+  // any I/O / IPC. `scannedFiles` is the in-scope count.
+  // Story #2079: route every relPath through path-canon so a scan from
+  // inside `.worktrees/<workspace>/` (with cwd pointing at the main
+  // checkout) cannot leak the worktree prefix into the on-disk baseline's
+  // `file` / `path` keys downstream.
+  const queue = [];
+  for (const abs of files) {
+    const rawRel = path.relative(cwd, abs).replace(/\\/g, '/');
+    const relPath = canonicalisePath(rawRel);
+    if (scopeSet && !scopeSet.has(relPath)) continue;
+    queue.push({ abs, relPath, requireCoverage });
+  }
+  const scannedFiles = queue.length;
+
+  const perFile =
+    queue.length < SERIAL_THRESHOLD
+      ? queue.map((item) => ({ item, result: scoreFileSerial(item, coverage) }))
+      : await scoreFilesViaPool(queue, coverage);
+
+  const rows = [];
+  let skippedFilesNoCoverage = 0;
+  let skippedMethodsNoCoverage = 0;
+  for (const { item, result } of perFile) {
+    if (!result) continue; // unrecoverable per-file failure: drop silently to match pre-pool semantics
+    if (result.skippedFileNoCoverage) {
+      skippedFilesNoCoverage += 1;
+      continue;
+    }
+    if (result.rows === null) {
+      // read/transpile/parse failure: drop and move on, but if the worker
+      // attached an error message (calculateCrapForSource throw) surface it
+      // so the run isn't silent on the ops side.
+      if (result.error) {
+        Logger.warn(
+          `[crap-utils] failed to score ${item.relPath}: ${result.error}`,
+        );
+      }
+      continue;
+    }
+    skippedMethodsNoCoverage += result.skippedMethodsNoCoverage ?? 0;
+    for (const mr of result.rows) {
+      rows.push({
+        file: item.relPath,
+        method: mr.method,
+        startLine: mr.startLine,
+        cyclomatic: mr.cyclomatic,
+        coverage: mr.coverage,
+        crap: mr.crap,
+      });
+    }
+  }
+
+  rows.sort((a, b) => {
+    if (a.file !== b.file) return a.file < b.file ? -1 : 1;
+    if (a.startLine !== b.startLine) return a.startLine - b.startLine;
+    if (a.method !== b.method) return a.method < b.method ? -1 : 1;
+    return 0;
+  });
+
+  return {
+    rows,
+    scannedFiles,
+    skippedFilesNoCoverage,
+    skippedMethodsNoCoverage,
+  };
+}
+
+/**
+ * In-process scorer used by both the small-batch fast path and as the
+ * reference implementation against which the worker output is asserted
+ * byte-for-byte in the cpu-pool tests.
+ *
+ * Uses `analyzeOnce` so the source is parsed a single time and both the
+ * CRAP rows and the MI score are derived from the same escomplex report.
+ */
+function scoreFileSerial({ abs, relPath, requireCoverage }, coverage) {
+  const entry = findCoverageEntry(coverage, relPath);
+  if (requireCoverage && entry === null) {
+    return {
+      skippedFileNoCoverage: true,
+      rows: [],
+      skippedMethodsNoCoverage: 0,
+    };
+  }
+  let source;
+  try {
+    source = fs.readFileSync(abs, 'utf-8');
+  } catch {
+    return {
+      skippedFileNoCoverage: false,
+      rows: null,
+      skippedMethodsNoCoverage: 0,
+    };
+  }
+  const prepared = transpileIfNeeded(abs, source);
+  if (prepared === null) {
+    return {
+      skippedFileNoCoverage: false,
+      rows: null,
+      skippedMethodsNoCoverage: 0,
+    };
+  }
+  const { crapRows, parseError } = analyzeOnce(prepared, entry);
+  if (parseError) {
+    return {
+      skippedFileNoCoverage: false,
+      rows: null,
+      skippedMethodsNoCoverage: 0,
+    };
+  }
+  const rows = [];
+  let skippedMethodsNoCoverage = 0;
+  for (const mr of crapRows) {
+    if (mr.crap === null || mr.coverage === null) {
+      skippedMethodsNoCoverage += 1;
+      continue;
+    }
+    rows.push({
+      method: mr.method,
+      startLine: mr.startLine,
+      cyclomatic: mr.cyclomatic,
+      coverage: mr.coverage,
+      crap: mr.crap,
+    });
+  }
+  return { skippedFileNoCoverage: false, rows, skippedMethodsNoCoverage };
+}
+
+async function scoreFilesViaPool(queue, coverage) {
+  // Resolve each file's coverage entry on the host before dispatch so workers
+  // receive only their file's entry rather than the whole map. This removes the
+  // O(workers × coverageMapSize) structured-clone at spawn time.
+  const enrichedQueue = queue.map((item) => ({
+    ...item,
+    coverageEntry: findCoverageEntry(coverage, item.relPath),
+  }));
+  const results = await runOnPool(CRAP_WORKER_URL, enrichedQueue, {
+    workerData: {},
+  });
+  return results.map((r, i) => {
+    const item = queue[i];
+    if (!r || r.__cpuPoolError) {
+      Logger.warn(
+        `[crap-utils] worker pool error for ${item.relPath}: ${r?.message ?? 'unknown'}`,
+      );
+      return { item, result: null };
+    }
+    return { item, result: r };
+  });
+}

package/.agents/scripts/lib/degraded-mode.js

@@ -0,0 +1,69 @@
+/**
+ * Shared helper for the explicit-degraded contract used by soft-failing gates.
+ *
+ * Tech Spec #819 §"Degraded-mode contract (Story 3)" — three soft-fail sites
+ * (select-audits diff-timeout, lint-baseline JSON-parse, baseline-refresh
+ * guardrail git-diff) historically returned a silent zero/empty result. The
+ * new contract is:
+ *
+ *   { ok: false, degraded: true, reason: <code>, detail: <human> }
+ *
+ * with a non-zero CLI exit so the operator/agent has explicit visibility, OR
+ * a hard-fail closed when `--gate-mode` / `MANDREL_GATE_MODE=1` is set
+ * (CI invocations).
+ */
+
+/**
+ * Build the canonical degraded envelope.
+ *
+ * @param {string} reason  Machine-readable code (e.g. `GIT_DIFF_TIMEOUT`).
+ * @param {string} [detail] Human-readable explanation for operators.
+ * @returns {{ ok: false, degraded: true, reason: string, detail: string }}
+ */
+export function degraded(reason, detail = '') {
+  return { ok: false, degraded: true, reason, detail };
+}
+
+/**
+ * True when `value` carries the degraded envelope shape.
+ */
+export function isDegraded(value) {
+  return Boolean(
+    value &&
+      typeof value === 'object' &&
+      value.ok === false &&
+      value.degraded === true &&
+      typeof value.reason === 'string',
+  );
+}
+
+/**
+ * Decide whether the caller is running in gate-mode (hard-fail closed) based
+ * on argv and env. CI invocations set `--gate-mode` or
+ * `MANDREL_GATE_MODE=1`; local invocations leave both unset.
+ */
+export function isGateMode({ argv = process.argv, env = process.env } = {}) {
+  if (Array.isArray(argv) && argv.includes('--gate-mode')) return true;
+  if (env && env.MANDREL_GATE_MODE === '1') return true;
+  return false;
+}
+
+/**
+ * In gate-mode, throw a hard-fail Error keyed to `reason`. Otherwise return
+ * the degraded envelope. Centralises the if-gate-mode branch so each site has
+ * a single call site.
+ *
+ * @param {string} reason
+ * @param {string} [detail]
+ * @param {{ argv?: string[], env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {{ ok: false, degraded: true, reason: string, detail: string }}
+ */
+export function softFailOrThrow(reason, detail = '', opts) {
+  if (isGateMode(opts)) {
+    const err = new Error(`[gate-mode] hard-fail: ${reason}: ${detail}`);
+    err.code = reason;
+    err.degraded = true;
+    throw err;
+  }
+  return degraded(reason, detail);
+}

package/.agents/scripts/lib/dependency-parser.js

@@ -0,0 +1,129 @@
+/**
+ * dependency-parser.js — Shared Dependency & Metadata Parsing Utilities
+ *
+ * Canonical implementation of dependency-related regex parsing and
+ * ticket metadata extraction. Eliminates duplicated implementations
+ * across dispatcher.js, verify-prereqs.js, and providers/github.js.
+ */
+
+/**
+ * Parse `blocked by #NNN` and `depends on #NNN` references from text.
+ * Handles case-insensitive variations.
+ *
+ * @param {string} body - Issue body or freeform text.
+ * @returns {number[]} Array of issue numbers this text declares as blockers.
+ */
+export function parseBlockedBy(body) {
+  if (!body) return [];
+  const re = /(?:blocked\s+by|depends\s+on):?\s+#(\d+)/gi;
+  const ids = [...body.matchAll(re)].map((m) => Number.parseInt(m[1], 10));
+  return [...new Set(ids)];
+}
+
+/**
+ * Parse `blocks #NNN` references from text.
+ *
+ * @param {string} body - Issue body or freeform text.
+ * @returns {number[]} Array of issue numbers this text declares as blocked.
+ */
+export function parseBlocks(body) {
+  if (!body) return [];
+  const re = /blocks\s+#(\d+)/gi;
+  return [...body.matchAll(re)].map((m) => Number.parseInt(m[1], 10));
+}
+
+/**
+ * Extract the parent Epic id from a ticket body. Matches `Epic: #NNN`
+ * anchored to the start of a line (multiline + case-insensitive). The
+ * anchored form prevents accidental matches inside prose ("...this Epic:
+ * #...follow-on..."). Used during state-transition notification dispatch
+ * and Story-level execution planning.
+ *
+ * @param {string|null|undefined} body
+ * @returns {number|null}
+ */
+export function extractEpicIdFromBody(body) {
+  if (!body) return null;
+  const m = body.match(/^Epic:\s*#(\d+)/im);
+  return m ? Number.parseInt(m[1], 10) : null;
+}
+
+/**
+ * Validates that a string is safe to use as a git branch name component.
+ * Rejects shell metacharacters, whitespace, and other dangerous patterns.
+ *
+ * @param {string} value - The value to validate.
+ * @returns {boolean} True if safe for use in branch names.
+ */
+export function isSafeBranchComponent(value) {
+  // Allow: alphanumeric, hyphens, underscores, dots, forward slashes
+  // Reject: everything else (shell metacharacters, spaces, etc.)
+  return /^[a-zA-Z0-9._\-/]+$/.test(value);
+}
+
+/**
+ * Pre-compiled `**Key**: value` matchers for every metadata key we extract.
+ * Construction cost is paid once at module load rather than per task.
+ */
+const METADATA_FIELD_KEYS = [
+  'Persona',
+  'Mode',
+  'Skills',
+  'Focus Areas',
+  'Protocol Version',
+];
+const METADATA_FIELD_RES = new Map(
+  METADATA_FIELD_KEYS.map((k) => [
+    k,
+    new RegExp(`\\*\\*${k}\\*\\*\\s*:?\\s*(.+)`, 'i'),
+  ]),
+);
+
+/**
+ * Parse task execution metadata from the `## Metadata` section of a ticket body.
+ * Returns a plain object with `persona`, `mode`, `skills`, `focusAreas`,
+ * and `protocolVersion`.
+ *
+ * @param {string} body - Issue body text.
+ * @returns {{ persona: string, mode: string, skills: string[], focusAreas: string[], protocolVersion: string }}
+ */
+export function parseTaskMetadata(body) {
+  const defaults = {
+    persona: 'engineer',
+    mode: 'fast',
+    skills: [],
+    focusAreas: [],
+    protocolVersion: '',
+  };
+
+  if (!body) return defaults;
+
+  const metaMatch = body.match(/##\s*Metadata\s*([\s\S]*?)(?=\n##|$)/i);
+  if (!metaMatch) return defaults;
+
+  const block = metaMatch[1];
+
+  function extractField(key) {
+    const re = METADATA_FIELD_RES.get(key);
+    const m = re ? block.match(re) : null;
+    return m ? m[1].trim() : null;
+  }
+
+  function extractList(key) {
+    const raw = extractField(key);
+    if (!raw) return [];
+    return raw
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+  }
+
+  return {
+    persona: extractField('Persona') || defaults.persona,
+    mode: extractField('Mode') || defaults.mode,
+    skills: extractList('Skills'),
+    focusAreas: extractList('Focus Areas'),
+    protocolVersion:
+      extractField('Protocol Version') || defaults.protocolVersion,
+  };
+}