session-orchestrator 3.16.0

package/scripts/generate-pi-prompts.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * generate-pi-prompts.mjs — build Pi prompt-template wrappers for commands/*.md.
+ *
+ * Pi prompt templates expand `$@`; Session Orchestrator command files use the
+ * cross-harness `$ARGUMENTS` placeholder. The generated wrapper keeps one
+ * maintained command source while giving Pi a native prompt entry per command.
+ *
+ * Usage:
+ *   node scripts/generate-pi-prompts.mjs
+ *   node scripts/generate-pi-prompts.mjs --check
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const SCRIPT_DIR = path.dirname(__filename);
+const ROOT = path.dirname(SCRIPT_DIR);
+const COMMANDS_DIR = path.join(ROOT, 'commands');
+const PROMPTS_DIR = path.join(ROOT, 'pi', 'prompts');
+const CHECK_ONLY = process.argv.includes('--check');
+
+function commandFiles() {
+  return readdirSync(COMMANDS_DIR)
+    .filter((name) => name.endsWith('.md'))
+    .sort();
+}
+
+function parseFrontmatter(content) {
+  if (!content.startsWith('---\n')) return {};
+  const end = content.indexOf('\n---\n', 4);
+  if (end === -1) return {};
+
+  const fields = {};
+  const block = content.slice(4, end).split('\n');
+  for (const line of block) {
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!match) continue;
+    fields[match[1]] = match[2];
+  }
+  return fields;
+}
+
+function frontmatterLine(key, value) {
+  if (value === undefined || value === '') return null;
+  return `${key}: ${value}`;
+}
+
+function renderPrompt(commandFile) {
+  const commandPath = path.join(COMMANDS_DIR, commandFile);
+  const commandName = commandFile.replace(/\.md$/, '');
+  const fields = parseFrontmatter(readFileSync(commandPath, 'utf8'));
+  const frontmatter = [
+    '---',
+    frontmatterLine('description', fields.description),
+    frontmatterLine('argument-hint', fields['argument-hint']),
+    '---',
+  ].filter(Boolean).join('\n');
+
+  return `${frontmatter}
+
+# /${commandName}
+
+Use the Session Orchestrator command definition at \`commands/${commandFile}\`.
+
+Arguments: $@
+
+Read that command file and follow it exactly. When it references \`$ARGUMENTS\`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+`;
+}
+
+function expectedPrompts() {
+  const prompts = new Map();
+  for (const commandFile of commandFiles()) {
+    prompts.set(commandFile, renderPrompt(commandFile));
+  }
+  return prompts;
+}
+
+function checkPrompts(expected) {
+  const failures = [];
+  for (const [name, content] of expected) {
+    const promptPath = path.join(PROMPTS_DIR, name);
+    if (!existsSync(promptPath)) {
+      failures.push(`${name}: missing`);
+      continue;
+    }
+    const actual = readFileSync(promptPath, 'utf8');
+    if (actual !== content) failures.push(`${name}: stale`);
+  }
+
+  const expectedNames = new Set(expected.keys());
+  const actualNames = existsSync(PROMPTS_DIR)
+    ? readdirSync(PROMPTS_DIR).filter((name) => name.endsWith('.md'))
+    : [];
+  for (const name of actualNames) {
+    if (!expectedNames.has(name)) failures.push(`${name}: orphan`);
+  }
+
+  if (failures.length > 0) {
+    for (const failure of failures) {
+      console.error(`FAIL: ${failure}`);
+    }
+    process.exit(1);
+  }
+
+  console.log(`pi prompts: ${expected.size} file(s) up to date`);
+}
+
+function writePrompts(expected) {
+  mkdirSync(PROMPTS_DIR, { recursive: true });
+  for (const name of readdirSync(PROMPTS_DIR)) {
+    if (name.endsWith('.md') && !expected.has(name)) {
+      rmSync(path.join(PROMPTS_DIR, name));
+    }
+  }
+  for (const [name, content] of expected) {
+    writeFileSync(path.join(PROMPTS_DIR, name), content, 'utf8');
+  }
+  console.log(`pi prompts: wrote ${expected.size} file(s)`);
+}
+
+const expected = expectedPrompts();
+if (CHECK_ONLY) checkPrompts(expected);
+else writePrompts(expected);

package/scripts/harness-audit.mjs

@@ -0,0 +1,287 @@
+#!/usr/bin/env node
+/**
+ * harness-audit.mjs — Deterministic harness-audit scorecard script.
+ *
+ * Runs 36 checks across 9 categories against a target repo. Emits a single
+ * JSON record to stdout (schema defined in issue #210) and appends the same
+ * record (with session_id) to .orchestrator/metrics/audit.jsonl.
+ * Writes a human-readable summary to stderr.
+ * Always exits 0 — audit never blocks.
+ *
+ * Usage: node scripts/harness-audit.mjs
+ *
+ * Stdlib only: node:fs, node:path, node:child_process, node:url.
+ * Rubric version: 2026-06
+ */
+
+import { existsSync, readFileSync, mkdirSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+import {
+  runCategory1,
+  runCategory2,
+  runCategory3,
+  runCategory4,
+  runCategory5,
+  runCategory6,
+  runCategory7,
+  runCategory8,
+  runCategory9,
+} from './lib/harness-audit/categories.mjs';
+
+const RUBRIC_VERSION = '2026-06';
+
+// ---------------------------------------------------------------------------
+// Audit root resolution
+// ---------------------------------------------------------------------------
+
+function resolveAuditRoot() {
+  const cwd = process.cwd();
+  if (existsSync(join(cwd, '.git')) || existsSync(join(cwd, 'CLAUDE.md')) || existsSync(join(cwd, 'AGENTS.md'))) {
+    return cwd;
+  }
+  try {
+    const result = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      timeout: 5000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      encoding: 'utf8',
+    });
+    const top = result.trim();
+    if (top) return top;
+  } catch { /* fall through */ }
+  return cwd;
+}
+
+// ---------------------------------------------------------------------------
+// Git metadata
+// ---------------------------------------------------------------------------
+
+function getGitMeta(root) {
+  let branch = null;
+  let headSha = null;
+  try {
+    branch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      cwd: root, timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf8',
+    }).trim();
+  } catch { /* ignore */ }
+  try {
+    headSha = execFileSync('git', ['rev-parse', '--short', 'HEAD'], {
+      cwd: root, timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf8',
+    }).trim();
+  } catch { /* ignore */ }
+  return { branch: branch || null, head_sha: headSha || null };
+}
+
+// ---------------------------------------------------------------------------
+// Package version
+// ---------------------------------------------------------------------------
+
+function getHarnessVersion(root) {
+  try {
+    const text = readFileSync(join(root, 'package.json'), 'utf8');
+    const pkg = JSON.parse(text);
+    return typeof pkg.version === 'string' ? pkg.version : null;
+  } catch { return null; }
+}
+
+// ---------------------------------------------------------------------------
+// Session ID derivation
+// ---------------------------------------------------------------------------
+
+function getSessionId(root, branch) {
+  const now = new Date();
+  const utcDate = now.toISOString().slice(0, 10); // YYYY-MM-DD
+  const utcHHmm = now.toISOString().slice(11, 16).replace(':', ''); // HHmm
+
+  // Try reading STATE.md for active session_id
+  const candidates = [
+    join(root, '.claude/STATE.md'),
+    join(root, '.codex/STATE.md'),
+    join(root, '.cursor/STATE.md'),
+  ];
+  for (const p of candidates) {
+    if (!existsSync(p)) continue;
+    try {
+      const text = readFileSync(p, 'utf8');
+      const fm = parseFrontmatter(text);
+      if (fm && fm['status'] === 'active' && fm['session_id']) {
+        return fm['session_id'];
+      }
+      // Build session-id from branch + date if status is active but no session_id key
+      if (fm && fm['status'] === 'active') {
+        const sessionBranch = fm['branch'] || branch || 'unknown';
+        return `${sessionBranch}-${utcDate}-${utcHHmm}`;
+      }
+    } catch { /* ignore */ }
+  }
+
+  return `standalone-${utcDate}-${utcHHmm}`;
+}
+
+// ---------------------------------------------------------------------------
+// Minimal frontmatter parser (duplicated here to avoid lib dependency in main)
+// ---------------------------------------------------------------------------
+
+function parseFrontmatter(text) {
+  const lines = text.split(/\r?\n/);
+  let start = -1;
+  let end = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === '---') {
+      if (start === -1) { start = i; }
+      else { end = i; break; }
+    }
+  }
+  if (start === -1 || end === -1) return null;
+  const fm = {};
+  for (let i = start + 1; i < end; i++) {
+    const line = lines[i];
+    if (!line.trim() || line.trimStart().startsWith('#')) continue;
+    const colon = line.indexOf(':');
+    if (colon === -1) continue;
+    const key = line.slice(0, colon).trim();
+    const val = line.slice(colon + 1).trim();
+    fm[key] = val;
+  }
+  return fm;
+}
+
+// ---------------------------------------------------------------------------
+// Score a category from its checks
+// ---------------------------------------------------------------------------
+
+function scoreCategory(name, weight, checks) {
+  const maxPoints = checks.reduce((s, c) => s + c.max_points, 0);
+  const earnedPoints = checks.reduce((s, c) => s + c.points, 0);
+  const score010 = maxPoints > 0 ? parseFloat(((earnedPoints / maxPoints) * 10).toFixed(2)) : 0;
+  return { name, weight, score_0_10: score010, earned_points: earnedPoints, max_points: maxPoints, checks };
+}
+
+// ---------------------------------------------------------------------------
+// Overall band
+// ---------------------------------------------------------------------------
+
+function computeBand(score) {
+  if (score >= 8.5) return 'healthy';
+  if (score >= 6.0) return 'warn';
+  return 'critical';
+}
+
+// ---------------------------------------------------------------------------
+// stderr summary
+// ---------------------------------------------------------------------------
+
+function writeSummary(categories, summary) {
+  const bandSymbol = { healthy: '[OK]', warn: '[WARN]', critical: '[CRIT]' };
+  process.stderr.write('\n--- harness-audit summary ---\n');
+  for (const cat of categories) {
+    const band = computeBand(cat.score_0_10);
+    process.stderr.write(
+      `  ${cat.name.padEnd(32)} score=${cat.score_0_10.toFixed(2)}/10  ${bandSymbol[band]}\n`
+    );
+  }
+  process.stderr.write(
+    `  ${'OVERALL'.padEnd(32)} score=${summary.overall_mean_0_10.toFixed(2)}/10  ${bandSymbol[summary.overall_band]}  ` +
+    `checks=${summary.checks_passed}/${summary.checks_total}\n`
+  );
+  process.stderr.write('-----------------------------\n\n');
+}
+
+// ---------------------------------------------------------------------------
+// Append to audit.jsonl
+// ---------------------------------------------------------------------------
+
+function appendAuditRecord(root, record) {
+  const metricsDir = join(root, '.orchestrator/metrics');
+  try {
+    mkdirSync(metricsDir, { recursive: true });
+    const line = JSON.stringify(record) + '\n';
+    appendFileSync(join(metricsDir, 'audit.jsonl'), line, 'utf8');
+  } catch (err) {
+    process.stderr.write(`harness-audit: Failed to append audit.jsonl: ${err.message}\n`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const startedAt = new Date().toISOString();
+const startMs = Date.now();
+
+const auditRoot = resolveAuditRoot();
+const gitMeta = getGitMeta(auditRoot);
+const harnessVersion = getHarnessVersion(auditRoot);
+const sessionId = getSessionId(auditRoot, gitMeta.branch);
+
+// Run all 9 categories
+const categoryResults = [
+  scoreCategory('Session Discipline',       10, runCategory1(auditRoot)),
+  scoreCategory('Quality Gate Coverage',    10, runCategory2(auditRoot)),
+  scoreCategory('Hook Integrity',           10, runCategory3(auditRoot)),
+  scoreCategory('Persistence Health',       10, runCategory4(auditRoot)),
+  scoreCategory('Plugin-Root Resolution',    9, runCategory5(auditRoot)),
+  scoreCategory('Config Hygiene',            8, runCategory6(auditRoot)),
+  scoreCategory('Policy Freshness',         10, runCategory7(auditRoot)),
+  // Weight 8 mirrors Config Hygiene (cat 6): cat 8 is structural-hygiene rubric,
+  // not runtime-correctness. Weight 10 is reserved for production-impacting cats
+  // (Session Discipline / Quality Gate Coverage / Persistence Health / Policy Freshness).
+  scoreCategory('Large-Codebase Readiness',  8, runCategory8(auditRoot)),
+  // Weight 8 mirrors cat 6/8: skill-health surfacing is an advisory-hygiene
+  // rubric, not runtime-correctness. No-adoption scores full points by design
+  // (absent telemetry/module are HEALTHY states), so this never penalizes a
+  // repo that has not opted into the #648 per-skill health pipeline.
+  scoreCategory('Skill-Health Surfacing',    8, runCategory9(auditRoot)),
+];
+
+const durationMs = Date.now() - startMs;
+
+// Compute weighted mean
+const totalWeight = categoryResults.reduce((s, c) => s + c.weight, 0);
+const weightedSum = categoryResults.reduce((s, c) => s + c.weight * c.score_0_10, 0);
+const overallMean = parseFloat((weightedSum / totalWeight).toFixed(2));
+
+const checksPassed = categoryResults.reduce((s, c) => s + c.checks.filter((ch) => ch.status === 'pass').length, 0);
+const checksTotal = categoryResults.reduce((s, c) => s + c.checks.length, 0);
+
+const summary = {
+  overall_mean_0_10: overallMean,
+  overall_band: computeBand(overallMean),
+  checks_passed: checksPassed,
+  checks_total: checksTotal,
+};
+
+const output = {
+  rubric_version: RUBRIC_VERSION,
+  started_at: startedAt,
+  duration_ms: durationMs,
+  audit_root: auditRoot,
+  harness_version: harnessVersion,
+  categories: categoryResults,
+  summary,
+  repository: gitMeta,
+};
+
+// Write stdout (without session_id — session_id only in audit.jsonl).
+// Use the write callback to ensure the stdout buffer has fully drained before
+// running any subsequent I/O or exiting. On CI runners the process can exit
+// before the pipe buffer flushes, truncating the JSON at the OS pipe boundary
+// (8 KiB on many Linux kernels). Pattern A — drain-aware write (issue #356).
+const jsonStr = JSON.stringify(output, null, 2) + '\n';
+process.stdout.write(jsonStr, (err) => {
+  if (err) {
+    process.stderr.write(`harness-audit: stdout write error: ${err.message}\n`);
+    process.exit(2);
+    return; // prevent fall-through to success-path side effects on stdout failure (#356 Q1)
+  }
+
+  // Append to audit.jsonl (with session_id) — runs only after stdout drains
+  appendAuditRecord(auditRoot, { session_id: sessionId, ...output });
+
+  // Write stderr summary
+  writeSummary(categoryResults, summary);
+
+  // Always exit 0
+  process.exit(0);
+});

package/scripts/lib/agent-frontmatter.mjs

@@ -0,0 +1,266 @@
+/**
+ * Agent frontmatter validator — plain-JS, no Zod (issue #189).
+ *
+ * Validates `.claude/agents/*.md` frontmatter against the project-instruction
+ * file's Agent Authoring Rules (CLAUDE.md, or AGENTS.md on Codex CLI — see
+ * skills/_shared/instruction-file-resolution.md). Catches the two most common
+ * silent-failure pitfalls:
+ *   (a) `tools` as a JSON array instead of a comma-separated string
+ *   (b) `description` as a YAML block scalar (`>` or `|`) instead of an
+ *       inline string
+ *
+ * Modelled after scripts/lib/state-md.mjs (FRONTMATTER_RE, line-by-line
+ * key:value parsing) and scripts/lib/config-schema.mjs (error shape).
+ *
+ * Never throws. Returns structured result objects.
+ */
+
+import { readFileSync } from 'node:fs';
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+
+// Aliases per https://code.claude.com/docs/en/sub-agents § model resolution.
+// Full model IDs (claude-{opus|sonnet|haiku|fable}-N[-N][-YYYYMMDD], e.g.
+// "claude-opus-4-7", "claude-sonnet-5", "claude-fable-5-20260101") also
+// accepted via MODEL_ID_RE. `fable` is a valid upstream model family
+// alongside opus/sonnet/haiku (#768) — the trailing numeric group is
+// optional so both the two-part ("claude-sonnet-5") and three-part
+// ("claude-opus-4-7") ID shapes validate.
+// Exported so persona-panel modules (catalog-loader.mjs, persona-gate-wave.mjs) can
+// validate against the SSOT instead of re-declaring (W4 architect MED-1, 2026-05-19).
+export const ALLOWED_MODEL_ALIASES = new Set(['inherit', 'sonnet', 'opus', 'haiku', 'fable']);
+export const MODEL_ID_RE = /^claude-(opus|sonnet|haiku|fable)-\d+(-\d+)?(-\d{8})?$/;
+
+// Canonical Anthropic palette (red|blue|green|yellow|purple|orange|pink|cyan)
+// plus magenta from plugin-dev SKILL.md for backward-compat.
+const ALLOWED_COLORS = new Set(['blue', 'cyan', 'green', 'yellow', 'magenta', 'red', 'purple', 'orange', 'pink']);
+
+/**
+ * name must be 3–50 chars, lowercase letters, digits, hyphens only,
+ * starting with a lowercase letter.
+ */
+const NAME_RE = /^[a-z][a-z0-9-]{2,49}$/;
+
+/**
+ * Parses the YAML frontmatter block from an agent markdown file.
+ *
+ * Preserves raw string values so the validator can detect JSON-array tools
+ * and block-scalar descriptions without normalising them away.
+ *
+ * @returns {{ ok: true, frontmatter: Record<string,string>, body: string }
+ *          |{ ok: false, errors: Array<{path: string, rule: string, message: string}> }}
+ */
+export function parseAgentFrontmatter(contents) {
+  if (typeof contents !== 'string') {
+    return {
+      ok: false,
+      errors: [{ path: '$', rule: 'type', message: 'contents must be a string' }],
+    };
+  }
+
+  const match = FRONTMATTER_RE.exec(contents);
+  if (!match) {
+    return {
+      ok: false,
+      errors: [
+        {
+          path: '$',
+          rule: 'missing-frontmatter',
+          message: 'No YAML front-matter block (expected file to start with ---)',
+        },
+      ],
+    };
+  }
+
+  const [, fmText, body] = match;
+  const frontmatter = /** @type {Record<string,string>} */ ({});
+  const lines = fmText.split(/\r?\n/);
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\s+$/, '');
+    if (line === '' || /^\s*#/.test(line)) continue;
+
+    // Detect block-scalar indicators on a key line, e.g. `description: >` or `description: |`
+    // These are valid YAML but break Claude Code's parser.
+    const blockScalarMatch = /^(\w[\w-]*):\s*[>|]\s*$/.exec(line);
+    if (blockScalarMatch) {
+      // Store a sentinel so the validator can emit the correct rule.
+      frontmatter[blockScalarMatch[1]] = '__BLOCK_SCALAR__';
+      continue;
+    }
+
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    if (key === '') continue;
+    const value = line.slice(idx + 1).trim();
+    frontmatter[key] = value;
+  }
+
+  return {
+    ok: true,
+    frontmatter,
+    body: body.startsWith('\n') ? body.slice(1) : body,
+  };
+}
+
+/**
+ * Validates a parsed frontmatter object against CLAUDE.md Agent Authoring Rules.
+ *
+ * @param {Record<string,string>|null|undefined} frontmatter
+ * @returns {{ ok: true }|{ ok: false, errors: Array<{path: string, rule: string, message: string}> }}
+ */
+export function validateAgentFrontmatter(frontmatter) {
+  if (frontmatter === null || frontmatter === undefined || typeof frontmatter !== 'object') {
+    return {
+      ok: false,
+      errors: [{ path: '$', rule: 'missing-frontmatter', message: 'No YAML front-matter block' }],
+    };
+  }
+
+  const errors = /** @type {Array<{path: string, rule: string, message: string}>} */ ([]);
+
+  // --- name ---
+  const name = frontmatter['name'];
+  if (name === undefined || name === '') {
+    errors.push({
+      path: 'name',
+      rule: 'required',
+      message: 'name is required',
+    });
+  } else if (!NAME_RE.test(name)) {
+    errors.push({
+      path: 'name',
+      rule: 'name-format',
+      message: `name must be 3–50 chars, lowercase letters/digits/hyphens, starting with a letter (got ${JSON.stringify(name)})`,
+    });
+  }
+
+  // --- description ---
+  const description = frontmatter['description'];
+  if (description === undefined || description === '') {
+    errors.push({
+      path: 'description',
+      rule: 'required',
+      message: 'description is required',
+    });
+  } else if (description === '__BLOCK_SCALAR__') {
+    errors.push({
+      path: 'description',
+      rule: 'no-block-scalar',
+      message:
+        'description must be an inline single-line string, not a YAML block scalar (> or |). Put <example> blocks inline.',
+    });
+  }
+
+  // --- model ---
+  const model = frontmatter['model'];
+  if (model === undefined || model === '') {
+    errors.push({
+      path: 'model',
+      rule: 'required',
+      message: 'model is required',
+    });
+  } else if (!ALLOWED_MODEL_ALIASES.has(model) && !MODEL_ID_RE.test(model)) {
+    errors.push({
+      path: 'model',
+      rule: 'enum',
+      message: `model must be one of ${[...ALLOWED_MODEL_ALIASES].map((m) => JSON.stringify(m)).join('|')} or a full model ID like "claude-opus-4-7" or "claude-sonnet-5" (got ${JSON.stringify(model)})`,
+    });
+  }
+
+  // --- color ---
+  const color = frontmatter['color'];
+  if (color === undefined || color === '') {
+    errors.push({
+      path: 'color',
+      rule: 'required',
+      message: 'color is required',
+    });
+  } else if (!ALLOWED_COLORS.has(color)) {
+    errors.push({
+      path: 'color',
+      rule: 'enum',
+      message: `color must be one of ${[...ALLOWED_COLORS].map((c) => JSON.stringify(c)).join('|')} (got ${JSON.stringify(color)})`,
+    });
+  }
+
+  // --- tools (optional) ---
+  // Both forms accepted per Anthropic canonical:
+  //   1. Comma-separated string: "Read, Edit, Write"
+  //   2. JSON array:             ["Read","Edit","Write"]
+  // Reject only malformed arrays (non-string elements, parse failures).
+  const tools = frontmatter['tools'];
+  if (tools !== undefined && tools !== '' && typeof tools === 'string') {
+    if (tools.startsWith('[')) {
+      let parsed;
+      try {
+        parsed = JSON.parse(tools);
+      } catch {
+        errors.push({
+          path: 'tools',
+          rule: 'malformed-array',
+          message: `tools is a malformed JSON array: ${tools}`,
+        });
+        parsed = null;
+      }
+      if (parsed !== null) {
+        if (!Array.isArray(parsed)) {
+          errors.push({
+            path: 'tools',
+            rule: 'array-expected',
+            message: `tools must be an array when using JSON form (got ${typeof parsed})`,
+          });
+        } else if (!parsed.every((t) => typeof t === 'string')) {
+          errors.push({
+            path: 'tools',
+            rule: 'array-strings-only',
+            message: 'tools array must contain only string elements',
+          });
+        }
+      }
+    }
+  }
+
+  return errors.length > 0 ? { ok: false, errors } : { ok: true };
+}
+
+/**
+ * Convenience function: reads a file, parses its frontmatter, and validates it.
+ *
+ * Never throws. Returns a result object with the file path attached.
+ *
+ * @param {string} filePath - absolute or relative path to the agent .md file
+ * @returns {{ ok: true, file: string }
+ *          |{ ok: false, file: string, errors: Array<{path: string, rule: string, message: string}> }}
+ */
+export function validateAgentFile(filePath) {
+  let contents;
+  try {
+    contents = readFileSync(filePath, 'utf8');
+  } catch (err) {
+    return {
+      ok: false,
+      file: filePath,
+      errors: [
+        {
+          path: '$',
+          rule: 'read-error',
+          message: `Could not read file: ${err.message}`,
+        },
+      ],
+    };
+  }
+
+  const parsed = parseAgentFrontmatter(contents);
+  if (!parsed.ok) {
+    return { ok: false, file: filePath, errors: parsed.errors };
+  }
+
+  const validation = validateAgentFrontmatter(parsed.frontmatter);
+  if (!validation.ok) {
+    return { ok: false, file: filePath, errors: validation.errors };
+  }
+
+  return { ok: true, file: filePath };
+}