@event4u/agent-config 1.14.0 → 1.16.0

package/scripts/ai_council/project_context.py

@@ -0,0 +1,159 @@
+"""Lightweight project-context detector for the council handoff preamble.
+
+Council members do better critique when they know what the project IS,
+not just what the artefact looks like. This module reads the bare
+minimum from the repo root — `composer.json`, `package.json`, root
+`README.md` — and returns a neutral `ProjectContext`. All fields are
+optional; missing data is `None` and the preamble silently omits the
+line.
+
+Iron law of neutrality (`ai-council` skill): nothing here may carry
+host-agent identity, prior reasoning, or framing. Manifest fields and
+README prose only.
+
+Truncation strategy (locked by council review, 2026-05-02): the
+``repo_purpose`` field is capped at ``REPO_PURPOSE_MAX_CHARS`` by
+stopping at the **last full sentence ≤ 400 chars**, with an ellipsis
+when truncation occurred. We never cut mid-sentence — a half-sentence
+reads as broken and adds noise to the council preamble.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+REPO_PURPOSE_MAX_CHARS = 400
+_HEADING_RE = re.compile(r"^\s*#")
+_BADGE_RE = re.compile(r"^\s*(\[!\[|!\[|<).*")
+_HTML_RE = re.compile(r"<[^>]+>")
+
+
+@dataclass
+class ProjectContext:
+    """Neutral project description for the council handoff preamble."""
+
+    name: str | None = None
+    stack: str | None = None
+    repo_purpose: str | None = None
+
+    def is_empty(self) -> bool:
+        return self.name is None and self.stack is None and self.repo_purpose is None
+
+
+def _read_json(path: Path) -> dict | None:
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _name_from(composer: dict | None, package: dict | None, root: Path) -> str | None:
+    for src in (composer, package):
+        if src and isinstance(src.get("name"), str) and src["name"].strip():
+            return src["name"].strip()
+    # Fall back to the directory name; useful for repos without manifests.
+    try:
+        return root.resolve().name or None
+    except OSError:
+        return None
+
+
+def _stack_from(composer: dict | None, package: dict | None) -> str | None:
+    parts: list[str] = []
+    if composer:
+        php_v = (composer.get("require") or {}).get("php")
+        if isinstance(php_v, str):
+            parts.append(f"PHP {php_v}")
+        # Detect well-known frameworks without claiming the project IS one.
+        require = {**(composer.get("require") or {}), **(composer.get("require-dev") or {})}
+        for needle, label in (
+            ("laravel/framework", "Laravel"),
+            ("symfony/framework-bundle", "Symfony"),
+            ("laminas/laminas-mvc", "Laminas"),
+        ):
+            if needle in require:
+                parts.append(label)
+                break
+    if package:
+        engines = package.get("engines") or {}
+        if isinstance(engines, dict) and isinstance(engines.get("node"), str):
+            parts.append(f"Node {engines['node']}")
+        deps = {**(package.get("dependencies") or {}), **(package.get("devDependencies") or {})}
+        for needle, label in (
+            ("next", "Next.js"),
+            ("react", "React"),
+            ("vue", "Vue"),
+            ("@angular/core", "Angular"),
+        ):
+            if needle in deps:
+                parts.append(label)
+                break
+    if not parts:
+        return None
+    return " · ".join(parts)
+
+
+def _purpose_from_readme(path: Path) -> str | None:
+    if not path.exists():
+        return None
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    paragraph: list[str] = []
+    for raw in text.splitlines():
+        line = raw.rstrip()
+        stripped = line.strip()
+        if not stripped:
+            if paragraph:
+                break
+            continue
+        if _HEADING_RE.match(stripped) or _BADGE_RE.match(stripped):
+            if paragraph:
+                break
+            continue
+        paragraph.append(stripped)
+    if not paragraph:
+        return None
+    joined = " ".join(paragraph)
+    joined = _HTML_RE.sub("", joined).strip()
+    if not joined:
+        return None
+    if len(joined) > REPO_PURPOSE_MAX_CHARS:
+        joined = _truncate_at_sentence(joined, REPO_PURPOSE_MAX_CHARS)
+    return joined
+
+
+def _truncate_at_sentence(text: str, limit: int) -> str:
+    """Truncate at the last full sentence ≤ limit chars; append an ellipsis.
+
+    Total return length is always ≤ ``limit`` (ellipsis included).
+    """
+    budget = max(1, limit - 2)
+    head = text[:budget]
+    cut = max(head.rfind(". "), head.rfind("! "), head.rfind("? "))
+    if cut >= 0:
+        return head[: cut + 1].rstrip() + " …"
+    return head.rstrip() + " …"
+
+
+def detect_project_context(root: Path | None = None) -> ProjectContext:
+    """Return a `ProjectContext` for `root` (default: cwd).
+
+    Always returns — never raises. Missing manifest files / README → the
+    matching field is `None`, and `handoff_preamble()` will omit the line.
+    """
+    root = (root or Path.cwd()).resolve()
+    composer = _read_json(root / "composer.json")
+    package = _read_json(root / "package.json")
+    return ProjectContext(
+        name=_name_from(composer, package, root),
+        stack=_stack_from(composer, package),
+        repo_purpose=_purpose_from_readme(root / "README.md"),
+    )

package/scripts/ai_council/prompts.py

@@ -0,0 +1,232 @@
+"""Neutrality system prompts for the council.
+
+Council members must NOT see the host agent's reasoning, internal
+state, or framing language. Each prompt asks for an independent
+critique on the artefact's own merits.
+
+Anti-patterns guarded against in tests (test_prompts.py):
+- No leak of host-agent identity ("Augment", "Claude Code", etc.).
+- No "the agent thinks X" framing.
+- No instructions that bias toward agreement.
+"""
+
+from __future__ import annotations
+
+from scripts.ai_council.project_context import ProjectContext
+
+NEUTRALITY_PREAMBLE = """\
+You are an independent reviewer. You have NOT seen any prior reasoning,
+agent output, or commentary on the artefact below. Critique it on its
+own merits. Disagree if warranted. Cite specific lines or sections.
+Do not assume the artefact is correct just because it was sent to you.
+""".strip()
+
+# Host-agent identity strings that must never leak into a council member's
+# view. Lines containing any of these (case-insensitive substring) are
+# dropped before assembly. See `ai-council` skill § Neutrality.
+HOST_AGENT_IDENTITY_PATTERNS = (
+    "augment",
+    "claude code",
+    "cursor agent",
+    "cursor ide",
+    "cline",
+    "windsurf",
+    "copilot agent",
+)
+
+# Per-mode addenda — appended after the preamble.
+
+PROMPT_MODE = """\
+The artefact is a free-form question or proposal from a developer.
+Respond with:
+1. Your honest assessment (agree / disagree / mixed).
+2. The single strongest argument for your position.
+3. The single strongest counter-argument the developer should consider.
+4. Concrete next steps if you agree, or concrete alternatives if you disagree.
+""".strip()
+
+ROADMAP_MODE = """\
+The artefact is a proposed implementation roadmap. Critique it as if
+you were a senior engineer asked to greenlight it. Focus on:
+1. Hidden coupling between phases that the roadmap glosses over.
+2. Steps that are too coarse to verify ("implement X" vs "X with Y test").
+3. Missing rollback or kill-switch criteria.
+4. Sequencing risks — does step N really not block step N+1?
+5. Open questions disguised as decisions, or vice versa.
+""".strip()
+
+DIFF_MODE = """\
+The artefact is a code diff. Review it for:
+1. Correctness — bugs, off-by-one, null-safety, type drift.
+2. Security — injection, secrets, unsafe deserialization, authZ gaps.
+3. Test coverage — uncovered branches, missing regression tests.
+4. Maintainability — surprise dependencies, naming drift, dead code.
+End with: APPROVE / REQUEST_CHANGES / REJECT and one sentence why.
+""".strip()
+
+FILES_MODE = """\
+The artefact is a set of source files for an architectural review.
+Map out:
+1. The boundaries you see (modules, layers, trust zones).
+2. The strongest design decision present.
+3. The weakest design decision present.
+4. The single change that would most reduce future maintenance cost.
+""".strip()
+
+# Specialised modes — used by /council-pr, /council-design,
+# /council-optimize. Selected via `mode_override=` in `/council` so the
+# base modes (`prompt`, `roadmap`, `diff`, `files`) keep their v2 byte
+# shape for back-compat with existing callers.
+
+PR_MODE = """\
+The artefact is a code diff from a pull request. Review with both a
+correctness lens AND a shipping-risk lens:
+1. Correctness — bugs, off-by-one, null-safety, type drift.
+2. Security — injection, secrets, unsafe deserialization, authZ gaps.
+3. Test coverage — uncovered branches, missing regression tests.
+4. Shipping risk — does this PR mix concerns that should be split?
+   Is the blast radius bigger than the title implies?
+5. Reviewer fatigue — is anything in the diff that a tired reviewer
+   would rubber-stamp but should not?
+End with: APPROVE / REQUEST_CHANGES / REJECT, one sentence why, and
+the single highest-leverage change the PR author should make before
+merge.
+""".strip()
+
+DESIGN_MODE = """\
+The artefact is a design document, ADR, or architecture proposal.
+Critique it as if you were greenlighting it as a senior engineer.
+Focus on:
+1. Trust boundaries and module coupling the design glosses over.
+2. Rollback / kill-switch criteria the design omits.
+3. Sequencing risk — does step N really not block step N+1?
+4. Open questions disguised as decisions, or decisions disguised as
+   open questions.
+5. The single architectural call you would push back on the hardest,
+   and what evidence would change your mind.
+""".strip()
+
+OPTIMIZE_MODE = """\
+The artefact is an optimization target — code, a query, a profile,
+or an existing optimization report. Produce ranked, evidence-based
+suggestions for the metric stated in the user's original ask. You
+MUST:
+1. Rank suggestions by expected impact on the stated metric, not by
+   effort or cleverness.
+2. Cite the evidence (line, query plan, profile entry) for every
+   suggestion. No hand-wave "this is probably slow".
+3. State at least one suggestion you explicitly REJECT as
+   low-leverage, so the user does not over-engineer.
+4. Mark at least one suggestion as hypothesis (requires measurement
+   before committing) versus confirmed (already supported by the
+   evidence in the artefact).
+""".strip()
+
+
+_MODE_TABLE = {
+    "prompt": PROMPT_MODE,
+    "roadmap": ROADMAP_MODE,
+    "diff": DIFF_MODE,
+    "files": FILES_MODE,
+    "pr": PR_MODE,
+    "design": DESIGN_MODE,
+    "optimize": OPTIMIZE_MODE,
+}
+
+
+def _strip_host_identity(text: str) -> str:
+    """Drop any *whole line* containing a host-agent identity substring.
+
+    Strategy (locked by council review, 2026-05-02): a line is dropped
+    in full as soon as any host-identity needle (Augment / Claude Code
+    / Cursor / Cline / Windsurf, etc.) appears anywhere on it. We err
+    toward false-positive — slightly less context — over false-negative
+    — a neutrality leak. Substring-only stripping was rejected because
+    it can leave dangling clauses that still hint at the host.
+    """
+    if not text:
+        return text
+    kept: list[str] = []
+    for line in text.splitlines():
+        low = line.lower()
+        if any(needle in low for needle in HOST_AGENT_IDENTITY_PATTERNS):
+            continue
+        kept.append(line)
+    return "\n".join(kept)
+
+
+def handoff_preamble(
+    project: ProjectContext | None,
+    original_ask: str,
+) -> str:
+    """Neutral context-handoff for council members.
+
+    Layout (any block omitted when its inputs are empty):
+
+        Project: <name>
+        Stack: <stack>
+        Purpose: <repo_purpose>
+
+        The user originally asked:
+        > <original_ask>
+
+        <NEUTRALITY_PREAMBLE>
+
+    Iron Law of Neutrality (`ai-council` skill): lines containing a
+    host-agent identity string (Augment, Claude Code, Cursor, Cline,
+    Windsurf, Copilot agent) are dropped from `project` fields and
+    `original_ask` BEFORE assembly so they cannot leak.
+
+    `project=None` and/or `original_ask=""` collapses the output to
+    `NEUTRALITY_PREAMBLE` alone (back-compat with v1 callers).
+    """
+    blocks: list[str] = []
+
+    if project is not None and not project.is_empty():
+        ctx_lines: list[str] = []
+        if project.name:
+            ctx_lines.append(f"Project: {project.name}")
+        if project.stack:
+            ctx_lines.append(f"Stack: {project.stack}")
+        if project.repo_purpose:
+            ctx_lines.append(f"Purpose: {project.repo_purpose}")
+        ctx = _strip_host_identity("\n".join(ctx_lines)).strip()
+        if ctx:
+            blocks.append(ctx)
+
+    cleaned_ask = _strip_host_identity(original_ask or "").strip()
+    if cleaned_ask:
+        quoted = "\n".join(f"> {ln}" for ln in cleaned_ask.splitlines())
+        blocks.append(f"The user originally asked:\n{quoted}")
+
+    blocks.append(NEUTRALITY_PREAMBLE)
+    return "\n\n".join(blocks)
+
+
+def system_prompt_for(
+    mode: str,
+    *,
+    project: ProjectContext | None = None,
+    original_ask: str = "",
+) -> str:
+    """Build the full system prompt for one of the four input modes.
+
+    Raises ValueError on an unknown mode — callers must use one of
+    `prompt`, `roadmap`, `diff`, `files`.
+
+    When `project` and `original_ask` are both omitted, the result is
+    `NEUTRALITY_PREAMBLE` + per-mode addendum (v1 shape, byte-identical
+    to pre-2a output). When either is supplied, the neutral handoff
+    preamble replaces the bare `NEUTRALITY_PREAMBLE`.
+    """
+    if mode not in _MODE_TABLE:
+        raise ValueError(
+            f"Unknown council mode {mode!r}. "
+            f"Expected one of: {sorted(_MODE_TABLE)}"
+        )
+    head = handoff_preamble(project, original_ask)
+    return f"{head}\n\n{_MODE_TABLE[mode]}"
+
+
+def all_modes() -> list[str]:
+    return sorted(_MODE_TABLE)

package/scripts/ai_council/session.py

@@ -0,0 +1,144 @@
+"""Session persistence for council consultations (D2).
+
+Every `/council` call that completes (success or partial) writes an
+audit artefact under `agents/council-sessions/<UTC-timestamp>/`:
+
+- `manifest.json` — input mode, members, token + USD totals, original
+  ask, neutrality preamble fingerprint.
+- `response.md`   — `orchestrator.render()` output (per-member
+  sections + Convergence/Divergence slot).
+- `raw-text.md`   — concatenated raw text per member, separated by
+  ASCII rules so a later `grep` is trivial.
+
+Hard rules:
+- Never raises on the project — disk write failures are logged and
+  swallowed; the council is text-only and the report is the contract.
+- Never writes secrets. The bundle has already been redacted by
+  `bundler.py` before the orchestrator receives it.
+- Never writes outside `agents/council-sessions/`. Path traversal in
+  the timestamp is impossible (we generate it from `datetime.utcnow`).
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import json
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable
+
+from scripts.ai_council.clients import CouncilResponse
+from scripts.ai_council.orchestrator import render
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SESSIONS_DIR = REPO_ROOT / "agents" / "council-sessions"
+
+
+@dataclass
+class SessionManifest:
+    """Structured record of a single council call.
+
+    Round 2+ debate calls (D1) pass `rounds > 1`; each round's
+    per-member response is appended in `responses_per_round`.
+    """
+
+    mode: str  # bundle mode: prompt|roadmap|diff|files
+    artefact: str  # human-readable artefact descriptor (path or "<inline>")
+    original_ask: str
+    members: list[str]  # "provider/model" pairs
+    rounds: int = 1
+    cost_usd_estimated: float = 0.0
+    cost_usd_actual: float = 0.0
+    extra: dict[str, object] = field(default_factory=dict)
+
+
+def _utc_timestamp() -> str:
+    """UTC timestamp safe for filesystem use (Z suffix preserved)."""
+    return _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H-%M-%SZ")
+
+
+def _serialise_response(r: CouncilResponse) -> dict[str, object]:
+    return {
+        "provider": r.provider,
+        "model": r.model,
+        "input_tokens": r.input_tokens,
+        "output_tokens": r.output_tokens,
+        "latency_ms": r.latency_ms,
+        "error": r.error,
+    }
+
+
+def save(
+    *,
+    manifest: SessionManifest,
+    responses: list[CouncilResponse] | Iterable[list[CouncilResponse]],
+    sessions_dir: Path | None = None,
+    timestamp: str | None = None,
+) -> Path:
+    """Persist a council call. Returns the session directory.
+
+    `responses` accepts either:
+    - `list[CouncilResponse]` — single round (round 1 only).
+    - `Iterable[list[CouncilResponse]]` — multi-round, one list per
+      round in execution order.
+
+    Disk-write failures are surfaced via a stderr line but do not
+    raise; the caller's text report is the source of truth.
+    """
+    rounds_data: list[list[CouncilResponse]]
+    if responses and isinstance(responses, list) and isinstance(responses[0], CouncilResponse):
+        rounds_data = [responses]  # type: ignore[list-item]
+    else:
+        rounds_data = list(responses)  # type: ignore[arg-type]
+
+    base = sessions_dir or SESSIONS_DIR
+    ts = timestamp or _utc_timestamp()
+    session_dir = base / ts
+
+    try:
+        session_dir.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:  # noqa: BLE001 - never block the report
+        print(f"[council:session] mkdir failed: {exc}", file=sys.stderr)
+        return session_dir
+
+    manifest_payload = {
+        "timestamp_utc": ts,
+        "mode": manifest.mode,
+        "artefact": manifest.artefact,
+        "original_ask": manifest.original_ask,
+        "members": manifest.members,
+        "rounds": manifest.rounds,
+        "cost_usd_estimated": round(manifest.cost_usd_estimated, 6),
+        "cost_usd_actual": round(manifest.cost_usd_actual, 6),
+        "responses_per_round": [
+            [_serialise_response(r) for r in round_responses]
+            for round_responses in rounds_data
+        ],
+        **manifest.extra,
+    }
+
+    try:
+        (session_dir / "manifest.json").write_text(
+            json.dumps(manifest_payload, indent=2) + "\n", encoding="utf-8",
+        )
+        # Render uses the LAST round (the moderator-facing summary).
+        last_round = rounds_data[-1] if rounds_data else []
+        (session_dir / "response.md").write_text(
+            render(last_round) + "\n", encoding="utf-8",
+        )
+        raw_blocks: list[str] = []
+        for round_idx, round_responses in enumerate(rounds_data, start=1):
+            for r in round_responses:
+                raw_blocks.append(
+                    f"=== round {round_idx} · {r.provider}/{r.model} ===\n\n"
+                    f"{r.text}\n",
+                )
+        (session_dir / "raw-text.md").write_text(
+            "\n".join(raw_blocks) + ("\n" if raw_blocks else ""),
+            encoding="utf-8",
+        )
+    except OSError as exc:  # noqa: BLE001 - never block the report
+        print(f"[council:session] write failed: {exc}", file=sys.stderr)
+
+    return session_dir

