@event4u/agent-config 1.20.0 → 1.21.0

package/scripts/_pilot_measure.py

@@ -0,0 +1,53 @@
+"""Pilot compression ratio + Iron-Law checksum verification (one-off, not CI)."""
+import sys, re, hashlib, statistics
+from pathlib import Path
+
+sys.path.insert(0, "scripts")
+from measure_rule_budget import strip_frontmatter
+
+FENCE_RE = re.compile(r"```(?:[^\n]*\n)([\s\S]*?)```")
+
+
+def iron_law_sha(body: str) -> str:
+    blocks = FENCE_RE.findall(body)
+    norm = "".join(re.sub(r"\s+", " ", b).strip().upper() for b in blocks)
+    return hashlib.sha256(norm.encode()).hexdigest()[:16]
+
+
+pairs = [
+    ("agent-authority",   ".agent-src.uncompressed/rules/agent-authority.md",   "docs/contracts/pilot/agent-authority.md"),
+    ("direct-answers",    ".agent-src.uncompressed/rules/direct-answers.md",    "docs/contracts/pilot/direct-answers.md"),
+    ("language-and-tone", ".agent-src.uncompressed/rules/language-and-tone.md", "docs/contracts/pilot/language-and-tone.md"),
+]
+
+header = f"{'rule':25s} {'orig':>6s}  {'pilot':>6s}  {'r':>6s}  {'budget':>7s}  {'sha-orig':>16s}  {'sha-pilot':>16s}  {'IL':>3s}"
+print(header)
+print("-" * len(header))
+
+ratios = []
+for rid, orig_path, pilot_path in pairs:
+    orig_body, _  = strip_frontmatter(Path(orig_path).read_text())
+    pilot_body, _ = strip_frontmatter(Path(pilot_path).read_text())
+    o, p = len(orig_body), len(pilot_body)
+    r = p / o
+    ratios.append(r)
+    sha_o = iron_law_sha(orig_body)
+    sha_p = iron_law_sha(pilot_body)
+    match = "OK" if sha_o == sha_p else "FAIL"
+    budget = "OK" if p <= 1500 else f"+{p - 1500}"
+    print(f"{rid:25s} {o:6d}  {p:6d}  {r:6.3f}  {budget:>7s}  {sha_o:>16s}  {sha_p:>16s}  {match:>3s}")
+
+mean   = sum(ratios) / len(ratios)
+median = statistics.median(ratios)
+print()
+print(f"r-values : {[round(x, 3) for x in ratios]}")
+print(f"mean   r = {mean:.3f}")
+print(f"median r = {median:.3f}")
+print(f"max    r = {max(ratios):.3f}")
+print(f"min    r = {min(ratios):.3f}")
+print()
+
+TOTAL = 32403
+print(f"Projected always-bucket @ r=mean ({mean:.3f})  : {int(TOTAL * mean):>6d}  (target ≤ 25000)")
+print(f"Projected always-bucket @ r=max  ({max(ratios):.3f})  : {int(TOTAL * max(ratios)):>6d}  (target ≤ 25000)")
+print(f"Projected always-bucket @ r=med  ({median:.3f})  : {int(TOTAL * median):>6d}  (target ≤ 25000)")

package/scripts/ai_council/session.py

@@ -35,9 +35,15 @@ from scripts.ai_council.orchestrator import render
 
 REPO_ROOT = Path(__file__).resolve().parents[2]
 SESSIONS_DIR = REPO_ROOT / "agents" / "council-sessions"
+QUESTIONS_DIR = REPO_ROOT / "agents" / "council-questions"
+RESPONSES_DIR = REPO_ROOT / "agents" / "council-responses"
 SETTINGS_FILE = REPO_ROOT / ".agent-settings.yml"
 
-DEFAULT_RETENTION_DAYS = 14
+# Default retention for all council artefacts (questions, responses,
+# sessions). Overridden by `ai_council.session_retention_days`
+# in `.agent-settings.yml`. Council files are local-only scratch — short
+# retention keeps the working tree from accumulating dead weight.
+DEFAULT_RETENTION_DAYS = 7
 _TS_RE = re.compile(r"^(\d{4})-(\d{2})-(\d{2})T(\d{2})-(\d{2})-(\d{2})Z$")
 
 
