@event4u/agent-config 2.26.0 → 3.1.0

package/scripts/lint_mcp_registry_manifest.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Lint `dist/mcp/registry-manifest.json` against its JSON Schema.
+
+Asserts:
+  * file exists
+  * validates against `docs/contracts/mcp-registry-manifest.schema.json`
+  * `dist/mcp/awesome-mcp-servers.row.md` is non-empty and parses as a
+    single Markdown table row (one `|`-delimited line)
+  * `dist/mcp/mcp-cloudflare-catalogue.json` is valid JSON
+
+Exits 0 on success, 1 on any failure. `--quiet` suppresses the OK line.
+
+Roadmap: agents/roadmaps/strategic-visibility-mcp-topics-positioning.md Phase 2 exit gate.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import jsonschema
+
+ROOT = Path(__file__).resolve().parents[1]
+SCHEMA = ROOT / "docs" / "contracts" / "mcp-registry-manifest.schema.json"
+MANIFEST = ROOT / "dist" / "mcp" / "registry-manifest.json"
+ROW_MD = ROOT / "dist" / "mcp" / "awesome-mcp-servers.row.md"
+CF_JSON = ROOT / "dist" / "mcp" / "mcp-cloudflare-catalogue.json"
+
+
+def _fail(msg: str) -> int:
+    print(f"\u274c  {msg}", file=sys.stderr)
+    return 1
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--quiet", action="store_true")
+    args = ap.parse_args()
+
+    for p in (SCHEMA, MANIFEST, ROW_MD, CF_JSON):
+        if not p.exists():
+            return _fail(f"missing: {p.relative_to(ROOT)}")
+
+    schema = json.loads(SCHEMA.read_text(encoding="utf-8"))
+    manifest = json.loads(MANIFEST.read_text(encoding="utf-8"))
+    try:
+        jsonschema.Draft202012Validator(schema).validate(manifest)
+    except jsonschema.ValidationError as e:
+        return _fail(f"schema validation: {e.message} at {list(e.absolute_path)}")
+
+    row = ROW_MD.read_text(encoding="utf-8").strip()
+    if not row:
+        return _fail("awesome-mcp-servers.row.md is empty")
+    if row.count("\n") != 0 or row.count("|") < 4:
+        return _fail("awesome-mcp-servers.row.md must be a single `|`-delimited row")
+
+    try:
+        json.loads(CF_JSON.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        return _fail(f"mcp-cloudflare-catalogue.json: {e}")
+
+    if not args.quiet:
+        print(f"\u2705  mcp registry manifest OK ({len(manifest['registries'])} registries)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/lint_media_policy_linkage.py

@@ -1,18 +1,18 @@
 #!/usr/bin/env python3
 """Lint structural reachability of media governance policies.
 
-Every policy file under `agents/policies/media/` (except README) must
+Every policy file under `agents/settings/policies/media/` (except README) must
 be linked from at least one of:
 
   * a skill SKILL.md (any .agent-src.uncompressed/skills/*/SKILL.md
     or .claude/skills/*/SKILL.md),
   * a routing rule under .agent-src.uncompressed/rules/, or
-  * a sibling policy file under agents/policies/media/.
+  * a sibling policy file under agents/settings/policies/media/.
 
 A policy that no surface references is a silent policy and a silent
 policy is a failed policy. This is the CI-side reachability guarantee
 the agent-in-the-loop enforcement model rests on (see
-agents/policies/media/README.md § Enforcement model).
+agents/settings/policies/media/README.md § Enforcement model).
 
 Exit codes:
   0  all policies linked
@@ -66,7 +66,7 @@ def collect_scan_files() -> list[Path]:
 def referrers_for(policy: Path, scan_files: list[Path]) -> list[Path]:
     """Return files that reference `policy` by its repo-relative name
     or basename. We accept both the full path token
-    (`agents/policies/media/likeness.md`) and the bare basename
+    (`agents/settings/policies/media/likeness.md`) and the bare basename
     (`likeness.md`) inside a markdown link, because sibling policies
     link via relative `[likeness.md](likeness.md)` form.
     """
@@ -91,7 +91,7 @@ def referrers_for(policy: Path, scan_files: list[Path]) -> list[Path]:
 def main() -> int:
     if not POLICY_DIR.exists():
         emit(
-            "media-policy-linkage: agents/policies/media/ missing — "
+            "media-policy-linkage: agents/settings/policies/media/ missing — "
             "nothing to lint."
         )
         return 0
@@ -99,7 +99,7 @@ def main() -> int:
     policies = collect_policies()
     if not policies:
         emit(
-            "media-policy-linkage: agents/policies/media/ has no policy "
+            "media-policy-linkage: agents/settings/policies/media/ has no policy "
             "files — nothing to lint."
         )
         return 0

package/scripts/lint_orchestration_dsl.py

@@ -33,6 +33,9 @@ import sys
 from pathlib import Path
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+from _lib.agent_src import resolve_logical  # noqa: E402
+
 DEFAULT_DIR = REPO_ROOT / ".agent-config" / "orchestrations"
 
 NAME_RE = re.compile(r"^[a-z][a-z0-9-]*$")
@@ -62,11 +65,11 @@ def _load_yaml(path: Path) -> object:
 
 def _ref_exists(kind: str, ref: str) -> bool:
     if kind == "skill":
-        return (REPO_ROOT / ".agent-src.uncompressed" / "skills" / ref / "SKILL.md").is_file()
+        return resolve_logical(f"skills/{ref}/SKILL.md") is not None
     if kind == "command":
-        return (REPO_ROOT / ".agent-src.uncompressed" / "commands" / f"{ref}.md").is_file()
+        return resolve_logical(f"commands/{ref}.md") is not None
     if kind == "persona":
-        return (REPO_ROOT / ".agent-src.uncompressed" / "personas" / f"{ref}.md").is_file()
+        return resolve_logical(f"personas/{ref}.md") is not None
     if kind == "subagent":
         return ref in SUBAGENT_MODES
     return False

package/scripts/lint_pack_boundaries.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""Enforce cross-pack reference boundaries.
+
+Phase 4.4 of the monorepo migration (ADR-017). Walks every markdown
+link in every artefact under ``packages/*/.agent-src.uncompressed/``
+and verifies the link target's pack is either the same pack, ``core``
+(always allowed), or listed in the source pack's ``requires``.
+
+Reports every violation with ``source -> target`` plus the offending
+pack edge. Exits non-zero if any are found.
+
+CLI:
+  --format text|json   default text
+  --quiet              suppress per-file noise; only print violations
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+PACKAGES = ROOT / "packages"
+
+LINK_RE = re.compile(r"\[[^\]]*\]\(([^)#?]+)(?:[#?][^)]*)?\)")
+
+
+def _load_pack_meta(pkg_dir: Path) -> dict[str, Any]:
+    pack_yaml = pkg_dir / "pack.yaml"
+    if not pack_yaml.exists():
+        return {}
+    data = yaml.safe_load(pack_yaml.read_text(encoding="utf-8"))
+    return data if isinstance(data, dict) else {}
+
+
+def _build_artefact_index() -> dict[str, str]:
+    """Map repo-relative POSIX artefact path -> pack id."""
+    index: dict[str, str] = {}
+    if not PACKAGES.exists():
+        return index
+    for pkg in sorted(PACKAGES.iterdir()):
+        if not pkg.is_dir():
+            continue
+        src_root = pkg / ".agent-src.uncompressed"
+        if not src_root.is_dir():
+            continue
+        pid = _load_pack_meta(pkg).get("id") or pkg.name.removeprefix("pack-")
+        for p in src_root.rglob("*.md"):
+            if p.is_file():
+                index[p.relative_to(ROOT).as_posix()] = pid
+    return index
+
+
+def _resolve_link(source_file: Path, raw: str) -> Path | None:
+    """Resolve a markdown link target to a repo-relative path, or None."""
+    target = raw.strip()
+    if not target or target.startswith(("http://", "https://", "mailto:", "ftp://")):
+        return None
+    if target.startswith("/"):
+        return None  # absolute web paths, ignored
+    try:
+        resolved = (source_file.parent / target).resolve()
+    except OSError:
+        return None
+    try:
+        return resolved.relative_to(ROOT)
+    except ValueError:
+        return None
+
+
+def _scan_file(path: Path) -> list[str]:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return []
+    return LINK_RE.findall(text)
+
+
+def _is_allowed(source_pack: str, target_pack: str, requires: list[str]) -> bool:
+    if source_pack == target_pack:
+        return True
+    if target_pack == "core":
+        return True
+    return target_pack in (requires or [])
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--format", choices=["text", "json"], default="text")
+    ap.add_argument("--quiet", action="store_true")
+    args = ap.parse_args()
+
+    artefact_pack = _build_artefact_index()
+    if not artefact_pack:
+        print("no packages/ tree to lint — skipping", file=sys.stderr)
+        return 0
+
+    pack_requires: dict[str, list[str]] = {}
+    for pkg in sorted(PACKAGES.iterdir()):
+        if pkg.is_dir():
+            meta = _load_pack_meta(pkg)
+            pid = meta.get("id") or pkg.name.removeprefix("pack-")
+            pack_requires[pid] = list(meta.get("requires") or [])
+
+    violations: list[dict[str, str]] = []
+    for rel_path, src_pack in artefact_pack.items():
+        source_file = ROOT / rel_path
+        for raw in _scan_file(source_file):
+            target_rel = _resolve_link(source_file, raw)
+            if target_rel is None:
+                continue
+            target_key = target_rel.as_posix()
+            target_pack = artefact_pack.get(target_key)
+            if target_pack is None:
+                continue  # link to docs/, scripts/, root files — not pack-scoped
+            if _is_allowed(src_pack, target_pack, pack_requires.get(src_pack, [])):
+                continue
+            violations.append({
+                "source_pack": src_pack,
+                "target_pack": target_pack,
+                "source": rel_path,
+                "target": target_key,
+                "link": raw,
+            })
+
+    if args.format == "json":
+        json.dump({"violations": violations, "count": len(violations)}, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+    else:
+        if not args.quiet:
+            print(f"lint_pack_boundaries: scanned {len(artefact_pack)} artefacts across {len(pack_requires)} packs")
+        for v in violations:
+            print(f"  ✗ {v['source_pack']} -> {v['target_pack']} : {v['source']} → {v['target']} (link: {v['link']})")
+        if violations:
+            print(f"\n{len(violations)} cross-pack violation(s) — declare 'requires' in pack.yaml or move the artefact")
+        elif not args.quiet:
+            print("OK — no cross-pack drift")
+    return 1 if violations else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_pack_first_win.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""Lint: every featured pack ships FIRST_WIN.md + onboarding: block.
+
+Phase 4 Step 4 of road-to-role-first-onboarding.md.
+
+A pack is "featured" when its id appears in the
+FEATURED_PACK_IDS set below — currently the five role-first packs
+listed in docs/featured-skills.md.
+
+Each featured pack MUST have:
+  - packages/pack-<id>/FIRST_WIN.md (file present, > 0 bytes)
+  - packages/pack-<id>/pack.yaml with an `onboarding:` block carrying
+    `first_win_doc`, `example_workflow`, `time_to_first_value_minutes`
+
+Exits non-zero on any violation. Stdlib-only (no PyYAML — uses simple
+YAML scan since pack.yaml is generator-controlled flat shape).
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+PACKAGES = REPO_ROOT / "packages"
+
+FEATURED_PACK_IDS = {
+    "founder-strategy",
+    "finance-basic",
+    "gtm-sales",
+    "ops-people",
+    "ai-video",
+}
+
+REQUIRED_ONBOARDING_KEYS = (
+    "first_win_doc",
+    "example_workflow",
+    "time_to_first_value_minutes",
+)
+
+
+def _has_onboarding_block(pack_yaml: Path) -> tuple[bool, list[str]]:
+    """Return (ok, missing_keys). Uses a tiny scanner — pack.yaml is
+    generator-controlled, so we only check for the literal `onboarding:`
+    parent key and the three required child keys nested under it."""
+    if not pack_yaml.exists():
+        return False, list(REQUIRED_ONBOARDING_KEYS)
+    lines = pack_yaml.read_text(encoding="utf-8").splitlines()
+    in_block = False
+    found: set[str] = set()
+    for raw in lines:
+        if raw.startswith("onboarding:"):
+            in_block = True
+            continue
+        if in_block:
+            if raw and not raw.startswith((" ", "\t")):
+                break
+            stripped = raw.strip()
+            for key in REQUIRED_ONBOARDING_KEYS:
+                if stripped.startswith(f"{key}:"):
+                    found.add(key)
+    if not in_block:
+        return False, list(REQUIRED_ONBOARDING_KEYS)
+    missing = [k for k in REQUIRED_ONBOARDING_KEYS if k not in found]
+    return not missing, missing
+
+
+def main() -> int:
+    errors: list[str] = []
+    for pid in sorted(FEATURED_PACK_IDS):
+        pack_dir = PACKAGES / f"pack-{pid}"
+        if not pack_dir.is_dir():
+            errors.append(f"missing pack dir: {pack_dir.relative_to(REPO_ROOT)}")
+            continue
+        first_win = pack_dir / "FIRST_WIN.md"
+        if not first_win.exists() or first_win.stat().st_size == 0:
+            errors.append(
+                f"missing or empty: {first_win.relative_to(REPO_ROOT)}"
+            )
+        ok, missing = _has_onboarding_block(pack_dir / "pack.yaml")
+        if not ok:
+            errors.append(
+                f"{pack_dir.name}/pack.yaml: onboarding block missing "
+                f"key(s) {missing!r}"
+            )
+    if errors:
+        print("❌ pack first-win lint failed:", file=sys.stderr)
+        for e in errors:
+            print(f"  - {e}", file=sys.stderr)
+        print(
+            "  fix: add FIRST_WIN.md to the pack root and the onboarding "
+            "block to config/discovery/packs.yml, then re-run "
+            "`task generate-pack-manifests`",
+            file=sys.stderr,
+        )
+        return 1
+    print(
+        f"✅ pack first-win lint OK — {len(FEATURED_PACK_IDS)} featured packs"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_positioning.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Positioning consistency lint for event4u/agent-config.
+
+Asserts that three public-positioning surfaces agree on the canonical
+phrasing and that every advertised GitHub topic is discoverable in the
+README body (literally or through `equivalents:` paraphrases).
+
+Sources:
+  - README.md              — canonical phrasing (H1 + first blockquote)
+  - package.json           — `description` field
+  - .github/about.yml      — `description` field
+  - .github/topics.yml     — `topics:` + optional `equivalents:` map
+
+Failure mode is a diff, not a stack trace. See R5 Phase 3 in
+agents/roadmaps/strategic-visibility-mcp-topics-positioning.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:
+    sys.stderr.write("❌  PyYAML is required: pip3 install pyyaml\n")
+    sys.exit(2)
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+README = REPO_ROOT / "README.md"
+PACKAGE_JSON = REPO_ROOT / "package.json"
+ABOUT_YML = REPO_ROOT / ".github" / "about.yml"
+TOPICS_YML = REPO_ROOT / ".github" / "topics.yml"
+
+# Canonical anchor: the right-side phrase of the README H1
+# ("Agent Config — Universal AI Agent OS" → "Universal AI Agent OS").
+# This is the substring that MUST appear in the other two surfaces.
+H1_RE = re.compile(r"^#\s+(.+?)\s*$", re.MULTILINE)
+BLOCKQUOTE_RE = re.compile(r"^>\s+(.+?)\s*$", re.MULTILINE)
+DESCRIPTION_MAX = 200
+
+
+def _read_readme_anchors() -> tuple[str, str, str]:
+    text = README.read_text(encoding="utf-8")
+    h1_match = H1_RE.search(text)
+    if not h1_match:
+        raise SystemExit("❌  README.md has no H1 heading")
+    h1 = h1_match.group(1)
+    # Anchor = the phrase after the em dash, falling back to the whole H1.
+    parts = re.split(r"\s+[—–-]\s+", h1, maxsplit=1)
+    anchor = parts[1].strip() if len(parts) == 2 else h1.strip()
+
+    bq_match = BLOCKQUOTE_RE.search(text)
+    blockquote = bq_match.group(1).strip() if bq_match else ""
+    return h1, anchor, blockquote
+
+
+def _read_package_description() -> str:
+    data = json.loads(PACKAGE_JSON.read_text(encoding="utf-8"))
+    return str(data.get("description", "")).strip()
+
+
+def _read_about_description() -> str:
+    data = yaml.safe_load(ABOUT_YML.read_text(encoding="utf-8")) or {}
+    return str(data.get("description", "")).strip()
+
+
+def _read_topics() -> tuple[list[str], dict[str, list[str]]]:
+    data = yaml.safe_load(TOPICS_YML.read_text(encoding="utf-8")) or {}
+    topics = [str(t) for t in data.get("topics", [])]
+    equivalents = {str(k): [str(v) for v in vs] for k, vs in (data.get("equivalents") or {}).items()}
+    return topics, equivalents
+
+
+def _topic_present(readme_lc: str, topic: str, equivalents: dict[str, list[str]]) -> tuple[bool, str | None]:
+    needles = [topic, topic.replace("-", " "), topic.replace("-", "")] + equivalents.get(topic, [])
+    for n in needles:
+        if n and n.lower() in readme_lc:
+            return True, n
+    return False, None
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Positioning consistency lint.")
+    parser.add_argument("--quiet", action="store_true", help="Suppress success output.")
+    args = parser.parse_args()
+
+    h1, anchor, blockquote = _read_readme_anchors()
+    pkg_desc = _read_package_description()
+    about_desc = _read_about_description()
+    topics, equivalents = _read_topics()
+
+    errors: list[str] = []
+    anchor_lc = anchor.lower()
+    if anchor_lc not in pkg_desc.lower():
+        errors.append("package.json.description missing canonical anchor")
+    if anchor_lc not in about_desc.lower():
+        errors.append(".github/about.yml description missing canonical anchor")
+    if len(pkg_desc) > DESCRIPTION_MAX:
+        errors.append(f"package.json.description is {len(pkg_desc)} chars (max {DESCRIPTION_MAX})")
+    if len(about_desc) > DESCRIPTION_MAX:
+        errors.append(f".github/about.yml description is {len(about_desc)} chars (max {DESCRIPTION_MAX})")
+
+    readme_lc = README.read_text(encoding="utf-8").lower()
+    missing_topics: list[str] = []
+    for topic in topics:
+        present, _ = _topic_present(readme_lc, topic, equivalents)
+        if not present:
+            missing_topics.append(topic)
+
+    if errors or missing_topics:
+        sys.stderr.write("❌  positioning drift detected:\n")
+        sys.stderr.write(f"        README anchor:         {anchor}\n")
+        sys.stderr.write(f"        package.json.desc:     {pkg_desc}\n")
+        sys.stderr.write(f"        .github/about.yml:     {about_desc}\n\n")
+        for err in errors:
+            sys.stderr.write(f"        - {err}\n")
+        if missing_topics:
+            sys.stderr.write("\n        topics absent from README (literal + equivalents):\n")
+            for t in missing_topics:
+                sys.stderr.write(f"          - {t}\n")
+            sys.stderr.write(
+                "\n        Resolve by editing all three to share the canonical anchor,\n"
+                "        or extending .github/topics.yml's `equivalents:` map\n"
+                "        (or by removing the topic). The README is the canonical phrasing.\n"
+            )
+        else:
+            sys.stderr.write(
+                "\n        Resolve by editing all three to share the canonical anchor.\n"
+                "        The README is the canonical phrasing; the other two follow it.\n"
+            )
+        return 1
+
+    if not args.quiet:
+        sys.stdout.write(f"✅  positioning consistent (anchor: {anchor!r}, topics: {len(topics)})\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_readme_jargon.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""CI guard for README.md above-fold jargon density.
+
+The role-first-onboarding roadmap (Phase 2 Step 3) targets non-developer
+readers above the fold. Lines 1..ABOVE_FOLD_LINES of README.md MUST
+contain at most MAX_HITS occurrences of the watchlist terms below
+(case-insensitive, whole-word matched).
+
+Watchlist comes from feedback8 — words that read fine to a maintainer
+but bounce a Founder or Creator off the page within five seconds:
+
+    kernel · contract · iron law · projection · manifest · lint ·
+    ADR · soak · drift · gate · harness
+
+Counting rules:
+  - Case-insensitive.
+  - Whole-word match (no partial hits inside other words).
+  - Skip fenced code blocks (```...```), HTML comments, and link URLs.
+  - Each match counts once at its location; multi-line lints stay
+    deterministic.
+
+Exit codes:
+  0 — above-fold jargon hits <= MAX_HITS.
+  1 — above-fold jargon hits >  MAX_HITS (print line + match summary).
+
+Invocation:
+  python3 scripts/lint_readme_jargon.py
+  python3 scripts/lint_readme_jargon.py --quiet
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+README = Path("README.md")
+ABOVE_FOLD_LINES = 120
+MAX_HITS = 3
+
+WATCHLIST = (
+    "kernel",
+    "contract",
+    "iron law",
+    "projection",
+    "manifest",
+    "lint",
+    "ADR",
+    "soak",
+    "drift",
+    "gate",
+    "harness",
+)
+
+
+def _strip_noise(lines: list[str]) -> list[str]:
+    """Return per-line content with fences / HTML comments / URLs removed.
+
+    Order matters: drop URLs first (they may sit inside fences), then
+    blank out fenced code regions so word-boundary matches don't trip
+    on stack-trace or shell tokens.
+    """
+    url_re = re.compile(r"https?://\S+|\(\.[\w./-]+\)")
+    cleaned: list[str] = []
+    in_fence = False
+    in_html = False
+    for raw in lines:
+        line = raw
+        if "<!--" in line and "-->" not in line:
+            in_html = True
+        if in_html:
+            cleaned.append("")
+            if "-->" in line:
+                in_html = False
+            continue
+        stripped = line.strip()
+        if stripped.startswith("```"):
+            in_fence = not in_fence
+            cleaned.append("")
+            continue
+        if in_fence:
+            cleaned.append("")
+            continue
+        cleaned.append(url_re.sub(" ", line))
+    return cleaned
+
+
+def main() -> int:
+    quiet = "--quiet" in sys.argv
+    if not README.exists():
+        print(f"error: {README} not found", file=sys.stderr)
+        return 1
+
+    all_lines = README.read_text(encoding="utf-8").splitlines()
+    head = _strip_noise(all_lines[:ABOVE_FOLD_LINES])
+
+    patterns = [
+        (term, re.compile(r"(?<![A-Za-z0-9])" + re.escape(term) + r"(?![A-Za-z0-9])", re.IGNORECASE))
+        for term in WATCHLIST
+    ]
+
+    hits: list[tuple[int, str, str]] = []
+    for idx, content in enumerate(head, start=1):
+        for term, pat in patterns:
+            for m in pat.finditer(content):
+                hits.append((idx, term, m.group(0)))
+
+    if len(hits) > MAX_HITS:
+        print(
+            f"FAIL  {README}: {len(hits)} jargon hits above the fold "
+            f"(lines 1..{ABOVE_FOLD_LINES}, limit {MAX_HITS})."
+        )
+        for line_no, term, match in hits:
+            print(f"  L{line_no:>3}  {term:<10}  -> {match!r}")
+        print(
+            "\nFix: rewrite the line in role-first language. Move the "
+            "term below line "
+            f"{ABOVE_FOLD_LINES + 1} (architecture / contracts section)."
+        )
+        return 1
+
+    if not quiet:
+        print(
+            f"OK    {README}: {len(hits)} jargon hits above the fold "
+            f"(limit {MAX_HITS})."
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())