@event4u/agent-config 5.10.1 → 6.1.0

package/scripts/audit_likelihood.py

@@ -1,148 +0,0 @@
-#!/usr/bin/env python3
-"""Activation-likelihood heuristic for the Rule-Governance pass
-(Phase 5.3 of road-to-augment-limit-fit).
-
-For every auto-rule from `agents/runtime/reports/auto-rules-audit.json`:
-
-1. Build a token set from `description`, `triggers[].keyword`,
-   `triggers[].intent`, and the rule name itself.
-2. Index a corpus of skills (`SKILL.md`), contexts
-   (`agents/settings/contexts/**/*.md`), guidelines, and command files.
-3. Score `corpus_hits = sum(1 for token in tokens if token in corpus)`.
-4. Flag rules with `< 2` corpus hits as "low-likelihood" (their trigger
-   surface is so generic that the host LLM is unlikely to find a
-   project-local file the rule was written to bridge to).
-
-Result is a JSON dump + Markdown section appended to
-`agents/runtime/reports/auto-rules-audit.md`.
-"""
-
-from __future__ import annotations
-
-import json
-import re
-import sys
-from collections import Counter
-from pathlib import Path
-
-REPO_ROOT = Path(__file__).resolve().parent.parent
-REPORT_DIR = REPO_ROOT / "agents" / "reports"
-AUDIT_JSON = REPORT_DIR / "auto-rules-audit.json"
-AUDIT_MD = REPORT_DIR / "auto-rules-audit.md"
-LIKELIHOOD_JSON = REPORT_DIR / "auto-rules-likelihood.json"
-
-CORPUS_GLOBS = [
-    ".agent-src.uncondensed/skills/**/SKILL.md",
-    ".agent-src.uncondensed/commands/**/*.md",
-    "agents/settings/contexts/**/*.md",
-    "docs/guidelines/**/*.md",
-]
-
-LOW_LIKELIHOOD_HITS = 2
-
-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", "rule", "rules",
-    "skill", "skills", "command", "commands", "files", "file", "doc",
-    "docs", "md", "txt",
-}
-
-
-def tokens(text: str) -> set[str]:
-    raw = re.findall(r"[A-Za-z][A-Za-z0-9_-]{2,}", text.lower())
-    return {t for t in raw if t not in STOPWORDS and len(t) > 3}
-
-
-def build_corpus() -> Counter:
-    counter: Counter = Counter()
-    for glob in CORPUS_GLOBS:
-        for path in REPO_ROOT.glob(glob):
-            if not path.is_file():
-                continue
-            try:
-                text = path.read_text(encoding="utf-8")
-            except UnicodeDecodeError:
-                continue
-            for tok in tokens(text):
-                counter[tok] += 1
-    return counter
-
-
-def score(rule: dict, corpus: Counter) -> dict:
-    rule_tokens = (
-        tokens(rule["description"])
-        | tokens(rule["name"].replace("-", " "))
-        | tokens(" ".join(rule["triggers"]["keywords"]))
-        | tokens(" ".join(rule["triggers"]["intents"]))
-    )
-    hits = {t: corpus[t] for t in rule_tokens if corpus[t] > 0}
-    return {
-        "name": rule["name"],
-        "tokens": sorted(rule_tokens),
-        "hits": dict(sorted(hits.items(), key=lambda x: -x[1])[:8]),
-        "hit_count": len(hits),
-        "total_hit_volume": sum(hits.values()),
-        "low_likelihood": len(hits) < LOW_LIKELIHOOD_HITS,
-    }
-
-
-def render_md(scores: list[dict]) -> str:
-    flagged = [s for s in scores if s["low_likelihood"]]
-    lines = [
-        "",
-        "## Phase 5.3 — Activation likelihood (corpus-keyword)",
-        "",
-        f"Corpus: skills + commands + contexts + guidelines.",
-        f"Low-likelihood threshold: `< {LOW_LIKELIHOOD_HITS}` distinct corpus hits.",
-        "",
-        f"Rules flagged: **{len(flagged)} / {len(scores)}**.",
-        "",
-        "### Low-likelihood rules",
-        "",
-    ]
-    if not flagged:
-        lines += ["_None._", ""]
-    else:
-        lines += ["| Rule | Hits | Tokens (top) |", "|------|------|--------------|"]
-        for s in sorted(flagged, key=lambda x: x["hit_count"]):
-            toks = ", ".join(f"`{t}`" for t in s["tokens"][:6]) or "—"
-            lines.append(f"| `{s['name']}` | {s['hit_count']} | {toks} |")
-        lines.append("")
-    lines += [
-        "### Full ranking (lowest hit-count first, top 20)",
-        "",
-        "| Rule | Distinct hits | Total hit volume |",
-        "|------|---------------|------------------|",
-    ]
-    for s in sorted(scores, key=lambda x: (x["hit_count"], x["total_hit_volume"]))[:20]:
-        lines.append(f"| `{s['name']}` | {s['hit_count']} | {s['total_hit_volume']} |")
-    lines.append("")
-    return "\n".join(lines)
-
-
-def main() -> int:
-    if not AUDIT_JSON.exists():
-        print(f"❌  Run audit_auto_rules.py first: missing {AUDIT_JSON}", file=sys.stderr)
-        return 1
-    rules = json.loads(AUDIT_JSON.read_text(encoding="utf-8"))["rules"]
-    corpus = build_corpus()
-    scores = [score(r, corpus) for r in rules]
-    LIKELIHOOD_JSON.write_text(
-        json.dumps({"corpus_size": len(corpus), "scores": scores}, indent=2),
-        encoding="utf-8",
-    )
-    md = AUDIT_MD.read_text(encoding="utf-8") if AUDIT_MD.exists() else ""
-    if "## Phase 5.3 — Activation likelihood" in md:
-        md = md.split("## Phase 5.3 — Activation likelihood")[0].rstrip() + "\n"
-    AUDIT_MD.write_text(md + render_md(scores), encoding="utf-8")
-    flagged = [s for s in scores if s["low_likelihood"]]
-    print(f"✅  Likelihood scored: {len(scores)} rules, {len(flagged)} low-likelihood.")
-    print(f"   JSON: {LIKELIHOOD_JSON.relative_to(REPO_ROOT)}")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/scripts/audit_mcp_tools.py