@@ -152,6 +158,92 @@ def prune_old_sessions(
     return removed
 
 
+def prune_old_artifacts(
+    artifact_dir: Path,
+    retention_days: int,
+    *,
+    now: _dt.datetime | None = None,
+) -> list[Path]:
+    """Delete files and timestamp-less directories older than `retention_days`.
+
+    mtime-based — used for `agents/council-questions/`,
+    `agents/council-responses/`, and root-level files in
+    `agents/council-sessions/` that don't match the
+    timestamp-subdir convention handled by `prune_old_sessions`.
+
+    Walks the directory non-recursively. For files: deletes when
+    mtime predates the cutoff. For sub-directories without a
+    timestamp name: deletes recursively when mtime predates the
+    cutoff. Never raises — disk failures log to stderr.
+
+    Returns the list of deleted paths. `retention_days <= 0`
+    disables pruning and returns an empty list.
+    """
+    if retention_days <= 0 or not artifact_dir.exists():
+        return []
+    cutoff = (now or _dt.datetime.now(_dt.timezone.utc)) - _dt.timedelta(days=retention_days)
+    cutoff_ts = cutoff.timestamp()
+    removed: list[Path] = []
+    try:
+        entries = list(artifact_dir.iterdir())
+    except OSError as exc:  # noqa: BLE001 - never block the report
+        print(f"[council:session] artifact iterdir failed: {exc}", file=sys.stderr)
+        return removed
+    for entry in entries:
+        # Timestamp subdirs are owned by prune_old_sessions; skip them
+        # so the two pruners don't race.
+        if entry.is_dir() and _parse_session_timestamp(entry.name) is not None:
+            continue
+        try:
+            mtime = entry.stat().st_mtime
+        except OSError as exc:  # noqa: BLE001 - never block the report
+            print(f"[council:session] artifact stat failed for {entry}: {exc}",
+                  file=sys.stderr)
+            continue
+        if mtime >= cutoff_ts:
+            continue
+        try:
+            if entry.is_dir():
+                shutil.rmtree(entry)
+            else:
+                entry.unlink()
+            removed.append(entry)
+        except OSError as exc:  # noqa: BLE001 - never block the report
+            print(f"[council:session] artifact remove failed for {entry}: {exc}",
+                  file=sys.stderr)
+    return removed
+
+
+def prune_all_council_artifacts(
+    retention_days: int | None = None,
+    *,
+    repo_root: Path | None = None,
+    now: _dt.datetime | None = None,
+) -> dict[str, list[Path]]:
+    """Prune every council artefact dir under `repo_root` in one pass.
+
+    Reads `retention_days` from settings if not supplied. Used by the
+    `task council-prune` target and by `save()`. Never raises.
+
+    Returns a dict keyed by directory label — `sessions`,
+    `questions`, `responses` — each mapped to the list of
+    paths actually removed.
+    """
+    root = repo_root or REPO_ROOT
+    days = _load_retention_days() if retention_days is None else retention_days
+    sessions = root / "agents" / "council-sessions"
+    questions = root / "agents" / "council-questions"
+    responses = root / "agents" / "council-responses"
+    return {
+        "sessions": (
+            prune_old_sessions(sessions, days, now=now)
+            + prune_old_artifacts(sessions, days, now=now)
+        ),
+        "questions": prune_old_artifacts(questions, days, now=now),
+        "responses": prune_old_artifacts(responses, days, now=now),
+    }
+
+
 def save(
     *,
     manifest: SessionManifest,
@@ -167,10 +259,12 @@ def save(
     - `Iterable[list[CouncilResponse]]` — multi-round, one list per
       round in execution order.
 
-    `retention_days` controls auto-pruning of older sibling sessions
-    after the new one is written. `None` reads the value from
-    `.agent-settings.yml` (`ai_council.session_retention_days`,
-    default `14`); `0` disables pruning.
+    `retention_days` controls auto-pruning of older council artefacts
+    after the new one is written — sibling sessions plus, when
+    `sessions_dir` is not overridden, files in `council-questions/`
+    and `council-responses/`. `None` reads the value
+    from `.agent-settings.yml` (`ai_council.session_retention_days`,
+    default `7`); `0` disables pruning.
 
     Disk-write failures are surfaced via a stderr line but do not
     raise; the caller's text report is the source of truth.
@@ -232,5 +326,13 @@ def save(
 
     days = _load_retention_days() if retention_days is None else retention_days
     prune_old_sessions(base, days)
+    prune_old_artifacts(base, days)
+    # In production (no sessions_dir override), also prune the sibling
+    # council artefact dirs so questions/responses aren't left as dead
+    # weight. Tests that pass an explicit sessions_dir stay isolated
+    # from the wider tree.
+    if sessions_dir is None:
+        prune_old_artifacts(QUESTIONS_DIR, days)
+        prune_old_artifacts(RESPONSES_DIR, days)
 
     return session_dir

package/scripts/build_linear_digest.py

@@ -76,15 +76,13 @@ WORKSPACE: list[RuleEntry] = [
     RuleEntry("reviewer-awareness"),
     RuleEntry("scope-control"),
     RuleEntry("security-sensitive-stop"),
-    RuleEntry("think-before-action", "degraded",
-              strip_sections=["Consult memory before editing"]),
+    RuleEntry("think-before-action"),
     RuleEntry("verify-before-complete"),
-    RuleEntry("cli-output-handling", "degraded",
-              strip_sections=["Iron Law — rtk first, tail/grep fallback"]),
+    RuleEntry("cli-output-handling"),
     RuleEntry("downstream-changes"),
     RuleEntry("improve-before-implement"),
     RuleEntry("language-and-tone", "degraded",
-              strip_sections=["`.md` files are ALWAYS English — no exceptions"]),
+              strip_sections=["`.md` files — ALWAYS English"]),
     RuleEntry("missing-tool-handling"),
     RuleEntry("token-efficiency"),
     RuleEntry("user-interaction"),

package/scripts/check_always_budget.py

@@ -47,6 +47,26 @@ FAIL_THRESHOLD = 0.90
 CONCENTRATION_SINGLE_PCT = 0.12
 CONCENTRATION_TOP3_PCT = 0.30
 
+# Transitional concentration allowlist — non-safety-floor rules whose
+# extended share exceeds CONCENTRATION_SINGLE_PCT after the kernel-trim
+# refactor (commit 4e771da `refactor(kernel): compress 8 kernel rules
+# per P2.2 playbook + lock kernel`). Trimming safety-floor rules shrank
+# the denominator, mechanically lifting non-floor rules' percentage
+# share even though their absolute size did not grow. Each entry pins
+# the measured extended-size ceiling at the day road-to-path-fixes was
+# closed; growth above the ceiling regresses CI. Future kernel-aware
+# trimming work retires entries here.
+KNOWN_CONCENTRATION_BREACHES: dict[str, int] = {
+    "language-and-tone.md": 3_985,
+    "no-cheap-questions.md": 3_530,
+}
+# Top-3 non-floor concentration ceiling — same rationale as the
+# per-rule allowlist above. The current top-3 sum (language-and-tone +
+# scope-control-allowlisted + non-destructive-allowlisted) clears the
+# 30 % cap; the entry below pins the measured ceiling. Future trim
+# work drops this back to None (default 30 %).
+KNOWN_TOP3_CONCENTRATION_CEILING: int | None = 10_900
+
 # Q3=A locked safety-floor rules — out of scope for slimming and for the
 # concentration check. Their size is intentional (Iron Laws + obligation
 # surface), not drift. See road-to-structural-optimization Phase 5.
@@ -221,6 +241,12 @@ def _concentration_check(
     Returns (single-rule breaches, top-3 breach or None). Q3=A locked
     safety-floor rules are excluded from both numerator and the top-3
     selection — their size is intentional, not drift.
+
+    Allowlisted rules in `KNOWN_CONCENTRATION_BREACHES` are exempted
+    from the per-rule cap as long as their extended size does not
+    exceed the recorded ceiling (regression guard). The top-3 cap is
+    relaxed to `KNOWN_TOP3_CONCENTRATION_CEILING` while that ceiling
+    is non-None.
     """
     non_floor = [
         (name, raw, ext) for name, raw, ext in sizes
@@ -229,15 +255,22 @@ def _concentration_check(
     single_cap = total_ext * CONCENTRATION_SINGLE_PCT
     top3_cap = total_ext * CONCENTRATION_TOP3_PCT
 
-    single_breaches = [
-        (name, ext, ext / total_ext)
-        for name, _, ext in non_floor
-        if ext > single_cap
-    ]
+    single_breaches: list[tuple[str, int, float]] = []
+    for name, _, ext in non_floor:
+        if ext <= single_cap:
+            continue
+        ceiling = KNOWN_CONCENTRATION_BREACHES.get(name)
+        if ceiling is not None and ext <= ceiling:
+            continue
+        single_breaches.append((name, ext, ext / total_ext))
+
     top3_sum = sum(ext for _, _, ext in non_floor[:3])
+    effective_top3_cap = top3_cap
+    if KNOWN_TOP3_CONCENTRATION_CEILING is not None:
+        effective_top3_cap = max(top3_cap, KNOWN_TOP3_CONCENTRATION_CEILING)
     top3_breach = (
         (top3_sum, top3_sum / total_ext)
-        if top3_sum > top3_cap else None
+        if top3_sum > effective_top3_cap else None
     )
     return single_breaches, top3_breach
 

package/scripts/check_compressed_paths.py

@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+"""Validate compressed-output paths in `.agent-src/rules/*.md`.
+
+Runs after `scripts/compress.py` projects sources to `.agent-src/`. The
+rewriter in `compress.py` is the load-bearing primitive (road-to-path-fixes
+P1.2); this script is the post-condition gate (P5.1) — every `load_context:`
+entry in `.agent-src/rules/*.md` must resolve relative to the rule file's
+directory to an existing file, and forbidden substrings must not survive
+the rewrite (unless declared in `validator_ignore`).
+
+Forbidden substrings (load_context + body):
+  - `.agent-src.uncompressed/`            unless declared in validator_ignore
+  - `../../docs/`                         body-link two-up form (rewriter
+                                           collapses to single-up)
+  - `../../agents/`                       same shape, different root
+
+Body-link checks (Council Decision 2, 2026-05-06):
+  - `load_context:` entries MUST resolve to an existing file under
+    `.agent-src/`.
+  - Body markdown links to `../contexts/...md` MUST resolve.
+  - Body markdown links to `../docs/guidelines/...md` are NOT checked
+    (P3.1 was cancelled; resolution is intentionally out of scope, the
+    Copilot suppression floor in P6 is the silencer).
+
+`validator_ignore:` frontmatter primitive:
+  - Per-rule allowlist for rules that *describe* a forbidden substring as
+    their subject matter (e.g. `augment-source-of-truth` documents the
+    `.agent-src.uncompressed/` boundary). Each entry: `{type, pattern,
+    reason}`. The validator emits an audit line per matched ignore so
+    drift cannot hide.
+
+Exit codes: 0 = clean, 1 = violations found, 3 = internal error.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+ROOT = Path(__file__).resolve().parent.parent
+RULES_DIR = ROOT / ".agent-src" / "rules"
+
+FORBIDDEN_SUBSTRINGS = (
+    ".agent-src.uncompressed/",
+    "../../docs/",
+    "../../agents/",
+)
+
+# Markdown links: `[text](path)` — capture path. Skip URLs and anchors.
+_LINK_RE = re.compile(r'\[[^\]]*\]\(([^)#\s]+)(?:#[^)]*)?\)')
+
+
+# Body-link prefixes whose resolution is intentionally out of scope.
+# Council Decision 2 (2026-05-06): P3.1 was cancelled, so guideline links
+# under `.agent-src/rules/` cannot resolve in the projected tree. Copilot
+# suppression (P6) is the silencer for the noise.
+UNCHECKED_LINK_PREFIXES = (
+    "../docs/guidelines/",
+    "../../docs/guidelines/",
+)
+
+
+@dataclass
+class Violation:
+    file: str
+    line: int
+    kind: str
+    detail: str
+
+
+@dataclass
+class IgnoreEntry:
+    """Frontmatter `validator_ignore:` entry."""
+    kind: str       # "substring" | "link"
+    pattern: str    # exact substring or link prefix to ignore
+    reason: str     # human-readable rationale (audited)
+
+
+def _split_frontmatter(text: str):
+    if not text.startswith("---\n"):
+        return None, text
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return None, text
+    fm_text = text[4:end]
+    body = text[end + len("\n---\n"):]
+    try:
+        fm = yaml.safe_load(fm_text)
+    except yaml.YAMLError:
+        return None, text
+    return fm if isinstance(fm, dict) else {}, body
+
+
+def _parse_ignores(fm: dict) -> list[IgnoreEntry]:
+    entries = fm.get("validator_ignore") or []
+    if not isinstance(entries, list):
+        return []
+    out: list[IgnoreEntry] = []
+    for raw in entries:
+        if not isinstance(raw, dict):
+            continue
+        kind = str(raw.get("type") or "").strip()
+        pattern = str(raw.get("pattern") or "").strip()
+        reason = str(raw.get("reason") or "").strip()
+        if kind in ("substring", "link") and pattern and reason:
+            out.append(IgnoreEntry(kind=kind, pattern=pattern, reason=reason))
+    return out
+
+
+def _ignored(needle: str, ignores: list[IgnoreEntry], kind: str) -> IgnoreEntry | None:
+    for ig in ignores:
+        if ig.kind == kind and ig.pattern == needle:
+            return ig
+    return None
+
+
+def _check_load_context(rule_file: Path, fm: dict, viols: list[Violation],
+                        ignores: list[IgnoreEntry], audited: list[tuple[str, IgnoreEntry]]) -> None:
+    rule_dir = rule_file.parent
+    for key in ("load_context", "load_context_eager"):
+        entries = fm.get(key) or []
+        if not isinstance(entries, list):
+            continue
+        for entry in entries:
+            if not isinstance(entry, str):
+                continue
+            blocked = False
+            for needle in FORBIDDEN_SUBSTRINGS:
+                if needle in entry:
+                    ig = _ignored(needle, ignores, "substring")
+                    if ig:
+                        audited.append((str(rule_file.relative_to(ROOT)), ig))
+                        continue
+                    viols.append(Violation(
+                        str(rule_file.relative_to(ROOT)), 0, f"{key}-forbidden",
+                        f"forbidden substring {needle!r} in entry {entry!r}",
+                    ))
+                    blocked = True
+                    break
+            if blocked:
+                continue
+            target = (rule_dir / entry).resolve()
+            if not target.is_file():
+                viols.append(Violation(
+                    str(rule_file.relative_to(ROOT)), 0, f"{key}-missing",
+                    f"{entry!r} does not resolve to an existing file",
+                ))
+
+
+def _check_body(rule_file: Path, body: str, viols: list[Violation],
+                ignores: list[IgnoreEntry], audited: list[tuple[str, IgnoreEntry]]) -> None:
+    rule_dir = rule_file.parent
+    for line_num, line in enumerate(body.splitlines(), start=1):
+        for needle in FORBIDDEN_SUBSTRINGS:
+            if needle in line:
+                ig = _ignored(needle, ignores, "substring")
+                if ig:
+                    audited.append((f"{rule_file.relative_to(ROOT)}:{line_num}", ig))
+                    continue
+                viols.append(Violation(
+                    str(rule_file.relative_to(ROOT)), line_num, "body-forbidden",
+                    f"forbidden substring {needle!r}",
+                ))
+        for m in _LINK_RE.finditer(line):
+            link = m.group(1)
+            if link.startswith(("http://", "https://", "mailto:", "#")):
+                continue
+            if not link.endswith(".md"):
+                continue
+            if any(link.startswith(p) for p in UNCHECKED_LINK_PREFIXES):
+                continue
+            target = (rule_dir / link).resolve()
+            if not target.is_file():
+                viols.append(Violation(
+                    str(rule_file.relative_to(ROOT)), line_num, "body-link-missing",
+                    f"link target {link!r} does not resolve",
+                ))
+
+
+def main() -> int:
+    if not RULES_DIR.is_dir():
+        print(f"❌  {RULES_DIR} not found — run compression first", file=sys.stderr)
+        return 3
+    viols: list[Violation] = []
+    audited: list[tuple[str, IgnoreEntry]] = []
+    for rule_file in sorted(RULES_DIR.glob("*.md")):
+        text = rule_file.read_text(encoding="utf-8")
+        fm, body = _split_frontmatter(text)
+        ignores: list[IgnoreEntry] = _parse_ignores(fm) if fm is not None else []
+        if fm is not None:
+            _check_load_context(rule_file, fm, viols, ignores, audited)
+        _check_body(rule_file, body, viols, ignores, audited)
+    if audited:
+        print("ℹ️   validator_ignore audit:")
+        for loc, ig in audited:
+            print(f"    {loc} — [{ig.kind}] {ig.pattern!r} → {ig.reason}")
+        print()
+    if viols:
+        for v in viols:
+            loc = f"{v.file}:{v.line}" if v.line else v.file
+            print(f"❌  [{v.kind}] {loc} — {v.detail}")
+        print(f"\n{len(viols)} violation(s) in .agent-src/rules/")
+        return 1
+    rule_count = len(list(RULES_DIR.glob('*.md')))
+    print(f"✅  compressed-path check clean ({rule_count} rules, {len(audited)} ignore(s) audited)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_compression.py

@@ -24,6 +24,15 @@ from dataclasses import dataclass, asdict
 from pathlib import Path
 from typing import List, Literal
 
+# Import the rewriter so frontmatter comparison can normalise the source
+# side through the same path transformations the compressor applies. Without
+# this, every `load_context:` logical name (e.g. `contexts/foo.md`) and every
+# `../../docs/...` body link looks like a frontmatter / body mismatch even
+# though the rewriter is doing exactly what road-to-path-fixes.md P2/P3
+# specified.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from compress import _rewrite_paths  # noqa: E402
+
 Severity = Literal["error", "warning", "info"]
 
 SOURCE_DIR = Path(".agent-src.uncompressed")
@@ -275,6 +284,12 @@ def scan_all(root: Path) -> List[Issue]:
 
         source_text = source_file.read_text(encoding="utf-8")
         target_text = target_file.read_text(encoding="utf-8")
+        # Normalise source through the path rewriter (idempotent) so logical
+        # `load_context:` names and `../../docs/...` body links match the
+        # depth-aware form the compressor produced. Compression word-count
+        # checks downstream are unaffected because rewriting only edits
+        # frontmatter list values and link targets, not prose tokens.
+        source_text = _rewrite_paths(source_text, rel_str)
         issues.extend(check_pair(rel_str, source_text, target_text))
 
     return issues

package/scripts/check_context_paths.py

@@ -35,6 +35,7 @@ LOCKED_SUBTREES = (
     "chat-history",
     "execution",
     "authority",
+    "contracts",
 )
 
 # Files allowed to remain at the contexts root. Anything else at the root

package/scripts/check_council_layout.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""CI guard for the `ai-council` skill's output-path convention.
+
+Council artefacts (questions, responses, sessions) belong in three
+canonical directories under `agents/`:
+
+  - agents/council-questions/<topic-slug>.md       (paired with roadmap/ADR)
+  - agents/council-responses/<topic-slug>.json     (paired with question)
+  - agents/council-sessions/<UTC-timestamp>.json   (ad-hoc sessions)
+
+The three canonical dirs are gitignored — the linter therefore only
+catches **misplacement**, not naming-conventions inside the dirs:
+
+  - Files at agents/ root with a council-* or .council-* prefix
+    (e.g. agents/council-question-foo.md, agents/.council-foo.md).
+  - council-* files under any other subdirectory of agents/.
+
+Failure modes are enforced by `.agent-src.uncompressed/skills/ai-council/SKILL.md`
+§ "Output path convention".
+
+Exit codes:
+  0 — layout is clean.
+  1 — at least one violation found; details printed to stdout.
+
+Invocation (from project root):
+  python3 scripts/check_council_layout.py
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+AGENTS_ROOT = Path("agents")
+CANONICAL_DIRS = {
+    "council-questions": ".md",
+    "council-responses": ".json",
+    "council-sessions": ".json",
+}
+# A council artefact is a file whose name starts with `council-` or
+# `.council-`. This intentionally excludes roadmaps like
+# `road-to-ai-council.md` whose stem only contains the word "council".
+COUNCIL_PREFIX_RE = re.compile(r"^\.?council-")
+
+
+def is_council_artefact(path: Path) -> bool:
+    return bool(COUNCIL_PREFIX_RE.match(path.name))
+
+
+def find_violations(root: Path) -> list[str]:
+    findings: list[str] = []
+    if not root.is_dir():
+        return findings
+
+    # 1. Stray council artefacts at agents/ root
+    for path in sorted(root.iterdir()):
+        if not path.is_file():
+            continue
+        if is_council_artefact(path):
+            findings.append(
+                f"{path}: council artefact at agents/ root — move to "
+                f"agents/council-questions/, agents/council-responses/, "
+                f"or agents/council-sessions/ per ai-council § Output path "
+                f"convention."
+            )
+
+    # 2. Council artefacts in non-canonical subdirectories
+    for path in sorted(root.rglob("*")):
+        if not path.is_file() or not is_council_artefact(path):
+            continue
+        try:
+            rel = path.relative_to(root)
+        except ValueError:
+            continue
+        if len(rel.parts) == 1:
+            continue  # already handled above
+        if rel.parts[0] in CANONICAL_DIRS:
+            continue
+        findings.append(
+            f"{path}: council artefact in non-canonical directory "
+            f"agents/{rel.parts[0]}/ — only council-questions/, "
+            f"council-responses/, council-sessions/ are allowed."
+        )
+
+    return findings
+
+
+def main() -> int:
+    findings = find_violations(AGENTS_ROOT)
+    if findings:
+        print("❌  Council layout violations:\n")
+        for f in findings:
+            print(f"  - {f}")
+        print(
+            "\nRule: .agent-src.uncompressed/skills/ai-council/SKILL.md "
+            '§ "Output path convention"'
+        )
+        return 1
+    print("✅  Council layout clean.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())