@event4u/agent-config 1.19.0 → 1.21.0

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:]))

package/scripts/compress.py

@@ -1,7 +1,9 @@
 #!/usr/bin/env python3
 """
 Agent-config sync — compress .agent-src.uncompressed/ → .agent-src/
-and project .agent-src/ → .augment/ (copies for rules, symlinks for the rest).
+and project .agent-src/ → .augment/ (copies for rules by default,
+symlinks for the rest; opt into rule symlinks via
+augment.rules_use_symlinks in .agent-settings.yml).
 
 Copies non-.md files as-is. Lists .md files that need compression (done by the
 Augment agent interactively). Tracks SHA-256 hashes of source files to detect
@@ -19,6 +21,7 @@ Usage:
 
 import hashlib
 import json
+import re
 import shutil
 import sys
 from pathlib import Path
@@ -28,11 +31,41 @@ SOURCE_DIR = PROJECT_ROOT / ".agent-src.uncompressed"
 TARGET_DIR = PROJECT_ROOT / ".agent-src"
 AUGMENT_DIR = PROJECT_ROOT / ".augment"
 HASH_FILE = PROJECT_ROOT / ".compression-hashes.json"
+SETTINGS_FILE = PROJECT_ROOT / ".agent-settings.yml"
 
 # Files to copy as-is even if .md (not compressed by agent)
 COPY_AS_IS = {"README.md"}
 
 
+def _read_augment_rules_use_symlinks() -> bool:
+    """Read augment.rules_use_symlinks from .agent-settings.yml.
+
+    Returns True only when the setting is present under the top-level
+    ``augment:`` block and resolves to a truthy YAML scalar
+    (true/yes/on/1, case-insensitive). Missing file, missing block, or
+    any other value → False (preserve copy default).
+    """
+    if not SETTINGS_FILE.exists():
+        return False
+    try:
+        text = SETTINGS_FILE.read_text(encoding="utf-8")
+    except OSError:
+        return False
+    in_augment = False
+    for line in text.splitlines():
+        stripped = line.lstrip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if not line.startswith((" ", "\t")):
+            in_augment = stripped.startswith("augment:")
+            continue
+        if in_augment:
+            m = re.match(r"^\s+rules_use_symlinks\s*:\s*([^\s#]+)", line)
+            if m:
+                return m.group(1).strip().lower() in ("true", "yes", "on", "1")
+    return False
+
+
 
 
 def file_hash(filepath: Path) -> str:
@@ -59,17 +92,42 @@ def save_hashes(hashes: dict) -> None:
 
 
 def mark_done(relative_path: str) -> None:
-    """Mark a single file as compressed by storing its current source hash."""
+    """Mark a single file as compressed by storing its current source hash.
+
+    Also runs the path rewriter on the just-written `.agent-src/<path>` so
+    logical names from the source frontmatter resolve to deployment-correct
+    relative paths in the shipped layer (P1 of road-to-path-fixes.md).
+    Idempotent — re-running is a no-op.
+    """
     source_file = SOURCE_DIR / relative_path
     if not source_file.exists():
         print(f"❌  Source file not found: {relative_path}")
         sys.exit(1)
+    apply_path_rewriter(relative_path)
     hashes = load_hashes()
     hashes[relative_path] = file_hash(source_file)
     save_hashes(hashes)
     print(f"✅  Marked as compressed: {relative_path}")
 
 
+def apply_path_rewriter(relative_path: str) -> bool:
+    """Apply `_rewrite_paths` to `.agent-src/<relative_path>` in-place.
+
+    Returns True if the file was modified, False otherwise. Silently
+    returns False if the target doesn't exist (compression hasn't run
+    yet) — `--mark-done` is also valid before content exists.
+    """
+    target = TARGET_DIR / relative_path
+    if not target.exists() or not relative_path.endswith(".md"):
+        return False
+    original = target.read_text(encoding="utf-8")
+    rewritten = _rewrite_paths(original, relative_path)
+    if rewritten == original:
+        return False
+    target.write_text(rewritten, encoding="utf-8")
+    return True
+
+
 def mark_all_done() -> None:
     """Mark ALL .md files as compressed (e.g. after initial full compression)."""
     hashes = load_hashes()
@@ -250,6 +308,144 @@ def strip_frontmatter(content: str) -> str:
     return content
 
 
+# ── Path rewriter (P1 of road-to-path-fixes.md) ───────────────────────────
+# Source files use logical names that the rewriter resolves at compress
+# time, so the shipped `.agent-src/` (and `.augment/` projection) carry
+# deployment-correct relative paths without the agent author having to
+# know how deep their file lives.
+#
+# Frontmatter rewrites:
+#   load_context: / load_context_eager:
+#     contexts/<area>/<file>.md                          (logical, preferred)
+#     .agent-src.uncompressed/contexts/<area>/<file>.md  (legacy)
+#       → ../contexts/<area>/<file>.md  (relative from .agent-src/rules/)
+#   triggers[].path_prefix:
+#     LEFT ALONE — `path_prefix:` is a literal match pattern, not a
+#     file reference. Source-of-truth rules that fire on edits under
+#     `.agent-src.uncompressed/` keep that prefix verbatim (see
+#     road-to-path-fixes.md P2.2 / Modified Option 1).
+#
+# Body-link rewrites:
+#   ../../docs/guidelines/<file>.md  →  ../docs/guidelines/<file>.md
+#   ../../docs/contracts/<file>.md   →  ../docs/contracts/<file>.md
+#
+# Idempotent: applying twice is a no-op (rewritten patterns no longer
+# match the source patterns).
+
+_LEGACY_SRC_PREFIX = ".agent-src.uncompressed/"
+_PROJECTED_SRC_PREFIX = ".agent-src/"
+
+# A YAML list item under load_context*: `  - some/path.md` (optionally quoted)
+_FM_LIST_ITEM_RE = re.compile(r'^(\s*-\s*)(["\']?)([^"\'\n]+?\.md)(["\']?)\s*$')
+
+# `path_prefix:` line — top-level or under `triggers:` (with leading dash)
+_FM_PATH_PREFIX_RE = re.compile(
+    r'^(\s*(?:-\s+)?path_prefix:\s*)(["\']?)([^"\'\n]+?)(["\']?)\s*$'
+)
+
+# Body-link patterns (relative two-up to docs/) — capture the docs/... tail
+_BODY_DOCS_RE = re.compile(r'\.\./\.\./(docs/(?:guidelines|contracts)/[^)\s]+\.md)')
+
+
+def _depth_prefix(source_relative_path: str) -> str:
+    """Return the `../` chain to climb from `<source_relative_path>` back to
+    the source root. A file at `rules/X.md` (1 dir deep) needs `../`; a
+    file at `commands/council/default.md` (2 dirs deep) needs `../../`.
+    """
+    parts = Path(source_relative_path).parts
+    depth = max(len(parts) - 1, 1)
+    return "../" * depth
+
+
+def _split_frontmatter(content: str):
+    """Return (frontmatter_lines, body) — frontmatter_lines is None if no FM."""
+    if not content.startswith("---\n"):
+        return None, content
+    end = content.find("\n---\n", 4)
+    if end == -1:
+        return None, content
+    fm_text = content[4:end]
+    body = content[end + len("\n---\n"):]
+    return fm_text.split("\n"), body
+
+
+def _rewrite_load_context_value(value: str, prefix: str) -> str:
+    """Rewrite a single `load_context` list-item value to a deployment path."""
+    # Already relative or absolute → leave alone (idempotence).
+    if value.startswith(("../", "./", "/")):
+        return value
+    # Legacy fully-qualified source prefix.
+    if value.startswith(_LEGACY_SRC_PREFIX):
+        return prefix + value[len(_LEGACY_SRC_PREFIX):]
+    # Projected source prefix (defensive — also strip).
+    if value.startswith(_PROJECTED_SRC_PREFIX):
+        return prefix + value[len(_PROJECTED_SRC_PREFIX):]
+    # Logical name (e.g. `contexts/execution/foo.md`).
+    return prefix + value
+
+
+def _rewrite_path_prefix_value(value: str) -> str:
+    """No-op for `triggers[].path_prefix:` values.
+
+    `path_prefix:` is a literal match pattern the host evaluates against
+    the file the agent is editing — not a file reference. Rewriting it
+    breaks the workflow it was authored for: source-of-truth rules that
+    fire when the agent edits files under `.agent-src.uncompressed/`
+    keep that prefix verbatim. The prefix ban therefore applies only to
+    `load_context:` entries and body links (see road-to-path-fixes.md
+    P2.2 + the AI-Council convergence on 2026-05-06).
+    """
+    return value
+
+
+def _rewrite_frontmatter_lines(lines, prefix):
+    """Apply load_context / path_prefix rewrites to a frontmatter line list."""
+    in_load_context = False
+    out = []
+    for line in lines:
+        bare = line.lstrip()
+        if bare.startswith(("load_context:", "load_context_eager:")):
+            in_load_context = True
+            out.append(line)
+            continue
+        if in_load_context:
+            m = _FM_LIST_ITEM_RE.match(line)
+            if m:
+                indent, q1, value, q2 = m.groups()
+                rewritten = _rewrite_load_context_value(value, prefix)
+                out.append(f"{indent}{q1}{rewritten}{q2}")
+                continue
+            in_load_context = False
+            # fall through to path_prefix / passthrough
+        m = _FM_PATH_PREFIX_RE.match(line)
+        if m:
+            head, q1, value, q2 = m.groups()
+            out.append(f"{head}{q1}{_rewrite_path_prefix_value(value)}{q2}")
+            continue
+        out.append(line)
+    return out
+
+
+def _rewrite_body_links(body: str, prefix: str) -> str:
+    """Rewrite `../../docs/{guidelines,contracts}/...` to use depth-prefix."""
+    return _BODY_DOCS_RE.sub(prefix + r"\1", body)
+
+
+def _rewrite_paths(content: str, source_relative_path: str) -> str:
+    """Rewrite logical / legacy paths in `content` for a file shipped at
+    `.agent-src/{source_relative_path}`. Idempotent.
+
+    See module-level comment above for the full pattern catalog.
+    """
+    prefix = _depth_prefix(source_relative_path)
+    fm_lines, body = _split_frontmatter(content)
+    body = _rewrite_body_links(body, prefix)
+    if fm_lines is None:
+        return body
+    new_fm = _rewrite_frontmatter_lines(fm_lines, prefix)
+    return "---\n" + "\n".join(new_fm) + "\n---\n" + body
+
+
 def generate_rule_symlinks() -> int:
     """Create symlink directories for rules (.claude/rules/, .cursor/rules/, .clinerules/).
 
