@cohortapp/agent-sdk 2.4.1 → 2.5.0

package/scripts/setup/repair-subagent-frontmatter.mjs

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+/**
+ * repair-subagent-frontmatter.mjs — bring every `agents/<slug>/agent.md` back to
+ * a state that `lib/subagents/schema.validateAgentMd()` accepts.
+ *
+ * WHY THIS EXISTS. `renderAgentMd()` in generate-capability.mjs shipped two bugs
+ * that every repo scaffolded before 2026-08-11 inherited across its whole role
+ * roster:
+ *
+ *   1. it emitted no `tools:` key, so EVERY generated sub-agent failed
+ *      validation ("frontmatter.tools is required") — 57 of 70 in this repo; and
+ *   2. it interpolated identity at GENERATION time rather than leaving
+ *      `{{agent.*}}` tokens for lib/render.mjs, so a repo generated before
+ *      config/agent.json was populated baked the empty values in permanently:
+ *      "You are the Chief of Staff sub-agent for ( at UNCONFIGURED)".
+ *
+ * Both are fixed at source in generate-capability.mjs. This pass repairs the
+ * files that were already written, and it does so by calling that SAME exported
+ * renderAgentMd() — a second implementation here would be free to drift from the
+ * generator, which is the whole failure mode we are cleaning up.
+ *
+ * SAFETY. Dry-run by default; `--write` applies. It only rewrites files that
+ * FAIL validation and whose slug is still present in the capability pack, and it
+ * refuses to touch a file whose body has been edited away from the generator's
+ * output unless `--force` is passed — a hand-tailored mandate is real work and
+ * regenerating it silently would destroy it.
+ *
+ * Usage:
+ *   node scripts/setup/repair-subagent-frontmatter.mjs            # report only
+ *   node scripts/setup/repair-subagent-frontmatter.mjs --write    # apply
+ *
+ * @module scripts/setup/repair-subagent-frontmatter
+ */
+
+"use strict";
+
+import { readFileSync, writeFileSync, existsSync, readdirSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import {
+  checkAgentFile,
+  splitFrontmatter,
+} from "../../lib/subagents/schema.mjs";
+import { renderAgentMd } from "./generate-capability.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const MAESTRO_ROOT =
+  process.env.MAESTRO_ROOT &&
+  existsSync(join(process.env.MAESTRO_ROOT, "lib", "capability.mjs"))
+    ? process.env.MAESTRO_ROOT
+    : resolve(here, "..", "..");
+const AGENT_ROOT = process.env.AGENT_ROOT || process.cwd();
+
+/**
+ * The `{function, altitude}` the on-disk roster was generated from.
+ *
+ * Deliberately read from config/agent-roster.yaml, NOT config/agent.json: the
+ * roster records what was actually written to agents/, and the two can disagree
+ * (this repo's agent.json says technical-leader × svp while every file on disk is
+ * executive-operator × c-suite). Repairing against agent.json would look up the
+ * wrong pack and "repair" nothing.
+ *
+ * @param {object} yaml js-yaml module
+ * @returns {{function:string, altitude:string}|null}
+ */
+export function rosterArchetype(yaml, agentRoot = AGENT_ROOT) {
+  const p = join(agentRoot, "config", "agent-roster.yaml");
+  if (!existsSync(p)) return null;
+  const doc = yaml.load(readFileSync(p, "utf-8")) || {};
+  const m = String(doc.archetype || "").match(/^([a-z-]+)@([a-z-]+)$/);
+  return m ? { function: m[1], altitude: m[2] } : null;
+}
+
+/**
+ * Pull the prose under a `## <heading>` out of an agent.md body, whitespace
+ * normalised. Returns "" when the heading is absent.
+ *
+ * Normalising whitespace is not cosmetic here: the machine-wide prettier hook
+ * inserts a blank line after every markdown heading, so the on-disk files differ
+ * from the generator's own output by whitespace alone in three places.
+ *
+ * @param {string} text full agent.md @param {string} heading e.g. "Mandate"
+ * @returns {string}
+ */
+export function sectionText(text, heading) {
+  const body = splitFrontmatter(text).body;
+  const m = body.match(
+    new RegExp(`^##\\s+${heading}\\s*$([\\s\\S]*?)(?=^##\\s|\\Z)`, "m"),
+  );
+  return m ? m[1].replace(/\s+/g, " ").trim() : "";
+}
+
+/**
+ * Has this file's BODY been tailored away from the pack's own content?
+ *
+ * Deliberately NOT a diff against a regenerated file. The corrupt files differ
+ * from a token-bearing regeneration in exactly the identity spans, and trying to
+ * regex those spans back out is guesswork that fails open (an over-eager pattern
+ * silently overwrites someone's tailored mandate) or closed (a shy one repairs
+ * nothing — the first cut of this function flagged all 57 files as hand-edited).
+ *
+ * So compare the only two things a human tailoring an agent would actually
+ * change, against the pack they came from: the mandate prose and the towers
+ * list. Everything else in the template is boilerplate the generator owns. If
+ * both still match the pack verbatim, nothing has been authored here and
+ * regenerating destroys nothing.
+ *
+ * @param {string} currentText @param {object} packEntry @returns {boolean}
+ */
+export function bodyWasHandEdited(currentText, packEntry) {
+  const mandate = String((packEntry && packEntry.mandate) || "")
+    .replace(/\s+/g, " ")
+    .trim();
+  const towers = (packEntry && packEntry.towers) || [];
+  const expectedTowers = towers.length
+    ? `- ${towers.join(", ")}`
+    : "- (general)";
+  return (
+    sectionText(currentText, "Mandate") !== mandate ||
+    sectionText(currentText, "Towers served") !== expectedTowers
+  );
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const write = argv.includes("--write");
+  const force = argv.includes("--force");
+
+  const yamlMod = await import("js-yaml");
+  const yaml = yamlMod && yamlMod.default ? yamlMod.default : yamlMod;
+  const { resolveArchetype } = await import(
+    pathToFileURL(join(MAESTRO_ROOT, "lib", "archetype.mjs")).href
+  );
+  const { resolveCapabilitySurface } = await import(
+    pathToFileURL(join(MAESTRO_ROOT, "lib", "capability.mjs")).href
+  );
+
+  const sel = rosterArchetype(yaml);
+  if (!sel) {
+    console.error(
+      "[repair-subagent-frontmatter] config/agent-roster.yaml has no `archetype: <function>@<altitude>` — nothing to repair against.",
+    );
+    return 1;
+  }
+  const profile = await resolveArchetype(sel);
+  const surface = await resolveCapabilitySurface(sel);
+  const byId = new Map(surface.roleAgents.map((a) => [a.id, a]));
+
+  const agentsDir = join(AGENT_ROOT, "agents");
+  const slugs = existsSync(agentsDir)
+    ? readdirSync(agentsDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name)
+        .sort()
+    : [];
+
+  const repaired = [];
+  const skippedValid = [];
+  const unknown = [];
+  const handEdited = [];
+
+  for (const slug of slugs) {
+    const p = join(agentsDir, slug, "agent.md");
+    if (!existsSync(p)) {
+      unknown.push(`${slug} (no agent.md)`);
+      continue;
+    }
+    const text = readFileSync(p, "utf-8");
+    if (checkAgentFile(text, slug).ok) {
+      skippedValid.push(slug);
+      continue;
+    }
+    const packEntry = byId.get(slug);
+    if (!packEntry) {
+      unknown.push(`${slug} (invalid, but not in the ${sel.function} pack)`);
+      continue;
+    }
+    if (!force && bodyWasHandEdited(text, packEntry)) {
+      handEdited.push(slug);
+      continue;
+    }
+    const fresh = renderAgentMd(packEntry, profile);
+    const after = checkAgentFile(fresh, slug);
+    if (!after.ok) {
+      unknown.push(
+        `${slug} (regenerated but STILL invalid: ${after.errors.join("; ")})`,
+      );
+      continue;
+    }
+    if (write) writeFileSync(p, fresh, "utf-8");
+    repaired.push(slug);
+  }
+
+  const verb = write ? "repaired" : "would repair";
+  console.log(
+    `[repair-subagent-frontmatter] ${sel.function} × ${sel.altitude}: ${slugs.length} agent dir(s)`,
+  );
+  console.log(
+    `[repair-subagent-frontmatter]   already valid: ${skippedValid.length}`,
+  );
+  console.log(`[repair-subagent-frontmatter]   ${verb}: ${repaired.length}`);
+  if (handEdited.length)
+    console.log(
+      `[repair-subagent-frontmatter]   SKIPPED (body hand-edited, pass --force to overwrite): ${handEdited.join(", ")}`,
+    );
+  if (unknown.length)
+    console.log(
+      `[repair-subagent-frontmatter]   NOT repairable: ${unknown.join(", ")}`,
+    );
+  if (!write && repaired.length)
+    console.log(
+      "[repair-subagent-frontmatter] dry run — re-run with --write to apply.",
+    );
+  return 0;
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  main()
+    .then((c) => process.exit(c))
+    .catch((e) => {
+      console.error(
+        `[repair-subagent-frontmatter] FAILED: ${e && e.message ? e.message : e}`,
+      );
+      process.exit(1);
+    });
+}
+
+export { main };