@event4u/agent-config 2.19.0 → 2.20.0

package/scripts/lint_archived_skills.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Lint archive notes under agents/archived-skills/.
+
+Enforces the contract from
+.agent-src.uncompressed/templates/skill-archive-note.md:
+
+  1. Every <slug>.md under agents/archived-skills/ has the six required
+     frontmatter fields with valid values.
+  2. `reason` is one of {unused, merged, superseded, deprecated}.
+  3. When `reason ∈ {merged, superseded}` the `replacement` slug exists
+     under .agent-src.uncompressed/skills/.
+  4. No archived slug still has a live SKILL.md (no zombies).
+  5. No live SKILL.md cites an archived slug as a router target in
+     its frontmatter `replaced_by:` field.
+
+Hooked into `task ci` via `task lint-archived-skills`. Passes cleanly
+against an empty agents/archived-skills/ (only README.md present).
+
+Exit codes:
+  0  contract holds
+  1  one or more violations
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+QUIET = "--quiet" in sys.argv
+
+REPO = Path(__file__).resolve().parents[1]
+ARCHIVE_DIR = REPO / "agents" / "archived-skills"
+SKILLS_DIR = REPO / ".agent-src.uncompressed" / "skills"
+
+REQUIRED_FIELDS = ("slug", "archived_on", "last_seen_count", "reason", "replacement", "last_known_callers")
+VALID_REASONS = frozenset({"unused", "merged", "superseded", "deprecated"})
+DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+
+def parse_frontmatter(text: str) -> dict[str, str] | None:
+    if not text.startswith("---\n"):
+        return None
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return None
+    fields: dict[str, str] = {}
+    for line in text[4:end].splitlines():
+        if ":" not in line or line.startswith(" ") or line.startswith("-"):
+            continue
+        k, _, v = line.partition(":")
+        fields[k.strip()] = v.strip().strip('"').strip("'")
+    return fields
+
+
+def archived_slugs() -> list[Path]:
+    return sorted(p for p in ARCHIVE_DIR.glob("*.md") if p.name != "README.md")
+
+
+def live_skill_slugs() -> set[str]:
+    return {p.name for p in SKILLS_DIR.iterdir() if p.is_dir() and (p / "SKILL.md").exists()}
+
+
+def main() -> int:
+    if not ARCHIVE_DIR.exists():
+        print(f"❌  lint_archived_skills: {ARCHIVE_DIR} missing", file=sys.stderr)
+        return 1
+
+    notes = archived_slugs()
+    live = live_skill_slugs()
+    errors: list[str] = []
+
+    archived_keys: set[str] = set()
+    for note in notes:
+        text = note.read_text(encoding="utf-8")
+        fm = parse_frontmatter(text)
+        slug_from_name = note.stem
+
+        if fm is None:
+            errors.append(f"{note.name}: missing or malformed frontmatter")
+            continue
+
+        missing = [f for f in REQUIRED_FIELDS if f not in fm]
+        if missing:
+            errors.append(f"{note.name}: missing required fields: {', '.join(missing)}")
+            continue
+
+        if fm["slug"] != slug_from_name:
+            errors.append(f"{note.name}: slug field '{fm['slug']}' != filename stem '{slug_from_name}'")
+
+        if not DATE_RE.match(fm["archived_on"]):
+            errors.append(f"{note.name}: archived_on '{fm['archived_on']}' is not YYYY-MM-DD")
+
+        if fm["reason"] not in VALID_REASONS:
+            errors.append(f"{note.name}: reason '{fm['reason']}' not in {sorted(VALID_REASONS)}")
+
+        try:
+            int(fm["last_seen_count"])
+        except ValueError:
+            errors.append(f"{note.name}: last_seen_count '{fm['last_seen_count']}' is not an integer")
+
+        replacement = fm["replacement"]
+        reason = fm["reason"]
+        if reason in {"merged", "superseded"}:
+            if replacement == "none" or not replacement:
+                errors.append(f"{note.name}: reason={reason} requires a replacement slug, got 'none'")
+            elif replacement not in live:
+                errors.append(f"{note.name}: replacement '{replacement}' not found under {SKILLS_DIR}")
+        elif reason in {"unused", "deprecated"}:
+            if replacement not in {"none", ""}:
+                if replacement not in live:
+                    errors.append(f"{note.name}: replacement '{replacement}' not found under {SKILLS_DIR}")
+
+        if fm["slug"] in live:
+            errors.append(f"{note.name}: slug '{fm['slug']}' still has a live SKILL.md (zombie)")
+
+        archived_keys.add(fm["slug"])
+
+    # Cross-check: live skills must not list an archived slug as replaced_by.
+    for skill_dir in sorted(SKILLS_DIR.iterdir()):
+        skill_md = skill_dir / "SKILL.md"
+        if not skill_md.exists():
+            continue
+        text = skill_md.read_text(encoding="utf-8")
+        fm = parse_frontmatter(text)
+        if fm is None:
+            continue
+        rb = fm.get("replaced_by", "").strip()
+        if rb and rb in archived_keys:
+            errors.append(f"{skill_dir.name}/SKILL.md: replaced_by '{rb}' points at an archived slug")
+
+    if errors:
+        print(f"❌  lint_archived_skills: {len(errors)} violation(s) across {len(notes)} note(s)", file=sys.stderr)
+        for e in errors:
+            print(f"    {e}", file=sys.stderr)
+        return 1
+
+    if not QUIET:
+        print(f"✅  lint_archived_skills: {len(notes)} archive note(s), contract holds")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/lint_bench_corpus.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""Lint benchmark corpora under tests/eval/corpus-*.yaml.
+
+Enforces the contract from docs/contracts/benchmark-corpus-spec.md:
+  - Required top-level keys (version, corpus_id, prompts) present.
+  - version == 1.
+  - selection_accuracy_target in [0.0, 1.0].
+  - Per-prompt schema (id format, category enum, language enum,
+    expected_skills non-empty + referencing real skills, destructive
+    prompts carry expected_carve_outs, prompt text non-empty).
+  - No duplicate ids within a corpus.
+
+Hooked into `task ci` via `task lint-bench`. Step-4 Phase 1 Step 3.
+
+Exit codes:
+  0  contract holds across every corpus
+  1  one or more violations
+  2  invocation error (missing PyYAML, no corpora found)
+
+Flags:
+  --quiet            suppress per-file OK lines
+  --require-full     also enforce 25-prompt composition (10/8/5/2)
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:
+    sys.stderr.write("error: PyYAML required (pip install pyyaml)\n")
+    sys.exit(2)
+
+QUIET = "--quiet" in sys.argv
+REQUIRE_FULL = "--require-full" in sys.argv
+
+REPO = Path(__file__).resolve().parents[1]
+CORPUS_DIR = REPO / "tests" / "eval"
+SKILLS_DIR = REPO / ".agent-src.uncompressed" / "skills"
+
+VALID_CATEGORIES = frozenset({"canonical", "ambiguous", "destructive", "long-context"})
+# Non-dev corpus (pre-spec) uses legacy categories — accept them so the
+# new linter does not break that file. Migration is a follow-up.
+LEGACY_CATEGORIES = frozenset({"content", "consulting", "finance", "ops", "safety"})
+VALID_LANGUAGES = frozenset({"en", "de"})
+VALID_VERSIONS = frozenset({1})
+ID_RE = re.compile(r"^[a-z][a-z0-9-]*-\d{2}$")
+FULL_COUNTS = {"canonical": 10, "ambiguous": 8, "destructive": 5, "long-context": 2}
+
+
+def live_skills() -> set[str]:
+    return {p.name for p in SKILLS_DIR.iterdir() if p.is_dir() and (p / "SKILL.md").exists()}
+
+
+def lint_corpus(path: Path, skills: set[str]) -> list[str]:
+    errors: list[str] = []
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        return [f"{path.name}: yaml_parse_error: {exc}"]
+
+    if not isinstance(data, dict):
+        return [f"{path.name}: missing_top_level: corpus must be a mapping"]
+
+    for key in ("version", "corpus_id", "prompts"):
+        if key not in data:
+            errors.append(f"{path.name}: missing_top_level: {key}")
+
+    if data.get("version") not in VALID_VERSIONS:
+        errors.append(f"{path.name}: unsupported_version: {data.get('version')!r}")
+
+    target = data.get("selection_accuracy_target")
+    if target is not None and not (isinstance(target, (int, float)) and 0.0 <= target <= 1.0):
+        errors.append(f"{path.name}: target_out_of_range: {target!r}")
+
+    prompts = data.get("prompts") or []
+    if not isinstance(prompts, list):
+        return errors + [f"{path.name}: missing_top_level: prompts must be a list"]
+
+    seen_ids: set[str] = set()
+    bucket_counts: dict[str, int] = {}
+    is_legacy = data.get("corpus_id") == "non-dev"
+    for idx, p in enumerate(prompts):
+        loc = f"{path.name}:#{idx}"
+        if not isinstance(p, dict):
+            errors.append(f"{loc}: bad_prompt_shape")
+            continue
+        pid = p.get("id")
+        if not isinstance(pid, str) or not ID_RE.match(pid):
+            errors.append(f"{loc}: bad_id_format: {pid!r}")
+        elif pid in seen_ids:
+            errors.append(f"{loc}: duplicate_id: {pid}")
+        else:
+            seen_ids.add(pid)
+
+        cat = p.get("category")
+        if cat not in VALID_CATEGORIES and not (is_legacy and cat in LEGACY_CATEGORIES):
+            errors.append(f"{loc}: bad_category: {cat!r}")
+        bucket_counts[cat] = bucket_counts.get(cat, 0) + 1
+
+        lang = p.get("language", "en")
+        if lang not in VALID_LANGUAGES:
+            errors.append(f"{loc}: bad_language: {lang!r}")
+
+        prompt_text = p.get("prompt", "")
+        if not isinstance(prompt_text, str) or not prompt_text.strip():
+            errors.append(f"{loc}: empty_prompt")
+
+        expected = p.get("expected_skills") or []
+        if not isinstance(expected, list) or not expected:
+            errors.append(f"{loc}: empty_expected")
+        else:
+            for slug in expected:
+                if slug not in skills:
+                    errors.append(f"{loc}: unknown_skill: {slug}")
+
+        if cat == "destructive":
+            carve = p.get("expected_carve_outs") or []
+            if not isinstance(carve, list) or not carve:
+                errors.append(f"{loc}: missing_carve_out")
+
+    if REQUIRE_FULL and not is_legacy:
+        for bucket, want in FULL_COUNTS.items():
+            have = bucket_counts.get(bucket, 0)
+            if have != want:
+                errors.append(f"{path.name}: composition_drift: {bucket} have={have} want={want}")
+
+    return errors
+
+
+def main() -> int:
+    if not CORPUS_DIR.is_dir():
+        sys.stderr.write(f"error: corpus dir missing: {CORPUS_DIR}\n")
+        return 2
+    corpora = sorted(CORPUS_DIR.glob("corpus-*.yaml"))
+    if not corpora:
+        sys.stderr.write("error: no corpora found\n")
+        return 2
+
+    skills = live_skills()
+    all_errors: list[str] = []
+    for path in corpora:
+        errs = lint_corpus(path, skills)
+        if errs:
+            all_errors.extend(errs)
+        elif not QUIET:
+            print(f"✅  {path.name}: contract OK")
+
+    if all_errors:
+        for err in all_errors:
+            print(f"❌  {err}", file=sys.stderr)
+        return 1
+    if not QUIET:
+        print(f"✅  lint-bench: {len(corpora)} corpora clean")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_namespace.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Namespace linter. Enforces `<stem>-<intent>` kebab-case + reserved
+names list across skills / rules / commands / personas.
+
+Contract: docs/contracts/namespace.md.
+Wired into: `task lint-skills` (taskfiles/ci-fast.yml).
+"""
+from __future__ import annotations
+import argparse, re, sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SRC = ROOT / ".agent-src.uncompressed"
+
+# Source-of-truth regex; mirrored in docs/contracts/namespace.md § 1.
+NAME_RE = re.compile(r"^[a-z][a-z0-9]*(-[a-z0-9]+)*$")
+
+MIN_LEN = 2
+MIN_LEN_SKILL = 3
+MAX_LEN = 64
+
+RESERVED = {"pattern", "claude-memories", "default", "index", "router"}
+
+# Filenames that are documentation, not artefacts.
+NON_ARTEFACTS = {"README.md", "INDEX.md"}
+
+# (kind, root, glob, depth, sub_verb) — depth tells us how to extract
+# the name. depth=0 → file stem; depth=1 → first directory under root.
+# sub_verb=True → the path is a `<group>/<verb>.md` form; reserved-name
+# check is skipped because the verb is namespaced under the group.
+TARGETS = [
+    ("skill",    SRC / "skills",    "*/SKILL.md", 1, False),
+    ("rule",     SRC / "rules",     "*.md",       0, False),
+    ("command",  SRC / "commands",  "*.md",       0, False),
+    ("command",  SRC / "commands",  "*/*.md",     0, True),
+    ("persona",  SRC / "personas",  "*.md",       0, False),
+]
+
+
+def _name_for(path: Path, root: Path, depth: int) -> str:
+    if depth == 0:
+        return path.stem
+    rel = path.relative_to(root)
+    return rel.parts[0]
+
+
+def _shape_errors(name: str, *, sub_verb: bool = False,
+                  kind: str = "command") -> list[str]:
+    errs = []
+    floor = MIN_LEN_SKILL if kind == "skill" else MIN_LEN
+    if not (floor <= len(name) <= MAX_LEN):
+        errs.append(f"length — {len(name)} chars (must be {floor}–{MAX_LEN})")
+    if not NAME_RE.match(name):
+        errs.append("regex — must match ^[a-z][a-z0-9]*(-[a-z0-9]+)*$")
+    if name in RESERVED and not sub_verb:
+        errs.append(f"reserved — '{name}' in reserved-names list")
+    return errs
+
+
+def _skill_name_field(path: Path) -> str | None:
+    """Read `name:` from skill frontmatter. None on missing / unparseable."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except Exception:
+        return None
+    if not text.startswith("---"):
+        return None
+    end = text.find("\n---", 3)
+    if end < 0:
+        return None
+    fm = text[3:end]
+    for line in fm.splitlines():
+        m = re.match(r"^name:\s*['\"]?([^'\"]+)['\"]?\s*$", line.strip())
+        if m:
+            return m.group(1).strip()
+    return None
+
+
+def scan() -> tuple[int, int]:
+    issues = 0
+    checked = 0
+    seen: set[tuple[str, str]] = set()
+    for kind, root, glob, depth, sub_verb in TARGETS:
+        if not root.is_dir():
+            continue
+        for path in sorted(root.glob(glob)):
+            if path.name in NON_ARTEFACTS:
+                continue
+            name = _name_for(path, root, depth)
+            key = (kind, str(path.relative_to(root)))
+            if key in seen:
+                continue
+            seen.add(key)
+            checked += 1
+            errs = _shape_errors(name, sub_verb=sub_verb, kind=kind)
+            if kind == "skill":
+                fm_name = _skill_name_field(path)
+                if fm_name and fm_name != name:
+                    errs.append(f"skill — frontmatter name='{fm_name}' != dir '{name}'")
+            for e in errs:
+                rel = path.relative_to(ROOT)
+                print(f"❌ {rel}: {e}", file=sys.stderr)
+                issues += 1
+    return checked, issues
+
+
+def check_single(name: str) -> int:
+    errs = _shape_errors(name)
+    if not errs:
+        print(f"✅ '{name}' is a valid artefact name")
+        return 0
+    for e in errs:
+        print(f"❌ '{name}': {e}", file=sys.stderr)
+    return 1
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--name", help="Check a single candidate name and exit.")
+    ap.add_argument("--quiet", action="store_true",
+                    help="Suppress the summary line on success.")
+    args = ap.parse_args()
+    if args.name:
+        return check_single(args.name)
+    checked, issues = scan()
+    if issues:
+        print(f"BASELINE: {issues} issue(s) across {checked} name(s)", file=sys.stderr)
+        return 1
+    if not args.quiet:
+        print(f"BASELINE: 0 issues · {checked} name(s) checked")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/skill_overlap.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+"""Structural overlap detection across skills (description + triggers).
+
+Implements step-2-skill-inventory-rationalization.md Phase 2 Step 2.
+Mirrors `scripts/audit_overlap.py` (the rule-side analog) but reads
+`.agent-src.uncompressed/skills/<slug>/SKILL.md` frontmatter directly
+and emits `agents/metrics/skill-overlap.md` listing pairs scoring
+≥ 0.6 on either:
+
+  - description-trigger Jaccard (tokenized union of `description` +
+    any `triggers:` / `keywords:` / `intents:` frontmatter values);
+  - symbol-set overlap (paths cited inside the SKILL.md body —
+    `.agent-src.uncompressed/...`, `agents/...`, `scripts/...`).
+
+The 0.6 threshold matches the roadmap; the rule-side script uses
+lower thresholds because rules have richer trigger metadata. Skills
+encode most signal in prose, so we raise the bar.
+
+Output is **a baseline, not a verdict**. Phase 2 Step 3 combines this
+report with the 30-day activation counts before any action.
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from itertools import combinations
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+SKILLS = REPO / ".agent-src.uncompressed" / "skills"
+OUT = REPO / "agents" / "metrics" / "skill-overlap.md"
+
+# Roadmap target. Empirical calibration (210 skills, 2026-05-16) shows
+# this threshold catches structural carbon-copies only — known-similar
+# pairs like blade-ui / flux land around 0.35 token-jaccard because
+# skill descriptions encode distinct trigger language by design.
+STRONG_TOKEN = 0.6
+STRONG_SYMBOL = 0.6
+# Calibrated review threshold — flags pairs worth a Phase 2 Step 3
+# review without exceeding signal-to-noise. Below this, descriptions
+# diverge enough that overlap is coincidental.
+CANDIDATE_TOKEN = 0.30
+CANDIDATE_SYMBOL = 0.50
+# Symbol-jaccard is noisy below this floor — two skills sharing a single
+# context-spine reference produce 1.0 with no signal. Require a non-trivial
+# symbol set on both sides before the symbol axis counts as evidence.
+SYMBOL_MIN_SET = 4
+
+STOPWORDS = {
+    "the", "and", "for", "with", "when", "use", "or", "of", "to", "a", "an",
+    "is", "in", "on", "by", "be", "at", "as", "it", "if", "are", "this",
+    "that", "from", "but", "not", "can", "any", "all", "no", "after",
+    "before", "during", "user", "agent", "code", "project", "via", "into",
+    "onto", "even", "without", "naming", "skill", "skills", "rule", "rules",
+    "command", "commands", "guideline", "guidelines",
+}
+
+PATH_RE = re.compile(r"`?(?:\.agent-src(?:\.uncompressed)?|agents|scripts|docs|tests|\.augment|\.claude)/[A-Za-z0-9_./-]+`?")
+TOKEN_RE = re.compile(r"[A-Za-z][A-Za-z0-9_-]{2,}")
+
+
+def parse_frontmatter(text: str) -> tuple[dict, str]:
+    if not text.startswith("---"):
+        return {}, text
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        return {}, text
+    fm_raw, body = parts[1], parts[2]
+    fm: dict[str, str] = {}
+    current_key: str | None = None
+    buf: list[str] = []
+    for line in fm_raw.splitlines():
+        if not line.strip():
+            continue
+        if line.startswith(" ") and current_key is not None:
+            buf.append(line.strip())
+            continue
+        if current_key is not None:
+            fm[current_key] = " ".join(buf) if buf else fm.get(current_key, "")
+        if ":" in line:
+            k, v = line.split(":", 1)
+            current_key, buf = k.strip(), []
+            v = v.strip()
+            if v:
+                fm[current_key] = v.strip().strip('"').strip("'")
+                current_key = None
+    if current_key is not None and buf:
+        fm[current_key] = " ".join(buf)
+    return fm, body
+
+
+def tokenize(text: str) -> set[str]:
+    return {t.lower() for t in TOKEN_RE.findall(text or "")
+            if t.lower() not in STOPWORDS and not t.isdigit() and len(t) > 2}
+
+
+def symbol_set(body: str) -> set[str]:
+    return {m.strip("`") for m in PATH_RE.findall(body or "")}
+
+
+def jaccard(a: set, b: set) -> float:
+    if not a and not b:
+        return 0.0
+    return len(a & b) / len(a | b)
+
+
+def load_skills(root: Path) -> list[dict]:
+    skills: list[dict] = []
+    if not root.is_dir():
+        return skills
+    for skill_md in sorted(root.glob("*/SKILL.md")):
+        slug = skill_md.parent.name
+        text = skill_md.read_text(encoding="utf-8", errors="replace")
+        fm, body = parse_frontmatter(text)
+        desc = fm.get("description", "")
+        trig = " ".join(fm.get(k, "") for k in ("triggers", "keywords", "intents", "domain"))
+        skills.append({
+            "slug": slug,
+            "tokens": tokenize(desc + " " + trig),
+            "symbols": symbol_set(body),
+        })
+    return skills
+
+
+def analyse(skills: list[dict]) -> list[dict]:
+    pairs: list[dict] = []
+    for a, b in combinations(skills, 2):
+        j = jaccard(a["tokens"], b["tokens"])
+        if min(len(a["symbols"]), len(b["symbols"])) >= SYMBOL_MIN_SET:
+            s = jaccard(a["symbols"], b["symbols"])
+        else:
+            s = 0.0
+        if j >= STRONG_TOKEN or s >= STRONG_SYMBOL:
+            tier = "strong"
+        elif j >= CANDIDATE_TOKEN or s >= CANDIDATE_SYMBOL:
+            tier = "candidate"
+        else:
+            continue
+        pairs.append({
+            "skill_a": a["slug"], "skill_b": b["slug"],
+            "tier": tier,
+            "description_jaccard": round(j, 3),
+            "symbol_jaccard": round(s, 3),
+        })
+    pairs.sort(key=lambda p: (p["tier"] != "strong",
+                              -max(p["description_jaccard"], p["symbol_jaccard"])))
+    return pairs
+
+
+def render(pairs: list[dict], total: int) -> str:
+    strong = [p for p in pairs if p["tier"] == "strong"]
+    candidate = [p for p in pairs if p["tier"] == "candidate"]
+    lines = [
+        "# Skill Structural Overlap (baseline)",
+        "",
+        "> Generated by `scripts/skill_overlap.py`. Scans",
+        "> `.agent-src.uncompressed/skills/*/SKILL.md` frontmatter (description +",
+        "> trigger metadata) and body symbol references. Reports pairs in two",
+        f"> tiers: **strong** ≥ {STRONG_TOKEN} description-token Jaccard or ≥ {STRONG_SYMBOL}",
+        f"> symbol-set Jaccard (roadmap floor); **candidate** ≥ {CANDIDATE_TOKEN} / ≥ {CANDIDATE_SYMBOL}",
+        "> (empirical calibration — skill descriptions encode distinct trigger",
+        "> language by design, so the roadmap floor catches structural carbon-",
+        "> copies only). See [`step-2-skill-inventory-rationalization.md`](../roadmaps/step-2-skill-inventory-rationalization.md)",
+        "> Phase 2 Step 2.",
+        "",
+        f"**Skills scanned:** {total} · **Strong pairs:** {len(strong)} · "
+        f"**Candidate pairs:** {len(candidate)}",
+        "",
+        "| # | skill_a | skill_b | tier | desc_jaccard | symbol_jaccard |",
+        "|---|---|---|---|---|---|",
+    ]
+    for i, p in enumerate(pairs, 1):
+        lines.append(f"| {i} | `{p['skill_a']}` | `{p['skill_b']}` | {p['tier']} | "
+                     f"{p['description_jaccard']} | {p['symbol_jaccard']} |")
+    lines.append("")
+    lines.append("**Read-out:** `strong` pairs are first-cut merge / supersede candidates. "
+                 "`candidate` pairs are worth a Phase 2 Step 3 review but the description "
+                 "signal is faint — usage data (30-day activation report) is the deciding "
+                 "input, not this report. Structural overlap alone is evidence, not a verdict.")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--out", type=Path, default=OUT)
+    ap.add_argument("--quiet", action="store_true")
+    args = ap.parse_args()
+    skills = load_skills(SKILLS)
+    if not skills:
+        print(f"no skills under {SKILLS}", file=sys.stderr)
+        return 1
+    pairs = analyse(skills)
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    args.out.write_text(render(pairs, len(skills)), encoding="utf-8")
+    if not args.quiet:
+        print(f"✅  Wrote {args.out.relative_to(REPO)} "
+              f"({len(skills)} skills, {len(pairs)} pair(s) flagged)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())