@event4u/agent-config 1.33.0 → 1.34.0

package/scripts/_backfill_skill_domains.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""One-shot back-fill: inject `domain:` frontmatter into every SKILL.md.
+
+Removed after B3 lands. Source-of-truth = SKILL_DOMAIN_MAP below.
+Fails loudly if the map and on-disk skill set diverge.
+"""
+from __future__ import annotations
+import re
+import sys
+from pathlib import Path
+
+SKILL_DOMAIN_MAP: dict[str, str] = {
+    "adr-create": "process", "adversarial-review": "quality",
+    "agent-docs-writing": "process", "agents-md-thin-root": "process",
+    "ai-council": "process", "analysis-autonomous-mode": "discovery",
+    "analysis-skill-router": "discovery", "api-design": "engineering",
+    "api-endpoint": "engineering", "api-testing": "quality",
+    "artisan-commands": "engineering", "async-python-patterns": "engineering",
+    "authz-review": "quality", "aws-infrastructure": "devops",
+    "blade-ui": "engineering", "blast-radius-analyzer": "discovery",
+    "bug-analyzer": "discovery", "check-refs": "process",
+    "code-refactoring": "engineering", "code-review": "quality",
+    "command-routing": "process", "command-writing": "process",
+    "composer-packages": "engineering", "context-authoring": "process",
+    "context-document": "process", "conventional-commits-writing": "process",
+    "copilot-agents-optimization": "process", "copilot-config": "process",
+    "dashboard-design": "devops", "data-flow-mapper": "discovery",
+    "database": "engineering", "dcf-modeling": "product",
+    "deep-reading-analyst": "discovery", "defense-in-depth": "quality",
+    "dependency-upgrade": "engineering", "description-assist": "process",
+    "design-review": "quality", "devcontainer": "devops",
+    "developer-like-execution": "process", "docker": "devops",
+    "dto-creator": "engineering", "eloquent": "engineering",
+    "error-handling-patterns": "engineering", "estimate-ticket": "product",
+    "existing-ui-audit": "discovery", "fe-design": "engineering",
+    "feature-planning": "product", "file-editor": "process",
+    "finishing-a-development-branch": "process", "flux": "engineering",
+    "funnel-analysis": "product", "git-workflow": "process",
+    "github-ci": "devops", "grafana": "devops",
+    "guideline-writing": "process", "jira-integration": "process",
+    "jobs-events": "engineering", "judge-bug-hunter": "quality",
+    "judge-code-quality": "quality", "judge-security-auditor": "quality",
+    "judge-test-coverage": "quality", "laravel": "engineering",
+    "laravel-horizon": "engineering", "laravel-mail": "engineering",
+    "laravel-middleware": "engineering", "laravel-notifications": "engineering",
+    "laravel-pennant": "engineering", "laravel-pulse": "engineering",
+    "laravel-reverb": "engineering", "laravel-scheduling": "engineering",
+    "laravel-validation": "engineering", "learning-to-rule-or-skill": "process",
+    "lint-skills": "process", "livewire": "engineering",
+    "logging-monitoring": "devops", "markitdown": "process",
+    "mcp": "process", "mcp-builder": "process",
+    "md-language-check": "process", "merge-conflicts": "process",
+    "migration-creator": "engineering", "mobile-e2e-strategy": "quality",
+    "module-management": "process", "multi-tenancy": "engineering",
+    "okr-tree-modeling": "product", "openapi": "engineering",
+    "override-management": "process", "performance": "engineering",
+    "performance-analysis": "discovery", "persona-writing": "process",
+    "pest-testing": "quality", "php-coder": "engineering",
+    "php-debugging": "engineering", "php-service": "engineering",
+    "playwright-testing": "quality", "project-analysis-core": "discovery",
+    "project-analysis-hypothesis-driven": "discovery",
+    "project-analysis-laravel": "discovery", "project-analysis-nextjs": "discovery",
+    "project-analysis-node-express": "discovery",
+    "project-analysis-react": "discovery", "project-analysis-symfony": "discovery",
+    "project-analysis-zend-laminas": "discovery", "project-analyzer": "discovery",
+    "project-docs": "process", "prompt-engineering-patterns": "product",
+    "prompt-optimizer": "product", "quality-tools": "quality",
+    "react-native-setup": "devops", "react-shadcn-ui": "engineering",
+    "readme-reviewer": "quality", "readme-writing": "process",
+    "readme-writing-package": "process", "receiving-code-review": "process",
+    "refine-prompt": "product", "refine-ticket": "product",
+    "repomix-packer": "process", "requesting-code-review": "process",
+    "review-routing": "quality", "rice-prioritization": "product",
+    "roadmap-management": "process", "roadmap-writing": "process",
+    "rtk-output-filtering": "process", "rule-writing": "process",
+    "script-writing": "process", "secrets-management": "devops",
+    "security": "quality", "security-audit": "quality",
+    "sentry-integration": "devops", "sequential-thinking": "process",
+    "skill-improvement-pipeline": "process", "skill-management": "process",
+    "skill-reviewer": "quality", "skill-writing": "process",
+    "sql-writing": "engineering", "subagent-orchestration": "process",
+    "systematic-debugging": "discovery", "technical-specification": "product",
+    "terraform": "devops", "terragrunt": "devops",
+    "test-driven-development": "quality", "test-performance": "quality",
+    "testing-anti-patterns": "quality", "threat-modeling": "quality",
+    "token-optimizer": "process", "traefik": "devops",
+    "unit-economics-modeling": "product", "universal-project-analysis": "discovery",
+    "upstream-contribute": "process", "using-git-worktrees": "process",
+    "validate-feature-fit": "quality", "verify-completion-evidence": "quality",
+    "websocket": "engineering",
+}
+VALID_DOMAINS = {"engineering", "product", "quality", "devops", "process", "discovery"}
+
+
+def main() -> int:
+    # Default: source-of-truth tree. Pass --target=compressed to mirror into .agent-src/.
+    target = ".agent-src.uncompressed/skills"
+    for arg in sys.argv[1:]:
+        if arg == "--target=compressed":
+            target = ".agent-src/skills"
+    skills_root = Path(target)
+    on_disk = sorted(p.name for p in skills_root.iterdir() if p.is_dir())
+    in_map = sorted(SKILL_DOMAIN_MAP.keys())
+    missing = set(on_disk) - set(in_map)
+    extra = set(in_map) - set(on_disk)
+    if missing or extra:
+        print(f"DRIFT: missing={sorted(missing)} extra={sorted(extra)}", file=sys.stderr)
+        return 2
+    bad = {k: v for k, v in SKILL_DOMAIN_MAP.items() if v not in VALID_DOMAINS}
+    if bad:
+        print(f"INVALID DOMAIN VALUES: {bad}", file=sys.stderr)
+        return 2
+
+    fm_pat = re.compile(r"^(---\n)(.*?)(\n---\n)", re.DOTALL)
+    domain_line_pat = re.compile(r"^domain:[ \t]*[A-Za-z]+[ \t]*$", re.MULTILINE)
+    source_line_pat = re.compile(r"^(source:[ \t]*\S+)$", re.MULTILINE)
+    edited = 0
+    for slug, domain in SKILL_DOMAIN_MAP.items():
+        skill_md = skills_root / slug / "SKILL.md"
+        text = skill_md.read_text()
+        m = fm_pat.match(text)
+        if not m:
+            print(f"NO FRONTMATTER: {skill_md}", file=sys.stderr)
+            return 2
+        fm_body = m.group(2)
+        if domain_line_pat.search(fm_body):
+            new_fm = domain_line_pat.sub(f"domain: {domain}", fm_body)
+        elif source_line_pat.search(fm_body):
+            new_fm = source_line_pat.sub(rf"\1\ndomain: {domain}", fm_body)
+        else:
+            new_fm = fm_body.rstrip("\n") + f"\ndomain: {domain}"
+        if new_fm != fm_body:
+            skill_md.write_text(m.group(1) + new_fm + m.group(3) + text[m.end():])
+            edited += 1
+    print(f"Back-filled {edited}/{len(SKILL_DOMAIN_MAP)} skills")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/_emit_domain_table.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""Emit the per-domain skill list as Markdown for skill-domains.md § 4."""
+from __future__ import annotations
+
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _backfill_skill_domains import SKILL_DOMAIN_MAP  # noqa: E402
+
+ORDER = ["engineering", "product", "quality", "devops", "process", "discovery"]
+
+
+def main() -> int:
+    by_domain: dict[str, list[str]] = defaultdict(list)
+    for slug, dom in SKILL_DOMAIN_MAP.items():
+        by_domain[dom].append(slug)
+
+    lines: list[str] = []
+    total = 0
+    for dom in ORDER:
+        skills = sorted(by_domain[dom])
+        total += len(skills)
+        lines.append(f"### {dom} ({len(skills)})")
+        lines.append("")
+        lines.append(", ".join(f"`{s}`" for s in skills))
+        lines.append("")
+    lines.append(f"**Total: {total} skills.**")
+    print("\n".join(lines))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/install-hooks.sh

@@ -13,14 +13,31 @@ mkdir -p "$HOOKS_DIR"
 cat > "$HOOKS_DIR/pre-push" << 'EOF'
 #!/usr/bin/env bash
 # Pre-push hook: verify .agent-src/ is in sync with .agent-src.uncompressed/
+# and that the canonical command count matches README + getting-started docs.
+#
+# The command-count gate exists because three consecutive PRs landed
+# post-CI count-drift fixes (e.g. f2fb0026 "bump command count
+# 101→103"). Catching the drift pre-push stops it from flooding remote
+# CI. Runtime ~0.1s.
+
+fail=0
 
 echo "🔍 Checking .agent-src/ sync..."
-python3 scripts/compress.py --check
+if ! python3 scripts/compress.py --check; then
+    echo "❌  .agent-src/ is out of sync. Run 'task sync' and compress changed .md files, then commit."
+    fail=1
+fi
+
+echo "🔍 Checking command count messaging..."
+if ! python3 scripts/check_command_count_messaging.py; then
+    echo "❌  Command-count drift in README / AGENTS.md / getting-started. Run 'task counts-update', stage the changes, then re-commit."
+    fail=1
+fi
 
-if [ $? -ne 0 ]; then
+if [ $fail -ne 0 ]; then
     echo ""
