@event4u/agent-config 2.12.0 → 2.14.0

package/scripts/install.sh

@@ -787,6 +787,18 @@ main() {
         echo ""
         echo "✅  agent-config payload synced."
         echo "    Run scripts/install (or python3 scripts/install.py) to render .agent-settings.yml and bridges."
+        # step-9 P11 · U1 — airgap detection. Probe DNS for provider hosts;
+        # on first-run with no reachable backend, surface the banner so the
+        # installer caller can flip defaults.member_mode to `api`.
+        if command -v python3 >/dev/null 2>&1; then
+            local airgap_mode
+            airgap_mode="$(python3 "$SOURCE_DIR/scripts/ai_council/airgap.py" 2>/dev/null || true)"
+            if [[ "$airgap_mode" == "api" ]]; then
+                echo ""
+                echo "⚠️  airgapped environment detected — defaulting to mode: api"
+                echo "    Set defaults.member_mode: api in agents/.ai-council.yml when configuring the council."
+            fi
+        fi
     elif ! $QUIET; then
         echo "✅  agent-config payload synced."
     fi

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())