@event4u/agent-config 5.4.1 → 5.5.0

package/scripts/cross_repo_retrieve.py

@@ -0,0 +1,172 @@
+"""Cross-repo retrieval — read-only, targeted, opt-in (ADR-032 Option A).
+
+Phase 4 of `road-to-leaner-core-and-discovery`. Given a query and the opted-in
+`linked_projects` siblings, runs a bounded *targeted* search (path-glob +
+content grep — never a full walk) and returns the retrieval envelope defined in
+`docs/contracts/cross-repo-retrieval.md`. Reuses the redaction + chunking floor
+from `knowledge_ingest.py` so no secret crosses a repo boundary.
+
+Scope guards (Option A):
+  - read-only, no writes, no network;
+  - only siblings with `include: true` in agents/settings/.agent-settings.local.yml;
+  - `large`-flagged siblings REQUIRE a `--path-scope` (reject an unscoped query);
+  - ≤ --max-chunks results, one concept per query.
+
+Usage:
+    python3 scripts/cross_repo_retrieve.py "<query>" [--path-scope GLOB]
+            [--max-chunks N] [--format text|json] [--root PATH]
+"""
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+sys.path.insert(0, str(REPO_ROOT / "packages" / "core" / "installer" / "python"))
+from linked_projects_list import collect as collect_siblings  # type: ignore  # noqa: E402
+
+try:
+    from knowledge_ingest import redact, chunk_text  # type: ignore
+except Exception:  # pragma: no cover - keep retrieval usable if ingest moves
+    def redact(text, counters):  # type: ignore
+        return text, 0
+
+    def chunk_text(text, target_bytes=2048):  # type: ignore
+        return [text[:target_bytes]] if text else []
+
+DEFAULT_MAX_CHUNKS = 8
+MAX_FILES_SCANNED = 2000  # hard ceiling on the targeted walk, defence-in-depth
+TEXT_SUFFIXES = {".md", ".txt", ".py", ".ts", ".tsx", ".js", ".jsx", ".php", ".go",
+                 ".rs", ".rb", ".java", ".json", ".yml", ".yaml", ".toml", ".sql", ".sh"}
+SKIP_DIRS = {".git", "node_modules", "dist", "vendor", ".venv", "__pycache__",
+             ".idea", ".vscode", "build", "target", ".next", "coverage"}
+
+
+def _freshness(repo: Path, rel: str) -> str:
+    try:
+        out = subprocess.run(
+            ["git", "log", "-1", "--format=%ad", "--date=short", "--", rel],
+            cwd=repo, capture_output=True, text=True, timeout=8, check=False,
+        )
+        if out.returncode == 0 and out.stdout.strip():
+            return out.stdout.strip()
+    except (OSError, subprocess.SubprocessError):
+        pass
+    try:
+        from datetime import datetime, timezone
+        ts = (repo / rel).stat().st_mtime
+        return datetime.fromtimestamp(ts, timezone.utc).date().isoformat()
+    except OSError:
+        return "unknown"
+
+
+def _iter_files(repo: Path, path_scope: str | None):
+    count = 0
+    for p in sorted(repo.rglob("*")):
+        if count >= MAX_FILES_SCANNED:
+            break
+        if not p.is_file() or p.suffix.lower() not in TEXT_SUFFIXES:
+            continue
+        if any(part in SKIP_DIRS for part in p.relative_to(repo).parts):
+            continue
+        rel = str(p.relative_to(repo))
+        if path_scope and not fnmatch.fnmatch(rel, path_scope):
+            continue
+        count += 1
+        yield p, rel
+
+
+def _terms(query: str) -> list[str]:
+    return [t for t in query.lower().replace(",", " ").split() if len(t) > 2]
+
+
+def search_sibling(repo: Path, query: str, terms: list[str], path_scope: str | None,
+                   budget: int) -> list[dict]:
+    hits: list[dict] = []
+    repo_name = repo.name
+    for p, rel in _iter_files(repo, path_scope):
+        if len(hits) >= budget:
+            break
+        rel_lower = rel.lower()
+        path_match = any(t in rel_lower for t in terms)
+        try:
+            text = p.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        text_lower = text.lower()
+        content_terms = [t for t in terms if t in text_lower]
+        if not path_match and not content_terms:
+            continue
+        # Pull the most relevant chunk (first chunk containing a term, else the head).
+        chunks = chunk_text(text)
+        chosen = next((c for c in chunks if any(t in c.lower() for t in terms)), chunks[0] if chunks else "")
+        redacted, _ = redact(chosen, {})
+        reason = (f"path matches: {rel}" if path_match
+                  else f"content term(s): {', '.join(content_terms[:3])}")
+        hits.append({
+            "source_repo": repo_name,
+            "path": rel,
+            "chunk": redacted[:2048],
+            "freshness": _freshness(repo, rel),
+            "match_reason": reason,
+        })
+    return hits
+
+
+def retrieve(root: Path, query: str, path_scope: str | None, max_chunks: int) -> dict:
+    siblings = collect_siblings(root, show_all=False)  # opted-in only
+    if not siblings:
+        return {"query": query, "matches": [], "note": "no opted-in linked-project siblings — nothing to search"}
+    terms = _terms(query)
+    if not terms:
+        return {"query": query, "matches": [], "note": "query too short — give at least one term > 2 chars"}
+    matches: list[dict] = []
+    skipped: list[str] = []
+    for sib in siblings:
+        if len(matches) >= max_chunks:
+            break
+        repo = Path(sib["path"])
+        if sib.get("large") and not path_scope:
+            skipped.append(sib["path"])
+            continue
+        matches.extend(search_sibling(repo, query, terms, path_scope, max_chunks - len(matches)))
+    out: dict = {"query": query, "matches": matches[:max_chunks]}
+    if skipped:
+        out["note"] = ("large sibling(s) skipped — supply --path-scope to search them: "
+                       + "; ".join(skipped))
+    return out
+
+
+def render_text(result: dict) -> str:
+    matches = result["matches"]
+    if not matches:
+        return result.get("note", "no matches")
+    lines = ["| source_repo | path | freshness | why |", "|---|---|---|---|"]
+    for m in matches:
+        lines.append(f"| {m['source_repo']} | {m['path']} | {m['freshness']} | {m['match_reason']} |")
+    if result.get("note"):
+        lines += ["", f"> {result['note']}"]
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Targeted, read-only cross-repo retrieval (ADR-032 Option A).")
+    ap.add_argument("query", help="What to retrieve (one concept; ≥ 1 term > 2 chars).")
+    ap.add_argument("--path-scope", default=None, help="Glob to scope the search (required for large siblings).")
+    ap.add_argument("--max-chunks", type=int, default=DEFAULT_MAX_CHUNKS)
+    ap.add_argument("--format", choices=("text", "json"), default="text")
+    ap.add_argument("--root", default=".")
+    args = ap.parse_args(argv)
+
+    result = retrieve(Path(args.root).resolve(), args.query, args.path_scope, args.max_chunks)
+    print(json.dumps(result, indent=2) if args.format == "json" else render_text(result))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/inventory_meta_layers.py

