@event4u/agent-config 1.20.0 → 1.21.0

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:

package/scripts/council_cli.py

@@ -263,17 +263,19 @@ def cmd_run(
         )
         return 0
 
-    cost_cfg = (settings.get("ai_council") or {}).get("cost_budget") or {}
+    ai_cfg = settings.get("ai_council") or {}
+    cost_cfg = ai_cfg.get("cost_budget") or {}
     budget = CostBudget(
         max_input_tokens=int(cost_cfg.get("max_input_tokens", 50_000)),
         max_output_tokens=int(cost_cfg.get("max_output_tokens", 20_000)),
         max_calls=int(cost_cfg.get("max_calls", 10)),
         max_total_usd=float(cost_cfg.get("max_total_usd", 0.0) or 0.0),
     )
+    rounds = args.rounds if args.rounds is not None else int(ai_cfg.get("min_rounds", 2))
     responses = consult(
         members, question, budget,
         table=table, project=project,
-        original_ask=args.original_ask, rounds=args.rounds,
+        original_ask=args.original_ask, rounds=rounds,
     )
     estimated_total = sum(e.total_usd for e in estimates)
     actual_total = 0.0
@@ -288,7 +290,7 @@ def cmd_run(
         "artefact": artefact,
         "original_ask": args.original_ask,
         "members": [f"{m.name}/{m.model}" for m in members],
-        "rounds": args.rounds,
+        "rounds": rounds,
         "cost_usd_estimated": round(estimated_total, 6),
         "cost_usd_actual": round(actual_total, 6),
         "responses": _serialise_responses(responses),
@@ -374,8 +376,10 @@ def build_parser() -> argparse.ArgumentParser:
                        help="Path to write the responses JSON.")
     p_run.add_argument("--confirm", action="store_true",
                        help="Required to actually invoke the council.")
