@event4u/agent-config 5.10.0 → 6.0.0

package/src/scripts/check_release_pr_shape.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Release-PR shape checker — fail-closed gate for `docs/contracts/release-pr-gating.md`.
+
+Given a PR number, fetches the file list via `gh pr diff <n> --name-only`
+and asserts every changed file matches the version-bump allowlist:
+
+  * `package.json`
+  * `CHANGELOG.md`
+  * `.claude-plugin/marketplace.json`
+  * `packages/*/pack.yaml`
+  * `packages/*/README.md`
+  * `docs/archive/CHANGELOG-pre-*.md`
+
+Exit codes:
+
+  0 — every file matches; release-PR is shape-clean and the heavy install /
+      test matrices may skip per `release-pr-gating.md`.
+  1 — at least one file outside the allowlist OR no files at all. Stdout
+      lists each offending entry one per line with an "OUT-OF-SHAPE: " prefix
+      so CI logs surface the precise reason.
+  2 — usage / environment error (gh missing, invalid PR number, gh non-zero).
+
+Design constraints from the roadmap:
+
+  * stdlib-only — no jsonschema, no requests, no PyYAML
+  * ≤ 150 LOC including this docstring
+  * deterministic — same diff in, same exit
+"""
+
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import shutil
+import subprocess
+import sys
+
+ALLOWLIST_GLOBS = (
+    "package.json",
+    "CHANGELOG.md",
+    ".claude-plugin/marketplace.json",
+    # 6.0.x (ADR-052): generated pack manifests live under src/packs/<id>/
+    # (capability packs + core) and src/domains/<pack>/ (command-bearing).
+    "src/packs/*/pack.yaml",
+    "src/packs/*/README.md",
+    "src/domains/*/pack.yaml",
+    "src/domains/*/README.md",
+    # `scripts/release.py` auto-splits the CHANGELOG era before bumping
+    # (perform_split / plan_split in `_lib/changelog_eras.py`) whenever the
+    # current era body crosses CURRENT_ERA_BODY_CAP. The split emits a new
+    # `docs/archive/CHANGELOG-pre-X.Y.Z.md` — part of the release surface,
+    # so the shape gate must allow it. Test-enforced by test_changelog_eras.
+    "docs/archive/CHANGELOG-pre-*.md",
+)
+
+
+def _matches(path: str) -> bool:
+    return any(fnmatch.fnmatch(path, pat) for pat in ALLOWLIST_GLOBS)
+
+
+def _gh_diff_files(pr: str) -> list[str]:
+    """Return the list of files changed in `pr`, via `gh pr diff --name-only`."""
+    if shutil.which("gh") is None:
+        print("ERROR: gh CLI not on PATH; cannot fetch PR diff.", file=sys.stderr)
+        sys.exit(2)
+    try:
+        out = subprocess.run(
+            ["gh", "pr", "diff", pr, "--name-only"],
+            check=True,
+            capture_output=True,
+            text=True,
+        ).stdout
+    except subprocess.CalledProcessError as exc:
+        stderr = (exc.stderr or "").strip()
+        print(f"ERROR: gh pr diff {pr} failed: {stderr}", file=sys.stderr)
+        sys.exit(2)
+    return [line.strip() for line in out.splitlines() if line.strip()]
+
+
+def check(files: list[str]) -> int:
+    """Return exit code; print per-file diff to stdout on failure."""
+    if not files:
+        print("OUT-OF-SHAPE: empty diff — release PR must touch at least one file.")
+        return 1
+    bad = [f for f in files if not _matches(f)]
+    if bad:
+        for f in bad:
+            print(f"OUT-OF-SHAPE: {f}")
+        return 1
+    print(f"SHAPE-CLEAN: {len(files)} file(s) — all within release-PR allowlist.")
+    for f in files:
+        print(f"  ok: {f}")
+    return 0
+
+
+def _read_files_arg(value: str) -> list[str]:
+    """`--files` accepts comma-separated paths or `-` to read stdin (one per line)."""
+    if value == "-":
+        return [line.strip() for line in sys.stdin.read().splitlines() if line.strip()]
+    return [v.strip() for v in value.split(",") if v.strip()]
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Fail-closed shape checker for release PRs.",
+    )
+    src = parser.add_mutually_exclusive_group(required=True)
+    src.add_argument("--pr", help="GitHub PR number; uses `gh pr diff --name-only`.")
+    src.add_argument(
+        "--files",
+        help=(
+            "Comma-separated file list, or '-' to read one path per line from "
+            "stdin. Bypasses gh — useful for tests and local previews."
+        ),
+    )
+    args = parser.parse_args(argv)
+
+    files = _gh_diff_files(args.pr) if args.pr else _read_files_arg(args.files)
+    return check(files)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/scripts/check_release_published.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""
+Release-published drift gate.
+
+Catches the "release merged to main but never tagged/published" failure
+mode — where ``main``'s ``package.json`` claims a version that has no
+matching git tag, and npm's ``latest`` therefore lags behind main. This
+is the backstop that would have surfaced the 5.8.0-stuck-on-5.7.0 state
+the moment it happened, instead of weeks later.
+
+Two independent invariants:
+
+  1. **Tag invariant** (always checkable, no network): the version in
+     ``package.json`` MUST have a matching git tag (local or remote).
+  2. **npm invariant** (``--check-npm``, network): ``npm view <pkg>
+     dist-tags.latest`` MUST equal the ``package.json`` version.
+
+Scope guard: this only makes sense on the release trunk. Off ``main``
+(e.g. a feature branch, or a ``release/X.Y.Z`` branch mid-flight where
+the bump legitimately precedes the tag) the gate **no-ops** unless
+``--strict`` is combined with an explicit on-main signal. The daily
+scheduled workflow runs ``--strict --check-npm`` on ``main``; the local
+``task check-release-published`` runs the tag invariant only.
+
+Exit codes: 0 = pass / no-op · 1 = drift detected · 3 = internal error.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+SEMVER_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$")
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent
+PACKAGE_JSON = REPO_ROOT / "package.json"
+MAIN_BRANCH = "main"
+
+
+def _git(*args: str) -> tuple[int, str]:
+    proc = subprocess.run(["git", *args], capture_output=True, text=True, check=False)
+    return proc.returncode, (proc.stdout or "").strip()
+
+
+def _package_version() -> str:
+    data = json.loads(PACKAGE_JSON.read_text(encoding="utf-8"))
+    return str(data["version"])
+
+
+def _package_name() -> str:
+    data = json.loads(PACKAGE_JSON.read_text(encoding="utf-8"))
+    return str(data["name"])
+
+
+def _tag_exists(tag: str) -> bool:
+    rc, out = _git("tag", "-l", tag)
+    if rc == 0 and tag in out.splitlines():
+        return True
+    rc, _ = _git("ls-remote", "--exit-code", "--tags", "origin", tag)
+    return rc == 0
+
+
+def _on_main() -> bool:
+    # Local checkout, CI push ref, or CI scheduled ref all map to main.
+    ref = os.environ.get("GITHUB_REF", "")
+    if ref in ("refs/heads/main", "refs/heads/master"):
+        return True
+    rc, head = _git("rev-parse", "--abbrev-ref", "HEAD")
+    return rc == 0 and head == MAIN_BRANCH
+
+
+def _npm_latest(pkg: str) -> str | None:
+    proc = subprocess.run(
+        ["npm", "view", pkg, "dist-tags.latest"],
+        capture_output=True, text=True, check=False,
+    )
+    if proc.returncode != 0:
+        return None
+    return (proc.stdout or "").strip() or None
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Release-published drift gate.")
+    ap.add_argument("--strict", action="store_true",
+                    help="Fail on drift (default: informational, exit 0).")
+    ap.add_argument("--check-npm", action="store_true",
+                    help="Also assert npm dist-tags.latest == package.json version (network).")
+    ap.add_argument("--require-main", action="store_true",
+                    help="Only enforce when on main; no-op elsewhere (default for scheduled).")
+    args = ap.parse_args(argv)
+
+    try:
+        version = _package_version()
+    except (OSError, KeyError, json.JSONDecodeError) as exc:
+        print(f"❌  cannot read package.json version: {exc}", file=sys.stderr)
+        return 3
+    if not SEMVER_RE.match(version):
+        print(f"❌  package.json version is not semver: {version!r}", file=sys.stderr)
+        return 3
+
+    if args.require_main and not _on_main():
+        print(f"ℹ️  not on {MAIN_BRANCH} — release-published gate skipped.")
+        return 0
+
+    problems: list[str] = []
+
+    if not _tag_exists(version):
+        problems.append(
+            f"package.json is {version} but no git tag {version} exists "
+            f"(local or origin) — the release was bumped/merged but never "
+            f"tagged. Complete it: tag the release-merge commit and push "
+            f"(triggers publish-npm.yml), e.g. `git tag {version} && git "
+            f"push origin {version}`."
+        )
+
+    if args.check_npm:
+        pkg = _package_name()
+        latest = _npm_latest(pkg)
+        if latest is None:
+            print(f"⚠️  could not read npm dist-tags.latest for {pkg} "
+                  f"(network/registry) — npm invariant not checked.", file=sys.stderr)
+        elif latest != version:
+            problems.append(
+                f"npm {pkg}@latest is {latest} but package.json is {version} "
+                f"— the published release lags main. Check publish-npm.yml "
+                f"for tag {version}, or re-dispatch it."
+            )
+
+    if not problems:
+        suffix = " + npm" if args.check_npm else ""
+        print(f"✅  release-published: {version} is tagged{suffix} and in sync.")
+        return 0
+
+    header = "❌  Release-published drift:" if args.strict else "⚠️  Release-published drift (warn-only):"
+    print(header, file=sys.stderr)
+    for p in problems:
+        print(f"  - {p}", file=sys.stderr)
+    return 1 if args.strict else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/scripts/check_reply_consistency.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""check_reply_consistency.py — enforce user-interaction.md Iron Laws.
+
+Single-Source Recommendation Line: a reply with numbered options must
+have ONE bolded `Recommendation: N` / `Empfehlung: N` line, no inline
+`(recommended)` / `(rec)` / `(empfohlen)` tag next to options, and the
+recommended number must appear in the option block.
+
+Modes:
+  --stdin / --file <path>   Validate a single draft (all rules).
+  --scan-dir <dir>          Scan .md tree for legacy inline-tag regression.
+
+Exit codes:
+  0 ok · 2 inline tag · 3 multi-rec · 4 rec-not-in-options
+  5 options-without-rec (strict) · 6 scan-dir found · 9 usage error
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent.parent
+sys.path.insert(0, str(ROOT / "src" / "scripts"))
+from _lib.agent_src import artefact_roots  # noqa: E402
+
+QUIET = "--quiet" in sys.argv
+
+OPTION_LINE_RE = re.compile(r"^\s*>?\s*(\d+)\.\s+\S")
+REC_LINE_RE = re.compile(
+    r"(?:Recommendation|Empfehlung)\s*:\s*(\d+)\b", re.IGNORECASE
+)
+TAG_RE = re.compile(r"\((?:recommended|rec|empfohlen)\)", re.IGNORECASE)
+CODESPAN_RE = re.compile(r"`[^`\n]*`")
+
+
+def _strip_codespans(line: str) -> str:
+    return CODESPAN_RE.sub("``", line)
+
+
+def find_inline_tag(text: str) -> tuple[int, str] | None:
+    """Return (line_no, raw_line) of the first numbered-option line carrying
+    an inline (recommended)-class tag outside code spans, or None."""
+    for idx, raw in enumerate(text.splitlines(), start=1):
+        stripped = _strip_codespans(raw)
+        if not OPTION_LINE_RE.match(stripped):
+            continue
+        if TAG_RE.search(stripped):
+            return idx, raw.strip()
+    return None
+
+
+def find_option_blocks(text: str) -> list[list[int]]:
+    """Group consecutive numbered-option lines into blocks; return list of
+    blocks, each a list of the numbers found in that block."""
+    blocks: list[list[int]] = []
+    current: list[int] = []
+    for raw in text.splitlines():
+        m = OPTION_LINE_RE.match(raw)
+        if m:
+            current.append(int(m.group(1)))
+        else:
+            if len(current) >= 2:
+                blocks.append(current)
+            current = []
+    if len(current) >= 2:
+        blocks.append(current)
+    return blocks
+
+
+def validate(text: str, strict: bool = False) -> tuple[int, str]:
+    """Run rules. Returns (exit_code, human_message)."""
+    tag = find_inline_tag(text)
+    if tag:
+        line_no, snippet = tag
+        return 2, f"line {line_no}: inline tag on numbered option — {snippet!r}"
+
+    blocks = find_option_blocks(text)
+    rec_numbers = [int(n) for n in REC_LINE_RE.findall(text)]
+
+    if not blocks:
+        return 0, "ok (no numbered options block)"
+
+    if not rec_numbers:
+        if strict:
+            return 5, "numbered options without Recommendation:/Empfehlung: line"
+        return 0, "ok (options without recommendation; non-strict)"
+
+    distinct = sorted(set(rec_numbers))
+    if len(distinct) > 1:
+        return 3, f"multiple distinct recommendation numbers: {distinct}"
+
+    rec_num = distinct[0]
+    for block in blocks:
+        if rec_num in block:
+            return 0, f"ok (recommendation {rec_num} matches option block)"
+    return 4, f"recommendation {rec_num} not present in any option block"
+
+
+def cmd_scan_dir(root: Path) -> int:
+    # If the requested root is the legacy ".agent-src.uncondensed" and it
+    # no longer exists (post-monorepo-move), fall back to artefact_roots()
+    # so every packages/*/.agent-src.uncondensed/ is scanned.
+    if not root.is_dir():
+        legacy = ROOT / ".agent-src.uncondensed"
+        if root.resolve() == legacy.resolve():
+            roots = artefact_roots()
+            if not roots:
+                print("error: no artefact roots found (legacy or packages/*)", file=sys.stderr)
+                return 9
+        else:
+            print(f"error: not a directory: {root}", file=sys.stderr)
+            return 9
+    else:
+        roots = [root]
+    violations: list[tuple[Path, int, str]] = []
+    for r in roots:
+        for md in sorted(r.rglob("*.md")):
+            text = md.read_text(encoding="utf-8")
+            for idx, raw in enumerate(text.splitlines(), start=1):
+                stripped = _strip_codespans(raw)
+                if OPTION_LINE_RE.match(stripped) and TAG_RE.search(stripped):
+                    violations.append((md, idx, raw.strip()))
+    if violations:
+        for path, line, snippet in violations:
+            print(f"  🔴 {path}:{line} — inline-tag — {snippet}", file=sys.stderr)
+        print(f"\n❌  {len(violations)} legacy-pattern violation(s)", file=sys.stderr)
+        return 6
+    if not QUIET:
+        def _rel(p: Path) -> str:
+            try:
+                return p.relative_to(ROOT).as_posix()
+            except ValueError:
+                return p.as_posix()
+        scanned = ", ".join(_rel(r) for r in roots)
+        print(f"✅  No legacy (recommended) tags found under {scanned}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description=__doc__.split("\n", 1)[0])
+    g = p.add_mutually_exclusive_group(required=True)
+    g.add_argument("--stdin", action="store_true", help="read draft from stdin")
+    g.add_argument("--file", type=Path, help="read draft from file")
+    g.add_argument("--scan-dir", type=Path, help="scan dir for legacy inline tags")
+    p.add_argument("--strict", action="store_true",
+                   help="numbered options REQUIRE recommendation line (rule 5)")
+    p.add_argument("-v", "--verbose", action="store_true")
+    p.add_argument("--quiet", action="store_true",
+                   help="suppress success messages (P10.5)")
+    args = p.parse_args(argv)
+
+    if args.scan_dir:
+        return cmd_scan_dir(args.scan_dir)
+
+    text = sys.stdin.read() if args.stdin else args.file.read_text(encoding="utf-8")
+    code, msg = validate(text, strict=args.strict)
+    if code == 0:
+        if args.verbose:
+            if not QUIET:
+                print(f"✅  {msg}")
+        return 0
+    print(f"❌  [exit {code}] {msg}", file=sys.stderr)
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/scripts/check_roadmap_trackable.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""CI guard for the `roadmap-progress-sync` rule's trackability Iron Law.
+
+Every non-draft file under `agents/roadmaps/` (excluding `archive/`,
+`skipped/`, template/README/open-questions) MUST:
+
+  1. Be parseable by the dashboard's `PHASE_RE` — i.e. contain at least
+     one `## Phase <id>` or `### Phase <id>` heading.
+  2. Have at least one trackable checkbox (`- [ ]`, `[x]`, `[~]`, `[-]`)
+     under every parsed phase.
+
+A roadmap that fails (1) is invisible to `agents/roadmaps-progress.md`
+and silently lies to the next reader. A phase that fails (2) shows as
+`⬜ empty` and contributes nothing to progress percentages.
+
+Both failure modes are rule violations per
+`.augment/rules/roadmap-progress-sync.md` § "Iron Law — every active
+roadmap is trackable". This script is the CI backstop so the rule
+cannot be quietly broken again.
+
+Exit codes:
+  0 — every active roadmap has parseable phases with at least one
+      checkbox per phase.
+  1 — at least one violation found; details printed to stdout.
+
+Invocation (from project root):
+  python3 scripts/check_roadmap_trackable.py
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# Reuse the dashboard's regexes and helpers — single source of truth so
+# the linter cannot drift from what the dashboard actually parses.
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent / ".augment" / "scripts"))
+from update_roadmap_progress import (  # noqa: E402
+    CHECKBOX_RE,
+    PHASE_RE,
+    is_draft,
+    is_roadmap_candidate,
+    parse_frontmatter,
+)
+
+QUIET = "--quiet" in sys.argv
+
+ROADMAP_ROOT = Path("agents/roadmaps")
+
+
+def find_active_roadmaps(root: Path) -> list[Path]:
+    """Return every non-draft roadmap candidate under root."""
+    out: list[Path] = []
+    for path in sorted(root.rglob("*.md")):
+        if not path.is_file() or not is_roadmap_candidate(path):
+            continue
+        text = path.read_text(encoding="utf-8")
+        if is_draft(parse_frontmatter(text)):
+            continue
+        out.append(path)
+    return out
+
+
+def violations_for(path: Path) -> list[str]:
+    """Return human-readable violation strings for a single roadmap."""
+    text = path.read_text(encoding="utf-8")
+    matches = list(PHASE_RE.finditer(text))
+    if not matches:
+        return [
+            f"{path}: no `## Phase <id>` or `### Phase <id>` heading "
+            "matched the dashboard's PHASE_RE — roadmap is invisible "
+            "to agents/roadmaps-progress.md. Either rename headings to "
+            "the canonical `Phase <id>` form or add `status: draft` to "
+            "the frontmatter."
+        ]
+    out: list[str] = []
+    for i, pm in enumerate(matches):
+        start = pm.end()
+        end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
+        if not CHECKBOX_RE.search(text[start:end]):
+            phase_id = pm.group(2)
+            name = (pm.group(3) or "").strip() or f"Phase {phase_id}"
+            out.append(
+                f"{path}: Phase {phase_id} ({name[:60]}) has zero "
+                "trackable checkboxes — add at least one `- [ ]` (or "
+                "`[x]`/`[~]`/`[-]`) item or remove the phase."
+            )
+    return out
+
+
+def main() -> int:
+    if not ROADMAP_ROOT.is_dir():
+        print(f"❌  {ROADMAP_ROOT} not found — run from project root.", file=sys.stderr)
+        return 1
+    findings: list[str] = []
+    for path in find_active_roadmaps(ROADMAP_ROOT):
+        findings.extend(violations_for(path))
+    if findings:
+        print("❌  Trackable-roadmap rule violations:\n")
+        for f in findings:
+            print(f"  - {f}")
+        print(
+            "\nRule: .augment/rules/roadmap-progress-sync.md "
+            '§ "Iron Law — every active roadmap is trackable"'
+        )
+        return 1
+    count = len(find_active_roadmaps(ROADMAP_ROOT))
+    if not QUIET:
+        print(f"✅  {count} active roadmap(s) — all parseable, all phases have checkboxes.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/scripts/check_role_doc_links.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""Verify every skill link in role-based docs resolves to a real file.
+
+Part of step-12 Phase 2. Runs in `task ci` to catch link rot when a
+skill is renamed or removed but the role docs still reference it.
+
+Scans `docs/getting-started-by-role.md` and `docs/getting-started-laravel.md`
+for markdown links of the form `../dist/agent-src/skills/<name>/SKILL.md`
+(relative to docs/) and checks that the target file exists on disk.
+
+Exit codes:
+  0 — every link resolves
+  1 — at least one broken link; prints the offending file:line:url tuples
+  2 — usage error (one of the role doc files missing)
+
+Usage:
+  python3 scripts/check_role_doc_links.py
+  python3 scripts/check_role_doc_links.py --quiet
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent.parent
+DOCS_DIR = ROOT / "docs"
+
+# (display-path, on-disk path, link-anchor) — anchor is the relative
+# prefix that identifies a skill link from inside docs/.
+ROLE_DOCS = [
+    DOCS_DIR / "getting-started-by-role.md",
+    DOCS_DIR / "getting-started-laravel.md",
+]
+
+# Markdown link: [label](path). We only check the (path) part. The
+# regex tolerates trailing #anchor fragments and ignores absolute URLs.
+LINK_RE = re.compile(r"\]\(([^)\s]+)\)")
+
+# Anchors we know how to resolve. Each tuple is (prefix, base_dir).
+ANCHORS: list[tuple[str, Path]] = [
+    ("../dist/agent-src/skills/", ROOT / "dist/agent-src" / "skills"),
+    ("../dist/agent-src/commands/", ROOT / "dist/agent-src" / "commands"),
+    ("../dist/agent-src/rules/", ROOT / "dist/agent-src" / "rules"),
+    ("../agents/", ROOT / "agents"),
+    ("contracts/", DOCS_DIR / "contracts"),
+    ("guidelines/", DOCS_DIR / "guidelines"),
+]
+
+
+def resolve(url: str, doc_path: Path) -> Path | None:
+    """Return the on-disk target path for a relative link, or None if external."""
+    if url.startswith(("http://", "https://", "mailto:")):
+        return None
+    bare = url.split("#", 1)[0]
+    if not bare:
+        return None
+    # Relative to the doc's own directory.
+    target = (doc_path.parent / bare).resolve()
+    return target
+
+
+def scan(doc_path: Path) -> list[tuple[int, str]]:
+    """Return list of (line_no, url) tuples for every non-external link."""
+    if not doc_path.is_file():
+        print(f"error: missing role doc: {doc_path}", file=sys.stderr)
+        sys.exit(2)
+    links: list[tuple[int, str]] = []
+    for i, line in enumerate(doc_path.read_text(encoding="utf-8").splitlines(), 1):
+        for m in LINK_RE.finditer(line):
+            url = m.group(1)
+            if url.startswith(("http://", "https://", "mailto:")):
+                continue
+            links.append((i, url))
+    return links
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    p.add_argument("--quiet", action="store_true", help="Suppress success summary.")
+    args = p.parse_args()
+
+    failures: list[tuple[Path, int, str]] = []
+    checked = 0
+
+    for doc in ROLE_DOCS:
+        for line_no, url in scan(doc):
+            target = resolve(url, doc)
+            if target is None:
+                continue
+            checked += 1
+            if not target.exists():
+                failures.append((doc, line_no, url))
+
+    if failures:
+        print("Broken links in role docs:", file=sys.stderr)
+        for doc, line_no, url in failures:
+            rel = doc.relative_to(ROOT)
+            print(f"  {rel}:{line_no}  -> {url}", file=sys.stderr)
+        print(f"\n{len(failures)} broken / {checked} checked", file=sys.stderr)
+        return 1
+
+    if not args.quiet:
+        print(f"check_role_doc_links: {checked} links OK across {len(ROLE_DOCS)} files")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())