@raishin/vanguard-frontier-agentic 3.9.0 → 3.11.0

package/scripts/generate-board-counts.mjs

@@ -0,0 +1,287 @@
+#!/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",
+  "docs/databricks-board.md",
+  "tests/fixtures/README.md",
+  "index.md",
+];
+
+// README.md is deliberately NOT a target. `manifest:write:all` runs this generator and
+// generate-readme-counts.mjs concurrently (`&` … `wait`), so two writers on one file would
+// race. README keeps a single owner; its per-provider figures use that generator's own
+// `count:provider:<slug>` namespace, which this generator's marker regex cannot match.
+
+// ---------------------------------------------------------------------------
+// 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-kiro-powers.mjs

@@ -251,14 +251,14 @@ const PROVIDERS = {
     ],
   },
   databricks: {
-    displayName: "Vanguard Frontier — Databricks (Azure)",
+    displayName: "Vanguard Frontier — Databricks",
     description:
-      "Curated Azure Databricks agents for Unity Catalog governance and lakehouse engineering — static review only, no workspace or production mutations. Covers Unity Catalog securables and schema-scoped least-privilege grants, identity federation and account groups, account/workspace/metastore admin separation, run-production-as-service-principal, Entra ID managed identities, Access Connector + ADLS Gen2 external locations, cluster policies, and audit logs. Databricks and Azure surfaces are drift-prone; agents always verify against current Databricks and Microsoft Learn documentation before rendering findings.",
-    keywords: ["databricks", "azure", "unity-catalog", "lakehouse", "least-privilege", "data-engineering", "static-review"],
+      "Curated Databricks agents spanning a cloud-neutral lakehouse and AI board plus Azure-specific assets — static review only, no workspace or production mutations. Covers account and workspace topology, Unity Catalog governance (three-level namespace, GRANT model, workspace-catalog binding, governed tags), identity/network security (SCIM, service principals, OAuth vs personal access tokens, IP access lists, serverless egress, secret scopes), data protection and privacy (row filters, column masks, ABAC, classification, erasure via REORG/VACUUM, Delta Sharing egress, residency), Lakeflow pipelines and Delta table layout, Structured Streaming recovery, data quality and Lakehouse Monitoring, SQL warehouse performance, AI/BI Genie and metric views, MLflow and Model Serving, GenAI agent engineering and evaluation, Declarative Automation Bundles and CI/CD, operational evidence from system tables, FinOps cost attribution, and value realization. Databricks surfaces are drift-prone and differ by cloud, tier, and compute type; agents verify against current Databricks documentation, and pin version-sensitive client APIs against library documentation, before rendering findings.",
+    keywords: ["databricks", "unity-catalog", "lakehouse", "lakeflow", "mlflow", "genai", "finops", "least-privilege", "data-engineering", "static-review"],
     invariants: [
-      "Static review only — agents never request workspace tokens, service-principal secrets, storage keys, or customer data, and never mutate a Databricks workspace, Unity Catalog, or Azure resource.",
+      "Static review only — agents never request workspace tokens, service-principal secrets, storage keys, or customer data, and never mutate a Databricks workspace, Unity Catalog, or any cloud resource.",
       "Enforce least privilege: schema-scoped grants (CREATE TABLE/VOLUME/FUNCTION at schema level), no broad ALL PRIVILEGES, assign access to account groups not individuals, separate account/workspace/metastore admin roles.",
-      "Prefer Azure managed identities over service principals for storage access; production data is operated by service principals, not interactive users.",
+      "Storage access uses the platform's managed workload identity for the cloud in question — an Azure Access Connector managed identity, an AWS IAM role assumed by a storage credential, or a GCP service account — surfaced through a Unity Catalog storage credential and external location rather than embedded keys. Name the cloud before recommending a mechanism; do not assume Azure. Production workloads run as service principals, never as interactive users, on every cloud.",
       "Production grant/role/policy/cluster changes are live-guard gated — never auto-dispatched; require explicit approval, scope confirmation, and rollback plan.",
     ],
   },
@@ -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-readme-counts.mjs

@@ -181,6 +181,33 @@ const providerTableBlock =
 // Transform README content
 // ---------------------------------------------------------------------------
 
+// Agent counts per DIRECTORY under agents/, which is not the same thing as per
+// provider. agents/finops/ holds agents whose provider is kubernetes or multi-cloud,
+// and agents/qa/ holds agents whose provider is generic; conversely `generic` and
+// `multi-cloud` are provider values with no directory of their own. The README tree
+// documents the directory layout, so it must be keyed on directories — keying it on
+// provider would "correct" four currently-accurate lines into being wrong.
+const agentsPerDirectory = new Map();
+for (const entry of fs.readdirSync(path.join(repoRoot, "agents"), { withFileTypes: true })) {
+  if (!entry.isDirectory()) continue;
+  const dir = path.join(repoRoot, "agents", entry.name);
+  let n = 0;
+  for (const sub of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (sub.isDirectory() && fs.existsSync(path.join(dir, sub.name, "metadata.json"))) n++;
+  }
+  // A directory with no agents (agents/velero/ is a README-only leftover) is not part
+  // of the tree, and must not be reported as missing from it.
+  if (n > 0) agentsPerDirectory.set(entry.name, n);
+}
+
+/** Tree slugs naming a directory that holds no agents. */
+const treeUnknownDirs = new Set();
+/** Directories holding agents that the tree never lists. */
+let treeMissingDirs = [];
+
+/** Provider slugs referenced by a count:provider marker but absent from the catalog. */
+const unknownProviders = new Set();
+
 function buildExpectedContent(original) {
   let content = original;
 
@@ -202,6 +229,58 @@ function buildExpectedContent(original) {
     return `<!-- count:${key} -->${counts[key]}<!-- /count -->`;
   });
 
