@event4u/agent-config 3.0.0 → 3.1.0

package/scripts/lint_global_paths.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""Permissions-audit entry-gate for the global install tree.
+
+Phase 5.0 / amendment A7 of road-to-global-only-install. Runs BEFORE
+any legacy snapshot write so a perms leak cannot be created by the
+migration itself: `agent-config migrate-to-global` is expected to call
+this script first, abort on any failure, and only then proceed with
+the copy → verify → move → bridge sequence.
+
+Policy source: scripts/expected_perms.json (parameterised so the policy
+can evolve without code changes).
+
+Exit codes:
+    0  — all checks pass.
+    1  — at least one finding (printed to stdout, one finding per line).
+    2  — bad invocation (missing policy, JSON parse error, etc).
+
+Usage:
+    python3 scripts/lint_global_paths.py
+    python3 scripts/lint_global_paths.py --policy scripts/expected_perms.json
+    python3 scripts/lint_global_paths.py --quiet
+
+The script is intentionally read-only — no fixups, no chmod, no creates.
+The migration owns side effects.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import stat
+import sys
+from pathlib import Path
+
+DEFAULT_POLICY = Path(__file__).resolve().parent / "expected_perms.json"
+
+
+def _expand(p: str) -> Path:
+    return Path(os.path.expanduser(p))
+
+
+def _mode_str(mode: int) -> str:
+    return f"0{stat.S_IMODE(mode):03o}"
+
+
+def _check_mode(path: Path, expected: str, kind: str) -> str | None:
+    """Return finding text or None when path is clean."""
+    if not path.exists():
+        return None  # missing optional paths are silent — checked by `required`
+    try:
+        actual = _mode_str(path.stat().st_mode)
+    except OSError as exc:
+        return f"{path}: stat failed ({exc})"
+    if actual != expected:
+        return f"{path}: {kind} mode {actual} (expected {expected})"
+    return None
+
+
+def _check_symlinks(root: Path) -> list[str]:
+    """All symlinks under `root` must resolve to paths still under `root`."""
+    findings: list[str] = []
+    if not root.exists():
+        return findings
+    root_resolved = root.resolve()
+    for entry in root.rglob("*"):
+        if not entry.is_symlink():
+            continue
+        try:
+            target = entry.resolve(strict=False)
+        except OSError as exc:
+            findings.append(f"{entry}: symlink resolve failed ({exc})")
+            continue
+        try:
+            target.relative_to(root_resolved)
+        except ValueError:
+            findings.append(f"{entry}: symlink escapes global root → {target}")
+    return findings
+
+
+def _check_glob(root: Path, glob: str, expected_mode: str, required: bool, kind: str) -> list[str]:
+    findings: list[str] = []
+    # Globs anchored at ~ are pre-expanded; reduce them to a root-relative pattern.
+    home = Path.home()
+    pattern_path = Path(os.path.expanduser(glob))
+    try:
+        rel = pattern_path.relative_to(home)
+    except ValueError:
+        rel = pattern_path
+    matches = list(home.glob(str(rel)))
+    if not matches and required:
+        findings.append(f"{glob}: required {kind} missing")
+        return findings
+    for match in matches:
+        finding = _check_mode(match, expected_mode, kind)
+        if finding:
+            findings.append(finding)
+    return findings
+
+
+def lint(policy_path: Path, quiet: bool = False) -> int:
+    try:
+        policy = json.loads(policy_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"error: policy load failed: {exc}", file=sys.stderr)
+        return 2
+
+    findings: list[str] = []
+
+    root_spec = policy.get("global_root") or {}
+    root_path = _expand(root_spec.get("path", "~/.event4u/agent-config"))
+    if root_path.exists():
+        finding = _check_mode(root_path, root_spec.get("expected_mode", "0700"), "directory")
+        if finding:
+            findings.append(finding)
+        findings.extend(_check_symlinks(root_path))
+
+    for spec in policy.get("files", []):
+        findings.extend(_check_glob(
+            root_path, spec["glob"], spec["expected_mode"],
+            spec.get("required", False), "file",
+        ))
+    for spec in policy.get("directories", []):
+        findings.extend(_check_glob(
+            root_path, spec["glob"], spec["expected_mode"],
+            spec.get("required", False), "directory",
+        ))
+
+    if not findings:
+        if not quiet:
+            print(f"✅ global paths clean ({root_path})")
+        return 0
+    for f in findings:
+        print(f"❌ {f}")
+    return 1
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--policy", type=Path, default=DEFAULT_POLICY)
+    ap.add_argument("--quiet", action="store_true")
+    args = ap.parse_args()
+    return lint(args.policy, quiet=args.quiet)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_orchestration_dsl.py