@@ -0,0 +1,288 @@
+"""Meta-layer / concept-surface inventory — read-only discovery pass.
+
+Drives Phase 1 of `agents/roadmaps/road-to-leaner-core-and-discovery.md`.
+Sibling to `scripts/inventory_abstraction_budget.py`: that tool counts
+per-artefact references + frontmatter bloat; this one inventories the
+*concept surface* the post-5.x feedback names as meta-complexity.
+
+For each concept it emits one row:
+    concept · surfaces it lives in · line cost · last-touched · overlap candidates
+
+Concept = a normalized token shared by ≥ 2 stable artefacts (a rule, a
+contract, a guideline, or a context) — i.e. a single idea defined in
+more than one surface. Plus the curated meta-layer families the
+feedback names explicitly (iron-laws, value, roadmap, linked-projects,
+marketplace, governance). Also tabulates always-loaded rule families
+(kernel) + Iron-Law count per rule.
+
+Output: agents/evidence/analysis/meta-layer-inventory.md (+ .csv)
+Read-only. Touches no abstraction file.
+
+Usage:
+    python3 scripts/inventory_meta_layers.py [--quiet]
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import re
+import subprocess
+from collections import defaultdict
+from dataclasses import dataclass, field
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+RULES_DIR = REPO_ROOT / ".agent-src" / "rules"
+CONTRACTS_DIR = REPO_ROOT / "docs" / "contracts"
+GUIDELINES_DIR = REPO_ROOT / "docs" / "guidelines"
+CONTEXTS_DIR = REPO_ROOT / ".agent-src" / "contexts"
+ROUTER = REPO_ROOT / "dist" / "router.json"
+EVIDENCE_DIR = REPO_ROOT / "agents" / "evidence" / "analysis"
+
+IRON_LAW_RE = re.compile(r"^#{1,3}\s+(?:The\s+)?Iron\s+Laws?\b", re.IGNORECASE | re.MULTILINE)
+
+# Generic filename tokens that carry no concept identity — dropped before grouping.
+STOPWORDS = {
+    "rule", "rules", "contract", "contracts", "mechanics", "policy", "schema",
+    "config", "v1", "v2", "and", "the", "of", "for", "to", "in", "on", "a",
+    "adr", "model", "spec", "format", "default", "defaults", "system", "examples",
+    "demos", "writing", "patterns", "auto", "core", "base",
+}
+
+# Curated meta-layer families the feedback names (always emitted as rows).
+SEED_FAMILIES = ["iron", "value", "roadmap", "linked", "marketplace", "governance", "council"]
+
+
+@dataclass
+class Surface:
+    path: Path
+    kind: str  # rule | contract | guideline | context
+    lines: int
+    tokens: set[str] = field(default_factory=set)
+
+    @property
+    def rel(self) -> str:
+        return str(self.path.relative_to(REPO_ROOT))
+
+
+def _last_touched(path: Path) -> str:
+    try:
+        out = subprocess.run(
+            ["git", "log", "-1", "--format=%ad", "--date=short", "--", str(path)],
+            cwd=REPO_ROOT, capture_output=True, text=True, check=False, timeout=10,
+        )
+        return out.stdout.strip() or "untracked"
+    except Exception:
+        return "unknown"
+
+
+def _tokens(stem: str) -> set[str]:
+    return {t for t in re.split(r"[-_]", stem.lower()) if t and t not in STOPWORDS and len(t) > 2}
+
+
+def _collect(directory: Path, kind: str) -> list[Surface]:
+    out: list[Surface] = []
+    if not directory.exists():
+        return out
+    for p in sorted(directory.rglob("*.md")):
+        if p.name == "README.md":
+            continue
+        text = p.read_text(encoding="utf-8", errors="replace")
+        out.append(Surface(p, kind, text.count("\n") + 1, _tokens(p.stem)))
+    return out
+
+
+def _kernel_and_tiers() -> dict[str, int | list[str]]:
+    if not ROUTER.exists():
+        return {"kernel": [], "tier_1": 0, "tier_2": 0}
+    d = json.loads(ROUTER.read_text(encoding="utf-8"))
+    return {
+        "kernel": d.get("kernel", []),
+        "tier_1": d.get("tier_1", 0) if isinstance(d.get("tier_1"), int) else len(d.get("tier_1", [])),
+        "tier_2": d.get("tier_2", 0) if isinstance(d.get("tier_2"), int) else len(d.get("tier_2", [])),
+    }
+
+
+def _iron_law_counts() -> dict[str, int]:
+    counts: dict[str, int] = {}
+    for p in sorted(RULES_DIR.glob("*.md")):
+        text = p.read_text(encoding="utf-8", errors="replace")
+        n = len(IRON_LAW_RE.findall(text))
+        if n:
+            counts[p.stem] = n
+    return counts
+
+
+def _stack(s: Surface) -> str:
+    """Concern stack a surface belongs to. PHP coding guidelines are a
+    different domain from agent-behaviour rules/contracts — a shared topic
+    word (`git`, `security`) between them is coincidence, not duplication.
+    """
+    return "php" if "/guidelines/php/" in s.rel.replace("\\", "/") else "agent"
+
+
+def _same_concept(a: Surface, b: Surface) -> bool:
+    """Genuine concept duplication, not topic adjacency.
+
+    True when one stem is a prefix of the other (the rule→mechanics/examples
+    split — `language-and-tone` ⊂ `language-and-tone-examples`), OR the two
+    stems share ≥ 2 significant tokens (a tight family like `domain-safety-*`).
+    Single shared topic token (`skill`, `command`, `agent`) is NOT enough.
+
+    Cross-stack guard (Phase-1 council namespace-hygiene, 2026-05-30): a PHP
+    coding guideline and an agent rule/contract that merely share one topic
+    word (`git`, `security`) are distinct concerns — only group them on a
+    near-identical stem (prefix containment), never on a lone shared token.
+    """
+    sa, sb = a.path.stem.lower(), b.path.stem.lower()
+    short, long = (sa, sb) if len(sa) <= len(sb) else (sb, sa)
+    # Containment only counts when the prefix is itself a multi-token concept
+    # (`language-and-tone` ⊂ `…-examples`), never a generic single word
+    # (`git` ⊂ `git-history-discipline` is coincidence, not duplication).
+    if short != long and long.startswith(short + "-") and len(_tokens(short)) >= 2:
+        return True
+    if _stack(a) != _stack(b):
+        return False
+    return len(a.tokens & b.tokens) >= 2
+
+
+def _concept_rows(surfaces: list[Surface]) -> list[dict]:
+    # Union-find over the genuine-duplication adjacency.
+    parent = list(range(len(surfaces)))
+
+    def find(i: int) -> int:
+        while parent[i] != i:
+            parent[i] = parent[parent[i]]
+            i = parent[i]
+        return i
+
+    def union(i: int, j: int) -> None:
+        parent[find(i)] = find(j)
+
+    for i in range(len(surfaces)):
+        for j in range(i + 1, len(surfaces)):
+            if _same_concept(surfaces[i], surfaces[j]):
+                union(i, j)
+
+    comps: dict[int, list[Surface]] = defaultdict(list)
+    for idx, s in enumerate(surfaces):
+        comps[find(idx)].append(s)
+
+    rows: list[dict] = []
+    for group in comps.values():
+        if len(group) < 2:
+            continue
+        kinds = {s.kind for s in group}
+        # Concept label = the most-common significant token shared across the group.
+        tok_freq: dict[str, int] = defaultdict(int)
+        for s in group:
+            for t in s.tokens:
+                tok_freq[t] += 1
+        shared = [t for t, n in tok_freq.items() if n == len(group)] or [max(tok_freq, key=tok_freq.get)]
+        label = "-".join(sorted(shared)[:2])
+        seeded = any(any(t.startswith(f) or f.startswith(t) for f in SEED_FAMILIES) for t in shared)
+        cross_kind = len(kinds) >= 2
+        contract_dup = sum(1 for s in group if s.kind == "contract") >= 2
+        line_cost = sum(s.lines for s in group)
+        touched = max((_last_touched(s.path) for s in group), default="unknown")
+        rows.append({
+            "concept": label,
+            "surfaces": "; ".join(s.rel for s in sorted(group, key=lambda x: x.rel)),
+            "surface_count": len(group),
+            "kinds": ",".join(sorted(kinds)),
+            "line_cost": line_cost,
+            "last_touched": touched,
+            "overlap": "Y" if (cross_kind or contract_dup) else "family",
+            "seeded": "Y" if seeded else "",
+        })
+    rows.sort(key=lambda r: (-r["surface_count"], -r["line_cost"]))
+    return rows
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Meta-layer / concept-surface inventory (read-only).")
+    ap.add_argument("--quiet", action="store_true")
+    args = ap.parse_args(argv)
+
+    surfaces = (
+        _collect(RULES_DIR, "rule")
+        + _collect(CONTRACTS_DIR, "contract")
+        + _collect(GUIDELINES_DIR, "guideline")
+        + _collect(CONTEXTS_DIR, "context")
+    )
+    tiers = _kernel_and_tiers()
+    iron = _iron_law_counts()
+    rows = _concept_rows(surfaces)
+
+    EVIDENCE_DIR.mkdir(parents=True, exist_ok=True)
+    md = EVIDENCE_DIR / "meta-layer-inventory.md"
+    csv_path = EVIDENCE_DIR / "meta-layer-inventory.csv"
+
+    kernel = tiers["kernel"]
+    overlap_count = sum(1 for r in rows if r["overlap"] == "Y")
+    iron_total = sum(iron.values())
+
+    lines = [
+        "# Meta-Layer / Concept-Surface Inventory",
+        "",
+        "> Read-only discovery output for `agents/roadmaps/road-to-leaner-core-and-discovery.md` Phase 1.",
+        "> Counts are grep/git-backed via `scripts/inventory_meta_layers.py`. A row is an *overlap candidate*",
+        "> when one concept (a shared filename token) is defined across ≥ 2 stable surfaces.",
+        "",
+        "## Summary",
+        "",
+        "| Metric | Value |",
+        "|---|---:|",
+        f"| Always-loaded kernel rule families | {len(kernel)} |",
+        f"| tier_1 (balanced) rules | {tiers['tier_1']} |",
+        f"| tier_2 (full) rules | {tiers['tier_2']} |",
+        f"| Rules carrying Iron-Law headings | {len(iron)} |",
+        f"| Total Iron-Law headings across rules | {iron_total} |",
+        f"| Concept surfaces scanned (rule/contract/guideline/context) | {len(surfaces)} |",
+        f"| Concept overlap candidates (≥ 2 surfaces, cross-kind/contract-dup) | {overlap_count} |",
+        "",
+        f"Kernel: {', '.join(kernel)}",
+        "",
+        "## Iron-Law density per rule (top 15)",
+        "",
+        "| Rule | Iron Laws |",
+        "|---|---:|",
+    ]
+    for stem, n in sorted(iron.items(), key=lambda kv: -kv[1])[:15]:
+        lines.append(f"| `{stem}` | {n} |")
+
+    lines += [
+        "",
+        "## Concept-overlap ledger",
+        "",
+        "> One row per concept defined in ≥ 2 surfaces. `overlap=Y` = cross-kind or duplicate-contract",
+        "> (genuine merge/delete candidate). `seeded` = a feedback-named meta-layer family.",
+        "> Classification (merge / delete / keep-with-reason) is filled in Step 2 — left blank here.",
+        "",
+        "| Concept | Surfaces | # | Kinds | Lines | Last touched | Overlap | Class |",
+        "|---|---|---:|---|---:|---|---|---|",
+    ]
+    for r in rows:
+        lines.append(
+            f"| `{r['concept']}` | {r['surfaces']} | {r['surface_count']} | {r['kinds']} | "
+            f"{r['line_cost']} | {r['last_touched']} | {r['overlap']} | _unclassified_ |"
+        )
+    lines.append("")
+    md.write_text("\n".join(lines), encoding="utf-8")
+
+    with csv_path.open("w", newline="", encoding="utf-8") as fh:
+        w = csv.DictWriter(fh, fieldnames=["concept", "surface_count", "kinds", "line_cost", "last_touched", "overlap", "seeded", "surfaces"])
+        w.writeheader()
+        for r in rows:
+            w.writerow(r)
+
+    if not args.quiet:
+        print(f"meta-layer inventory: {len(surfaces)} surfaces, {len(rows)} concept rows, {overlap_count} overlap candidates")
+        print(f"  → {md.relative_to(REPO_ROOT)}")
+        print(f"  → {csv_path.relative_to(REPO_ROOT)}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/linked_projects_list.py

@@ -0,0 +1,91 @@
+"""`agent-config linked-projects:list` — list opted-in IDE-attached siblings.
+
+Phase 4 of `road-to-leaner-core-and-discovery`; closes the ADR-032 follow-up
+"expose the detector as a CLI subcommand for consumer reach". Pure wrapper over
+`scripts/_lib/linked_projects.detect_linked_projects` + the
+`agents/settings/.agent-settings.local.yml` → `linked_projects[]` opt-in
+cascade. No detection logic is duplicated here.
+
+Prints opted-in siblings (`path · detected_via · large`). `--all` shows every
+detected sibling with its opt-in status; `--format json` is machine-readable.
+Read-only, no network.
+
+Usage:
+    python3 scripts/linked_projects_list.py [--all] [--format text|json] [--root PATH]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import yaml
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+from _lib.linked_projects import detect_linked_projects  # type: ignore  # noqa: E402
+
+LOCAL_SETTINGS = Path("agents") / "settings" / ".agent-settings.local.yml"
+
+
+def _opt_in_map(root: Path) -> dict[str, bool]:
+    """Map resolved sibling path → include flag from the local settings cascade."""
+    f = root / LOCAL_SETTINGS
+    if not f.is_file():
+        return {}
+    try:
+        data = yaml.safe_load(f.read_text(encoding="utf-8", errors="replace")) or {}
+    except yaml.YAMLError:
+        return {}
+    out: dict[str, bool] = {}
+    for entry in (data.get("linked_projects") or []):
+        if isinstance(entry, dict) and entry.get("path"):
+            try:
+                out[str(Path(entry["path"]).expanduser().resolve())] = bool(entry.get("include"))
+            except OSError:
+                out[str(entry["path"])] = bool(entry.get("include"))
+    return out
+
+
+def collect(root: Path, show_all: bool) -> list[dict]:
+    detected = detect_linked_projects(root)
+    opt_in = _opt_in_map(root)
+    rows: list[dict] = []
+    for d in detected:
+        include = opt_in.get(d["path"])  # None = undecided
+        if not show_all and include is not True:
+            continue
+        rows.append({**d, "include": include})
+    return rows
+
+
+def render_text(rows: list[dict], show_all: bool) -> str:
+    if not rows:
+        scope = "detected" if show_all else "opted-in"
+        return f"No {scope} linked-project siblings. (Attach a sibling repo in your IDE and opt in.)"
+    lines = ["| path | detected via | large | opted in |", "|---|---|---|---|"]
+    for r in rows:
+        inc = {True: "yes", False: "no", None: "undecided"}[r.get("include")]
+        lines.append(f"| {r['path']} | {r['detected_via']} | {'yes' if r['large'] else 'no'} | {inc} |")
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="List opted-in IDE-attached sibling projects (read-only).")
+    ap.add_argument("--all", action="store_true", help="Show every detected sibling, not only opted-in.")
+    ap.add_argument("--format", choices=("text", "json"), default="text")
+    ap.add_argument("--root", default=".", help="Project root (default: cwd).")
+    args = ap.parse_args(argv)
+
+    root = Path(args.root).resolve()
+    rows = collect(root, args.all)
+    if args.format == "json":
+        print(json.dumps({"root": str(root), "siblings": rows}, indent=2))
+    else:
+        print(render_text(rows, args.all))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/memory_lookup.py

