session-orchestrator 3.20.0 → 3.22.0

package/scripts/lib/state-md/mission-status.mjs

@@ -16,6 +16,40 @@
 import { parseStateMd, serializeStateMd } from './yaml-parser.mjs';
 import { updateFrontmatterFields, writeStateMd } from './frontmatter-mutators.mjs';
 
+const MISSION_STATUS_HEADING_RE = /^##\s+Mission Status\s*$/;
+const WRITER_TIMESTAMP_SOURCE = '\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z';
+const WRITER_TIMESTAMP_RE = new RegExp(`^${WRITER_TIMESTAMP_SOURCE}$`);
+const CANONICAL_MISSION_STATUS_ENTRY_RE = new RegExp(
+  `^- ([a-z][a-z0-9]*(?:-[a-z0-9]+)*-\\d+): (.*) \\(updated (${WRITER_TIMESTAMP_SOURCE})\\)$`
+);
+
+/**
+ * Finds the first exact `## Mission Status` section and its closing heading.
+ *
+ * @param {string[]} lines
+ * @returns {{ headingIdx: number, sectionEnd: number }|null}
+ */
+function findMissionStatusSection(lines) {
+  if (!Array.isArray(lines)) return null;
+  const headingIdx = lines.findIndex((line) => MISSION_STATUS_HEADING_RE.test(line));
+  if (headingIdx === -1) return null;
+
+  let sectionEnd = lines.length;
+  for (let i = headingIdx + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) {
+      sectionEnd = i;
+      break;
+    }
+  }
+  return { headingIdx, sectionEnd };
+}
+
+function isWriterTimestamp(timestamp) {
+  if (!WRITER_TIMESTAMP_RE.test(timestamp)) return false;
+  const parsed = new Date(timestamp);
+  return !Number.isNaN(parsed.getTime()) && parsed.toISOString() === timestamp;
+}
+
 /**
  * Parses the optional `mission-status:` block from a STATE.md frontmatter object
  * (as returned by `parseStateMd(...).frontmatter`).
@@ -24,8 +58,9 @@ import { updateFrontmatterFields, writeStateMd } from './frontmatter-mutators.mj
  * STATE.md files). Returns `[]` when the key is present but the value is an empty
  * array. Returns the array of entries when present and non-empty.
  *
- * Does NOT validate individual entry shapes — callers that need schema validation
- * should use `validateMissionStatusEntry` from mission-status-schema.mjs.
+ * Does NOT validate individual entry shapes, and no helper in this repo does:
+ * entry shape and the `status` enum are coordinator convention, deliberately not a
+ * mechanical gate (see `syncFrontmatterMissionStatus` below for why).
  *
  * @param {object} frontmatter
  * @returns {object[]|null}
@@ -55,9 +90,9 @@ export function parseMissionStatus(frontmatter) {
  * - Works on string input (pure — no file I/O). Returns the updated STATE.md contents.
  * - No-ops if `contents` has no parseable frontmatter (returns input unchanged).
  *
- * Individual entry objects must conform to the shape validated by
- * `validateMissionStatusEntry` in mission-status-schema.mjs, but this function does
- * NOT enforce that constraint — callers are responsible for pre-validation.
+ * Individual entry objects are expected to carry `{ id, task, wave, status }`, but
+ * this function does NOT enforce that shape and no validator in this repo does —
+ * callers own the invariant.
  *
  * @param {string} contents
  * @param {object[]|null|undefined} missionStatusArray
@@ -82,19 +117,31 @@ export function writeMissionStatus(contents, missionStatusArray) {
  * entry level — the input is never mutated, which keeps `parseMissionStatus`'s
  * shallow-copy contract intact for anything else holding the same nested entries).
  *
- * UPDATE-ONLY by design: when the key is absent, is not an array, or holds no entry
- * with a matching `id`, the frontmatter is returned unchanged. It is deliberately
- * neither created nor an error, because `setMissionStatus(contents, taskId, status)`
- * knows only `id` and `status` — it lacks the `task` and `wave` fields that
- * `validateMissionStatusEntry` (mission-status-schema.mjs) requires, so a synthesised
- * entry would be schema-invalid yet look authoritative to frontmatter consumers such
- * as `vault-status/narrative-mirror.mjs`. Throwing is likewise excluded by the
- * never-throw contract of `setMissionStatus`.
+ * UPDATE-ONLY by design: when the key is absent, is not an array, or holds no
+ * matching entry in a populated array, the frontmatter is returned unchanged. It is
+ * deliberately neither created nor an error, because `setMissionStatus(contents,
+ * taskId, status)` knows only `id` and `status` — it lacks the `task` and `wave`
+ * fields a full entry carries, so a synthesised entry would be shape-invalid yet look
+ * authoritative to frontmatter consumers such as `vault-status/narrative-mirror.mjs`.
+ * Throwing is likewise excluded by the never-throw contract of `setMissionStatus`.
+ *
+ * An empty array is recovered from the final body by
+ * `recoverFrontmatterMissionStatus`, which persists only the truthful `id` and
+ * `status` values available there. It does not fabricate absent metadata.
  *
  * `status` is mirrored verbatim without an enum check on purpose: gating it would
  * reintroduce the exact divergence (body says X, frontmatter says Y) this sync exists
- * to remove. An out-of-enum value now lands on BOTH surfaces, where the repo's own
- * validator can see it.
+ * to remove. An out-of-enum value therefore lands visibly on BOTH surfaces rather than
+ * being silently rejected on one.
+ *
+ * There is deliberately NO transition validator behind this. A `mission-status-schema.mjs`
+ * once existed (#340) offering `isValidMissionStatusTransition`; it was never wired and
+ * was removed, because the only guard form it enabled — read the current status, reject a
+ * disallowed transition — would reject legitimate live writes. Measured against a copy of
+ * this repo's own STATE.md carrying 24 items: 12 had no body entry yet (current status
+ * reads `null`, so every transition out of them is "invalid"), and the routine
+ * `in-dev` → `completed` write is not in the strict forward chain either — 18 of 24
+ * writes would have been refused. The enum is a vocabulary, not a state machine.
  *
  * @param {object} frontmatter
  * @param {string} taskId
@@ -116,6 +163,80 @@ function syncFrontmatterMissionStatus(frontmatter, taskId, status) {
   return { ...frontmatter, 'mission-status': entries };
 }
 
+/**
+ * Mirrors body-only task IDs into the frontmatter `mission-status` registry as
+ * partial `{ id, status }` entries. This is a SUPERSET merge: existing entries are
+ * never rewritten or reordered, so their full metadata (`task`, `wave`) survives —
+ * only IDs absent from the registry are appended.
+ *
+ * It must not be gated on an EMPTY registry. Recovering only from empty froze the
+ * registry after its first recovery: the sync path (`syncFrontmatterMissionStatus`)
+ * is update-only, so every subsequently added task ID was never mirrored again, and
+ * Phase 1.9/1.10 read a plausible undercount instead of the obvious zero. That is
+ * #1084 one write later — measured m-1/m-2/m-3 in the body against `[m-1]` in the
+ * frontmatter.
+ *
+ * The section parse stays strict and all-or-nothing: any nonblank line that is not a
+ * unique canonical writer bullet (unsafe ID, pipe, malformed timestamp, duplicate,
+ * prose) aborts the whole merge rather than fabricating entries from an ambiguous
+ * body. Known limitation: one foreign-but-writer-accepted ID (e.g. `Docs_2`) or a
+ * hand-written legacy bullet without a timestamp therefore suppresses the merge for
+ * the whole file, silently.
+ *
+ * @param {object} frontmatter
+ * @param {string} body
+ * @returns {object}
+ */
+function recoverFrontmatterMissionStatus(frontmatter, body) {
+  if (frontmatter === null || typeof frontmatter !== 'object' || Array.isArray(frontmatter)) {
+    return frontmatter;
+  }
+  const raw = frontmatter['mission-status'];
+  if (!Array.isArray(raw) || typeof body !== 'string') return frontmatter;
+
+  const lines = body.split('\n');
+  const section = findMissionStatusSection(lines);
+  if (section === null) return frontmatter;
+
+  const entries = [];
+  const ids = new Set();
+  for (let i = section.headingIdx + 1; i < section.sectionEnd; i++) {
+    const line = lines[i];
+    if (line.trim() === '') continue;
+
+    const match = CANONICAL_MISSION_STATUS_ENTRY_RE.exec(line);
+    if (match === null) return frontmatter;
+    const [, id, status, timestamp] = match;
+    if (
+      status.length === 0 ||
+      status.includes('|') ||
+      status.includes('\n') ||
+      !isWriterTimestamp(timestamp) ||
+      ids.has(id)
+    ) {
+      return frontmatter;
+    }
+    ids.add(id);
+    entries.push({ id, status });
+  }
+
+  const known = new Set(
+    raw
+      .filter((e) => e !== null && typeof e === 'object' && !Array.isArray(e))
+      .map((e) => e.id)
+  );
+  const added = entries.filter((e) => !known.has(e.id));
+  if (added.length === 0) return frontmatter;
+  return { ...frontmatter, 'mission-status': [...raw, ...added] };
+}
+
+function serializeMissionStatusUpdate(frontmatter, body) {
+  return serializeStateMd({
+    frontmatter: recoverFrontmatterMissionStatus(frontmatter, body),
+    body,
+  });
+}
+
 /**
  * Sets (or updates) the mission status for a single task in the `## Mission Status` body
  * section of STATE.md. Creates the section if it does not exist.
@@ -128,7 +249,10 @@ function syncFrontmatterMissionStatus(frontmatter, taskId, status) {
  * during a wave; the frontmatter array is what `parseMissionStatus` consumers read
  * (`vault-status/narrative-mirror.mjs`, session-end Phase 1.9/1.10). Before this sync the
  * live writer and the reader sat on different surfaces and drifted apart in both
- * directions. Frontmatter mirroring is UPDATE-ONLY — see `syncFrontmatterMissionStatus`.
+ * directions. A legacy empty registry is recovered from canonical body bullets as
+ * partial `{ id, status }` entries, which lets frontmatter readers classify the work
+ * without fabricated metadata. Ambiguous legacy bodies remain empty; other unmatched
+ * populated entries remain update-only. See `syncFrontmatterMissionStatus`.
  *
  * Pure function — no I/O. Returns original `contents` unchanged on bad input.
  *
@@ -151,31 +275,16 @@ export function setMissionStatus(contents, taskId, status) {
   const bullet = `- ${taskId}: ${status} (updated ${timestamp})`;
   const lines = parsed.body.split('\n');
 
-  // Find existing ## Mission Status section
-  let headingIdx = -1;
-  for (let i = 0; i < lines.length; i++) {
-    if (/^##\s+Mission Status\b/.test(lines[i])) {
-      headingIdx = i;
-      break;
-    }
-  }
-
-  if (headingIdx === -1) {
+  const section = findMissionStatusSection(lines);
+  if (section === null) {
     // Section does not exist — append it at the end
     let bodyOut = parsed.body;
     if (!bodyOut.endsWith('\n')) bodyOut += '\n';
     bodyOut += `\n## Mission Status\n\n${bullet}\n`;
-    return serializeStateMd({ frontmatter, body: bodyOut });
+    return serializeMissionStatusUpdate(frontmatter, bodyOut);
   }
 
-  // Find end of section: next ## heading or end of lines
-  let sectionEnd = lines.length;
-  for (let i = headingIdx + 1; i < lines.length; i++) {
-    if (/^##\s+/.test(lines[i])) {
-      sectionEnd = i;
-      break;
-    }
-  }
+  const { headingIdx, sectionEnd } = section;
 
   // Look for an existing entry with this taskId within the section
   const entryRe = new RegExp(`^-\\s+${taskId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}:`);
@@ -205,18 +314,20 @@ export function setMissionStatus(contents, taskId, status) {
       const before = lines.slice(0, headingIdx + 1);
       const after = lines.slice(insertAt);
       const rebuilt = [...before, '', bullet, ...after];
-      return serializeStateMd({ frontmatter, body: rebuilt.join('\n') });
+      return serializeMissionStatusUpdate(frontmatter, rebuilt.join('\n'));
     }
   }
 
-  return serializeStateMd({ frontmatter, body: lines.join('\n') });
+  return serializeMissionStatusUpdate(frontmatter, lines.join('\n'));
 }
 
 /**
  * Reads the current mission status for a single task from the `## Mission Status` body
  * section of STATE.md.
  *
- * Returns the status string (e.g. `'in-dev'`) or `null` if the task is not found or the
+ * Returns the full status string before a current-writer timestamp (e.g. `'in-dev'`
+ * or `'needs manual testing'`). For legacy body lines that lack that exact form, falls
+ * back to the first status token. Returns `null` if the task is not found or the
  * section does not exist. Never throws — returns `null` on any bad input.
  *
  * @param {string} contents - Current STATE.md file contents (string)
@@ -230,29 +341,24 @@ export function readMissionStatus(contents, taskId) {
   if (parsed === null) return null;
 
   const lines = parsed.body.split('\n');
-  let headingIdx = -1;
-  for (let i = 0; i < lines.length; i++) {
-    if (/^##\s+Mission Status\b/.test(lines[i])) {
-      headingIdx = i;
-      break;
-    }
-  }
-  if (headingIdx === -1) return null;
+  const section = findMissionStatusSection(lines);
+  if (section === null) return null;
 
-  let sectionEnd = lines.length;
-  for (let i = headingIdx + 1; i < lines.length; i++) {
-    if (/^##\s+/.test(lines[i])) {
-      sectionEnd = i;
-      break;
-    }
+  // Prefer the full current-writer status, including internal spaces.
+  const escapedId = taskId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const writerEntryRe = new RegExp(
+    `^- ${escapedId}: (.*) \\(updated ${WRITER_TIMESTAMP_SOURCE}\\)$`
+  );
+  for (let i = section.headingIdx + 1; i < section.sectionEnd; i++) {
+    const match = writerEntryRe.exec(lines[i]);
+    if (match) return match[1];
   }
 
-  // Match: - <taskId>: <status> (updated ...)
-  const escapedId = taskId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const entryRe = new RegExp(`^-\\s+${escapedId}:\\s+(\\S+)`);
-  for (let i = headingIdx + 1; i < sectionEnd; i++) {
-    const m = entryRe.exec(lines[i]);
-    if (m) return m[1];
+  // Reader-only legacy compatibility. Recovery remains canonical and all-or-nothing.
+  const legacyEntryRe = new RegExp(`^-\\s+${escapedId}:\\s+(\\S+)`);
+  for (let i = section.headingIdx + 1; i < section.sectionEnd; i++) {
+    const match = legacyEntryRe.exec(lines[i]);
+    if (match) return match[1];
   }
   return null;
 }

package/scripts/lib/tmux-layout/vcs-detector.mjs

@@ -6,20 +6,116 @@
  * so all commands are wrapped in a `while true; sleep` loop per D5 findings.
  *
  * Issue #561 — ADR-0007 tmux-visualization substrate.
+ *
+ * ## The probed pane commands — SSOT for the lockstep test
+ *
+ * The two lines below are the argv this module emits, with the resolved repo
+ * spec written as `<spec>` and the `2>&1` redirect dropped. They are not a
+ * description of the commands: `tests/lib/tmux-layout/vcs-detector.test.mjs`
+ * reconstructs the same normalisation from `detectVcsCommand()` and asserts
+ * equality, so a flag added to the emitted command without a matching probe
+ * here turns that test RED. See § Why a probe line, not prose.
+ *
+ *   PROBE 2026-08-14 glab 1.91.0: glab ci status -R <spec> --output json
+ *   PROBE 2026-08-14 gh 2.86.0: gh pr checks --watch
+ *
+ * ## Why `glab ci status` carries no pipeline selector (#1022)
+ *
+ * The glab pane emitted `--pipeline-id LATEST` until 2026-08-14. That flag does
+ * not exist on any `glab ci` subcommand, and `glab ci status --help` (1.91.0)
+ * lists only `-b --branch`, `-c --compact`, `-l --live`, `-F --output`,
+ * `-R --repo`. Probed from a non-git cwd against this repo's own remote:
+ *
+ *   with the flag → `ERROR Unknown flag: --pipeline-id.`, exit 1
+ *   without it    → exit 0, `{"jobs":[…],"pipeline":{…}}`
+ *
+ * So the flag was the sole cause and it has NO replacement: the argument-less
+ * form already means "the pipeline of the current branch" (glab's own help
+ * example). `--branch=<name>` is the only selector glab offers and is
+ * deliberately NOT used — it would freeze a render-time branch snapshot into a
+ * pane that must follow the operator's checkout, the same reason the gh pane
+ * takes no positional.
+ *
+ * The `jq` filter was dead by the same measurement and is fixed with it: the
+ * payload is an OBJECT keyed `jobs`/`pipeline`, so the old `.[]` raised
+ * `Cannot index array with string "name"` (jq exit 5) on every real response.
+ * `.jobs[]` returns one `<status> <name>` line per job. Because the whole
+ * pipeline is `… 2>&1 | jq … 2>/dev/null || echo …`, both failures were
+ * swallowed into the fallback text — the pane printed "glab not available or no
+ * pipeline" against a healthy pipeline, indistinguishable from a missing binary.
+ *
+ * ## Why only the glab pane carries `-R` (#971)
+ *
+ * The pane commands run in whatever cwd the operator pastes the one-liner into,
+ * so an omitted `-R`/`--repo` silently targets the ambient cwd remote. Both
+ * halves were probed against the installed binaries on 2026-08-14
+ * (glab 1.91.0 / gh 2.86.0) and they do NOT behave the same:
+ *
+ *  - `glab ci status -R <spec> --output json` from a NON-git cwd → exit 0 with
+ *    real pipeline JSON. The flag is applicable and makes the pane
+ *    cwd-independent, so it is passed whenever `resolveRepoSpec()` resolves one.
+ *  - `gh pr checks -R <spec>` with NO positional argument →
+ *    `argument required when using the --repo flag` (exit non-zero, no output).
+ *    gh selects "the PR of the current branch" ONLY in the argument-less form;
+ *    `-R` is legal there only alongside a `<number> | <url> | <branch>`
+ *    positional, which this pane deliberately does not have (the watched branch
+ *    must follow the operator's checkout, and a render-time branch snapshot
+ *    would go stale on the next `git switch`). Adding `-R` there would break the
+ *    pane at runtime — the exact defect shape recorded in
+ *    `scripts/lib/ci-status-banner.mjs` (`-R` on `gh repo view`, which rejects
+ *    it). The gh pane therefore stays cwd-scoped BY MEASUREMENT, not by
+ *    oversight.
+ *
+ * ## Why a probe line, not prose
+ *
+ * The #971 sweep added `-R` here and left `--pipeline-id` untouched, then wrote
+ * a header documenting a probe of `glab ci status -R <spec> --output json` —
+ * a command the pane never emitted. The measurement was real and cited for
+ * something it had not measured, so a dead flag rode through a green test.
+ * NAMED CEILING: the lockstep only proves that command and probe were changed
+ * together; it cannot prove the probe was re-executed. It buys the one step
+ * that was skipped — no flag change without touching the measurement record.
+ * Revisit if a pane ever needs a runtime-varying flag, which this shape cannot
+ * express.
+ */
+
+import { resolveRepoSpec } from '../vcs-repo-spec.mjs';
+
+/**
+ * Shell-safe spec shape. A git remote URL (`git@host:group/project.git`,
+ * `https://host/group/project.git`) and an `OWNER/REPO` spec are both fully
+ * inside this character class, so a matching value can be spliced into the pane
+ * command line without quoting. A value OUTSIDE it is DROPPED (the flag is
+ * omitted) rather than quoted — this mirrors `resolveRepoSpec`'s own contract
+ * that an unresolvable spec means "omit the flag entirely", never "emit a
+ * broken one", and keeps a hostile remote URL out of the pane's shell.
  */