@@ -33,6 +33,9 @@ import sys
 from pathlib import Path
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+from _lib.agent_src import resolve_logical  # noqa: E402
+
 DEFAULT_DIR = REPO_ROOT / ".agent-config" / "orchestrations"
 
 NAME_RE = re.compile(r"^[a-z][a-z0-9-]*$")
@@ -62,11 +65,11 @@ def _load_yaml(path: Path) -> object:
 
 def _ref_exists(kind: str, ref: str) -> bool:
     if kind == "skill":
-        return (REPO_ROOT / ".agent-src.uncompressed" / "skills" / ref / "SKILL.md").is_file()
+        return resolve_logical(f"skills/{ref}/SKILL.md") is not None
     if kind == "command":
-        return (REPO_ROOT / ".agent-src.uncompressed" / "commands" / f"{ref}.md").is_file()
+        return resolve_logical(f"commands/{ref}.md") is not None
     if kind == "persona":
-        return (REPO_ROOT / ".agent-src.uncompressed" / "personas" / f"{ref}.md").is_file()
+        return resolve_logical(f"personas/{ref}.md") is not None
     if kind == "subagent":
         return ref in SUBAGENT_MODES
     return False

package/scripts/lint_pack_boundaries.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""Enforce cross-pack reference boundaries.
+
+Phase 4.4 of the monorepo migration (ADR-017). Walks every markdown
+link in every artefact under ``packages/*/.agent-src.uncompressed/``
+and verifies the link target's pack is either the same pack, ``core``
+(always allowed), or listed in the source pack's ``requires``.
+
+Reports every violation with ``source -> target`` plus the offending
+pack edge. Exits non-zero if any are found.
+
+CLI:
+  --format text|json   default text
+  --quiet              suppress per-file noise; only print violations
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+PACKAGES = ROOT / "packages"
+
+LINK_RE = re.compile(r"\[[^\]]*\]\(([^)#?]+)(?:[#?][^)]*)?\)")
+
+
+def _load_pack_meta(pkg_dir: Path) -> dict[str, Any]:
+    pack_yaml = pkg_dir / "pack.yaml"
+    if not pack_yaml.exists():
+        return {}
+    data = yaml.safe_load(pack_yaml.read_text(encoding="utf-8"))
+    return data if isinstance(data, dict) else {}
+
+
+def _build_artefact_index() -> dict[str, str]:
+    """Map repo-relative POSIX artefact path -> pack id."""
+    index: dict[str, str] = {}
+    if not PACKAGES.exists():
+        return index
+    for pkg in sorted(PACKAGES.iterdir()):
+        if not pkg.is_dir():
+            continue
+        src_root = pkg / ".agent-src.uncompressed"
+        if not src_root.is_dir():
+            continue
+        pid = _load_pack_meta(pkg).get("id") or pkg.name.removeprefix("pack-")
+        for p in src_root.rglob("*.md"):
+            if p.is_file():
+                index[p.relative_to(ROOT).as_posix()] = pid
+    return index
+
+
+def _resolve_link(source_file: Path, raw: str) -> Path | None:
+    """Resolve a markdown link target to a repo-relative path, or None."""
+    target = raw.strip()
+    if not target or target.startswith(("http://", "https://", "mailto:", "ftp://")):
+        return None
+    if target.startswith("/"):
+        return None  # absolute web paths, ignored
+    try:
+        resolved = (source_file.parent / target).resolve()
+    except OSError:
+        return None
+    try:
+        return resolved.relative_to(ROOT)
+    except ValueError:
+        return None
+
+
+def _scan_file(path: Path) -> list[str]:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return []
+    return LINK_RE.findall(text)
+
+
+def _is_allowed(source_pack: str, target_pack: str, requires: list[str]) -> bool:
+    if source_pack == target_pack:
+        return True
+    if target_pack == "core":
+        return True
+    return target_pack in (requires or [])
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--format", choices=["text", "json"], default="text")
+    ap.add_argument("--quiet", action="store_true")
+    args = ap.parse_args()
+
+    artefact_pack = _build_artefact_index()
+    if not artefact_pack:
+        print("no packages/ tree to lint — skipping", file=sys.stderr)
+        return 0
+
+    pack_requires: dict[str, list[str]] = {}
+    for pkg in sorted(PACKAGES.iterdir()):
+        if pkg.is_dir():
+            meta = _load_pack_meta(pkg)
+            pid = meta.get("id") or pkg.name.removeprefix("pack-")
+            pack_requires[pid] = list(meta.get("requires") or [])
+
+    violations: list[dict[str, str]] = []
+    for rel_path, src_pack in artefact_pack.items():
+        source_file = ROOT / rel_path
+        for raw in _scan_file(source_file):
+            target_rel = _resolve_link(source_file, raw)
+            if target_rel is None:
+                continue
+            target_key = target_rel.as_posix()
+            target_pack = artefact_pack.get(target_key)
+            if target_pack is None:
+                continue  # link to docs/, scripts/, root files — not pack-scoped
+            if _is_allowed(src_pack, target_pack, pack_requires.get(src_pack, [])):
+                continue
+            violations.append({
+                "source_pack": src_pack,
+                "target_pack": target_pack,
+                "source": rel_path,
+                "target": target_key,
+                "link": raw,
+            })
+
+    if args.format == "json":
+        json.dump({"violations": violations, "count": len(violations)}, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+    else:
+        if not args.quiet:
+            print(f"lint_pack_boundaries: scanned {len(artefact_pack)} artefacts across {len(pack_requires)} packs")
+        for v in violations:
+            print(f"  ✗ {v['source_pack']} -> {v['target_pack']} : {v['source']} → {v['target']} (link: {v['link']})")
+        if violations:
+            print(f"\n{len(violations)} cross-pack violation(s) — declare 'requires' in pack.yaml or move the artefact")
+        elif not args.quiet:
+            print("OK — no cross-pack drift")
+    return 1 if violations else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_pack_first_win.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""Lint: every featured pack ships FIRST_WIN.md + onboarding: block.
+
+Phase 4 Step 4 of road-to-role-first-onboarding.md.
+
+A pack is "featured" when its id appears in the
+FEATURED_PACK_IDS set below — currently the five role-first packs
+listed in docs/featured-skills.md.
+
+Each featured pack MUST have:
+  - packages/pack-<id>/FIRST_WIN.md (file present, > 0 bytes)
+  - packages/pack-<id>/pack.yaml with an `onboarding:` block carrying
+    `first_win_doc`, `example_workflow`, `time_to_first_value_minutes`
+
+Exits non-zero on any violation. Stdlib-only (no PyYAML — uses simple
+YAML scan since pack.yaml is generator-controlled flat shape).
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+PACKAGES = REPO_ROOT / "packages"
+
+FEATURED_PACK_IDS = {
+    "founder-strategy",
+    "finance-basic",
+    "gtm-sales",
+    "ops-people",
+    "ai-video",
+}
+
+REQUIRED_ONBOARDING_KEYS = (
+    "first_win_doc",
+    "example_workflow",
+    "time_to_first_value_minutes",
+)
+
+
+def _has_onboarding_block(pack_yaml: Path) -> tuple[bool, list[str]]:
+    """Return (ok, missing_keys). Uses a tiny scanner — pack.yaml is
+    generator-controlled, so we only check for the literal `onboarding:`
+    parent key and the three required child keys nested under it."""
+    if not pack_yaml.exists():
+        return False, list(REQUIRED_ONBOARDING_KEYS)
+    lines = pack_yaml.read_text(encoding="utf-8").splitlines()
+    in_block = False
+    found: set[str] = set()
+    for raw in lines:
+        if raw.startswith("onboarding:"):
+            in_block = True
+            continue
+        if in_block:
+            if raw and not raw.startswith((" ", "\t")):
+                break
+            stripped = raw.strip()
+            for key in REQUIRED_ONBOARDING_KEYS:
+                if stripped.startswith(f"{key}:"):
+                    found.add(key)
+    if not in_block:
+        return False, list(REQUIRED_ONBOARDING_KEYS)
+    missing = [k for k in REQUIRED_ONBOARDING_KEYS if k not in found]
+    return not missing, missing
+
+
+def main() -> int:
+    errors: list[str] = []
+    for pid in sorted(FEATURED_PACK_IDS):
+        pack_dir = PACKAGES / f"pack-{pid}"
+        if not pack_dir.is_dir():
+            errors.append(f"missing pack dir: {pack_dir.relative_to(REPO_ROOT)}")
+            continue
+        first_win = pack_dir / "FIRST_WIN.md"
+        if not first_win.exists() or first_win.stat().st_size == 0:
+            errors.append(
+                f"missing or empty: {first_win.relative_to(REPO_ROOT)}"
+            )
+        ok, missing = _has_onboarding_block(pack_dir / "pack.yaml")
+        if not ok:
+            errors.append(
+                f"{pack_dir.name}/pack.yaml: onboarding block missing "
+                f"key(s) {missing!r}"
+            )
+    if errors:
+        print("❌ pack first-win lint failed:", file=sys.stderr)
+        for e in errors:
+            print(f"  - {e}", file=sys.stderr)
+        print(
+            "  fix: add FIRST_WIN.md to the pack root and the onboarding "
+            "block to config/discovery/packs.yml, then re-run "
+            "`task generate-pack-manifests`",
+            file=sys.stderr,
+        )
+        return 1
+    print(
+        f"✅ pack first-win lint OK — {len(FEATURED_PACK_IDS)} featured packs"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_readme_jargon.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""CI guard for README.md above-fold jargon density.
+
+The role-first-onboarding roadmap (Phase 2 Step 3) targets non-developer
+readers above the fold. Lines 1..ABOVE_FOLD_LINES of README.md MUST
+contain at most MAX_HITS occurrences of the watchlist terms below
+(case-insensitive, whole-word matched).
+
+Watchlist comes from feedback8 — words that read fine to a maintainer
+but bounce a Founder or Creator off the page within five seconds:
+
+    kernel · contract · iron law · projection · manifest · lint ·
+    ADR · soak · drift · gate · harness
+
+Counting rules:
+  - Case-insensitive.
+  - Whole-word match (no partial hits inside other words).
+  - Skip fenced code blocks (```...```), HTML comments, and link URLs.
+  - Each match counts once at its location; multi-line lints stay
+    deterministic.
+
+Exit codes:
+  0 — above-fold jargon hits <= MAX_HITS.
+  1 — above-fold jargon hits >  MAX_HITS (print line + match summary).
+
+Invocation:
+  python3 scripts/lint_readme_jargon.py
+  python3 scripts/lint_readme_jargon.py --quiet
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+README = Path("README.md")
+ABOVE_FOLD_LINES = 120
+MAX_HITS = 3
+
+WATCHLIST = (
+    "kernel",
+    "contract",
+    "iron law",
+    "projection",
+    "manifest",
+    "lint",
+    "ADR",
+    "soak",
+    "drift",
+    "gate",
+    "harness",
+)
+
+
+def _strip_noise(lines: list[str]) -> list[str]:
+    """Return per-line content with fences / HTML comments / URLs removed.
+
+    Order matters: drop URLs first (they may sit inside fences), then
+    blank out fenced code regions so word-boundary matches don't trip
+    on stack-trace or shell tokens.
+    """
+    url_re = re.compile(r"https?://\S+|\(\.[\w./-]+\)")
+    cleaned: list[str] = []
+    in_fence = False
+    in_html = False
+    for raw in lines:
+        line = raw
+        if "<!--" in line and "-->" not in line:
+            in_html = True
+        if in_html:
+            cleaned.append("")
+            if "-->" in line:
+                in_html = False
+            continue
+        stripped = line.strip()
+        if stripped.startswith("```"):
+            in_fence = not in_fence
+            cleaned.append("")
+            continue
+        if in_fence:
+            cleaned.append("")
+            continue
+        cleaned.append(url_re.sub(" ", line))
+    return cleaned
+
+
+def main() -> int:
+    quiet = "--quiet" in sys.argv
+    if not README.exists():
+        print(f"error: {README} not found", file=sys.stderr)
+        return 1
+
+    all_lines = README.read_text(encoding="utf-8").splitlines()
+    head = _strip_noise(all_lines[:ABOVE_FOLD_LINES])
+
+    patterns = [
+        (term, re.compile(r"(?<![A-Za-z0-9])" + re.escape(term) + r"(?![A-Za-z0-9])", re.IGNORECASE))
+        for term in WATCHLIST
+    ]
+
+    hits: list[tuple[int, str, str]] = []
+    for idx, content in enumerate(head, start=1):
+        for term, pat in patterns:
+            for m in pat.finditer(content):
+                hits.append((idx, term, m.group(0)))
+
+    if len(hits) > MAX_HITS:
+        print(
+            f"FAIL  {README}: {len(hits)} jargon hits above the fold "
+            f"(lines 1..{ABOVE_FOLD_LINES}, limit {MAX_HITS})."
+        )
+        for line_no, term, match in hits:
+            print(f"  L{line_no:>3}  {term:<10}  -> {match!r}")
+        print(
+            "\nFix: rewrite the line in role-first language. Move the "
+            "term below line "
+            f"{ABOVE_FOLD_LINES + 1} (architecture / contracts section)."
+        )
+        return 1
+
+    if not quiet:
+        print(
+            f"OK    {README}: {len(hits)} jargon hits above the fold "
+            f"(limit {MAX_HITS})."
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_readme_size.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+"""CI guard for README.md line budget.
+
+The role-first-onboarding roadmap (Phase 2 Step 6) freezes README at
+its current length: replace, do not grow. Every line added above the
+fold must displace an existing line. Budget: 750 lines max.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+README = Path("README.md")
+LIMIT = 750
+
+
+def main() -> int:
+    quiet = "--quiet" in sys.argv
+    if not README.exists():
+        print(f"error: {README} not found", file=sys.stderr)
+        return 1
+    n = sum(1 for _ in README.read_text(encoding="utf-8").splitlines())
+    if n > LIMIT:
+        print(f"FAIL  {README}: {n} lines (limit {LIMIT}). Trim before merge.")
+        return 1
+    if not quiet:
+        print(f"OK    {README}: {n} lines (limit {LIMIT}).")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_rule_interactions.py

@@ -25,8 +25,27 @@ import yaml
 QUIET = "--quiet" in sys.argv
 
 ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / "scripts"))
+from _lib.agent_src import resolve_logical, strip_source_prefix  # noqa: E402
+
 MATRIX = ROOT / "docs" / "contracts" / "rule-interactions.yml"
-RULES_DIR = ROOT / ".agent-src.uncompressed" / "rules"
+
+
+def _rule_exists(slug: str) -> bool:
+    return resolve_logical(f"rules/{slug}.md") is not None
+
+
+def _evidence_exists(file_part: str) -> bool:
+    """Return True if the evidence path resolves under any source root.
+
+    Accepts legacy ``.agent-src.uncompressed/...`` citations and resolves
+    them through the multi-root layout; falls back to a literal repo
+    path check for non-source citations (docs/, agents/, ...).
+    """
+    logical = strip_source_prefix(file_part)
+    if logical is not None:
+        return resolve_logical(logical) is not None
+    return (ROOT / file_part).exists()
 
 ALLOWED_RELATIONS = {
     "overrides",
@@ -77,9 +96,8 @@ def main() -> int:
         if not isinstance(slug, str):
             errors.append(f"rule slug not a string: {slug!r}")
             continue
-        rule_path = RULES_DIR / f"{slug}.md"
-        if not rule_path.exists():
-            errors.append(f"rule slug `{slug}` has no file at {rule_path.relative_to(ROOT)}")
+        if not _rule_exists(slug):
+            errors.append(f"rule slug `{slug}` has no file under any source root (rules/{slug}.md)")
 
     pairs = data.get("pairs") or []
     if not isinstance(pairs, list) or not pairs:
@@ -124,7 +142,7 @@ def main() -> int:
                 errors.append(f"pair `{pid}` evidence item not a string: {citation!r}")
                 continue
             file_part = citation.split("#", 1)[0]
-            if not (ROOT / file_part).exists():
+            if not _evidence_exists(file_part):
                 errors.append(f"pair `{pid}` evidence path does not exist: {file_part}")
 
         # Anchor coverage check

package/scripts/lint_rule_tiers.py

@@ -20,7 +20,12 @@ from pathlib import Path
 QUIET = "--quiet" in sys.argv
 
 REPO = Path(__file__).resolve().parents[1]
-RULES_DIR = REPO / ".agent-src.uncompressed" / "rules"
+
+# Rules live under every artefact root post-monorepo Phase 4.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _lib.agent_src import artefact_roots  # noqa: E402
+
+RULES_DIRS = [root / "rules" for root in artefact_roots() if (root / "rules").is_dir()]
 
 VALID_TIERS = frozenset({"1", "2a", "2b", "3", "safety-floor", "mechanical-already"})
 
@@ -41,9 +46,13 @@ def parse_tier(text: str) -> str | None:
 
 
 def main() -> int:
-    rules = sorted(RULES_DIR.glob("*.md"))
+    rules: list[Path] = []
+    for rules_dir in RULES_DIRS:
+        rules.extend(rules_dir.glob("*.md"))
+    rules.sort()
     if not rules:
-        print(f"lint_rule_tiers: no rules found under {RULES_DIR}", file=sys.stderr)
+        roots_label = ", ".join(str(d) for d in RULES_DIRS) or "<no rules root>"
+        print(f"lint_rule_tiers: no rules found under {roots_label}", file=sys.stderr)
         return 1
 
     missing: list[str] = []