@raishin/vanguard-frontier-agentic 1.9.0 → 2.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raishin/vanguard-frontier-agentic",
-  "version": "1.9.0",
+  "version": "2.0.1",
   "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",

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

@@ -1,6 +1,6 @@
 {
   "name": "vanguard-frontier-agentic",
-  "version": "1.9.0",
+  "version": "2.0.1",
   "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/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/marketing/ai-advertising-targeting-fairness-review/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: ai-advertising-targeting-fairness-review
+description: Use this skill when reviewing ad-platform audience targeting configurations and declared AI feature usage for protected-class discrimination risk. Trigger when a user provides a Meta Ads Manager audience definition, Google Ads targeting layer export, DSP deal config, or any ad platform audience spec annotated with AI features enabled (Advantage+ Audience, broad match, automated bidding, lookalike seeds). Use when a campaign is in housing, credit, employment, or insurance verticals, or when automated bidding or AI audience expansion is active on any campaign reaching the US or EU and the user needs to assess Fair Housing Act, ECOA, or EU AI Act Article 5 exposure.
+allowed-tools: Read Grep Glob
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-05-17"
+  category: ai
+  lifecycle: experimental
+---
+
+# AI Advertising Targeting Fairness Review
+
+## Purpose
+This skill reviews ad-platform audience targeting configurations and declared AI feature usage for protected-class discrimination risk under the Fair Housing Act (42 U.S.C. §3604), the Equal Credit Opportunity Act (ECOA), and EU AI Act Article 5. Ad platforms increasingly offer AI-driven audience expansion features — Meta Advantage+ Audience, Google broad match and Performance Max, DSP algorithmic deal targeting — that optimize delivery based on historical conversion patterns. When historical converters skew along protected-class lines (race, sex, age, national origin, familial status, disability, religion), algorithmic optimization propagates that skew without explicit intent. The review examines declared AI feature usage, audience seed composition, interest-segment proxy risk, and the absence of protected-category exclusion declarations on special-category campaigns before the configuration ships.
+
+## Lean operating rules
+- Treat Meta Advantage+ Audience enabled on a housing, credit, employment, or insurance campaign with no declared protected-category exclusions as HIGH — the system expands targeting beyond the declared audience using engagement signals that may correlate with race, sex, or national origin.
+- Treat interest-based segments that function as proxies for health conditions, religion, national origin, or familial status used on an insurance or financial-services campaign as HIGH — proxy targeting on protected classes is substantively equivalent to explicit targeting under FHA and ECOA case law.
+- Treat automated bidding (Target CPA, Target ROAS, Smart Bidding) optimizing a credit-offer, rental, or employment campaign on lookalike audiences seeded from historical converters as HIGH — disparate impact is propagated algorithmically when the seed population reflects historical discriminatory patterns.
+- Treat any AI-generated audience expansion (broad match, Performance Max audience signals, DSP algorithmic reach extension) active on a special-category campaign (housing, credit, employment, insurance) with no fairness audit trail as HIGH — the optimization objective does not include disparate-impact minimization.
+- Treat geofencing or geographic exclusion zones that closely follow racially or ethnically concentrated neighborhood boundaries on a housing or credit campaign as HIGH — geographic redlining is prohibited under FHA regardless of whether intent is declared.
+- Treat the absence of a Special Ad Category declaration on a Meta campaign reasonably classifiable as housing, employment, or credit as HIGH — the declaration unlocks mandatory fairness restrictions; omitting it circumvents them.
+- Flag automated bidding that optimizes on a conversion event defined as a past purchase or application when the historical converter population is not documented for demographic representativeness as MEDIUM — undocumented seed bias is a disparate-impact risk even when not yet proven.
+- Flag interest segments that include health-condition or medication-related categories on campaigns not in the healthcare vertical as MEDIUM — health proxies reach users based on inferred sensitive characteristics.
+- Flag AI feature disclosures that are absent or vague (e.g., "algorithmic optimization enabled" with no named feature, no version, no opt-out path) as MEDIUM — EU AI Act Article 13 and FTC guidance require meaningful transparency.
+- Do not recommend disabling AI features without naming the performance impact and the manual alternative that preserves reach.
+- Label every finding with evidence basis: audience spec provided, AI feature declaration provided, documentation-based, or inference from missing config.
+
+## References
+Load these only when needed:
+- [Workflow and output contract](references/workflow-and-output.md) — use when executing the full review or formatting the final answer.
+
+## Response minimum
+Return, at minimum:
+- AI feature inventory (named features enabled per campaign, evidence basis)
+- Special-category campaign detection (housing, credit, employment, insurance)
+- Protected-class proxy segment assessment (interest segments, lookalike seeds)
+- Algorithmic disparate-impact assessment (bidding, audience expansion)
+- Special Ad Category declaration check (Meta) or equivalent platform declaration
+- Severity-labelled finding list (critical / high / medium / low)
+- Safe next actions

package/skills/marketing/ai-advertising-targeting-fairness-review/metadata.json

@@ -0,0 +1,21 @@
+{
+  "id": "ai-advertising-targeting-fairness-review",
+  "name": "AI Advertising Targeting Fairness Review",
+  "type": "skill",
+  "provider": "marketing",
+  "harnesses": ["codex", "claude-code", "cursor", "gemini", "kiro", "other"],
+  "summary": "Review ad-platform audience targeting configurations and AI feature usage for protected-class discrimination risk under Fair Housing Act, ECOA, and EU AI Act Article 5 — proxy segments, algorithmic disparate impact, and missing Special Ad Category declarations.",
+  "source_type": "original",
+  "official_docs": [
+    "https://www.ftc.gov/business-guidance/blog/2023/02/ftcs-ai-related-enforcement-actions",
+    "https://www.hud.gov/program_offices/fair_housing_equal_opp/fair_housing_act_overview",
+    "https://www.consumerfinance.gov/about-us/blog/cfpb-issues-guidance-on-credit-denials-by-lenders-using-artificial-intelligence/",
+    "https://digital-strategy.ec.europa.eu/en/policies/regulatory-framework-ai",
+    "https://www.federalregister.gov/documents/2023/07/13/2023-14625/civil-rights-principles-for-the-use-of-artificial-intelligence"
+  ],
+  "security_notes": "Ad-platform AI features that optimize on historical converter populations can propagate protected-class disparate impact without explicit discriminatory intent. Review works from sanitized audience spec exports and declared AI feature annotations only; never request live campaign credentials, ad-account access tokens, or real user audience data.",
+  "last_verified": "2026-05-17",
+  "path": "skills/marketing/ai-advertising-targeting-fairness-review",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}