@xemahq/biome-sdk 0.1.1

package/src/builder/lib/extends-precedence.ts

@@ -0,0 +1,195 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// Biome `xema.extends` precedence — runtime side.
+//
+// A biome MAY declare `xema.extends: <id> | <id>[]` in its xema-biome.json.
+// An extending biome is the same-or-upgraded variant of the biome(s) it
+// extends and MAY re-ship their content (agent slugs, workspace manifests,
+// skills, role capabilities, …). When BOTH are installed (both present under
+// the seeder scan roots), the extending biome's contribution must WIN — not
+// crash the seeder with a "duplicate slug" error.
+//
+// This module is the runtime counterpart to the boundary tooling's
+// `buildExtendsIndex` / `extendsOf` in
+// `tooling/boundaries/lib/carved-biomes.mjs`. The two MUST agree on the
+// relation: the CI duplication check allows a dup slug iff the biomes are
+// extends-related; the runtime seeders resolve that same relation into a
+// concrete winner. Keep the two in sync.
+//
+// Precedence rule: the extending (descendant) biome overrides the base
+// (ancestor) it extends, transitively. Two unrelated biomes — or the same
+// biome contributing a slug twice — are a genuine packaging conflict the
+// caller MUST reject (fail-fast, no silent winner).
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type { Dirent } from 'node:fs';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Read a biome manifest's `xema.extends` (string | string[]) from a raw
+ * parsed manifest object. Mirrors the boundary tooling's `extendsOf()` so
+ * runtime precedence and the CI duplication check resolve the identical
+ * relation. Non-string / missing values yield an empty list.
+ */
+function readExtendsTargets(raw: unknown): string[] {
+  const ext = (raw as { xema?: { extends?: unknown } } | null | undefined)?.xema
+    ?.extends;
+  if (Array.isArray(ext)) {
+    return ext.filter((x): x is string => typeof x === 'string');
+  }
+  if (typeof ext === 'string') {
+    return [ext];
+  }
+  return [];
+}
+
+export interface BiomeExtendsIndex {
+  /**
+   * True when `descendant` extends `ancestor` directly OR transitively. The
+   * extending biome is the same-or-upgraded variant and wins on a slug
+   * collision. Returns false for `descendant === ancestor`.
+   */
+  extendsTransitively(descendant: string, ancestor: string): boolean;
+  /** Direct `xema.extends` targets declared by each scanned biome id. */
+  readonly directTargets: ReadonlyMap<string, ReadonlySet<string>>;
+}
+
+/**
+ * Build the extends graph over every biome under the given scan roots by
+ * reading each `xema-biome.json`'s `xema.extends`. Cheap (one stat + read
+ * per biome dir) and side-effect free; safe to call once per seeder boot
+ * alongside `enumerateContentAcrossBiomeTree` (same roots).
+ *
+ * Malformed / unreadable manifests are skipped silently here — the same
+ * contract `enumerateContentAcrossBiomeTree` follows (biome-host owns
+ * manifest validation; a seeder must not crash the whole boot on one bad
+ * sibling manifest).
+ */
+export function buildBiomeExtendsIndex(
+  scanRoots: readonly string[],
+): BiomeExtendsIndex {
+  const directTargets = new Map<string, Set<string>>();
+
+  for (const root of scanRoots) {
+    if (!existsSync(root)) continue;
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(root, { withFileTypes: true }) as Dirent[];
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const manifestPath = join(root, entry.name, 'xema-biome.json');
+      if (!existsSync(manifestPath)) continue;
+      let raw: unknown;
+      try {
+        raw = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+      } catch {
+        continue;
+      }
+      const id = (raw as { xema?: { id?: unknown } } | null | undefined)?.xema
+        ?.id;
+      if (typeof id !== 'string') continue;
+      // A biome may appear under more than one scan root in dev; union its
+      // declared targets rather than overwriting.
+      const existing = directTargets.get(id) ?? new Set<string>();
+      for (const t of readExtendsTargets(raw)) existing.add(t);
+      directTargets.set(id, existing);
+    }
+  }
+
+  const extendsTransitively = (
+    descendant: string,
+    ancestor: string,
+  ): boolean => {
+    if (descendant === ancestor) return false;
+    const seen = new Set<string>();
+    const stack = [...(directTargets.get(descendant) ?? [])];
+    while (stack.length > 0) {
+      const current = stack.pop();
+      if (current === undefined) break;
+      if (current === ancestor) return true;
+      if (seen.has(current)) continue; // cycle guard
+      seen.add(current);
+      for (const next of directTargets.get(current) ?? []) stack.push(next);
+    }
+    return false;
+  };
+
+  return { extendsTransitively, directTargets };
+}
+
+export type ExtendsPrecedence = 'keep-existing' | 'replace' | 'conflict';
+
+/**
+ * Decide which of two biomes contributing the SAME slug wins. The extending
+ * (same-or-upgraded) biome overrides the base it extends; two unrelated
+ * biomes — or the same biome contributing a slug twice — are a genuine
+ * packaging conflict (`'conflict'`) the caller must reject.
+ */
+export function resolveExtendsPrecedence(
+  index: BiomeExtendsIndex,
+  existingBiomeId: string,
+  incomingBiomeId: string,
+): ExtendsPrecedence {
+  if (existingBiomeId === incomingBiomeId) return 'conflict';
+  if (index.extendsTransitively(incomingBiomeId, existingBiomeId)) {
+    return 'replace';
+  }
+  if (index.extendsTransitively(existingBiomeId, incomingBiomeId)) {
+    return 'keep-existing';
+  }
+  return 'conflict';
+}
+
+/**
+ * Deduplicate slug-keyed contributions across biomes, honoring
+ * `xema.extends`. Non-colliding items keep their first-seen order; on a
+ * collision the extending biome's item replaces the base's. A collision
+ * between unrelated biomes (or within one biome) is reported through
+ * `onConflict`, which MUST throw (its `never` return type enforces this) so
+ * a real packaging conflict fails fast instead of silently picking a winner.
+ */
+export function dedupeBySlugWithExtends<T>(
+  items: readonly T[],
+  opts: {
+    readonly index: BiomeExtendsIndex;
+    readonly slugOf: (item: T) => string;
+    readonly biomeIdOf: (item: T) => string;
+    readonly onConflict: (slug: string, existing: T, incoming: T) => never;
+  },
+): T[] {
+  const winners = new Map<string, T>();
+  const order: string[] = [];
+
+  for (const item of items) {
+    const slug = opts.slugOf(item);
+    const existing = winners.get(slug);
+    if (existing === undefined) {
+      winners.set(slug, item);
+      order.push(slug);
+      continue;
+    }
+    const decision = resolveExtendsPrecedence(
+      opts.index,
+      opts.biomeIdOf(existing),
+      opts.biomeIdOf(item),
+    );
+    if (decision === 'replace') {
+      winners.set(slug, item);
+    } else if (decision === 'conflict') {
+      opts.onConflict(slug, existing, item);
+    }
+    // 'keep-existing' → leave the current winner in place.
+  }
+
+  return order.map((slug) => {
+    const winner = winners.get(slug);
+    if (winner === undefined) {
+      // Unreachable: every slug in `order` has a winner.
+      throw new Error(`dedupeBySlugWithExtends: lost winner for slug "${slug}"`);
+    }
+    return winner;
+  });
+}

