@event4u/agent-config 2.26.0 → 3.1.0

package/scripts/discovery_stats.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Pretty-print the ``stats`` block from the committed discovery manifest.
+
+Cheap sanity surface for developers: counts by category, lifecycle, and
+trust level — answers "how many skills are professional vs core?" in
+one terminal line. Reads only the committed manifest; no scan, no
+generation. See ADR-015.
+
+CLI:
+  python scripts/discovery_stats.py [--manifest PATH]
+
+Exit codes:
+  0  printed
+  1  manifest missing or malformed
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_MANIFEST = ROOT / "dist" / "discovery" / "discovery-manifest.json"
+
+
+def _fmt_row(label: str, counts: dict[str, int]) -> str:
+    parts = [f"{k}={v}" for k, v in counts.items()]
+    return f"  {label:<14} " + "  ".join(parts)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--manifest", type=Path, default=DEFAULT_MANIFEST)
+    args = parser.parse_args(argv)
+
+    if not args.manifest.exists():
+        print(
+            f"error: manifest not found at {args.manifest} "
+            "— run `task build-discovery` first.",
+            file=sys.stderr,
+        )
+        return 1
+
+    try:
+        manifest = json.loads(args.manifest.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        print(f"error: invalid JSON: {exc}", file=sys.stderr)
+        return 1
+
+    stats = manifest.get("stats")
+    if not isinstance(stats, dict):
+        print("error: manifest has no `stats` block (regenerate)", file=sys.stderr)
+        return 1
+
+    rel = args.manifest.relative_to(ROOT) if args.manifest.is_absolute() else args.manifest
+    print(f"Discovery stats — {rel}")
+    print(f"  total          {stats.get('total_artefacts', 0)}")
+    print(_fmt_row("by category", stats.get("by_category", {})))
+    print(_fmt_row("by lifecycle", stats.get("by_lifecycle", {})))
+    print(_fmt_row("by trust", stats.get("by_trust_level", {})))
+    if stats.get("unassigned_count"):
+        print(f"  unassigned     {stats['unassigned_count']}")
+    if stats.get("documented_unassigned_count"):
+        print(f"  documented     {stats['documented_unassigned_count']}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/expected_perms.json

@@ -0,0 +1,47 @@
+{
+  "$schema_version": "expected-perms/v1",
+  "$comment": "Expected POSIX modes for the global install tree. Consumed by scripts/lint_global_paths.py as an entry-gate for the migrate-to-global subcommand (road-to-global-only-install Phase 5.0 / A7). Octal modes are strings so JSON tooling never widens 0700 → 700.",
+  "global_root": {
+    "path": "~/.event4u/agent-config",
+    "expected_mode": "0700",
+    "kind": "directory"
+  },
+  "files": [
+    {
+      "glob": "~/.event4u/agent-config/.agent-settings.yml",
+      "expected_mode": "0600",
+      "required": false
+    },
+    {
+      "glob": "~/.event4u/agent-config/.agent-user.yml",
+      "expected_mode": "0600",
+      "required": false
+    },
+    {
+      "glob": "~/.event4u/agent-config/.wizard-state.json",
+      "expected_mode": "0600",
+      "required": false
+    },
+    {
+      "glob": "~/.event4u/agent-config/**/*.key",
+      "expected_mode": "0600",
+      "required": false
+    }
+  ],
+  "directories": [
+    {
+      "glob": "~/.event4u/agent-config/state",
+      "expected_mode": "0700",
+      "required": false
+    },
+    {
+      "glob": "~/.event4u/agent-config/settings",
+      "expected_mode": "0700",
+      "required": false
+    }
+  ],
+  "forbid_symlink_escape": {
+    "root": "~/.event4u/agent-config",
+    "$comment": "All symlinks under the global root MUST resolve to paths still under the global root. Cross-root escapes are a security finding (allows external writes via a writable symlink target)."
+  }
+}

package/scripts/extract_audit_patterns.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Mine repeated phase patterns from ``agents/state/audit/*.jsonl``.
+"""Mine repeated phase patterns from ``agents/runtime/state/audit/*.jsonl``.
 
 Consumer side of `audit-log-v1` (see
 `docs/contracts/audit-log-v1.md`). Reads append-only JSONL audit
@@ -46,7 +46,7 @@ from pathlib import Path
 from typing import Iterable
 
 ROOT = Path(__file__).resolve().parent.parent
-DEFAULT_AUDIT_DIR = ROOT / "agents" / "state" / "audit"
+DEFAULT_AUDIT_DIR = ROOT / "agents" / "runtime" / "state" / "audit"
 SCHEMA_VERSION = 1
 
 

package/scripts/gen_discovery_baseline.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""Generate agents/evidence/notes/discovery-baseline.md for Phase 0.1."""
+from __future__ import annotations
+
+import datetime as _dt
+import pathlib
+import re
+import sys
+from collections import Counter
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+SRC = ROOT / ".agent-src.uncompressed"
+
+
+def _frontmatter(path: pathlib.Path) -> dict[str, str]:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    m = re.match(r"^---\n(.*?)\n---\n", text, re.DOTALL)
+    if not m:
+        return {}
+    out: dict[str, str] = {}
+    for line in m.group(1).splitlines():
+        if ":" in line and not line.startswith(" "):
+            k, _, v = line.partition(":")
+            out[k.strip()] = v.strip().strip('"').strip("'")
+    return out
+
+
+def main() -> int:
+    skills = sorted((SRC / "skills").rglob("SKILL.md"))
+    rules = sorted((SRC / "rules").rglob("*.md"))
+    commands = sorted((SRC / "commands").rglob("*.md"))
+    templates = sorted((SRC / "templates").rglob("*")) if (SRC / "templates").exists() else []
+    templates = [p for p in templates if p.is_file()]
+
+    domains: Counter[str] = Counter()
+    no_domain = 0
+    for s in skills:
+        fm = _frontmatter(s)
+        d = fm.get("domain")
+        if d:
+            domains[d] += 1
+        else:
+            no_domain += 1
+
+    out = []
+    out.append("# Discovery Baseline — Inventory (Phase 0.1)\n")
+    out.append(
+        f"> Generated by `scripts/gen_discovery_baseline.py` on "
+        f"{_dt.datetime.now(_dt.timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')}.\n"
+    )
+    out.append(
+        "> Frozen reference for the Phase 2 scanner — the `no domain` tally below must match the\n"
+        "> first scanner run's `unassigned[]` count within ±5% (Phase 2.4 acceptance).\n"
+    )
+
+    out.append("## Counts by category\n")
+    out.append("| Category | Path | Count |")
+    out.append("|---|---|---|")
+    out.append(f"| Skills | `.agent-src.uncompressed/skills/*/SKILL.md` | {len(skills)} |")
+    out.append(f"| Rules | `.agent-src.uncompressed/rules/**/*.md` | {len(rules)} |")
+    out.append(f"| Commands | `.agent-src.uncompressed/commands/**/*.md` | {len(commands)} |")
+    out.append(f"| Templates | `.agent-src.uncompressed/templates/**/*` | {len(templates)} |")
+    out.append("")
+
+    out.append("## Distinct `domain:` values (skills)\n")
+    for d, n in domains.most_common():
+        out.append(f"- `{d}` — {n} skill(s)")
+    out.append("")
+
+    out.append("## Skills without `domain:` (Phase 0.1 baseline)\n")
+    out.append(
+        f"- Count: **{no_domain}** (target for Phase 2.4 `unassigned[]` tally ±5%)"
+    )
+    out.append("")
+
+    out.append("## Sample frontmatter keys (first 10 skills)\n")
+    out.append("| File | name | source | domain | other keys |")
+    out.append("|---|---|---|---|---|")
+    interesting = {"status", "tier", "recommended_for_user_types", "cluster", "skills"}
+    for s in skills[:10]:
+        fm = _frontmatter(s)
+        other = ",".join(sorted(k for k in fm if k in interesting))
+        rel = s.relative_to(SRC)
+        out.append(
+            f"| `{rel}` | {fm.get('name','')} | {fm.get('source','')} | "
+            f"{fm.get('domain','')} | {other} |"
+        )
+    out.append("")
+
+    out.append("## Sample rules (first 10)\n")
+    out.append("| File | type | tier | source |")
+    out.append("|---|---|---|---|")
+    for r in rules[:10]:
+        fm = _frontmatter(r)
+        rel = r.relative_to(SRC)
+        out.append(
+            f"| `{rel}` | {fm.get('type','')} | {fm.get('tier','')} | {fm.get('source','')} |"
+        )
+    out.append("")
+
+    out.append("## Sample commands (first 10)\n")
+    out.append("| File | name | tier | cluster |")
+    out.append("|---|---|---|---|")
+    for c in commands[:10]:
+        fm = _frontmatter(c)
+        rel = c.relative_to(SRC)
+        out.append(
+            f"| `{rel}` | {fm.get('name','')} | {fm.get('tier','')} | {fm.get('cluster','')} |"
+        )
+    out.append("")
+
+    out.append("## Notes\n")
+    out.append("- Every skill carries `domain:` today — Phase 4 mapping uses it as primary signal.")
+    out.append("- Rules use `type` (always | auto) + `tier` (safety-floor | kernel | …); no `domain:` today.")
+    out.append("- Commands use `tier` + `cluster`; no `domain:` today.")
+    out.append("- Templates have no consistent frontmatter; Phase 4 quarantines them in `unassigned-artefacts.yml`.")
+    out.append("")
+
+    dest = ROOT / "agents" / "notes" / "discovery-baseline.md"
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text("\n".join(out), encoding="utf-8")
+    print(f"wrote {dest} — {len(out)} lines")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/generate_index.py

@@ -19,6 +19,12 @@ from dataclasses import dataclass
 from pathlib import Path
 
 ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / "scripts"))
+from _lib.agent_src import artefact_roots  # noqa: E402
+
+# Legacy single-root anchor — kept as fallback for pure-compressed
+# consumer projections. Multi-root discovery uses artefact_roots() so
+# generate_index works across packages/* per ADR-017.
 SRC = ROOT / ".agent-src.uncompressed"
 GUIDELINES = ROOT / "docs" / "guidelines"
 INDEX_PATH = ROOT / "agents" / "index.md"
@@ -62,59 +68,79 @@ def _truncate(text: str, limit: int = 200) -> str:
 
 
 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():
+    """Walk every source root for skills; first root wins per logical id."""
+    seen: dict[str, Entry] = {}
+    for src_root in artefact_roots():
+        skills_root = src_root / "skills"
+        if not skills_root.is_dir():
             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
+        for skill_dir in sorted(skills_root.iterdir()):
+            if not skill_dir.is_dir() or skill_dir.name in seen:
+                continue
+            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
+            seen[skill_dir.name] = Entry(
+                kind="skill",
+                name=name,
+                description=_truncate(fm.get("description", "")),
+                extra="",
+                path=skill_md.relative_to(ROOT).as_posix(),
+            )
+    return [seen[k] for k in sorted(seen)]
 
 
 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
+    """Walk every source root for rules; first root wins per logical id."""
+    seen: dict[str, Entry] = {}
+    for src_root in artefact_roots():
+        rules_root = src_root / "rules"
+        if not rules_root.is_dir():
+            continue
+        for rule_md in sorted(rules_root.glob("*.md")):
+            if rule_md.stem in seen:
+                continue
+            fm = _parse_frontmatter(rule_md.read_text(encoding="utf-8"))
+            seen[rule_md.stem] = Entry(
+                kind="rule",
+                name=rule_md.stem,
+                description=_truncate(fm.get("description", "")),
+                extra=fm.get("type", "?"),
+                path=rule_md.relative_to(ROOT).as_posix(),
+            )
+    return [seen[k] for k in sorted(seen)]
 
 
 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":
+    """Walk every source root for commands; first root wins per logical id."""
+    seen: dict[str, Entry] = {}
+    for src_root in artefact_roots():
+        cmd_dir = src_root / "commands"
+        if not cmd_dir.is_dir():
             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
+        for cmd_md in sorted(cmd_dir.rglob("*.md")):
+            if cmd_md.name == "AGENTS.md":
+                continue
+            rel = cmd_md.relative_to(cmd_dir).as_posix()
+            if rel in seen:
+                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']}"
+            seen[rel] = Entry(
+                kind="shim" if is_shim else "command",
+                name=fm.get("name") or cmd_md.stem,
+                description=_truncate(fm.get("description", "")),
+                extra=extra,
+                path=cmd_md.relative_to(ROOT).as_posix(),
+            )
+    return [seen[k] for k in sorted(seen)]
 
 
 def _collect_guidelines() -> list[Entry]:
@@ -137,8 +163,14 @@ def _collect_guidelines() -> list[Entry]:
 # 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.
+# Post-ADR-017 the source-of-truth lives at packages/*/.agent-src.uncompressed/,
+# so we strip whichever prefix matches and pin to the flat .agent-src/ output.
 def _to_shipped_path(path: str) -> str:
-    return path.replace(".agent-src.uncompressed/", ".agent-src/", 1)
+    from _lib.agent_src import strip_source_prefix
+    logical = strip_source_prefix(path)
+    if logical is not None:
+        return f".agent-src/{logical}"
+    return path
 
 
 def _render_table(

package/scripts/generate_ownership_matrix.py

@@ -4,7 +4,7 @@
 Produces:
 
   * docs/contracts/file-ownership-matrix.json (machine, internal-locked)
-  * agents/contexts/structural/file-ownership-matrix.md (human-readable)
+  * agents/settings/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
@@ -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: