@raishin/vanguard-frontier-agentic 1.8.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raishin/vanguard-frontier-agentic",
-  "version": "1.8.0",
+  "version": "2.0.0",
   "description": "Cloud and zero-trust agentic workflow marketplace for skills, agents, rules, MCP references, and compliance-aware architecture.",
   "license": "Apache-2.0",
   "repository": {
@@ -32,7 +32,8 @@
     "rules/",
     "mcp/",
     "templates/",
-    "assets/"
+    "assets/",
+    "tests/"
   ],
   "scripts": {
     "agents:export": "node scripts/export-marketplace-agents.mjs",
@@ -54,6 +55,7 @@
     "validate:kiro-powers": "python3 tests/validate-kiro-powers.py",
     "validate:multi-harness-marketplace": "python3 tests/validate-multi-harness-marketplace.py",
     "validate:codex-marketplace": "python3 tests/validate-codex-marketplace.py",
+    "validate:finops-fixtures": "python3 tests/validate-finops-price-fixtures.py",
     "test:marketplace-validators": "python3 tests/test-marketplace-validators.py",
     "maestro-routing:write": "python3 tests/_generate_maestro_routing_fixtures.py",
     "plugin-manifest:write": "node scripts/generate-plugin-manifest.mjs",
@@ -64,7 +66,7 @@
     "test:gemini-bundling": "python3 tests/test-gemini-skill-bundling.py",
     "test:cursor-kiro-notices": "node tests/export-cursor-kiro-skill-notice.test.mjs",
     "test:fuzz": "node tests/fuzz-properties.test.mjs",
-    "validate": "npm run validate:catalog && npm run validate:aws && npm run manifest:check && npm run validate:allowed-tools && npm run validate:skill-schema && npm run validate:agent-schema && npm run validate:links && npm run validate:asset-integrity && npm run validate:mcp-trust-matrix && npm run validate:no-lifecycle-scripts && npm run validate:promotion-gatekeeper && npm run validate:install-coverage && npm run validate:maestro-routing && npm run validate:plugin-manifest && npm run validate:kiro-powers && npm run validate:multi-harness-marketplace && npm run validate:codex-marketplace",
+    "validate": "npm run validate:catalog && npm run validate:aws && npm run manifest:check && npm run validate:allowed-tools && npm run validate:skill-schema && npm run validate:agent-schema && npm run validate:links && npm run validate:asset-integrity && npm run validate:mcp-trust-matrix && npm run validate:no-lifecycle-scripts && npm run validate:promotion-gatekeeper && npm run validate:install-coverage && npm run validate:maestro-routing && npm run validate:plugin-manifest && npm run validate:kiro-powers && npm run validate:multi-harness-marketplace && npm run validate:codex-marketplace && npm run validate:finops-fixtures",
     "release:sbom": "command -v syft >/dev/null 2>&1 && syft scan dir:. -o spdx-json=sbom.spdx.json || echo 'syft not installed; SBOM is generated in CI by anchore/sbom-action'",
     "lint:md": "npx --yes markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#.git\" \"#.code-review-graph\" \"#CHANGELOG.md\"",
     "lint:spell": "codespell",
@@ -75,9 +77,9 @@
     "@semantic-release/commit-analyzer": "13.0.1",
     "@semantic-release/exec": "7.1.0",
     "@semantic-release/git": "10.0.1",
-    "@semantic-release/github": "12.0.6",
+    "@semantic-release/github": "12.0.8",
     "@semantic-release/npm": "13.1.5",
-    "@semantic-release/release-notes-generator": "14.1.0",
+    "@semantic-release/release-notes-generator": "14.1.1",
     "conventional-changelog-conventionalcommits": "9.3.1",
     "fast-check": "^4.7.0",
     "semantic-release": "25.0.3"

package/plugins/vanguard-frontier-agentic/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "vanguard-frontier-agentic",
-  "version": "1.8.0",
+  "version": "2.0.0",
   "description": "Curated marketplace for cloud and zero-trust AI workflows. 331 agents, 286 skills, and rules across AWS, Azure, OCI, GCP, Alibaba Cloud, Huawei Cloud, Kubernetes, and Terraform.",
   "author": {
     "name": "Raishin",

package/powers/vanguard-kubernetes/POWER.md

@@ -40,7 +40,7 @@ Live-guard agents enforce approval, target confirmation, evidence capture, and r
 
 ## Where the agents live
 
-Agent specs and adapters are part of the [Vanguard Frontier Agentic](https://github.com/Raishin/vanguard-frontier-agentic) marketplace. For this provider, see `agents/kubernetes/` in that repository. All 15 agents in this provider ship a Kiro adapter (`harnesses/kiro-ide.agent.md`, `kiro-cli.agent.json`).
+Agent specs and adapters are part of the [Vanguard Frontier Agentic](https://github.com/Raishin/vanguard-frontier-agentic) marketplace. For this provider, see `agents/kubernetes/` in that repository. All 16 agents in this provider ship a Kiro adapter (`harnesses/kiro-ide.agent.md`, `kiro-cli.agent.json`).
 
 ## Companion install paths
 

package/scripts/export-marketplace-agents.mjs

@@ -4,6 +4,7 @@ import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
+import { parseArgs as utilParseArgs } from "node:util";
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -119,8 +120,13 @@ Selectors (mutually exclusive):
 
   --provider <p> --role <r>  → narrow the role to agents whose provider == p.
   --provider <p>             → standalone; equivalent to --all filtered to p.
-  --dry-run            Print the export plan as "export agent: <id> [provider=<p>]"
-                       lines without copying any files. Exit 0 on success.
+
+Options:
+  --repo <path>          Target repository path (default: cwd).
+  --force                Overwrite existing files without prompting.
+  --list-providers        List all providers with agent counts; then exit.
+  --dry-run              Print the export plan without writing files.
+  --no-skills            Skip companion skill bundling.
 
 Companion skills:
   By default, when --platform supports skill bundling (claude-code, copilot, gemini),
@@ -137,8 +143,8 @@ Examples:
   vfa-export-agents --platform claude-code --agents azure-cosmosdb-platform-operator-agent
   vfa-export-agents --platform claude-code --role cloud-security-engineer
   vfa-export-agents --platform claude-code --role cloud-security-engineer --provider azure
-  vfa-export-agents --platform claude-code --provider nvidia
-  vfa-export-agents --platform claude-code --provider nvidia --dry-run
+  vfa-export-agents --platform claude-code --provider aws
+  vfa-export-agents --platform claude-code --provider azure --dry-run
   vfa-export-agents --platform claude-code --all --no-skills --repo /path/to/project
   vfa-export-agents --platform kiro --agents azure-cosmosdb-platform-operator-agent --repo ../consumer-repo
   vfa-export-agents --platform copilot --all --repo /path/to/project --force
@@ -148,79 +154,71 @@ Examples:
 }
 
 function parseArgs(argv) {
-  const args = {
-    repo: process.cwd(),
-    force: false,
-    list: false,
-    listRoles: false,
-    listProviders: false,
-    all: false,
-    dryRun: false,
-    agents: [],
-    platform: null,
-    role: null,
-    provider: null,
-    noSkills: false,
-  };
+  // Use Node.js built-in util.parseArgs (stable since v18.3, available in v22):
+  // - handles --key=value inline form natively
+  // - returns null-prototype values object (prototype pollution safe)
+  // - strict mode throws a real Error for unknown flags (not a silent usage() exit)
+  let parsed;
+  try {
+    parsed = utilParseArgs({
+      args: argv,
+      strict: true,
+      allowPositionals: false,
+      options: {
+        help:             { type: "boolean", short: "h", default: false },
+        list:             { type: "boolean", default: false },
+        "list-roles":     { type: "boolean", default: false },
+        "list-providers": { type: "boolean", default: false },
+        force:            { type: "boolean", default: false },
+        all:              { type: "boolean", default: false },
+        "dry-run":        { type: "boolean", default: false },
+        "no-skills":      { type: "boolean", default: false },
+        platform:         { type: "string" },
+        role:             { type: "string" },
+        provider:         { type: "string" },
+        repo:             { type: "string" },
+        agents:           { type: "string" },
+      },
+    });
+  } catch (err) {
+    // Unknown or mistyped flags surface here with a clear message.
+    console.error(err.message);
+    usage(1);
+  }
 
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg === "--help" || arg === "-h") usage(0);
-    if (arg === "--list") {
-      args.list = true;
-      continue;
-    }
-    if (arg === "--list-roles") {
-      args.listRoles = true;
-      continue;
-    }
-    if (arg === "--list-providers") {
-      args.listProviders = true;
-      continue;
-    }
-    if (arg === "--force") {
-      args.force = true;
-      continue;
-    }
-    if (arg === "--all") {
-      args.all = true;
-      continue;
-    }
-    if (arg === "--dry-run") {
-      args.dryRun = true;
-      continue;
-    }
-    if (arg === "--no-skills") {
-      args.noSkills = true;
-      continue;
-    }
-    if (arg === "--repo") {
-      args.repo = path.resolve(argv[++i] ?? "");
-      continue;
-    }
-    if (arg === "--platform") {
-      args.platform = argv[++i] ?? "";
-      continue;
-    }
-    if (arg === "--agents") {
-      args.agents = (argv[++i] ?? "")
-        .split(",")
-        .map((value) => value.trim())
-        .filter(Boolean);
-      continue;
-    }
-    if (arg === "--role") {
-      args.role = argv[++i] ?? "";
-      continue;
-    }
-    if (arg === "--provider") {
-      args.provider = argv[++i] ?? "";
-      continue;
+  const v = parsed.values;
+  if (v.help) usage(0);
+
+  // Validate --provider: empty string and whitespace-only are rejected.
+  // unicode zero-width chars (e.g. U+200B) pass trim() in some engines so
+  // the downstream format regex /^[a-z0-9][a-z0-9-]*$/ acts as a second gate.
+  const providerRaw = v.provider ?? null;
+  if (providerRaw !== null) {
+    const provVal = providerRaw.trim();
+    if (!provVal) {
+      throw new Error(
+        "--provider requires a non-empty value. " +
+        "Run 'vfa-export-agents --list-providers' for valid options."
+      );
     }
-    usage(1);
   }
 
-  return args;
+  return {
+    repo:          v.repo ? path.resolve(v.repo) : process.cwd(),
+    force:         v.force ?? false,
+    list:          v.list ?? false,
+    listRoles:     v["list-roles"] ?? false,
+    listProviders: v["list-providers"] ?? false,
+    all:           v.all ?? false,
+    dryRun:        v["dry-run"] ?? false,
+    noSkills:      v["no-skills"] ?? false,
+    platform:      v.platform ?? null,
+    role:          v.role ?? null,
+    provider:      providerRaw !== null ? providerRaw.trim() : null,
+    agents:        v.agents
+      ? v.agents.split(",").map((s) => s.trim()).filter(Boolean)
+      : [],
+  };
 }
 
 function walk(dir, matcher, results = []) {
@@ -274,6 +272,16 @@ function ensurePlatform(platform) {
 }
 
 function assertWithin(parent, child, label) {
+  // Lexical containment check — path.resolve() is purely string-based and does
+  // NOT follow symlinks. This guards against traversal strings (../../) and
+  // metadata.json with absolute paths outside the repo.
+  //
+  // Residual TOCTOU: if an adversary races to create a symlink at `child`
+  // AFTER this check but BEFORE the actual write, the symlink target would be
+  // written to. copyFile()/copySkillTree() use lstatSync on source AND
+  // destination to detect pre-existing symlinks, which closes the window for
+  // the common case. A fully TOCTOU-proof solution requires O_NOFOLLOW at the
+  // kernel level, which is not exposed by Node.js fs APIs.
   const resolvedParent = path.resolve(parent);
   const resolvedChild = path.resolve(child);
   const sep = path.sep;
@@ -297,7 +305,7 @@ function loadSkills() {
       if (!skill.isDirectory()) continue;
       const skillDir = path.join(providerDir, skill.name);
       if (fs.existsSync(path.join(skillDir, "SKILL.md"))) {
-        byName.set(skill.name, skillDir);
+        byName.set(skill.name, { dir: skillDir, provider: provider.name });
       }
     }
   }
@@ -325,20 +333,38 @@ function copySkillTree(sourceDir, destDir, force) {
   }
 }
 
-function resolveCompanionSkills(selectedAgents, skillsByName, role, includeAll) {
+function resolveCompanionSkills(selectedAgents, skillsByName, role, includeAll, selectedProvider) {
   const skillNames = new Set();
   if (includeAll) {
-    for (const name of skillsByName.keys()) skillNames.add(name);
+    for (const [name, meta] of skillsByName.entries()) {
+      if (!selectedProvider || meta.provider === selectedProvider || meta.provider === "shared") {
+        skillNames.add(name);
+      }
+    }
   }
   if (role && Array.isArray(role.skills)) {
-    for (const id of role.skills) skillNames.add(id);
+    for (const id of role.skills) {
+      const meta = skillsByName.get(id);
+      // Exclude skills not found on disk — do not promote undefined through the
+      // provider gate (the old `!meta` branch made dry-run output lie about what
+      // would actually be written, masking catalog rot).
+      if (!meta) continue;
+      if (!selectedProvider || meta.provider === selectedProvider || meta.provider === "shared") {
+        skillNames.add(id);
+      }
+    }
   }
   const orphans = [];
   for (const agent of selectedAgents) {
     // Prefer explicit companion_skills if declared (even if empty — that means intentional no-pair)
     if (Array.isArray(agent.companion_skills)) {
       for (const skillId of agent.companion_skills) {
-        if (skillsByName.has(skillId)) skillNames.add(skillId);
+        const meta = skillsByName.get(skillId);
+        // Apply the same provider scope gate used for role.skills — prevents a
+        // cross-provider companion_skills declaration from leaking rival skills.
+        if (meta && (!selectedProvider || meta.provider === selectedProvider || meta.provider === "shared")) {
+          skillNames.add(skillId);
+        }
       }
       // companion_skills: [] is intentional no-pair — do NOT count as orphan
       continue;
@@ -347,7 +373,8 @@ function resolveCompanionSkills(selectedAgents, skillsByName, role, includeAll)
     const skillName = agent.id.endsWith("-agent")
       ? agent.id.slice(0, -"-agent".length)
       : agent.id;
-    if (skillsByName.has(skillName)) {
+    const meta = skillsByName.get(skillName);
+    if (meta && (!selectedProvider || meta.provider === selectedProvider || meta.provider === "shared")) {
       skillNames.add(skillName);
     } else if (!role) {
       orphans.push(agent.id);
@@ -361,8 +388,21 @@ function copyFile(source, destination, force) {
   if (sourceStat.isSymbolicLink()) {
     throw new Error(`Refusing to copy symbolic link as harness source: ${source}`);
   }
-  if (!force && fs.existsSync(destination)) {
-    throw new Error(`Refusing to overwrite existing file without --force: ${destination}`);
+  if (fs.existsSync(destination)) {
+    // Reject symlink destinations regardless of --force. A symlink at the
+    // destination would redirect the write outside the repo tree, bypassing
+    // assertWithin(). lstatSync does not follow the symlink — exactly what we
+    // want here to detect the link itself.
+    const destStat = fs.lstatSync(destination);
+    if (destStat.isSymbolicLink()) {
+      throw new Error(
+        `Refusing to write to symbolic link destination: ${destination}. ` +
+        `Remove the symlink and retry.`
+      );
+    }
+    if (!force) {
+      throw new Error(`Refusing to overwrite existing file without --force: ${destination}`);
+    }
   }
   fs.mkdirSync(path.dirname(destination), { recursive: true });
   fs.copyFileSync(source, destination);
@@ -533,7 +573,28 @@ function main() {
     for (const agent of selectedAgents) {
       console.log(`export agent: ${agent.id} [provider=${agent.provider}]`);
     }
-    process.stderr.write(`[vfa] --dry-run: ${selectedAgents.length} agent(s) planned, no files written.\n`);
+    const skillsDestRoot = SKILLS_PLATFORM_CONFIG[platform];
+    let dryRunSkillCount = 0;
+    if (!args.noSkills && skillsDestRoot) {
+      const skillsByName = loadSkills();
+      const includeAllSkills = args.all && !args.provider;
+      const { skillNames } = resolveCompanionSkills(
+        selectedAgents,
+        skillsByName,
+        selectedRole,
+        includeAllSkills,
+        args.provider ?? null
+      );
+      for (const skillName of skillNames) {
+        console.log(`export skill: ${skillName}`);
+        dryRunSkillCount += 1;
+      }
+    }
+    process.stderr.write(
+      `[vfa] --dry-run: ${selectedAgents.length} agent(s)` +
+      (dryRunSkillCount > 0 ? `, ${dryRunSkillCount} skill(s)` : "") +
+      ` planned, no files written.\n`
+    );
     return;
   }
 
@@ -581,11 +642,12 @@ function main() {
       selectedAgents,
       skillsByName,
       selectedRole,
-      includeAllSkills
+      includeAllSkills,
+      args.provider ?? null
     );
     let bundled = 0;
     for (const skillName of skillNames) {
-      const sourceDir = skillsByName.get(skillName);
+      const sourceDir = skillsByName.get(skillName)?.dir;
       if (!sourceDir) continue;
       const destDir = path.join(args.repo, skillsDestRoot, skillName);
       assertWithin(args.repo, destDir, "write skill destination");

package/scripts/generate-changelog-counts.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * Generate dynamic catalog counts for CHANGELOG.md and other versioning docs.
+ * Called by release-prepare.mjs to keep counts current across releases.
+ */
+
+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)), "..");
+
+// Count agents
+const agentDirs = fs.readdirSync(path.join(repoRoot, "agents"), { recursive: true });
+const agentCount = agentDirs.filter(f => String(f).endsWith("metadata.json")).length;
+
+// Count skills (on-disk SKILL.md files)
+const skillDirs = fs.readdirSync(path.join(repoRoot, "skills"), { recursive: true });
+const skillCount = skillDirs.filter(f => String(f).endsWith("SKILL.md")).length;
+
+// Count catalog providers (agents only, not skill-only dirs)
+const allProviders = new Set();
+for (const f of agentDirs) {
+  if (!String(f).endsWith("metadata.json")) continue;
+  const m = JSON.parse(fs.readFileSync(path.join(repoRoot, "agents", String(f)), "utf8"));
+  if (m.provider) allProviders.add(m.provider);
+}
+const providerCount = allProviders.size;
+
+// Count roles
+const roles = JSON.parse(fs.readFileSync(path.join(repoRoot, "catalog/install-roles.json"), "utf8"));
+const roleCount = Object.keys(roles.roles).length;
+
+console.log(`${agentCount} agents · ${skillCount} skills · ${providerCount} providers · ${roleCount} roles`);

package/scripts/release-prepare.mjs

@@ -7,21 +7,26 @@
  * tarball. Synchronizes every published artifact whose content depends on
  * `package.json.version` or on file hashes that include `package.json`:
  *
- *   1. .claude-plugin/plugin.json         — version-parity (validate:plugin-manifest)
- *   2. .cursor-plugin/plugin.json         — version-parity (validate:multi-harness-marketplace)
+ *   1. .claude-plugin/plugin.json              — version-parity (validate:plugin-manifest)
+ *   2. .cursor-plugin/plugin.json              — version-parity (validate:multi-harness-marketplace)
  *   3. plugins/vanguard-frontier-agentic/.codex-plugin/plugin.json
- *                                         — version-parity (validate:codex-marketplace)
- *   4. catalog/asset-integrity.json       — includes package.json sha256
+ *                                              — version-parity (validate:codex-marketplace)
+ *   4. .github/plugin/marketplace.json         — Copilot marketplace version field
+ *   5. SECURITY.md                             — "current published version" + supported-version table
+ *   6. catalog/asset-integrity.json            — includes package.json sha256
  *
  * Without this step the released tarball would ship plugin manifests whose
  * version diverges from `package.json` (breaks every harness's version-parity
  * gate) and an asset-integrity manifest whose package.json hash no longer
  * matches the released tree (breaks downstream attestation verification).
  *
+ * `package.json` is the single source of truth for the release version.
+ * No other file should hard-code a version string that this script can derive.
+ *
  * Idempotent: re-running on an already-synced tree is a no-op.
  */
 
-import { readFileSync, writeFileSync } from "node:fs";
+import { readFileSync, writeFileSync, readdirSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -44,6 +49,8 @@ const VERSION_PINNED_PLUGINS = [
   ".claude-plugin/plugin.json",
   ".cursor-plugin/plugin.json",
   "plugins/vanguard-frontier-agentic/.codex-plugin/plugin.json",
+  // Copilot marketplace manifest — version field only; content is manually curated.
+  ".github/plugin/marketplace.json",
 ];
 
 function syncPluginVersion(relPath) {
@@ -57,6 +64,82 @@ function syncPluginVersion(relPath) {
   return true;
 }
 
+// Sync the "current published version" banner and supported-version table in
+// SECURITY.md from package.json. Keeps the security policy credible without
+// requiring a manual edit on every release.
+function syncSecurityMd(nextVersion) {
+  const abs = join(REPO, "SECURITY.md");
+  let content = readFileSync(abs, "utf8");
+  const [major, minor] = nextVersion.split(".").map(Number);
+  const curr = `${major}.${minor}.x`;
+
+  // At a major-version boundary (X.0.0), the "previous minor" is the last
+  // minor of the previous major — which this script cannot know precisely.
+  // Use `(major-1).x` as a conservative label and `< X.0.0` as the floor.
+  // A human must verify the exact prior-major support window on X.0.0 releases.
+  const isMajorBump = minor === 0;
+  const prev = isMajorBump ? `${major - 1}.x` : `${major}.${minor - 1}.x`;
+  const floor = isMajorBump ? `${major}.0.0` : `${major}.${minor - 1}.0`;
+
+  const updated = content
+    .replace(
+      /current published version: \*\*[\d.]+\*\*/,
+      `current published version: **${nextVersion}**`
+    )
+    .replace(
+      /\| \d+\.\d+\.x\s+\| Yes — current minor \|[^\n]*/,
+      `| ${curr.padEnd(13)} | Yes — current minor |`
+    )
+    .replace(
+      /\| [\d.x]+\s+\| Yes — previous minor \|[^\n]*/,
+      `| ${prev.padEnd(13)} | Yes — previous minor |`
+    )
+    .replace(
+      /\| < [\d.]+\s+\| No[^\n]*/,
+      `| < ${floor.padEnd(10)} | No                 |`
+    );
+
+  if (updated === content) return false;
+  writeFileSync(abs, updated, "utf8");
+  return true;
+}
+
+function syncChangelogCounts(nextVersion) {
+  // Update counts in CHANGELOG.md from the live catalog to prevent stale hardcoded values.
+  // Pattern: > _Provider-scoped exports... 334 agents · 335 skills · 26 providers · 16 roles_
+  const abs = join(REPO, "CHANGELOG.md");
+  let content = readFileSync(abs, "utf8");
+
+  // Count agents, skills, providers, roles from live catalog
+  const agentDirs = readdirSync(join(REPO, "agents"), { recursive: true });
+  const agentCount = agentDirs.filter(f => String(f).endsWith("metadata.json")).length;
+
+  const skillDirs = readdirSync(join(REPO, "skills"), { recursive: true });
+  const skillCount = skillDirs.filter(f => String(f).endsWith("SKILL.md")).length;
+
+  const allProviders = new Set();
+  for (const f of agentDirs) {
+    if (!String(f).endsWith("metadata.json")) continue;
+    const m = JSON.parse(readFileSync(join(REPO, "agents", String(f)), "utf8"));
+    if (m.provider) allProviders.add(m.provider);
+  }
+  const providerCount = allProviders.size;
+
+  const roles = JSON.parse(readFileSync(join(REPO, "catalog/install-roles.json"), "utf8"));
+  const roleCount = Object.keys(roles.roles).length;
+
+  // Replace counts in all version blurb lines
+  const versionRegex = /(\> _[^.]+\. )\d+ agents · \d+ skills · \d+ providers · \d+ roles/g;
+  const updated = content.replace(
+    versionRegex,
+    `$1${agentCount} agents · ${skillCount} skills · ${providerCount} providers · ${roleCount} roles`
+  );
+
+  if (updated === content) return false;
+  writeFileSync(abs, updated, "utf8");
+  return true;
+}
+
 function regenerate(cmd, args) {
   const result = spawnSync(cmd, args, { cwd: REPO, stdio: "inherit" });
   if (result.status !== 0) {
@@ -74,6 +157,15 @@ for (const rel of VERSION_PINNED_PLUGINS) {
   }
 }
 
+if (syncSecurityMd(NEXT_VERSION)) {
+  console.log("[release-prepare] updated SECURITY.md");
+  touched += 1;
+}
+
+if (syncChangelogCounts(NEXT_VERSION)) {
+  console.log("[release-prepare] updated CHANGELOG.md counts");
+}
+
 // Re-run the Claude Code + Cursor manifest generators so any other
 // catalog-derived fields (agents[] list, etc.) stay in sync alongside
 // the version bump.

package/skills/finops/README.md

@@ -5,26 +5,77 @@
   <span style="font-size:3.5em">💰</span>
 </p>
 
+> ⚠️ **ALPHA RELEASE** — All FinOps skills are currently at `lifecycle: experimental`. Use at your own risk in pre-production environments only. [Board readiness memo](../../docs/strategy/finops-maestro-board-memo.md) documents known limitations and 30-day diligence requirements.
+
 This folder contains cross-cloud FinOps skills curated for this marketplace.
 
 ## Local marketplace portfolio
 
-This folder contains **1** local FinOps skill:
+This folder contains **7** local FinOps skills (all alpha):
 
-- `finops-cloud-price-advisor`
+| Skill | Purpose | Lifecycle | Tools |
+|---|---|---|---|
+| `finops-maestro` | Route FinOps tasks to the narrowest specialist or parallel team (max 4) | **experimental** | Agent Skill Read Grep Glob |
+| `finops-cloud-price-advisor` | Live public pricing across AWS, Azure, OCI, Scaleway, Gandi, Alibaba, Tencent, Hetzner, Contabo, Ionos, OVHcloud | **experimental** | Read Grep Glob WebFetch |
+| `fetch-foundation-model-pricing` | Live per-token, per-image, per-GPU-hour pricing across Anthropic, OpenAI, Google, Bedrock, Azure OpenAI, OCI, and Vertex | **experimental** | Read Grep Glob WebFetch |
+| `kubernetes-allocation-report` | OpenCost-compatible namespace/pod/workload cost allocation mapped to FOCUS v1.2 columns | **experimental** | Read Grep Glob WebFetch |
+| `rightsize-recommendation` | Pod request/limit recommendations from user-supplied p50/p95/p99 metrics; Karpenter consolidation eligibility | **experimental** | Read Grep Glob |
+| `carbon-cost-pair` | Pair $ values with kgCO2e by region and service category for CSRD/SEC climate disclosure | **experimental** | Read Grep Glob WebFetch |
+| `focus-spec-normalizer` | Normalize vendor bills (AWS CUR, Azure Cost Management, GCP Billing Export, OCI) into FOCUS v1.2 columns | **experimental** | Read Grep Glob |
 
 ## Portfolio posture
 
-Cross-cloud FinOps skills for live price lookup, cost estimation, provider comparison, and budget governance.
+Cross-cloud, harness-portable FinOps skills covering AI workload economics, Kubernetes rightsizing, cross-cloud price advisory, FOCUS-spec normalization, and carbon-cost pairing.
 
 These skills are intentionally conservative:
 
-- fetch prices from public unauthenticated APIs only — no billing credentials required
+- fetch prices from public unauthenticated APIs only — no billing credentials, kubeconfig, bearer tokens, or tenant data accepted
 - always distinguish on-demand list price from effective price (reserved instances, savings plans, committed use discounts not included by default)
-- prefer live API lookups over cached or memory-based price estimates — cloud prices change frequently
-- when comparing providers, normalize compute specs (vCPU, RAM, storage type) before comparing price
-- flag GPU and accelerated compute costs explicitly — they dominate bills and are often overlooked
+- prefer live API lookups over cached or memory-based price estimates — foundation-model and cloud prices change frequently
+- when comparing providers, normalize compute specs (vCPU, RAM, GPU SKU, storage type) before comparing price
+- flag GPU and accelerated compute costs explicitly — they dominate AI workload bills
+- label every numeric output: `live-price` / `live-evidence` / `documentation-based` / `assumed` / `excluded`
+- emit FOCUS v1.2 column mappings where applicable — vendor-column adapters are explicit, not assumed
+
+### Provider coverage matrix
+
+| Category | Providers | Skill | Status |
+|---|---|---|---|
+| **Foundation models** | Anthropic, OpenAI, Google, AWS Bedrock, Azure OpenAI, OCI Generative AI, Vertex | `fetch-foundation-model-pricing` | experimental |
+| **Cloud compute (on-demand)** | AWS, Azure, OCI | `finops-cloud-price-advisor` | experimental |
+| **Cloud compute (regional)** | Scaleway (EU), Gandi (EU), Alibaba Cloud (CN/APAC), Tencent Cloud (CN/APAC), Hetzner (EU), Contabo (EU), Ionos (EU), OVHcloud (EU) | `finops-cloud-price-advisor` | experimental |
+| **Kubernetes cost** | EKS, AKS, GKE, OKE (vendor-agnostic allocation) | `kubernetes-allocation-report` + `rightsize-recommendation` | experimental |
+| **Bill normalization** | AWS CUR, Azure Cost Management, GCP Billing Export, OCI Cost Analysis | `focus-spec-normalizer` | experimental |
+| **Carbon tracking** | AWS, Azure, GCP, OCI | `carbon-cost-pair` | experimental |
+
+## 🧭 Routing taxonomy
+
+See [agents/finops/README.md](../agents/README.md) for the complete 120+ keyword taxonomy used by `finops-maestro` to classify and dispatch tasks to the right specialist skill or agent.
+
+## ⚠️ Known limitations and disclaimers
+
+**Alpha status**: These skills support pre-production research and estimation use cases. Production deployment requires:
+1. Signed design-partner SOW with cost verification clause
+2. AT-C 215 AUP report from Big 4 accounting firm documenting hard savings
+3. SOC 2 Type II observation (≥150 days) on infrastructure
+4. FOCUS v1.2 column-mapping audit by compliance reviewer
+
+**Data freshness**: Cloud and foundation-model prices are live-fetched on every invocation. Pricing APIs are public and unauthenticated; no caching across sessions. If a pricing API is unavailable, the skill returns a documented-based fallback with a timestamp.
+
+**Scope limitations**:
+- Reserved instances, savings plans, committed use discounts require separate calculation (not included in base list-price estimates)
+- Volume discounts (multi-year, enterprise agreements) not modeled
+- Spot/preemptible pricing not included (separate query required)
+- Custom pricing (e.g., negotiated cloud contracts) not discoverable
+
+**Accuracy**: Cost estimates from these skills are **indicative only**. Use them for:
+- Budget planning (±20% accuracy acceptable)
+- Comparative analysis (which cloud is cheaper?)
+- Anomaly detection (which workload got expensive?)
 
-Providers covered: 🟧 AWS Price List API · 🟦 Azure Retail Prices API · 🟥 OCI public pricing API
+Do not use for:
+- Chargeback / cost allocation without human review
+- SLA-level cost forecasting
+- Contractual billing disputes
 
-Run `npm run validate` after changing cataloged FinOps skills.
+**See also**: [Board readiness memo Section 8](../../docs/strategy/finops-maestro-board-memo.md#8-risk-catalog) enumerates all 21 operational risks with contractual mitigations.