@event4u/agent-config 1.16.0 → 1.18.0

package/scripts/check_command_count_messaging.py

@@ -53,7 +53,9 @@ def canonical_counts() -> tuple[int, int, int]:
         print(f"❌  {COMMANDS_DIR.relative_to(ROOT)} not found", file=sys.stderr)
         sys.exit(1)
     total = shims = 0
-    for f in COMMANDS_DIR.glob("*.md"):
+    for f in COMMANDS_DIR.rglob("*.md"):
+        if f.name == "AGENTS.md":
+            continue
         total += 1
         m = FM_RE.match(f.read_text(encoding="utf-8"))
         fm = m.group(1) if m else ""
@@ -82,16 +84,21 @@ def main() -> int:
         # README.md
         (README, r"<strong>(\d+) Commands</strong>", active, "hero row"),
         (README, r"Browse all (\d+) active commands", active, "browse line"),
-        (README, r"\((\d+) files total ", total, "browse meta · total files"),
-        (README, r"— (\d+) are deprecation shims", shims, "browse meta · shims"),
         (README, r"\+ (\d+) native commands\)", active, "tools blurb"),
-        # AGENTS.md (`commands/  (84 files — 69 active + 15 deprecation shims)`)
-        (AGENTS, r"commands/\s+\((\d+) files —", total, "tree · total files"),
-        (AGENTS, r"files — (\d+) active", active, "tree · active"),
-        (AGENTS, r"active \+ (\d+) deprecation shims", shims, "tree · shims"),
         # docs/getting-started.md
         (GETTING_STARTED, r"Browse all (\d+) active commands", active, "browse line"),
     ]
+    # Shim-specific messaging only applies during a deprecation window.
+    # When shims == 0 the clauses are dropped from public docs entirely;
+    # re-add these patterns when a new deprecation cycle starts.
+    if shims > 0:
+        checks.extend([
+            (README, r"\((\d+) files total ", total, "browse meta · total files"),
+            (README, r"— (\d+) are deprecation shims", shims, "browse meta · shims"),
+            (AGENTS, r"commands/\s+\((\d+) files —", total, "tree · total files"),
+            (AGENTS, r"files — (\d+) active", active, "tree · active"),
+            (AGENTS, r"active \+ (\d+) deprecation shims", shims, "tree · shims"),
+        ])
 
     errors: list[str] = []
     for path, pattern, expected, label in checks:

