@event4u/agent-config 1.19.0 → 1.21.0

package/scripts/measure_rule_budget.py

@@ -0,0 +1,314 @@
+#!/usr/bin/env python3
+"""Measure rule-bucket char counts (kernel + auto) for the rule-kernel roadmap.
+
+Source of truth: `.agent-src.uncompressed/rules/*.md`. Frontmatter (YAML
+between two `---` lines at file start) is stripped before counting; only
+the rule body counts toward the bucket.
+
+Buckets follow the existing frontmatter `type:` field:
+- `always` rules → always-bucket (today's kernel proxy).
+- `auto` rules → auto-bucket.
+
+Output:
+- Default: stdout table (per-rule rows, top-5 oversize, totals).
+- `--json`: deterministic JSON (sorted keys, sorted lists).
+
+Acceptance per `road-to-kernel-and-router.md` P1.1: re-runnable,
+deterministic, stdlib-only, no network.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import json
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+RULES_DIR = REPO_ROOT / ".agent-src.uncompressed" / "rules"
+OVERRIDES_FILE = REPO_ROOT / "docs" / "contracts" / "iron-law-overrides.txt"
+TREND_FILE = REPO_ROOT / "agents" / ".rule-budget-history.jsonl"
+
+# Council R2 amendments (2026-05-06) — see docs/contracts/kernel-membership.md § 5.1.
+# Per-rule cap raised 1.5k → 2.5k; warning band raised 1.2k → 2.0k.
+# ADR-002 (2026-05-06) — KERNEL_HARD raised 25k → 26k after empirical r_actual=0.795
+# vs r_projected=0.712; see docs/decisions/ADR-002-kernel-bucket-overrides.md.
+KERNEL_HARD = 26_000
+KERNEL_TARGET = 20_000
+PER_RULE_HARD = 2_500
+PER_RULE_TARGET = 2_000
+PER_RULE_OVERRIDE_CEILING = 4_000  # Iron-Law-override ADR ceiling.
+
+# Locked kernel set — docs/contracts/kernel-membership.md § 4.
+# This is the *kernel* (P1.3 lock), not "every always-rule". After P4 the
+# `type:` frontmatter no longer maps 1:1 to kernel; the kernel is this set.
+KERNEL_RULES: frozenset[str] = frozenset(
+    {
+        "agent-authority",
+        "ask-when-uncertain",
+        "commit-policy",
+        "direct-answers",
+        "language-and-tone",
+        "no-cheap-questions",
+        "non-destructive-by-default",
+        "scope-control",
+        "verify-before-complete",
+    }
+)
+
+
+def strip_frontmatter(text: str) -> tuple[str, dict[str, str]]:
+    """Strip leading YAML frontmatter and return (body, fields).
+
+    Minimal parser — handles `key: "value"` / `key: value` only. No nested
+    structures, no lists. Sufficient for the rule frontmatter contract.
+    """
+    if not text.startswith("---\n"):
+        return text, {}
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return text, {}
+    raw = text[4:end]
+    body = text[end + 5 :]
+    fields: dict[str, str] = {}
+    for line in raw.splitlines():
+        if ":" not in line or line.startswith("#"):
+            continue
+        key, _, val = line.partition(":")
+        fields[key.strip()] = val.strip().strip('"').strip("'")
+    return body, fields
+
+
+def measure_rule(path: Path) -> dict[str, object]:
+    text = path.read_text(encoding="utf-8")
+    body, fields = strip_frontmatter(text)
+    return {
+        "id": path.stem,
+        "type": fields.get("type", "auto"),
+        "tier": fields.get("tier", ""),
+        "chars": len(body),
+        "lines": body.count("\n"),
+    }
+
+
+def collect() -> list[dict[str, object]]:
+    rules = [measure_rule(p) for p in sorted(RULES_DIR.glob("*.md"))]
+    return rules
+
+
+def load_overrides() -> set[str]:
+    """Read iron-law-override allowlist (one rule-id per line, '#' comments)."""
+    if not OVERRIDES_FILE.exists():
+        return set()
+    out: set[str] = set()
+    for line in OVERRIDES_FILE.read_text(encoding="utf-8").splitlines():
+        s = line.split("#", 1)[0].strip()
+        if s:
+            out.add(s)
+    return out
+
+
+def aggregate(rules: list[dict[str, object]]) -> dict[str, object]:
+    always = [r for r in rules if r["type"] == "always"]
+    auto = [r for r in rules if r["type"] == "auto"]
+    kernel = [r for r in rules if r["id"] in KERNEL_RULES]
+    total_chars = sum(int(r["chars"]) for r in rules)
+    return {
+        "always_count": len(always),
+        "auto_count": len(auto),
+        "kernel_count": len(kernel),
+        "rule_count": len(rules),
+        "always_chars": sum(int(r["chars"]) for r in always),
+        "auto_chars": sum(int(r["chars"]) for r in auto),
+        "kernel_chars": sum(int(r["chars"]) for r in kernel),
+        "total_chars": total_chars,
+        "kernel_hard": KERNEL_HARD,
+        "kernel_target": KERNEL_TARGET,
+        "per_rule_hard": PER_RULE_HARD,
+        "per_rule_target": PER_RULE_TARGET,
+        "per_rule_override_ceiling": PER_RULE_OVERRIDE_CEILING,
+        "oversize_rules": sorted(
+            (r for r in rules if int(r["chars"]) > PER_RULE_HARD),
+            key=lambda r: (-int(r["chars"]), r["id"]),
+        ),
+        "top5_largest": sorted(rules, key=lambda r: (-int(r["chars"]), r["id"]))[:5],
+    }
+
+
+def render_table(rules: list[dict[str, object]], agg: dict[str, object]) -> str:
+    lines: list[str] = []
+    lines.append("Rule budget — source: .agent-src.uncompressed/rules/")
+    lines.append("")
+    lines.append(f"{'id':<40} {'type':<7} {'tier':<5} {'chars':>7}")
+    lines.append("-" * 62)
+    for r in sorted(rules, key=lambda r: r["id"]):
+        flag = "!" if int(r["chars"]) > PER_RULE_HARD else (
+            "~" if int(r["chars"]) > PER_RULE_TARGET else " "
+        )
+        lines.append(
+            f"{r['id']:<40} {r['type']:<7} {str(r['tier']):<5} {r['chars']:>6}{flag}"
+        )
+    lines.append("")
+    lines.append(
+        f"kernel-bucket: {agg['kernel_chars']:>6} chars across {agg['kernel_count']} rules "
+        f"(target ≤ {KERNEL_TARGET}, hard ≤ {KERNEL_HARD})"
+    )
+    lines.append(
+        f"always-bucket: {agg['always_chars']:>6} chars across {agg['always_count']} rules "
+        f"(legacy frontmatter `type: always`)"
+    )
+    lines.append(
+        f"  auto-bucket: {agg['auto_chars']:>6} chars across {agg['auto_count']} rules"
+    )
+    lines.append(f"        total: {agg['total_chars']:>6} chars across {agg['rule_count']} rules")
+    lines.append("")
+    lines.append(f"top-5 largest:")
+    for r in agg["top5_largest"]:  # type: ignore[index]
+        lines.append(f"  {r['chars']:>5}  {r['id']}  ({r['type']})")
+    over = agg["oversize_rules"]  # type: ignore[index]
+    if over:
+        lines.append("")
+        lines.append(f"OVER per-rule hard cap ({PER_RULE_HARD} chars): {len(over)} rule(s)")
+    return "\n".join(lines)
+
+
+def kernel_budget_check(
+    rules: list[dict[str, object]], agg: dict[str, object], overrides: set[str]
+) -> tuple[int, list[str]]:
+    """Enforce kernel budget per Council R2 amendments.
+
+    Returns (exit_code, report_lines). Exit 0 = pass, 1 = breach.
+
+    Checks:
+    - Kernel-bucket sum ≤ KERNEL_HARD (25k).
+    - Each kernel rule ≤ PER_RULE_HARD (2.5k), unless listed in
+      `iron-law-overrides.txt` (then ≤ PER_RULE_OVERRIDE_CEILING = 4k).
+    - Missing kernel rules (rule-id in KERNEL_RULES but no file) → fail.
+    """
+    out: list[str] = []
+    fails: list[str] = []
+
+    kernel_rules = [r for r in rules if r["id"] in KERNEL_RULES]
+    found_ids = {str(r["id"]) for r in kernel_rules}
+    missing = sorted(KERNEL_RULES - found_ids)
+    for mid in missing:
+        fails.append(f"missing kernel rule: {mid} (declared in KERNEL_RULES, no file found)")
+
+    bucket = int(agg["kernel_chars"])
+    out.append(
+        f"kernel-bucket: {bucket} / {KERNEL_HARD} chars "
+        f"({agg['kernel_count']} rules)"
+    )
+    if bucket > KERNEL_HARD:
+        fails.append(f"kernel-bucket {bucket} > hard cap {KERNEL_HARD}")
+
+    out.append(
+        f"per-rule cap: {PER_RULE_HARD} (override ceiling {PER_RULE_OVERRIDE_CEILING} "
+        f"with ADR; allowlist {OVERRIDES_FILE.relative_to(REPO_ROOT)})"
+    )
+    out.append("")
+    out.append(f"{'id':<28} {'chars':>6} {'cap':>6} {'status':<24}")
+    out.append("-" * 68)
+    for r in sorted(kernel_rules, key=lambda r: r["id"]):
+        rid = str(r["id"])
+        chars = int(r["chars"])
+        if rid in overrides:
+            cap = PER_RULE_OVERRIDE_CEILING
+            label = "OK (override)"
+            if chars > cap:
+                label = f"FAIL (>{cap} ceiling)"
+                fails.append(f"{rid} {chars} > override ceiling {cap}")
+        else:
+            cap = PER_RULE_HARD
+            if chars > cap:
+                label = "FAIL (needs override ADR)"
+                fails.append(f"{rid} {chars} > per-rule hard cap {cap} (no override)")
+            elif chars > PER_RULE_TARGET:
+                label = "warn (> target)"
+            else:
+                label = "OK"
+        out.append(f"{rid:<28} {chars:>6} {cap:>6} {label:<24}")
+
+    out.append("")
+    if fails:
+        out.append(f"❌  kernel budget check: {len(fails)} breach(es)")
+        for f in fails:
+            out.append(f"  - {f}")
+        return 1, out
+    out.append(f"✅  kernel budget check: pass")
+    return 0, out
+
+
+def trend_append(agg: dict[str, object]) -> tuple[int, str]:
+    """Append a daily snapshot to agents/.rule-budget-history.jsonl.
+
+    Idempotent per UTC day: if today's date already has a row, the file
+    is not modified. Snapshot fields: date, kernel_chars, auto_chars,
+    rule_count, total_chars. Read by `roadmap:progress` for the Kernel
+    track per `road-to-kernel-and-router.md` P5.3.
+    """
+    today = _dt.datetime.now(_dt.timezone.utc).date().isoformat()
+    snapshot = {
+        "date": today,
+        "kernel_chars": int(agg["kernel_chars"]),
+        "auto_chars": int(agg["auto_chars"]),
+        "rule_count": int(agg["rule_count"]),
+        "total_chars": int(agg["total_chars"]),
+    }
+    TREND_FILE.parent.mkdir(parents=True, exist_ok=True)
+    if TREND_FILE.exists():
+        for line in TREND_FILE.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                row = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if row.get("date") == today:
+                return 0, f"trend: {today} already recorded — no-op"
+    with TREND_FILE.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(snapshot, sort_keys=True) + "\n")
+    return 0, f"trend: appended {today} → {TREND_FILE.relative_to(REPO_ROOT)}"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--json", action="store_true", help="emit JSON instead of a table")
+    parser.add_argument(
+        "--kernel-budget-check",
+        action="store_true",
+        help="enforce Council R2 kernel-bucket + per-rule caps; exit 1 on breach",
+    )
+    parser.add_argument(
+        "--trend-append",
+        action="store_true",
+        help="append today's snapshot to agents/.rule-budget-history.jsonl (idempotent per UTC day)",
+    )
+    args = parser.parse_args(argv)
+
+    rules = collect()
+    agg = aggregate(rules)
+
+    if args.kernel_budget_check:
+        overrides = load_overrides()
+        code, report = kernel_budget_check(rules, agg, overrides)
+        print("\n".join(report))
+        return code
+
+    if args.trend_append:
+        code, msg = trend_append(agg)
+        print(msg)
+        return code
+
+    if args.json:
+        payload = {"rules": sorted(rules, key=lambda r: r["id"]), "summary": agg}
+        print(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        print(render_table(rules, agg))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/prototype_lint_contradictions.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""
+Prototype contradiction linter (P1.1 of road-to-package-optimization).
+
+Hard acceptance: must flag >=3 real cross-artifact contradictions in this
+repo within 5 s wall-clock and < $0.01 cost (deterministic, no LLM calls).
+On failure, the roadmap closes with the null result documented; no
+Phase 2 work begins.
+
+Heuristic family — three deterministic checks across rules, skills,
+commands, and contexts:
+
+1. Routing mismatch: rule frontmatter `routes_to: [skill:foo]` but the
+   target artifact does not exist or has no matching trigger.
+2. Trigger collision with imperative conflict: two artifacts share a
+   trigger keyword AND one body contains an `ALWAYS X` Iron Law while
+   the other contains `NEVER X` (or `MUST` vs `MUST NOT`) on the same
+   verb-object.
+3. Catalog drift: a token-optimizer-style catalog row cites a path that
+   does not exist (subset of #1, broader scope than the freshness gate).
+
+Stdlib only. JSON to stdout. Exit 0 = clean / Exit 1 = contradictions found.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+import time
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+SRC = REPO / ".agent-src.uncompressed"
+
+ARTIFACT_DIRS = {
+    "rule": SRC / "rules",
+    "skill": SRC / "skills",
+    "command": SRC / "commands",
+    "context": SRC / "contexts",
+}
+
+FM_RE = re.compile(r"^---\n(.*?)\n---\n", re.DOTALL)
+ALWAYS_RE = re.compile(r"^\s*(ALWAYS|MUST)\s+([A-Z][^.\n]{2,80})", re.MULTILINE)
+NEVER_RE = re.compile(r"^\s*(NEVER|MUST NOT|DO NOT)\s+([A-Z][^.\n]{2,80})", re.MULTILINE)
+
+
+def parse_artifact(path: Path, kind: str) -> dict:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    fm: dict = {}
+    m = FM_RE.match(text)
+    body = text
+    if m:
+        body = text[m.end():]
+        for line in m.group(1).splitlines():
+            if ":" in line and not line.startswith(" "):
+                k, _, v = line.partition(":")
+                fm[k.strip()] = v.strip()
+    triggers = re.findall(r"`([a-z][a-z0-9_-]+)`", fm.get("description", ""))
+    routes = re.findall(r"(skill|rule|command):([a-z0-9_-]+)", fm.get("routes_to", ""))
+    always = [m.group(2).strip() for m in ALWAYS_RE.finditer(body)]
+    never = [m.group(2).strip() for m in NEVER_RE.finditer(body)]
+    return {
+        "kind": kind,
+        "path": str(path.relative_to(REPO)),
+        "id": path.stem if path.name != "SKILL.md" else path.parent.name,
+        "triggers": set(triggers),
+        "routes": routes,
+        "always": always,
+        "never": never,
+    }
+
+
+def collect() -> list[dict]:
+    out: list[dict] = []
+    for kind, root in ARTIFACT_DIRS.items():
+        if not root.exists():
+            continue
+        for p in root.rglob("*.md"):
+            if p.name in {"README.md", "INDEX.md"}:
+                continue
+            out.append(parse_artifact(p, kind))
+    return out
+
+
+def check_routing(arts: list[dict]) -> list[dict]:
+    by_id = {(a["kind"], a["id"]): a for a in arts}
+    flags: list[dict] = []
+    for a in arts:
+        for tgt_kind, tgt_id in a["routes"]:
+            if (tgt_kind, tgt_id) not in by_id:
+                flags.append({
+                    "type": "routing_mismatch",
+                    "artifact_a": a["path"],
+                    "artifact_b": f"{tgt_kind}:{tgt_id} (missing)",
+                    "evidence": f"{a['id']} routes_to {tgt_kind}:{tgt_id}, target not found",
+                })
+    return flags
+
+
+def normalize_verb(s: str) -> str:
+    return re.sub(r"[^a-z ]+", "", s.lower()).split(" ", 1)[0] if s else ""
+
+
+def check_imperative_conflict(arts: list[dict]) -> list[dict]:
+    flags: list[dict] = []
+    by_trigger: dict[str, list[dict]] = {}
+    for a in arts:
+        for t in a["triggers"]:
+            by_trigger.setdefault(t, []).append(a)
+    for trigger, group in by_trigger.items():
+        if len(group) < 2:
+            continue
+        for i, a in enumerate(group):
+            for b in group[i + 1:]:
+                a_verbs = {normalize_verb(s) for s in a["always"]}
+                b_verbs = {normalize_verb(s) for s in b["never"]}
+                conflict = a_verbs & b_verbs - {""}
+                if conflict:
+                    flags.append({
+                        "type": "imperative_conflict",
+                        "artifact_a": a["path"],
+                        "artifact_b": b["path"],
+                        "evidence": f"shared trigger '{trigger}', a says ALWAYS {sorted(conflict)}, b says NEVER {sorted(conflict)}",
+                    })
+    return flags
+
+
+def main() -> int:
+    t0 = time.monotonic()
+    arts = collect()
+    flags = check_routing(arts) + check_imperative_conflict(arts)
+    elapsed = time.monotonic() - t0
+    report = {
+        "artifacts_scanned": len(arts),
+        "elapsed_seconds": round(elapsed, 3),
+        "flags": flags,
+        "acceptance": {
+            "min_flags": 3,
+            "max_seconds": 5.0,
+            "passed": len(flags) >= 3 and elapsed < 5.0,
+        },
+    }
+    json.dump(report, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0 if not flags else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/redact_hook_capture.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Redact captured hook payloads for the verified-platforms roadmap.
+
+Reads JSON capture files written by ``dispatch_hook.py`` (when
+``AGENT_HOOK_CAPTURE_DIR`` is set) and produces a redacted version
+suitable for pasting into
+``agents/roadmaps/road-to-verified-chat-history-platforms.md``.
+
+Redaction policy (per the roadmap's Capture-and-redact protocol):
+
+- Replace string values at known user-content paths with
+  ``<REDACTED>``. Default field allowlist mirrors the fallback list
+  in ``scripts/chat_history.py::_extract_hook_text`` plus Augment's
+  nested ``conversation.*`` shape.
+- Preserve envelope keys (``hook_event_name``, ``session_id``,
+  ``platform``, ``event``, ``cwd``, ``workspace_roots``,
+  ``transcript_path``, ``model``, ``cursor_version``, …) so the
+  schema is reviewable.
+- ``--strict`` redacts any string longer than ``--max-len`` (default
+  120) chars regardless of key, as a safety net for unknown fields.
+
+Usage:
+
+    python3 scripts/redact_hook_capture.py <input> [--out <path>] [--strict]
+
+Input may be a single JSON file or a directory; with a directory,
+every ``*.json`` is redacted and written next to the original with
+the suffix ``.redacted.json``.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+REDACTED = "<REDACTED>"
+
+# Field names that carry user / agent content (from
+# scripts/chat_history.py::_extract_hook_text fallback list +
+# nested Augment shape). Matched case-insensitively against the
+# leaf key.
+_USER_CONTENT_KEYS = {
+    "prompt", "user_prompt", "userprompt", "first_user_msg",
+    "firstusermsg", "usermessage", "user_message", "text",
+    "response", "message", "content",
+    # Augment Code with includeConversationData
+    "agenttextresponse", "agent_text_response",
+    "agentcoderesponse", "agent_code_response",
+    # Cursor / generic
+    "submitted_prompt", "submittedprompt",
+    # Free-form transcript bodies (path stays — content is in another file)
+    "transcript", "transcript_text",
+}
+
+# Keys whose value is a structural / schema marker — keep as-is even
+# when --strict would otherwise redact long values.
+_ENVELOPE_KEYS_KEEP = {
+    "hook_event_name", "session_id", "transcript_path", "transcriptpath",
+    "platform", "event", "native_event", "captured_at", "cwd",
+    "workspace_roots", "model", "cursor_version", "user_email",
+    "conversation_id", "generation_id", "agent", "type",
+    "schema_version", "started_at", "completed_at", "_raw_text",
+    "path", "changetype", "change_type",
+}
+
+
+def _redact_value(val: Any, *, key: str | None, strict: bool,
+                  max_len: int) -> Any:
+    """Recursively redact a value."""
+    norm_key = (key or "").lower().replace("-", "_")
+    if isinstance(val, dict):
+        return {k: _redact_value(v, key=k, strict=strict, max_len=max_len)
+                for k, v in val.items()}
+    if isinstance(val, list):
+        return [_redact_value(item, key=key, strict=strict, max_len=max_len)
+                for item in val]
+    if isinstance(val, str):
+        if norm_key in _ENVELOPE_KEYS_KEEP:
+            return val
+        if norm_key in _USER_CONTENT_KEYS:
+            return REDACTED
+        if strict and len(val) > max_len:
+            return REDACTED
+        return val
+    return val
+
+
+def redact(record: dict, *, strict: bool = False, max_len: int = 120) -> dict:
+    """Redact a single capture record. Top-level envelope is preserved."""
+    out: dict = {}
+    for k, v in record.items():
+        if k == "raw_payload":
+            out[k] = _redact_value(v, key=None, strict=strict,
+                                   max_len=max_len)
+        else:
+            out[k] = _redact_value(v, key=k, strict=strict,
+                                   max_len=max_len)
+    return out
+
+
+def _process_file(path: Path, *, out: Path | None, strict: bool,
+                  max_len: int) -> Path:
+    record = json.loads(path.read_text(encoding="utf-8"))
+    redacted = redact(record, strict=strict, max_len=max_len)
+    target = out or path.with_suffix(".redacted.json")
+    target.write_text(json.dumps(redacted, indent=2) + "\n",
+                      encoding="utf-8")
+    return target
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("input", help="capture file or directory")
+    parser.add_argument("--out", default=None,
+                        help="output path (single-file mode only)")
+    parser.add_argument("--strict", action="store_true",
+                        help="redact any string longer than --max-len")
+    parser.add_argument("--max-len", type=int, default=120,
+                        help="strict-mode length threshold (default 120)")
+    args = parser.parse_args(argv)
+
+    src = Path(args.input).expanduser()
+    if not src.exists():
+        sys.stderr.write(f"redact: input not found: {src}\n")
+        return 2
+
+    if src.is_dir():
+        if args.out:
+            sys.stderr.write("redact: --out is single-file only\n")
+            return 2
+        files = sorted(p for p in src.glob("*.json")
+                       if not p.name.endswith(".redacted.json"))
+        for path in files:
+            target = _process_file(path, out=None, strict=args.strict,
+                                   max_len=args.max_len)
+            print(f"redacted: {target}")
+        return 0
+
+    target = _process_file(src, out=Path(args.out) if args.out else None,
+                           strict=args.strict, max_len=args.max_len)
+    print(f"redacted: {target}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())