@event4u/agent-config 3.0.0 → 3.1.1

package/scripts/lint_trust_coherence.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""Lint trust/safety coherence across the discovery manifest.
+
+Phase 5.4 of the monorepo trust-and-safety layer. Walks the freshly
+built `dist/discovery/discovery-manifest.json` and asserts three
+invariants:
+
+  1. Every pack whose ``trust_summary`` declares ``advisory`` or
+     ``restricted`` artefacts ships at least one ``*safety-floor*``
+     rule in the same pack.
+  2. Every artefact with ``trust.human_review_required: true`` carries
+     the ``_HRR_BANNER_MARKER`` in its compiled output under
+     ``.agent-src/<logical>``.
+  3. Every rule listed in ``router.json`` ``kernel[]`` declares
+     ``trust.level: core`` (no escalation to advisory/restricted,
+     no demotion to experimental).
+
+Exits 0 clean, 1 on any violation. Stdlib + pyyaml. Cap: ≤ 200 LOC.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+ROOT = Path(__file__).resolve().parents[1]
+MANIFEST = ROOT / "dist" / "discovery" / "discovery-manifest.json"
+ROUTER = ROOT / "dist" / "router.json"
+COMPILED_SRC = ROOT / ".agent-src"
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _lib.agent_src import strip_source_prefix  # noqa: E402
+
+# Imported lazily inside _banner_marker() to keep the cap loose if compress.py
+# grows additional top-level side effects.
+_BANNER_MARKER = "<!-- agent-config:human-review-banner -->"
+
+# Trust levels that demand a domain-safety floor in the same pack.
+_FLAGGED_LEVELS = ("advisory", "restricted")
+_SAFETY_FLOOR_FRAGMENT = "safety-floor"
+
+
+def _load_manifest(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        raise SystemExit(
+            f"ERROR: manifest not found: {path}\n"
+            "  Run `task build-discovery` first."
+        )
+    return json.loads(path.read_text("utf-8"))
+
+
+def _load_kernel(path: Path) -> set[str]:
+    if not path.exists():
+        raise SystemExit(f"ERROR: router.json not found: {path}")
+    data = json.loads(path.read_text("utf-8"))
+    kernel = data.get("kernel") or []
+    if not isinstance(kernel, list):
+        raise SystemExit("ERROR: router.json `kernel` must be a list")
+    return {str(name) for name in kernel}
+
+
+def _check_pack_safety_floors(manifest: dict[str, Any]) -> list[str]:
+    """Check 1: advisory/restricted packs ship a *safety-floor* rule."""
+    errs: list[str] = []
+    # Build pack -> [artefact path] index from the artefact list so we can
+    # spot the safety-floor regardless of how trust_summary was computed.
+    pack_paths: dict[str, list[str]] = {}
+    for art in manifest.get("artefacts", []):
+        for pack in art.get("packs", []) or []:
+            pack_paths.setdefault(pack, []).append(art["path"])
+
+    for pack in manifest.get("packs", []):
+        summary = pack.get("trust_summary", {}) or {}
+        flagged_total = sum(int(summary.get(lvl, 0)) for lvl in _FLAGGED_LEVELS)
+        if flagged_total == 0:
+            continue
+        paths = pack_paths.get(pack["id"], [])
+        has_floor = any(_SAFETY_FLOOR_FRAGMENT in p for p in paths)
+        if not has_floor:
+            counts = ", ".join(
+                f"{lvl}={int(summary.get(lvl, 0))}" for lvl in _FLAGGED_LEVELS
+            )
+            errs.append(
+                f"pack `{pack['id']}` declares flagged artefacts ({counts})"
+                f" but ships no `*{_SAFETY_FLOOR_FRAGMENT}*` rule"
+            )
+    return errs
+
+
+def _check_human_review_banners(
+    manifest: dict[str, Any], compiled_src: Path
+) -> list[str]:
+    """Check 2: every human_review_required artefact has the banner."""
+    errs: list[str] = []
+    for art in manifest.get("artefacts", []):
+        trust = art.get("trust", {}) or {}
+        if not trust.get("human_review_required"):
+            continue
+        rel = art["path"]
+        logical = strip_source_prefix(rel)
+        if logical is None:
+            errs.append(
+                f"{rel}: human_review_required=true but path is not under"
+                " any known source root"
+            )
+            continue
+        compiled = compiled_src / logical
+        if not compiled.exists():
+            errs.append(
+                f"{rel}: human_review_required=true but compiled output"
+                f" missing at `{compiled.relative_to(ROOT)}`"
+            )
+            continue
+        body = compiled.read_text("utf-8", errors="replace")
+        if _BANNER_MARKER not in body:
+            errs.append(
+                f"{rel}: human_review_required=true but compiled output"
+                f" `{compiled.relative_to(ROOT)}` is missing the HRR banner"
+                f" (`{_BANNER_MARKER}`) — re-run `task compress`."
+            )
+    return errs
+
+
+def _check_kernel_trust(
+    manifest: dict[str, Any], kernel: set[str]
+) -> list[str]:
+    """Check 3: every kernel rule declares trust.level=core."""
+    errs: list[str] = []
+    # name -> artefact for category=rule entries. Manifest does not always
+    # populate `name` for rules, so fall back to the logical filename stem.
+    rule_by_name: dict[str, dict[str, Any]] = {}
+    for art in manifest.get("artefacts", []):
+        if art.get("category") != "rule":
+            continue
+        name = art.get("name")
+        if not name:
+            logical = strip_source_prefix(art.get("path", ""))
+            if logical is None:
+                continue
+            stem = Path(logical).stem
+            name = stem
+        rule_by_name[name] = art
+
+    for kname in sorted(kernel):
+        art = rule_by_name.get(kname)
+        if art is None:
+            errs.append(
+                f"kernel rule `{kname}` listed in router.json but no"
+                " matching artefact in manifest"
+            )
+            continue
+        level = (art.get("trust", {}) or {}).get("level")
+        if level != "core":
+            errs.append(
+                f"kernel rule `{kname}` has trust.level=`{level}`"
+                " — must be `core` (router.json kernel guarantees Iron-Law"
+                " floor)"
+            )
+    return errs
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--quiet", action="store_true")
+    parser.add_argument(
+        "--manifest", type=Path, default=MANIFEST, help="discovery manifest"
+    )
+    parser.add_argument(
+        "--router", type=Path, default=ROUTER, help="router.json with kernel[]"
+    )
+    parser.add_argument(
+        "--compiled-src",
+        type=Path,
+        default=COMPILED_SRC,
+        help="compiled output root (.agent-src/)",
+    )
+    args = parser.parse_args(argv)
+
+    manifest = _load_manifest(args.manifest)
+    kernel = _load_kernel(args.router)
+
+    errs: list[str] = []
+    errs.extend(_check_pack_safety_floors(manifest))
+    errs.extend(_check_human_review_banners(manifest, args.compiled_src))
+    errs.extend(_check_kernel_trust(manifest, kernel))
+
+    if errs:
+        for e in errs:
+            print(f"ERROR: {e}", file=sys.stderr)
+        print(
+            f"\n{len(errs)} trust-coherence violation(s) across"
+            f" {len(manifest.get('packs', []))} pack(s) and"
+            f" {len(manifest.get('artefacts', []))} artefact(s).",
+            file=sys.stderr,
+        )
+        return 1
+
+    if not args.quiet:
+        print(
+            "✅  lint-trust-coherence:"
+            f" {len(manifest.get('packs', []))} pack(s),"
+            f" {len(kernel)} kernel rule(s),"
+            f" {sum(1 for a in manifest.get('artefacts', []) if (a.get('trust') or {}).get('human_review_required'))}"
+            " HRR artefact(s) clean."
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/measure_rule_budget.py

@@ -26,7 +26,9 @@ import sys
 from pathlib import Path
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
-RULES_DIR = REPO_ROOT / ".agent-src.uncompressed" / "rules"
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+from _lib.agent_src import artefact_roots  # noqa: E402
+
 OVERRIDES_FILE = REPO_ROOT / "docs" / "contracts" / "iron-law-overrides.txt"
 TREND_FILE = REPO_ROOT / "agents" / "runtime" / ".rule-budget-history.jsonl"
 
@@ -93,8 +95,24 @@ def measure_rule(path: Path) -> dict[str, object]:
 
 
 def collect() -> list[dict[str, object]]:
-    rules = [measure_rule(p) for p in sorted(RULES_DIR.glob("*.md"))]
-    return rules
+    """Collect rule measurements from every source root (multi-root aware).
+
+    Pre-move: reads .agent-src.uncompressed/rules/*.md.
+    Post-move (ADR-017): reads packages/*/.agent-src.uncompressed/rules/*.md.
+    Deduplicates on logical rule id (stem) — first root wins.
+    """
+    seen: set[str] = set()
+    rules: list[dict[str, object]] = []
+    for root in artefact_roots():
+        rules_dir = root / "rules"
+        if not rules_dir.is_dir():
+            continue
+        for p in sorted(rules_dir.glob("*.md")):
+            if p.stem in seen:
+                continue
+            seen.add(p.stem)
+            rules.append(measure_rule(p))
+    return sorted(rules, key=lambda r: r["id"])
 
 
 def load_overrides() -> set[str]:
@@ -138,7 +156,7 @@ def aggregate(rules: list[dict[str, object]]) -> dict[str, object]:
 
 def render_table(rules: list[dict[str, object]], agg: dict[str, object]) -> str:
     lines: list[str] = []
-    lines.append("Rule budget — source: .agent-src.uncompressed/rules/")
+    lines.append("Rule budget — source: rules/ under every artefact root (multi-root aware, ADR-017)")
     lines.append("")
     lines.append(f"{'id':<40} {'type':<7} {'tier':<5} {'chars':>7}")
     lines.append("-" * 62)

package/scripts/move_artefact.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Move a single artefact between packs via ``git mv`` (history-preserving).
+
+Phase 4.5 of the monorepo migration (ADR-017). Locates the artefact by
+slug or logical path, computes its destination under the requested
+pack, runs ``git mv`` for the artefact directory (skills/commands) or
+the single file (rules), and rewrites the ``packs:`` frontmatter so the
+discovery manifest stays in sync.
+
+CLI:
+  --id ID            artefact slug (skill/command name or rule stem)
+  --type TYPE        skill | rule | command (required when --id ambiguous)
+  --to PACK          target pack id (e.g. ``laravel``, ``core``)
+  --dry-run          print the planned move and frontmatter edit, no FS changes
+"""
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+PACKAGES = ROOT / "packages"
+PACKS_VOCAB = ROOT / "config" / "discovery" / "packs.yml"
+
+
+def _list_pack_ids() -> set[str]:
+    data = yaml.safe_load(PACKS_VOCAB.read_text(encoding="utf-8")) or []
+    return {p["id"] for p in data} | {"core"}
+
+
+def _pack_dir(pack_id: str) -> Path:
+    return PACKAGES / ("core" if pack_id == "core" else f"pack-{pack_id}")
+
+
+def _find_artefact(slug: str, kind: str | None) -> tuple[Path, str, str]:
+    """Return (physical_path, detected_kind, current_pack_id)."""
+    hits: list[tuple[Path, str, str]] = []
+    for pkg in sorted(PACKAGES.iterdir()):
+        src = pkg / ".agent-src.uncompressed"
+        if not src.is_dir():
+            continue
+        pid = "core" if pkg.name == "core" else pkg.name.removeprefix("pack-")
+        for k, rel in (("skill", f"skills/{slug}/SKILL.md"),
+                        ("rule", f"rules/{slug}.md"),
+                        ("command", f"commands/{slug}.md")):
+            p = src / rel
+            if p.exists() and (kind is None or kind == k):
+                hits.append((p, k, pid))
+    if not hits:
+        raise SystemExit(f"error: artefact '{slug}' not found under any pack")
+    if len(hits) > 1 and kind is None:
+        kinds = ", ".join(sorted({h[1] for h in hits}))
+        raise SystemExit(f"error: '{slug}' ambiguous (found as: {kinds}); pass --type")
+    return hits[0]
+
+
+def _move_root(path: Path, kind: str) -> Path:
+    """Return the path to git-mv (directory for skills, file for rule/command)."""
+    return path.parent if kind == "skill" else path
+
+
+def _rewrite_packs(md_path: Path, new_pack: str, dry_run: bool) -> bool:
+    text = md_path.read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        return False
+    end = text.find("\n---", 4)
+    if end == -1:
+        return False
+    head = text[4:end]
+    body = text[end:]
+    fm = yaml.safe_load(head) or {}
+    if not isinstance(fm, dict):
+        return False
+    current = fm.get("packs") or []
+    desired = [] if new_pack == "core" else [new_pack]
+    if current == desired:
+        return False
+    if desired:
+        fm["packs"] = desired
+    else:
+        fm.pop("packs", None)
+    new_text = "---\n" + yaml.safe_dump(fm, sort_keys=False, allow_unicode=True) + body[1:]
+    if dry_run:
+        print(f"  would rewrite frontmatter packs: {current} -> {desired}")
+    else:
+        md_path.write_text(new_text, encoding="utf-8")
+        print(f"  rewrote frontmatter packs: {current} -> {desired}")
+    return True
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--id", required=True, help="artefact slug")
+    ap.add_argument("--to", required=True, help="target pack id")
+    ap.add_argument("--type", choices=["skill", "rule", "command"])
+    ap.add_argument("--dry-run", action="store_true")
+    args = ap.parse_args()
+
+    vocab = _list_pack_ids()
+    if args.to not in vocab:
+        print(f"error: target pack '{args.to}' not in {sorted(vocab)}", file=sys.stderr)
+        return 2
+
+    src_md, kind, current_pack = _find_artefact(args.id, args.type)
+    if current_pack == args.to:
+        print(f"no-op: '{args.id}' already lives in pack '{args.to}'")
+        return 0
+
+    src_root = _move_root(src_md, kind)
+    dest_pkg_src = _pack_dir(args.to) / ".agent-src.uncompressed"
+    rel_under_pack = src_root.relative_to(_pack_dir(current_pack) / ".agent-src.uncompressed")
+    dest_root = dest_pkg_src / rel_under_pack
+
+    print(f"plan: {kind} '{args.id}' : {current_pack} -> {args.to}")
+    print(f"  git mv {src_root.relative_to(ROOT)} {dest_root.relative_to(ROOT)}")
+
+    # Frontmatter must be rewritten BEFORE the move so the new physical
+    # location matches the declared pack. Discovery scanner cross-checks.
+    _rewrite_packs(src_md, args.to, args.dry_run)
+
+    if args.dry_run:
+        print("dry-run: no FS changes")
+        return 0
+
+    dest_root.parent.mkdir(parents=True, exist_ok=True)
+    result = subprocess.run(
+        ["git", "mv", str(src_root.relative_to(ROOT)), str(dest_root.relative_to(ROOT))],
+        cwd=ROOT, capture_output=True, text=True,
+    )
+    if result.returncode != 0:
+        print(f"git mv failed: {result.stderr}", file=sys.stderr)
+        return result.returncode
+    print(f"moved: {src_root.relative_to(ROOT)} -> {dest_root.relative_to(ROOT)}")
+    print("next: run `task sync` and `task lint-pack-boundaries`")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/new_skill.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Interactive scaffolder for new skills under the packages/ layout.
+
+Phase 4.5 of the monorepo migration (ADR-017). Asks for pack, type,
+name, workspaces, and description, then drops a templated artefact
+into ``packages/<pack-dir>/.agent-src.uncompressed/<type>s/<name>/SKILL.md``.
+
+Type → directory mapping:
+  - skill    → skills/<name>/SKILL.md
+  - rule     → rules/<name>.md
+  - command  → commands/<name>.md
+
+CLI (non-interactive overrides):
+  --pack PACK         pack id (e.g. ``laravel`` or ``core``)
+  --type TYPE         skill | rule | command (default: skill)
+  --name NAME         artefact slug (kebab-case)
+  --description TEXT  one-line description (trigger phrasing)
+  --workspace WS      repeatable; defaults to pack's owner list
+  --force             overwrite if file exists
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+PACKAGES = ROOT / "packages"
+PACKS_VOCAB = ROOT / "config" / "discovery" / "packs.yml"
+
+TEMPLATES = {
+    "skill": "skills/{name}/SKILL.md",
+    "rule": "rules/{name}.md",
+    "command": "commands/{name}.md",
+}
+
+
+def _load_vocab() -> dict[str, dict[str, Any]]:
+    if not PACKS_VOCAB.exists():
+        return {}
+    data = yaml.safe_load(PACKS_VOCAB.read_text(encoding="utf-8")) or []
+    return {p["id"]: p for p in data}
+
+
+def _list_packs() -> list[str]:
+    if not PACKAGES.exists():
+        return []
+    return sorted([
+        ("core" if p.name == "core" else p.name.removeprefix("pack-"))
+        for p in PACKAGES.iterdir() if p.is_dir()
+    ])
+
+
+def _pack_dir(pack_id: str) -> Path:
+    return PACKAGES / ("core" if pack_id == "core" else f"pack-{pack_id}")
+
+
+def _prompt(label: str, default: str | None = None, choices: list[str] | None = None) -> str:
+    suffix = f" [{default}]" if default else ""
+    if choices:
+        suffix = f" ({'/'.join(choices)})" + suffix
+    while True:
+        raw = input(f"{label}{suffix}: ").strip()
+        if not raw and default is not None:
+            return default
+        if choices and raw not in choices:
+            print(f"  must be one of: {', '.join(choices)}")
+            continue
+        if raw:
+            return raw
+
+
+def _frontmatter(name: str, description: str, workspaces: list[str], pack: str) -> str:
+    fm: dict[str, Any] = {
+        "name": name,
+        "description": description,
+        "source": "package",
+        "workspaces": workspaces,
+        "packs": [pack] if pack != "core" else [],
+        "lifecycle": "active",
+        "trust": {"level": "professional", "confidence": "medium", "human_review_required": False},
+        "install": {"default": False, "removable": True},
+    }
+    if not fm["packs"]:
+        del fm["packs"]
+    return "---\n" + yaml.safe_dump(fm, sort_keys=False, allow_unicode=True) + "---\n"
+
+
+def _body(kind: str, name: str, description: str) -> str:
+    if kind == "skill":
+        return (
+            f"\n# {name}\n\n## When to use\n\n{description}\n\n## Procedure\n\n"
+            "1. _TODO: replace with the real step-by-step._\n\n"
+            "## Examples\n\n_TODO: copy-pasteable example._\n"
+        )
+    if kind == "rule":
+        return f"\n# {name}\n\n{description}\n\n## Iron Law\n\n```\nTODO\n```\n"
+    return f"\n# {name}\n\n{description}\n\n## Steps\n\n1. _TODO_\n"
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--pack")
+    ap.add_argument("--type", dest="kind", choices=list(TEMPLATES))
+    ap.add_argument("--name")
+    ap.add_argument("--description")
+    ap.add_argument("--workspace", action="append", default=[])
+    ap.add_argument("--force", action="store_true")
+    args = ap.parse_args()
+
+    packs = _list_packs()
+    if not packs:
+        print("error: no packages/ tree found", file=sys.stderr)
+        return 2
+    vocab = _load_vocab()
+    interactive = sys.stdin.isatty()
+    pack = args.pack or (_prompt("pack", default="core", choices=packs) if interactive else "core")
+    if pack not in packs:
+        print(f"error: pack '{pack}' not in {packs}", file=sys.stderr)
+        return 2
+    kind = args.kind or (_prompt("type", default="skill", choices=list(TEMPLATES)) if interactive else "skill")
+    name = args.name or (_prompt("name (kebab-case)") if interactive else "")
+    if not name or " " in name or name != name.lower():
+        print(f"error: name '{name}' must be lowercase kebab-case", file=sys.stderr)
+        return 2
+    description = args.description or (_prompt("description (one line)") if interactive else "TODO: describe trigger")
+    workspaces = args.workspace or vocab.get(pack, {}).get("workspaces") or ["engineering"]
+
+    rel = TEMPLATES[kind].format(name=name)
+    out = _pack_dir(pack) / ".agent-src.uncompressed" / rel
+    if out.exists() and not args.force:
+        print(f"error: {out.relative_to(ROOT)} exists (use --force)", file=sys.stderr)
+        return 1
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(_frontmatter(name, description, workspaces, pack) + _body(kind, name, description), encoding="utf-8")
+    print(f"created: {out.relative_to(ROOT)}")
+    print("next steps:")
+    print("  1. flesh out the body")
+    print("  2. run `task sync` to project into .agent-src/ and .augment/")
+    print("  3. run `task lint-skills` for validation")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())