@event4u/agent-config 1.20.0 → 1.21.0

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

package/scripts/compile_router.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Compile rule frontmatter into ``router.json``.
+
+Reads ``.agent-src.uncompressed/rules/*.md``; produces deterministic JSON
+mapping kernel + tier-1 + tier-2 rules to their triggers and routed
+artifacts, per ``docs/contracts/rule-router.md``.
+
+Stdlib-only, deterministic (sorted keys + sorted lists), idempotent.
+Wired into ``task generate-tools`` after the compress step.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+RULES_DIR = ROOT / ".agent-src.uncompressed" / "rules"
+OUT_PATH = ROOT / "router.json"
+SCHEMA_VERSION = 1
+
+# Maps legacy tier values to the router-canonical names. See
+# docs/contracts/rule-router.md § Backward compatibility.
+LEGACY_TIER_MAP = {
+    "1": "tier-1",
+    "2": "tier-2",
+    "2a": "tier-2",
+    "3": "tier-1",
+    "mechanical-already": "tier-1",
+    "kernel": "kernel",
+    "tier-1": "tier-1",
+    "tier-2": "tier-2",
+}
+
+ALLOWED_TIERS = {"kernel", "tier-1", "tier-2"}
+ALLOWED_PROFILES = {"minimal", "balanced", "full"}
+ALLOWED_TRIGGER_KEYS = {"keyword", "phrase", "intent", "file_pattern",
+                        "path_prefix", "command"}
+
+
+def _parse_frontmatter(text: str) -> dict:
+    if not text.startswith("---\n"):
+        return {}
+    end = text.find("\n---", 4)
+    if end < 0:
+        return {}
+    block = text[4:end]
+    try:
+        import yaml  # type: ignore
+        data = yaml.safe_load(block) or {}
+        return data if isinstance(data, dict) else {}
+    except ImportError:
+        return _parse_frontmatter_minimal(block)
+
+
+def _parse_frontmatter_minimal(block: str) -> dict:
+    """Minimal YAML parser fallback (flat scalars + simple lists)."""
+    out: dict = {}
+    cur_key = None
+    for raw in block.splitlines():
+        line = raw.rstrip()
+        if not line or line.lstrip().startswith("#"):
+            continue
+        if line.startswith("  - ") and cur_key:
+            out.setdefault(cur_key, []).append(line[4:].strip())
+        elif ":" in line and not line.startswith(" "):
+            k, _, v = line.partition(":")
+            cur_key = k.strip()
+            v = v.strip()
+            if v in ("", "[]"):
+                out[cur_key] = [] if v == "[]" else None
+            else:
+                out[cur_key] = v.strip('"').strip("'")
+    return out
+
+
+def _resolve_tier(rule_type: str, raw_tier: str) -> str:
+    if rule_type == "always":
+        return "kernel"
+    return LEGACY_TIER_MAP.get(str(raw_tier), "tier-2")
+
+
+def _normalize_trigger(item) -> dict | None:
+    if not isinstance(item, dict):
+        return None
+    keys = [k for k in item if k in ALLOWED_TRIGGER_KEYS]
+    if len(keys) != 1:
+        return None
+    return {keys[0]: str(item[keys[0]])}
+
+
+def _collect(rules_dir: Path) -> dict:
+    kernel: list[str] = []
+    tiered: dict[str, list[dict]] = {"tier-1": [], "tier-2": []}
+    for path in sorted(rules_dir.glob("*.md")):
+        fm = _parse_frontmatter(path.read_text(encoding="utf-8"))
+        if not fm:
+            continue
+        rule_id = path.stem
+        rule_type = str(fm.get("type", "auto"))
+        tier = _resolve_tier(rule_type, fm.get("tier", ""))
+        if tier not in ALLOWED_TIERS:
+            continue
+        if tier == "kernel":
+            kernel.append(rule_id)
+            continue
+        triggers_raw = fm.get("triggers") or []
+        triggers = [t for t in (_normalize_trigger(x) for x in triggers_raw) if t]
+        routes_to = sorted(str(x) for x in (fm.get("routes_to") or []))
+        entry = {"id": rule_id, "triggers": triggers, "routes_to": routes_to}
+        tiered[tier].append(entry)
+    for k in tiered:
+        tiered[k].sort(key=lambda x: x["id"])
+    return {"kernel": sorted(kernel), **{k.replace("-", "_"): v for k, v in tiered.items()}}
+
+
+def build() -> dict:
+    collected = _collect(RULES_DIR)
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "kernel": collected["kernel"],
+        "tier_1": collected["tier_1"],
+        "tier_2": collected["tier_2"],
+        "profiles": {
+            "minimal":  ["__kernel__"],
+            "balanced": ["__kernel__", "__tier_1__"],
+            "full":     ["__kernel__", "__tier_1__", "__tier_2__"],
+        },
+    }
+
+
+def main(argv: list[str]) -> int:
+    out = build()
+    text = json.dumps(out, indent=2, sort_keys=False) + "\n"
+    if "--check" in argv:
+        if not OUT_PATH.exists() or OUT_PATH.read_text(encoding="utf-8") != text:
+            print("router.json out of date — run scripts/compile_router.py", file=sys.stderr)
+            return 1
+        print("✅  router.json is up to date")
+        return 0
+    OUT_PATH.write_text(text, encoding="utf-8")
+    counts = (len(out["kernel"]), len(out["tier_1"]), len(out["tier_2"]))
+    print(f"✅  router.json — kernel={counts[0]}  tier-1={counts[1]}  tier-2={counts[2]}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))