@@ -499,8 +695,10 @@ def generate_tools() -> None:
 # ── .augment/ projection ──────────────────────────────────────────────
 # The package uses .agent-src/ as the tool-agnostic compressed source of truth.
 # .augment/ is a generated projection so that Augment Code (which reads from
-# .augment/ and cannot follow symlinked rule files) works on the package repo
-# itself. Rules are copied (real files); everything else is symlinked.
+# .augment/) works on the package repo itself. Rules default to copies
+# because Augment Code historically does not load symlinked rule files;
+# flip augment.rules_use_symlinks: true in .agent-settings.yml to switch
+# them to symlinks (everything else is always symlinked).
 
 # Subdirectories of .agent-src/ that map into .augment/ as symlinks.
 AUGMENT_SYMLINK_DIRS = ("skills", "commands", "guidelines", "personas", "templates", "contexts", "scripts")
@@ -509,34 +707,44 @@ AUGMENT_SYMLINK_FILES = ("README.md",)
 
 
 def project_to_augment() -> None:
-    """Mirror .agent-src/ into .augment/. Copy rules, symlink everything else."""
+    """Mirror .agent-src/ into .augment/. Symlink everything except rules,
+    which default to copies; opt into rule symlinks via
+    augment.rules_use_symlinks in .agent-settings.yml."""
     if not TARGET_DIR.exists():
         print(f"  ⚠️  {TARGET_DIR.name}/ not found — nothing to project")
         return
 
     AUGMENT_DIR.mkdir(parents=True, exist_ok=True)
 