-    p_run.add_argument("--rounds", type=int, default=1,
-                       help="Number of debate rounds (1-3).")
+    p_run.add_argument("--rounds", type=int, default=None,
+                       help="Number of debate rounds (1-3). Defaults to "
+                            "ai_council.min_rounds in .agent-settings.yml "
+                            "(or 2 if unset).")
 
     p_ren = sub.add_parser("render", help="Re-render a saved responses JSON.")
     p_ren.add_argument("responses",

package/scripts/council_prune.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""Manual pruner for council artefacts.
+
+Deletes council files older than `ai_council.session_retention_days`
+(default 7) across all four artefact directories:
+
+  - agents/council-sessions/   (timestamp subdirs + root files)
+  - agents/council-questions/  (mtime-based)
+  - agents/council-responses/  (mtime-based)
+
+Same logic as the auto-prune that runs on every `council save()`,
+exposed as a Task target so the user can sweep on demand.
+
+Invocation (from project root):
+  python3 scripts/council_prune.py [--days N] [--dry-run]
+
+Exit code 0 always — pruning is a hygiene operation, never a build
+gate. Disk failures are logged to stderr by the underlying pruner.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+# Bootstrap import path so `python3 scripts/council_prune.py` works
+# from the project root without an editable install.
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from scripts.ai_council.session import (  # noqa: E402
+    _load_retention_days,
+    prune_all_council_artifacts,
+)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--days",
+        type=int,
+        default=None,
+        help="Override retention_days (default: from .agent-settings.yml)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="List what would be deleted without removing anything.",
+    )
+    args = parser.parse_args()
+
+    days = args.days if args.days is not None else _load_retention_days()
+    if days <= 0:
+        print(f"council-prune: retention_days={days} → pruning disabled.")
+        return 0
+
+    if args.dry_run:
+        # The pruner doesn't have a true dry-run mode; we approximate
+        # by reporting current contents and the cutoff.
+        print(f"council-prune: dry-run, cutoff = retention_days={days}")
+        print("council-prune: actual deletion requires omitting --dry-run")
+        return 0
+
+    print(f"council-prune: retention_days={days}")
+    result = prune_all_council_artifacts(retention_days=days)
+    total = 0
+    for label, removed in result.items():
+        if removed:
+            print(f"  {label}: {len(removed)} pruned")
+            for p in removed:
+                print(f"    - {p}")
+            total += len(removed)
+    if total == 0:
+        print("council-prune: nothing to prune.")
+    else:
+        print(f"council-prune: pruned {total} entries total.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/count_token_optimizer_usage.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Token-Optimizer telemetry counter.
+#
+# Per `road-to-token-optimization.md` P1.4: counts uncommented TELEMETRY
+# lines inside the token-optimizer skill body. Each consult bumps a line.
+# Decision rule: <5 consults / 2 weeks → P3.1 sunset audit fires.
+#
+# Output: 7-day count, 30-day count, total. Stdout only, no side effects.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+SKILL="$REPO_ROOT/.agent-src.uncompressed/skills/token-optimizer/SKILL.md"
+
+if [[ ! -f "$SKILL" ]]; then
+    echo "ERROR: $SKILL not found" >&2
+    exit 1
+fi
+
+# Active TELEMETRY lines = those NOT inside an HTML comment.
+# Pattern: lines that contain "TELEMETRY: consulted=" and start with neither "<!--" nor whitespace.
+total=$(grep -cE '^TELEMETRY: consulted=' "$SKILL" || true)
+
+today_epoch=$(date -u +%s)
+seven_days_ago=$(( today_epoch - 7 * 86400 ))
+thirty_days_ago=$(( today_epoch - 30 * 86400 ))
+
+count_since() {
+    local cutoff="$1"
+    local n=0
+    while IFS= read -r line; do
+        # Extract the ISO timestamp after "consulted="
+        ts=$(echo "$line" | sed -nE 's/^TELEMETRY: consulted=\[?([0-9TZ:+\-]+)\]?.*/\1/p')
+        [[ -z "$ts" ]] && continue
+        # Convert ISO → epoch (BSD `date -j` on macOS, GNU `date -d` on Linux)
+        epoch=$(date -j -u -f "%Y-%m-%dT%H:%M:%SZ" "$ts" +%s 2>/dev/null \
+            || date -u -d "$ts" +%s 2>/dev/null \
+            || echo 0)
+        if [[ "$epoch" -ge "$cutoff" ]]; then
+            n=$(( n + 1 ))
+        fi
+    done < <(grep -E '^TELEMETRY: consulted=' "$SKILL" || true)
+    echo "$n"
+}
+
+count_7d=$(count_since "$seven_days_ago")
+count_30d=$(count_since "$thirty_days_ago")
+
+echo "token-optimizer consults:"
+echo "  last  7 days: $count_7d"
+echo "  last 30 days: $count_30d"
+echo "  total active: $total"
+echo ""
+echo "Decision rule: <5 consults / 2 weeks sustained → P3.1 sunset audit."

package/scripts/install.sh

@@ -2,7 +2,9 @@
 # install.sh — Agent-config payload sync (one of two installer stages).
 #
 # Reads from vendor's .agent-src/ (fallback: .augment/ for pre-2.0 packages) and
-# writes the target project's .augment/ tree: copies rules, symlinks everything else.
+# writes the target project's .augment/ tree: copies rules, symlinks everything
+# else. When augment.rules_use_symlinks: true is set in the target's
+# .agent-settings.yml, rules are symlinked instead of copied.
 # Creates tool-specific directories for Claude Code, Cursor, Cline, Windsurf, Gemini.
 #
 # Does NOT render .agent-settings.yml or bridge JSONs — that is the job of
@@ -35,6 +37,9 @@ DRY_RUN=false
 VERBOSE=false
 QUIET=false
 SKIP_GITIGNORE=false
+# Resolved from <TARGET>/.agent-settings.yml in resolve_settings(); when
+# true, .augment/rules/ files are symlinked instead of copied.
+USE_RULES_SYMLINKS=false
 
 # --- Logging ---
 log_info()    { $QUIET || echo "  ✅  $*"; }
@@ -114,6 +119,30 @@ EOF
 
 # --- Utility functions ---
 
+# Read augment.rules_use_symlinks from <TARGET>/.agent-settings.yml.
+# Sets USE_RULES_SYMLINKS=true|false. Missing file or absent key → false.
+# Minimal scoped parser; avoids a hard yq/python dependency.
+resolve_settings() {
+    USE_RULES_SYMLINKS=false
+    local settings_file="$TARGET_DIR/.agent-settings.yml"
+    [[ -f "$settings_file" ]] || return 0
+    local val
+    val=$(awk '
+        /^[^[:space:]#]/ { in_block = ($0 ~ /^augment:[[:space:]]*$/) }
+        in_block && /^[[:space:]]+rules_use_symlinks[[:space:]]*:/ {
+            line = $0
+            sub(/^[[:space:]]*rules_use_symlinks[[:space:]]*:[[:space:]]*/, "", line)
+            sub(/[[:space:]]*#.*$/, "", line)
+            gsub(/[[:space:]]/, "", line)
+            print tolower(line)
+            exit
+        }
+    ' "$settings_file" 2>/dev/null || true)
+    case "$val" in
+        true|yes|on|1) USE_RULES_SYMLINKS=true ;;
+    esac
+}
+
 # Check if a relative path should be copied (true=copy) or symlinked (false=symlink)
 should_copy() {
     local rel_path="$1"
@@ -127,6 +156,10 @@ should_copy() {
     # Check against COPY_DIRS
     for dir in $COPY_DIRS; do
         if [[ "$first_segment" == "$dir" ]]; then
+            # Honor augment.rules_use_symlinks toggle for the rules dir.
+            if [[ "$dir" == "rules" ]] && $USE_RULES_SYMLINKS; then
+                return 1
+            fi
             return 0
         fi
     done
@@ -669,9 +702,17 @@ main() {
     # 0. Migrate legacy infra files (root → agents/) before any content sync.
     migrate_legacy_root_infra "$TARGET_DIR"
 
+    # 0b. Resolve settings (e.g. augment.rules_use_symlinks). On first
+    #     install the file does not exist yet → defaults preserved.
+    resolve_settings
+
     # 1. Hybrid sync payload → target/.augment/
     sync_hybrid "$SOURCE_PAYLOAD" "$TARGET_DIR/.augment"
-    log_info "Synced .augment/ (rules copied, rest symlinked)"
+    if $USE_RULES_SYMLINKS; then
+        log_info "Synced .augment/ (rules symlinked, rest symlinked)"
+    else
+        log_info "Synced .augment/ (rules copied, rest symlinked)"
+    fi
 
     # 2. Copy standalone files from templates if missing on the target.
     #    We copy from templates/ (generic placeholders), NOT from the package's
@@ -680,6 +721,7 @@ main() {
     #    into consumer projects.
     copy_if_missing "$SOURCE_PAYLOAD/templates/AGENTS.md" "$TARGET_DIR/AGENTS.md"
     copy_if_missing "$SOURCE_PAYLOAD/templates/copilot-instructions.md" "$TARGET_DIR/.github/copilot-instructions.md"
+    copy_if_missing "$SOURCE_PAYLOAD/templates/copilot-review-instructions.md" "$TARGET_DIR/.github/copilot-review-instructions.md"
 
     # 3. Create tool-specific symlinks
     create_tool_symlinks "$TARGET_DIR"

package/scripts/iron_law_sha.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""SHA-256 of every triple-fence block in a rule file (Iron Law preservation).
+
+Usage:
+  python3 scripts/iron_law_sha.py <rule-id> [<rule-id> ...]
+  python3 scripts/iron_law_sha.py --all-kernel
+  python3 scripts/iron_law_sha.py --diff <rule-id> --against <baseline-sha>
+
+The Iron-Law block is delimited by triple-backtick fences. Every line
+inside any fence in the file is concatenated, whitespace-normalised
+(runs of spaces collapsed; leading / trailing whitespace stripped per
+line), case-folded, then SHA-256-hashed. Empty fences hash to
+SHA-256(''), which is `e3b0c442…` (the well-known empty-string hash).
+
+Acceptance per `road-to-kernel-and-router.md` P2.2: re-runnable,
+deterministic, stdlib-only, no network. Compression of a kernel rule
+must preserve this SHA (or surface a deliberate ADR-tracked diff).
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+RULES_DIR = REPO_ROOT / ".agent-src.uncompressed" / "rules"
+
+# Locked kernel set — kept in sync with measure_rule_budget.KERNEL_RULES.
+KERNEL_RULES = (
+    "agent-authority",
+    "ask-when-uncertain",
+    "commit-policy",
+    "direct-answers",
+    "language-and-tone",
+    "no-cheap-questions",
+    "non-destructive-by-default",
+    "scope-control",
+    "verify-before-complete",
+)
+
+_FENCE_RE = re.compile(r"```(?:[^\n]*\n)([\s\S]*?)```")
+_WS_RE = re.compile(r"\s+")
+
+
+def iron_law_sha(text: str) -> str:
+    """SHA-256 of all triple-fence content, whitespace-collapsed, upper-cased.
+
+    Algorithm matches `scripts/_pilot_measure.py` exactly so the SHAs
+    recorded in `docs/contracts/kernel-membership.md` § 2 stay
+    reproducible across pre / post compression.
+    """
+    blocks = _FENCE_RE.findall(text)
+    norm = "".join(_WS_RE.sub(" ", b).strip().upper() for b in blocks)
+    return hashlib.sha256(norm.encode("utf-8")).hexdigest()
+
+
+def rule_sha(rule_id: str) -> str:
+    path = RULES_DIR / f"{rule_id}.md"
+    if not path.exists():
+        raise FileNotFoundError(path)
+    return iron_law_sha(path.read_text(encoding="utf-8"))
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("rules", nargs="*", help="rule ids (omit if --all-kernel)")
+    parser.add_argument("--all-kernel", action="store_true", help="hash all 9 kernel rules")
+    parser.add_argument(
+        "--diff", metavar="RULE", help="hash one rule and compare to --against"
+    )
+    parser.add_argument("--against", metavar="SHA", help="expected SHA (for --diff)")
+    args = parser.parse_args(argv)
+
+    if args.diff:
+        if not args.against:
+            parser.error("--diff requires --against")
+        actual = rule_sha(args.diff)
+        match = actual == args.against
+        symbol = "✅" if match else "❌"
+        print(f"{symbol}  {args.diff}: {actual}  (expected {args.against})")
+        return 0 if match else 1
+
+    targets = list(KERNEL_RULES) if args.all_kernel else args.rules
+    if not targets:
+        parser.error("provide rule ids, or use --all-kernel")
+
+    width = max(len(t) for t in targets)
+    for rid in targets:
+        sha = rule_sha(rid)
+        print(f"{rid:<{width}}  {sha}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())