feat: cross-level xref link scopes via detail_reference and member tag

backend/agents/linker.py

@@ -30,9 +30,23 @@ def _family(assertion: Dict) -> str:
     )
 
 
+def _xref_keys(assertion: Dict) -> List[str]:
+    """Cross-level join keys: detail references and member tags."""
+    location = assertion.get("location_key") or {}
+    keys = []
+    ref = re.sub(r"\s+", "", str(location.get("detail_reference") or "")).upper()
+    if ref:
+        keys.append(f"detail:{ref}")
+    tag = re.sub(r"\s+", "", str(location.get("tag") or "")).upper()
+    if re.match(r"^[A-Z]{2,}\d", tag):  # member marks: HSS16X4X5/8, W12X26, ...
+        keys.append(f"tag:{tag}")
+    return keys
+
+
 def build_link_scopes(sheets: List[Dict]) -> List[AgentScope]:
     """Partition facts by level and object/tag family, then enforce a hard cap."""
     buckets: Dict[Tuple[str, str], List[Dict]] = defaultdict(list)
+    xref: Dict[str, List[Dict]] = defaultdict(list)
     for sheet in sheets:
         for assertion in sheet.get("assertions", []):
             enriched = {
@@ -44,6 +58,8 @@ def build_link_scopes(sheets: List[Dict]) -> List[AgentScope]:
             level = str((assertion.get("location_key") or {}).get("level")
                         or sheet.get("level") or "unknown").lower()
             buckets[(level, _family(assertion))].append(enriched)
+            for key in _xref_keys(assertion):
+                xref[key].append(enriched)
 
     scopes: List[AgentScope] = []
     cap = max(2, config.AGENT_LINK_MAX_ASSERTIONS)
@@ -56,6 +72,15 @@ def build_link_scopes(sheets: List[Dict]) -> List[AgentScope]:
                 scope_id=f"{level}:{family}:{offset // cap + 1}",
                 payload={"assertions": chunk, "level": level, "family": family},
             ))
+    for key, assertions in sorted(xref.items()):
+        sheets_present = {a.get("sheet_number") for a in assertions}
+        if len(assertions) < 2 or len(sheets_present) < 2:
+            continue
+        scopes.append(AgentScope(
+            scope_id=f"xref:{key}",
+            payload={"assertions": assertions[:cap],
+                     "level": "xref", "family": key},
+        ))
     return scopes