-    # Rules: copy each .md file (Augment Code cannot load symlinked rules)
+    use_symlinks = _read_augment_rules_use_symlinks()
+
+    # Rules: copy by default (Augment Code historically does not load
+    # symlinked rules), or symlink when augment.rules_use_symlinks is true.
     src_rules = TARGET_DIR / "rules"
     dst_rules = AUGMENT_DIR / "rules"
     dst_rules.mkdir(parents=True, exist_ok=True)
     existing = {f.name for f in dst_rules.iterdir() if f.is_file() or f.is_symlink()}
     current = set()
-    copied = 0
+    written = 0
     if src_rules.exists():
         for rule in sorted(src_rules.glob("*.md")):
             target = dst_rules / rule.name
-            if target.is_symlink():
+            # Always remove first to avoid copy↔symlink mode mismatch.
+            if target.is_symlink() or target.exists():
                 target.unlink()
-            shutil.copy2(rule, target)
+            if use_symlinks:
+                target.symlink_to(Path("..") / ".." / ".agent-src" / "rules" / rule.name)
+            else:
+                shutil.copy2(rule, target)
             current.add(rule.name)
-            copied += 1
+            written += 1
     # Remove stale rule files
     removed_rules = 0
     for name in existing - current:
         (dst_rules / name).unlink()
         removed_rules += 1
-    print(f"  ✅  Copied {copied} rules to .augment/rules/" + (f" ({removed_rules} stale removed)" if removed_rules else ""))
+    mode_label = "Symlinked" if use_symlinks else "Copied"
+    print(f"  ✅  {mode_label} {written} rules to .augment/rules/" + (f" ({removed_rules} stale removed)" if removed_rules else ""))
 
     # Subdirectories: replace each with a symlink → ../.agent-src/<subdir>
     for sub in AUGMENT_SYMLINK_DIRS: