fix(project-registry): surface normalized-key collisions instead of silent first-wins

Code-review hardening: the resolver index keeps the first entry on a
normalized-form clash, so a second project normalizing to the same form
would silently mis-resolve. Detect clashes during index build and emit
them under warnings.normalized_key_collisions (live registry has none
today). Adds 2 tests.

Author: saagpatel

src/project_registry.py

@@ -305,9 +305,23 @@ def build_project_registry(
 
     by_key = {e.canonical_key: e for e in entries}
     index: dict[str, _Entry] = {}
+    collisions: list[dict] = []
     for entry in entries:
         for form in entry.matchset:
-            index.setdefault(form, entry)
+            existing = index.get(form)
+            if existing is None:
+                index[form] = entry
+            elif existing is not entry:
+                # Two distinct projects normalize to the same form: the index
+                # keeps the first (stable), so the second would mis-resolve.
+                # Surface it as a warning rather than failing silently.
+                collisions.append(
+                    {
+                        "normalized_form": form,
+                        "kept": existing.canonical_key,
+                        "shadowed": entry.canonical_key,
+                    }
+                )
     override_norm = {normalize(raw): key for raw, key in overrides.items()}
 
     def resolve_entry(raw: str) -> _Entry | None:
@@ -395,6 +409,7 @@ def resolve_entry(raw: str) -> _Entry | None:
             "notion_local": sorted(notion_orphans),
             "notion_pageid_map": sorted(pageid_unmatched),
         },
+        "warnings": {"normalized_key_collisions": collisions},
     }
 
 

tests/test_project_registry.py

@@ -159,6 +159,22 @@ def test_build_attaches_external_sources(tmp_path: Path):
     assert by_key["PortfolioCommandCenter"]["notion_local_title"] is None
 
 
+def test_normalized_key_collision_is_surfaced_not_silent():
+    # Two distinct projects whose display names normalize to the same form.
+    colliding = _snapshot(
+        _ident("NetMapper", "Net Mapper", "saagpatel/NetMapper"),
+        _ident("NetworkMapperAlt", "NetMapper", "saagpatel/NetworkMapperAlt"),
+    )
+    registry = build_project_registry(colliding, overrides_config_path=None)
+    collisions = registry["warnings"]["normalized_key_collisions"]
+    assert any(c["normalized_form"] == "netmapper" for c in collisions)
+
+
+def test_real_snapshot_shape_has_no_collisions_block_when_clean():
+    registry = build_project_registry(SNAPSHOT, overrides_config_path=None)
+    assert registry["warnings"]["normalized_key_collisions"] == []
+
+
 def test_scoring_pageids_attach_to_matching_entries():
     registry = build_project_registry(
         SNAPSHOT,