@event4u/agent-config 1.14.0 → 1.16.0

package/scripts/check_roadmap_trackable.py

@@ -0,0 +1,111 @@
+#!/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 / ".augment" / "scripts"))
+from update_roadmap_progress import (  # noqa: E402
+    CHECKBOX_RE,
+    PHASE_RE,
+    is_draft,
+    is_roadmap_candidate,
+    parse_frontmatter,
+)
+
+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))
+    print(f"✅  {count} active roadmap(s) — all parseable, all phases have checkboxes.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/command_suggester/cooldown.py

@@ -31,7 +31,7 @@ def is_explicit_slash_invocation(message: str) -> bool:
 
     Per the `command-suggestion` rule, explicit slash invocations
     bypass the suggestion layer entirely \u2014 they're handled by
-    `slash-commands` directly. The engine should not score in that
+    `slash-command-routing-policy` directly. The engine should not score in that
     case. Helper exposed for the runtime caller and the GT-CS4
     golden.
     """

package/scripts/generate_index.py

@@ -0,0 +1,266 @@
+#!/usr/bin/env python3
+"""Generate `agents/index.md` (internal) and `docs/catalog.md` (public).
+
+Scans `.agent-src.uncompressed/{skills,rules,commands}/` plus `docs/guidelines/`
+and renders two artefact tables — one for maintainers, one for consumers.
+
+Both files are sync-checked in CI via `--check`; drift = build break.
+
+Usage:
+    python3 scripts/generate_index.py            # write both files
+    python3 scripts/generate_index.py --check    # exit 1 if drift
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SRC = ROOT / ".agent-src.uncompressed"
+GUIDELINES = ROOT / "docs" / "guidelines"
+INDEX_PATH = ROOT / "agents" / "index.md"
+CATALOG_PATH = ROOT / "docs" / "catalog.md"
+
+# Internal-only rules — excluded from the public catalog.
+INTERNAL_RULES = {
+    "augment-source-of-truth",
+    "augment-portability",
+    "docs-sync",
+}
+
+FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+
+
+@dataclass(frozen=True)
+class Entry:
+    kind: str          # skill | rule | command | shim | guideline
+    name: str
+    description: str
+    extra: str         # rule type · cluster · sub-folder, etc.
+    path: str          # repo-relative link target
+
+
+def _parse_frontmatter(text: str) -> dict[str, str]:
+    m = FRONTMATTER_RE.match(text)
+    if not m:
+        return {}
+    out: dict[str, str] = {}
+    for line in m.group(1).splitlines():
+        if ":" not in line or line.startswith(" "):
+            continue
+        k, _, v = line.partition(":")
+        out[k.strip()] = v.strip().strip('"').strip("'")
+    return out
+
+
+def _truncate(text: str, limit: int = 200) -> str:
+    text = text.replace("|", "\\|").replace("\n", " ").strip()
+    return text if len(text) <= limit else text[: limit - 1].rstrip() + "…"
+
+
+def _collect_skills() -> list[Entry]:
+    out = []
+    for skill_dir in sorted((SRC / "skills").iterdir()):
+        skill_md = skill_dir / "SKILL.md"
+        if not skill_md.exists():
+            continue
+        fm = _parse_frontmatter(skill_md.read_text(encoding="utf-8"))
+        name = fm.get("name") or skill_dir.name
+        out.append(Entry(
+            kind="skill",
+            name=name,
+            description=_truncate(fm.get("description", "")),
+            extra="",
+            path=f".agent-src.uncompressed/skills/{skill_dir.name}/SKILL.md",
+        ))
+    return out
+
+
+def _collect_rules() -> list[Entry]:
+    out = []
+    for rule_md in sorted((SRC / "rules").glob("*.md")):
+        fm = _parse_frontmatter(rule_md.read_text(encoding="utf-8"))
+        out.append(Entry(
+            kind="rule",
+            name=rule_md.stem,
+            description=_truncate(fm.get("description", "")),
+            extra=fm.get("type", "?"),
+            path=f".agent-src.uncompressed/rules/{rule_md.name}",
+        ))
+    return out
+
+
+def _collect_commands() -> list[Entry]:
+    out = []
+    for cmd_md in sorted((SRC / "commands").glob("*.md")):
+        fm = _parse_frontmatter(cmd_md.read_text(encoding="utf-8"))
+        is_shim = bool(fm.get("superseded_by"))
+        extra = ""
+        if is_shim:
+            extra = f"shim → /{fm['superseded_by']}"
+        elif fm.get("cluster"):
+            extra = f"cluster: {fm['cluster']}"
+        out.append(Entry(
+            kind="shim" if is_shim else "command",
+            name=fm.get("name") or cmd_md.stem,
+            description=_truncate(fm.get("description", "")),
+            extra=extra,
+            path=f".agent-src.uncompressed/commands/{cmd_md.name}",
+        ))
+    return out
+
+
+def _collect_guidelines() -> list[Entry]:
+    out = []
+    if not GUIDELINES.exists():
+        return out
+    for g_md in sorted(GUIDELINES.rglob("*.md")):
+        rel = g_md.relative_to(ROOT)
+        category = g_md.parent.name if g_md.parent != GUIDELINES else "(root)"
+        out.append(Entry(
+            kind="guideline",
+            name=g_md.stem,
+            description="",
+            extra=category,
+            path=str(rel),
+        ))
+    return out
+
+
+# Path rewriter for the public catalog: link to the shipped surface
+# (`.agent-src/`) instead of the source-of-truth (`.agent-src.uncompressed/`),
+# which is excluded from `package.json#files` and `composer.json` archives.
+def _to_shipped_path(path: str) -> str:
+    return path.replace(".agent-src.uncompressed/", ".agent-src/", 1)
+
+
+def _render_table(
+    entries: list[Entry],
+    cols: list[str],
+    link_prefix: str,
+    path_rewrite=None,
+) -> str:
+    rows = ["| " + " | ".join(cols) + " |", "|" + "|".join(["---"] * len(cols)) + "|"]
+    for e in entries:
+        path = path_rewrite(e.path) if path_rewrite else e.path
+        link = f"[`{e.name}`]({link_prefix}{path})"
+        row = [e.kind, link, e.extra, e.description]
+        rows.append("| " + " | ".join(row) + " |")
+    return "\n".join(rows)
+
+
+
+def _render_index(skills, rules, commands, guidelines) -> str:
+    total = len(skills) + len(rules) + len(commands) + len(guidelines)
+    parts = [
+        "# Agent-Config Internal Index",
+        "",
+        f"Maintainer-facing index of all **{total} artefacts** in this package.",
+        "Auto-generated from `.agent-src.uncompressed/` and `docs/guidelines/`.",
+        "",
+        "> **Regenerate:** `python3 scripts/generate_index.py`",
+        "> **Drift check:** `python3 scripts/generate_index.py --check` (runs in `task ci`)",
+        "> Do not edit manually.",
+        "",
+        f"## Skills ({len(skills)})",
+        "",
+        _render_table(skills, ["kind", "name", "extra", "description"], "../"),
+        "",
+        f"## Rules ({len(rules)})",
+        "",
+        _render_table(rules, ["kind", "name", "type", "description"], "../"),
+        "",
+        f"## Commands ({len(commands)})",
+        "",
+        _render_table(commands, ["kind", "name", "cluster/shim", "description"], "../"),
+        "",
+        f"## Guidelines ({len(guidelines)})",
+        "",
+        _render_table(guidelines, ["kind", "name", "category", "description"], "../"),
+        "",
+    ]
+    return "\n".join(parts)
+
+
+def _render_catalog(skills, rules, commands, guidelines) -> str:
+    public_rules = [r for r in rules if r.name not in INTERNAL_RULES]
+    public_commands = [c for c in commands if c.kind == "command"]
+    total = len(skills) + len(public_rules) + len(public_commands) + len(guidelines)
+    parts = [
+        "# agent-config — Public Catalog",
+        "",
+        f"Consumer-facing catalog of all **{total} public artefacts** shipped by",
+        "this package. Internal package-maintenance rules and deprecation shims",
+        "are excluded.",
+        "",
+        "> **Regenerate:** `python3 scripts/generate_index.py`",
+        "> Auto-generated — do not edit manually.",
+        "",
+        f"## Skills ({len(skills)})",
+        "",
+        _render_table(skills, ["kind", "name", "extra", "description"], "../", _to_shipped_path),
+        "",
+        f"## Rules ({len(public_rules)})",
+        "",
+        _render_table(public_rules, ["kind", "name", "type", "description"], "../", _to_shipped_path),
+        "",
+        f"## Commands ({len(public_commands)})",
+        "",
+        _render_table(public_commands, ["kind", "name", "cluster", "description"], "../", _to_shipped_path),
+        "",
+        f"## Guidelines ({len(guidelines)})",
+        "",
+        _render_table(guidelines, ["kind", "name", "category", "description"], "../", _to_shipped_path),
+        "",
+        "---",
+        "",
+        "← [Back to README](../README.md)",
+        "",
+    ]
+    return "\n".join(parts)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--check", action="store_true",
+                        help="Exit 1 if generated content differs from on-disk files.")
+    args = parser.parse_args()
+
+    skills = _collect_skills()
+    rules = _collect_rules()
+    commands = _collect_commands()
+    guidelines = _collect_guidelines()
+
+    index_text = _render_index(skills, rules, commands, guidelines)
+    catalog_text = _render_catalog(skills, rules, commands, guidelines)
+
+    if args.check:
+        drift = []
+        if not INDEX_PATH.exists() or INDEX_PATH.read_text(encoding="utf-8") != index_text:
+            drift.append(str(INDEX_PATH.relative_to(ROOT)))
+        if not CATALOG_PATH.exists() or CATALOG_PATH.read_text(encoding="utf-8") != catalog_text:
+            drift.append(str(CATALOG_PATH.relative_to(ROOT)))
+        if drift:
+            print("❌  Index drift detected — regenerate with:")
+            print("    python3 scripts/generate_index.py")
+            for d in drift:
+                print(f"    - {d}")
+            return 1
+        print("✅  Index files in sync.")
+        return 0
+
+    INDEX_PATH.parent.mkdir(parents=True, exist_ok=True)
+    CATALOG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    INDEX_PATH.write_text(index_text, encoding="utf-8")
+    CATALOG_PATH.write_text(catalog_text, encoding="utf-8")
+    print(f"✅  Wrote {INDEX_PATH.relative_to(ROOT)} ({len(skills)} skills, "
+          f"{len(rules)} rules, {len(commands)} commands, {len(guidelines)} guidelines)")
+    print(f"✅  Wrote {CATALOG_PATH.relative_to(ROOT)} (public subset)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/install_anthropic_key.sh

@@ -99,3 +99,8 @@ echo "✅  Key installed: ${TARGET_FILE} (mode 0600)."
 echo "    Verify:  ls -la ${TARGET_FILE}"
 echo "    Rotate:  rerun this script (you'll be prompted to overwrite)."
 echo "    Remove:  rm ${TARGET_FILE}"
+echo
+echo "ℹ️   Key install ≠ enable. To use this provider in /council:"
+echo "    set ai_council.enabled: true and ai_council.members.anthropic.enabled: true"
+echo "    in .agent-settings.yml. Council is a 'full' cost_profile feature; under"
+echo "    'minimal' / 'balanced' the runtime hooks stay inactive."

package/scripts/install_openai_key.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# Interactive OpenAI-API-key installer for scripts/ai_council/clients.py.
+#
+# Reads the key with `read -s` so it never echoes to the terminal and
+# never lands in shell history or scrollback. Writes atomically to
+# ~/.config/agent-config/openai.key with mode 0600.
+#
+# Contract — companion to scripts/ai_council/clients.py:
+#   - File path:  $HOME/.config/agent-config/openai.key
+#   - File mode:  0600 (owner read/write only)
+#   - Key format: must start with `sk-`
+#   - No --force, no --yes, no env-var bypass. Piped stdin is rejected.
+#
+# The runner re-checks all of the above at every live invocation and
+# refuses to run if the file drifts from this contract.
+
+set -euo pipefail
+
+TARGET_DIR="${HOME}/.config/agent-config"
+TARGET_FILE="${TARGET_DIR}/openai.key"
+
+# ── controlling-terminal requirement ─────────────────────────────────────
+# We read from /dev/tty directly (fd 3), not from stdin. This is the
+# stricter and more portable contract:
+#   - works under `task`, `script`, `sudo`, anything that reattaches stdin
+#   - forces every character to come from the user's real keyboard, so a
+#     pipe or redirected file cannot smuggle the key into the process
+#   - exits cleanly if there is no controlling terminal at all (e.g. CI,
+#     cron, agent automation)
+if ! exec 3</dev/tty 2>/dev/null; then
+    echo "❌  install_openai_key.sh requires a controlling terminal." >&2
+    echo "    /dev/tty not available — refusing to run under automation." >&2
+    exit 2
+fi
+
+# ── overwrite confirmation ───────────────────────────────────────────────
+if [[ -e "${TARGET_FILE}" ]]; then
+    echo "⚠️   ${TARGET_FILE} already exists."
+    printf "Overwrite? [type 'yes' to replace, anything else aborts]: "
+    read -r -u 3 answer
+    if [[ "${answer}" != "yes" ]]; then
+        echo "Aborted. Existing key untouched."
+        exit 0
+    fi
+fi
+
+# ── read key (no echo, no history) ───────────────────────────────────────
+echo "Paste your OpenAI API key (input is hidden, no echo)."
+echo "The key should start with 'sk-'."
+printf "Key: "
+# -s = silent (no echo), read from fd 3 = /dev/tty, not stdin.
+read -r -s -u 3 API_KEY
+echo
+
+if [[ -z "${API_KEY}" ]]; then
+    echo "❌  Empty input — no file written." >&2
+    exit 2
+fi
+
+if [[ "${API_KEY}" != sk-* ]]; then
+    echo "❌  Input does not look like an OpenAI key (missing 'sk-' prefix)." >&2
+    echo "    No file written." >&2
+    exit 2
+fi
+
+# ── create config dir with 0700, atomic write with 0600 ──────────────────
+mkdir -p "${TARGET_DIR}"
+chmod 0700 "${TARGET_DIR}"
+
+TMP_FILE="$(mktemp "${TARGET_DIR}/.openai.key.XXXXXX")"
+cleanup() { rm -f "${TMP_FILE}"; }
+trap cleanup EXIT
+
+# chmod the tmpfile BEFORE writing the key, so there is no window where
+# the key sits on disk with group/other-readable permissions.
+chmod 0600 "${TMP_FILE}"
+printf '%s\n' "${API_KEY}" > "${TMP_FILE}"
+mv "${TMP_FILE}" "${TARGET_FILE}"
+trap - EXIT
+
+# Clear the variable and the `mv` positional argument — defence in depth
+# against a crash handler that dumps the process environment.
+API_KEY=""
+
+# ── verify mode post-write (portable stat: BSD on macOS, GNU on Linux) ───
+if ACTUAL_MODE=$(stat -f '%Lp' "${TARGET_FILE}" 2>/dev/null); then
+    :  # macOS / BSD
+else
+    ACTUAL_MODE=$(stat -c '%a' "${TARGET_FILE}")
+fi
+
+if [[ "${ACTUAL_MODE}" != "600" ]]; then
+    echo "❌  Permissions verification failed: ${TARGET_FILE} has mode ${ACTUAL_MODE}, expected 600." >&2
+    echo "    Delete and reinstall:  rm ${TARGET_FILE} && $0" >&2
+    exit 3
+fi
+
+echo "✅  Key installed: ${TARGET_FILE} (mode 0600)."
+echo "    Verify:  ls -la ${TARGET_FILE}"
+echo "    Rotate:  rerun this script (you'll be prompted to overwrite)."
+echo "    Remove:  rm ${TARGET_FILE}"
+echo
+echo "ℹ️   Key install ≠ enable. To use this provider in /council:"
+echo "    set ai_council.enabled: true and ai_council.members.openai.enabled: true"
+echo "    in .agent-settings.yml. Council is a 'full' cost_profile feature; under"
+echo "    'minimal' / 'balanced' the runtime hooks stay inactive."

package/scripts/lint_load_context.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""Lint the `load_context:` / `load_context_eager:` frontmatter schema.
+
+Validates per docs/contracts/load-context-schema.md:
+  - Paths exist and are .md
+  - Allowed roots only (.agent-src*/contexts/, agents/contexts/)
+  - No public→project-local leak (warn)
+  - No circular refs across lazy + eager edges
+  - Combined char-budget for eager edges (rule + eager targets ≤ cap)
+
+Exits non-zero on error; warnings are reported but do not fail.
+Used in CI via `task lint-load-context`.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Iterable
+
+import yaml
+
+ROOT = Path(__file__).resolve().parent.parent
+
+SCAN_DIRS = [
+    ROOT / ".agent-src.uncompressed" / "rules",
+    ROOT / ".agent-src.uncompressed" / "contexts",
+    ROOT / "agents" / "contexts",
+]
+
+ALLOWED_PREFIXES = (
+    ".agent-src.uncompressed/contexts/",
+    ".agent-src/contexts/",
+    "agents/contexts/",
+)
+
+PUBLIC_RULE_PREFIX = ".agent-src.uncompressed/rules/"
+PROJECT_LOCAL_PREFIX = "agents/contexts/"
+
+HARD_FLOOR_RULES = {"non-destructive-by-default", "security-sensitive-stop"}
+
+CAP_ALWAYS = 2_500
+CAP_AUTO = 4_000
+CAP_SAFETY = 5_000
+
+
+def parse_frontmatter(path: Path) -> dict:
+    text = path.read_text(encoding="utf-8")
+    if not text.startswith("---\n"):
+        return {}
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return {}
+    try:
+        data = yaml.safe_load(text[4:end])
+    except yaml.YAMLError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def collect_files() -> Iterable[Path]:
+    for d in SCAN_DIRS:
+        if d.exists():
+            yield from d.rglob("*.md")
+
+
+def rel(p: Path) -> str:
+    return p.relative_to(ROOT).as_posix()
+
+
+def cap_for(rule_path: Path, fm: dict) -> int:
+    if rule_path.stem in HARD_FLOOR_RULES:
+        return CAP_SAFETY
+    rtype = (fm.get("type") or "").strip('"').strip("'")
+    if rtype == "always":
+        return CAP_ALWAYS
+    if rtype == "auto":
+        return CAP_AUTO
+    return CAP_AUTO  # default for non-rule contexts cited in eager (won't trigger)
+
+
+def find_cycles(graph: dict[str, list[str]]) -> list[list[str]]:
+    cycles: list[list[str]] = []
+    visiting: set[str] = set()
+    visited: set[str] = set()
+    stack: list[str] = []
+
+    def dfs(node: str) -> None:
+        if node in visiting:
+            i = stack.index(node)
+            cycles.append(stack[i:] + [node])
+            return
+        if node in visited:
+            return
+        visiting.add(node)
+        stack.append(node)
+        for nxt in graph.get(node, []):
+            dfs(nxt)
+        stack.pop()
+        visiting.discard(node)
+        visited.add(node)
+
+    for n in graph:
+        dfs(n)
+    return cycles
+
+
+def main() -> int:
+    errors: list[str] = []
+    warnings: list[str] = []
+    graph: dict[str, list[str]] = {}
+
+    for f in collect_files():
+        fm = parse_frontmatter(f)
+        lazy = fm.get("load_context") or []
+        eager = fm.get("load_context_eager") or []
+        if not (lazy or eager):
+            continue
+        if not isinstance(lazy, list) or not isinstance(eager, list):
+            errors.append(f"{rel(f)}: load_context* must be a list")
+            continue
+
+        edges = list(lazy) + list(eager)
+        graph[rel(f)] = edges
+
+        for entry in edges:
+            if not isinstance(entry, str) or not entry.endswith(".md"):
+                errors.append(f"{rel(f)}: entry not str ending in .md → {entry!r}")
+                continue
+            if not entry.startswith(ALLOWED_PREFIXES):
+                errors.append(f"{rel(f)}: disallowed root → {entry}")
+                continue
+            target = ROOT / entry
+            if not target.exists():
+                errors.append(f"{rel(f)}: target missing → {entry}")
+                continue
+            if rel(f).startswith(PUBLIC_RULE_PREFIX) and entry.startswith(PROJECT_LOCAL_PREFIX):
+                warnings.append(f"{rel(f)}: public rule references project-local context → {entry}")
+
+        if eager:
+            cap = cap_for(f, fm)
+            total = len(f.read_text(encoding="utf-8"))
+            for entry in eager:
+                tgt = ROOT / entry
+                if tgt.exists():
+                    total += len(tgt.read_text(encoding="utf-8"))
+            if total > cap:
+                errors.append(f"{rel(f)}: eager-load combined chars {total} > cap {cap}")
+
+    for cycle in find_cycles(graph):
+        errors.append("circular load_context: " + " → ".join(cycle))
+
+    for w in warnings:
+        print(f"⚠️  {w}")
+    for e in errors:
+        print(f"❌  {e}")
+    if errors:
+        return 1
+    print(f"✅  load_context schema clean ({len(graph)} declarer(s))")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())