+  // 3. Per-provider agent counts: <!-- count:provider:SLUG -->N<!-- /count -->
+  //
+  // README's two narrative provider tables carry a count column alongside a
+  // hand-written description. The descriptions are prose and stay hand-written
+  // (CLAUDE.md), but the numbers next to them are catalog facts and drifted
+  // exactly as you would expect: both the databricks and snowflake rows sat at
+  // "3" for boards that had grown to 20 and 28 agents respectively, because
+  // nothing checked them.
+  //
+  // This namespace is deliberately separate from generate-board-counts.mjs.
+  // That generator owns `count:board:*` and `count:global:*`, and its TARGETS
+  // list does NOT include README.md — `manifest:write:all` runs the two
+  // generators concurrently (`&` … `wait`), so two writers on one file would
+  // race. Keeping README single-owner is what makes that safe; the two marker
+  // regexes are disjoint, so the split is enforceable rather than conventional.
+  const providerRe = /<!-- count:provider:([a-z0-9-]+) -->\d+<!-- \/count -->/g;
+  content = content.replace(providerRe, (match, slug) => {
+    if (!agentsPerProvider.has(slug)) {
+      // Fail closed. A typo'd or removed provider must not silently freeze at
+      // whatever number happened to be typed there.
+      unknownProviders.add(slug);
+      return match;
+    }
+    return `<!-- count:provider:${slug} -->${agentsPerProvider.get(slug)}<!-- /count -->`;
+  });
+
+  // 4. Repository-tree block: rewrite the agent count on each directory line.
+  //
+  // The tree lives inside a ```text fence, where an HTML comment marker would render
+  // as visible text — so the markers wrap the fence and the counts are rewritten in
+  // place instead. Descriptions are hand-written prose and are preserved verbatim;
+  // only the number and its agent/agents pluralisation are generated.
+  const treeRe = /<!-- agent-tree:start -->[\s\S]*?<!-- agent-tree:end -->/;
+  const treeMatch = content.match(treeRe);
+  if (treeMatch) {
+    const seen = new Set();
+    const rewritten = treeMatch[0].replace(
+      /^([├└]── )([a-z0-9-]+)(\/\s*)\((\d+) (agents?)\b/gm,
+      (match, branch, slug, sep, _n, _word) => {
+        if (!agentsPerDirectory.has(slug)) {
+          treeUnknownDirs.add(slug);
+          return match;
+        }
+        seen.add(slug);
+        const n = agentsPerDirectory.get(slug);
+        return `${branch}${slug}${sep}(${n} ${n === 1 ? "agent" : "agents"}`;
+      },
+    );
+    treeMissingDirs = [...agentsPerDirectory.keys()].filter((d) => !seen.has(d)).sort();
+    content = content.replace(treeRe, rewritten);
+  }
+
   return content;
 }
 
@@ -212,6 +291,36 @@ function buildExpectedContent(original) {
 const original = fs.readFileSync(readmePath, "utf8");
 const expected = buildExpectedContent(original);
 
+// Fail closed on a count:provider marker naming a provider the catalog does not
+// have. Rewriting it is impossible and leaving it alone would freeze a stale
+// number behind a marker that looks generated — the worst of both worlds.
+if (treeUnknownDirs.size > 0 || treeMissingDirs.length > 0) {
+  const parts = [];
+  if (treeUnknownDirs.size > 0) {
+    parts.push(
+      `tree lists director(y|ies) with no agents: ${[...treeUnknownDirs].sort().join(", ")}`,
+    );
+  }
+  if (treeMissingDirs.length > 0) {
+    parts.push(`agents/ director(y|ies) missing from the tree: ${treeMissingDirs.join(", ")}`);
+  }
+  process.stderr.write(
+    `ERROR: README.md repository tree is out of sync with agents/.\n  - ${parts.join("\n  - ")}\n` +
+      `The counts are generated, but each line's description is hand-written — ` +
+      `add or remove the line by hand, then re-run.\n`,
+  );
+  process.exit(1);
+}
+
+if (unknownProviders.size > 0) {
+  process.stderr.write(
+    `ERROR: README.md references unknown provider(s) in count:provider markers: ` +
+      `${[...unknownProviders].sort().join(", ")}\n` +
+      `Valid providers: ${[...agentsPerProvider.keys()].sort().join(", ")}\n`,
+  );
+  process.exit(1);
+}
+
 if (check) {
   if (original === expected) {
     console.log("OK: README counts current");