@event4u/agent-config 1.20.0 → 1.22.0

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())

package/scripts/check_council_references.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""CI guard for the `no-council-references` rule.
+
+Council artefacts under `agents/council-{questions,responses,sessions}/`
+are gitignored, local-only, and auto-pruned. A link to a specific
+council file rots three ways: gitignored (not in cloned repo),
+pruned after the retention window (gone even locally), and the
+installed `.augment/` projection cannot follow a path that does not
+exist in the consumer.
+
+This linter scans durable artefacts for forbidden links to specific
+council files. Directory mentions and placeholder paths
+(`<timestamp>`, `<topic-slug>`) are allowed — they document the
+output-path convention, not a live reference.
+
+Forbidden hits in this codebase exist today (kernel-membership ADRs
+cite real session JSONs as decision traces). Suppress them with an
+inline pragma at the end of the line:
+
+    `agents/council-sessions/...json` <!-- council-ref-allowed: <reason> -->
+
+Exit codes:
+  0 — no forbidden references.
+  1 — at least one forbidden reference found.
+
+Invocation (from project root):
+  python3 scripts/check_council_references.py
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+from typing import Iterable
+
+ROOT = Path(".")
+
+# A specific file inside a council dir: must end with .md or .json,
+# must NOT contain `<` or `>` (placeholders), must NOT contain backticks
+# or quotes (those are line delimiters, not path content).
+PATTERN = re.compile(
+    r"agents/council-(?:questions|responses|sessions)/"
+    r"([^\s\"'<>)\]`]+\.(?:md|json))"
+)
+
+# Only these durable surfaces are scanned. Archive, analysis, and the
+# council dirs themselves are excluded by design.
+SCAN_ROOTS = (
+    ".agent-src.uncompressed",
+    "agents/roadmaps",
+    "agents/contexts",
+    "agents/docs",
+    "docs/contracts",
+    "docs/decisions",
+    "docs/guidelines",
+)
+SCAN_EXTS = (".md", ".yml", ".yaml", ".json", ".py")
+
+# Files (or directory prefixes) that legitimately document the output
+# convention or are scratch / archived. Paths are POSIX-style, repo-relative.
+ALLOWLIST_PREFIXES: tuple[str, ...] = (
+    # Archived roadmaps — historical evidence trail.
+    "agents/roadmaps/archive/",
+    # Working comparison docs — forward-refs to planned artefacts (mirrors
+    # the SKIP_DIRS contract in scripts/check_references.py).
+    "agents/analysis/",
+    # The rule itself documents forbidden vs. allowed forms.
+    ".agent-src.uncompressed/rules/no-council-references.md",
+    # ai-council skill documents the output-path schema.
+    ".agent-src.uncompressed/skills/ai-council/",
+    # Council commands document the output-path schema.
+    ".agent-src.uncompressed/commands/council/",
+    ".agent-src.uncompressed/commands/council.md",
+)
+# Top-level files that are also exempt (e.g. CHANGELOG with historical entries).
+ALLOWLIST_FILES: frozenset[str] = frozenset({
+    "CHANGELOG.md",
+})
+
+INLINE_PRAGMA = re.compile(r"<!--\s*council-ref-allowed:[^>]*-->")
+
+
+def _is_allowlisted(rel: str) -> bool:
+    if rel in ALLOWLIST_FILES:
+        return True
+    return any(rel.startswith(prefix) for prefix in ALLOWLIST_PREFIXES)
+
+
+def _scan_file(path: Path) -> list[tuple[int, str]]:
+    findings: list[tuple[int, str]] = []
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return findings
+    for ln, line in enumerate(text.splitlines(), 1):
+        if INLINE_PRAGMA.search(line):
+            continue
+        for m in PATTERN.finditer(line):
+            findings.append((ln, m.group(0)))
+    return findings
+
+
+def _iter_files(roots: Iterable[str]) -> Iterable[Path]:
+    for root in roots:
+        base = ROOT / root
+        if not base.exists():
+            continue
+        if base.is_file():
+            yield base
+            continue
+        for path in sorted(base.rglob("*")):
+            if path.is_file() and path.suffix in SCAN_EXTS:
+                yield path
+
+
+def main() -> int:
+    violations: list[tuple[Path, int, str]] = []
+    for path in _iter_files(SCAN_ROOTS):
+        rel = path.as_posix()
+        if _is_allowlisted(rel):
+            continue
+        for ln, ref in _scan_file(path):
+            violations.append((path, ln, ref))
+
+    if not violations:
+        print("✅  No forbidden council references in durable artefacts.")
+        return 0
+
+    print(f"❌  {len(violations)} forbidden council reference(s):\n")
+    for path, ln, ref in violations:
+        print(f"  - {path.as_posix()}:{ln}: {ref}")
+    print(
+        "\nRule: .agent-src/rules/no-council-references.md\n"
+        "Fix: inline the convergence summary (members + date) instead of\n"
+        "linking the file. Append "
+        "<!-- council-ref-allowed: <reason> --> on the same line to\n"
+        "suppress when the reference is genuinely required (ADR / contract\n"
+        "decision trace)."
+    )
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_portability.py

