@event4u/agent-config 2.23.0 → 2.25.0

package/scripts/ai-video/stitch.sh

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# stitch.sh — ffmpeg-based clip concatenator for /video:* pipelines.
+#
+# Drives the cut from <project>/manifest.json (an ordered array of
+# `{scene_id, clip_path, audio_embedded, audio_path?, duration}`).
+# Pass-through for audio_embedded=true; ffmpeg mux for audio_embedded
+# =false; operator-supplied bed for video-only clips.
+#
+# Usage:
+#   stitch.sh <manifest.json> <output.mp4>
+#               [--skip-scene <id> ...]
+#               [--abort-on-missing | --continue]
+#               [--crossfade <seconds>]
+#
+# Failure semantics:
+#   - Missing clip → fail loud with scene_id and re-render hint
+#     unless --skip-scene <id> drops the clip from the cut or
+#     --continue is passed (the dropped scenes are written to stderr).
+#   - --abort-on-missing is the default.
+#   - Adapter-failure rollback contract: a failed adapter writes
+#     <project>/scenes/<id>/error.json; stitch.sh checks for that
+#     file alongside the clip and surfaces it instead of an opaque
+#     ffmpeg error.
+
+set -euo pipefail
+
+# shellcheck source=lib/adapter-common.sh
+. "$(dirname "$0")/lib/adapter-common.sh"
+
+aiv_require_cmd jq
+
+DRYRUN="${AIV_DRYRUN:-true}"
+case "${DRYRUN}" in
+  false|FALSE|0|no|NO) DRYRUN_FLAG=0 ;;
+  *) DRYRUN_FLAG=1 ;;
+esac
+[ "${DRYRUN_FLAG}" -eq 0 ] && aiv_require_cmd ffmpeg
+
+MANIFEST="${1:-}"
+OUTPUT="${2:-}"
+[ -n "${MANIFEST}" ] && [ -n "${OUTPUT}" ] \
+  || aiv_die 2 "usage: stitch.sh <manifest.json> <output.mp4> [--skip-scene <id>] [--abort-on-missing|--continue] [--crossfade <s>]"
+[ -r "${MANIFEST}" ] || aiv_die 2 "manifest not readable: ${MANIFEST}"
+shift 2 || true
+
+SKIP_IDS=""
+MISSING_POLICY="abort"
+CROSSFADE=""
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --skip-scene) SKIP_IDS="${SKIP_IDS} ${2:-}"; shift 2 ;;
+    --abort-on-missing) MISSING_POLICY="abort"; shift ;;
+    --continue) MISSING_POLICY="continue"; shift ;;
+    --crossfade) CROSSFADE="${2:-}"; shift 2 ;;
+    *) aiv_die 2 "stitch.sh: unknown flag '$1'" ;;
+  esac
+done
+
+skip_match() {
+  local id="$1" s
+  for s in ${SKIP_IDS}; do
+    [ "${s}" = "${id}" ] && return 0
+  done
+  return 1
+}
+
+PROJECT_DIR="$(cd "$(dirname "${MANIFEST}")" && pwd)"
+WORK_DIR="$(mktemp -d -t aiv-stitch-XXXXXX)"
+trap 'rm -rf "${WORK_DIR}"' EXIT
+CONCAT_LIST="${WORK_DIR}/concat.txt"
+: > "${CONCAT_LIST}"
+
+# Accept both bare-array manifests and the documented object shape
+# (`{ "scenes": [...] }`). Field names tolerate the legacy
+# `scene_id` / `clip_path` keys and the example `id` / `expected_clip`.
+SCENES_JQ='if type == "array" then .[] else .scenes[] end'
+
+count=0
+missing=0
+plan=""
+while IFS= read -r row; do
+  [ -n "${row}" ] || continue
+  scene_id="$(printf '%s' "${row}" | jq -r '.scene_id // .id')"
+  clip_path="$(printf '%s' "${row}" | jq -r '.clip_path // .expected_clip')"
+  audio_embedded="$(printf '%s' "${row}" | jq -r '.audio_embedded // false')"
+  audio_path="$(printf '%s' "${row}" | jq -r '.audio_path // empty')"
+
+  case "${clip_path}" in
+    /*) ;;
+    *) clip_path="${PROJECT_DIR}/${clip_path}" ;;
+  esac
+
+  if skip_match "${scene_id}"; then
+    printf 'stitch: skip scene=%s (operator --skip-scene)\n' "${scene_id}" >&2
+    continue
+  fi
+
+  if [ "${DRYRUN_FLAG}" -eq 1 ]; then
+    plan="${plan}${scene_id}\taudio_embedded=${audio_embedded}\t${clip_path}\n"
+    count=$((count + 1))
+    continue
+  fi
+
+  if [ ! -f "${clip_path}" ]; then
+    err_json="${PROJECT_DIR}/scenes/${scene_id}/error.json"
+    if [ -f "${err_json}" ]; then
+      printf 'stitch: scene=%s adapter-error: ' "${scene_id}" >&2
+      jq -r '"adapter=\(.adapter) exit=\(.exit_code) user_action=\(.user_action)"' "${err_json}" >&2
+    fi
+    if [ "${MISSING_POLICY}" = "continue" ]; then
+      printf 'stitch: continue past missing scene=%s clip=%s (re-render or --skip-scene next time)\n' \
+        "${scene_id}" "${clip_path}" >&2
+      missing=$((missing + 1))
+      continue
+    fi
+    aiv_die 7 "missing clip for scene=${scene_id} at ${clip_path} (re-render the scene, pass --skip-scene ${scene_id}, or use --continue)"
+  fi
+
+  # For clips without embedded audio that ship a sibling track, mux
+  # via ffmpeg into a tmp file before concat. Pure pass-through for
+  # the embedded-audio case.
+  if [ "${audio_embedded}" = "false" ] && [ -n "${audio_path}" ] && [ -f "${audio_path}" ]; then
+    muxed="${WORK_DIR}/${scene_id}.mp4"
+    ffmpeg -loglevel error -y -i "${clip_path}" -i "${audio_path}" \
+      -c:v copy -c:a aac -shortest "${muxed}" >/dev/null \
+      || aiv_die 8 "ffmpeg mux failed for scene=${scene_id}"
+    printf "file '%s'\n" "${muxed}" >> "${CONCAT_LIST}"
+  else
+    printf "file '%s'\n" "${clip_path}" >> "${CONCAT_LIST}"
+  fi
+  count=$((count + 1))
+done <<EOF
+$(jq -c "${SCENES_JQ}" "${MANIFEST}")
+EOF
+
+[ "${count}" -gt 0 ] || aiv_die 7 "stitch: no usable clips after manifest scan (missing=${missing}, skipped via --skip-scene)"
+
+if [ "${DRYRUN_FLAG}" -eq 1 ]; then
+  printf 'stitch: dry-run plan (output=%s, scenes=%d):\n' "${OUTPUT}" "${count}" >&2
+  printf '%b' "${plan}" >&2
+  printf '{"output":"%s","scenes":%d,"missing":0,"dry_run":true}\n' "${OUTPUT}" "${count}"
+  exit 0
+fi
+
+if [ -n "${CROSSFADE}" ]; then
+  printf 'stitch: crossfade=%ss requested — passing through ffmpeg xfade filter not yet implemented (concat path used)\n' \
+    "${CROSSFADE}" >&2
+fi
+
+ffmpeg -loglevel error -y -f concat -safe 0 -i "${CONCAT_LIST}" \
+  -c copy "${OUTPUT}" >/dev/null \
+  || aiv_die 8 "ffmpeg concat failed (manifest=${MANIFEST}, output=${OUTPUT})"
+
+printf '{"output":"%s","scenes":%d,"missing":%d}\n' "${OUTPUT}" "${count}" "${missing}"

package/scripts/ai-video/test-pipeline.sh

@@ -0,0 +1,169 @@
+#!/usr/bin/env bash
+# test-pipeline.sh — offline smoke test for /video:* against
+# agents/ai-video/examples/banana-arc/. Dry-run only; no network.
+#
+# Asserts (per agents/roadmaps/ai-video-pipeline.md Phase 6 Step 3):
+#   1. parse-blueprint.sh output matches the committed expected.json
+#      per scene (3 scenes, 3 tiers).
+#   2. character.json descriptor tokens (silhouette, palette, wardrobe,
+#      prop) appear verbatim in each scene's prompt.subject — the
+#      load-bearing character-lock substring assertion.
+#   3. audio.* branching is correct: scene 2 → enable_native_audio=true,
+#      scenes 1+3 → false.
+#   4. native-audio-capable adapter (gemini-veo) advertises capability
+#      audio=native; non-audio adapter (openai-images) advertises
+#      audio=none; stitch.sh sees audio_embedded per scene.
+#   5. stitch.sh dry-run returns the committed manifest's stitch_output
+#      path without invoking ffmpeg or any network.
+#   6. visual regression: each scene's locked.png is non-empty + has
+#      PNG magic; pairwise NCC ≥ 0.95 when `compare` is available.
+#      When unavailable, asserts byte-identity (the three frames are
+#      committed identical for the offline path).
+#
+# Exit 0 = all assertions pass; 1 = at least one failure (counted +
+# summarized at the end).
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+PROJECT="$ROOT/agents/ai-video/examples/banana-arc"
+
+PASS=0
+FAIL=0
+FAILS=""
+
+ok()   { PASS=$((PASS+1)); printf '  ✅  %s\n' "$1"; }
+fail() { FAIL=$((FAIL+1)); FAILS="$FAILS\n  ❌  $1"; printf '  ❌  %s\n' "$1"; }
+
+require() {
+  if command -v "$1" >/dev/null 2>&1; then return 0; fi
+  fail "required tool missing: $1"
+  return 1
+}
+
+require jq || exit 1
+
+printf '\n== test-pipeline.sh — banana-arc golden run (offline) ==\n\n'
+
+# ---------------------------------------------------------------- 1
+printf '[1/6] parse-blueprint vs. expected.json\n'
+SCENES="01-simple 02-dialogue-native-audio 03-edge-duration"
+for s in $SCENES; do
+  actual="$(bash "$ROOT/scripts/ai-video/lib/parse-blueprint.sh" "$PROJECT/scenes/$s/blueprint.txt" 2>/dev/null \
+    | jq -S . 2>/dev/null || true)"
+  expected="$(jq -S . "$PROJECT/scenes/$s/expected.json" 2>/dev/null || true)"
+  if [ -z "$actual" ]; then
+    fail "$s: parse-blueprint produced no output"
+  elif [ "$actual" = "$expected" ]; then
+    ok "$s: parse-blueprint matches expected.json"
+  else
+    fail "$s: parse-blueprint mismatch (diff actual vs. expected.json)"
+  fi
+done
+
+# ---------------------------------------------------------------- 2
+printf '\n[2/6] character.json descriptors verbatim in prompt.subject\n'
+SILHOUETTE="$(jq -r '.characters[0].silhouette' "$PROJECT/character.json")"
+PALETTE="$(jq -r '.characters[0].palette'    "$PROJECT/character.json")"
+WARDROBE="$(jq -r '.characters[0].wardrobe'  "$PROJECT/character.json")"
+PROP="$(jq -r '.characters[0].prop'          "$PROJECT/character.json")"
+
+for s in $SCENES; do
+  subj="$(jq -r '.prompt.subject' "$PROJECT/scenes/$s/expected.json")"
+  miss=""
+  case "$subj" in *"$SILHOUETTE"*) :;; *) miss="$miss silhouette";; esac
+  case "$subj" in *"$PALETTE"*)    :;; *) miss="$miss palette";; esac
+  case "$subj" in *"$WARDROBE"*)   :;; *) miss="$miss wardrobe";; esac
+  case "$subj" in *"$PROP"*)       :;; *) miss="$miss prop";; esac
+  if [ -z "$miss" ]; then
+    ok "$s: silhouette + palette + wardrobe + prop verbatim in prompt.subject"
+  else
+    fail "$s: missing verbatim tokens in prompt.subject:$miss"
+  fi
+done
+
+# ---------------------------------------------------------------- 3
+printf '\n[3/6] audio.* branching matches manifest\n'
+for entry in 01-simple:false 02-dialogue-native-audio:true 03-edge-duration:false; do
+  s="${entry%%:*}"
+  want="${entry##*:}"
+  got="$(jq -r '.audio.enable_native_audio' "$PROJECT/scenes/$s/expected.json")"
+  manifest_got="$(jq -r --arg id "$s" '.scenes[] | select(.id==$id) | .audio_embedded' "$PROJECT/manifest.json")"
+  if [ "$got" = "$want" ] && [ "$manifest_got" = "$want" ]; then
+    ok "$s: enable_native_audio=$got, manifest.audio_embedded=$manifest_got"
+  else
+    fail "$s: audio branching drift (expected=$want, blueprint=$got, manifest=$manifest_got)"
+  fi
+done
+
+# ---------------------------------------------------------------- 4
+printf '\n[4/6] adapter capability declarations\n'
+declare_caps() {
+  local adapter="$1"; local expected="$2"
+  local out got
+  out="$(AIV_DRYRUN=true bash "$ROOT/scripts/ai-video/adapters/$adapter.sh" capability 2>/dev/null || true)"
+  got="$(printf '%s' "$out" | jq -r '.audio // empty' 2>/dev/null || true)"
+  if [ "$got" = "$expected" ]; then
+    ok "$adapter: capability.audio=$got"
+  else
+    fail "$adapter: capability mismatch (want audio=$expected, got: ${got:-<unparseable: $out>})"
+  fi
+}
+declare_caps gemini-veo    "native"
+declare_caps openai-images "none"
+declare_caps sora          "native"
+declare_caps kling         "none"
+
+# ---------------------------------------------------------------- 5
+printf '\n[5/6] stitch.sh dry-run returns manifest output path\n'
+STITCH_OUT="$(jq -r '.stitch_output' "$PROJECT/manifest.json")"
+stitch_log="$(AIV_DRYRUN=true bash "$ROOT/scripts/ai-video/stitch.sh" \
+  "$PROJECT/manifest.json" "$PROJECT/$STITCH_OUT" 2>&1 || true)"
+case "$stitch_log" in
+  *"$STITCH_OUT"*) ok   "stitch.sh dry-run referenced $STITCH_OUT";;
+  *)               fail "stitch.sh dry-run did not reference $STITCH_OUT (log: $stitch_log)";;
+esac
+
+# ---------------------------------------------------------------- 6
+printf '\n[6/6] visual regression (locked.png pairwise)\n'
+PNG_MAGIC="$(printf '\x89PNG\r\n\x1a\n')"
+prev=""
+have_compare=0
+command -v compare >/dev/null 2>&1 && have_compare=1
+for s in $SCENES; do
+  f="$PROJECT/scenes/$s/fixtures/frames/locked.png"
+  if [ ! -s "$f" ]; then
+    fail "$s: locked.png missing or empty"
+    continue
+  fi
+  head -c 8 "$f" | od -An -c | tr -d ' \n' | grep -q '211PNG' \
+    && ok "$s: locked.png is a valid PNG ($(wc -c < "$f" | tr -d ' ') bytes)" \
+    || fail "$s: locked.png lacks PNG magic"
+  if [ -n "$prev" ]; then
+    if [ "$have_compare" -eq 1 ]; then
+      ncc="$(compare -metric NCC "$prev" "$f" null: 2>&1 || true)"
+      awk_ok="$(awk -v v="$ncc" 'BEGIN { exit !(v+0 >= 0.95) }' && echo yes || echo no)"
+      if [ "$awk_ok" = "yes" ]; then
+        ok "$s: NCC vs. previous = $ncc (≥ 0.95)"
+      else
+        fail "$s: NCC vs. previous = $ncc (< 0.95)"
+      fi
+    else
+      if cmp -s "$prev" "$f"; then
+        ok "$s: byte-identical to previous (compare unavailable; offline fallback)"
+      else
+        fail "$s: differs from previous frame and compare is unavailable"
+      fi
+    fi
+  fi
+  prev="$f"
+done
+
+# ----------------------------------------------------------------
+printf '\n----------------\nresult: %d passed · %d failed\n' "$PASS" "$FAIL"
+if [ "$FAIL" -gt 0 ]; then
+  printf '%b\n' "$FAILS"
+  exit 1
+fi
+exit 0

package/scripts/check_portability.py

@@ -319,6 +319,12 @@ _TASK_DETECTOR_SKIP = (
     "rules/package-ci-checks.md",
     "contexts/communication/rules-auto/package-ci-checks-mechanics.md",
     "contexts/contracts/agents-md-anatomy.md",
+    # roadmap-ci-steps-policy defines the gate by listing the forbidden
+    # CI-shaped literals; its mechanics doc and the execution loop +
+    # authoring skill enumerate the same literals to detect them.
+    "rules/roadmap-ci-steps-policy.md",
+    "contexts/execution/roadmap-process-loop.md",
+    "skills/roadmap-writing/SKILL.md",
 )
 
 

package/scripts/lint_media_policy_linkage.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""Lint structural reachability of media governance policies.
+
+Every policy file under `agents/policies/media/` (except README) must
+be linked from at least one of:
+
+  * a skill SKILL.md (any .agent-src.uncompressed/skills/*/SKILL.md
+    or .claude/skills/*/SKILL.md),
+  * a routing rule under .agent-src.uncompressed/rules/, or
+  * a sibling policy file under agents/policies/media/.
+
+A policy that no surface references is a silent policy and a silent
+policy is a failed policy. This is the CI-side reachability guarantee
+the agent-in-the-loop enforcement model rests on (see
+agents/policies/media/README.md § Enforcement model).
+
+Exit codes:
+  0  all policies linked
+  1  one or more orphan policies
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+QUIET = "--quiet" in sys.argv
+
+REPO = Path(__file__).resolve().parents[1]
+POLICY_DIR = REPO / "agents" / "policies" / "media"
+EXEMPT_STEMS = frozenset({"README"})
+
+# Surfaces scanned for inbound references to policy files.
+SCAN_ROOTS: tuple[Path, ...] = (
+    REPO / ".agent-src.uncompressed" / "skills",
+    REPO / ".agent-src.uncompressed" / "rules",
+    REPO / ".agent-src.uncompressed" / "commands",
+    REPO / ".claude" / "skills",
+    REPO / "agents" / "policies" / "media",
+)
+
+
+def emit(msg: str) -> None:
+    if not QUIET:
+        print(msg)
+
+
+def collect_policies() -> list[Path]:
+    if not POLICY_DIR.exists():
+        return []
+    return sorted(
+        p
+        for p in POLICY_DIR.glob("*.md")
+        if p.stem not in EXEMPT_STEMS
+    )
+
+
+def collect_scan_files() -> list[Path]:
+    files: list[Path] = []
+    for root in SCAN_ROOTS:
+        if not root.exists():
+            continue
+        files.extend(root.rglob("*.md"))
+    return files
+
+
+def referrers_for(policy: Path, scan_files: list[Path]) -> list[Path]:
+    """Return files that reference `policy` by its repo-relative name
+    or basename. We accept both the full path token
+    (`agents/policies/media/likeness.md`) and the bare basename
+    (`likeness.md`) inside a markdown link, because sibling policies
+    link via relative `[likeness.md](likeness.md)` form.
+    """
+    needles = (
+        f"policies/media/{policy.name}",
+        f"]({policy.name})",
+    )
+    referrers: list[Path] = []
+    for scan_file in scan_files:
+        # A policy can't satisfy its own linkage requirement.
+        if scan_file.resolve() == policy.resolve():
+            continue
+        try:
+            text = scan_file.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        if any(n in text for n in needles):
+            referrers.append(scan_file)
+    return referrers
+
+
+def main() -> int:
+    if not POLICY_DIR.exists():
+        emit(
+            "media-policy-linkage: agents/policies/media/ missing — "
+            "nothing to lint."
+        )
+        return 0
+
+    policies = collect_policies()
+    if not policies:
+        emit(
+            "media-policy-linkage: agents/policies/media/ has no policy "
+            "files — nothing to lint."
+        )
+        return 0
+
+    scan_files = collect_scan_files()
+    orphans: list[Path] = []
+    for policy in policies:
+        referrers = referrers_for(policy, scan_files)
+        rel = policy.relative_to(REPO)
+        if not referrers:
+            orphans.append(policy)
+            emit(f"❌  ORPHAN  {rel}")
+            continue
+        emit(f"✅  {rel}  ({len(referrers)} referrer(s))")
+
+    if orphans:
+        print(
+            f"\nmedia-policy-linkage: {len(orphans)} orphan policy "
+            f"file(s) — every policy must be linked from a skill, rule, "
+            f"or sibling policy.",
+            file=sys.stderr,
+        )
+        for o in orphans:
+            print(
+                f"  - {o.relative_to(REPO)}",
+                file=sys.stderr,
+            )
+        return 1
+
+    emit(
+        f"media-policy-linkage: {len(policies)} policy file(s) — all "
+        f"linked."
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_persona_governance.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""Lint persona governance — per-domain cap (hard) + citation floor (warn).
+
+Enforces the mechanical checks in
+`.agent-src.uncompressed/rules/persona-governance.md`:
+
+  1. **Per-domain cap (HARD)** — ≤ 2 active specialist personas per
+     content domain. Core-tier personas are exempt. `status:
+     deprecated` rows (if any survive a transition window) are
+     excluded from the count; the canonical path is in-commit
+     deletion, no soak window.
+  2. **Skill citation floor (WARN)** — every active specialist
+     persona SHOULD be cited by `personas: [<id>]` in at least one
+     skill SKILL.md under `.agent-src.uncompressed/skills/` or
+     `.claude/skills/`. Surfaced as a warning, never blocks CI:
+     the citation floor is enforced at PR time per the rule (a new
+     specialist MUST land with a cite); pre-existing wiring debt is
+     tracked as `--citation-debt` for the maintainer dashboard.
+
+Schema conformance (check 4) is delegated to `lint-skills`.
+Deprecation path (check 3) is reviewed at PR time via the table in
+`docs/personas.md`.
+
+Domain inference: persona ids → content domain via `DOMAIN_MAP`,
+mirroring `persona-governance.md § Per-domain cap`. Personas absent
+from the map are cross-cutting (uncapped).
+
+Exit codes:
+  0  per-domain cap clean (citation warnings non-blocking)
+  1  per-domain cap violated
+"""
+from __future__ import annotations
+
+import re
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+QUIET = "--quiet" in sys.argv
+
+REPO = Path(__file__).resolve().parents[1]
+PERSONA_DIR = REPO / ".agent-src.uncompressed" / "personas"
+SKILL_ROOTS: tuple[Path, ...] = (
+    REPO / ".agent-src.uncompressed" / "skills",
+    REPO / ".claude" / "skills",
+)
+
+# Per-domain cap — mirrors persona-governance.md § Per-domain cap.
+# Maps persona id → content-domain bucket. Personas absent from this
+# map are cross-cutting (uncapped) — typically singleton specialists
+# without a domain peer (e.g. `qa`, `tech-writer`).
+DOMAIN_MAP: dict[str, str] = {
+    "hollywood-director": "ai-video",
+    "ai-video-technical-director": "ai-video",
+    "backend-architect": "backend",
+    "eloquent-tamer": "backend",
+    "cmo": "gtm",
+    "revops": "gtm",
+    "growth-pm": "growth",
+    "customer-success-lead": "customer",
+    "discovery-lead": "customer",
+    "engineering-manager": "people",
+    "people-strategist": "people",
+    "finance-partner": "money",
+    "strategist": "money",
+}
+PER_DOMAIN_CAP = 2
+
+
+def emit(msg: str) -> None:
+    if not QUIET:
+        print(msg)
+
+
+def parse_frontmatter(path: Path) -> dict[str, str]:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    if not text.startswith("---"):
+        return {}
+    end = text.find("\n---", 3)
+    if end == -1:
+        return {}
+    out: dict[str, str] = {}
+    for line in text[3:end].splitlines():
+        m = re.match(r"^([a-zA-Z_][\w-]*):\s*(.*)$", line)
+        if m:
+            out[m.group(1)] = m.group(2).strip().strip('"').strip("'")
+    return out
+
+
+def collect_personas() -> list[tuple[str, str, str, Path]]:
+    """Return (id, tier, status, path) for every persona file."""
+    out: list[tuple[str, str, str, Path]] = []
+    if not PERSONA_DIR.exists():
+        return out
+    for path in sorted(PERSONA_DIR.glob("*.md")):
+        if path.stem == "README":
+            continue
+        fm = parse_frontmatter(path)
+        pid = fm.get("id") or path.stem
+        tier = fm.get("tier", "")
+        status = fm.get("status", "active") or "active"
+        out.append((pid, tier, status, path))
+    return out
+
+
+def citations_for(persona_id: str) -> list[Path]:
+    pattern = re.compile(rf"(^|[\s,\[]){re.escape(persona_id)}([\s,\]]|$)")
+    hits: list[Path] = []
+    for root in SKILL_ROOTS:
+        if not root.exists():
+            continue
+        for skill in root.rglob("SKILL.md"):
+            text = skill.read_text(encoding="utf-8", errors="replace")
+            if text.startswith("---"):
+                end = text.find("\n---", 3)
+                fm_block = text[3:end] if end != -1 else ""
+            else:
+                fm_block = ""
+            if "personas:" not in fm_block:
+                continue
+            if pattern.search(fm_block):
+                hits.append(skill)
+    return hits
+
+
+def main() -> int:
+    personas = collect_personas()
+    if not personas:
+        emit("persona-governance: no persona files found — nothing to lint.")
+        return 0
+
+    by_domain: dict[str, list[str]] = defaultdict(list)
+    missing_citations: list[str] = []
+
+    for pid, tier, status, _ in personas:
+        if status == "deprecated" or tier != "specialist":
+            continue
+        domain = DOMAIN_MAP.get(pid)
+        if domain:
+            by_domain[domain].append(pid)
+        if not citations_for(pid):
+            missing_citations.append(pid)
+
+    overflows = {d: ids for d, ids in by_domain.items() if len(ids) > PER_DOMAIN_CAP}
+    for d, ids in sorted(by_domain.items()):
+        marker = "❌" if d in overflows else "✅"
+        emit(f"{marker}  domain={d}  {len(ids)}/{PER_DOMAIN_CAP}  {', '.join(sorted(ids))}")
+    for pid in sorted(missing_citations):
+        emit(f"⚠️   no-skill-citation  {pid}  (warn — see PR-time gate)")
+
+    if overflows:
+        print("\npersona-governance: per-domain cap violated.", file=sys.stderr)
+        for d, ids in sorted(overflows.items()):
+            print(f"  - domain '{d}' has {len(ids)} specialists (cap {PER_DOMAIN_CAP}): {', '.join(sorted(ids))}", file=sys.stderr)
+        return 1
+
+    active = sum(1 for _, t, s, _ in personas if s != "deprecated" and t == "specialist")
+    cited = active - len(missing_citations)
+    emit(f"persona-governance: {active} active specialist persona(s) — all domains within cap; {cited}/{active} cited by ≥ 1 skill.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())