@event4u/agent-config 1.15.0 → 1.17.0

package/scripts/generate_index.py

@@ -0,0 +1,270 @@
+#!/usr/bin/env python3
+"""Generate `agents/index.md` (internal) and `docs/catalog.md` (public).
+
+Scans `.agent-src.uncompressed/{skills,rules,commands}/` plus `docs/guidelines/`
+and renders two artefact tables — one for maintainers, one for consumers.
+
+Both files are sync-checked in CI via `--check`; drift = build break.
+
+Usage:
+    python3 scripts/generate_index.py            # write both files
+    python3 scripts/generate_index.py --check    # exit 1 if drift
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SRC = ROOT / ".agent-src.uncompressed"
+GUIDELINES = ROOT / "docs" / "guidelines"
+INDEX_PATH = ROOT / "agents" / "index.md"
+CATALOG_PATH = ROOT / "docs" / "catalog.md"
+
+# Internal-only rules — excluded from the public catalog.
+INTERNAL_RULES = {
+    "augment-source-of-truth",
+    "augment-portability",
+    "docs-sync",
+}
+
+FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+
+
+@dataclass(frozen=True)
+class Entry:
+    kind: str          # skill | rule | command | shim | guideline
+    name: str
+    description: str
+    extra: str         # rule type · cluster · sub-folder, etc.
+    path: str          # repo-relative link target
+
+
+def _parse_frontmatter(text: str) -> dict[str, str]:
+    m = FRONTMATTER_RE.match(text)
+    if not m:
+        return {}
+    out: dict[str, str] = {}
+    for line in m.group(1).splitlines():
+        if ":" not in line or line.startswith(" "):
+            continue
+        k, _, v = line.partition(":")
+        out[k.strip()] = v.strip().strip('"').strip("'")
+    return out
+
+
+def _truncate(text: str, limit: int = 200) -> str:
+    text = text.replace("|", "\\|").replace("\n", " ").strip()
+    return text if len(text) <= limit else text[: limit - 1].rstrip() + "…"
+
+
+def _collect_skills() -> list[Entry]:
+    out = []
+    for skill_dir in sorted((SRC / "skills").iterdir()):
+        skill_md = skill_dir / "SKILL.md"
+        if not skill_md.exists():
+            continue
+        fm = _parse_frontmatter(skill_md.read_text(encoding="utf-8"))
+        name = fm.get("name") or skill_dir.name
+        out.append(Entry(
+            kind="skill",
+            name=name,
+            description=_truncate(fm.get("description", "")),
+            extra="",
+            path=f".agent-src.uncompressed/skills/{skill_dir.name}/SKILL.md",
+        ))
+    return out
+
+
+def _collect_rules() -> list[Entry]:
+    out = []
+    for rule_md in sorted((SRC / "rules").glob("*.md")):
+        fm = _parse_frontmatter(rule_md.read_text(encoding="utf-8"))
+        out.append(Entry(
+            kind="rule",
+            name=rule_md.stem,
+            description=_truncate(fm.get("description", "")),
+            extra=fm.get("type", "?"),
+            path=f".agent-src.uncompressed/rules/{rule_md.name}",
+        ))
+    return out
+
+
+def _collect_commands() -> list[Entry]:
+    out = []
+    cmd_dir = SRC / "commands"
+    for cmd_md in sorted(cmd_dir.rglob("*.md")):
+        if cmd_md.name == "AGENTS.md":
+            continue
+        fm = _parse_frontmatter(cmd_md.read_text(encoding="utf-8"))
+        is_shim = bool(fm.get("superseded_by"))
+        extra = ""
+        if is_shim:
+            extra = f"shim → /{fm['superseded_by']}"
+        elif fm.get("cluster"):
+            extra = f"cluster: {fm['cluster']}"
+        rel = cmd_md.relative_to(cmd_dir)
+        out.append(Entry(
+            kind="shim" if is_shim else "command",
+            name=fm.get("name") or cmd_md.stem,
+            description=_truncate(fm.get("description", "")),
+            extra=extra,
+            path=f".agent-src.uncompressed/commands/{rel}",
+        ))
+    return out
+
+
+def _collect_guidelines() -> list[Entry]:
+    out = []
+    if not GUIDELINES.exists():
+        return out
+    for g_md in sorted(GUIDELINES.rglob("*.md")):
+        rel = g_md.relative_to(ROOT)
+        category = g_md.parent.name if g_md.parent != GUIDELINES else "(root)"
+        out.append(Entry(
+            kind="guideline",
+            name=g_md.stem,
+            description="",
+            extra=category,
+            path=str(rel),
+        ))
+    return out
+
+
+# Path rewriter for the public catalog: link to the shipped surface
+# (`.agent-src/`) instead of the source-of-truth (`.agent-src.uncompressed/`),
+# which is excluded from `package.json#files` and `composer.json` archives.
+def _to_shipped_path(path: str) -> str:
+    return path.replace(".agent-src.uncompressed/", ".agent-src/", 1)
+
+
+def _render_table(
+    entries: list[Entry],
+    cols: list[str],
+    link_prefix: str,
+    path_rewrite=None,
+) -> str:
+    rows = ["| " + " | ".join(cols) + " |", "|" + "|".join(["---"] * len(cols)) + "|"]
+    for e in entries:
+        path = path_rewrite(e.path) if path_rewrite else e.path
+        link = f"[`{e.name}`]({link_prefix}{path})"
+        row = [e.kind, link, e.extra, e.description]
+        rows.append("| " + " | ".join(row) + " |")
+    return "\n".join(rows)
+
+
+
+def _render_index(skills, rules, commands, guidelines) -> str:
+    total = len(skills) + len(rules) + len(commands) + len(guidelines)
+    parts = [
+        "# Agent-Config Internal Index",
+        "",
+        f"Maintainer-facing index of all **{total} artefacts** in this package.",
+        "Auto-generated from `.agent-src.uncompressed/` and `docs/guidelines/`.",
+        "",
+        "> **Regenerate:** `python3 scripts/generate_index.py`",
+        "> **Drift check:** `python3 scripts/generate_index.py --check` (runs in `task ci`)",
+        "> Do not edit manually.",
+        "",
+        f"## Skills ({len(skills)})",
+        "",
+        _render_table(skills, ["kind", "name", "extra", "description"], "../"),
+        "",
+        f"## Rules ({len(rules)})",
+        "",
+        _render_table(rules, ["kind", "name", "type", "description"], "../"),
+        "",
+        f"## Commands ({len(commands)})",
+        "",
+        _render_table(commands, ["kind", "name", "cluster/shim", "description"], "../"),
+        "",
+        f"## Guidelines ({len(guidelines)})",
+        "",
+        _render_table(guidelines, ["kind", "name", "category", "description"], "../"),
+        "",
+    ]
+    return "\n".join(parts)
+
+
+def _render_catalog(skills, rules, commands, guidelines) -> str:
+    public_rules = [r for r in rules if r.name not in INTERNAL_RULES]
+    public_commands = [c for c in commands if c.kind == "command"]
+    total = len(skills) + len(public_rules) + len(public_commands) + len(guidelines)
+    parts = [
+        "# agent-config — Public Catalog",
+        "",
+        f"Consumer-facing catalog of all **{total} public artefacts** shipped by",
+        "this package. Internal package-maintenance rules and deprecation shims",
+        "are excluded.",
+        "",
+        "> **Regenerate:** `python3 scripts/generate_index.py`",
+        "> Auto-generated — do not edit manually.",
+        "",
+        f"## Skills ({len(skills)})",
+        "",
+        _render_table(skills, ["kind", "name", "extra", "description"], "../", _to_shipped_path),
+        "",
+        f"## Rules ({len(public_rules)})",
+        "",
+        _render_table(public_rules, ["kind", "name", "type", "description"], "../", _to_shipped_path),
+        "",
+        f"## Commands ({len(public_commands)})",
+        "",
+        _render_table(public_commands, ["kind", "name", "cluster", "description"], "../", _to_shipped_path),
+        "",
+        f"## Guidelines ({len(guidelines)})",
+        "",
+        _render_table(guidelines, ["kind", "name", "category", "description"], "../", _to_shipped_path),
+        "",
+        "---",
+        "",
+        "← [Back to README](../README.md)",
+        "",
+    ]
+    return "\n".join(parts)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--check", action="store_true",
+                        help="Exit 1 if generated content differs from on-disk files.")
+    args = parser.parse_args()
+
+    skills = _collect_skills()
+    rules = _collect_rules()
+    commands = _collect_commands()
+    guidelines = _collect_guidelines()
+
+    index_text = _render_index(skills, rules, commands, guidelines)
+    catalog_text = _render_catalog(skills, rules, commands, guidelines)
+
+    if args.check:
+        drift = []
+        if not INDEX_PATH.exists() or INDEX_PATH.read_text(encoding="utf-8") != index_text:
+            drift.append(str(INDEX_PATH.relative_to(ROOT)))
+        if not CATALOG_PATH.exists() or CATALOG_PATH.read_text(encoding="utf-8") != catalog_text:
+            drift.append(str(CATALOG_PATH.relative_to(ROOT)))
+        if drift:
+            print("❌  Index drift detected — regenerate with:")
+            print("    python3 scripts/generate_index.py")
+            for d in drift:
+                print(f"    - {d}")
+            return 1
+        print("✅  Index files in sync.")
+        return 0
+
+    INDEX_PATH.parent.mkdir(parents=True, exist_ok=True)
+    CATALOG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    INDEX_PATH.write_text(index_text, encoding="utf-8")
+    CATALOG_PATH.write_text(catalog_text, encoding="utf-8")
+    print(f"✅  Wrote {INDEX_PATH.relative_to(ROOT)} ({len(skills)} skills, "
+          f"{len(rules)} rules, {len(commands)} commands, {len(guidelines)} guidelines)")
+    print(f"✅  Wrote {CATALOG_PATH.relative_to(ROOT)} (public subset)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/generate_ownership_matrix.py

@@ -0,0 +1,323 @@
+#!/usr/bin/env python3
+"""Generate the file-ownership matrix.
+
+Produces:
+
+  * docs/contracts/file-ownership-matrix.json (machine, internal-locked)
+  * agents/contexts/structural/file-ownership-matrix.md (human-readable)
+
+Walks `.agent-src.uncompressed/{rules,skills,commands,contexts,personas}/`,
+parses frontmatter for `load_context:` / `load_context_eager:`, scans
+markdown bodies for inline links to `.md` files inside the scanned roots,
+and emits READ_ONLY edges plus depth-2 transitive closure of load_context
+chains. Depth-3 chains abort the build (matches the 0.2.4 nesting cap).
+
+Contract: docs/contracts/file-ownership-matrix.md
+Roadmap:  road-to-structural-optimization.md § 0.1
+
+Modes:
+  --check      Regenerate to memory and diff against committed JSON.
+               Exit 0 if identical, 1 if drifted.
+  (default)    Regenerate JSON + MD in place; exit 0 on success.
+
+Exit codes: 0 = ok, 1 = drift (--check), 2 = depth-3 chain, 3 = internal.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable
+
+import yaml
+
+ROOT = Path(__file__).resolve().parent.parent
+SRC_ROOT = ROOT / ".agent-src.uncompressed"
+
+SCAN_DIRS = ("rules", "skills", "commands", "contexts", "personas")
+
+JSON_OUT = ROOT / "docs" / "contracts" / "file-ownership-matrix.json"
+MD_OUT = ROOT / "agents" / "contexts" / "structural" / "file-ownership-matrix.md"
+
+LINK_RE = re.compile(r"\]\(([^)]+\.md)(?:#[^)]*)?\)")
+
+
+@dataclass
+class FileEntry:
+    path: str
+    kind: str
+    rule_type: str | None = None
+    load_context: list[str] = field(default_factory=list)
+    load_context_eager: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Edge:
+    source: str
+    target: str
+    type: str
+    via: str
+    depth: int
+
+
+def _rel(p: Path) -> str:
+    return p.relative_to(ROOT).as_posix()
+
+
+def _kind_for(rel: str) -> str:
+    parts = rel.split("/")
+    if len(parts) >= 3 and parts[0] == ".agent-src.uncompressed":
+        return parts[1].rstrip("s") if parts[1] != "personas" else "persona"
+    return "unknown"
+
+
+def _parse_frontmatter(p: Path) -> dict:
+    text = p.read_text(encoding="utf-8")
+    if not text.startswith("---\n"):
+        return {}
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return {}
+    try:
+        data = yaml.safe_load(text[4:end])
+    except yaml.YAMLError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _collect_files(src_root: Path) -> list[Path]:
+    out: list[Path] = []
+    for sub in SCAN_DIRS:
+        d = src_root / sub
+        if d.exists():
+            out.extend(sorted(d.rglob("*.md")))
+    return out
+
+
+def _resolve(target: str, src_root: Path) -> Path | None:
+    """Resolve a path string (repo-relative or short) into an absolute Path
+    under src_root or the repo root. Return None if not under a scanned root."""
+    cand = src_root.parent / target if "/" in target else src_root / target
+    try:
+        rel = cand.resolve().relative_to(src_root.parent)
+    except ValueError:
+        return None
+    parts = rel.parts
+    if len(parts) >= 3 and parts[0] == ".agent-src.uncompressed" and parts[1] in SCAN_DIRS:
+        return cand if cand.exists() else None
+    return None
+
+
+def build_matrix(src_root: Path) -> tuple[dict[str, FileEntry], list[Edge], list[str]]:
+    """Build the file map + edge list. Returns (files, edges, depth3_chains).
+
+    depth3_chains is non-empty iff the depth invariant is violated; the
+    caller must abort with exit code 2.
+    """
+    files: dict[str, FileEntry] = {}
+    for f in _collect_files(src_root):
+        rel = f.relative_to(src_root.parent).as_posix()
+        fm = _parse_frontmatter(f)
+        rtype = fm.get("type")
+        if isinstance(rtype, str):
+            rtype = rtype.strip('"').strip("'")
+        else:
+            rtype = None
+        lazy = fm.get("load_context") or []
+        eager = fm.get("load_context_eager") or []
+        if not isinstance(lazy, list):
+            lazy = []
+        if not isinstance(eager, list):
+            eager = []
+        files[rel] = FileEntry(
+            path=rel,
+            kind=_kind_for(rel),
+            rule_type=rtype,
+            load_context=[str(x) for x in lazy if isinstance(x, str)],
+            load_context_eager=[str(x) for x in eager if isinstance(x, str)],
+        )
+
+    edges: list[Edge] = []
+    for rel, entry in files.items():
+        for tgt in entry.load_context:
+            edges.append(Edge(rel, tgt, "READ_ONLY", "load_context", 1))
+        for tgt in entry.load_context_eager:
+            edges.append(Edge(rel, tgt, "READ_ONLY", "load_context_eager", 1))
+
+    # Body markdown links — only count edges to files we know about
+    for rel, entry in files.items():
+        body = (src_root.parent / rel).read_text(encoding="utf-8")
+        body = body.split("\n---\n", 1)[-1] if body.startswith("---\n") else body
+        seen_targets: set[str] = set()
+        for m in LINK_RE.finditer(body):
+            href = m.group(1).strip()
+            if href.startswith("http"):
+                continue
+            resolved = _resolve_link(rel, href, src_root)
+            if resolved is None or resolved == rel or resolved in seen_targets:
+                continue
+            if resolved in files:
+                seen_targets.add(resolved)
+                edges.append(Edge(rel, resolved, "READ_ONLY", "body_link", 1))
+
+    # Transitive closure on load_context* edges, depth 2; depth 3 aborts.
+    lc_edges_by_src: dict[str, list[str]] = {}
+    for e in edges:
+        if e.via in ("load_context", "load_context_eager"):
+            lc_edges_by_src.setdefault(e.source, []).append(e.target)
+
+    transitive: list[Edge] = []
+    depth3: list[str] = []
+    for src, lvl1_targets in lc_edges_by_src.items():
+        for t1 in lvl1_targets:
+            for t2 in lc_edges_by_src.get(t1, []):
+                if t2 == src or t2 == t1:
+                    continue
+                transitive.append(Edge(src, t2, "READ_ONLY", "load_context_transitive", 2))
+                # depth-3 probe
+                for t3 in lc_edges_by_src.get(t2, []):
+                    if t3 in (src, t1, t2):
+                        continue
+                    depth3.append(f"{src} → {t1} → {t2} → {t3}")
+
+    edges.extend(transitive)
+    for rel in files:
+        edges.append(Edge(rel, rel, "WRITE", "self", 0))
+
+    edges.sort(key=lambda e: (e.source, e.target, e.via, e.depth))
+    return files, edges, depth3
+
+
+def _resolve_link(source_rel: str, href: str, src_root: Path) -> str | None:
+    """Resolve a markdown link href (relative to source file) to a repo-relative
+    path inside a scanned root, or None."""
+    if href.startswith(".agent-src.uncompressed/") or href.startswith("agents/"):
+        cand = (src_root.parent / href).resolve()
+    else:
+        base = (src_root.parent / source_rel).parent
+        cand = (base / href).resolve()
+    try:
+        rel = cand.relative_to(src_root.parent).as_posix()
+    except ValueError:
+        return None
+    parts = rel.split("/")
+    if len(parts) >= 3 and parts[0] == ".agent-src.uncompressed" and parts[1] in SCAN_DIRS:
+        return rel if cand.exists() else None
+    return None
+
+
+def _to_json(files: dict[str, FileEntry], edges: list[Edge]) -> dict:
+    return {
+        "version": 1,
+        "generated_by": "scripts/generate_ownership_matrix.py",
+        "source_of_truth": ".agent-src.uncompressed/",
+        "files": {
+            rel: {
+                "kind": e.kind,
+                "rule_type": e.rule_type,
+                "load_context": e.load_context,
+                "load_context_eager": e.load_context_eager,
+            }
+            for rel, e in sorted(files.items())
+        },
+        "edges": [
+            {
+                "source": e.source,
+                "target": e.target,
+                "type": e.type,
+                "via": e.via,
+                "depth": e.depth,
+            }
+            for e in edges
+        ],
+    }
+
+
+def _to_markdown(payload: dict) -> str:
+    lines: list[str] = [
+        "# File-ownership matrix (regenerated)",
+        "",
+        "> **Do not edit.** Regenerated by `scripts/generate_ownership_matrix.py`.",
+        "> Schema: [`docs/contracts/file-ownership-matrix.md`](../../../docs/contracts/file-ownership-matrix.md).",
+        "",
+        f"- Schema version: `{payload['version']}`",
+        f"- Source of truth: `{payload['source_of_truth']}`",
+        f"- Files indexed: **{len(payload['files'])}**",
+        f"- Edges (incl. self-WRITE): **{len(payload['edges'])}**",
+        "",
+        "## READ_ONLY edges",
+        "",
+        "| Source | Target | Via | Depth |",
+        "|---|---|---|---:|",
+    ]
+    ro = [e for e in payload["edges"] if e["type"] == "READ_ONLY"]
+    for e in ro:
+        lines.append(f"| `{e['source']}` | `{e['target']}` | `{e['via']}` | {e['depth']} |")
+    if not ro:
+        lines.append("| _(none)_ |  |  |  |")
+    lines += [
+        "",
+        "## Files by kind",
+        "",
+        "| Kind | Count |",
+        "|---|---:|",
+    ]
+    counts: dict[str, int] = {}
+    for f in payload["files"].values():
+        counts[f["kind"]] = counts.get(f["kind"], 0) + 1
+    for k in sorted(counts):
+        lines.append(f"| `{k}` | {counts[k]} |")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _write_outputs(payload: dict, json_out: Path, md_out: Path) -> None:
+    json_out.parent.mkdir(parents=True, exist_ok=True)
+    md_out.parent.mkdir(parents=True, exist_ok=True)
+    json_out.write_text(json.dumps(payload, indent=2, sort_keys=False) + "\n", encoding="utf-8")
+    md_out.write_text(_to_markdown(payload) + "\n", encoding="utf-8")
+
+
+def main(argv: Iterable[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--check", action="store_true",
+                    help="Regenerate to memory and diff against committed JSON.")
+    args = ap.parse_args(list(argv) if argv is not None else None)
+
+    if not SRC_ROOT.is_dir():
+        print(f"❌  source dir missing: {SRC_ROOT}", file=sys.stderr)
+        return 3
+
+    files, edges, depth3 = build_matrix(SRC_ROOT)
+    if depth3:
+        print("❌  load_context depth-3 chain detected (limit is 2):", file=sys.stderr)
+        for chain in depth3:
+            print(f"  🔴 {chain}", file=sys.stderr)
+        return 2
+
+    payload = _to_json(files, edges)
+
+    if args.check:
+        if not JSON_OUT.exists():
+            print(f"❌  {JSON_OUT.relative_to(ROOT)} not committed; run `task generate-ownership-matrix`",
+                  file=sys.stderr)
+            return 1
+        committed = json.loads(JSON_OUT.read_text(encoding="utf-8"))
+        if committed != payload:
+            print("❌  ownership matrix is stale — run `task generate-ownership-matrix` and commit",
+                  file=sys.stderr)
+            return 1
+        print(f"✅  ownership matrix in sync ({len(files)} files, {len(edges)} edges)")
+        return 0
+
+    _write_outputs(payload, JSON_OUT, MD_OUT)
+    print(f"✅  wrote {JSON_OUT.relative_to(ROOT)} ({len(files)} files, {len(edges)} edges)")
+    print(f"✅  wrote {MD_OUT.relative_to(ROOT)}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/hooks/augment-roadmap-progress.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# Augment Code lifecycle-hook trampoline for roadmap-progress-sync.
+#
+# Augment requires hook scripts to use the .sh extension and live at
+# either a system path (/etc/augment/...) or user scope
+# (~/.augment/...). This trampoline lives at user scope and dispatches
+# every PostToolUse event to whichever workspace fired it, so a single
+# install covers every project that has ./agent-config available.
+#
+# Behaviour:
+#   - Read the JSON event from stdin into a buffer.
+#   - Extract workspace_roots[0]; bail silently when missing.
+#   - cd into that workspace; bail silently when it is not a directory
+#     or does not contain ./agent-config.
+#   - Re-pipe the original JSON into
+#       ./agent-config roadmap-progress:hook --platform augment
+#     so roadmap_progress_hook.py runs the path filter and decides
+#     whether to regenerate the dashboard.
+#   - Always exit 0 — PostToolUse hooks must never block.
+
+set -u
+
+EVENT_DATA="$(cat)"
+
+# Extract workspace_roots[0] using whichever JSON tool is available.
+WORKSPACE=""
+if command -v jq >/dev/null 2>&1; then
+    WORKSPACE="$(printf '%s' "$EVENT_DATA" \
+        | jq -r '.workspace_roots[0] // empty' 2>/dev/null)"
+elif command -v python3 >/dev/null 2>&1; then
+    WORKSPACE="$(printf '%s' "$EVENT_DATA" | python3 -c '
+import json, sys
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+roots = data.get("workspace_roots") or []
+if roots:
+    print(roots[0])
+' 2>/dev/null)"
+fi
+
+if [ -z "$WORKSPACE" ] || [ ! -d "$WORKSPACE" ]; then
+    exit 0
+fi
+
+cd "$WORKSPACE" 2>/dev/null || exit 0
+
+if [ ! -x ./agent-config ]; then
+    exit 0
+fi
+
+printf '%s' "$EVENT_DATA" \
+    | ./agent-config roadmap-progress:hook --platform augment \
+        >/dev/null 2>&1 || true
+
+exit 0