@@ -1,146 +0,0 @@
-#!/usr/bin/env python3
-"""MCP-tool inventory generator. Reads the source-of-truth catalog at
-`scripts/mcp_server/consumer_tool_catalog.json` and the handler
-registry at `scripts/mcp_server/tools.py`, emits
-`docs/contracts/mcp-tool-inventory.md` with every tool cited by
-`<file>:<line>`. README's MCP-tool count line links here; the bare
-claim is banned.
-
-Contract: step-11 Phase 5 Step 3
-(agents/roadmaps/step-11-ruflo-parity.md).
-
-Modes:
-  --check    exit non-zero if the generated inventory drifts from
-             the on-disk file (CI gate).
-  --write    regenerate the inventory file in-place (default).
-"""
-from __future__ import annotations
-import argparse, json, re, sys
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parent.parent
-CATALOG = ROOT / "scripts/mcp_server/consumer_tool_catalog.json"
-TOOLS_PY = ROOT / "scripts/mcp_server/tools.py"
-OUT = ROOT / "docs/contracts/mcp-tool-inventory.md"
-
-# Match `"<name>": BuiltinTool(` in the ALLOWLIST dict.
-HANDLER_RE = re.compile(r'^\s*"([a-z_]+)"\s*:\s*BuiltinTool\(')
-# Match `"name": "<name>",` in the catalog json (for catalog citations).
-CATALOG_NAME_RE = re.compile(r'^\s*"name"\s*:\s*"([a-z_]+)"\s*,?\s*$')
-
-
-def _index_handlers() -> dict[str, int]:
-    out: dict[str, int] = {}
-    for i, line in enumerate(TOOLS_PY.read_text(encoding="utf-8").splitlines(), 1):
-        m = HANDLER_RE.match(line)
-        if m:
-            out[m.group(1)] = i
-    return out
-
-
-def _index_catalog_lines() -> dict[str, int]:
-    out: dict[str, int] = {}
-    for i, line in enumerate(CATALOG.read_text(encoding="utf-8").splitlines(), 1):
-        m = CATALOG_NAME_RE.match(line)
-        if m and m.group(1) not in out:
-            out[m.group(1)] = i
-    return out
-
-
-def _render(catalog: dict, handlers: dict[str, int], cat_lines: dict[str, int]) -> str:
-    tools = catalog["tools"]
-    total = len(tools)
-    by_transport: dict[str, int] = {}
-    by_side_effect: dict[str, int] = {}
-    for t in tools:
-        for tr in t["implemented_on"]:
-            by_transport[tr] = by_transport.get(tr, 0) + 1
-        by_side_effect[t["side_effect"]] = by_side_effect.get(t["side_effect"], 0) + 1
-    stub_count = sum(1 for t in tools if not t["implemented_on"])
-    transport_summary = ", ".join(f"{k}={v}" for k, v in sorted(by_transport.items())) or "none"
-    side_effect_summary = ", ".join(f"{k}={v}" for k, v in sorted(by_side_effect.items()))
-
-    lines: list[str] = []
-    lines.append("---")
-    lines.append("stability: beta")
-    lines.append("keep-beta-until: 2026-08-14")
-    lines.append("---")
-    lines.append("")
-    lines.append("# MCP tool inventory")
-    lines.append("")
-    lines.append("> Generated by [`scripts/audit_mcp_tools.py`](../../scripts/audit_mcp_tools.py)")
-    lines.append("> from the source-of-truth catalog")
-    lines.append("> [`scripts/mcp_server/consumer_tool_catalog.json`](../../scripts/mcp_server/consumer_tool_catalog.json).")
-    lines.append("> Do **not** hand-edit; rerun `python3 scripts/audit_mcp_tools.py --write`.")
-    lines.append(">")
-    lines.append("> Step-11 Phase 5 Step 3 (`step-11-ruflo-parity.md`).")
-    lines.append("")
-    lines.append("## Summary")
-    lines.append("")
-    lines.append(f"- **Total tools:** {total}")
-    lines.append(f"- **By transport:** {transport_summary}")
-    lines.append(f"- **By side-effect:** {side_effect_summary}")
-    lines.append(f"- **Discovery-only stubs (no implementation):** {stub_count}")
-    lines.append("")
-    lines.append("## Tools")
-    lines.append("")
-    lines.append("| Tool | Side-effect | Transports | Catalog | Handler |")
-    lines.append("|---|---|---|---|---|")
-    for t in tools:
-        name = t["name"]
-        side = t["side_effect"]
-        transports = ", ".join(t["implemented_on"]) if t["implemented_on"] else "_(stub)_"
-        cat_line = cat_lines.get(name)
-        cat_cite = (
-            f"[`consumer_tool_catalog.json:{cat_line}`](../../scripts/mcp_server/consumer_tool_catalog.json#L{cat_line})"
-            if cat_line else "_missing_"
-        )
-        h_line = handlers.get(name)
-        h_cite = (
-            f"[`tools.py:{h_line}`](../../scripts/mcp_server/tools.py#L{h_line})"
-            if h_line else "_stub-only_"
-        )
-        lines.append(f"| `{name}` | `{side}` | {transports} | {cat_cite} | {h_cite} |")
-    lines.append("")
-    lines.append("## Glossary")
-    lines.append("")
-    lines.append("- **Side-effect** — `ro` (read-only) · `fs-write` (filesystem write) · `shell` (spawns processes).")
-    lines.append("- **Transports** — `stdio` (`scripts/mcp_server/`) · `worker` (`internal/workers/mcp/`). A tool may live on both.")
-    lines.append("- **Stub** — catalog-listed for discovery; returns the `not_implemented` envelope from")
-    lines.append("  [`mcp-tool-stub-envelope.md`](mcp-tool-stub-envelope.md) until promoted.")
-    lines.append("")
-    return "\n".join(lines) + "\n"
-
-
-def main() -> int:
-    ap = argparse.ArgumentParser(description=__doc__)
-    g = ap.add_mutually_exclusive_group()
-    g.add_argument("--check", action="store_true", help="Drift gate: exit 1 if file is stale.")
-    g.add_argument("--write", action="store_true", help="Regenerate the inventory file.")
-    ap.add_argument("--quiet", action="store_true")
-    args = ap.parse_args()
-
-    catalog = json.loads(CATALOG.read_text(encoding="utf-8"))
-    handlers = _index_handlers()
-    cat_lines = _index_catalog_lines()
-    rendered = _render(catalog, handlers, cat_lines)
-
-    if args.check:
-        on_disk = OUT.read_text(encoding="utf-8") if OUT.exists() else ""
-        if on_disk != rendered:
-            print(f"❌ {OUT.relative_to(ROOT)} drifted from generator.", file=sys.stderr)
-            print("   Run: python3 scripts/audit_mcp_tools.py --write", file=sys.stderr)
-            return 1
-        if not args.quiet:
-            print(f"BASELINE: {OUT.relative_to(ROOT)} is in sync · {len(catalog['tools'])} tool(s)")
-        return 0
-
-    OUT.parent.mkdir(parents=True, exist_ok=True)
-    OUT.write_text(rendered, encoding="utf-8")
-    if not args.quiet:
-        print(f"✅ wrote {OUT.relative_to(ROOT)} · {len(catalog['tools'])} tool(s)")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/scripts/audit_overlap.py

