@event4u/agent-config 1.20.0 → 1.22.0

package/scripts/measure_rule_budget.py

@@ -0,0 +1,314 @@
+#!/usr/bin/env python3
+"""Measure rule-bucket char counts (kernel + auto) for the rule-kernel roadmap.
+
+Source of truth: `.agent-src.uncompressed/rules/*.md`. Frontmatter (YAML
+between two `---` lines at file start) is stripped before counting; only
+the rule body counts toward the bucket.
+
+Buckets follow the existing frontmatter `type:` field:
+- `always` rules → always-bucket (today's kernel proxy).
+- `auto` rules → auto-bucket.
+
+Output:
+- Default: stdout table (per-rule rows, top-5 oversize, totals).
+- `--json`: deterministic JSON (sorted keys, sorted lists).
+
+Acceptance per `road-to-kernel-and-router.md` P1.1: re-runnable,
+deterministic, stdlib-only, no network.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import json
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+RULES_DIR = REPO_ROOT / ".agent-src.uncompressed" / "rules"
+OVERRIDES_FILE = REPO_ROOT / "docs" / "contracts" / "iron-law-overrides.txt"
+TREND_FILE = REPO_ROOT / "agents" / ".rule-budget-history.jsonl"
+
+# Council R2 amendments (2026-05-06) — see docs/contracts/kernel-membership.md § 5.1.
+# Per-rule cap raised 1.5k → 2.5k; warning band raised 1.2k → 2.0k.
+# ADR-002 (2026-05-06) — KERNEL_HARD raised 25k → 26k after empirical r_actual=0.795
+# vs r_projected=0.712; see docs/decisions/ADR-002-kernel-bucket-overrides.md.
+KERNEL_HARD = 26_000
+KERNEL_TARGET = 20_000
+PER_RULE_HARD = 2_500
+PER_RULE_TARGET = 2_000
+PER_RULE_OVERRIDE_CEILING = 4_000  # Iron-Law-override ADR ceiling.
+
+# Locked kernel set — docs/contracts/kernel-membership.md § 4.
+# This is the *kernel* (P1.3 lock), not "every always-rule". After P4 the
+# `type:` frontmatter no longer maps 1:1 to kernel; the kernel is this set.
+KERNEL_RULES: frozenset[str] = frozenset(
+    {
+        "agent-authority",
+        "ask-when-uncertain",
+        "commit-policy",
+        "direct-answers",
+        "language-and-tone",
+        "no-cheap-questions",
+        "non-destructive-by-default",
+        "scope-control",
+        "verify-before-complete",
+    }
+)
+
+
+def strip_frontmatter(text: str) -> tuple[str, dict[str, str]]:
+    """Strip leading YAML frontmatter and return (body, fields).
+
+    Minimal parser — handles `key: "value"` / `key: value` only. No nested
+    structures, no lists. Sufficient for the rule frontmatter contract.
+    """
+    if not text.startswith("---\n"):
+        return text, {}
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return text, {}
+    raw = text[4:end]
+    body = text[end + 5 :]
+    fields: dict[str, str] = {}
+    for line in raw.splitlines():
+        if ":" not in line or line.startswith("#"):
+            continue
+        key, _, val = line.partition(":")
+        fields[key.strip()] = val.strip().strip('"').strip("'")
+    return body, fields
+
+
+def measure_rule(path: Path) -> dict[str, object]:
+    text = path.read_text(encoding="utf-8")
+    body, fields = strip_frontmatter(text)
+    return {
+        "id": path.stem,
+        "type": fields.get("type", "auto"),
+        "tier": fields.get("tier", ""),
+        "chars": len(body),
+        "lines": body.count("\n"),
+    }
+
+
+def collect() -> list[dict[str, object]]:
+    rules = [measure_rule(p) for p in sorted(RULES_DIR.glob("*.md"))]
+    return rules
+
+
+def load_overrides() -> set[str]:
+    """Read iron-law-override allowlist (one rule-id per line, '#' comments)."""
+    if not OVERRIDES_FILE.exists():
+        return set()
+    out: set[str] = set()
+    for line in OVERRIDES_FILE.read_text(encoding="utf-8").splitlines():
+        s = line.split("#", 1)[0].strip()
+        if s:
+            out.add(s)
+    return out
+
+
+def aggregate(rules: list[dict[str, object]]) -> dict[str, object]:
+    always = [r for r in rules if r["type"] == "always"]
+    auto = [r for r in rules if r["type"] == "auto"]
+    kernel = [r for r in rules if r["id"] in KERNEL_RULES]
+    total_chars = sum(int(r["chars"]) for r in rules)
+    return {
+        "always_count": len(always),
+        "auto_count": len(auto),
+        "kernel_count": len(kernel),
+        "rule_count": len(rules),
+        "always_chars": sum(int(r["chars"]) for r in always),
+        "auto_chars": sum(int(r["chars"]) for r in auto),
+        "kernel_chars": sum(int(r["chars"]) for r in kernel),
+        "total_chars": total_chars,
+        "kernel_hard": KERNEL_HARD,
+        "kernel_target": KERNEL_TARGET,
+        "per_rule_hard": PER_RULE_HARD,
+        "per_rule_target": PER_RULE_TARGET,
+        "per_rule_override_ceiling": PER_RULE_OVERRIDE_CEILING,
+        "oversize_rules": sorted(
+            (r for r in rules if int(r["chars"]) > PER_RULE_HARD),
+            key=lambda r: (-int(r["chars"]), r["id"]),
+        ),
+        "top5_largest": sorted(rules, key=lambda r: (-int(r["chars"]), r["id"]))[:5],
+    }
+
+
+def render_table(rules: list[dict[str, object]], agg: dict[str, object]) -> str:
+    lines: list[str] = []
+    lines.append("Rule budget — source: .agent-src.uncompressed/rules/")
+    lines.append("")
+    lines.append(f"{'id':<40} {'type':<7} {'tier':<5} {'chars':>7}")
+    lines.append("-" * 62)
+    for r in sorted(rules, key=lambda r: r["id"]):
+        flag = "!" if int(r["chars"]) > PER_RULE_HARD else (
+            "~" if int(r["chars"]) > PER_RULE_TARGET else " "
+        )
+        lines.append(
+            f"{r['id']:<40} {r['type']:<7} {str(r['tier']):<5} {r['chars']:>6}{flag}"
+        )
+    lines.append("")
+    lines.append(
+        f"kernel-bucket: {agg['kernel_chars']:>6} chars across {agg['kernel_count']} rules "
+        f"(target ≤ {KERNEL_TARGET}, hard ≤ {KERNEL_HARD})"
+    )
+    lines.append(
+        f"always-bucket: {agg['always_chars']:>6} chars across {agg['always_count']} rules "
+        f"(legacy frontmatter `type: always`)"
+    )
+    lines.append(
+        f"  auto-bucket: {agg['auto_chars']:>6} chars across {agg['auto_count']} rules"
+    )
+    lines.append(f"        total: {agg['total_chars']:>6} chars across {agg['rule_count']} rules")
+    lines.append("")
+    lines.append(f"top-5 largest:")
+    for r in agg["top5_largest"]:  # type: ignore[index]
+        lines.append(f"  {r['chars']:>5}  {r['id']}  ({r['type']})")
+    over = agg["oversize_rules"]  # type: ignore[index]
+    if over:
+        lines.append("")
+        lines.append(f"OVER per-rule hard cap ({PER_RULE_HARD} chars): {len(over)} rule(s)")
+    return "\n".join(lines)
+
+
+def kernel_budget_check(
+    rules: list[dict[str, object]], agg: dict[str, object], overrides: set[str]
+) -> tuple[int, list[str]]:
+    """Enforce kernel budget per Council R2 amendments.
+
+    Returns (exit_code, report_lines). Exit 0 = pass, 1 = breach.
+
+    Checks:
+    - Kernel-bucket sum ≤ KERNEL_HARD (25k).
+    - Each kernel rule ≤ PER_RULE_HARD (2.5k), unless listed in
+      `iron-law-overrides.txt` (then ≤ PER_RULE_OVERRIDE_CEILING = 4k).
+    - Missing kernel rules (rule-id in KERNEL_RULES but no file) → fail.
+    """
+    out: list[str] = []
+    fails: list[str] = []
+
+    kernel_rules = [r for r in rules if r["id"] in KERNEL_RULES]
+    found_ids = {str(r["id"]) for r in kernel_rules}
+    missing = sorted(KERNEL_RULES - found_ids)
+    for mid in missing:
+        fails.append(f"missing kernel rule: {mid} (declared in KERNEL_RULES, no file found)")
+
+    bucket = int(agg["kernel_chars"])
+    out.append(
+        f"kernel-bucket: {bucket} / {KERNEL_HARD} chars "
+        f"({agg['kernel_count']} rules)"
+    )
+    if bucket > KERNEL_HARD:
+        fails.append(f"kernel-bucket {bucket} > hard cap {KERNEL_HARD}")
+
+    out.append(
+        f"per-rule cap: {PER_RULE_HARD} (override ceiling {PER_RULE_OVERRIDE_CEILING} "
+        f"with ADR; allowlist {OVERRIDES_FILE.relative_to(REPO_ROOT)})"
+    )
+    out.append("")
+    out.append(f"{'id':<28} {'chars':>6} {'cap':>6} {'status':<24}")
+    out.append("-" * 68)
+    for r in sorted(kernel_rules, key=lambda r: r["id"]):
+        rid = str(r["id"])
+        chars = int(r["chars"])
+        if rid in overrides:
+            cap = PER_RULE_OVERRIDE_CEILING
+            label = "OK (override)"
+            if chars > cap:
+                label = f"FAIL (>{cap} ceiling)"
+                fails.append(f"{rid} {chars} > override ceiling {cap}")
+        else:
+            cap = PER_RULE_HARD
+            if chars > cap:
+                label = "FAIL (needs override ADR)"
+                fails.append(f"{rid} {chars} > per-rule hard cap {cap} (no override)")
+            elif chars > PER_RULE_TARGET:
+                label = "warn (> target)"
+            else:
+                label = "OK"
+        out.append(f"{rid:<28} {chars:>6} {cap:>6} {label:<24}")
+
+    out.append("")
+    if fails:
+        out.append(f"❌  kernel budget check: {len(fails)} breach(es)")
+        for f in fails:
+            out.append(f"  - {f}")
+        return 1, out
+    out.append(f"✅  kernel budget check: pass")
+    return 0, out
+
+
+def trend_append(agg: dict[str, object]) -> tuple[int, str]:
+    """Append a daily snapshot to agents/.rule-budget-history.jsonl.
+
+    Idempotent per UTC day: if today's date already has a row, the file
+    is not modified. Snapshot fields: date, kernel_chars, auto_chars,
+    rule_count, total_chars. Read by `roadmap:progress` for the Kernel
+    track per `road-to-kernel-and-router.md` P5.3.
+    """
+    today = _dt.datetime.now(_dt.timezone.utc).date().isoformat()
+    snapshot = {
+        "date": today,
+        "kernel_chars": int(agg["kernel_chars"]),
+        "auto_chars": int(agg["auto_chars"]),
+        "rule_count": int(agg["rule_count"]),
+        "total_chars": int(agg["total_chars"]),
+    }
+    TREND_FILE.parent.mkdir(parents=True, exist_ok=True)
+    if TREND_FILE.exists():
+        for line in TREND_FILE.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                row = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if row.get("date") == today:
+                return 0, f"trend: {today} already recorded — no-op"
+    with TREND_FILE.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(snapshot, sort_keys=True) + "\n")
+    return 0, f"trend: appended {today} → {TREND_FILE.relative_to(REPO_ROOT)}"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--json", action="store_true", help="emit JSON instead of a table")
+    parser.add_argument(
+        "--kernel-budget-check",
+        action="store_true",
+        help="enforce Council R2 kernel-bucket + per-rule caps; exit 1 on breach",
+    )
+    parser.add_argument(
+        "--trend-append",
+        action="store_true",
+        help="append today's snapshot to agents/.rule-budget-history.jsonl (idempotent per UTC day)",
+    )
+    args = parser.parse_args(argv)
+
+    rules = collect()
+    agg = aggregate(rules)
+
+    if args.kernel_budget_check:
+        overrides = load_overrides()
+        code, report = kernel_budget_check(rules, agg, overrides)
+        print("\n".join(report))
+        return code
+
+    if args.trend_append:
+        code, msg = trend_append(agg)
+        print(msg)
+        return code
+
+    if args.json:
+        payload = {"rules": sorted(rules, key=lambda r: r["id"]), "summary": agg}
+        print(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        print(render_table(rules, agg))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/migrate_command_suggestions.py

@@ -29,7 +29,7 @@ INELIGIBLE: dict[str, str] = {
     "copilot-agents-init": "Project init — only deliberately during onboarding.",
     "copilot-agents-optimize": "Maintenance refactor; only when the maintainer chooses to run it.",
     "do-and-judge": "Subagent orchestration — overlaps /work and judge skills; keep explicit.",
-    "do-in-steps": "Subagent orchestration — overlaps /work and /roadmap-execute; keep explicit.",
+    "do-in-steps": "Subagent orchestration — overlaps /work and /roadmap:process-*; keep explicit.",
     "fix-portability": "Package-internal — only the event4u/agent-config repo runs this.",
     "fix-references": "Package-internal — only the event4u/agent-config repo runs this.",
     "judge": "Sibling of /review-changes — eligibility routed there; keep this explicit.",
@@ -89,7 +89,7 @@ ELIGIBLE: dict[str, tuple[str, str]] = {
     "review-changes": ("self-review my changes, judge this diff before PR", "uncommitted or staged changes pre-PR"),
     "review-routing": ("who should review this, suggest reviewers for this PR", "PR open without assigned reviewers"),
     "roadmap-create": ("create a roadmap for X, plan this work as a roadmap", "multi-phase work without an existing agents/roadmaps/*.md"),
-    "roadmap-execute": ("execute the roadmap, work through the roadmap step by step", "existing agents/roadmaps/*.md referenced in the prompt"),
+    "roadmap-execute": ("process the roadmap, work through the roadmap autonomously, finish this phase", "existing agents/roadmaps/*.md referenced in the prompt"),
     "rule-compliance-audit": ("audit my rules, check rule trigger quality", "maintainer working on .augment/rules/ files"),
     "tests-create": ("write tests for these changes, add tests for this branch", "code changes on the branch without matching test changes"),
     "tests-execute": ("run the tests, execute the test suite", "code changes pending verification"),

package/scripts/prototype_lint_contradictions.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""
+Prototype contradiction linter (P1.1 of road-to-package-optimization).
+
+Hard acceptance: must flag >=3 real cross-artifact contradictions in this
+repo within 5 s wall-clock and < $0.01 cost (deterministic, no LLM calls).
+On failure, the roadmap closes with the null result documented; no
+Phase 2 work begins.
+
+Heuristic family — three deterministic checks across rules, skills,
+commands, and contexts:
+
+1. Routing mismatch: rule frontmatter `routes_to: [skill:foo]` but the
+   target artifact does not exist or has no matching trigger.
+2. Trigger collision with imperative conflict: two artifacts share a
+   trigger keyword AND one body contains an `ALWAYS X` Iron Law while
+   the other contains `NEVER X` (or `MUST` vs `MUST NOT`) on the same
+   verb-object.
+3. Catalog drift: a token-optimizer-style catalog row cites a path that
+   does not exist (subset of #1, broader scope than the freshness gate).
+
+Stdlib only. JSON to stdout. Exit 0 = clean / Exit 1 = contradictions found.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+import time
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+SRC = REPO / ".agent-src.uncompressed"
+
+ARTIFACT_DIRS = {
+    "rule": SRC / "rules",
+    "skill": SRC / "skills",
+    "command": SRC / "commands",
+    "context": SRC / "contexts",
+}
+
+FM_RE = re.compile(r"^---\n(.*?)\n---\n", re.DOTALL)
+ALWAYS_RE = re.compile(r"^\s*(ALWAYS|MUST)\s+([A-Z][^.\n]{2,80})", re.MULTILINE)
+NEVER_RE = re.compile(r"^\s*(NEVER|MUST NOT|DO NOT)\s+([A-Z][^.\n]{2,80})", re.MULTILINE)
+
+
+def parse_artifact(path: Path, kind: str) -> dict:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    fm: dict = {}
+    m = FM_RE.match(text)
+    body = text
+    if m:
+        body = text[m.end():]
+        for line in m.group(1).splitlines():
+            if ":" in line and not line.startswith(" "):
+                k, _, v = line.partition(":")
+                fm[k.strip()] = v.strip()
+    triggers = re.findall(r"`([a-z][a-z0-9_-]+)`", fm.get("description", ""))
+    routes = re.findall(r"(skill|rule|command):([a-z0-9_-]+)", fm.get("routes_to", ""))
+    always = [m.group(2).strip() for m in ALWAYS_RE.finditer(body)]
+    never = [m.group(2).strip() for m in NEVER_RE.finditer(body)]
+    return {
+        "kind": kind,
+        "path": str(path.relative_to(REPO)),
+        "id": path.stem if path.name != "SKILL.md" else path.parent.name,
+        "triggers": set(triggers),
+        "routes": routes,
+        "always": always,
+        "never": never,
+    }
+
+
+def collect() -> list[dict]:
+    out: list[dict] = []
+    for kind, root in ARTIFACT_DIRS.items():
+        if not root.exists():
+            continue
+        for p in root.rglob("*.md"):
+            if p.name in {"README.md", "INDEX.md"}:
+                continue
+            out.append(parse_artifact(p, kind))
+    return out
+
+
+def check_routing(arts: list[dict]) -> list[dict]:
+    by_id = {(a["kind"], a["id"]): a for a in arts}
+    flags: list[dict] = []
+    for a in arts:
+        for tgt_kind, tgt_id in a["routes"]:
+            if (tgt_kind, tgt_id) not in by_id:
+                flags.append({
+                    "type": "routing_mismatch",
+                    "artifact_a": a["path"],
+                    "artifact_b": f"{tgt_kind}:{tgt_id} (missing)",
+                    "evidence": f"{a['id']} routes_to {tgt_kind}:{tgt_id}, target not found",
+                })
+    return flags
+
+
+def normalize_verb(s: str) -> str:
+    return re.sub(r"[^a-z ]+", "", s.lower()).split(" ", 1)[0] if s else ""
+
+
+def check_imperative_conflict(arts: list[dict]) -> list[dict]:
+    flags: list[dict] = []
+    by_trigger: dict[str, list[dict]] = {}
+    for a in arts:
+        for t in a["triggers"]:
+            by_trigger.setdefault(t, []).append(a)
+    for trigger, group in by_trigger.items():
+        if len(group) < 2:
+            continue
+        for i, a in enumerate(group):
+            for b in group[i + 1:]:
+                a_verbs = {normalize_verb(s) for s in a["always"]}
+                b_verbs = {normalize_verb(s) for s in b["never"]}
+                conflict = a_verbs & b_verbs - {""}
+                if conflict:
+                    flags.append({
+                        "type": "imperative_conflict",
+                        "artifact_a": a["path"],
+                        "artifact_b": b["path"],
+                        "evidence": f"shared trigger '{trigger}', a says ALWAYS {sorted(conflict)}, b says NEVER {sorted(conflict)}",
+                    })
+    return flags
+
+
+def main() -> int:
+    t0 = time.monotonic()
+    arts = collect()
+    flags = check_routing(arts) + check_imperative_conflict(arts)
+    elapsed = time.monotonic() - t0
+    report = {
+        "artifacts_scanned": len(arts),
+        "elapsed_seconds": round(elapsed, 3),
+        "flags": flags,
+        "acceptance": {
+            "min_flags": 3,
+            "max_seconds": 5.0,
+            "passed": len(flags) >= 3 and elapsed < 5.0,
+        },
+    }
+    json.dump(report, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0 if not flags else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/schemas/command.schema.json

@@ -49,6 +49,11 @@
       "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
       "description": "Semver release in which this command became a shim (e.g. '1.15.0')."
     },
+    "council_depth": {
+      "type": "string",
+      "enum": ["deep"],
+      "description": "Optional reasoning-depth marker for AI Council invocations triggered by this command. The only accepted value is 'deep'; omit the key for default depth (setting 'standard' is rejected — every frontmatter byte counts against the context window, and 'standard' is the implicit default). 'deep' instructs the host agent to pass --depth deep to council_cli, which floors rounds at max(ai_council.deep_min_rounds, ai_council.min_rounds). Use for architecture, refactoring, or bug-diagnosis commands. See .agent-src.uncompressed/skills/ai-council/SKILL.md."
+    },
     "suggestion": {
       "type": "object",
       "additionalProperties": false,

package/scripts/schemas/rule.schema.json

@@ -26,18 +26,72 @@
     },
     "load_context": {
       "type": "array",
-      "items": {"type": "string", "pattern": "\\.md$"},
-      "description": "Lazy on-demand context references. Path rules and budget caps enforced by scripts/lint_load_context.py. Contract: docs/contracts/load-context-schema.md."
+      "items": {
+        "type": "string",
+        "pattern": "^((\\.\\./)*contexts/|agents/contexts/|\\.agent-src/contexts/)[^\\s]+\\.md$",
+        "description": "Logical name (preferred — `contexts/<area>/<file>.md`) or project-local (`agents/contexts/<file>.md`). The `.agent-src.uncompressed/` prefix is rejected by the regex; the rewriter (`scripts/compress.py::_rewrite_paths`) resolves logical names at compress time. Rewritten relative forms (`../contexts/...`, `../../contexts/...`) are accepted so the linter passes on the compressed mirror in CI."
+      },
+      "description": "Lazy on-demand context references. Use logical names rooted at the source (e.g. `contexts/execution/foo.md`); the `.agent-src.uncompressed/` prefix is forbidden by the regex (road-to-path-fixes.md P5.3). Path rules and budget caps enforced by scripts/lint_load_context.py. Contract: docs/contracts/load-context-schema.md."
     },
     "load_context_eager": {
       "type": "array",
-      "items": {"type": "string", "pattern": "\\.md$"},
-      "description": "Eager auto-loaded context references. Counts against the per-rule char budget; enforced by scripts/lint_load_context.py."
+      "items": {
+        "type": "string",
+        "pattern": "^((\\.\\./)*contexts/|agents/contexts/|\\.agent-src/contexts/)[^\\s]+\\.md$",
+        "description": "Same logical-name rule as `load_context`."
+      },
+      "description": "Eager auto-loaded context references. Same logical-name rule as `load_context`. Counts against the per-rule char budget; enforced by scripts/lint_load_context.py."
     },
     "tier": {
       "type": "string",
-      "enum": ["1", "2a", "2b", "3", "safety-floor", "mechanical-already"],
-      "description": "Hardening tier per road-to-rule-hardening.md. Optional today, recommended for new rules. Tracked in agents/contexts/rule-trigger-matrix.md. Tier 3 rules also referenced in agents/contexts/tier-3-dispositions.md."
+      "enum": ["1", "2a", "2b", "3", "safety-floor", "mechanical-already", "kernel", "tier-1", "tier-2"],
+      "description": "Hardening tier. Legacy values (1/2a/2b/3/safety-floor/mechanical-already) accepted; new router-canonical values (kernel/tier-1/tier-2) introduced by road-to-kernel-and-router.md Phase 4."
+    },
+    "council_depth": {
+      "type": "string",
+      "enum": ["deep"],
+      "description": "Optional reasoning-depth marker for AI Council invocations triggered while this rule is active. The only accepted value is 'deep'; omit the key for default depth (setting 'standard' is rejected — every frontmatter byte counts against the context window, and 'standard' is the implicit default). 'deep' instructs the host agent to pass --depth deep to council_cli, which floors rounds at max(ai_council.deep_min_rounds, ai_council.min_rounds). Use for rules that gate architecture, refactoring, or bug-diagnosis flows. See .agent-src.uncompressed/skills/ai-council/SKILL.md."
+    },
+    "triggers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "keyword": {"type": "string"},
+          "phrase": {"type": "string"},
+          "intent": {"type": "string"},
+          "file_pattern": {"type": "string"},
+          "path_prefix": {"type": "string", "description": "Literal path-prefix match pattern the host evaluates against the file the agent is editing — NOT a file reference. The rewriter leaves it verbatim. Source-of-truth rules that must fire on edits under `.agent-src.uncompressed/` keep that prefix here (the prefix ban applies only to `load_context:` and body links — see road-to-path-fixes.md P2.2 / AI-Council 2026-05-06)."},
+          "command": {"type": "string"},
+          "reason": {"type": "string"}
+        }
+      },
+      "description": "Router activation triggers (Phase 3 of road-to-kernel-and-router.md). Forbidden on kernel rules, required on non-kernel rules. Schema: docs/contracts/rule-router.md."
+    },
+    "routes_to": {
+      "type": "array",
+      "items": {"type": "string", "pattern": "^(skill|guideline|command|contract):"},
+      "description": "Router targets (skill / guideline / command / contract). Forbidden on kernel rules. Schema: docs/contracts/rule-router.md."
+    },
+    "profile": {
+      "type": "string",
+      "enum": ["minimal", "balanced", "full"],
+      "description": "Optional profile override; rare. Tier-derived default applies otherwise."
+    },
+    "validator_ignore": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["type", "pattern"],
+        "properties": {
+          "type": {"type": "string", "enum": ["substring", "regex"]},
+          "pattern": {"type": "string", "minLength": 1},
+          "reason": {"type": "string", "description": "Human-readable rationale for the suppression — surfaced in audit logs."}
+        }
+      },
+      "description": "Per-rule allowlist consumed by the post-compression validator (scripts/check_compressed_paths.py). Rules that document forbidden path substrings as their subject matter (e.g. augment-portability, no-roadmap-references) declare the literal strings here so the gate does not flag itself. road-to-path-fixes.md P5.1."
     }
   }
 }

package/scripts/schemas/skill.schema.json

@@ -42,6 +42,11 @@
       "enum": ["senior"],
       "description": "Optional tier marker. `senior` opts the skill into the Senior-Tier Required Structure check (Context-First lead, Related Skills, Proactive Triggers, Output Artifacts) per .agent-src.uncompressed/rules/skill-quality.md."
     },
+    "council_depth": {
+      "type": "string",
+      "enum": ["deep"],
+      "description": "Optional reasoning-depth marker for AI Council invocations triggered by this skill. The only accepted value is 'deep'; omit the key for default depth (setting 'standard' is rejected — every frontmatter byte counts against the context window, and 'standard' is the implicit default). 'deep' instructs the host agent to pass --depth deep to council_cli, which floors rounds at max(ai_council.deep_min_rounds, ai_council.min_rounds). Use for architecture, refactoring, or bug-diagnosis skills. See .agent-src.uncompressed/skills/ai-council/SKILL.md."
+    },
     "execution": {
       "type": "object",
       "additionalProperties": false,