@event4u/agent-config 1.19.0 → 1.21.0

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
@@ -563,6 +596,40 @@ copy_if_missing() {
     cp "$source" "$target"
 }
 
+# Migrate legacy infra files from project root to agents/.
+# Pre-2.x layout: .agent-chat-history (+ .bak), .agent-prices.md lived at
+# the project root. They now live under agents/. Move them in place before
+# any other content sync so the updated gitignore block (which lists
+# /agents/.agent-chat-history*) and the chat-history hooks operate on the
+# already-migrated layout. Idempotent: skips silently if the target already
+# exists; never overwrites.
+migrate_legacy_root_infra() {
+    local project_root="$1"
+    local agents_dir="$project_root/agents"
+    local items=(".agent-chat-history" ".agent-chat-history.bak" ".agent-prices.md")
+
+    for name in "${items[@]}"; do
+        local old="$project_root/$name"
+        local new="$agents_dir/$name"
+
+        [[ -e "$old" ]] || continue
+
+        if [[ -e "$new" ]]; then
+            log_warn "Legacy $name found at project root, but agents/$name already exists — leaving root copy in place"
+            continue
+        fi
+
+        if $DRY_RUN; then
+            log_verbose "would migrate $name → agents/$name"
+            continue
+        fi
+
+        mkdir -p "$agents_dir"
+        mv "$old" "$new"
+        log_info "Migrated $name → agents/$name"
+    done
+}
+
 # Ensure .gitignore contains the managed agent-config block.
 # Delegates to scripts/sync_gitignore.py so the installer and the
 # standalone /sync-gitignore command share one source of truth
@@ -632,9 +699,20 @@ main() {
     $DRY_RUN && ! $QUIET && echo "    Mode: DRY RUN"
     echo ""
 
+    # 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
@@ -643,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())

package/scripts/lint_handoffs.py

@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+"""Lint cross-wing handoffs declared in senior-tier skills' ``## Related Skills`` blocks.
+
+Builds a directed graph from every ``tier: senior`` skill's Related Skills
+block (markdown links pointing at peer ``SKILL.md`` files), then enforces
+the rules from ``docs/contracts/cross-wing-handoff.md`` § 4:
+
+  handoff_cycle           — graph must be a DAG.
+  handoff_dangling        — every linked target must exist.
+  handoff_tier_mismatch   — senior may delegate only to senior.
+
+Hooked into ``task lint-handoffs`` and ``task ci`` (between ``lint-skills``
+and ``test``). Output mirrors ``scripts/skill_linter.py``: ``file:line:reason``.
+
+Exit codes:
+  0  no violations
+  1  one or more violations
+"""
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+REPO = Path(__file__).resolve().parents[1]
+SKILLS_DIR = REPO / ".agent-src.uncompressed" / "skills"
+
+LINK_RE = re.compile(r"\[`?([a-z0-9][a-z0-9-]*)`?\]\(([^)]+SKILL\.md)\)")
+RELATED_HEADING_RE = re.compile(r"^##\s+Related\s+Skills\s*$", re.IGNORECASE)
+NEXT_HEADING_RE = re.compile(r"^##\s+\S")
+WHEN_USE_RE = re.compile(r"^\*\*WHEN\s+to\s+use\s+this\*\*\s*$", re.IGNORECASE)
+WHEN_NOT_RE = re.compile(r"^\*\*WHEN\s+NOT\s+to\s+use\s+this\*\*\s*$", re.IGNORECASE)
+
+
+@dataclass(frozen=True)
+class Violation:
+    file: Path
+    line: int
+    code: str
+    message: str
+
+    def render(self, repo: Path) -> str:
+        rel = self.file.relative_to(repo) if self.file.is_absolute() else self.file
+        return f"{rel}:{self.line}:{self.code}: {self.message}"
+
+
+def parse_frontmatter_tier(text: str) -> str | None:
+    if not text.startswith("---\n"):
+        return None
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return None
+    for raw in text[4:end].splitlines():
+        if ":" not in raw:
+            continue
+        key, _, val = raw.partition(":")
+        if key.strip() == "tier":
+            return val.strip().strip('"').strip("'")
+    return None
+
+
+def extract_related_block(text: str) -> tuple[int, list[tuple[int, str]]] | None:
+    """Return (block_start_line, [(line, raw_line), ...]) for ``## Related Skills``."""
+    lines = text.splitlines()
+    start: int | None = None
+    for idx, line in enumerate(lines):
+        if RELATED_HEADING_RE.match(line):
+            start = idx
+            break
+    if start is None:
+        return None
+    body: list[tuple[int, str]] = []
+    for idx in range(start + 1, len(lines)):
+        if NEXT_HEADING_RE.match(lines[idx]):
+            break
+        body.append((idx + 1, lines[idx]))
+    return start + 1, body
+
+
+def split_when_subblocks(body: list[tuple[int, str]]) -> tuple[
+    list[tuple[int, str]], list[tuple[int, str]]
+]:
+    """Split a ``## Related Skills`` body into (when_to_use, when_not_to_use).
+
+    WHEN-to-use links are composition (delegation) edges — graph for cycles.
+    WHEN-NOT-to-use links are alternative pointers (peer cognition the user
+    picks instead) — never composition edges. Lines outside both sub-blocks
+    are treated as WHEN-to-use for backward compatibility.
+    """
+    when_use: list[tuple[int, str]] = []
+    when_not: list[tuple[int, str]] = []
+    current = when_use
+    for lineno, raw in body:
+        if WHEN_USE_RE.match(raw):
+            current = when_use
+            continue
+        if WHEN_NOT_RE.match(raw):
+            current = when_not
+            continue
+        current.append((lineno, raw))
+    return when_use, when_not
+
+
+def extract_links(body: list[tuple[int, str]]) -> list[tuple[int, str, str]]:
+    """Yield ``(line, slug, target_path)`` for every markdown link in the block."""
+    out: list[tuple[int, str, str]] = []
+    for lineno, raw in body:
+        for match in LINK_RE.finditer(raw):
+            out.append((lineno, match.group(1), match.group(2)))
+    return out
+
+
+def resolve_target(skill_file: Path, link: str) -> Path:
+    return (skill_file.parent / link).resolve()
+
+
+def detect_cycles(graph: dict[Path, set[Path]]) -> list[list[Path]]:
+    cycles: list[list[Path]] = []
+    visited: set[Path] = set()
+    stack: list[Path] = []
+    on_stack: set[Path] = set()
+
+    def dfs(node: Path) -> None:
+        if node in on_stack:
+            i = stack.index(node)
+            cycles.append(stack[i:] + [node])
+            return
+        if node in visited:
+            return
+        visited.add(node)
+        on_stack.add(node)
+        stack.append(node)
+        for nxt in graph.get(node, ()):
+            dfs(nxt)
+        stack.pop()
+        on_stack.discard(node)
+
+    for node in list(graph):
+        dfs(node)
+    return cycles
+
+
+def lint(skills_dir: Path) -> list[Violation]:
+    senior_skills: dict[Path, str] = {}
+    all_skills: dict[Path, str] = {}
+    for skill_md in sorted(skills_dir.rglob("SKILL.md")):
+        text = skill_md.read_text(encoding="utf-8")
+        tier = parse_frontmatter_tier(text)
+        all_skills[skill_md.resolve()] = tier or ""
+        if tier == "senior":
+            senior_skills[skill_md.resolve()] = text
+
+    violations: list[Violation] = []
+    graph: dict[Path, set[Path]] = {}
+
+    for skill_path, text in senior_skills.items():
+        block = extract_related_block(text)
+        if block is None:
+            continue
+        _, body = block
+        when_use, when_not = split_when_subblocks(body)
+
+        # WHEN-to-use links: composition edges (graph) + dangling/tier checks.
+        for lineno, slug, link in extract_links(when_use):
+            target = resolve_target(skill_path, link)
+            graph.setdefault(skill_path, set()).add(target)
+            if target not in all_skills:
+                violations.append(Violation(skill_path, lineno, "handoff_dangling",
+                    f"link to `{slug}` resolves to missing file {link}"))
+                continue
+            if all_skills[target] != "senior":
+                violations.append(Violation(skill_path, lineno, "handoff_tier_mismatch",
+                    f"senior skill links to non-senior `{slug}` "
+                    f"(tier={all_skills[target] or 'unset'!r})"))
+
+        # WHEN-NOT-to-use links: alternative pointers, NOT composition edges.
+        # Dangling + tier-mismatch still apply (a broken alternative is wrong);
+        # cycles do not (mutual "use X instead" pointers are intentional).
+        for lineno, slug, link in extract_links(when_not):
+            target = resolve_target(skill_path, link)
+            if target not in all_skills:
+                violations.append(Violation(skill_path, lineno, "handoff_dangling",
+                    f"link to `{slug}` resolves to missing file {link}"))
+                continue
+            if all_skills[target] != "senior":
+                violations.append(Violation(skill_path, lineno, "handoff_tier_mismatch",
+                    f"senior skill links to non-senior `{slug}` "
+                    f"(tier={all_skills[target] or 'unset'!r})"))
+
+    for cycle in detect_cycles(graph):
+        names = " → ".join(p.parent.name for p in cycle)
+        violations.append(Violation(cycle[0], 1, "handoff_cycle",
+            f"composition cycle: {names}"))
+    return violations
+
+
+def main(argv: list[str] | None = None) -> int:
+    skills_dir = SKILLS_DIR
+    if argv:
+        skills_dir = Path(argv[0]).resolve()
+    violations = lint(skills_dir)
+    if not violations:
+        print(f"✅  lint_handoffs: no violations under {skills_dir.relative_to(REPO)}")
+        return 0
+    for v in violations:
+        print(v.render(REPO))
+    print(f"\n❌  lint_handoffs: {len(violations)} violation(s)", file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/scripts/lint_hook_manifest.py

@@ -57,7 +57,8 @@ EVENT_VOCABULARY: set[str] = {
 # Known platform identifiers. New platforms MUST be added here as they
 # land — the linter is the gate that proves no orphan slot escapes.
 KNOWN_PLATFORMS: set[str] = {
-    "augment", "claude", "cursor", "cline", "windsurf", "gemini", "copilot",
+    "augment", "claude", "cowork",
+    "cursor", "cline", "windsurf", "gemini", "copilot",
 }
 
 

package/scripts/lint_load_context.py

@@ -28,14 +28,37 @@ SCAN_DIRS = [
 ]
 
 ALLOWED_PREFIXES = (
-    ".agent-src.uncompressed/contexts/",
-    ".agent-src/contexts/",
-    "agents/contexts/",
+    "contexts/",                               # logical name (canonical — P1.1 / P5.3)
+    ".agent-src/contexts/",                    # projected (defensive — only seen in compressed inputs)
+    "agents/contexts/",                        # project-local
 )
 
+# `.agent-src.uncompressed/contexts/` was the legacy fully-qualified form
+# (pre road-to-path-fixes.md P5.3). It is now a hard error: P2.1 migrated
+# all in-tree rules to logical names, the rewriter resolves them at
+# compress time, and the schema regex in `scripts/schemas/rule.schema.json`
+# rejects the prefix at validate-schema time. Keeping a separate runtime
+# diagnostic so the failure points authors at the canonical
+# `contexts/<area>/<file>.md` form rather than a generic schema mismatch.
+LEGACY_PREFIX = ".agent-src.uncompressed/contexts/"
+
+# Logical names resolve against the source root.
+SOURCE_ROOT = ROOT / ".agent-src.uncompressed"
+
 PUBLIC_RULE_PREFIX = ".agent-src.uncompressed/rules/"
 PROJECT_LOCAL_PREFIX = "agents/contexts/"
 
+
+def resolve_entry(entry: str) -> Path:
+    """Resolve a `load_context:` entry to an absolute path on disk.
+
+    Logical names (`contexts/...`) live under `.agent-src.uncompressed/`;
+    fully-qualified entries are repo-root-relative.
+    """
+    if entry.startswith("contexts/"):
+        return SOURCE_ROOT / entry
+    return ROOT / entry
+
 HARD_FLOOR_RULES = {"non-destructive-by-default", "security-sensitive-stop"}
 
 CAP_ALWAYS = 2_500
@@ -126,10 +149,17 @@ def main() -> int:
             if not isinstance(entry, str) or not entry.endswith(".md"):
                 errors.append(f"{rel(f)}: entry not str ending in .md → {entry!r}")
                 continue
+            if entry.startswith(LEGACY_PREFIX):
+                logical = entry[len(".agent-src.uncompressed/"):]
+                errors.append(
+                    f"{rel(f)}: legacy `.agent-src.uncompressed/` prefix in load_context → {entry} "
+                    f"— use logical name `{logical}` instead (road-to-path-fixes.md P5.3)"
+                )
+                continue
             if not entry.startswith(ALLOWED_PREFIXES):
                 errors.append(f"{rel(f)}: disallowed root → {entry}")
                 continue
-            target = ROOT / entry
+            target = resolve_entry(entry)
             if not target.exists():
                 errors.append(f"{rel(f)}: target missing → {entry}")
                 continue
@@ -140,7 +170,7 @@ def main() -> int:
             cap = cap_for(f, fm)
             total = len(f.read_text(encoding="utf-8"))
             for entry in eager:
-                tgt = ROOT / entry
+                tgt = resolve_entry(entry)
                 if tgt.exists():
                     total += len(tgt.read_text(encoding="utf-8"))
             if total > cap: