@event4u/agent-config 1.14.0 → 1.16.0

package/scripts/lint_no_new_atomic_commands.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""
+Atomic-command linter for the command-collapse policy.
+
+Reads the locked verb clusters from `docs/contracts/command-clusters.md`,
+finds every command file under `.agent-src.uncompressed/commands/` that
+was **added** since `--baseline` (default: `main`), and requires each
+new file to declare either:
+
+  - `cluster: <locked-name>`   (file is a cluster entry or sub-command), or
+  - `superseded_by: <slug>`    (file is a deprecation shim).
+
+Modifications to pre-existing files are NOT flagged — only additions.
+This stops the atomic surface from growing without forcing every existing
+command into a Phase 1 cluster (most aren't in Phase 1).
+
+Exit codes: 0 = clean, 1 = violations found, 3 = internal error.
+
+Usage:
+    python3 scripts/lint_no_new_atomic_commands.py
+    python3 scripts/lint_no_new_atomic_commands.py --baseline origin/main
+    python3 scripts/lint_no_new_atomic_commands.py --all       # ignore baseline
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+COMMANDS_DIR = Path(".agent-src.uncompressed/commands")
+CLUSTER_CONTRACT = Path("docs/contracts/command-clusters.md")
+
+
+@dataclass
+class Violation:
+    file: str
+    reason: str
+
+
+def load_locked_clusters() -> set[str]:
+    """Parse the Phase 1 cluster table from the locked contract."""
+    text = (ROOT / CLUSTER_CONTRACT).read_text(encoding="utf-8")
+    # Locate the Phase 1 table; cluster names sit in backticks in column 1.
+    in_phase_1 = False
+    clusters: set[str] = set()
+    for line in text.splitlines():
+        if line.startswith("## Phase 1 clusters"):
+            in_phase_1 = True
+            continue
+        if in_phase_1 and line.startswith("## "):
+            break
+        if in_phase_1:
+            m = re.match(r"\|\s*`([a-z][a-z0-9-]*)`\s*\|", line)
+            if m:
+                clusters.add(m.group(1))
+    if not clusters:
+        print(
+            f"❌  Could not parse Phase 1 cluster table from {CLUSTER_CONTRACT}",
+            file=sys.stderr,
+        )
+        sys.exit(3)
+    return clusters
+
+
+def added_command_files(baseline: str) -> list[Path]:
+    """Files under commands/ added (status A) since baseline."""
+    try:
+        result = subprocess.run(
+            ["git", "diff", "--name-only", "--diff-filter=A",
+             f"{baseline}...HEAD", "--", str(COMMANDS_DIR)],
+            capture_output=True, text=True, cwd=ROOT, timeout=15,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired) as exc:
+        print(f"❌  git diff failed: {exc}", file=sys.stderr)
+        sys.exit(3)
+    if result.returncode != 0:
+        print(f"❌  git diff exit {result.returncode}: {result.stderr}",
+              file=sys.stderr)
+        sys.exit(3)
+    files = [Path(p) for p in result.stdout.splitlines()
+             if p.endswith(".md") and p != ""]
+    # Also include untracked (newly added, uncommitted) files.
+    try:
+        wt = subprocess.run(
+            ["git", "status", "--porcelain", "--", str(COMMANDS_DIR)],
+            capture_output=True, text=True, cwd=ROOT, timeout=10,
+        )
+        for line in wt.stdout.splitlines():
+            if len(line) < 4:
+                continue
+            status = line[:2]
+            if status.strip() not in ("A", "??", "AM"):
+                continue
+            path = line[3:].strip().split(" -> ")[-1]
+            if path.endswith(".md"):
+                p = Path(path)
+                if p not in files:
+                    files.append(p)
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        pass
+    return files
+
+
+def all_command_files() -> list[Path]:
+    return sorted((ROOT / COMMANDS_DIR).glob("*.md"))
+
+
+def parse_frontmatter(path: Path) -> dict[str, str]:
+    text = path.read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        return {}
+    end = text.find("\n---", 3)
+    if end == -1:
+        return {}
+    fm: dict[str, str] = {}
+    for line in text[3:end].splitlines():
+        if ":" in line:
+            k, _, v = line.partition(":")
+            fm[k.strip()] = v.strip()
+    return fm
+
+
+def check_file(path: Path, clusters: set[str]) -> Violation | None:
+    abs_path = path if path.is_absolute() else ROOT / path
+    if not abs_path.exists():
+        return None  # deleted file, nothing to check
+    fm = parse_frontmatter(abs_path)
+    if "superseded_by" in fm:
+        return None  # shim — exempt
+    cluster = fm.get("cluster")
+    if not cluster:
+        return Violation(str(path),
+                         "missing `cluster:` frontmatter "
+                         f"(allowed: {sorted(clusters)})")
+    if cluster not in clusters:
+        return Violation(str(path),
+                         f"`cluster: {cluster}` is not a locked cluster "
+                         f"(allowed: {sorted(clusters)})")
+    return None
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--baseline", default="main",
+                    help="git ref to diff against (default: main)")
+    ap.add_argument("--all", action="store_true",
+                    help="check every command file, not just changed ones")
+    args = ap.parse_args()
+
+    clusters = load_locked_clusters()
+    targets = (all_command_files() if args.all
+               else added_command_files(args.baseline))
+    if not targets:
+        print(f"✅  No new commands added under {COMMANDS_DIR} "
+              f"(baseline: {args.baseline}).")
+        return 0
+
+    violations = [v for v in (check_file(p, clusters) for p in targets)
+                  if v is not None]
+    if violations:
+        print(f"❌  {len(violations)} newly-added atomic command(s) violate "
+              f"the command-cluster policy:")
+        for v in violations:
+            print(f"  • {v.file} — {v.reason}")
+        print(f"\nSee docs/contracts/command-clusters.md for the locked "
+              f"cluster names and frontmatter contract.")
+        return 1
+    print(f"✅  {len(targets)} newly-added command(s) all declare a valid "
+          f"`cluster:` (or `superseded_by:`).")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_rule_interactions.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""Lint docs/contracts/rule-interactions.yml.
+
+Validates:
+  - Schema (required fields per pair)
+  - All rule slugs in `rules:` exist as `.agent-src.uncompressed/rules/<slug>.md`
+  - Every pair references rules listed in the top-level `rules:` block
+  - `relation` is one of the allowed values
+  - All `evidence:` entries point at real files (anchors are advisory, not checked)
+  - Pair `id`s are unique
+  - The anchor pair from `road-to-post-pr29-optimize.md` Phase 2 is present:
+    `non-destructive-by-default` × {autonomous-execution, scope-control,
+    commit-policy, ask-when-uncertain, verify-before-complete}.
+
+Exits non-zero on any failure. Used in CI via Taskfile target
+`lint-rule-interactions`.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import yaml
+
+ROOT = Path(__file__).resolve().parent.parent
+MATRIX = ROOT / "docs" / "contracts" / "rule-interactions.yml"
+RULES_DIR = ROOT / ".agent-src.uncompressed" / "rules"
+
+ALLOWED_RELATIONS = {
+    "overrides",
+    "narrows",
+    "defers_to",
+    "restates",
+    "gates",
+    "complements",
+}
+
+REQUIRED_PAIR_FIELDS = {"id", "rules", "relation", "conflict", "resolution", "evidence"}
+
+ANCHOR_PARTNERS = {
+    "autonomous-execution",
+    "scope-control",
+    "commit-policy",
+    "ask-when-uncertain",
+    "verify-before-complete",
+}
+ANCHOR_RULE = "non-destructive-by-default"
+
+
+def fail(errors: list[str]) -> None:
+    print(f"❌  rule-interactions.yml — {len(errors)} issue(s):")
+    for e in errors:
+        print(f"  • {e}")
+    sys.exit(1)
+
+
+def main() -> int:
+    if not MATRIX.exists():
+        fail([f"{MATRIX.relative_to(ROOT)} is missing"])
+
+    data = yaml.safe_load(MATRIX.read_text())
+    errors: list[str] = []
+
+    if not isinstance(data, dict):
+        fail(["top-level YAML must be a mapping"])
+
+    if data.get("version") != 1:
+        errors.append("version must be 1")
+
+    declared_rules = data.get("rules") or []
+    if not isinstance(declared_rules, list) or not declared_rules:
+        errors.append("`rules:` must be a non-empty list of slugs")
+
+    for slug in declared_rules:
+        if not isinstance(slug, str):
+            errors.append(f"rule slug not a string: {slug!r}")
+            continue
+        rule_path = RULES_DIR / f"{slug}.md"
+        if not rule_path.exists():
+            errors.append(f"rule slug `{slug}` has no file at {rule_path.relative_to(ROOT)}")
+
+    pairs = data.get("pairs") or []
+    if not isinstance(pairs, list) or not pairs:
+        errors.append("`pairs:` must be a non-empty list")
+
+    seen_ids: set[str] = set()
+    declared_set = set(declared_rules) if isinstance(declared_rules, list) else set()
+    anchor_partners_seen: set[str] = set()
+
+    for idx, pair in enumerate(pairs):
+        if not isinstance(pair, dict):
+            errors.append(f"pair[{idx}] is not a mapping")
+            continue
+        missing = REQUIRED_PAIR_FIELDS - set(pair)
+        if missing:
+            errors.append(f"pair[{idx}] missing fields: {sorted(missing)}")
+            continue
+
+        pid = pair["id"]
+        if pid in seen_ids:
+            errors.append(f"duplicate pair id: {pid}")
+        seen_ids.add(pid)
+
+        rules_pair = pair["rules"]
+        if not (isinstance(rules_pair, list) and len(rules_pair) == 2):
+            errors.append(f"pair `{pid}` rules must be a 2-element list")
+            continue
+        for r in rules_pair:
+            if r not in declared_set:
+                errors.append(f"pair `{pid}` references undeclared rule `{r}`")
+
+        if pair["relation"] not in ALLOWED_RELATIONS:
+            errors.append(
+                f"pair `{pid}` relation `{pair['relation']}` not in {sorted(ALLOWED_RELATIONS)}"
+            )
+
+        evidence = pair.get("evidence") or []
+        if not isinstance(evidence, list) or not evidence:
+            errors.append(f"pair `{pid}` evidence must be a non-empty list")
+        for citation in evidence:
+            if not isinstance(citation, str):
+                errors.append(f"pair `{pid}` evidence item not a string: {citation!r}")
+                continue
+            file_part = citation.split("#", 1)[0]
+            if not (ROOT / file_part).exists():
+                errors.append(f"pair `{pid}` evidence path does not exist: {file_part}")
+
+        # Anchor coverage check
+        if ANCHOR_RULE in rules_pair:
+            partner = next((r for r in rules_pair if r != ANCHOR_RULE), None)
+            if partner in ANCHOR_PARTNERS:
+                anchor_partners_seen.add(partner)
+
+    missing_anchors = ANCHOR_PARTNERS - anchor_partners_seen
+    if missing_anchors:
+        errors.append(
+            f"anchor pairs missing for `{ANCHOR_RULE}` × {sorted(missing_anchors)} "
+            "(required by road-to-post-pr29-optimize.md P2.2)"
+        )
+
+    if errors:
+        fail(errors)
+
+    print(f"✅  rule-interactions.yml clean — {len(declared_rules)} rules, {len(pairs)} pairs.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/memory_lookup.py

@@ -246,7 +246,7 @@ def _apply_conflict_rule(
 # says retrieval should route through `@event4u/agent-memory`. The package
 # CLI is purely **semantic** (`memory retrieve <query> --type T …`); the
 # shared `retrieve(types, keys, …)` API is **key-based**. The hybrid
-# resolution agreed in `agents/contexts/agent-memory-contract.md` synthesises
+# resolution agreed in `docs/contracts/agent-memory-contract.md` synthesises
 # `keys` into a single natural-language query for the package call, while
 # the file fallback continues to do glob/substring matching on the same
 # keys. Both legs land in the same `Hit` shape so the conflict rule can