@event4u/agent-config 1.15.0 → 1.17.0

package/scripts/check_command_count_messaging.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""
+Command-count messaging gate (regression guard for road-to-pr-34-followups 1.2).
+
+Public surfaces (README.md, AGENTS.md, docs/getting-started.md) advertise
+the size of the command catalog. PR #34 collapses atomic commands into
+clusters via deprecation shims — the externally meaningful number is the
+**active** command count (non-shim files), not the raw file count. This
+gate sources canonical counts from `.agent-src.uncompressed/commands/`
+frontmatter and fails when any documented number drifts from those.
+
+Canonical counts:
+    total   = number of *.md files under .agent-src.uncompressed/commands/
+    shims   = files whose frontmatter declares `superseded_by:`
+    active  = total - shims
+
+Patterns checked (per file):
+
+    README.md
+      hero row     "<strong>{N} Commands</strong>"            → active
+      browse line  "Browse all {N} active commands"           → active
+      browse meta  "{N} files total"                          → total
+      browse meta  "{N} are deprecation shims"                → shims
+      tools blurb  "{N} native commands"                      → active
+
+    AGENTS.md
+      tree         "commands/  ({N} files — {A} active + {S} deprecation shims)"
+
+    docs/getting-started.md
+      browse line  "Browse all {N} active commands"           → active
+
+Exit codes: 0 = clean, 1 = drift detected.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+COMMANDS_DIR = ROOT / ".agent-src.uncompressed" / "commands"
+README = ROOT / "README.md"
+AGENTS = ROOT / "AGENTS.md"
+GETTING_STARTED = ROOT / "docs" / "getting-started.md"
+
+FM_RE = re.compile(r"^---\s*\n(.*?)\n---", re.DOTALL)
+SUPERSEDED_RE = re.compile(r"^superseded_by:\s*\S", re.MULTILINE)
+
+
+def canonical_counts() -> tuple[int, int, int]:
+    if not COMMANDS_DIR.is_dir():
+        print(f"❌  {COMMANDS_DIR.relative_to(ROOT)} not found", file=sys.stderr)
+        sys.exit(1)
+    total = shims = 0
+    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 ""
+        if SUPERSEDED_RE.search(fm):
+            shims += 1
+    return total, shims, total - shims
+
+
+def _check(path: Path, pattern: str, expected: int, label: str) -> str | None:
+    if not path.exists():
+        return f"missing file: {path.relative_to(ROOT)}"
+    m = re.search(pattern, path.read_text(encoding="utf-8"))
+    if not m:
+        return f"{path.relative_to(ROOT)}: pattern not found for `{label}` — /{pattern}/"
+    found = int(m.group(1))
+    if found != expected:
+        return f"{path.relative_to(ROOT)}: `{label}` says {found}, expected {expected}"
+    return None
+
+
+def main() -> int:
+    total, shims, active = canonical_counts()
+    print(f"Canonical counts: {total} files · {shims} shims · {active} active")
+
+    checks = [
+        # README.md
+        (README, r"<strong>(\d+) Commands</strong>", active, "hero row"),
+        (README, r"Browse all (\d+) active commands", active, "browse line"),
+        (README, r"\+ (\d+) native commands\)", active, "tools blurb"),
+        # 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:
+        err = _check(path, pattern, expected, label)
+        if err:
+            errors.append(err)
+
+    if not errors:
+        print("✅  All command-count messaging in sync with registry.")
+        return 0
+
+    print(f"❌  Command-count messaging drift — {len(errors)} mismatch(es):")
+    for e in errors:
+        print(f"    {e}")
+    print(
+        "\nFix: update the documented numbers above, or run "
+        "`task check-command-count` after editing."
+    )
+    print(
+        "Why this gate exists: see `agents/roadmaps/road-to-pr-34-followups.md` § 1.2."
+    )
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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