package/src/builder/lib/workflow-phase-config-loader.ts

@@ -0,0 +1,163 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// Workflow phase-config loader.
+//
+// A sub-app biome that defines a gated delivery pipeline ships exactly one
+// `workflow-config/phase-config.json` (validated by `WorkflowPhaseConfigSchema`).
+// The kernel carries no domain phase enum — platform services that need the
+// ordered phase list, the coordinator→parent hierarchy, or the per-phase
+// gate-reviewer map load it AT RUNTIME via this single shared helper, so the
+// FS-discovery + merge logic stays DRY across consumers (llm-registry-api,
+// opencode-pool-api, …).
+//
+// The file lives under the existing `workflowConfig` content kind — no new
+// content kind, no new manifest field. A biome already listing
+// `workflowConfig` in `xema.ships.content[]` is scanned automatically.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  parseContribution,
+  type WorkflowPhaseConfig,
+} from './contribution-schemas';
+import { WorkflowPhaseConfigSchema } from './contribution-schemas';
+import { enumerateBiomesWithContent } from './content-walker';
+
+/** Conventional filename for the phase-config document inside `workflow-config/`. */
+const PHASE_CONFIG_FILENAME = 'phase-config.json';
+
+/**
+ * A phase-config loaded from one biome, tagged with the originating
+ * biome id so a merge collision can name the culprit.
+ */
+export interface LoadedWorkflowPhaseConfig {
+  readonly biomeId: string;
+  readonly config: WorkflowPhaseConfig;
+}
+
+/**
+ * The merged, cross-biome view of every shipped phase-config. Phase keys
+ * are globally unique by contract — `loadWorkflowPhaseConfigs` throws on a
+ * collision rather than silently picking a winner.
+ */
+export interface MergedWorkflowPhaseConfig {
+  /** Ordered phase keys across all biomes (biome order, then file order). */
+  readonly orderedPhaseKeys: readonly string[];
+  /** Phase key → lifecycle | delivery. */
+  readonly phaseCategory: ReadonlyMap<string, 'lifecycle' | 'delivery'>;
+  /** Direct-call agent phase keys (run outside the sequential pipeline). */
+  readonly directAgentPhases: readonly string[];
+  /**
+   * All configurable phase keys = ordered pipeline phases followed by
+   * direct-agent phases. Mirrors the legacy `ALL_CONFIGURABLE_PHASES`.
+   */
+  readonly allConfigurablePhases: readonly string[];
+  /** Sub-phase coordinator agent slug → parent phase key. */
+  readonly subPhaseToParent: ReadonlyMap<string, string>;
+  /** Phase key → required review-capability keys. */
+  readonly reviewCapabilities: ReadonlyMap<string, readonly string[]>;
+  /** Every distinct review-capability key across all phases. */
+  readonly allReviewCapabilities: readonly string[];
+}
+
+/**
+ * Scan every server biome under `scanRoots` for a
+ * `workflow-config/phase-config.json` and return one validated entry per
+ * biome that ships one. Biomes without the file are skipped (a biome
+ * may ship workflows without defining a gated phase pipeline).
+ */
+export function loadWorkflowPhaseConfigs(
+  scanRoots: readonly string[],
+): LoadedWorkflowPhaseConfig[] {
+  const out: LoadedWorkflowPhaseConfig[] = [];
+  for (const binding of enumerateBiomesWithContent(scanRoots, 'workflowConfig')) {
+    const path = join(binding.contentDir, PHASE_CONFIG_FILENAME);
+    if (!existsSync(path)) {
+      continue;
+    }
+    let raw: unknown;
+    try {
+      raw = JSON.parse(readFileSync(path, 'utf-8'));
+    } catch (err) {
+      throw new Error(
+        `Biome "${binding.biomeId}" ships a malformed ${PHASE_CONFIG_FILENAME}: ${
+          (err as Error).message
+        }`,
+      );
+    }
+    const config = parseContribution(WorkflowPhaseConfigSchema, raw, path);
+    out.push({ biomeId: binding.biomeId, config });
+  }
+  return out;
+}
+
+/**
+ * Load and merge every biome's phase-config into a single runtime view.
+ * Throws on a phase-key collision across biomes — phase keys flow onto
+ * the artifact natural key and must be globally unique.
+ */
+export function loadMergedWorkflowPhaseConfig(
+  scanRoots: readonly string[],
+): MergedWorkflowPhaseConfig {
+  const loaded = loadWorkflowPhaseConfigs(scanRoots);
+
+  const orderedPhaseKeys: string[] = [];
+  const phaseCategory = new Map<string, 'lifecycle' | 'delivery'>();
+  const directAgentPhases: string[] = [];
+  const subPhaseToParent = new Map<string, string>();
+  const reviewCapabilities = new Map<string, readonly string[]>();
+  const phaseOwner = new Map<string, string>();
+
+  for (const { biomeId, config } of loaded) {
+    for (const phase of config.phases) {
+      const existingOwner = phaseOwner.get(phase.key);
+      if (existingOwner !== undefined) {
+        throw new Error(
+          `Workflow phase key "${phase.key}" is declared by both biome ` +
+            `"${existingOwner}" and biome "${biomeId}". Phase keys must be ` +
+            `globally unique — they flow onto the artifact natural key.`,
+        );
+      }
+      phaseOwner.set(phase.key, biomeId);
+      orderedPhaseKeys.push(phase.key);
+      phaseCategory.set(phase.key, phase.category);
+    }
+    for (const direct of config.directAgentPhases) {
+      directAgentPhases.push(direct);
+    }
+    for (const [slug, parent] of Object.entries(config.subPhaseToParent)) {
+      subPhaseToParent.set(slug, parent);
+    }
+    for (const [key, caps] of Object.entries(config.reviewCapabilities)) {
+      reviewCapabilities.set(key, caps);
+    }
+  }
+
+  const allConfigurablePhases = [...orderedPhaseKeys, ...directAgentPhases];
+  const allReviewCapabilities = [
+    ...new Set([...reviewCapabilities.values()].flat()),
+  ];
+
+  return {
+    orderedPhaseKeys,
+    phaseCategory,
+    directAgentPhases,
+    allConfigurablePhases,
+    subPhaseToParent,
+    reviewCapabilities,
+    allReviewCapabilities,
+  };
+}
+
+/**
+ * Resolve a coordinator/sub-phase agent slug to its parent phase key.
+ * Returns the slug unchanged when it is itself a base phase or unknown —
+ * the same fall-through contract the kernel `resolveParentPhaseKey` had.
+ */
+export function resolveParentPhaseKey(
+  merged: MergedWorkflowPhaseConfig,
+  agentSlug: string,
+): string {
+  return merged.subPhaseToParent.get(agentSlug) ?? agentSlug;
+}