package/scripts/check_context_paths.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+"""Context-file path & orphan checker.
+
+Validates that every `*.md` under `.agent-src.uncompressed/contexts/`:
+
+1. Lives in a locked sub-tree (or is one of six grandfathered root files).
+2. Does not collide on basename with another context file in another sub-tree.
+3. Is referenced by at least one rule, skill, command, or other context
+   (via `load_context:` frontmatter or a markdown body path mention).
+
+Contract: docs/contracts/context-paths.md
+Roadmap:  road-to-structural-optimization.md § 0.6
+
+Exit codes: 0 = clean, 1 = violations, 3 = internal error.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+CONTEXTS_ROOT = ROOT / ".agent-src.uncompressed" / "contexts"
+
+# Sub-trees that may contain context files. Update in lock-step with
+# docs/contracts/context-paths.md whenever a roadmap revision adds one.
+LOCKED_SUBTREES = (
+    "communication/rules-always",
+    "communication/rules-auto",
+    "judges",
+    "analysis",
+    "skills",
+    "chat-history",
+    "execution",
+    "authority",
+)
+
+# Files allowed to remain at the contexts root. Anything else at the root
+# fails the path check. New context files MUST live in a sub-tree.
+GRANDFATHERED_ROOT_FILES = frozenset({
+    "augment-infrastructure.md",
+    "documentation-hierarchy.md",
+    "model-recommendations.md",
+    "override-system.md",
+    "skills-and-commands.md",
+    "subagent-configuration.md",
+})
+
+# Directories whose content we scan for references to a context file.
+# `agents/roadmaps` is included because in-flight roadmap docs are
+# legitimate referrers during multi-phase rollouts — a context can land
+# in phase N while its first rule/skill referrer lands in phase N+k.
+# Without this scan dir, every newly-introduced context would orphan
+# until the consuming artefact lands, blocking phase-by-phase commits.
+REFERENCE_SCAN_DIRS = (
+    ".agent-src.uncompressed/rules",
+    ".agent-src.uncompressed/skills",
+    ".agent-src.uncompressed/commands",
+    ".agent-src.uncompressed/contexts",
+    "agents/roadmaps",
+)
+
+
+@dataclass
+class Violation:
+    file: str
+    kind: str          # "out-of-tree" | "root-not-grandfathered" | "collision" | "orphan"
+    detail: str
+
+
+def _collect_contexts(root: Path) -> list[Path]:
+    if not (root / CONTEXTS_ROOT.relative_to(ROOT)).exists():
+        return []
+    return sorted((root / CONTEXTS_ROOT.relative_to(ROOT)).rglob("*.md"))
+
+
+def _check_path(ctx: Path, contexts_root: Path) -> Violation | None:
+    rel = ctx.relative_to(contexts_root)
+    parts = rel.parts
+    if len(parts) == 1:
+        if parts[0] not in GRANDFATHERED_ROOT_FILES:
+            return Violation(
+                file=str(ctx),
+                kind="root-not-grandfathered",
+                detail=(f"new file at contexts/ root — must live in one of "
+                        f"{sorted(LOCKED_SUBTREES)} or be added to "
+                        "GRANDFATHERED_ROOT_FILES via a roadmap revision"),
+            )
+        return None
+    subtree = "/".join(parts[:-1])
+    # Allow nested matches: e.g. communication/rules-always/foo/bar.md still
+    # lives under "communication/rules-always". Direct prefix match suffices.
+    for allowed in LOCKED_SUBTREES:
+        if subtree == allowed or subtree.startswith(allowed + "/"):
+            return None
+    return Violation(
+        file=str(ctx),
+        kind="out-of-tree",
+        detail=(f"sub-tree '{subtree}' is not in LOCKED_SUBTREES — see "
+                "docs/contracts/context-paths.md to add a new sub-tree"),
+    )
+
+
+def _check_collisions(contexts: list[Path], contexts_root: Path) -> list[Violation]:
+    by_name: dict[str, list[Path]] = {}
+    for ctx in contexts:
+        by_name.setdefault(ctx.name, []).append(ctx)
+    out: list[Violation] = []
+    for name, paths in by_name.items():
+        if len(paths) <= 1:
+            continue
+        rels = sorted(str(p.relative_to(contexts_root)) for p in paths)
+        for p in paths:
+            out.append(Violation(
+                file=str(p),
+                kind="collision",
+                detail=f"basename '{name}' shared with: {', '.join(r for r in rels if r != str(p.relative_to(contexts_root)))}",
+            ))
+    return out
+
+
+def _build_reference_corpus(root: Path) -> str:
+    chunks: list[str] = []
+    for d in REFERENCE_SCAN_DIRS:
+        base = root / d
+        if not base.exists():
+            continue
+        for f in base.rglob("*.md"):
+            try:
+                chunks.append(f.read_text(encoding="utf-8"))
+            except OSError:
+                continue
+    return "\n".join(chunks)
+
+
+def _check_orphans(contexts: list[Path], corpus: str, root: Path) -> list[Violation]:
+    out: list[Violation] = []
+    for ctx in contexts:
+        rel_src = str(ctx.relative_to(root))                       # .agent-src.uncompressed/contexts/...
+        rel_short = rel_src.split("contexts/", 1)[-1]               # judges/persona-voice-rubric.md
+        candidates = (rel_src, f"contexts/{rel_short}", rel_short)
+        # Exclude self-references: drop this file's own content from the
+        # corpus check by reading the file and subtracting its substring.
+        try:
+            own_text = ctx.read_text(encoding="utf-8")
+        except OSError:
+            own_text = ""
+        external_corpus = corpus.replace(own_text, "") if own_text else corpus
+        if not any(c in external_corpus for c in candidates):
+            out.append(Violation(
+                file=str(ctx),
+                kind="orphan",
+                detail="not referenced by any rule, skill, command, or other context",
+            ))
+    return out
+
+
+def scan(root: Path) -> list[Violation]:
+    contexts_root = root / CONTEXTS_ROOT.relative_to(ROOT)
+    contexts = _collect_contexts(root)
+    violations: list[Violation] = []
+    for ctx in contexts:
+        v = _check_path(ctx, contexts_root)
+        if v:
+            violations.append(v)
+    violations.extend(_check_collisions(contexts, contexts_root))
+    corpus = _build_reference_corpus(root)
+    violations.extend(_check_orphans(contexts, corpus, root))
+    return violations
+
+
+def format_text(violations: list[Violation]) -> str:
+    if not violations:
+        return "✅  No context-path violations."
+    lines = [f"❌  Found {len(violations)} context-path violation(s):\n"]
+    for v in violations:
+        lines.append(f"  🔴 [{v.kind}] {v.file}\n      {v.detail}")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--format", choices=["text", "json"], default="text")
+    parser.add_argument("--root", type=Path, default=ROOT)
+    args = parser.parse_args()
+    try:
+        violations = scan(args.root)
+    except Exception as e:    # pragma: no cover
+        print(f"Internal error: {e}", file=sys.stderr)
+        return 3
+    if args.format == "json":
+        print(json.dumps([asdict(v) for v in violations], indent=2))
+    else:
+        print(format_text(violations))
+    return 1 if violations else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_no_roadmap_refs.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""No-roadmap-references checker.
+
+Stable artifacts (rules, skills, commands, contexts, guidelines, AGENTS.md,
+README, copilot-instructions) must NOT cite a specific roadmap file in
+`agents/roadmaps/`. Roadmap files are transient — archived, skipped, or
+deleted as work completes — and stable artifacts citing them rot.
+
+Allowed: directory mentions (`agents/roadmaps/`, `agents/roadmaps/archive/`,
+`agents/roadmaps/skipped/`). Forbidden: specific `*.md` files inside those
+directories.
+
+Contract: .agent-src.uncompressed/rules/no-roadmap-references.md
+
+Exit codes: 0 = clean, 1 = violations, 3 = internal error.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+# Stable artefact trees — every `*.md` below MUST be free of roadmap-file
+# citations. Directory mentions stay allowed (the regex below excludes them).
+STABLE_TREES = (
+    ".agent-src.uncompressed/rules",
+    ".agent-src.uncompressed/skills",
+    ".agent-src.uncompressed/commands",
+    ".agent-src.uncompressed/contexts",
+    ".agent-src.uncompressed/templates",
+    ".agent-src.uncompressed/personas",
+    "agents/contexts",
+    "docs/guidelines",
+    "docs/contracts",
+)
+
+# Stable single-file artefacts at well-known paths.
+STABLE_FILES = (
+    "AGENTS.md",
+    "README.md",
+    "copilot-instructions.md",
+    "docs/architecture.md",
+    "docs/customization.md",
+    "docs/getting-started.md",
+    "docs/catalog.md",
+)
+
+# Roadmap-file pattern: any `*.md` file under `agents/roadmaps/` at any
+# depth (including `archive/`, `skipped/`, and nested topical subfolders
+# like `agent-memory/`). Directory-only mentions (`agents/roadmaps/`
+# with trailing slash, no filename) and placeholder mentions like
+# `agents/roadmaps/<file>.md` (angle-bracket placeholder) do NOT match.
+ROADMAP_FILE_RE = re.compile(
+    r"agents/roadmaps/(?:[a-z0-9][a-z0-9_-]*/)*[a-z0-9][a-z0-9_-]*\.md",
+    re.IGNORECASE,
+)
+
+# Files that may legitimately quote forbidden patterns inside backticks for
+# documentation purposes — the rule itself, the companion CI script docs,
+# and the contract doc that names the rule.
+SELF_DOCUMENTING_ALLOWLIST = frozenset({
+    ".agent-src.uncompressed/rules/no-roadmap-references.md",
+    "docs/guidelines/agent-infra/no-roadmap-references.md",
+})
+
+
+@dataclass
+class Violation:
+    file: str
+    line: int
+    match: str
+
+
+def _scan_file(path: Path, root: Path) -> list[Violation]:
+    rel = str(path.relative_to(root))
+    if rel in SELF_DOCUMENTING_ALLOWLIST:
+        return []
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return []
+    out: list[Violation] = []
+    in_fence = False
+    for n, line in enumerate(text.splitlines(), start=1):
+        # Skip fenced code blocks — path listings inside ``` are functional
+        # constants (command contracts, runtime checks), not link rot.
+        stripped = line.lstrip()
+        if stripped.startswith("```"):
+            in_fence = not in_fence
+            continue
+        if in_fence:
+            continue
+        for m in ROADMAP_FILE_RE.finditer(line):
+            out.append(Violation(file=rel, line=n, match=m.group(0)))
+    return out
+
+
+def _collect_targets(root: Path) -> list[Path]:
+    targets: list[Path] = []
+    for d in STABLE_TREES:
+        base = root / d
+        if not base.exists():
+            continue
+        targets.extend(sorted(base.rglob("*.md")))
+    for f in STABLE_FILES:
+        p = root / f
+        if p.exists():
+            targets.append(p)
+    return targets
+
+
+def scan(root: Path) -> list[Violation]:
+    out: list[Violation] = []
+    for path in _collect_targets(root):
+        out.extend(_scan_file(path, root))
+    return out
+
+
+def format_text(violations: list[Violation]) -> str:
+    if not violations:
+        return "✅  No roadmap-file references in stable artifacts."
+    lines = [f"❌  Found {len(violations)} roadmap reference(s) in stable artifacts:\n"]
+    for v in violations:
+        lines.append(f"  🔴 {v.file}:{v.line}  →  {v.match}")
+    lines.append(
+        "\nPromote the durable conclusion to agents/contexts/ and cite that "
+        "instead. See .agent-src.uncompressed/rules/no-roadmap-references.md."
+    )
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--format", choices=["text", "json"], default="text")
+    parser.add_argument("--root", type=Path, default=ROOT)
+    args = parser.parse_args()
+    try:
+        violations = scan(args.root)
+    except Exception as e:    # pragma: no cover
+        print(f"Internal error: {e}", file=sys.stderr)
+        return 3
+    if args.format == "json":
+        print(json.dumps([asdict(v) for v in violations], indent=2))
+    else:
+        print(format_text(violations))
+    return 1 if violations else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_one_off_location.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""One-off script-location guard (Phase 0a.2 of road-to-rule-hardening).
+
+Every ``_one_off_*.py`` script under ``scripts/`` must live inside the
+archive folder ``scripts/ai_council/one_off_archive/<YYYY-MM>/``. The
+guard fails CI if a new probe lands anywhere else in the tree.
+
+Rationale: one-off council probes / phase-specific measurements are
+inherently single-purpose; their durable artefact is the council
+session under ``agents/council-sessions/``. Keeping them in the
+archive prevents the ``scripts/`` root from accumulating noise and
+makes their lifecycle visible (folder == month archived).
+
+Exit codes:
+    0 = clean
+    1 = violation (script outside the archive)
+    3 = internal error
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SCRIPTS = REPO_ROOT / "scripts"
+ARCHIVE = SCRIPTS / "ai_council" / "one_off_archive"
+ARCHIVE_MONTH_RE = re.compile(r"^\d{4}-\d{2}$")
+
+
+def find_violations() -> list[Path]:
+    """Return one-off scripts that are outside the archive folder."""
+    violations: list[Path] = []
+    for path in SCRIPTS.rglob("_one_off_*.py"):
+        if not path.is_file():
+            continue
+        # Must live under scripts/ai_council/one_off_archive/<YYYY-MM>/
+        try:
+            rel = path.relative_to(ARCHIVE)
+        except ValueError:
+            violations.append(path)
+            continue
+        # rel = "<YYYY-MM>/<name>.py"
+        parts = rel.parts
+        if len(parts) != 2 or not ARCHIVE_MONTH_RE.match(parts[0]):
+            violations.append(path)
+    return violations
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.strip().splitlines()[0])
+    parser.add_argument("--quiet", action="store_true", help="Only print on failure")
+    args = parser.parse_args()
+
+    try:
+        violations = find_violations()
+    except Exception as exc:  # pragma: no cover — defensive
+        print(f"❌  internal error: {exc}", file=sys.stderr)
+        return 3
+
+    if violations:
+        print("❌  one-off scripts outside the archive:", file=sys.stderr)
+        for path in violations:
+            rel = path.relative_to(REPO_ROOT)
+            print(f"    {rel}", file=sys.stderr)
+        print(
+            "\n  Move them under "
+            "scripts/ai_council/one_off_archive/<YYYY-MM>/ "
+            "(see that folder's README.md).",
+            file=sys.stderr,
+        )
+        return 1
+
+    if not args.quiet:
+        print("✅  all _one_off_*.py scripts are archived")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/scripts/check_phase_coupling.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Phase 6 → Phase 2B coupling guard (Phase 0.3.3).
+
+Re-runs the audit recorded in `agents/roadmaps/phase6-2b-coupling.md`
+on every CI run. Fails the build if any of the 13 Phase-2B target
+rules introduces a reference to one of the three Phase-6-owned rules
+(`chat-history-cadence`, `chat-history-ownership`,
+`chat-history-visibility`) — by rule name, `load_context:` entry, or
+body link / cite.
+
+Excluded from the coupling probe (separate infrastructure, not
+reshaped by Phase 6):
+
+- The CLI dispatcher subcommand `./agent-config chat-history:hook`
+  and any other `chat-history:*` colon-suffix command surface.
+
+Exit codes: 0 = decoupling intact, 1 = coupling detected,
+3 = internal error (target rule missing, unreadable file).
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+SRC_RULES = REPO_ROOT / ".agent-src.uncompressed" / "rules"
+COMP_RULES = REPO_ROOT / ".agent-src" / "rules"
+
+# Phase 2B priority list — see road-to-structural-optimization.md § Phase 2 → 2B.
+TARGET_RULES: tuple[str, ...] = (
+    "roadmap-progress-sync",
+    "user-interaction",
+    "augment-source-of-truth",
+    "command-suggestion-policy",
+    "artifact-engagement-recording",
+    "review-routing-awareness",
+    "autonomous-execution",
+    "docs-sync",
+    "cli-output-handling",
+    "augment-portability",
+    "ui-audit-gate",
+    "skill-quality",
+    "package-ci-checks",
+)
+
+# Phase 6 owns these three rule names. Match must be a *rule reference*,
+# not a *dispatcher reference* (chat-history:hook etc).
+PHASE6_RULES: tuple[str, ...] = (
+    "chat-history-cadence",
+    "chat-history-ownership",
+    "chat-history-visibility",
+)
+
+# Rule-reference pattern: rule name not immediately followed by `:` (which
+# would mark it as a CLI subcommand like `chat-history:hook`). Allows
+# trailing word-boundary characters typical of Markdown / YAML contexts.
+_RULE_REF_RE = re.compile(
+    r"\bchat-history-(?:cadence|ownership|visibility)\b(?!:)"
+)
+
+
+def _scan(file: Path) -> list[tuple[int, str]]:
+    """Return [(line_no, line)] of rule-reference matches in `file`."""
+    if not file.is_file():
+        return []
+    hits: list[tuple[int, str]] = []
+    for i, line in enumerate(file.read_text(encoding="utf-8").splitlines(), 1):
+        if _RULE_REF_RE.search(line):
+            hits.append((i, line.strip()))
+    return hits
+
+
+def _check_surface(label: str, base: Path) -> tuple[int, list[str]]:
+    """Scan `base` for all 13 Phase-2B targets; return (#hits, formatted lines)."""
+    if not base.is_dir():
+        return 0, [f"❌  {label} dir missing: {base}"]
+    out: list[str] = []
+    total = 0
+    for rule in TARGET_RULES:
+        path = base / f"{rule}.md"
+        if not path.is_file():
+            return 0, [f"❌  target rule missing: {path}"]
+        hits = _scan(path)
+        if not hits:
+            continue
+        total += len(hits)
+        for line_no, line in hits:
+            out.append(f"  {label}/{rule}.md:{line_no}  {line}")
+    return total, out
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="suppress the per-rule breakdown when no coupling found",
+    )
+    args = parser.parse_args()
+
+    hits_src, lines_src = _check_surface("uncompressed", SRC_RULES)
+    if any(line.startswith("❌") for line in lines_src):
+        for line in lines_src:
+            print(line, file=sys.stderr)
+        return 3
+    hits_comp, lines_comp = _check_surface("compressed", COMP_RULES)
+    if any(line.startswith("❌") for line in lines_comp):
+        for line in lines_comp:
+            print(line, file=sys.stderr)
+        return 3
+
+    total = hits_src + hits_comp
+
+    if total == 0:
+        if not args.quiet:
+            print(
+                f"✅  Phase 6 → 2B decoupling intact: 0 rule-references "
+                f"across {len(TARGET_RULES)} Phase-2B targets "
+                f"(uncompressed + compressed surfaces)."
+            )
+            print(
+                "      probe: rule names, load_context: entries, body "
+                "link/cite — dispatcher subcommand chat-history:hook "
+                "excluded by design."
+            )
+        return 0
+
+    print(
+        f"❌  Phase 6 → 2B coupling detected: {total} rule-reference(s) "
+        f"across Phase-2B targets:"
+    )
+    for line in lines_src + lines_comp:
+        print(line)
+    print(
+        "\n      Action: see agents/roadmaps/phase6-2b-coupling.md. "
+        "Either drop the new reference, migrate it to the dispatcher "
+        "(chat-history:hook), or trigger the >0-hits branch in 0.3.2 "
+        "(Phase 6 ships call-signature contract before Phase 2B "
+        "touches the coupled rule)."
+    )
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_portability.py

@@ -315,6 +315,7 @@ _TASK_FENCE_RE = re.compile(r"^\s*task\s+([a-z][a-z0-9:_-]*)\b")
 # by the task-invocation detector (but still scanned for layer 1 + 2).
 _TASK_DETECTOR_SKIP = (
     "rules/augment-portability.md",
+    "contexts/communication/rules-auto/augment-portability-mechanics.md",
 )
 
 
@@ -422,6 +423,7 @@ _CLI_INVOCATION_MAP: list[tuple[re.Pattern, str]] = [
 # own help, the portability rule that defines the mapping).
 _CLI_DETECTOR_SKIP = (
     "rules/augment-portability.md",
+    "contexts/communication/rules-auto/augment-portability-mechanics.md",
 )