@event4u/agent-config 1.18.0 → 1.20.0

package/scripts/install.sh

@@ -344,7 +344,7 @@ clean_stale() {
             log_verbose "preserve: $entry"
             continue
         fi
-        if is_excluded_rule "$entry" || ! echo "$source_manifest" | grep -qxF "$entry"; then
+        if is_excluded_rule "$entry" || ! grep -qxF -- "$entry" <<<"$source_manifest"; then
             local path="$target_dir/$entry"
             if $DRY_RUN; then
                 log_verbose "remove stale: $entry"
@@ -563,6 +563,40 @@ copy_if_missing() {
     cp "$source" "$target"
 }
 
+# Migrate legacy infra files from project root to agents/.
+# Pre-2.x layout: .agent-chat-history (+ .bak), .agent-prices.md lived at
+# the project root. They now live under agents/. Move them in place before
+# any other content sync so the updated gitignore block (which lists
+# /agents/.agent-chat-history*) and the chat-history hooks operate on the
+# already-migrated layout. Idempotent: skips silently if the target already
+# exists; never overwrites.
+migrate_legacy_root_infra() {
+    local project_root="$1"
+    local agents_dir="$project_root/agents"
+    local items=(".agent-chat-history" ".agent-chat-history.bak" ".agent-prices.md")
+
+    for name in "${items[@]}"; do
+        local old="$project_root/$name"
+        local new="$agents_dir/$name"
+
+        [[ -e "$old" ]] || continue
+
+        if [[ -e "$new" ]]; then
+            log_warn "Legacy $name found at project root, but agents/$name already exists — leaving root copy in place"
+            continue
+        fi
+
+        if $DRY_RUN; then
+            log_verbose "would migrate $name → agents/$name"
+            continue
+        fi
+
+        mkdir -p "$agents_dir"
+        mv "$old" "$new"
+        log_info "Migrated $name → agents/$name"
+    done
+}
+
 # Ensure .gitignore contains the managed agent-config block.
 # Delegates to scripts/sync_gitignore.py so the installer and the
 # standalone /sync-gitignore command share one source of truth
@@ -632,6 +666,9 @@ main() {
     $DRY_RUN && ! $QUIET && echo "    Mode: DRY RUN"
     echo ""
 
+    # 0. Migrate legacy infra files (root → agents/) before any content sync.
+    migrate_legacy_root_infra "$TARGET_DIR"
+
     # 1. Hybrid sync payload → target/.augment/
     sync_hybrid "$SOURCE_PAYLOAD" "$TARGET_DIR/.augment"
     log_info "Synced .augment/ (rules copied, rest symlinked)"

package/scripts/lint_handoffs.py

@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+"""Lint cross-wing handoffs declared in senior-tier skills' ``## Related Skills`` blocks.
+
+Builds a directed graph from every ``tier: senior`` skill's Related Skills
+block (markdown links pointing at peer ``SKILL.md`` files), then enforces
+the rules from ``docs/contracts/cross-wing-handoff.md`` § 4:
+
+  handoff_cycle           — graph must be a DAG.
+  handoff_dangling        — every linked target must exist.
+  handoff_tier_mismatch   — senior may delegate only to senior.
+
+Hooked into ``task lint-handoffs`` and ``task ci`` (between ``lint-skills``
+and ``test``). Output mirrors ``scripts/skill_linter.py``: ``file:line:reason``.
+
+Exit codes:
+  0  no violations
+  1  one or more violations
+"""
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+REPO = Path(__file__).resolve().parents[1]
+SKILLS_DIR = REPO / ".agent-src.uncompressed" / "skills"
+
+LINK_RE = re.compile(r"\[`?([a-z0-9][a-z0-9-]*)`?\]\(([^)]+SKILL\.md)\)")
+RELATED_HEADING_RE = re.compile(r"^##\s+Related\s+Skills\s*$", re.IGNORECASE)
+NEXT_HEADING_RE = re.compile(r"^##\s+\S")
+WHEN_USE_RE = re.compile(r"^\*\*WHEN\s+to\s+use\s+this\*\*\s*$", re.IGNORECASE)
+WHEN_NOT_RE = re.compile(r"^\*\*WHEN\s+NOT\s+to\s+use\s+this\*\*\s*$", re.IGNORECASE)
+
+
+@dataclass(frozen=True)
+class Violation:
+    file: Path
+    line: int
+    code: str
+    message: str
+
+    def render(self, repo: Path) -> str:
+        rel = self.file.relative_to(repo) if self.file.is_absolute() else self.file
+        return f"{rel}:{self.line}:{self.code}: {self.message}"
+
+
+def parse_frontmatter_tier(text: str) -> str | None:
+    if not text.startswith("---\n"):
+        return None
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return None
+    for raw in text[4:end].splitlines():
+        if ":" not in raw:
+            continue
+        key, _, val = raw.partition(":")
+        if key.strip() == "tier":
+            return val.strip().strip('"').strip("'")
+    return None
+
+
+def extract_related_block(text: str) -> tuple[int, list[tuple[int, str]]] | None:
+    """Return (block_start_line, [(line, raw_line), ...]) for ``## Related Skills``."""
+    lines = text.splitlines()
+    start: int | None = None
+    for idx, line in enumerate(lines):
+        if RELATED_HEADING_RE.match(line):
+            start = idx
+            break
+    if start is None:
+        return None
+    body: list[tuple[int, str]] = []
+    for idx in range(start + 1, len(lines)):
+        if NEXT_HEADING_RE.match(lines[idx]):
+            break
+        body.append((idx + 1, lines[idx]))
+    return start + 1, body
+
+
+def split_when_subblocks(body: list[tuple[int, str]]) -> tuple[
+    list[tuple[int, str]], list[tuple[int, str]]
+]:
+    """Split a ``## Related Skills`` body into (when_to_use, when_not_to_use).
+
+    WHEN-to-use links are composition (delegation) edges — graph for cycles.
+    WHEN-NOT-to-use links are alternative pointers (peer cognition the user
+    picks instead) — never composition edges. Lines outside both sub-blocks
+    are treated as WHEN-to-use for backward compatibility.
+    """
+    when_use: list[tuple[int, str]] = []
+    when_not: list[tuple[int, str]] = []
+    current = when_use
+    for lineno, raw in body:
+        if WHEN_USE_RE.match(raw):
+            current = when_use
+            continue
+        if WHEN_NOT_RE.match(raw):
+            current = when_not
+            continue
+        current.append((lineno, raw))
+    return when_use, when_not
+
+
+def extract_links(body: list[tuple[int, str]]) -> list[tuple[int, str, str]]:
+    """Yield ``(line, slug, target_path)`` for every markdown link in the block."""
+    out: list[tuple[int, str, str]] = []
+    for lineno, raw in body:
+        for match in LINK_RE.finditer(raw):
+            out.append((lineno, match.group(1), match.group(2)))
+    return out
+
+
+def resolve_target(skill_file: Path, link: str) -> Path:
+    return (skill_file.parent / link).resolve()
+
+
+def detect_cycles(graph: dict[Path, set[Path]]) -> list[list[Path]]:
+    cycles: list[list[Path]] = []
+    visited: set[Path] = set()
+    stack: list[Path] = []
+    on_stack: set[Path] = set()
+
+    def dfs(node: Path) -> None:
+        if node in on_stack:
+            i = stack.index(node)
+            cycles.append(stack[i:] + [node])
+            return
+        if node in visited:
+            return
+        visited.add(node)
+        on_stack.add(node)
+        stack.append(node)
+        for nxt in graph.get(node, ()):
+            dfs(nxt)
+        stack.pop()
+        on_stack.discard(node)
+
+    for node in list(graph):
+        dfs(node)
+    return cycles
+
+
+def lint(skills_dir: Path) -> list[Violation]:
+    senior_skills: dict[Path, str] = {}
+    all_skills: dict[Path, str] = {}
+    for skill_md in sorted(skills_dir.rglob("SKILL.md")):
+        text = skill_md.read_text(encoding="utf-8")
+        tier = parse_frontmatter_tier(text)
+        all_skills[skill_md.resolve()] = tier or ""
+        if tier == "senior":
+            senior_skills[skill_md.resolve()] = text
+
+    violations: list[Violation] = []
+    graph: dict[Path, set[Path]] = {}
+
+    for skill_path, text in senior_skills.items():
+        block = extract_related_block(text)
+        if block is None:
+            continue
+        _, body = block
+        when_use, when_not = split_when_subblocks(body)
+
+        # WHEN-to-use links: composition edges (graph) + dangling/tier checks.
+        for lineno, slug, link in extract_links(when_use):
+            target = resolve_target(skill_path, link)
+            graph.setdefault(skill_path, set()).add(target)
+            if target not in all_skills:
+                violations.append(Violation(skill_path, lineno, "handoff_dangling",
+                    f"link to `{slug}` resolves to missing file {link}"))
+                continue
+            if all_skills[target] != "senior":
+                violations.append(Violation(skill_path, lineno, "handoff_tier_mismatch",
+                    f"senior skill links to non-senior `{slug}` "
+                    f"(tier={all_skills[target] or 'unset'!r})"))
+
+        # WHEN-NOT-to-use links: alternative pointers, NOT composition edges.
+        # Dangling + tier-mismatch still apply (a broken alternative is wrong);
+        # cycles do not (mutual "use X instead" pointers are intentional).
+        for lineno, slug, link in extract_links(when_not):
+            target = resolve_target(skill_path, link)
+            if target not in all_skills:
+                violations.append(Violation(skill_path, lineno, "handoff_dangling",
+                    f"link to `{slug}` resolves to missing file {link}"))
+                continue
+            if all_skills[target] != "senior":
+                violations.append(Violation(skill_path, lineno, "handoff_tier_mismatch",
+                    f"senior skill links to non-senior `{slug}` "
+                    f"(tier={all_skills[target] or 'unset'!r})"))
+
+    for cycle in detect_cycles(graph):
+        names = " → ".join(p.parent.name for p in cycle)
+        violations.append(Violation(cycle[0], 1, "handoff_cycle",
+            f"composition cycle: {names}"))
+    return violations
+
+
+def main(argv: list[str] | None = None) -> int:
+    skills_dir = SKILLS_DIR
+    if argv:
+        skills_dir = Path(argv[0]).resolve()
+    violations = lint(skills_dir)
+    if not violations:
+        print(f"✅  lint_handoffs: no violations under {skills_dir.relative_to(REPO)}")
+        return 0
+    for v in violations:
+        print(v.render(REPO))
+    print(f"\n❌  lint_handoffs: {len(violations)} violation(s)", file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/scripts/lint_hook_manifest.py

@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+"""Lint `scripts/hook_manifest.yaml`.
+
+CI gate per roadmap step 7.10. Hard-fails on:
+
+- missing or malformed top-level keys (`schema_version`, `concerns`,
+  `platforms`)
+- a concern entry referencing a non-existent script file
+- a platform binding referencing an unknown concern name
+- a platform binding referencing an unknown event (outside the
+  vocabulary in `docs/contracts/hook-architecture-v1.md`)
+- a `native_event_aliases` block referencing an unknown agent-config
+  event or an unknown platform
+- a `scripts/hooks/<platform>-dispatcher.sh` trampoline that exists on
+  disk without a corresponding non-empty platform block in the
+  manifest (orphan trampoline)
+
+Soft-warns on:
+
+- platform blocks set to `null` / empty (Phase 7.5–7.8 placeholders)
+- concerns declared but not bound to any platform (dead concern)
+
+Exit codes:
+  0 — clean (warnings allowed)
+  1 — at least one hard failure
+  2 — file or schema-load error
+
+Invocation:
+
+    python3 scripts/lint_hook_manifest.py [--manifest PATH] [--strict]
+
+`--strict` upgrades warnings to errors. Wired into `task ci` via the
+`lint-hook-manifest` task.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_MANIFEST = REPO_ROOT / "scripts" / "hook_manifest.yaml"
+HOOKS_DIR = REPO_ROOT / "scripts" / "hooks"
+
+# Canonical event vocabulary — keep in lock-step with
+# docs/contracts/hook-architecture-v1.md and dispatch_hook.EVENT_VOCABULARY.
+# `agent_error` added in Round 2 (2026-05-04) — synthetic event the
+# wrapper fires on host crashes outside a concern.
+EVENT_VOCABULARY: set[str] = {
+    "session_start", "session_end",
+    "user_prompt_submit",
+    "pre_tool_use", "post_tool_use",
+    "stop", "pre_compact",
+    "agent_error",
+}
+
+# Known platform identifiers. New platforms MUST be added here as they
+# land — the linter is the gate that proves no orphan slot escapes.
+KNOWN_PLATFORMS: set[str] = {
+    "augment", "claude", "cowork",
+    "cursor", "cline", "windsurf", "gemini", "copilot",
+}
+
+
+def _load_manifest(path: Path) -> dict:
+    """Reuse the dispatcher's loader so the linter sees exactly what
+    the runtime sees — including the fallback parser when PyYAML is
+    not installed."""
+    sys.path.insert(0, str(REPO_ROOT / "scripts"))
+    from hooks.dispatch_hook import _load_yaml  # noqa: E402
+    return _load_yaml(path)
+
+
+def _check_concerns(manifest: dict, errors: list[str]) -> set[str]:
+    concerns = manifest.get("concerns") or {}
+    if not isinstance(concerns, dict) or not concerns:
+        errors.append("manifest: 'concerns' must be a non-empty mapping")
+        return set()
+    names: set[str] = set()
+    for name, spec in concerns.items():
+        if not isinstance(spec, dict):
+            errors.append(f"concerns.{name}: must be a mapping, got {type(spec).__name__}")
+            continue
+        script = spec.get("script")
+        if not script or not isinstance(script, str):
+            errors.append(f"concerns.{name}: 'script' must be a relative path")
+            continue
+        if not (REPO_ROOT / script).is_file():
+            errors.append(f"concerns.{name}: script not found at '{script}'")
+        names.add(name)
+    return names
+
+
+def _check_platforms(manifest: dict, concern_names: set[str],
+                     errors: list[str], warnings: list[str]) -> set[str]:
+    platforms = manifest.get("platforms") or {}
+    if not isinstance(platforms, dict) or not platforms:
+        errors.append("manifest: 'platforms' must be a non-empty mapping")
+        return set()
+    bound: set[str] = set()
+    for plat, block in platforms.items():
+        if plat not in KNOWN_PLATFORMS:
+            errors.append(f"platforms.{plat}: unknown platform "
+                          f"(allowed: {sorted(KNOWN_PLATFORMS)})")
+            continue
+        if block is None:
+            warnings.append(f"platforms.{plat}: placeholder (no events bound)")
+            continue
+        if not isinstance(block, dict):
+            errors.append(f"platforms.{plat}: must be mapping or null")
+            continue
+        if block.get("fallback_only"):
+            continue  # Copilot — intentional, no event surface
+        for event, names in block.items():
+            if event not in EVENT_VOCABULARY:
+                errors.append(f"platforms.{plat}.{event}: unknown event "
+                              f"(allowed: {sorted(EVENT_VOCABULARY)})")
+                continue
+            if not isinstance(names, list):
+                errors.append(f"platforms.{plat}.{event}: must be a list of concern names")
+                continue
+            for n in names:
+                if n not in concern_names:
+                    errors.append(f"platforms.{plat}.{event}: unknown concern '{n}'")
+                else:
+                    bound.add(n)
+    return bound
+
+
+def _check_aliases(manifest: dict, errors: list[str]) -> None:
+    aliases = manifest.get("native_event_aliases") or {}
+    if not isinstance(aliases, dict):
+        errors.append("native_event_aliases: must be a mapping")
+        return
+    for plat, mapping in aliases.items():
+        if plat not in KNOWN_PLATFORMS:
+            errors.append(f"native_event_aliases.{plat}: unknown platform")
+            continue
+        if not isinstance(mapping, dict):
+            errors.append(f"native_event_aliases.{plat}: must be a mapping")
+            continue
+        for native, target in mapping.items():
+            if target not in EVENT_VOCABULARY:
+                errors.append(f"native_event_aliases.{plat}.{native}: "
+                              f"target '{target}' not in vocabulary")
+
+
+def _check_orphan_trampolines(manifest: dict, errors: list[str]) -> None:
+    """A `<platform>-dispatcher.sh` on disk MUST have a non-null,
+    non-empty manifest block — otherwise the trampoline runs but no
+    concerns fire (silent no-op, hardest class of bug to debug)."""
+    if not HOOKS_DIR.is_dir():
+        return
+    platforms = manifest.get("platforms") or {}
+    for entry in sorted(HOOKS_DIR.iterdir()):
+        if not entry.name.endswith("-dispatcher.sh"):
+            continue
+        plat = entry.name[: -len("-dispatcher.sh")]
+        if plat not in KNOWN_PLATFORMS:
+            errors.append(f"orphan trampoline {entry.name}: unknown platform '{plat}'")
+            continue
+        block = platforms.get(plat)
+        if block is None or (isinstance(block, dict)
+                             and not any(k in EVENT_VOCABULARY for k in block)):
+            errors.append(f"orphan trampoline {entry.name}: "
+                          f"platform '{plat}' has no event bindings in manifest")
+
+
+def _check_dead_concerns(concern_names: set[str], bound: set[str],
+                         warnings: list[str]) -> None:
+    for n in sorted(concern_names - bound):
+        warnings.append(f"concerns.{n}: declared but not bound to any platform")
+
+
+def lint(manifest_path: Path, *, strict: bool) -> int:
+    if not manifest_path.is_file():
+        sys.stderr.write(f"lint_hook_manifest: file not found: {manifest_path}\n")
+        return 2
+    try:
+        manifest = _load_manifest(manifest_path)
+    except Exception as exc:  # pragma: no cover — covered by malformed-yaml test
+        sys.stderr.write(f"lint_hook_manifest: load error: {exc}\n")
+        return 2
+    if not isinstance(manifest, dict) or manifest.get("schema_version") != 1:
+        sys.stderr.write("lint_hook_manifest: schema_version must be 1\n")
+        return 1
+
+    errors: list[str] = []
+    warnings: list[str] = []
+    concern_names = _check_concerns(manifest, errors)
+    bound = _check_platforms(manifest, concern_names, errors, warnings)
+    _check_aliases(manifest, errors)
+    _check_orphan_trampolines(manifest, errors)
+    _check_dead_concerns(concern_names, bound, warnings)
+
+    for w in warnings:
+        sys.stderr.write(f"warn: {w}\n")
+    for e in errors:
+        sys.stderr.write(f"error: {e}\n")
+
+    if errors:
+        return 1
+    if strict and warnings:
+        return 1
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--manifest", type=Path, default=DEFAULT_MANIFEST)
+    parser.add_argument("--strict", action="store_true")
+    args = parser.parse_args(argv)
+    return lint(args.manifest, strict=args.strict)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/lint_one_off_age.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""One-off-script age linter.
+
+Scans `scripts/_one_off/<YYYY-MM>/_one_off_*.py` and enforces the
+TTL policy from `docs/contracts/one-off-script-lifecycle.md`:
+
+  * Age ≤ 60 days   → active, silent.
+  * 60 < Age ≤ 90   → warning, exit 0.
+  * Age > 90        → hard fail, exit 1 (purge candidate).
+
+Scripts MAY extend their TTL exactly once via a frontmatter block:
+
+    \"\"\"
+    ---
+    ttl_extended_until: YYYY-MM-DD
+    ttl_reason: <free text>
+    ---
+    \"\"\"
+
+The extended date is honoured up to 180 days past the month-directory
+date. Anything beyond hard-fails with no second extension.
+
+Exit codes: 0 = clean (incl. warnings), 1 = hard fail, 3 = internal error.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import asdict, dataclass
+from datetime import date, datetime, timezone
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+ONE_OFF_DIR = ROOT / "scripts" / "_one_off"
+
+NAME_RE = re.compile(r"^_one_off_[a-z0-9-]+\.py$")
+MONTH_RE = re.compile(r"^\d{4}-\d{2}$")
+TTL_RE = re.compile(
+    r"---\s*\n\s*ttl_extended_until:\s*(\d{4}-\d{2}-\d{2})\s*\n",
+    re.MULTILINE,
+)
+
+WARN_DAYS = 60
+HARD_DAYS = 90
+EXTEND_CAP_DAYS = 180
+
+
+@dataclass
+class Finding:
+    path: str
+    age_days: int
+    severity: str  # "warn" | "fail"
+    reason: str
+
+
+def _today_utc() -> date:
+    return datetime.now(timezone.utc).date()
+
+
+def _month_anchor(month_dir: str) -> date | None:
+    if not MONTH_RE.match(month_dir):
+        return None
+    y, m = map(int, month_dir.split("-"))
+    try:
+        return date(y, m, 1)
+    except ValueError:
+        return None
+
+
+def _read_extension(path: Path) -> date | None:
+    try:
+        head = path.read_text(encoding="utf-8")[:1024]
+    except OSError:
+        return None
+    m = TTL_RE.search(head)
+    if not m:
+        return None
+    try:
+        return datetime.strptime(m.group(1), "%Y-%m-%d").date()
+    except ValueError:
+        return None
+
+
+def scan(root: Path, today: date | None = None) -> list[Finding]:
+    today = today or _today_utc()
+    base = root / "scripts" / "_one_off"
+    if not base.exists():
+        return []
+    out: list[Finding] = []
+    for month_dir in sorted(base.iterdir()):
+        if not month_dir.is_dir():
+            continue
+        anchor = _month_anchor(month_dir.name)
+        if anchor is None:
+            out.append(Finding(
+                path=str(month_dir.relative_to(root)),
+                age_days=-1,
+                severity="fail",
+                reason="invalid month directory name (expect YYYY-MM)",
+            ))
+            continue
+        for f in sorted(month_dir.iterdir()):
+            if f.name == "README.md" or f.is_dir():
+                continue
+            if not NAME_RE.match(f.name):
+                out.append(Finding(
+                    path=str(f.relative_to(root)),
+                    age_days=-1,
+                    severity="fail",
+                    reason="filename does not match _one_off_<slug>.py",
+                ))
+                continue
+            age = (today - anchor).days
+            extension = _read_extension(f)
+            if extension is not None:
+                cap = (extension - anchor).days
+                if cap > EXTEND_CAP_DAYS:
+                    out.append(Finding(
+                        path=str(f.relative_to(root)),
+                        age_days=age,
+                        severity="fail",
+                        reason=f"ttl_extended_until exceeds 180-day cap ({cap}d)",
+                    ))
+                    continue
+                if age <= cap:
+                    continue  # extension still valid, silent
+            if age > HARD_DAYS:
+                out.append(Finding(
+                    path=str(f.relative_to(root)),
+                    age_days=age,
+                    severity="fail",
+                    reason=f"age {age}d exceeds {HARD_DAYS}-day hard limit",
+                ))
+            elif age > WARN_DAYS:
+                out.append(Finding(
+                    path=str(f.relative_to(root)),
+                    age_days=age,
+                    severity="warn",
+                    reason=f"age {age}d in soft window ({WARN_DAYS}–{HARD_DAYS}d)",
+                ))
+    return out
+
+
+def format_text(findings: list[Finding]) -> str:
+    if not findings:
+        return "✅  No one-off-script age violations."
+    lines = []
+    fails = [f for f in findings if f.severity == "fail"]
+    warns = [f for f in findings if f.severity == "warn"]
+    if fails:
+        lines.append(f"❌  {len(fails)} one-off script(s) past hard limit:")
+        for f in fails:
+            lines.append(f"  🔴 {f.path}  →  {f.reason}")
+    if warns:
+        lines.append(f"⚠️  {len(warns)} one-off script(s) in soft window:")
+        for f in warns:
+            lines.append(f"  🟡 {f.path}  →  {f.reason}")
+    lines.append(
+        "\nPurge candidates per docs/contracts/one-off-script-lifecycle.md."
+    )
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--format", choices=["text", "json"], default="text")
+    parser.add_argument("--root", type=Path, default=ROOT)
+    args = parser.parse_args()
+    try:
+        findings = scan(args.root)
+    except Exception as e:    # pragma: no cover
+        print(f"Internal error: {e}", file=sys.stderr)
+        return 3
+    if args.format == "json":
+        print(json.dumps([asdict(f) for f in findings], indent=2))
+    else:
+        print(format_text(findings))
+    return 1 if any(f.severity == "fail" for f in findings) else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())