package/src/host/index.ts

@@ -0,0 +1,39 @@
+export * from './lib/biome-manifest';
+export * from './lib/topology';
+export * from './lib/default-state';
+export * from './lib/system-overlay-contribution';
+export * from './lib/integration-cross-validate';
+export * from './lib/agents-cross-validate';
+export * from './lib/bootstrap-contributions-service';
+
+// Kernel-owned XSI types re-exported under the SDK namespace so
+// consumers can write `import { ContributionKind, CapabilityRef,
+// BiomePermissionsManifest, BiomeLifecycleHooks, BiomeEngines } from
+// '@xemahq/biome-host-sdk'`. Kernel-owned; do not redefine here — the
+// authoritative shapes live in `@xemahq/kernel-contracts/contribution`,
+// `@xemahq/kernel-contracts/capability`, and `@xemahq/kernel-contracts/biome`.
+export {
+  ContributionKind,
+  ContributionKindSchema,
+  type ContributionKindValue,
+  ContributionSource,
+  ContributionSourceSchema,
+  type ContributionSourceValue,
+  type Contribution,
+  type ContributionIngestContext,
+  type ContributionKindHandler,
+  AnyContributionEnvelopeSchema,
+  ContributionSlugSchema,
+} from '@xemahq/kernel-contracts/contribution';
+export {
+  type CapabilityRef,
+  CapabilityRefSchema,
+} from '@xemahq/kernel-contracts/capability';
+export {
+  type BiomeEngines,
+  BiomeEnginesSchema,
+  type BiomeLifecycleHooks,
+  BiomeLifecycleHooksSchema,
+  type BiomePermissionsManifest,
+  BiomePermissionsManifestSchema,
+} from '@xemahq/kernel-contracts/biome';