-    echo "❌  Push blocked — .agent-src/ is out of sync."
-    echo "   Run 'task sync' and compress changed .md files, then commit."
+    echo "   Push blocked — fix the failures above and re-push."
+    echo "   Bypass for a WIP push:  git push --no-verify"
     exit 1
 fi
 EOF

package/scripts/lint_skill_tools.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""Block D · D1 — meta-linter for ``scripts/skill_tools/*.py``.
+
+Enforces the four pilot-tool invariants locked by the Block D council
+verdict (`agents/council-responses/block-d-python-tools-pilot-verdict.md`):
+
+  1. **stdlib-only** — no third-party imports. Internal package imports
+     (``scripts.*``) are allowed.
+  2. **--help and --json flags** — every tool must register both via
+     ``argparse`` so callers can introspect and machine-read.
+  3. **naming** — ``snake_case_verb_noun.py`` (≥ 1 underscore, lowercase).
+  4. **embedded sample data** — module must define a ``_SAMPLE`` constant
+     OR contain ``if __name__ == "__main__"`` with sample-mode handling
+     (so the tool can run without external fixtures).
+  5. **size cap** — file ≤ 200 LOC (per roadmap D1, applies to D1 itself
+     and to D2/D3/D4 with their own caps validated externally).
+
+Tool discovery is glob-based (``scripts/skill_tools/*.py`` excluding
+``__init__.py``) per anthropic round-2 critique — never a hardcoded list.
+
+Run:
+  python3 scripts/lint_skill_tools.py            # human-readable
+  python3 scripts/lint_skill_tools.py --json     # machine-readable
+
+Exit codes: 0 clean · 1 violations found · 2 usage error.
+"""
+from __future__ import annotations
+
+import argparse
+import ast
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+ROOT = Path(__file__).resolve().parents[1]
+TOOLS_DIR = ROOT / "scripts" / "skill_tools"
+NAME_RE = re.compile(r"^[a-z][a-z0-9]*(?:_[a-z0-9]+)+\.py$")
+SIZE_CAP = 200
+
+# Python 3.9-compatible stdlib list. Kept conservative — additions are cheap,
+# false negatives are not. Mirrors `sys.stdlib_module_names` from 3.10+.
+STDLIB = frozenset({
+    "__future__", "abc", "argparse", "ast", "base64", "collections", "configparser",
+    "contextlib", "copy", "csv", "dataclasses", "datetime", "decimal", "difflib",
+    "enum", "errno", "fnmatch", "functools", "glob", "gzip", "hashlib", "heapq",
+    "html", "http", "importlib", "inspect", "io", "ipaddress", "itertools", "json",
+    "logging", "math", "mimetypes", "os", "pathlib", "pickle", "platform", "posixpath",
+    "pprint", "queue", "random", "re", "shlex", "shutil", "signal", "socket",
+    "sqlite3", "ssl", "stat", "string", "struct", "subprocess", "sys", "tempfile",
+    "textwrap", "threading", "time", "tomllib", "traceback", "types", "typing",
+    "unicodedata", "unittest", "urllib", "uuid", "venv", "warnings", "weakref",
+    "xml", "zipfile", "zlib",
+})
+PROJECT_PACKAGES = frozenset({"scripts", "skill_tools"})  # internal imports are fine.
+
+
+def _violations_for(path: Path) -> List[str]:
+    """Return a list of violation strings for one tool (empty = clean)."""
+    out: List[str] = []
+    name = path.name
+    if not NAME_RE.match(name):
+        out.append(f"naming: `{name}` is not snake_case_verb_noun.py")
+
+    text = path.read_text(encoding="utf-8")
+    loc = sum(1 for ln in text.splitlines() if ln.strip() and not ln.lstrip().startswith("#"))
+    if loc > SIZE_CAP:
+        out.append(f"size: {loc} LOC > {SIZE_CAP} cap")
+
+    try:
+        tree = ast.parse(text, filename=str(path))
+    except SyntaxError as exc:
+        out.append(f"syntax: {exc.msg} at line {exc.lineno}")
+        return out
+
+    # Imports — flag any non-stdlib, non-project top-level module + record argparse use.
+    imported: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                root = alias.name.split(".")[0]
+                imported.add(root)
+                if root not in STDLIB and root not in PROJECT_PACKAGES:
+                    out.append(f"stdlib-only: imports `{alias.name}` (third-party)")
+        elif isinstance(node, ast.ImportFrom):
+            if node.module is None or node.level > 0:
+                continue  # relative imports — package-internal
+            root = node.module.split(".")[0]
+            imported.add(root)
+            if root not in STDLIB and root not in PROJECT_PACKAGES:
+                out.append(f"stdlib-only: imports from `{node.module}` (third-party)")
+
+    # CLI flags — confirm argparse is imported and `--json` is registered.
+    has_argparse = "argparse" in imported
+    has_json_flag = re.search(r"['\"]--json['\"]", text) is not None
+    if not has_argparse:
+        out.append("cli: no `argparse` import detected")
+    if not has_json_flag:
+        out.append("cli: missing `--json` flag")
+    # `--help` is auto-registered by argparse; we sanity-check that
+    # add_help isn't disabled.
+    if re.search(r"add_help\s*=\s*False", text):
+        out.append("cli: `add_help=False` disables --help")
+
+    # Embedded sample data — accept either a module-level _SAMPLE constant
+    # or a __main__ block (the tool can self-demo).
+    has_sample = bool(re.search(r"^_SAMPLE\s*[:=]", text, re.MULTILINE))
+    has_main = '__name__ == "__main__"' in text or "__name__ == '__main__'" in text
+    if not (has_sample or has_main):
+        out.append("sample: no `_SAMPLE` constant or `__main__` block")
+
+    return out
+
+
+def lint(tools_dir: Path) -> Tuple[int, Dict[str, List[str]]]:
+    tools_dir = tools_dir.resolve()
+    if not tools_dir.is_dir():
+        return 2, {"_error": [f"tools dir missing: {tools_dir}"]}
+    findings: Dict[str, List[str]] = {}
+    for path in sorted(tools_dir.glob("*.py")):
+        if path.name == "__init__.py":
+            continue
+        viols = _violations_for(path)
+        if viols:
+            try:
+                key = str(path.relative_to(ROOT))
+            except ValueError:
+                key = str(path)
+            findings[key] = viols
+    return (1 if findings else 0), findings
+
+
+def _print_human(findings: Dict[str, List[str]]) -> None:
+    if not findings:
+        print(f"✅  scripts/skill_tools/ — all tools clean.")
+        return
+    print(f"❌  scripts/skill_tools/ — {len(findings)} tool(s) with violations:")
+    for fp, viols in findings.items():
+        print(f"  {fp}:")
+        for v in viols:
+            print(f"    - {v}")
+
+
+def main(argv: List[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Lint scripts/skill_tools/*.py against Block D pilot invariants.",
+    )
+    parser.add_argument("--json", action="store_true", help="emit JSON instead of text")
+    parser.add_argument("--quiet", action="store_true",
+                        help="suppress the clean-pass success line (errors still print)")
+    parser.add_argument("--tools-dir", default=str(TOOLS_DIR),
+                        help="directory to lint (default: scripts/skill_tools)")
+    args = parser.parse_args(argv)
+
+    code, findings = lint(Path(args.tools_dir))
+    if args.json:
+        json.dump({"exit_code": code, "findings": findings}, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+    elif findings or not args.quiet:
+        _print_human(findings)
+    return code
+
+
+_SAMPLE = {"violations": ["stdlib-only: imports `requests` (third-party)"]}
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/schemas/skill.schema.json

@@ -5,7 +5,7 @@
   "$comment": "Source: agents/docs/frontmatter-contract.md#skills. Keep in sync with inventory_frontmatter.py and the linter's lint_skill().",
   "type": "object",
   "additionalProperties": false,
-  "required": ["name", "description", "source"],
+  "required": ["name", "description", "source", "domain"],
   "properties": {
     "name": {
       "type": "string",
@@ -22,6 +22,11 @@
       "type": "string",
       "enum": ["package", "project"]
     },
+    "domain": {
+      "type": "string",
+      "enum": ["engineering", "product", "quality", "devops", "process", "discovery"],
+      "description": "Skill classification axis; see docs/contracts/skill-domains.md. Required for every skill — exactly one of: engineering, product, quality, devops, process, discovery."
+    },
     "status": {
       "type": "string",
       "enum": ["active", "deprecated", "superseded"]

package/scripts/skill_linter.py

@@ -41,15 +41,22 @@ from validate_frontmatter import (  # noqa: E402
 Severity = Literal["error", "warning", "info"]
 ArtifactType = Literal["skill", "rule", "command", "guideline", "persona", "unknown"]
 
-REQUIRED_PERSONA_SECTIONS = [
+REQUIRED_PERSONA_SECTIONS_CORE = [
     "Focus",
     "Mindset",
     "Unique Questions",
     "Output Expectations",
     "Anti-Patterns",
 ]
+REQUIRED_PERSONA_SECTIONS_SPECIALIST = REQUIRED_PERSONA_SECTIONS_CORE + [
+    "Critical Rules",
+    "Workflows",
+]
+# Back-compat alias — used by tier-agnostic callers; defaults to the core spine.
+REQUIRED_PERSONA_SECTIONS = REQUIRED_PERSONA_SECTIONS_CORE
 VALID_PERSONA_TIERS = {"core", "specialist"}
-PERSONA_LINE_BUDGETS = {"core": 120, "specialist": 80}
+# Locked in docs/contracts/persona-schema.md § 4: core ≤ 120, specialist ≤ 100.
+PERSONA_LINE_BUDGETS = {"core": 120, "specialist": 100}
 
 
 REQUIRED_SKILL_SECTIONS = [
@@ -1437,9 +1444,17 @@ def lint_persona(path: Path, text: str) -> LintResult:
             f"Persona description is {len(parsed['description'])} chars (target ≤ 160)",
         ))
 
-    # Required sections
+    # Required sections — tier-aware (per docs/contracts/persona-schema.md § 3).
+    # Core: 5 sections. Specialist: Core-5 + Critical Rules + Workflows.
     sections = extract_sections(text)
-    for required_section in REQUIRED_PERSONA_SECTIONS:
+    tier = parsed.get("tier")
+    if tier == "specialist":
+        required_sections = REQUIRED_PERSONA_SECTIONS_SPECIALIST
+    else:
+        # Default to core sections when tier is missing or invalid; the
+        # tier-enum check above already raised an error in that case.
+        required_sections = REQUIRED_PERSONA_SECTIONS_CORE
+    for required_section in required_sections:
         if required_section not in sections:
             issues.append(Issue(
                 "error",

package/scripts/skill_tools/__init__.py

@@ -0,0 +1,22 @@
+"""Block D pilot tools for skill discovery and persona auditing.
+
+These four tools (D1 meta-linter + D2/D3/D4 functional pilots) ship under
+this subdirectory per Block D council verdict (D-OQ2 → b). Each tool is:
+
+  - stdlib-only (no third-party imports)
+  - exposes ``--help`` and ``--json`` flags
+  - named ``snake_case_verb_noun.py``
+  - embeds sample data so it runs without external fixtures
+
+Layout chosen to make the pilot reversible. If the D5 eval gate fails
+(< 2 of 3 functional tools pass), the directory and its CI hook can be
+removed in a single commit without touching the wider ``scripts/`` tree.
+
+Public entry points:
+
+  - ``scripts/lint_skill_tools.py`` — D1 meta-linter (lives at scripts/ root
+    so ``task ci`` picks it up like other linters).
+  - ``score_skill_relevance`` — D2 (this dir).
+  - ``audit_persona_coverage`` — D3 (this dir).
+  - ``suggest_skill_for_task`` — D4 (this dir).
+"""

package/scripts/skill_tools/audit_persona_coverage.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""Block D · D3 — audit_persona_coverage.
+
+Build a citation matrix of personas across the SKILL.md corpus and flag
+under-cited personas using **tier-aware thresholds** (council iter-1
+D-OQ4 verdict):
+
+  - **specialist** persona < 3 citations  → under-cited
+  - **core**       persona < 5 citations  → under-cited
+
+Inputs:
+  --skills-dir DIR   — directory holding SKILL.md files
+  --personas-dir DIR — directory holding persona Markdown files
+  --json             — machine-readable output
+
+Output: per-persona citation count + tier + status (ok / under-cited / orphan).
+Exit code: 0 always (this is an advisory tool, not a CI gate).
+
+Stdlib-only. ≤ 120 LOC. Embedded `_SAMPLE` for self-demo.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_SKILLS = ROOT / ".agent-src.uncompressed" / "skills"
+DEFAULT_PERSONAS = ROOT / ".agent-src.uncompressed" / "personas"
+THRESHOLDS = {"core": 5, "specialist": 3}
+
+
+def _read_block(path: Path) -> str:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    if not text.startswith("---"):
+        return ""
+    end = text.find("\n---", 3)
+    return text[3:end] if end != -1 else ""
+
+
+def _frontmatter_value(block: str, key: str) -> str | None:
+    m = re.search(rf"^{re.escape(key)}\s*:\s*(.+)$", block, re.MULTILINE)
+    if not m:
+        return None
+    val = m.group(1).strip()
+    if val.startswith('"') and val.endswith('"'):
+        val = val[1:-1]
+    return val
+
+
+def _frontmatter_list(block: str, key: str) -> List[str]:
+    m = re.search(rf"^{re.escape(key)}\s*:\s*$", block, re.MULTILINE)
+    if not m:
+        return []
+    items: List[str] = []
+    for line in block[m.end():].splitlines():
+        if line.startswith("  - "):
+            items.append(line[4:].strip())
+        elif line and not line.startswith(" "):
+            break
+    return items
+
+
+def _load_personas(personas_dir: Path) -> Dict[str, str]:
+    """slug → tier (core | specialist | unknown)."""
+    personas: Dict[str, str] = {}
+    if not personas_dir.is_dir():
+        return personas
+    for md in sorted(personas_dir.glob("*.md")):
+        if md.name.lower() == "readme.md":
+            continue
+        block = _read_block(md)
+        slug = _frontmatter_value(block, "id") or md.stem
+        tier = _frontmatter_value(block, "tier") or "unknown"
+        personas[slug] = tier
+    return personas
+
+
+def _count_citations(skills_dir: Path) -> Dict[str, int]:
+    counts: Dict[str, int] = {}
+    if not skills_dir.is_dir():
+        return counts
+    for skill_md in skills_dir.glob("*/SKILL.md"):
+        block = _read_block(skill_md)
+        for slug in _frontmatter_list(block, "personas"):
+            counts[slug] = counts.get(slug, 0) + 1
+    return counts
+
+
+def audit(skills_dir: Path, personas_dir: Path) -> List[Dict[str, object]]:
+    personas = _load_personas(personas_dir)
+    citations = _count_citations(skills_dir)
+    rows: List[Dict[str, object]] = []
+    for slug, tier in sorted(personas.items()):
+        count = citations.get(slug, 0)
+        threshold = THRESHOLDS.get(tier, 3)
+        status = "under-cited" if count < threshold else "ok"
+        rows.append({"persona": slug, "tier": tier, "citations": count,
+                     "threshold": threshold, "status": status})
+    # Surface citations that point at unknown personas (typos, deletions).
+    for slug in sorted(citations.keys()):
+        if slug not in personas:
+            rows.append({"persona": slug, "tier": "unknown",
+                         "citations": citations[slug], "threshold": 0,
+                         "status": "orphan"})
+    return rows
+
+
+def _print_human(rows: List[Dict[str, object]]) -> None:
+    if not rows:
+        print("(no personas found)")
+        return
+    width = max(len(str(r["persona"])) for r in rows)
+    print(f"  {'persona':<{width}}  tier        cites  status")
+    print(f"  {'-' * width}  ----------  -----  -----------")
+    for r in rows:
+        print(f"  {str(r['persona']):<{width}}  {str(r['tier']):<10}  "
+              f"{int(r['citations']):>5}  {r['status']}")
+    flagged = [r for r in rows if r["status"] != "ok"]
+    if flagged:
+        print(f"\n  {len(flagged)} persona(s) flagged "
+              f"(under-cited or orphan).")
+
+
+def main(argv: List[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n", 1)[0])
+    parser.add_argument("--skills-dir", default=str(DEFAULT_SKILLS))
+    parser.add_argument("--personas-dir", default=str(DEFAULT_PERSONAS))
+    parser.add_argument("--json", action="store_true",
+                        help="emit JSON instead of text")
+    args = parser.parse_args(argv)
+    rows = audit(Path(args.skills_dir), Path(args.personas_dir))
+    if args.json:
+        json.dump({"rows": rows}, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+    else:
+        _print_human(rows)
+    return 0
+
+
+_SAMPLE = {"thresholds": THRESHOLDS}
+
+if __name__ == "__main__":
+    raise SystemExit(main())