package/scripts/build_linear_digest.py

@@ -10,7 +10,7 @@ Concatenates a curated set of cloud-safe rules from
   personal.md   — empty stub for individual preferences
 
 Per-rule inclusion + mode is the source of truth in
-`agents/contexts/linear-ai-rules-inclusion.md`. This script encodes the
+`docs/contracts/linear-ai-rules-inclusion.md`. This script encodes the
 same lists so a drift between the two surfaces is caught by the digest
 audit (Phase 3 Step 4) — the markdown doc is the human-readable spec,
 this script is the executable.
@@ -44,7 +44,7 @@ from pathlib import Path
 ROOT = Path(__file__).resolve().parent.parent
 # Compressed source is the shipped form — denser, sharper section
 # structure; better fit for a guidance field than the verbose authoring
-# layer. The inclusion list at agents/contexts/linear-ai-rules-inclusion.md
+# layer. The inclusion list at docs/contracts/linear-ai-rules-inclusion.md
 # remains the human-readable spec.
 SOURCE = ROOT / ".agent-src" / "rules"
 OUT_DIR = ROOT / "dist" / "linear"
@@ -64,7 +64,7 @@ class RuleEntry:
 
 
 # Workspace digest — universal coding posture. Maps 1:1 to the
-# "Workspace digest" table in agents/contexts/linear-ai-rules-inclusion.md.
+# "Workspace digest" table in docs/contracts/linear-ai-rules-inclusion.md.
 WORKSPACE: list[RuleEntry] = [
     RuleEntry("ask-when-uncertain"),
     RuleEntry("commit-conventions"),
@@ -169,7 +169,7 @@ def render_digest(layer: str, entries: list[RuleEntry]) -> tuple[str, dict]:
     parts.append(
         "> Auto-generated by `scripts/build_linear_digest.py` from "
         "`.agent-src/rules/` (compressed source) plus the inclusion list "
-        "at `agents/contexts/linear-ai-rules-inclusion.md`. Do not edit "
+        "at `docs/contracts/linear-ai-rules-inclusion.md`. Do not edit "
         "this file by hand — re-run `task build-linear-digest` to "
         "regenerate.\n"
     )

package/scripts/check_always_budget.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""Always-rule budget gate (Phases 7.1 + 7.4 of road-to-pr-34-followups).
+
+Enforces a stricter budget contract than `tests/test_always_budget.py`:
+the test suite fails only at 100% utilization (49,000 chars). This
+script lives in CI as:
+
+- Warn-at-80% / fail-at-90% global trend gate (Phase 7.1).
+- Per-rule cap (≤ 6,000 chars per always-rule, Phase 7.4).
+- Top-3 cap (top-3 combined ≤ 50% of TOTAL_CAP, Phase 7.4).
+
+The same caps are enforced as hard assertions in
+`tests/test_always_budget.py`; this script duplicates them so a
+contributor sees a single, fast pre-test signal during local edits.
+
+Exit codes: 0 = pass (or warn), 1 = fail (≥ 90% utilization,
+per-rule breach, or top-3 breach), 3 = internal error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+RULES_DIR = REPO_ROOT / ".agent-src" / "rules"
+
+TOTAL_CAP = 49_000
+WARN_THRESHOLD = 0.80   # 80% — emit warning, exit 0
+FAIL_THRESHOLD = 0.90   # 90% — emit error,  exit 1
+PER_RULE_CAP = 6_000    # Phase 7.4 — no single always-rule may exceed this
+TOP3_CAP = TOTAL_CAP // 2  # Phase 7.4 — top-3 combined ≤ 50% of total budget
+
+
+def _always_rules() -> list[Path]:
+    rules: list[Path] = []
+    for path in sorted(RULES_DIR.glob("*.md")):
+        head = path.read_text(encoding="utf-8").splitlines()[1:2]
+        if head == ['type: "always"']:
+            rules.append(path)
+    return rules
+
+
+def _summary(rules: list[Path]) -> tuple[int, list[tuple[str, int]]]:
+    sizes = [(p.name, p.stat().st_size) for p in rules]
+    return sum(s for _, s in sizes), sorted(sizes, key=lambda x: -x[1])
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="suppress the per-rule breakdown unless threshold is crossed",
+    )
+    args = parser.parse_args()
+
+    if not RULES_DIR.is_dir():
+        print(f"❌  rules dir missing: {RULES_DIR}", file=sys.stderr)
+        return 3
+
+    rules = _always_rules()
+    if not rules:
+        print(f"❌  no always-rules found under {RULES_DIR}", file=sys.stderr)
+        return 3
+
+    total, sizes = _summary(rules)
+    pct = total / TOTAL_CAP
+    over_per_rule = [(n, s) for n, s in sizes if s > PER_RULE_CAP]
+    top3 = sum(s for _, s in sizes[:3])
+    top3_breach = top3 > TOP3_CAP
+
+    if pct >= FAIL_THRESHOLD or over_per_rule or top3_breach:
+        status = "❌  FAIL"
+        rc = 1
+    elif pct >= WARN_THRESHOLD:
+        status = "⚠️  WARN"
+        rc = 0
+    else:
+        status = "✅  OK"
+        rc = 0
+
+    print(
+        f"{status}  always-rule budget: {total:,} / {TOTAL_CAP:,} chars "
+        f"({pct * 100:.1f}%) across {len(rules)} rule(s)"
+    )
+    print(
+        f"      thresholds: warn {WARN_THRESHOLD * 100:.0f}% · "
+        f"fail {FAIL_THRESHOLD * 100:.0f}% · "
+        f"per-rule ≤ {PER_RULE_CAP:,} · top-3 ≤ {TOP3_CAP:,}"
+    )
+
+    if rc != 0 or pct >= WARN_THRESHOLD or not args.quiet:
+        print()
+        print(f"      breakdown (largest first; top-3 sum = {top3:,}):")
+        for i, (name, size) in enumerate(sizes):
+            mark = "  ❌" if size > PER_RULE_CAP else ""
+            tag = " (top-3)" if i < 3 else ""
+            print(f"        {size:>5}  {name}{tag}{mark}")
+
+    if over_per_rule:
+        names = ", ".join(f"{n}={s:,}" for n, s in over_per_rule)
+        print(
+            f"\n      Per-rule cap breach (> {PER_RULE_CAP:,} chars): {names}"
+        )
+
+    if top3_breach:
+        print(
+            f"\n      Top-3 cap breach: {top3:,} > {TOP3_CAP:,} chars "
+            f"(top-3 must stay ≤ 50% of {TOTAL_CAP:,} total budget)."
+        )
+
+    if rc == 1:
+        print(
+            f"\n      Action: trim the offending rule(s) via load_context: "
+            f"extraction (see contexts/execution + contexts/authority) "
+            f"until utilization drops below {FAIL_THRESHOLD * 100:.0f}% "
+            f"and all per-rule / top-3 caps hold."
+        )
+
+    return rc
+
+
+if __name__ == "__main__":
+    sys.exit(main())