@@ -56,12 +56,21 @@ CURATED_TYPES = {
 # conflict rule still treats them as repo entries against operational.
 KNOWLEDGE_TYPE = "knowledge"
 
+# Cross-repo retrieval (road-to-leaner-core-and-discovery Phase 4). When this
+# type is requested AND opted-in linked-project siblings exist, matches from
+# scripts/cross_repo_retrieve.py are projected as `source="cross-repo"` Hits,
+# scored below curated/knowledge so cross-repo context never outranks the
+# project's own truth (mirrors the 0.85× knowledge discount, then floored
+# further). Opt-in by caller (type must be requested) + lazy import → existing
+# call sites and consumers without the script are unaffected.
+CROSS_REPO_TYPE = "cross-repo"
+
 
 @dataclass
 class Hit:
     id: str
     type: str
-    source: str            # "curated" | "intake" | "operational"
+    source: str            # "curated" | "intake" | "operational" | "knowledge" | "cross-repo"
     path: str              # file (or logical locator) that produced the hit
     score: float           # naive, content-match based [0..1]
     entry: dict = field(default_factory=dict)
@@ -416,6 +425,45 @@ def package_operational_provider() -> Optional[OperationalProvider]:
     return _cli_operational_provider
 
 
+def _cross_repo_hits(keys: list[str], limit: int) -> list[Hit]:
+    """Project cross-repo matches into discounted, tagged Hits.
+
+    Lazy + guarded: imports `cross_repo_retrieve` on demand and swallows any
+    failure (script absent in a consumer install, no opted-in siblings) so the
+    cross-repo type degrades to zero hits rather than breaking retrieval. Scores
+    sit below curated/knowledge (0.85× floor, then a small per-rank decrement)
+    so cross-repo context never outranks the project's own truth.
+    """
+    query = " ".join(k for k in keys if k).strip()
+    if not query:
+        return []
+    try:
+        import os
+        import sys as _sys
+        from pathlib import Path as _Path
+
+        here = _Path(__file__).resolve().parent
+        if str(here) not in _sys.path:
+            _sys.path.insert(0, str(here))
+        import cross_repo_retrieve  # type: ignore
+
+        result = cross_repo_retrieve.retrieve(_Path(os.getcwd()), query, None, limit)
+    except Exception:  # noqa: BLE001 — optional surface; never break retrieval
+        return []
+
+    hits: list[Hit] = []
+    for i, m in enumerate(result.get("matches", [])):
+        hits.append(Hit(
+            id=f"cross-repo:{m.get('source_repo', '')}:{m.get('path', '')}",
+            type=CROSS_REPO_TYPE,
+            source="cross-repo",
+            path=f"{m.get('source_repo', '')}/{m.get('path', '')}",
+            score=round(0.7 * 0.85 - i * 0.01, 4),
+            entry=m,
+        ))
+    return hits
+
+
 def retrieve(
     types: list[str],
     keys: list[str],
@@ -455,6 +503,9 @@ def retrieve(
                     entry=entry,
                 ))
             continue
+        if mtype == CROSS_REPO_TYPE:
+            repo_hits.extend(_cross_repo_hits(keys, limit))
+            continue
         if mtype not in CURATED_TYPES:
             continue
         for path, entry in _iter_curated_entries(mtype):
@@ -503,7 +554,7 @@ CONTRACT_VERSION = 1
 
 # Memory types this file-backed backend can answer. Types outside this
 # set map to `unknown_type` per the retrieval contract.
-_KNOWN_TYPES = CURATED_TYPES | {KNOWLEDGE_TYPE}
+_KNOWN_TYPES = CURATED_TYPES | {KNOWLEDGE_TYPE, CROSS_REPO_TYPE}
 
 
 def retrieve_v1(