package/src/host/lib/agents-cross-validate.ts

@@ -0,0 +1,283 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Agent declarations cross-validator ──
+//
+// Cross-checks a biome's `xema.agents[]` declaration against the on-disk
+// `agents/*.md` files at boot. Sibling of `crossValidateIntegrationContract`
+// — same shape (fail-fast, collect every issue, throw with the full list).
+//
+// Why this exists: prior to the explicit `agents[]` field, the on-disk
+// `agents/` directory scan was the only source of truth for "what agents
+// does this biome ship?". A file added without seeder awareness silently
+// appeared; a deleted file silently disappeared. The manifest declaration
+// makes the roster authoritative and greppable; this validator enforces
+// parity between declaration and disk.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type {
+  BiomeAgentMode,
+  ServerBiomeManifest,
+} from './biome-manifest';
+
+/**
+ * Convention: agent files live at `<biomeRoot>/agents/<slug>.md`.
+ * Kept standalone here so the validator has no circular import back into
+ * the schema module.
+ */
+const AGENTS_DIR_NAME = 'agents';
+
+export class AgentDeclarationCrossValidationError extends Error {
+  readonly issues: readonly string[];
+  constructor(biomeId: string, issues: readonly string[]) {
+    super(
+      `biome "${biomeId}": agent-declaration cross-validation failed:\n  - ${issues.join('\n  - ')}`,
+    );
+    this.name = 'AgentDeclarationCrossValidationError';
+    this.issues = issues;
+  }
+}
+
+/**
+ * Fail-fast invariants:
+ *
+ *  1. Every declared `agents[].slug` MUST have a matching
+ *     `<biomeRoot>/agents/<slug>.md` file on disk.
+ *  2. Every on-disk `agents/*.md` file MUST appear in `agents[]`.
+ *  3. Every declared `agents[].mode` MUST agree with the file's YAML
+ *     frontmatter `mode:` field. A missing frontmatter mode is accepted
+ *     only when the declaration says `primary` (matches the legacy
+ *     seeder default; explicit beats implicit going forward).
+ *  4. If the biome does NOT ship the `agents` content kind, neither
+ *     the declaration nor the directory may exist. (The schema
+ *     `superRefine` already enforces declaration parity; this catches
+ *     orphan directories left over from refactors.)
+ *
+ * The function returns nothing on success and throws
+ * `AgentDeclarationCrossValidationError` with the full issue list on
+ * failure. Boot continues no further when this throws.
+ */
+export function crossValidateAgentDeclarations(
+  manifest: ServerBiomeManifest,
+  biomeRoot: string,
+): void {
+  const issues: string[] = [];
+  const shipsAgents = manifest.xema.ships?.content?.includes('agents') ?? false;
+  const declared = manifest.xema.agents ?? [];
+  const agentsDir = join(biomeRoot, AGENTS_DIR_NAME);
+  const dirExists = existsSync(agentsDir);
+
+  if (!shipsAgents) {
+    if (dirExists) {
+      issues.push(
+        `agents/ directory exists at ${agentsDir} but the manifest does not ship the "agents" content kind — remove the directory or add "agents" to ships.content`,
+      );
+    }
+    if (issues.length > 0) {
+      throw new AgentDeclarationCrossValidationError(manifest.xema.id, issues);
+    }
+    return;
+  }
+
+  if (!dirExists) {
+    throw new AgentDeclarationCrossValidationError(manifest.xema.id, [
+      `ships.content includes "agents" but ${agentsDir} does not exist — create the directory and add at least one agents/<slug>.md file`,
+    ]);
+  }
+
+  const onDiskSlugs = new Set<string>();
+  for (const entry of readdirSync(agentsDir)) {
+    if (entry.startsWith('.')) continue;
+    if (!entry.endsWith('.md')) continue;
+    const abs = join(agentsDir, entry);
+    try {
+      if (!statSync(abs).isFile()) continue;
+    } catch {
+      continue;
+    }
+    onDiskSlugs.add(entry.slice(0, -'.md'.length));
+  }
+
+  const declaredBySlug = new Map<string, BiomeAgentMode>();
+  for (const decl of declared) {
+    declaredBySlug.set(decl.slug, decl.mode);
+  }
+
+  // (1) Every declared slug must exist on disk.
+  for (const decl of declared) {
+    if (!onDiskSlugs.has(decl.slug)) {
+      issues.push(
+        `declared agents[].slug="${decl.slug}" has no matching file at ${join(agentsDir, decl.slug + '.md')}`,
+      );
+    }
+  }
+
+  // (2) Every on-disk file must be declared.
+  for (const slug of onDiskSlugs) {
+    if (!declaredBySlug.has(slug)) {
+      issues.push(
+        `agents/${slug}.md exists on disk but is not declared under agents[] — add { slug: "${slug}", mode: "primary" | "subagent" }`,
+      );
+    }
+  }
+
+  // (3) Mode parity for files that are both declared AND on-disk.
+  for (const decl of declared) {
+    if (!onDiskSlugs.has(decl.slug)) continue;
+    const filePath = join(agentsDir, decl.slug + '.md');
+    let frontmatter: ParsedFrontmatter;
+    try {
+      frontmatter = readFrontmatter(filePath);
+    } catch (err) {
+      issues.push(
+        `failed to read ${filePath}: ${(err as Error).message}`,
+      );
+      continue;
+    }
+    if (frontmatter.mode === null) {
+      // Legacy convention: missing frontmatter mode = primary.
+      if (decl.mode !== 'primary') {
+        issues.push(
+          `agents/${decl.slug}.md frontmatter has no "mode:" field (treated as primary by the seeder) but the manifest declares mode="${decl.mode}" — add "mode: ${decl.mode}" to the frontmatter or change the declaration to "primary"`,
+        );
+      }
+    } else if (frontmatter.mode !== decl.mode) {
+      issues.push(
+        `agents/${decl.slug}.md frontmatter mode="${frontmatter.mode}" does not match manifest declaration mode="${decl.mode}"`,
+      );
+    }
+
+    // (5) Description quality: opencode's `task` tool re-uses this
+    //     verbatim as the "when to use" surface (`registry.ts:260-273`).
+    //     Sub-agent descriptions ARE the routing prompt — primaries get
+    //     stricter scrutiny too because the same string lands in agent
+    //     pickers and audit dashboards. See Phase H of
+    //     `.claude/plans/runtime-loading-consolidation.md`.
+    const descriptionIssue = validateAgentDescription(
+      decl.slug,
+      frontmatter.description,
+    );
+    if (descriptionIssue) {
+      issues.push(descriptionIssue);
+    }
+  }
+
+  if (issues.length > 0) {
+    throw new AgentDeclarationCrossValidationError(manifest.xema.id, issues);
+  }
+}
+
+/**
+ * Quality bar for the frontmatter `description:` field.
+ *
+ * Why these rules: opencode's `task` tool description is composed by
+ * iterating every sub-agent's `description:` and printing
+ * `"- <slug>: <description>"`. The primary's prompt routes via that
+ * surface — a weak description tells the planner literally nothing
+ * about when to delegate. The "Agent that…" boilerplate that ChatGPT
+ * tends to default to fails the bar twice (low information density,
+ * everyone's agents end up sounding identical).
+ *
+ *  - Minimum 40 chars (typical strong description is 60-200).
+ *  - No leading "Agent that…", "An agent…", "This agent…", "Agent for…".
+ */
+const DESCRIPTION_MIN_LENGTH = 40;
+const BANNED_DESCRIPTION_OPENERS = [
+  /^\s*agent\s+(that|for|which|to)\b/i,
+  /^\s*an\s+agent\b/i,
+  /^\s*this\s+agent\b/i,
+];
+
+function validateAgentDescription(
+  slug: string,
+  description: string | null,
+): string | null {
+  if (description === null) {
+    return (
+      `agents/${slug}.md frontmatter is missing a "description:" field — ` +
+      `opencode's task tool uses this as the "when to use" surface for ` +
+      `delegate routing; an empty value silently breaks delegation`
+    );
+  }
+  const trimmed = description.trim();
+  if (trimmed.length < DESCRIPTION_MIN_LENGTH) {
+    return (
+      `agents/${slug}.md description is too short (${trimmed.length} chars, ` +
+      `min ${DESCRIPTION_MIN_LENGTH}) — describe the situation a primary ` +
+      `agent should delegate to this agent in, not just a label`
+    );
+  }
+  for (const banned of BANNED_DESCRIPTION_OPENERS) {
+    if (banned.test(trimmed)) {
+      return (
+        `agents/${slug}.md description starts with boilerplate matching ${banned} ` +
+        `— skip the "Agent that…" preamble and lead with the situation/output`
+      );
+    }
+  }
+  return null;
+}
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
+const MODE_LINE_RE = /^\s*mode\s*:\s*(\S+)\s*$/m;
+const DESCRIPTION_LINE_RE = /^\s*description\s*:\s*(.+?)\s*$/m;
+
+interface ParsedFrontmatter {
+  readonly mode: BiomeAgentMode | null;
+  readonly description: string | null;
+}
+
+/**
+ * Extract the fields we care about from an agent .md file's YAML
+ * frontmatter. Returns:
+ *   - `mode`: `'primary' | 'subagent'`, or `null` when the line is
+ *     absent (handled by the legacy default in the caller).
+ *   - `description`: the raw value of `description:` (single-line) or
+ *     `null` when the line is absent. Block-scalar descriptions (`>`
+ *     or `|`) are not supported by this minimal parser; agents that
+ *     want multi-line copy in `description:` would surface as `null`
+ *     here and fail the description quality gate, which is the
+ *     intended push to keep delegate-routing copy single-line.
+ *
+ * Throws on a frontmatter-less file or an unrecognised mode value.
+ *
+ * Deliberately a minimal regex parser instead of pulling in `js-yaml` —
+ * this file is a kernel-tier validator and we want zero runtime deps
+ * beyond `node:fs`/`node:path`. The frontmatter format is constrained
+ * enough that the regex is unambiguous.
+ */
+function readFrontmatter(filePath: string): ParsedFrontmatter {
+  const raw = readFileSync(filePath, 'utf8');
+  const match = FRONTMATTER_RE.exec(raw);
+  if (!match) {
+    throw new Error('missing YAML frontmatter (every agent .md must have one)');
+  }
+  const fm = match[1] ?? '';
+  return {
+    mode: parseFrontmatterMode(fm),
+    description: parseFrontmatterDescription(fm),
+  };
+}
+
+function parseFrontmatterMode(fm: string): BiomeAgentMode | null {
+  const modeMatch = MODE_LINE_RE.exec(fm);
+  if (!modeMatch) return null;
+  const value = modeMatch[1];
+  if (value === 'primary' || value === 'subagent') return value;
+  throw new Error(`frontmatter mode="${value}" is not a valid BiomeAgentMode (expected "primary" | "subagent")`);
+}
+
+function parseFrontmatterDescription(fm: string): string | null {
+  const m = DESCRIPTION_LINE_RE.exec(fm);
+  if (!m) return null;
+  // Strip surrounding quotes ("…" or '…') the YAML author may have
+  // added — `description: "…"` is common and our quality gate counts
+  // chars after the strip.
+  const raw = m[1] ?? '';
+  const quote = raw[0];
+  if (raw.length >= 2 && (quote === '"' || quote === "'") && raw.endsWith(quote)) {
+    return raw.slice(1, -1);
+  }
+  return raw;
+}