@@ -316,6 +316,8 @@ _TASK_FENCE_RE = re.compile(r"^\s*task\s+([a-z][a-z0-9:_-]*)\b")
 _TASK_DETECTOR_SKIP = (
     "rules/augment-portability.md",
     "contexts/communication/rules-auto/augment-portability-mechanics.md",
+    "rules/package-ci-checks.md",
+    "contexts/communication/rules-auto/package-ci-checks-mechanics.md",
 )
 
 

package/scripts/check_references.py

@@ -103,6 +103,8 @@ EXAMPLE_PATH_PATTERNS = [
     re.compile(r"skills/[\w-]+/SKILL\.md"),    # example skill paths in commands
     re.compile(r"\{"),                         # template placeholders like {module}
     re.compile(r"\.compression-hashes\.json"), # JSON file, not .md
+    re.compile(r"-foo\.(md|json|yml|yaml)$"),  # `-foo.<ext>` placeholder examples
+    re.compile(r"-bar\.(md|json|yml|yaml)$"),  # `-bar.<ext>` placeholder examples
     # Forward references inside in-flight planning docs (road-to-
     # structural-optimization.md and its companion spike protocols).
     # Each pattern below is removed once the matching phase lands.

package/scripts/check_token_optimizer_freshness.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""
+Token-Optimizer freshness validator.
+
+Per `road-to-token-optimization.md` P1.3: parses the catalog table inside
+`.agent-src.uncompressed/skills/token-optimizer/SKILL.md`, verifies every
+cited internal asset exists, and `grep`s the trigger keywords against
+each target file. Fails on missing target OR keyword mismatch.
+
+Authoritative-link rows (upstream URLs, planned commands marked TBD) are
+recorded but not fetched — they live and die with their upstream and are
+out of scope for this CI gate.
+
+Acceptance: stdlib-only, deterministic, exit 0 = clean / exit 1 = drift.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SKILL = REPO_ROOT / ".agent-src.uncompressed" / "skills" / "token-optimizer" / "SKILL.md"
+
+# Catalog row pattern: | name | path | keywords | description |
+ROW_RE = re.compile(
+    r"^\|\s*`?(?P<name>[^`|]+?)`?\s*\|\s*"
+    r"(?P<path>[^|]+?)\s*\|\s*"
+    r"(?P<keywords>[^|]+?)\s*\|\s*"
+    r"(?P<desc>[^|]+?)\s*\|\s*$"
+)
+KW_RE = re.compile(r"`([^`]+)`")
+
+
+def parse_catalog(text: str) -> list[dict[str, str]]:
+    rows: list[dict[str, str]] = []
+    in_catalog = False
+    for line in text.splitlines():
+        if line.strip().startswith("## "):
+            in_catalog = line.strip() == "## Catalog"
+            continue
+        if not in_catalog:
+            continue
+        if line.startswith("|---") or line.startswith("| Asset"):
+            continue
+        m = ROW_RE.match(line)
+        if not m:
+            continue
+        rows.append(
+            {
+                "name": m["name"].strip(),
+                "path": m["path"].strip(),
+                "keywords": m["keywords"].strip(),
+                "desc": m["desc"].strip(),
+            }
+        )
+    return rows
+
+
+def is_external(path: str) -> bool:
+    p = path.lower()
+    return (
+        p.startswith("upstream:")
+        or p.startswith("http://")
+        or p.startswith("https://")
+        or p.startswith("tbd")
+        or "github.com" in p
+    )
+
+
+def resolve(path: str) -> Path | None:
+    if is_external(path):
+        return None
+    cleaned = path.strip().lstrip("`").rstrip("`")
+    cleaned = cleaned.split(")")[0].lstrip("[(")
+    candidate = (REPO_ROOT / cleaned).resolve()
+    return candidate
+
+
+def check_row(row: dict[str, str]) -> list[str]:
+    errs: list[str] = []
+    if is_external(row["path"]):
+        return errs
+    target = resolve(row["path"])
+    if target is None or not target.exists():
+        errs.append(f"[{row['name']}] target missing: {row['path']}")
+        return errs
+    body = target.read_text(encoding="utf-8", errors="replace").lower()
+    for kw in KW_RE.findall(row["keywords"]):
+        kw_lc = kw.strip().lower()
+        if not kw_lc:
+            continue
+        if kw_lc not in body:
+            errs.append(
+                f"[{row['name']}] trigger keyword '{kw}' not found in "
+                f"{row['path']} — catalog row may be stale"
+            )
+    return errs
+
+
+def main() -> int:
+    if not SKILL.exists():
+        print(f"ERROR: token-optimizer skill not found at {SKILL}", file=sys.stderr)
+        return 1
+    text = SKILL.read_text(encoding="utf-8")
+    rows = parse_catalog(text)
+    if not rows:
+        print(
+            "ERROR: token-optimizer SKILL.md has no parseable catalog rows",
+            file=sys.stderr,
+        )
+        return 1
+    all_errs: list[str] = []
+    checked = 0
+    for row in rows:
+        errs = check_row(row)
+        all_errs.extend(errs)
+        if not is_external(row["path"]):
+            checked += 1
+    print(
+        f"token-optimizer freshness: {len(rows)} catalog rows, "
+        f"{checked} internal targets checked, {len(all_errs)} drift signal(s)"
+    )
+    for e in all_errs:
+        print(f"  FAIL  {e}")
+    return 1 if all_errs else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())