@raishin/vanguard-frontier-agentic 3.8.0 → 3.10.0

package/scripts/generate-board-counts.mjs

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+/**
+ * Generate catalog counts and inject them into the documentation that states them.
+ *
+ * Several docs quote agent, skill, provider, gate, and maestro totals. Typed by
+ * hand they go stale silently — a board gains an agent, a gate is added, and the
+ * prose keeps asserting last month's number with nothing to catch it. This
+ * generator derives every one of them from the repository itself and rewrites
+ * the marker spans, the same contract `generate-readme-counts.mjs` applies to
+ * README.md.
+ *
+ * Literal numbers are written into the markdown rather than Liquid variables:
+ * these files have no Jekyll front matter and several are read as raw markdown
+ * on GitHub, where `{{ site.data... }}` would render as literal braces.
+ *
+ * Two marker namespaces, both replacing only the number between the markers:
+ *
+ *   <!-- count:board:snowflake:agents -->28<!-- /count -->     per provider
+ *   <!-- count:global:gates -->25<!-- /count -->               repo-wide
+ *
+ * A board key may span providers by joining them with `+`, for a figure that is
+ * genuinely about a pair of boards rather than either one:
+ *
+ *   <!-- count:board:legal+hr:agents -->28<!-- /count -->
+ *
+ * Board keys, derived per provider. Deprecated assets are separated out FIRST
+ * and the tier keys then describe only the live board, so the parts sum to the
+ * whole without double counting — a deprecated live guard is `deprecated`, not
+ * `guards`:
+ *
+ *   agents      every agent for the provider, deprecated included
+ *   deprecated  agents whose metadata sets lifecycle: deprecated
+ *   skills      every skill for the provider
+ *   router      non-deprecated `*-maestro-agent` agents, whatever their tier
+ *   static      non-deprecated static-review agents
+ *   review      non-deprecated static-review agents that are NOT the router
+ *   readonly    non-deprecated read-only-runtime agents
+ *   guards      non-deprecated mutating-runtime agents
+ *   live        readonly + guards — the live control plane
+ *   specialists non-deprecated, non-router agents regardless of declared tier
+ *
+ * `review` is computed by excluding maestros from the static-review set rather
+ * than by subtracting the router count, because a maestro is not always a
+ * static-review agent: across this repo maestros are variously static-review,
+ * read-only-runtime, or untiered. Subtracting would under-count the specialists
+ * on every board whose router is not static-review.
+ *
+ * Global keys: agents, skills, providers, roles, gates, maestros, rules, mcp.
+ *
+ * Unknown providers and unknown keys are hard errors: a typo in a marker must
+ * fail the gate rather than silently keep a stale number.
+ *
+ * Mode:
+ *   (default)  rewrite the target documents in place
+ *   --check    compare expected vs actual, exit 1 if stale, 0 if current
+ *
+ * Run: npm run board-counts:write
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const check = process.argv.includes("--check");
+
+// Documents this generator owns. README.md is deliberately absent: it has its
+// own generator and its own `count:<key>` namespace. Changelogs, ADRs, and
+// dated plan/research documents are also absent on purpose — they record what
+// was true when written, and rewriting their numbers would falsify the record.
+const TARGETS = [
+  "docs/language-stack-boards.md",
+  "docs/configuration.md",
+  "docs/marketplace-model.md",
+  "tests/fixtures/README.md",
+  "index.md",
+];
+
+// ---------------------------------------------------------------------------
+// Collect stats from the repository
+// ---------------------------------------------------------------------------
+
+/** Read every metadata.json two levels under `root` (e.g. agents/<provider>/<asset>/). */
+function readMetadata(root) {
+  const out = [];
+  const base = path.join(repoRoot, root);
+  if (!fs.existsSync(base)) return out;
+  for (const provider of fs.readdirSync(base)) {
+    const providerDir = path.join(base, provider);
+    if (!fs.statSync(providerDir).isDirectory()) continue;
+    for (const asset of fs.readdirSync(providerDir)) {
+      const metaPath = path.join(providerDir, asset, "metadata.json");
+      if (!fs.existsSync(metaPath)) continue;
+      out.push(JSON.parse(fs.readFileSync(metaPath, "utf8")));
+    }
+  }
+  return out;
+}
+
+const agentMeta = readMetadata("agents");
+const skillMeta = readMetadata("skills");
+
+const BOARD_KEYS = [
+  "agents", "deprecated", "skills",
+  "router", "static", "review", "readonly", "guards", "live", "specialists",
+];
+
+/** @type {Map<string, Record<string, number>>} */
+const stats = new Map();
+
+function bucket(provider) {
+  if (!stats.has(provider)) {
+    stats.set(provider, Object.fromEntries(BOARD_KEYS.map((k) => [k, 0])));
+  }
+  return stats.get(provider);
+}
+
+for (const m of agentMeta) {
+  if (!m.provider) continue;
+  const s = bucket(m.provider);
+  s.agents += 1;
+
+  // Deprecated first, and exclusively: a deprecated live guard is not part of
+  // the live board, so counting it under `guards` would both overstate the
+  // mutation surface and break the sum against `agents`.
+  if (m.lifecycle === "deprecated") {
+    s.deprecated += 1;
+    continue;
+  }
+
+  const isRouter = typeof m.id === "string" && m.id.endsWith("-maestro-agent");
+  if (isRouter) s.router += 1;
+  // Every non-router agent on the live board, whatever tier it declares — or
+  // none at all. Many boards predate the tier field, so `review` (which counts
+  // only declared static-review agents) reads 0 for them; `specialists` is the
+  // figure those boards actually mean.
+  else s.specialists += 1;
+
+  if (m.execution_tier === "static-review") {
+    s.static += 1;
+    // Specialists are the static-review agents that are not the router. Derived
+    // by exclusion, not by subtracting `router`, because a router is not always
+    // static-review — see the header note.
+    if (!isRouter) s.review += 1;
+  } else if (m.execution_tier === "read-only-runtime") {
+    s.readonly += 1;
+  } else if (m.execution_tier === "mutating-runtime") {
+    s.guards += 1;
+  }
+}
+
+for (const m of skillMeta) {
+  if (!m.provider) continue;
+  bucket(m.provider).skills += 1;
+}
+
+for (const s of stats.values()) s.live = s.readonly + s.guards;
+
+// ---------------------------------------------------------------------------
+// Repo-wide figures
+// ---------------------------------------------------------------------------
+
+function jsonLen(rel, pick) {
+  const p = path.join(repoRoot, rel);
+  if (!fs.existsSync(p)) return 0;
+  const parsed = JSON.parse(fs.readFileSync(p, "utf8"));
+  const v = pick ? pick(parsed) : parsed;
+  return Array.isArray(v) ? v.length : Object.keys(v).length;
+}
+
+const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8"));
+// Gates = the distinct validate:* scripts the `validate` chain actually runs.
+// Counting the chain rather than every validate:* key means a script that
+// exists but was never wired in is not advertised as an enforced gate.
+const gateCount = new Set(
+  (pkg.scripts?.validate ?? "").match(/validate:[a-z0-9-]+/g) ?? [],
+).size;
+
+const fixturesDir = path.join(repoRoot, "tests", "fixtures");
+const maestroCount = fs.existsSync(fixturesDir)
+  ? fs.readdirSync(fixturesDir).filter((d) => d.endsWith("-maestro-routing")).length
+  : 0;
+
+const globals = {
+  agents: agentMeta.length,
+  skills: skillMeta.length,
+  providers: new Set(agentMeta.map((m) => m.provider).filter(Boolean)).size,
+  roles: jsonLen("catalog/install-roles.json", (d) => d.roles ?? d),
+  gates: gateCount,
+  maestros: maestroCount,
+  rules: jsonLen("catalog/rules.json"),
+  mcp: jsonLen("catalog/mcp-references.json"),
+};
+
+// ---------------------------------------------------------------------------
+// Rewrite the marker spans
+// ---------------------------------------------------------------------------
+
+const markerRe =
+  /<!-- count:(board:([a-z0-9+-]+)|global):([a-z]+) -->(\d+)<!-- \/count -->/g;
+
+const errors = [];
+const pending = [];
+let seen = 0;
+
+for (const rel of TARGETS) {
+  const file = path.join(repoRoot, rel);
+  if (!fs.existsSync(file)) {
+    errors.push(`target document missing: ${rel}`);
+    continue;
+  }
+  const original = fs.readFileSync(file, "utf8");
+
+  const updated = original.replace(markerRe, (match, scope, providerList, key, current) => {
+    seen += 1;
+    let expected;
+
+    if (scope === "global") {
+      if (!(key in globals)) {
+        errors.push(`${rel}: unknown global key "${key}" — valid: ${Object.keys(globals).sort().join(", ")}`);
+        return match;
+      }
+      expected = String(globals[key]);
+    } else {
+      if (!BOARD_KEYS.includes(key)) {
+        errors.push(`${rel}: unknown board key "${key}" — valid: ${BOARD_KEYS.slice().sort().join(", ")}`);
+        return match;
+      }
+      const providers = providerList.split("+");
+      let total = 0;
+      let bad = false;
+      for (const p of providers) {
+        const s = stats.get(p);
+        if (!s) {
+          errors.push(`${rel}: unknown provider "${p}" in count:board:${providerList}:${key} — no agents or skills found on disk for it`);
+          bad = true;
+          continue;
+        }
+        total += s[key];
+      }
+      if (bad) return match;
+      expected = String(total);
+    }
+
+    if (check && expected !== current) {
+      errors.push(`${rel}: stale count:${scope}:${key} — file says ${current}, repository says ${expected}`);
+    }
+    return `<!-- count:${scope}:${key} -->${expected}<!-- /count -->`;
+  });
+
+  if (updated !== original) pending.push([file, rel, updated]);
+}
+
+if (errors.length) {
+  console.error("FAIL: generated documentation counts");
+  for (const e of errors) console.error(`  - ${e}`);
+  if (check) console.error("\nRun `npm run board-counts:write` to refresh.");
+  process.exit(1);
+}
+
+if (seen === 0) {
+  console.error("FAIL: no count:board:* or count:global:* markers found in any target document.");
+  console.error("      The generator is wired in but the documents no longer carry markers,");
+  console.error("      which means their counts are unguarded. Restore the markers.");
+  process.exit(1);
+}
+
+if (check) {
+  console.log(`OK: documentation counts current (${seen} marker(s) across ${TARGETS.length} document(s))`);
+  process.exit(0);
+}
+
+for (const [file, rel, content] of pending) {
+  fs.writeFileSync(file, content);
+  console.log(`  updated ${rel}`);
+}
+console.log(
+  pending.length
+    ? `OK: documentation counts written (${seen} marker(s), ${pending.length} document(s) changed)`
+    : `OK: documentation counts already up to date (${seen} marker(s))`,
+);