+const SHELL_SAFE_SPEC_RE = /^[A-Za-z0-9._:/@+-]+$/;
 
 /**
  * Resolve the CI-watch pane command based on Session Config vcs: key.
  *
- * @param {{ config?: object, projectRoot: string }} args
+ * @param {{
+ *   config?: object,
+ *   projectRoot: string,
+ *   gitRun?: (args: string[]) => { ok: boolean, stdout: string, stderr: string }
+ * }} args
+ *   - gitRun: optional `resolveRepoSpec` seam, so callers/tests can pin the
+ *     resolved repo spec instead of spawning `git` against the real checkout.
  * @returns {{ bin: 'glab'|'gh'|null, command: string, fallback: string, blocking: boolean, platform: 'gitlab'|'github'|null }}
  *   - command: the shell command for Pane 3 (wrapped in poll-loop since glab/gh are poll-based, not live-tail)
  *   - fallback: shell command shown when bin is not available in PATH
  */
-export function detectVcsCommand({ config, projectRoot: _projectRoot }) {
+export function detectVcsCommand({ config, projectRoot, gitRun }) {
   const vcs = config?.vcs;   // 'gitlab' | 'github' | undefined
 
   if (vcs === 'gitlab') {
+    const spec = resolveRepoSpec({
+      repoRoot: projectRoot,
+      vcs: 'gitlab',
+      ...(typeof gitRun === 'function' ? { gitRun } : {}),
+    });
+    const repoFlag = spec && SHELL_SAFE_SPEC_RE.test(spec) ? ` -R ${spec}` : '';
     return {
       bin: 'glab',
       platform: 'gitlab',
@@ -29,8 +125,12 @@ export function detectVcsCommand({ config, projectRoot: _projectRoot }) {
         '  clear;',
         '  date;',
         "  echo '--- glab ci status (refresh: 15s) ---';",
-        '  glab ci status --pipeline-id LATEST --output json 2>&1',
-        "    | jq -r '.[] | \"\\(.status) \\(.name)\"' 2>/dev/null",
+        // No pipeline selector: `--pipeline-id` is not a glab flag (1.91.0
+        // rejects it outright) and the argument-less form already means "the
+        // current branch's pipeline". `.jobs[]`, not `.[]` — the payload is an
+        // object. Both measured 2026-08-14; see the module header.
+        `  glab ci status${repoFlag} --output json 2>&1`,
+        "    | jq -r '.jobs[] | \"\\(.status) \\(.name)\"' 2>/dev/null",
         "    || echo 'glab not available or no pipeline';",
         '  sleep 15;',
         'done',
@@ -55,6 +155,10 @@ export function detectVcsCommand({ config, projectRoot: _projectRoot }) {
         '  clear;',
         '  date;',
         "  echo '--- gh pr checks --watch (will exit on PR completion) ---';",
+        // No `-R` here BY MEASUREMENT, not by oversight: `gh pr checks -R <spec>`
+        // without a positional PR/branch argument is rejected outright
+        // ("argument required when using the `--repo` flag", gh 2.86.0), and this
+        // pane must follow the operator's current branch. See the module header.
         '  gh pr checks --watch 2>&1',
         "    || echo 'no PR in current branch';",
         '  sleep 15;',

package/scripts/lib/validate/check-agents.mjs

@@ -7,7 +7,9 @@
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import yaml from 'js-yaml';
 import { ALLOWED_MODEL_ALIASES, MODEL_ID_RE } from '../agent-frontmatter.mjs';
+import { extractInitialFrontmatter } from './frontmatter-block.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -57,10 +59,45 @@ function fail(msg) {
 /**
  * Extract YAML frontmatter content (between first --- and second ---).
  * Returns null if no valid frontmatter block found.
+ *
+ * Delegates to the shared extractor. This file carried a THIRD verbatim copy of
+ * that regex until now (check-skills.mjs and check-commands.mjs held the other
+ * two, which is why the extraction was lifted into frontmatter-block.mjs). Only
+ * the block-finding is shared — the field RULES stay per-gate and disagree on
+ * purpose; see the header of frontmatter-block.mjs.
+ *
+ * Checks 7-10 only need "text, or nothing"; Check 6 reads the shared
+ * diagnostic directly for a precise message.
  */
 function extractFrontmatter(content) {
-  const m = content.match(/^---\n([\s\S]*?)\n---/);
-  return m ? m[1] : null;
+  const extracted = extractInitialFrontmatter(content);
+  return extracted.ok ? extracted.yamlText : null;
+}
+
+/**
+ * Parse a frontmatter block with a real YAML parser (CORE_SCHEMA, matching
+ * check-commands.mjs and check-skills.mjs).
+ *
+ * @param {string} yamlText - the block's inner text, no fences
+ * @returns {{ ok: true, data: unknown } | { ok: false, message: string }}
+ *   On failure, `message` is a caller-printable reason with a frontmatter-local
+ *   line/column when js-yaml supplies one.
+ */
+function parseFrontmatterYaml(yamlText) {
+  let data;
+  try {
+    data = yaml.load(yamlText, { schema: yaml.CORE_SCHEMA });
+  } catch (error) {
+    const reason = error?.reason ?? error?.message ?? String(error);
+    const location = error?.mark
+      ? ` at frontmatter line ${error.mark.line + 1}, column ${error.mark.column + 1}`
+      : '';
+    return { ok: false, message: `invalid YAML frontmatter: ${reason}${location}` };
+  }
+  if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+    return { ok: false, message: 'YAML frontmatter must be a non-null mapping/object' };
+  }
+  return { ok: true, data };
 }
 
 /**
@@ -146,17 +183,48 @@ const mdFiles = readdirSync(agentsDir).filter(isAgentDefFile);
 if (mdFiles.length === 0) {
   fail('agents directory is empty (no .md files)');
 } else {
+  let parseable = 0;
+
   for (const agentFile of mdFiles) {
     const agentName = agentFile;
     const filePath = join(agentsDir, agentFile);
     const content = readFileSync(filePath, 'utf8');
 
-    const frontmatter = extractFrontmatter(content);
+    const extracted = extractInitialFrontmatter(content);
 
-    if (!frontmatter) {
-      fail(`${agentName}: missing YAML frontmatter`);
+    if (!extracted.ok) {
+      fail(`${agentName}: ${extracted.diagnostic}`);
       continue;
     }
+    const frontmatter = extracted.yamlText;
+
+    // ------------------------------------------------------------------
+    // The block is valid YAML.
+    //
+    // Every rule below reads the block with LINE REGEXES (getField/hasField),
+    // which model Claude Code's own lenient loader. That leniency is exactly
+    // how 14 of 16 agent definitions sat unparseable in the tree unnoticed: an
+    // unquoted single-line `description:` containing a `: ` (e.g.
+    // `<example>Context: /plan ...`) is not YAML, and a regex looking only for
+    // `^description:` sees nothing wrong. A ` #` inside such a value is worse
+    // still — it opens a YAML comment, so the block PARSES while silently
+    // truncating the description at that point.
+    //
+    // A parse failure is reported alone (no fall-through to the field rules):
+    // the block is broken at the root, and six regex verdicts stacked on top
+    // of it are cascade noise that buries the one defect worth fixing. Same
+    // posture as check-skills.mjs R8.
+    //
+    // ORTHOGONAL to the `description` block-scalar ban further down: this rule
+    // demands the block BE YAML; that one forbids one particular valid YAML
+    // form the agent loader cannot read. Neither implies the other.
+    // ------------------------------------------------------------------
+    const parsedFm = parseFrontmatterYaml(frontmatter);
+    if (!parsedFm.ok) {
+      fail(`${agentName}: ${parsedFm.message}`);
+      continue;
+    }
+    parseable++;
 
     // ------------------------------------------------------------------
     // Required fields check
@@ -236,6 +304,10 @@ if (mdFiles.length === 0) {
       }
     }
   }
+
+  if (parseable === mdFiles.length) {
+    pass(`all ${mdFiles.length} agent frontmatter blocks parse as YAML mappings`);
+  }
 }
 
 // ============================================================================