@@ -1,145 +0,0 @@
-#!/usr/bin/env python3
-"""Trigger-overlap analysis for the Rule-Governance pass (Phase 5.2 of
-road-to-augment-limit-fit).
-
-Reads `agents/runtime/reports/auto-rules-audit.json` (produced by
-`audit_auto_rules.py`) and computes:
-
-- path-prefix Jaccard similarity (per pair of rules);
-- description-keyword overlap fraction (per pair of rules).
-
-Pairs scoring `path_jaccard >= 0.5` OR `keyword_overlap >= 0.4` are
-flagged as merge candidates. Output is appended to
-`agents/runtime/reports/auto-rules-audit.md` and a structured JSON list is
-written to `agents/runtime/reports/auto-rules-overlap.json` for downstream
-consumers (Phase 5.3 likelihood, 5.4 council walk).
-"""
-
-from __future__ import annotations
-
-import json
-import re
-import sys
-from itertools import combinations
-from pathlib import Path
-
-REPO_ROOT = Path(__file__).resolve().parent.parent
-REPORT_DIR = REPO_ROOT / "agents" / "reports"
-AUDIT_JSON = REPORT_DIR / "auto-rules-audit.json"
-AUDIT_MD = REPORT_DIR / "auto-rules-audit.md"
-OVERLAP_JSON = REPORT_DIR / "auto-rules-overlap.json"
-
-PATH_THRESHOLD = 0.5
-KEYWORD_THRESHOLD = 0.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",
-}
-
-
-def keyword_set(text: str) -> set[str]:
-    tokens = re.findall(r"[A-Za-z][A-Za-z0-9_-]{2,}", text.lower())
-    return {t for t in tokens if t not in STOPWORDS and not t.isdigit()}
-
-
-def jaccard(a: set, b: set) -> float:
-    if not a and not b:
-        return 0.0
-    return len(a & b) / len(a | b)
-
-
-def overlap_fraction(a: set, b: set) -> float:
-    """Symmetric overlap as fraction of smaller set."""
-    if not a or not b:
-        return 0.0
-    return len(a & b) / min(len(a), len(b))
-
-
-def analyse(rules: list[dict]) -> list[dict]:
-    pairs: list[dict] = []
-    for r in rules:
-        r["_paths"] = set(r["triggers"]["path_prefixes"])
-        r["_keywords"] = (
-            keyword_set(r["description"])
-            | keyword_set(" ".join(r["triggers"]["keywords"]))
-            | keyword_set(" ".join(r["triggers"]["intents"]))
-        )
-
-    for a, b in combinations(rules, 2):
-        pj = jaccard(a["_paths"], b["_paths"])
-        ko = overlap_fraction(a["_keywords"], b["_keywords"])
-        flagged = pj >= PATH_THRESHOLD or ko >= KEYWORD_THRESHOLD
-        if not flagged:
-            continue
-        pairs.append(
-            {
-                "rule_a": a["name"],
-                "rule_b": b["name"],
-                "path_jaccard": round(pj, 3),
-                "keyword_overlap": round(ko, 3),
-                "shared_paths": sorted(a["_paths"] & b["_paths"]),
-                "shared_keywords": sorted(a["_keywords"] & b["_keywords"])[:12],
-                "rule_a_desc": a["description"],
-                "rule_b_desc": b["description"],
-            }
-        )
-
-    return sorted(
-        pairs, key=lambda p: -(p["path_jaccard"] + p["keyword_overlap"])
-    )
-
-
-def render_md(pairs: list[dict]) -> str:
-    lines = [
-        "",
-        "## Phase 5.2 — Trigger overlap (Jaccard + keyword)",
-        "",
-        f"Pairs flagged: **{len(pairs)}** "
-        f"(thresholds: path-Jaccard ≥ {PATH_THRESHOLD}, "
-        f"keyword-overlap ≥ {KEYWORD_THRESHOLD}).",
-        "",
-    ]
-    if not pairs:
-        lines.append("_No pairs over threshold._")
-        lines.append("")
-        return "\n".join(lines)
-    lines += [
-        "| # | Rule A | Rule B | Path-J | Keyword-O | Shared keywords |",
-        "|---|--------|--------|--------|-----------|-----------------|",
-    ]
-    for i, p in enumerate(pairs, 1):
-        kw = ", ".join(f"`{k}`" for k in p["shared_keywords"][:6]) or "—"
-        lines.append(
-            f"| {i} | `{p['rule_a']}` | `{p['rule_b']}` | "
-            f"{p['path_jaccard']:.2f} | {p['keyword_overlap']:.2f} | {kw} |"
-        )
-    lines.append("")
-    return "\n".join(lines)
-
-
-def main() -> int:
-    if not AUDIT_JSON.exists():
-        print(f"❌  Run audit_auto_rules.py first: missing {AUDIT_JSON}", file=sys.stderr)
-        return 1
-    data = json.loads(AUDIT_JSON.read_text(encoding="utf-8"))
-    pairs = analyse(data["rules"])
-    OVERLAP_JSON.write_text(
-        json.dumps({"pair_count": len(pairs), "pairs": pairs}, indent=2),
-        encoding="utf-8",
-    )
-    md_existing = AUDIT_MD.read_text(encoding="utf-8") if AUDIT_MD.exists() else ""
-    if "## Phase 5.2 — Trigger overlap" in md_existing:
-        md_existing = md_existing.split("## Phase 5.2 — Trigger overlap")[0].rstrip() + "\n"
-    AUDIT_MD.write_text(md_existing + render_md(pairs), encoding="utf-8")
-    print(f"✅  Overlap analysis: {len(pairs)} pairs flagged.")
-    print(f"   JSON: {OVERLAP_JSON.relative_to(REPO_ROOT)}")
-    print(f"   MD appended: {AUDIT_MD.relative_to(REPO_ROOT)}")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/scripts/audit_skill_descriptions.py

