@event4u/agent-config 1.20.0 → 1.22.0

package/scripts/council_cli.py

@@ -63,6 +63,7 @@ def build_members(
     *,
     invocation_mode: str | None = None,
     model_overrides: dict[str, str] | None = None,
+    siblings_overrides: dict[str, list[str]] | None = None,
 ) -> list[ExternalAIClient]:
     """Construct enabled council members from settings.
 
@@ -73,6 +74,13 @@ def build_members(
     `model_overrides` is a per-invocation `{member_name: model_id}`
     map that wins over the per-member `model` in settings. Members not
     listed fall back to the settings value, then the per-client default.
+
+    `siblings_overrides` is a per-invocation `{member_name: [model, ...]}`
+    map that fans the named provider out to multiple sibling models in
+    one run (e.g. claude-sonnet-4-5 + claude-opus-4-1). Each model
+    becomes its own billable member with independent cost tracking.
+    Mutually exclusive with `model_overrides` for the same provider;
+    requires `mode=api`; provider must be enabled in settings.
     """
     ai = (settings.get("ai_council") or {}) if isinstance(settings, dict) else {}
     if not ai.get("enabled"):
@@ -83,16 +91,34 @@ def build_members(
     members_cfg = ai.get("members") or {}
     global_mode = ai.get("mode")
     overrides = model_overrides or {}
+    siblings = siblings_overrides or {}
     unknown = set(overrides) - set(members_cfg)
     if unknown:
         raise CouncilDisabledError(
             f"--model targets unknown member(s) {sorted(unknown)!r}; "
             f"known members: {sorted(members_cfg)!r}."
         )
+    unknown_sib = set(siblings) - set(members_cfg)
+    if unknown_sib:
+        raise CouncilDisabledError(
+            f"--siblings targets unknown member(s) {sorted(unknown_sib)!r}; "
+            f"known members: {sorted(members_cfg)!r}."
+        )
+    conflict = set(overrides) & set(siblings)
+    if conflict:
+        raise CouncilDisabledError(
+            f"--model and --siblings target the same member(s) {sorted(conflict)!r}; "
+            f"pick one per provider per invocation."
+        )
     members: list[ExternalAIClient] = []
     for name, cfg in members_cfg.items():
         cfg = cfg or {}
         if not cfg.get("enabled"):
+            if name in siblings:
+                raise CouncilDisabledError(
+                    f"--siblings targets member {name!r} but it is not "
+                    f"enabled in .agent-settings.yml (ai_council.members.{name}.enabled)."
+                )
             continue
         mode = resolve_mode(
             name,
@@ -100,13 +126,17 @@ def build_members(
             member_settings=cfg,
             global_mode=global_mode,
         )
+        if name in siblings:
+            if mode != "api":
+                raise CouncilDisabledError(
+                    f"--siblings requires mode=api for member {name!r} (got {mode!r})."
+                )
+            for sib_model in siblings[name]:
+                members.append(_construct_api_member(name, sib_model))
+            continue
         model = overrides.get(name) or cfg.get("model")
-        if mode == "api" and name == "anthropic":
-            members.append(AnthropicClient(model=model or "claude-sonnet-4-5",
-                                           api_key=load_anthropic_key()))
-        elif mode == "api" and name == "openai":
-            members.append(OpenAIClient(model=model or "gpt-4o",
-                                        api_key=load_openai_key()))
+        if mode == "api" and name in {"anthropic", "openai"}:
+            members.append(_construct_api_member(name, model))
         elif mode == "manual":
             members.append(ManualClient(name=name, model=model or "manual"))
         elif mode == "playwright":
@@ -125,6 +155,19 @@ def build_members(
     return members
 
 
+def _construct_api_member(name: str, model: str | None) -> ExternalAIClient:
+    """Build an api-mode client for a known provider name."""
+    if name == "anthropic":
+        return AnthropicClient(model=model or "claude-sonnet-4-5",
+                               api_key=load_anthropic_key())
+    if name == "openai":
+        return OpenAIClient(model=model or "gpt-4o",
+                            api_key=load_openai_key())
+    raise CouncilDisabledError(
+        f"member {name!r} has no api transport (known: anthropic, openai)."
+    )
+
+
 def build_question(
     *,
     input_path: Path,
@@ -164,6 +207,29 @@ def format_estimate_table(
 # ── subcommands ─────────────────────────────────────────────────────
 
 
+def _resolve_rounds(args: argparse.Namespace, ai_cfg: dict[str, Any]) -> int:
+    """Resolve effective debate round count from CLI args + settings.
+
+    Resolution chain (highest priority first):
+      1. ``--rounds N`` — explicit user override, any value.
+      2. ``--depth deep`` — uses ``ai_council.deep_min_rounds``,
+         floored at ``min_rounds`` so the deep tier is monotonic.
+      3. ``ai_council.min_rounds`` — default 2.
+
+    Sub-commands (rule/skill/command) declare ``council_depth: deep``
+    in their frontmatter; the host agent reads that and translates it
+    to ``--depth deep`` on the CLI invocation. The CLI itself stays
+    unaware of frontmatter — the contract is the flag.
+    """
+    if getattr(args, "rounds", None) is not None:
+        return int(args.rounds)
+    min_rounds = int(ai_cfg.get("min_rounds", 2))
+    if getattr(args, "depth", "standard") == "deep":
+        deep = int(ai_cfg.get("deep_min_rounds", min_rounds))
+        return max(deep, min_rounds)
+    return min_rounds
+
+
 def cmd_estimate(
     args: argparse.Namespace,
     *,
@@ -179,6 +245,7 @@ def cmd_estimate(
             settings,
             invocation_mode=args.mode_override,
             model_overrides=_parse_model_overrides(getattr(args, "model", None)),
+            siblings_overrides=_parse_siblings_overrides(getattr(args, "siblings", None)),
         )
     if table is None:
         table = load_prices()
@@ -239,6 +306,7 @@ def cmd_run(
             settings,
             invocation_mode=args.mode_override,
             model_overrides=_parse_model_overrides(getattr(args, "model", None)),
+            siblings_overrides=_parse_siblings_overrides(getattr(args, "siblings", None)),
         )
     if table is None:
         table = load_prices()
@@ -263,17 +331,19 @@ def cmd_run(
         )
         return 0
 
-    cost_cfg = (settings.get("ai_council") or {}).get("cost_budget") or {}
+    ai_cfg = settings.get("ai_council") or {}
+    cost_cfg = ai_cfg.get("cost_budget") or {}
     budget = CostBudget(
         max_input_tokens=int(cost_cfg.get("max_input_tokens", 50_000)),
         max_output_tokens=int(cost_cfg.get("max_output_tokens", 20_000)),
         max_calls=int(cost_cfg.get("max_calls", 10)),
         max_total_usd=float(cost_cfg.get("max_total_usd", 0.0) or 0.0),
     )
+    rounds = _resolve_rounds(args, ai_cfg)
     responses = consult(
         members, question, budget,
         table=table, project=project,
-        original_ask=args.original_ask, rounds=args.rounds,
+        original_ask=args.original_ask, rounds=rounds,
     )
     estimated_total = sum(e.total_usd for e in estimates)
     actual_total = 0.0
@@ -288,7 +358,7 @@ def cmd_run(
         "artefact": artefact,
         "original_ask": args.original_ask,
         "members": [f"{m.name}/{m.model}" for m in members],
-        "rounds": args.rounds,
+        "rounds": rounds,
         "cost_usd_estimated": round(estimated_total, 6),
         "cost_usd_actual": round(actual_total, 6),
         "responses": _serialise_responses(responses),
@@ -337,6 +407,38 @@ def _parse_model_overrides(items: list[str] | None) -> dict[str, str]:
     return out
 
 
+def _parse_siblings_overrides(items: list[str] | None) -> dict[str, list[str]]:
+    """Parse repeated `--siblings name=model1,model2[,...]` flags.
+
+    Requires ≥ 2 distinct, non-empty models per provider — sibling
+    mode without diversity has no purpose. Repeating the same provider
+    flag is rejected as ambiguous.
+    """
+    out: dict[str, list[str]] = {}
+    for raw in items or []:
+        if "=" not in raw:
+            raise argparse.ArgumentTypeError(
+                f"--siblings expects '<member>=<model1>,<model2>[,...]', got {raw!r}."
+            )
+        name, models_csv = raw.split("=", 1)
+        name = name.strip()
+        models = [m.strip() for m in models_csv.split(",") if m.strip()]
+        if not name or not models:
+            raise argparse.ArgumentTypeError(
+                f"--siblings member and model list must both be non-empty: {raw!r}."
+            )
+        if len(set(models)) < 2:
+            raise argparse.ArgumentTypeError(
+                f"--siblings requires ≥ 2 distinct models for {name!r}, got {models!r}."
+            )
+        if name in out:
+            raise argparse.ArgumentTypeError(
+                f"--siblings repeated for member {name!r}; combine into one flag."
+            )
+        out[name] = models
+    return out
+
+
 def _add_common_input_args(p: argparse.ArgumentParser) -> None:
     p.add_argument("question", type=str,
                    help="Path to the question file (text or roadmap).")
@@ -354,6 +456,16 @@ def _add_common_input_args(p: argparse.ArgumentParser) -> None:
                         "Wins over `ai_council.members.<name>.model` in "
                         ".agent-settings.yml; the settings file is not "
                         "modified.")
+    p.add_argument("--siblings", action="append", default=None, dest="siblings",
+                   metavar="MEMBER=MODEL1,MODEL2[,...]",
+                   help="Fan one provider out to ≥ 2 sibling models in a "
+                        "single run, e.g. --siblings anthropic=claude-sonnet-4-5,"
+                        "claude-opus-4-1. Each model becomes its own billable "
+                        "member with independent cost tracking. Mutually "
+                        "exclusive with --model for the same provider; "
+                        "requires the provider to be enabled with mode=api. "
+                        "Single-provider degraded-run strategy per ai-council "
+                        "skill.")
     p.add_argument("--original-ask", default="",
                    help="The user's framing sentence (flows into handoff).")
 
@@ -374,8 +486,17 @@ def build_parser() -> argparse.ArgumentParser:
                        help="Path to write the responses JSON.")
     p_run.add_argument("--confirm", action="store_true",
                        help="Required to actually invoke the council.")
-    p_run.add_argument("--rounds", type=int, default=1,
-                       help="Number of debate rounds (1-3).")
+    p_run.add_argument("--rounds", type=int, default=None,
+                       help="Number of debate rounds (1-3). Explicit override; "
+                            "wins over --depth. Defaults to ai_council.min_rounds "
+                            "in .agent-settings.yml (or 2 if unset).")
+    p_run.add_argument("--depth", choices=["standard", "deep"], default="standard",
+                       help="Reasoning-depth tier. 'deep' floors rounds at "
+                            "ai_council.deep_min_rounds (max'd with min_rounds) "
+                            "for architecture, refactoring, or bug-diagnosis "
+                            "artefacts. Set by the host agent when the consuming "
+                            "rule/skill/command declares council_depth: deep. "
+                            "Overridden by explicit --rounds.")
 
     p_ren = sub.add_parser("render", help="Re-render a saved responses JSON.")
     p_ren.add_argument("responses",

package/scripts/council_prune.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""Manual pruner for council artefacts.
+
+Deletes council files older than `ai_council.session_retention_days`
+(default 7) across all four artefact directories:
+
+  - agents/council-sessions/   (timestamp subdirs + root files)
+  - agents/council-questions/  (mtime-based)
+  - agents/council-responses/  (mtime-based)
+
+Same logic as the auto-prune that runs on every `council save()`,
+exposed as a Task target so the user can sweep on demand.
+
+Invocation (from project root):
+  python3 scripts/council_prune.py [--days N] [--dry-run]
+
+Exit code 0 always — pruning is a hygiene operation, never a build
+gate. Disk failures are logged to stderr by the underlying pruner.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+# Bootstrap import path so `python3 scripts/council_prune.py` works
+# from the project root without an editable install.
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from scripts.ai_council.session import (  # noqa: E402
+    _load_retention_days,
+    prune_all_council_artifacts,
+)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--days",
+        type=int,
+        default=None,
+        help="Override retention_days (default: from .agent-settings.yml)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="List what would be deleted without removing anything.",
+    )
+    args = parser.parse_args()
+
+    days = args.days if args.days is not None else _load_retention_days()
+    if days <= 0:
+        print(f"council-prune: retention_days={days} → pruning disabled.")
+        return 0
+
+    if args.dry_run:
+        # The pruner doesn't have a true dry-run mode; we approximate
+        # by reporting current contents and the cutoff.
+        print(f"council-prune: dry-run, cutoff = retention_days={days}")
+        print("council-prune: actual deletion requires omitting --dry-run")
+        return 0
+
+    print(f"council-prune: retention_days={days}")
+    result = prune_all_council_artifacts(retention_days=days)
+    total = 0
+    for label, removed in result.items():
+        if removed:
+            print(f"  {label}: {len(removed)} pruned")
+            for p in removed:
+                print(f"    - {p}")
+            total += len(removed)
+    if total == 0:
+        print("council-prune: nothing to prune.")
+    else:
+        print(f"council-prune: pruned {total} entries total.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/count_token_optimizer_usage.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Token-Optimizer telemetry counter.
+#
+# Per `road-to-token-optimization.md` P1.4: counts uncommented TELEMETRY
+# lines inside the token-optimizer skill body. Each consult bumps a line.
+# Decision rule: <5 consults / 2 weeks → P3.1 sunset audit fires.
+#
+# Output: 7-day count, 30-day count, total. Stdout only, no side effects.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+SKILL="$REPO_ROOT/.agent-src.uncompressed/skills/token-optimizer/SKILL.md"
+
+if [[ ! -f "$SKILL" ]]; then
+    echo "ERROR: $SKILL not found" >&2
+    exit 1
+fi
+
+# Active TELEMETRY lines = those NOT inside an HTML comment.
+# Pattern: lines that contain "TELEMETRY: consulted=" and start with neither "<!--" nor whitespace.
+total=$(grep -cE '^TELEMETRY: consulted=' "$SKILL" || true)
+
+today_epoch=$(date -u +%s)
+seven_days_ago=$(( today_epoch - 7 * 86400 ))
+thirty_days_ago=$(( today_epoch - 30 * 86400 ))
+
+count_since() {
+    local cutoff="$1"
+    local n=0
+    while IFS= read -r line; do
+        # Extract the ISO timestamp after "consulted="
+        ts=$(echo "$line" | sed -nE 's/^TELEMETRY: consulted=\[?([0-9TZ:+\-]+)\]?.*/\1/p')
+        [[ -z "$ts" ]] && continue
+        # Convert ISO → epoch (BSD `date -j` on macOS, GNU `date -d` on Linux)
+        epoch=$(date -j -u -f "%Y-%m-%dT%H:%M:%SZ" "$ts" +%s 2>/dev/null \
+            || date -u -d "$ts" +%s 2>/dev/null \
+            || echo 0)
+        if [[ "$epoch" -ge "$cutoff" ]]; then
+            n=$(( n + 1 ))
+        fi
+    done < <(grep -E '^TELEMETRY: consulted=' "$SKILL" || true)
+    echo "$n"
+}
+
+count_7d=$(count_since "$seven_days_ago")
+count_30d=$(count_since "$thirty_days_ago")
+
+echo "token-optimizer consults:"
+echo "  last  7 days: $count_7d"
+echo "  last 30 days: $count_30d"
+echo "  total active: $total"
+echo ""
+echo "Decision rule: <5 consults / 2 weeks sustained → P3.1 sunset audit."

package/scripts/install.sh

@@ -2,7 +2,9 @@
 # install.sh — Agent-config payload sync (one of two installer stages).
 #
 # Reads from vendor's .agent-src/ (fallback: .augment/ for pre-2.0 packages) and
-# writes the target project's .augment/ tree: copies rules, symlinks everything else.
+# writes the target project's .augment/ tree: copies rules, symlinks everything
+# else. When augment.rules_use_symlinks: true is set in the target's
+# .agent-settings.yml, rules are symlinked instead of copied.
 # Creates tool-specific directories for Claude Code, Cursor, Cline, Windsurf, Gemini.
 #
 # Does NOT render .agent-settings.yml or bridge JSONs — that is the job of
@@ -35,6 +37,9 @@ DRY_RUN=false
 VERBOSE=false
 QUIET=false
 SKIP_GITIGNORE=false
+# Resolved from <TARGET>/.agent-settings.yml in resolve_settings(); when
+# true, .augment/rules/ files are symlinked instead of copied.
+USE_RULES_SYMLINKS=false
 
 # --- Logging ---
 log_info()    { $QUIET || echo "  ✅  $*"; }
@@ -114,6 +119,30 @@ EOF
 
 # --- Utility functions ---
 
+# Read augment.rules_use_symlinks from <TARGET>/.agent-settings.yml.
+# Sets USE_RULES_SYMLINKS=true|false. Missing file or absent key → false.
+# Minimal scoped parser; avoids a hard yq/python dependency.
+resolve_settings() {
+    USE_RULES_SYMLINKS=false
+    local settings_file="$TARGET_DIR/.agent-settings.yml"
+    [[ -f "$settings_file" ]] || return 0
+    local val
+    val=$(awk '
+        /^[^[:space:]#]/ { in_block = ($0 ~ /^augment:[[:space:]]*$/) }
+        in_block && /^[[:space:]]+rules_use_symlinks[[:space:]]*:/ {
+            line = $0
+            sub(/^[[:space:]]*rules_use_symlinks[[:space:]]*:[[:space:]]*/, "", line)
+            sub(/[[:space:]]*#.*$/, "", line)
+            gsub(/[[:space:]]/, "", line)
+            print tolower(line)
+            exit
+        }
+    ' "$settings_file" 2>/dev/null || true)
+    case "$val" in
+        true|yes|on|1) USE_RULES_SYMLINKS=true ;;
+    esac
+}
+
 # Check if a relative path should be copied (true=copy) or symlinked (false=symlink)
 should_copy() {
     local rel_path="$1"
@@ -127,6 +156,10 @@ should_copy() {
     # Check against COPY_DIRS
     for dir in $COPY_DIRS; do
         if [[ "$first_segment" == "$dir" ]]; then
+            # Honor augment.rules_use_symlinks toggle for the rules dir.
+            if [[ "$dir" == "rules" ]] && $USE_RULES_SYMLINKS; then
+                return 1
+            fi
             return 0
         fi
     done
@@ -669,9 +702,17 @@ main() {
     # 0. Migrate legacy infra files (root → agents/) before any content sync.
     migrate_legacy_root_infra "$TARGET_DIR"
 
+    # 0b. Resolve settings (e.g. augment.rules_use_symlinks). On first
+    #     install the file does not exist yet → defaults preserved.
+    resolve_settings
+
     # 1. Hybrid sync payload → target/.augment/
     sync_hybrid "$SOURCE_PAYLOAD" "$TARGET_DIR/.augment"
-    log_info "Synced .augment/ (rules copied, rest symlinked)"
+    if $USE_RULES_SYMLINKS; then
+        log_info "Synced .augment/ (rules symlinked, rest symlinked)"
+    else
+        log_info "Synced .augment/ (rules copied, rest symlinked)"
+    fi
 
     # 2. Copy standalone files from templates if missing on the target.
     #    We copy from templates/ (generic placeholders), NOT from the package's
@@ -680,6 +721,7 @@ main() {
     #    into consumer projects.
     copy_if_missing "$SOURCE_PAYLOAD/templates/AGENTS.md" "$TARGET_DIR/AGENTS.md"
     copy_if_missing "$SOURCE_PAYLOAD/templates/copilot-instructions.md" "$TARGET_DIR/.github/copilot-instructions.md"
+    copy_if_missing "$SOURCE_PAYLOAD/templates/copilot-review-instructions.md" "$TARGET_DIR/.github/copilot-review-instructions.md"
 
     # 3. Create tool-specific symlinks
     create_tool_symlinks "$TARGET_DIR"

package/scripts/iron_law_sha.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""SHA-256 of every triple-fence block in a rule file (Iron Law preservation).
+
+Usage:
+  python3 scripts/iron_law_sha.py <rule-id> [<rule-id> ...]
+  python3 scripts/iron_law_sha.py --all-kernel
+  python3 scripts/iron_law_sha.py --diff <rule-id> --against <baseline-sha>
+
+The Iron-Law block is delimited by triple-backtick fences. Every line
+inside any fence in the file is concatenated, whitespace-normalised
+(runs of spaces collapsed; leading / trailing whitespace stripped per
+line), case-folded, then SHA-256-hashed. Empty fences hash to
+SHA-256(''), which is `e3b0c442…` (the well-known empty-string hash).
+
+Acceptance per `road-to-kernel-and-router.md` P2.2: re-runnable,
+deterministic, stdlib-only, no network. Compression of a kernel rule
+must preserve this SHA (or surface a deliberate ADR-tracked diff).
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+RULES_DIR = REPO_ROOT / ".agent-src.uncompressed" / "rules"
+
+# Locked kernel set — kept in sync with measure_rule_budget.KERNEL_RULES.
+KERNEL_RULES = (
+    "agent-authority",
+    "ask-when-uncertain",
+    "commit-policy",
+    "direct-answers",
+    "language-and-tone",
+    "no-cheap-questions",
+    "non-destructive-by-default",
+    "scope-control",
+    "verify-before-complete",
+)
+
+_FENCE_RE = re.compile(r"```(?:[^\n]*\n)([\s\S]*?)```")
+_WS_RE = re.compile(r"\s+")
+
+
+def iron_law_sha(text: str) -> str:
+    """SHA-256 of all triple-fence content, whitespace-collapsed, upper-cased.
+
+    Algorithm matches `scripts/_pilot_measure.py` exactly so the SHAs
+    recorded in `docs/contracts/kernel-membership.md` § 2 stay
+    reproducible across pre / post compression.
+    """
+    blocks = _FENCE_RE.findall(text)
+    norm = "".join(_WS_RE.sub(" ", b).strip().upper() for b in blocks)
+    return hashlib.sha256(norm.encode("utf-8")).hexdigest()
+
+
+def rule_sha(rule_id: str) -> str:
+    path = RULES_DIR / f"{rule_id}.md"
+    if not path.exists():
+        raise FileNotFoundError(path)
+    return iron_law_sha(path.read_text(encoding="utf-8"))
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("rules", nargs="*", help="rule ids (omit if --all-kernel)")
+    parser.add_argument("--all-kernel", action="store_true", help="hash all 9 kernel rules")
+    parser.add_argument(
+        "--diff", metavar="RULE", help="hash one rule and compare to --against"
+    )
+    parser.add_argument("--against", metavar="SHA", help="expected SHA (for --diff)")
+    args = parser.parse_args(argv)
+
+    if args.diff:
+        if not args.against:
+            parser.error("--diff requires --against")
+        actual = rule_sha(args.diff)
+        match = actual == args.against
+        symbol = "✅" if match else "❌"
+        print(f"{symbol}  {args.diff}: {actual}  (expected {args.against})")
+        return 0 if match else 1
+
+    targets = list(KERNEL_RULES) if args.all_kernel else args.rules
+    if not targets:
+        parser.error("provide rule ids, or use --all-kernel")
+
+    width = max(len(t) for t in targets)
+    for rid in targets:
+        sha = rule_sha(rid)
+        print(f"{rid:<{width}}  {sha}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_load_context.py

@@ -28,14 +28,37 @@ SCAN_DIRS = [
 ]
 
 ALLOWED_PREFIXES = (
-    ".agent-src.uncompressed/contexts/",
-    ".agent-src/contexts/",
-    "agents/contexts/",
+    "contexts/",                               # logical name (canonical — P1.1 / P5.3)
+    ".agent-src/contexts/",                    # projected (defensive — only seen in compressed inputs)
+    "agents/contexts/",                        # project-local
 )
 
+# `.agent-src.uncompressed/contexts/` was the legacy fully-qualified form
+# (pre road-to-path-fixes.md P5.3). It is now a hard error: P2.1 migrated
+# all in-tree rules to logical names, the rewriter resolves them at
+# compress time, and the schema regex in `scripts/schemas/rule.schema.json`
+# rejects the prefix at validate-schema time. Keeping a separate runtime
+# diagnostic so the failure points authors at the canonical
+# `contexts/<area>/<file>.md` form rather than a generic schema mismatch.
+LEGACY_PREFIX = ".agent-src.uncompressed/contexts/"
+
+# Logical names resolve against the source root.
+SOURCE_ROOT = ROOT / ".agent-src.uncompressed"
+
 PUBLIC_RULE_PREFIX = ".agent-src.uncompressed/rules/"
 PROJECT_LOCAL_PREFIX = "agents/contexts/"
 
+
+def resolve_entry(entry: str) -> Path:
+    """Resolve a `load_context:` entry to an absolute path on disk.
+
+    Logical names (`contexts/...`) live under `.agent-src.uncompressed/`;
+    fully-qualified entries are repo-root-relative.
+    """
+    if entry.startswith("contexts/"):
+        return SOURCE_ROOT / entry
+    return ROOT / entry
+
 HARD_FLOOR_RULES = {"non-destructive-by-default", "security-sensitive-stop"}
 
 CAP_ALWAYS = 2_500
@@ -126,10 +149,17 @@ def main() -> int:
             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 entry.startswith(LEGACY_PREFIX):
+                logical = entry[len(".agent-src.uncompressed/"):]
+                errors.append(
+                    f"{rel(f)}: legacy `.agent-src.uncompressed/` prefix in load_context → {entry} "
+                    f"— use logical name `{logical}` instead (road-to-path-fixes.md P5.3)"
+                )
+                continue
             if not entry.startswith(ALLOWED_PREFIXES):
                 errors.append(f"{rel(f)}: disallowed root → {entry}")
                 continue
-            target = ROOT / entry
+            target = resolve_entry(entry)
             if not target.exists():
                 errors.append(f"{rel(f)}: target missing → {entry}")
                 continue
@@ -140,7 +170,7 @@ def main() -> int:
             cap = cap_for(f, fm)
             total = len(f.read_text(encoding="utf-8"))
             for entry in eager:
-                tgt = ROOT / entry
+                tgt = resolve_entry(entry)
                 if tgt.exists():
                     total += len(tgt.read_text(encoding="utf-8"))
             if total > cap: