@event4u/agent-config 3.0.0 → 3.1.1

package/scripts/generate_ownership_matrix.py

@@ -35,7 +35,14 @@ from typing import Iterable
 import yaml
 
 ROOT = Path(__file__).resolve().parent.parent
-SRC_ROOT = ROOT / ".agent-src.uncompressed"
+sys.path.insert(0, str(ROOT / "scripts"))
+from _lib.agent_src import artefact_roots, resolve_logical, strip_source_prefix  # noqa: E402
+
+# Canonical anchor used in the committed matrix. Paths are always
+# emitted as ".agent-src.uncompressed/<sub>/<...>" regardless of which
+# physical root (legacy or packages/*) contains the file, so the matrix
+# stays stable across the monorepo migration.
+CANONICAL_SRC_PREFIX = ".agent-src.uncompressed"
 
 SCAN_DIRS = ("rules", "skills", "commands", "contexts", "personas")
 
@@ -88,38 +95,48 @@ def _parse_frontmatter(p: Path) -> dict:
     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 _collect_files(root: Path | None = None) -> list[tuple[Path, str]]:
+    """Walk every artefact root and yield ``(physical_path, canonical_rel)``.
 
+    ``canonical_rel`` is always anchored at ``.agent-src.uncompressed/`` so
+    the matrix is byte-identical pre- and post-monorepo-move. Duplicates
+    across roots resolve to the first hit (legacy first, then packages
+    alphabetically) — matches the priority in ``artefact_roots()``.
 
-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
+    When ``root`` is given, only that single directory is scanned — used by
+    tests against a ``tmp_path`` fixture so they stay isolated from the
+    real package layout.
+    """
+    roots = [root] if root is not None else list(artefact_roots())
+    out: list[tuple[Path, str]] = []
+    seen: set[str] = set()
+    for r in roots:
+        for sub in SCAN_DIRS:
+            d = r / sub
+            if not d.exists():
+                continue
+            for f in sorted(d.rglob("*.md")):
+                logical = f.relative_to(r).as_posix()
+                canonical = f"{CANONICAL_SRC_PREFIX}/{logical}"
+                if canonical in seen:
+                    continue
+                seen.add(canonical)
+                out.append((f, canonical))
+    out.sort(key=lambda pair: pair[1])
+    return out
 
 
-def build_matrix(src_root: Path) -> tuple[dict[str, FileEntry], list[Edge], list[str]]:
+def build_matrix(root: Path | None = None) -> 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.
+    caller must abort with exit code 2. When ``root`` is given, only that
+    single directory is scanned (test isolation).
     """
     files: dict[str, FileEntry] = {}
-    for f in _collect_files(src_root):
-        rel = f.relative_to(src_root.parent).as_posix()
+    physical_by_canonical: dict[str, Path] = {}
+    for f, rel in _collect_files(root):
+        physical_by_canonical[rel] = f
         fm = _parse_frontmatter(f)
         rtype = fm.get("type")
         if isinstance(rtype, str):
@@ -149,14 +166,15 @@ def build_matrix(src_root: Path) -> tuple[dict[str, FileEntry], list[Edge], list
 
     # 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")
+        phys = physical_by_canonical[rel]
+        body = phys.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)
+            resolved = _resolve_link(rel, phys, href)
             if resolved is None or resolved == rel or resolved in seen_targets:
                 continue
             if resolved in files:
@@ -191,21 +209,57 @@ def build_matrix(src_root: Path) -> tuple[dict[str, FileEntry], list[Edge], list
     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()
+def _resolve_link(source_rel: str, source_phys: Path, href: str) -> str | None:
+    """Resolve a markdown link href to a canonical scanned-root path, or None.
+
+    ``source_rel`` is the canonical (``.agent-src.uncompressed/...``)
+    identity of the source file. Relative hrefs are resolved against
+    the source's *logical* directory, then looked up across every
+    artefact root via :func:`resolve_logical`. This keeps the matrix
+    stable when source and target live in different physical packages.
+
+    Repo-rooted hrefs (``agents/...``, ``packages/...``, or those
+    starting with ``.agent-src.uncompressed/``) are resolved against
+    the repo root and normalised through :func:`strip_source_prefix`.
+    """
+    if href.startswith(".agent-src.uncompressed/") or href.startswith("agents/") \
+            or href.startswith("packages/"):
+        cand = (ROOT / href).resolve()
+        if not cand.exists():
+            return None
+        try:
+            rel = cand.relative_to(ROOT).as_posix()
+        except ValueError:
+            return None
+        logical = strip_source_prefix(rel)
+        if logical is None:
+            return None
     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
+        # Logical resolution: walk relative hops on the canonical path
+        # so a `../skills/laravel/SKILL.md` link from
+        # `rules/architecture.md` resolves to `skills/laravel/SKILL.md`
+        # regardless of which package physically hosts either file.
+        source_logical = strip_source_prefix(source_rel)
+        if source_logical is None:
+            return None
+        base_parts = source_logical.split("/")[:-1]  # drop file name
+        href_parts = href.split("/")
+        for part in href_parts:
+            if part == "" or part == ".":
+                continue
+            if part == "..":
+                if not base_parts:
+                    return None
+                base_parts.pop()
+            else:
+                base_parts.append(part)
+        logical = "/".join(base_parts)
+    # Existence is validated downstream by the caller against the scanned
+    # ``files`` dict — that handles both real ``artefact_roots()`` scans
+    # and ``tmp_path`` test fixtures uniformly.
+    parts = logical.split("/")
+    if len(parts) >= 2 and parts[0] in SCAN_DIRS:
+        return f"{CANONICAL_SRC_PREFIX}/{logical}"
     return None
 
 
@@ -287,11 +341,12 @@ def main(argv: Iterable[str] | None = None) -> int:
                     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)
+    if not artefact_roots():
+        print("❌  no artefact roots found (legacy or packages/*/.agent-src.uncompressed/)",
+              file=sys.stderr)
         return 3
 
-    files, edges, depth3 = build_matrix(SRC_ROOT)
+    files, edges, depth3 = build_matrix()
     if depth3:
         print("❌  load_context depth-3 chain detected (limit is 2):", file=sys.stderr)
         for chain in depth3:

package/scripts/generate_pack_manifests.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+"""Generate ``pack.yaml`` + ``README.md`` for every ``packages/*/`` tree.
+
+Phase 4.4 of the monorepo migration (ADR-017). The manifests are
+*derived* from frontmatter + ``config/discovery/packs.yml``; they are
+regenerated on every ``task sync`` and must never be hand-edited.
+
+For each package directory under ``packages/`` we emit:
+  - ``packages/<pkg>/pack.yaml`` — id, label, owner (workspaces),
+    requires, version, artefact_count
+  - ``packages/<pkg>/README.md`` — pack description + per-artefact
+    description table
+
+CLI:
+  --check     exit non-zero if any output would change (CI gate)
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _lib.agent_src import iter_all_sources  # noqa: E402
+
+ROOT = Path(__file__).resolve().parents[1]
+PACKAGES = ROOT / "packages"
+PACKS_VOCAB = ROOT / "config" / "discovery" / "packs.yml"
+PACKAGE_JSON = ROOT / "package.json"
+GENERATED_HEADER = "# Generated by scripts/generate_pack_manifests.py — DO NOT EDIT BY HAND\n"
+
+
+def _load_yaml(path: Path) -> Any:
+    if not path.exists():
+        return None
+    return yaml.safe_load(path.read_text(encoding="utf-8"))
+
+
+def _read_frontmatter(path: Path) -> dict[str, Any]:
+    text = path.read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        return {}
+    end = text.find("\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 _pack_id_from_dir(pkg_dir: Path) -> str:
+    name = pkg_dir.name
+    return "core" if name == "core" else name.removeprefix("pack-")
+
+
+def _vocab_lookup(packs_vocab: list[dict[str, Any]]) -> dict[str, dict[str, Any]]:
+    return {p["id"]: p for p in (packs_vocab or [])}
+
+
+def _package_version() -> str:
+    if not PACKAGE_JSON.exists():
+        return "0.0.0"
+    return json.loads(PACKAGE_JSON.read_text(encoding="utf-8")).get("version", "0.0.0")
+
+
+def _collect_artefacts(pkg_dir: Path) -> list[dict[str, Any]]:
+    src_root = pkg_dir / ".agent-src.uncompressed"
+    if not src_root.is_dir():
+        return []
+    items: list[dict[str, Any]] = []
+    for p in sorted(src_root.rglob("*.md")):
+        if not p.is_file():
+            continue
+        fm = _read_frontmatter(p)
+        if not fm:
+            continue
+        items.append({
+            "path": p.relative_to(src_root).as_posix(),
+            "name": fm.get("name") or (p.parent.name if p.name == "SKILL.md" else p.stem),
+            "description": (fm.get("description") or "").strip(),
+            "category": _category_for(p, src_root),
+        })
+    return items
+
+
+def _category_for(path: Path, src_root: Path) -> str:
+    rel = path.relative_to(src_root).as_posix()
+    top = rel.split("/", 1)[0]
+    mapping = {"skills": "skill", "rules": "rule", "commands": "command",
+               "personas": "persona", "guidelines": "guideline",
+               "contexts": "context", "presets": "preset", "profiles": "profile"}
+    return mapping.get(top, top)
+
+
+def _build_pack_yaml(pkg_dir: Path, vocab: dict[str, dict[str, Any]],
+                     artefacts: list[dict[str, Any]], version: str) -> dict[str, Any]:
+    pid = _pack_id_from_dir(pkg_dir)
+    meta = vocab.get(pid) or {}
+    label = meta.get("label") or (pid.title() if pid == "core" else pid)
+    out: dict[str, Any] = {
+        "id": pid,
+        "label": label,
+        "description": meta.get("description") or ("Core framework-neutral artefacts." if pid == "core" else ""),
+        "owner": meta.get("workspaces") or (["agent-config-maintainer"] if pid == "core" else []),
+        "requires": meta.get("requires_hint") or [],
+        "trust_level_default": meta.get("trust_level_default") or "core",
+        "version": version,
+        "artefact_count": len(artefacts),
+    }
+    if isinstance(meta.get("onboarding"), dict):
+        out["onboarding"] = meta["onboarding"]
+    return out
+
+
+def _render_readme(pack_meta: dict[str, Any], artefacts: list[dict[str, Any]]) -> str:
+    lines = [GENERATED_HEADER, f"# {pack_meta['label']}", ""]
+    if pack_meta.get("description"):
+        lines += [pack_meta["description"], ""]
+    lines += [f"- **id**: `{pack_meta['id']}`",
+              f"- **version**: `{pack_meta['version']}`",
+              f"- **owner**: {', '.join(pack_meta['owner']) or '—'}",
+              f"- **requires**: {', '.join(pack_meta['requires']) or '—'}",
+              f"- **artefacts**: {pack_meta['artefact_count']}", ""]
+    by_cat: dict[str, list[dict[str, Any]]] = {}
+    for a in artefacts:
+        by_cat.setdefault(a["category"], []).append(a)
+    for cat in sorted(by_cat):
+        lines += [f"## {cat.title()}s ({len(by_cat[cat])})", ""]
+        for a in sorted(by_cat[cat], key=lambda x: x["name"]):
+            desc = a["description"] or "_(no description)_"
+            lines.append(f"- **`{a['name']}`** — {desc}")
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _write_if_changed(path: Path, content: str, check: bool) -> bool:
+    existing = path.read_text(encoding="utf-8") if path.exists() else None
+    if existing == content:
+        return False
+    if check:
+        return True
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return True
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--check", action="store_true", help="exit non-zero on drift")
+    args = ap.parse_args()
+    vocab = _vocab_lookup(_load_yaml(PACKS_VOCAB) or [])
+    version = _package_version()
+    if not PACKAGES.exists():
+        print("packages/ does not exist — nothing to generate", file=sys.stderr)
+        return 0
+    drift = 0
+    for pkg in sorted(PACKAGES.iterdir()):
+        if not pkg.is_dir():
+            continue
+        artefacts = _collect_artefacts(pkg)
+        meta = _build_pack_yaml(pkg, vocab, artefacts, version)
+        yaml_body = GENERATED_HEADER + yaml.safe_dump(meta, sort_keys=True, allow_unicode=True)
+        readme_body = _render_readme(meta, artefacts)
+        if _write_if_changed(pkg / "pack.yaml", yaml_body, args.check):
+            drift += 1
+            print(f"{'drift' if args.check else 'wrote'}: {pkg.name}/pack.yaml")
+        if _write_if_changed(pkg / "README.md", readme_body, args.check):
+            drift += 1
+            print(f"{'drift' if args.check else 'wrote'}: {pkg.name}/README.md")
+    if args.check and drift:
+        print(f"pack manifests out of date ({drift} file(s)) — run `task generate-pack-manifests`", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/install

@@ -183,6 +183,20 @@ if $LIST_TOOLS; then
     exit 0
 fi
 
+# road-to-global-only-install § Phase 3.3 — consumer-floor gate.
+#
+# Consumer installs are global-only (ADR-020). Explicit --scope=project
+# (and its --scope project / --scope=project / SCOPE shorthand) is the
+# maintainer-only escape hatch behind AGENT_CONFIG_DEV_MODE=1. Without
+# the env flag we refuse here so the bash orchestrator fails fast with
+# a directive error pointing at the maintainer doc — install.py's
+# Python-side _enforce_consumer_global_only still backstops the same
+# check for direct python3 scripts/install.py invocations.
+if [[ "${SCOPE:-}" == "project" && "${AGENT_CONFIG_DEV_MODE:-}" != "1" ]]; then
+    err "--scope=project is reserved for maintainers (ADR-020 — consumer installs are global-only). Set AGENT_CONFIG_DEV_MODE=1 to opt in. See docs/maintainers/dev-mode.md."
+    exit 1
+fi
+
 # Interactive --tools picker (S9). Fires only when:
 #   - --tools was not explicitly passed
 #   - --yes / -y was not passed (CI / non-interactive opt-out)
@@ -298,7 +312,10 @@ run_sync() {
     $QUIET   && args+=(--quiet)
     $MINIMAL && args+=(--minimal)
     args+=(--tools="$TOOLS")
-    bash "$INSTALL_SH" "${args[@]}"
+    # Suppress the install.sh deprecation banner when called through the
+    # orchestrator (this script). Direct `bash install.sh` invocations
+    # still see it. See ADR-016 § Distribution / Phase 6.
+    AGENT_CONFIG_FROM_ORCHESTRATOR=1 bash "$INSTALL_SH" "${args[@]}"
 }
 
 run_bridges() {