package/scripts/generate-docs-data.mjs

@@ -22,6 +22,14 @@ const mcpRefs = JSON.parse(readFileSync(join(root, 'catalog/mcp-references.json'
 const rules = JSON.parse(readFileSync(join(root, 'catalog/rules.json'), 'utf8'));
 const roles = JSON.parse(readFileSync(join(root, 'catalog/install-roles.json'), 'utf8'));
 const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+// Workflow catalog is additive: a checkout without any workflow reports zero rather
+// than failing the docs build, matching how the TUI loader treats a missing file.
+let workflows = [];
+try {
+  workflows = JSON.parse(readFileSync(join(root, 'catalog/workflows.json'), 'utf8')).workflows || [];
+} catch {
+  workflows = [];
+}
 
 // Compute counts
 const providers = [...new Set(agents.map(a => a.provider))].sort();
@@ -80,6 +88,7 @@ skills: ${skills.length}
 providers: ${providers.length}
 mcp_references: ${mcpRefs.length}
 rules: ${rules.length}
+workflows: ${workflows.length}
 install_roles: ${roleIds.length}
 validation_gates: ${validateScripts.length}
 agent_directories: ${agentDirs.length}
@@ -95,6 +104,10 @@ ${providers.map(p => `  - "${p}"`).join('\n')}
 provider_taxonomy:
 ${taxonomyYaml}
 
+# Workflow list (delegation workflows in .claude/workflows/)
+workflow_list:
+${workflows.length ? workflows.map(w => `  - name: "${w.name}"\n    phases: ${(w.phases || []).length}`).join('\n') : '  []'}
+
 # Role list
 role_list:
 ${roleIds.map(r => `  - "${r}"`).join('\n')}

package/scripts/generate-kiro-powers.mjs

@@ -275,15 +275,15 @@ const PROVIDERS = {
     ],
   },
   snowflake: {
-    displayName: "Vanguard Frontier — Snowflake (Azure)",
+    displayName: "Vanguard Frontier — Snowflake",
     description:
-      "Curated Snowflake-on-Azure agents for RBAC access governance and data-platform engineering — static review only, no account or production mutations. Covers role hierarchy and least privilege, ACCOUNTADMIN restriction, SECURITYADMIN/SYSADMIN separation of duties, future grants and managed-access schemas, network policies, key-pair/Entra OAuth/SSO/SCIM authentication, Azure Private Link and storage integration, and masking/row-access/tagging governance. Snowflake and Azure surfaces are drift-prone; agents always verify against current Snowflake and Microsoft Learn documentation before rendering findings.",
-    keywords: ["snowflake", "azure", "rbac", "least-privilege", "data-governance", "private-link", "static-review"],
+      "A cloud-neutral Snowflake board routed by snowflake-maestro: architecture and account topology, platform administration, identity and effective access, network and private connectivity, governance and privacy controls, independent compliance evidence, FinOps unit economics, query performance, batch pipelines, streaming ingestion reliability, analytical semantics, ML lifecycle, Cortex AI agent security, Native Apps and Marketplace, BCDR, DevOps/IaC, migration, and business value. Review agents are read-only; six approval-gated live guards each execute exactly one mutation behind an explicit written human gate. Snowflake surfaces are drift-prone — agents re-verify GA/preview status, deprecations, edition/cloud/region availability, and provider resource stability against current Snowflake documentation before rendering findings.",
+    keywords: ["snowflake", "rbac", "least-privilege", "data-governance", "finops", "cortex-ai", "bcdr", "live-guard"],
     invariants: [
-      "Static review only — agents never request account credentials, key-pair private keys, OAuth secrets, or customer data, and never mutate a Snowflake account or Azure resource.",
-      "Enforce least privilege: custom business-function roles under SYSADMIN, restrict ACCOUNTADMIN to a minimum of controlled users, never grant sensitive privileges to PUBLIC, separate SECURITYADMIN (grants) from SYSADMIN (objects).",
-      "Service accounts use key-pair or Entra OAuth (never passwords); enforce network policies and MFA for human users.",
-      "Production role/grant/policy/warehouse changes are live-guard gated — never auto-dispatched; require explicit approval, scope confirmation, and rollback plan.",
+      "Review agents are static review only — they never request account credentials, private keys, OAuth or programmatic access tokens, account locators, or customer data, and never mutate a Snowflake account.",
+      "Documentation proves supported platform behaviour, never configured account behaviour: edition, region, enabled bundles, authentication enforcement, and policy attachment are UNKNOWN until account evidence establishes them.",
+      "Enforce least privilege: narrow custom roles, ACCOUNTADMIN forbidden for automation without exception, no GRANT ALL PRIVILEGES, no grants to PUBLIC, no unbounded future grants, and no password authentication for non-human identities.",
+      "Live guards are never auto-dispatched: each executes exactly one mutation after explicit written human approval naming account, environment, target, mutation, and accepted blast radius, with prior-state capture, preflight, verification, and a rollback path.",
     ],
   },
 };

package/scripts/generate-workflow-catalog.mjs

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+/**
+ * Generator: catalog/workflows.json from .claude/workflows/*.js
+ *
+ * Workflow scripts are executable JavaScript whose body calls workflow globals
+ * (`phase`, `agent`, `parallel`) that only exist inside the workflow runtime, so the
+ * files cannot be imported to read their metadata — evaluating one outside the runtime
+ * throws on the first `phase()` call.
+ *
+ * They can, however, be read statically. The workflow contract requires `meta` to be a
+ * PURE LITERAL (no variables, calls, spreads, or interpolation), so this extracts the
+ * object literal following `export const meta =` by brace matching and then PARSES it
+ * with `parseLiteral` — it is never evaluated. Evaluating it would mean `npm run
+ * validate` executing code out of any workflow file a contributor adds; parsing both
+ * removes that and turns the pure-literal contract into something actually enforced.
+ *
+ * The output exists so `tools/vfa-tui` can display available workflows without
+ * re-implementing any of this: the TUI reads generated catalog JSON and never parses
+ * JavaScript. Same contract as every other catalog file.
+ *
+ * Usage:
+ *   node scripts/generate-workflow-catalog.mjs           # write
+ *   node scripts/generate-workflow-catalog.mjs --check   # verify in sync (CI)
+ */
+import { readFileSync, writeFileSync, readdirSync, existsSync, realpathSync } from 'node:fs'
+import { join, dirname, relative, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
+const WORKFLOW_DIR = join(ROOT, '.claude', 'workflows')
+const OUT = join(ROOT, 'catalog', 'workflows.json')
+
+/**
+ * Extract the balanced `{...}` literal following `export const meta =`.
+ * Returns null when the marker is absent.
+ */
+function extractMetaLiteral(source) {
+  const marker = /export\s+const\s+meta\s*=\s*/.exec(source)
+  if (!marker) return null
+  let i = marker.index + marker[0].length
+  if (source[i] !== '{') return null
+
+  // Brace matching that respects strings, template literals, and comments — a `{`
+  // inside a description string must not be counted as nesting.
+  let depth = 0
+  let inS = null // "'" | '"' | '`'
+  let inLine = false
+  let inBlock = false
+  for (; i < source.length; i++) {
+    const c = source[i]
+    const prev = source[i - 1]
+    if (inLine) {
+      if (c === '\n') inLine = false
+      continue
+    }
+    if (inBlock) {
+      if (c === '/' && prev === '*') inBlock = false
+      continue
+    }
+    if (inS) {
+      if (c === inS && prev !== '\\') inS = null
+      continue
+    }
+    if (c === '/' && source[i + 1] === '/') { inLine = true; continue }
+    if (c === '/' && source[i + 1] === '*') { inBlock = true; continue }
+    if (c === "'" || c === '"' || c === '`') { inS = c; continue }
+    if (c === '{') depth++
+    else if (c === '}') {
+      depth--
+      if (depth === 0) return source.slice(marker.index + marker[0].length, i + 1)
+    }
+  }
+  return null
+}
+
+/**
+ * Parse a JavaScript *data* literal without evaluating it.
+ *
+ * Accepts exactly the pure-literal subset the workflow `meta` contract promises:
+ * objects (quoted or bare identifier keys, optional trailing comma), arrays, single-,
+ * double- and backtick-quoted strings with no `${}` substitution, numbers, `true`,
+ * `false`, `null`. Anything else — a call, an identifier reference, a spread, a
+ * template substitution, an operator — is a syntax error rather than something that
+ * runs. Comments are skipped.
+ *
+ * Deliberately hand-written rather than delegated to `eval`/`Function`/`vm`: the point
+ * is that no code path here can execute the input.
+ */
+export function parseLiteral(src) {
+  let i = 0
+
+  const fail = (msg) => {
+    throw new Error(`${msg} at offset ${i}`)
+  }
+  const skip = () => {
+    for (;;) {
+      while (i < src.length && /\s/.test(src[i])) i++
+      if (src[i] === '/' && src[i + 1] === '/') {
+        while (i < src.length && src[i] !== '\n') i++
+      } else if (src[i] === '/' && src[i + 1] === '*') {
+        i += 2
+        while (i < src.length && !(src[i] === '*' && src[i + 1] === '/')) i++
+        if (i >= src.length) fail('unterminated block comment')
+        i += 2
+      } else {
+        return
+      }
+    }
+  }
+
+  const readString = () => {
+    const quote = src[i++]
+    let out = ''
+    while (i < src.length) {
+      const c = src[i]
+      if (c === '\\') {
+        const esc = src[i + 1]
+        const simple = { n: '\n', t: '\t', r: '\r', b: '\b', f: '\f', v: '\v', 0: '\0' }
+        if (esc === 'u') {
+          const hex = src.slice(i + 2, i + 6)
+          if (!/^[0-9a-fA-F]{4}$/.test(hex)) fail('bad unicode escape')
+          out += String.fromCharCode(parseInt(hex, 16))
+          i += 6
+        } else if (esc === 'x') {
+          const hex = src.slice(i + 2, i + 4)
+          if (!/^[0-9a-fA-F]{2}$/.test(hex)) fail('bad hex escape')
+          out += String.fromCharCode(parseInt(hex, 16))
+          i += 4
+        } else if (esc === '\n') {
+          i += 2 // line continuation
+        } else if (esc in simple) {
+          out += simple[esc]
+          i += 2
+        } else {
+          out += esc
+          i += 2
+        }
+        continue
+      }
+      if (c === quote) {
+        i++
+        return out
+      }
+      // A template substitution would require evaluation to resolve, which is exactly
+      // what this parser exists to avoid.
+      if (quote === '`' && c === '$' && src[i + 1] === '{') fail('template substitution is not a literal')
+      if (quote !== '`' && c === '\n') fail('unterminated string')
+      out += c
+      i++
+    }
+    return fail('unterminated string')
+  }
+
+  const readValue = () => {
+    skip()
+    const c = src[i]
+    if (c === '{') return readObject()
+    if (c === '[') return readArray()
+    if (c === '"' || c === "'" || c === '`') return readString()
+    if (src.startsWith('true', i)) { i += 4; return true }
+    if (src.startsWith('false', i)) { i += 5; return false }
+    if (src.startsWith('null', i)) { i += 4; return null }
+    const num = /^-?\d+(\.\d+)?([eE][+-]?\d+)?/.exec(src.slice(i))
+    if (num) { i += num[0].length; return Number(num[0]) }
+    return fail(`unexpected token ${JSON.stringify(src.slice(i, i + 24))}`)
+  }
+
+  const readObject = () => {
+    i++ // {
+    const obj = {}
+    skip()
+    if (src[i] === '}') { i++; return obj }
+    for (;;) {
+      skip()
+      if (src[i] === '.' ) fail('spread is not a literal')
+      let key
+      if (src[i] === '"' || src[i] === "'" || src[i] === '`') {
+        key = readString()
+      } else {
+        const id = /^[A-Za-z_$][A-Za-z0-9_$]*/.exec(src.slice(i))
+        if (!id) fail('expected property name')
+        key = id[0]
+        i += id[0].length
+      }
+      skip()
+      if (src[i] !== ':') fail(`expected ':' after key ${JSON.stringify(key)}`)
+      i++
+      obj[key] = readValue()
+      skip()
+      if (src[i] === ',') { i++; skip(); if (src[i] === '}') { i++; return obj } continue }
+      if (src[i] === '}') { i++; return obj }
+      return fail("expected ',' or '}'")
+    }
+  }
+
+  const readArray = () => {
+    i++ // [
+    const arr = []
+    skip()
+    if (src[i] === ']') { i++; return arr }
+    for (;;) {
+      skip()
+      if (src[i] === '.') fail('spread is not a literal')
+      arr.push(readValue())
+      skip()
+      if (src[i] === ',') { i++; skip(); if (src[i] === ']') { i++; return arr } continue }
+      if (src[i] === ']') { i++; return arr }
+      return fail("expected ',' or ']'")
+    }
+  }
+
+  const value = readValue()
+  skip()
+  if (i !== src.length) fail('trailing content after literal')
+  return value
+}
+
+function readWorkflow(file) {
+  const abs = join(WORKFLOW_DIR, file)
+  const src = readFileSync(abs, 'utf8')
+  const literal = extractMetaLiteral(src)
+  if (!literal) {
+    throw new Error(`${file}: no 'export const meta = {...}' block found`)
+  }
+  let meta
+  try {
+    // PARSED, never evaluated. An earlier version ran `new Function(...)` on this
+    // literal, which meant `npm run validate` executed code out of any workflow file a
+    // contributor added — `description: (() => { …anything… })()` would have run with
+    // the validator's privileges. In a repository whose subject is supply-chain
+    // integrity that is not an acceptable way to read metadata, and it also let
+    // nondeterministic values into a generated catalog. parseLiteral accepts only
+    // JSON-shaped data and rejects everything else, which additionally makes the
+    // "meta must be a pure literal" contract actually enforced rather than assumed.
+    meta = parseLiteral(literal)
+  } catch (err) {
+    throw new Error(`${file}: meta is not a pure literal (${err.message})`)
+  }
+  if (!meta || typeof meta.name !== 'string' || typeof meta.description !== 'string') {
+    throw new Error(`${file}: meta must declare string 'name' and 'description'`)
+  }
+  const expected = file.replace(/\.m?js$/, '')
+  if (meta.name !== expected) {
+    throw new Error(
+      `${file}: meta.name '${meta.name}' must match the filename '${expected}' — ` +
+      'the workflow is invoked by name, and a mismatch makes it unreachable',
+    )
+  }
+  return {
+    id: meta.name,
+    name: meta.name,
+    // Forward slashes always. `relative()` emits backslashes on Windows, which would
+    // make generated output platform-dependent: `--check` would fail on one OS against
+    // a catalog committed from another, and the Rust loader test asserts a
+    // `.claude/workflows/` prefix. A repo-relative path in a committed artifact is a
+    // repo path, not a filesystem path.
+    path: relative(ROOT, abs).split(sep).join('/'),
+    description: meta.description,
+    when_to_use: typeof meta.whenToUse === 'string' ? meta.whenToUse : '',
+    phases: Array.isArray(meta.phases)
+      ? meta.phases.map((p) => ({
+          title: String(p.title ?? ''),
+          detail: typeof p.detail === 'string' ? p.detail : '',
+          model: typeof p.model === 'string' ? p.model : '',
+        }))
+      : [],
+  }
+}
+
+function build() {
+  const files = existsSync(WORKFLOW_DIR)
+    ? readdirSync(WORKFLOW_DIR).filter((f) => /\.m?js$/.test(f)).sort()
+    : []
+  const workflows = files.map(readWorkflow)
+  return {
+    version: '0.1.0',
+    description:
+      'Workflow definitions discovered in .claude/workflows/. Generated from each ' +
+      "script's meta block by scripts/generate-workflow-catalog.mjs — never hand-edited.",
+    workflows,
+  }
+}
+
+function main() {
+  const catalog = build()
+  const serialized = JSON.stringify(catalog, null, 2) + '\n'
+
+  if (process.argv.includes('--check')) {
+    const current = existsSync(OUT) ? readFileSync(OUT, 'utf8') : ''
+    if (current !== serialized) {
+      console.error(
+        'FAIL: catalog/workflows.json is out of sync with .claude/workflows/.\n' +
+        '      Run: npm run workflow-catalog:write',
+      )
+      process.exit(1)
+    }
+    console.log(`OK: workflow catalog in sync (${catalog.workflows.length} workflow(s))`)
+  } else {
+    writeFileSync(OUT, serialized)
+    console.log(`OK: wrote catalog/workflows.json (${catalog.workflows.length} workflow(s))`)
+  }
+}
+
+// Only run when invoked directly. `parseLiteral` is exported so it can be tested and
+// reused, and importing a module must never write a file as a side effect.
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main()
+}