@@ -1,180 +0,0 @@
-#!/usr/bin/env python3
-"""
-Audit skill descriptions for triggering quality.
-
-Flags descriptions that are:
-  - too short (< 150 chars) or too long (> 200 chars, the linter limit)
-  - missing an explicit trigger verb prefix ("use when", "use if", "creates", ...)
-  - containing hedge terms ("may help", "can be useful", "covers various", ...)
-
-Context:
-  `archive/road-to-anthropic-alignment.md` Phase 2.2 — "pushy description" pattern from
-  anthropics/skills/skills/skill-creator (roadmap archived 2026-04-21).
-
-Usage:
-  python3 scripts/audit_skill_descriptions.py               # human table
-  python3 scripts/audit_skill_descriptions.py --json        # machine-readable
-  python3 scripts/audit_skill_descriptions.py --root DIR    # audit another tree
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import re
-import sys
-from dataclasses import asdict, dataclass, field
-from pathlib import Path
-from typing import List
-
-sys.path.insert(0, str(Path(__file__).resolve().parent))
-from _lib.agent_src import artefact_roots  # noqa: E402
-
-DEFAULT_ROOT: Path | None = None
-MIN_LENGTH = 150
-# Mirrors scripts/skill_linter.py `description_too_long` threshold.
-MAX_LENGTH = 200
-
-FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---", re.DOTALL)
-DESCRIPTION_RE = re.compile(r'^description:\s*"?(.*?)"?\s*$', re.MULTILINE)
-
-TRIGGER_PREFIX_RE = re.compile(
-    r"^\s*("
-    r"use\s+(when|if|for)\b|only\s+when\b|"
-    r"creates?\b|reviews?\b|writes?\b|handles?\b|generates?\b|runs?\b|"
-    r"builds?\b|fetches?\b|validates?\b|audits?\b|analyzes?\b|detects?\b|"
-    r"plans?\b|deploys?\b|configures?\b|scaffolds?\b|fixes?\b|refactors?\b|"
-    r"optimizes?\b|renders?\b|syncs?\b|explores?\b|installs?\b|updates?\b|"
-    r"manages?\b|orchestrates?\b|prepares?\b|finds?\b|executes?\b|reads?\b|"
-    r"checks?\b|tracks?\b"
-    r")",
-    re.IGNORECASE,
-)
-
-HEDGE_PHRASES = (
-    "may help",
-    "can be useful",
-    "covers various",
-    "might be",
-    "generally",
-    "as needed",
-    "when appropriate",
-)
-
-
-@dataclass
-class Finding:
-    skill: str
-    path: str
-    description: str
-    length: int
-    flags: List[str] = field(default_factory=list)
-
-    @property
-    def score(self) -> int:
-        # Higher score = worse. Used for sorting.
-        penalty = 0
-        if "no-trigger-prefix" in self.flags:
-            penalty += 30
-        if "too-short" in self.flags:
-            penalty += 20
-        if "very-short" in self.flags:
-            penalty += 10
-        penalty += sum(10 for f in self.flags if f.startswith("hedge:"))
-        return penalty
-
-
-def extract_description(text: str) -> str:
-    m = FRONTMATTER_RE.search(text)
-    if not m:
-        return ""
-    d = DESCRIPTION_RE.search(m.group(1))
-    return d.group(1).strip() if d else ""
-
-
-def audit_description(description: str) -> List[str]:
-    flags: List[str] = []
-    if not description:
-        flags.append("missing")
-        return flags
-    length = len(description)
-    if length < 80:
-        flags.append("very-short")
-    elif length < MIN_LENGTH:
-        flags.append("too-short")
-    if length > MAX_LENGTH:
-        flags.append("too-long")
-    if not TRIGGER_PREFIX_RE.match(description):
-        flags.append("no-trigger-prefix")
-    lowered = description.lower()
-    for phrase in HEDGE_PHRASES:
-        if phrase in lowered:
-            flags.append(f"hedge:{phrase}")
-    return flags
-
-
-def collect_findings(root: Path) -> List[Finding]:
-    findings: List[Finding] = []
-    for skill_md in sorted(root.glob("*/SKILL.md")):
-        text = skill_md.read_text(encoding="utf-8")
-        description = extract_description(text)
-        flags = audit_description(description)
-        findings.append(
-            Finding(
-                skill=skill_md.parent.name,
-                path=str(skill_md),
-                description=description,
-                length=len(description),
-                flags=flags,
-            )
-        )
-    return findings
-
-
-def render_text(findings: List[Finding], worst_only: bool) -> str:
-    flagged = [f for f in findings if f.flags]
-    flagged.sort(key=lambda f: (-f.score, f.skill))
-    lines = [f"Audited {len(findings)} skills, {len(flagged)} flagged.\n"]
-    if not flagged:
-        lines.append("✅  All descriptions look reasonable.")
-        return "\n".join(lines)
-    lines.append(f"{'SCORE':>5}  {'LEN':>4}  {'SKILL':<40}  FLAGS")
-    lines.append("-" * 90)
-    shown = flagged[:15] if worst_only else flagged
-    for f in shown:
-        lines.append(
-            f"{f.score:>5}  {f.length:>4}  {f.skill:<40}  {', '.join(f.flags)}"
-        )
-    if worst_only and len(flagged) > 15:
-        lines.append(f"\n... {len(flagged) - 15} more (use --full to show all)")
-    return "\n".join(lines)
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("--root", type=Path, default=None)
-    parser.add_argument("--json", action="store_true", help="emit JSON")
-    parser.add_argument("--full", action="store_true", help="show all flagged, not just top 15")
-    args = parser.parse_args()
-    if args.root is not None:
-        if not args.root.exists():
-            print(f"error: {args.root} does not exist", file=sys.stderr)
-            return 2
-        roots = [args.root]
-    else:
-        roots = [r / "skills" for r in artefact_roots() if (r / "skills").is_dir()]
-        if not roots:
-            print("error: no skills/ directories found across artefact roots", file=sys.stderr)
-            return 2
-    findings: List[Finding] = []
-    for r in roots:
-        findings.extend(collect_findings(r))
-    if args.json:
-        print(json.dumps([asdict(f) for f in findings], indent=2))
-    else:
-        print(render_text(findings, worst_only=not args.full))
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())