@event4u/agent-config 2.11.0 → 2.13.0

package/scripts/measure_projection_bytes.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""Measure per-tool projection bytes.
+
+Phase 2.1 deliverable for `agents/roadmaps/step-1-v2-feedback-followup.md`
+(council finding U1 — the 0.45 % source/dist headline metric measures the
+wrong boundary). Replaces the single headline figure with per-tool numbers
+and an explicit projection-method label.
+
+Usage:
+    python3 scripts/measure_projection_bytes.py           # human-readable
+    python3 scripts/measure_projection_bytes.py --json    # machine-readable
+    python3 scripts/measure_projection_bytes.py --regenerate
+        # runs `task clean-tools && task generate-tools` with *all* tools
+        # enabled (via temporary .agent-tools.yml override) before measuring,
+        # then restores the original `.agent-tools.yml`. Use this to produce
+        # a complete table when the local repo only enables a subset.
+
+Output is intentionally non-cached and read fresh from disk every run.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import yaml
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+
+# (surface, kind, projection-method). Surface paths are relative to the repo
+# root. `kind` is "dir" (walk recursively) or "file" (single file size).
+SURFACES: list[tuple[str, str, str]] = [
+    (".agent-src.uncompressed", "dir", "verbose source (input)"),
+    (".agent-src", "dir", "source projection (path-rewrite + .npmignore)"),
+    (".augment", "dir", "Augment Code — copies (rules) + symlinks (skills/cmds)"),
+    (".claude", "dir", "Claude Code — pure symlinks"),
+    (".cursor", "dir", "Cursor — per-rule `.mdc` materialized + symlinks"),
+    (".clinerules", "dir", "Cline — pure symlinks"),
+    (".windsurf", "dir", "Windsurf — per-rule wave-8 `.md` + symlinks"),
+    (".windsurfrules", "file", "Windsurf legacy — concatenated single file"),
+    ("GEMINI.md", "file", "Gemini CLI — symlink → AGENTS.md"),
+]
+
+
+def _measure_dir(path: Path) -> tuple[int, int, int]:
+    """Return (file_count, symlink_count, materialized_bytes) for *path*."""
+    if not path.exists():
+        return (0, 0, 0)
+    files = 0
+    links = 0
+    size = 0
+    for p in path.rglob("*"):
+        if p.is_symlink():
+            links += 1
+        elif p.is_file():
+            files += 1
+            try:
+                size += p.stat().st_size
+            except OSError:
+                pass
+    return (files, links, size)
+
+
+def _measure_file(path: Path) -> tuple[int, int, int]:
+    if path.is_symlink():
+        return (0, 1, 0)
+    if path.is_file():
+        return (1, 0, path.stat().st_size)
+    return (0, 0, 0)
+
+
+def collect() -> list[dict]:
+    rows: list[dict] = []
+    for surface, kind, method in SURFACES:
+        path = PROJECT_ROOT / surface
+        files, links, size = (
+            _measure_dir(path) if kind == "dir" else _measure_file(path)
+        )
+        rows.append(
+            {
+                "surface": surface,
+                "kind": kind,
+                "method": method,
+                "files": files,
+                "symlinks": links,
+                "bytes_materialized": size,
+                "exists": files + links > 0,
+            }
+        )
+    return rows
+
+
+def _temporarily_enable_all_tools() -> str | None:
+    tools_file = PROJECT_ROOT / ".agent-tools.yml"
+    if not tools_file.exists():
+        return None
+    original = tools_file.read_text()
+    data = yaml.safe_load(original) or {}
+    data["tools"] = [
+        "claude-code", "claude-desktop", "augment", "copilot",
+        "cursor", "windsurf", "cline", "gemini",
+    ]
+    tools_file.write_text(
+        "# TEMPORARY override by measure_projection_bytes.py — restored on exit\n"
+        + yaml.safe_dump(data, sort_keys=False)
+    )
+    return original
+
+
+def regenerate_all() -> None:
+    backup = _temporarily_enable_all_tools()
+    try:
+        subprocess.run(["task", "clean-tools"], check=True, capture_output=True)
+        subprocess.run(["task", "generate-tools"], check=True, capture_output=True)
+    finally:
+        if backup is not None:
+            (PROJECT_ROOT / ".agent-tools.yml").write_text(backup)
+
+
+def render_table(rows: list[dict]) -> str:
+    width = max(len(r["surface"]) for r in rows)
+    lines = [f"{'Surface':<{width}}  Files  Symlinks  Bytes        Method"]
+    lines.append("-" * (width + 50))
+    for r in rows:
+        lines.append(
+            f"{r['surface']:<{width}}  {r['files']:>5}  {r['symlinks']:>8}  "
+            f"{r['bytes_materialized']:>10,}  {r['method']}"
+        )
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--json", action="store_true", help="machine-readable output")
+    parser.add_argument(
+        "--regenerate",
+        action="store_true",
+        help="regenerate all tool projections before measuring",
+    )
+    args = parser.parse_args()
+    if args.regenerate:
+        if not shutil.which("task"):
+            print("❌  `task` CLI required for --regenerate", file=sys.stderr)
+            return 2
+        regenerate_all()
+    rows = collect()
+    if args.json:
+        print(json.dumps({"surfaces": rows}, indent=2))
+    else:
+        print(render_table(rows))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/measure_roadmap_trajectory.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""Phase 5.1 — Roadmap commitment-history measurement.
+
+Walks `agents/roadmaps/archive/` and computes per-roadmap checkbox
+completion ratio at archival time. Output: one-line trajectory metric
+per roadmap, plus an aggregate `agents/reports/roadmap-trajectory.json`.
+
+Checkbox grammar (mirrors `scripts/roadmap_progress_check.py`):
+- `[ ]` — open
+- `[x]` — done
+- `[~]` — in-progress
+- `[-]` — cancelled / dropped (counts neither toward open nor closed)
+
+Trajectory metric = closed / (open + closed + in-progress); cancelled
+items are excluded from the denominator so a cleanly archived "we
+decided not to do this" doesn't dilute the score.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+ARCHIVE = ROOT / "agents" / "roadmaps" / "archive"
+REPORT = ROOT / "agents" / "reports" / "roadmap-trajectory.json"
+
+CHECKBOX = re.compile(r"^\s*[-*]\s*\[(?P<state>[ x~\-])\]", re.MULTILINE)
+
+
+def measure(path: Path) -> dict:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    counts = {"open": 0, "done": 0, "wip": 0, "cancelled": 0}
+    for m in CHECKBOX.finditer(text):
+        state = m.group("state")
+        if state == " ":
+            counts["open"] += 1
+        elif state == "x":
+            counts["done"] += 1
+        elif state == "~":
+            counts["wip"] += 1
+        elif state == "-":
+            counts["cancelled"] += 1
+    denom = counts["open"] + counts["done"] + counts["wip"]
+    ratio = (counts["done"] / denom) if denom else None
+    return {
+        "file": str(path.relative_to(ROOT)),
+        "counts": counts,
+        "completion_ratio": ratio,
+        "total_actionable": denom,
+    }
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--archive", default=str(ARCHIVE))
+    ap.add_argument("--report", default=str(REPORT))
+    ap.add_argument("--print-table", action="store_true")
+    args = ap.parse_args()
+
+    archive = Path(args.archive)
+    if not archive.exists():
+        print(f"❌  archive not found: {archive}", file=sys.stderr)
+        return 2
+
+    rows = [measure(p) for p in sorted(archive.glob("*.md"))]
+
+    # Aggregate: mean, median, count above 80%, count zero-completion
+    ratios = [r["completion_ratio"] for r in rows if r["completion_ratio"] is not None]
+    aggregate = {
+        "roadmaps": len(rows),
+        "scored": len(ratios),
+        "mean": (sum(ratios) / len(ratios)) if ratios else None,
+        "median": sorted(ratios)[len(ratios) // 2] if ratios else None,
+        "above_80pct": sum(1 for r in ratios if r >= 0.80),
+        "below_50pct": sum(1 for r in ratios if r < 0.50),
+        "zero_completion": sum(1 for r in ratios if r == 0.0),
+    }
+
+    out = Path(args.report)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(
+        json.dumps({"aggregate": aggregate, "rows": rows}, indent=2) + "\n",
+        encoding="utf-8",
+    )
+
+    print(f"✅  Wrote {out.relative_to(ROOT)}")
+    print(f"   roadmaps={aggregate['roadmaps']} scored={aggregate['scored']}")
+    if aggregate["mean"] is not None:
+        print(
+            f"   mean={aggregate['mean']:.1%}  median={aggregate['median']:.1%}  "
+            f"above_80%={aggregate['above_80pct']}  below_50%={aggregate['below_50pct']}  "
+            f"zero={aggregate['zero_completion']}"
+        )
+    if args.print_table:
+        print()
+        print(f"   {'file':70s} {'ratio':>7s} {'done':>5s} {'open':>5s} {'wip':>5s} {'cx':>5s}")
+        for r in sorted(rows, key=lambda x: (x["completion_ratio"] is None, -(x["completion_ratio"] or 0))):
+            ratio = "—" if r["completion_ratio"] is None else f"{r['completion_ratio']:.1%}"
+            print(
+                f"   {Path(r['file']).name:70s} {ratio:>7s} "
+                f"{r['counts']['done']:>5d} {r['counts']['open']:>5d} "
+                f"{r['counts']['wip']:>5d} {r['counts']['cancelled']:>5d}"
+            )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/probe_projection_fidelity.py

@@ -0,0 +1,202 @@
+#!/usr/bin/env python3
+"""Phase 4.2 — Probe per-tool projection fidelity against the fixture.
+
+Reads tests/fixtures/projection_fidelity/fixtures.yml, walks the
+projected trees (.augment/, .claude/, .cursor/, .clinerules/,
+.windsurfrules, .windsurf/), and records pass/fail/partial per check.
+
+Output: agents/reports/projection-fidelity.json + stdout summary.
+
+Pure stdlib (PyYAML reuse from scripts/_lib if installed; otherwise
+inline minimal YAML loader for the fixture's restricted shape).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+try:
+    import yaml  # type: ignore
+except ImportError:  # pragma: no cover
+    print("❌  PyYAML required (already a project dep)", file=sys.stderr)
+    sys.exit(2)
+
+ROOT = Path(__file__).resolve().parent.parent
+
+TREES = {
+    "augment": ROOT / ".augment",
+    "claude": ROOT / ".claude",
+    "cursor_mdc": ROOT / ".cursor" / "rules",
+    "cursor_commands": ROOT / ".cursor" / "commands",
+    "cline": ROOT / ".clinerules",
+    "windsurf": ROOT / ".windsurfrules",
+    "windsurf_workflows": ROOT / ".windsurf" / "workflows",
+}
+
+
+def parse_frontmatter(path: Path) -> tuple[dict, str]:
+    if not path.exists():
+        return {}, ""
+    text = path.read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        return {}, text
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        return {}, text
+    try:
+        fm = yaml.safe_load(parts[1]) or {}
+    except yaml.YAMLError:
+        fm = {}
+    return fm if isinstance(fm, dict) else {}, parts[2]
+
+
+def locate(tree_key: str, entry_type: str, src: str) -> Path | None:
+    """Locate the projected artefact in a given tree."""
+    name = Path(src).stem  # 'laravel-routing'
+    if entry_type == "rule":
+        if tree_key in ("augment", "claude"):
+            p = TREES[tree_key] / "rules" / Path(src).name
+            return p if p.exists() else None
+        if tree_key == "cursor_mdc":
+            p = TREES[tree_key] / f"{name}.mdc"
+            return p if p.exists() else None
+        if tree_key == "cline":
+            p = TREES[tree_key] / f"{name}.md"
+            return p if p.exists() else None
+        if tree_key == "windsurf":
+            return TREES[tree_key] if TREES[tree_key].exists() else None
+    if entry_type == "skill":
+        if tree_key in ("augment", "claude"):
+            p = TREES[tree_key] / "skills" / Path(src).parent.name / "SKILL.md"
+            return p if p.exists() else None
+    if entry_type == "command":
+        if tree_key == "augment":
+            p = TREES[tree_key] / "commands" / Path(src).name
+            return p if p.exists() else None
+        if tree_key == "claude":
+            p = TREES[tree_key] / "skills" / name / "SKILL.md"
+            return p if p.exists() else None
+        if tree_key == "cursor_commands":
+            p = TREES[tree_key] / f"{name}.md"
+            return p if p.exists() else None
+        if tree_key == "windsurf_workflows":
+            p = TREES[tree_key] / f"{name}.md"
+            return p if p.exists() else None
+    return None
+
+
+def check_entry(entry: dict) -> dict:
+    out = {"id": entry["id"], "type": entry["type"], "tier": entry.get("tier"), "results": {}}
+    for tool, spec in (entry.get("checks") or {}).items():
+        result = {"status": "pass", "details": []}
+        expect_present = spec.get("present", True)
+        path = locate(tool, entry["type"], entry["source"])
+
+        if tool == "windsurf" and spec.get("concatenated_in"):
+            fp = ROOT / spec["concatenated_in"]
+            if not fp.exists():
+                result["status"] = "fail"
+                result["details"].append(f"missing concat file {spec['concatenated_in']}")
+            else:
+                body = fp.read_text(encoding="utf-8")
+                needle = spec.get("body_contains")
+                if needle and needle not in body:
+                    result["status"] = "fail"
+                    result["details"].append(f"body missing '{needle}'")
+                if spec.get("routes_to_visible") is False and "routes_to" in body:
+                    result["details"].append("note: routes_to leaks into concat (info)")
+            out["results"][tool] = result
+            continue
+
+        if expect_present and path is None:
+            result["status"] = "fail"
+            result["details"].append("file not found")
+            out["results"][tool] = result
+            continue
+        if not expect_present:
+            if path is not None:
+                result["status"] = "fail"
+                result["details"].append(f"unexpected file at {path}")
+            else:
+                result["details"].append(f"absent (ok: {spec.get('rationale', '')})")
+            out["results"][tool] = result
+            continue
+
+        fm, body = parse_frontmatter(path)
+        for key in spec.get("frontmatter_keys", []) or []:
+            if key not in fm:
+                result["status"] = "fail"
+                result["details"].append(f"frontmatter missing '{key}'")
+        for key in spec.get("frontmatter_drops", []) or []:
+            if key in fm:
+                result["status"] = "fail"
+                result["details"].append(f"frontmatter unexpectedly contains '{key}'")
+        if spec.get("alwaysApply") is not None and fm.get("alwaysApply") != spec["alwaysApply"]:
+            result["status"] = "partial"
+            result["details"].append(
+                f"alwaysApply={fm.get('alwaysApply')!r} expected {spec['alwaysApply']!r}"
+            )
+        trig_kw = spec.get("triggers_keyword_contains") or []
+        trig_pp = spec.get("triggers_path_prefix_contains") or []
+        if trig_kw or trig_pp:
+            trigs = fm.get("triggers") or []
+            kws = [t.get("keyword") for t in trigs if isinstance(t, dict) and t.get("keyword")]
+            pps = [t.get("path_prefix") for t in trigs if isinstance(t, dict) and t.get("path_prefix")]
+            for kw in trig_kw:
+                if kw not in kws:
+                    result["status"] = "fail"
+                    result["details"].append(f"trigger keyword '{kw}' missing")
+            for pp in trig_pp:
+                if pp not in pps:
+                    result["status"] = "fail"
+                    result["details"].append(f"trigger path_prefix '{pp}' missing")
+        routes = spec.get("routes_to_contains") or []
+        if routes:
+            rt = fm.get("routes_to") or []
+            for r in routes:
+                if r not in rt:
+                    result["status"] = "fail"
+                    result["details"].append(f"routes_to missing '{r}'")
+        body_needle = spec.get("body_contains")
+        if body_needle and body_needle not in body:
+            result["status"] = "fail"
+            result["details"].append(f"body missing '{body_needle}'")
+        out["results"][tool] = result
+    return out
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--fixture", default="tests/fixtures/projection_fidelity/fixtures.yml")
+    ap.add_argument("--report", default="agents/reports/projection-fidelity.json")
+    args = ap.parse_args()
+
+    fixture = yaml.safe_load((ROOT / args.fixture).read_text(encoding="utf-8"))
+    entries = fixture.get("entries", [])
+    results = [check_entry(e) for e in entries]
+
+    summary = {"pass": 0, "partial": 0, "fail": 0}
+    for e in results:
+        for r in e["results"].values():
+            summary[r["status"]] += 1
+
+    report = {"summary": summary, "entries": results}
+    out = ROOT / args.report
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
+
+    print(f"✅  Wrote {args.report}")
+    print(f"   pass={summary['pass']} partial={summary['partial']} fail={summary['fail']}")
+    for e in results:
+        for tool, r in e["results"].items():
+            if r["status"] != "pass":
+                print(f"   {r['status']:7s} {e['id']:40s} {tool:18s} {'; '.join(r['details'])}")
+    return 0 if summary["fail"] == 0 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/run_skill_evals.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+"""Quantitative skill-eval orchestrator (skill-writing § 7).
+
+Scaffolds, aggregates, and reports sub-agent eval runs for a skill.
+
+Sub-agent SPAWNING is per-environment (Claude Code, Augment Code,
+council) and is left as a stub `_spawn_subagent(...)` that authors
+implement once for their environment. The rest of the loop —
+scaffold / aggregate / report — works out of the box and reads /
+writes JSON files in `runs/`.
+
+Layout per skill:
+
+    .agent-src.uncompressed/skills/{name}/evals/
+        evals.json
+        runs/                              # gitignored
+            {timestamp}-baseline/{scenario_id}/output.txt
+            {timestamp}-baseline/{scenario_id}/grade.json
+            {timestamp}-with-skill/{scenario_id}/output.txt
+            {timestamp}-with-skill/{scenario_id}/grade.json
+            {timestamp}-benchmark.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SKILLS_ROOT = REPO_ROOT / ".agent-src.uncompressed" / "skills"
+
+
+def _skill_dir(skill: str) -> Path:
+    p = SKILLS_ROOT / skill
+    if not p.is_dir():
+        sys.exit(f"error: skill {skill!r} not found at {p}")
+    return p
+
+
+def _evals_dir(skill: str) -> Path:
+    return _skill_dir(skill) / "evals"
+
+
+def _load_evals(skill: str) -> dict[str, Any]:
+    f = _evals_dir(skill) / "evals.json"
+    if not f.exists():
+        sys.exit(f"error: {f} not found — create it before scaffolding")
+    return json.loads(f.read_text(encoding="utf-8"))
+
+
+def _timestamp() -> str:
+    return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+
+
+def _spawn_subagent(prompt: str, *, load_skill: str | None) -> dict[str, Any]:
+    """STUB — implement per environment.
+
+    Must return {"output": str, "elapsed_s": float, "tokens_in": int,
+    "tokens_out": int}. When load_skill is None, run baseline; when
+    set, load that skill into the sub-agent's context.
+    """
+    raise NotImplementedError(
+        "implement _spawn_subagent for this environment (Claude Code, "
+        "Augment, council, ...) — see docstring contract"
+    )
+
+
+def _grade_assertions(output: str, run_dir: Path, assertions: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    results: list[dict[str, Any]] = []
+    for a in assertions:
+        kind = a.get("kind")
+        if kind == "contains":
+            ok = a["value"] in output
+            results.append({"kind": kind, "value": a["value"], "pass": ok})
+        elif kind == "file_exists":
+            ok = (run_dir / a["path"]).exists() or Path(a["path"]).exists()
+            results.append({"kind": kind, "path": a["path"], "pass": ok})
+        elif kind == "rubric":
+            results.append({"kind": kind, "criterion": a["criterion"], "pass": None,
+                            "note": "rubric grading requires sub-agent — fill in manually or via grader"})
+        else:
+            results.append({"kind": kind, "pass": False, "note": f"unknown assertion kind {kind!r}"})
+    return results
+
+
+def cmd_scaffold(skill: str) -> int:
+    spec = _load_evals(skill)
+    scenarios = spec.get("scenarios", [])
+    if not scenarios:
+        sys.exit("error: evals.json has no scenarios")
+    ts = _timestamp()
+    runs = _evals_dir(skill) / "runs"
+    for arm in ("baseline", "with-skill"):
+        for sc in scenarios:
+            d = runs / f"{ts}-{arm}" / sc["id"]
+            d.mkdir(parents=True, exist_ok=True)
+            (d / "meta.json").write_text(json.dumps({
+                "skill": skill, "arm": arm, "scenario_id": sc["id"],
+                "prompt": sc["prompt"], "assertions": sc.get("assertions", []),
+                "timestamp": ts,
+            }, indent=2) + "\n", encoding="utf-8")
+    print(f"scaffolded {len(scenarios)} scenarios × 2 arms at runs/{ts}-{{baseline,with-skill}}/")
+    print(f"timestamp: {ts}")
+    return 0
+
+
+def cmd_aggregate(skill: str, run: str) -> int:
+    runs = _evals_dir(skill) / "runs"
+    spec = _load_evals(skill)
+    bench: dict[str, Any] = {"skill": skill, "run": run, "generated_at": _timestamp(), "scenarios": []}
+    totals = {"baseline_pass": 0, "with_skill_pass": 0, "scenarios": 0}
+    for sc in spec.get("scenarios", []):
+        row: dict[str, Any] = {"id": sc["id"], "arms": {}}
+        for arm in ("baseline", "with-skill"):
+            run_dir = runs / f"{run}-{arm}" / sc["id"]
+            grade_f = run_dir / "grade.json"
+            if not grade_f.exists():
+                row["arms"][arm] = {"status": "missing", "pass_count": 0, "total": 0}
+                continue
+            g = json.loads(grade_f.read_text(encoding="utf-8"))
+            results = g.get("results", [])
+            passed = sum(1 for r in results if r.get("pass") is True)
+            row["arms"][arm] = {"status": "graded", "pass_count": passed, "total": len(results),
+                                 "elapsed_s": g.get("elapsed_s"), "tokens_in": g.get("tokens_in"),
+                                 "tokens_out": g.get("tokens_out")}
+            if arm == "baseline" and passed == len(results) and results:
+                totals["baseline_pass"] += 1
+            if arm == "with-skill" and passed == len(results) and results:
+                totals["with_skill_pass"] += 1
+        bench["scenarios"].append(row)
+        totals["scenarios"] += 1
+    bench["totals"] = totals
+    out = runs / f"{run}-benchmark.json"
+    out.write_text(json.dumps(bench, indent=2) + "\n", encoding="utf-8")
+    print(f"wrote {out.relative_to(REPO_ROOT)}")
+    print(f"  baseline pass: {totals['baseline_pass']}/{totals['scenarios']}")
+    print(f"  with-skill pass: {totals['with_skill_pass']}/{totals['scenarios']}")
+    return 0
+
+
+def cmd_report(skill: str, run: str) -> int:
+    bench_f = _evals_dir(skill) / "runs" / f"{run}-benchmark.json"
+    if not bench_f.exists():
+        sys.exit(f"error: {bench_f} not found — run aggregate first")
+    bench = json.loads(bench_f.read_text(encoding="utf-8"))
+    print(f"# Skill eval report — {skill} @ {run}\n")
+    print("| Scenario | Baseline | With skill | Δ tokens_out | Δ elapsed_s |")
+    print("|---|---|---|---|---|")
+    for sc in bench["scenarios"]:
+        b = sc["arms"].get("baseline", {})
+        w = sc["arms"].get("with-skill", {})
+        bp = f"{b.get('pass_count', 0)}/{b.get('total', 0)}"
+        wp = f"{w.get('pass_count', 0)}/{w.get('total', 0)}"
+        dt = (w.get("tokens_out") or 0) - (b.get("tokens_out") or 0)
+        de = (w.get("elapsed_s") or 0) - (b.get("elapsed_s") or 0)
+        print(f"| {sc['id']} | {bp} | {wp} | {dt:+d} | {de:+.2f} |")
+    t = bench["totals"]
+    print(f"\n**Totals:** baseline {t['baseline_pass']}/{t['scenarios']} · with-skill {t['with_skill_pass']}/{t['scenarios']}")
+    return 0
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    sub = p.add_subparsers(dest="cmd", required=True)
+    for name in ("scaffold", "aggregate", "report"):
+        sp = sub.add_parser(name)
+        sp.add_argument("skill")
+        if name != "scaffold":
+            sp.add_argument("--run", required=True, help="run timestamp (from scaffold output)")
+    args = p.parse_args()
+    if args.cmd == "scaffold":
+        return cmd_scaffold(args.skill)
+    if args.cmd == "aggregate":
+        return cmd_aggregate(args.skill, args.run)
+    if args.cmd == "report":
+        return cmd_report(args.skill, args.run)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/schemas/skill.schema.json

@@ -47,6 +47,10 @@
       "enum": ["senior"],
       "description": "Optional tier marker. `senior` opts the skill into the Senior-Tier Required Structure check (Context-First lead, Related Skills, Proactive Triggers, Output Artifacts) per .agent-src.uncompressed/rules/skill-quality.md."
     },
+    "meta_skill": {
+      "type": "boolean",
+      "description": "Opt-out of the linter's `skill_too_large` warn for skills whose purpose IS breadth (skill-writing, agent-docs-writing, skill-reviewer). Meta-skills inherently bundle multiple procedures and inline examples. Use sparingly — every meta_skill: true is a load-on-context trade-off."
+    },
     "external_source": {
       "type": "string",
       "format": "uri",