feat(registry): publish Notion projection policy

Author: saagpatel

config/project-registry-overrides.json

@@ -1,5 +1,5 @@
 {
-	"_comment": "Operator-editable enrollment for the canonical project registry. 'overrides' pins hard normalization failures (drifted identifier -> canonical project_key). 'supplementary' enrolls real operator-OS projects the auditor does not track as git repos. 'memory_meta' maps ~/.claude memory note-slugs to their parent project (or '' for pure meta-notes). Consumed by src/project_registry.py; falls back to built-in defaults if this file is absent.",
+	"_comment": "Operator-editable enrollment for the canonical project registry. 'overrides' pins hard normalization failures (drifted identifier -> canonical project_key). 'supplementary' enrolls real operator-OS projects the auditor does not track as git repos. 'memory_meta' maps ~/.claude memory note-slugs to their parent project (or '' for pure meta-notes). 'notion_title_aliases' and 'notion_projection_only_rows' explain Local Portfolio projection differences that are not distinct GithubRepoAuditor truth projects. Consumed by src/project_registry.py and cross-system smoke checks; falls back to built-in defaults if this file is absent.",
 	"overrides": {
 		"jcc": "JobCommandCenter",
 		"jsm_export": "JSMTicketAnalyticsExport",
@@ -33,5 +33,20 @@
 		"github_repo_auditor_future_arcs": "GithubRepoAuditor",
 		"skill_library_port_2026-05": "",
 		"skill_eval_harness_2026-05": ""
+	},
+	"notion_title_aliases": {
+		"DesktopPEt-ready": "DesktopPEt",
+		"EarthPulse-readiness": "EarthPulse",
+		"GithubRepoAuditor-public": "GithubRepoAuditor",
+		"Notion Operating System": "Notion",
+		"OrbitForge (staging)": "OrbitForge",
+		"Personal Ops": "operator-os-docs",
+		"PomGambler-prod": "PomGambler"
+	},
+	"notion_projection_only_rows": {
+		"app": "local runtime/app shell placeholder; not a portfolio-truth repo",
+		"claude-code-harness": "local agent harness projection; outside repo-root truth",
+		"Sandbox Local Portfolio Project": "actuation sandbox fixture row",
+		"SecondBrain": "knowledge vault under /Users/d/Documents; not a /Users/d/Projects repo"
 	}
 }

src/project_registry.py

@@ -75,6 +75,23 @@
     "skill_eval_harness_2026-05": "",
 }
 
+DEFAULT_NOTION_TITLE_ALIASES: dict[str, str] = {
+    "DesktopPEt-ready": "DesktopPEt",
+    "EarthPulse-readiness": "EarthPulse",
+    "GithubRepoAuditor-public": "GithubRepoAuditor",
+    "Notion Operating System": "Notion",
+    "OrbitForge (staging)": "OrbitForge",
+    "Personal Ops": "operator-os-docs",
+    "PomGambler-prod": "PomGambler",
+}
+
+DEFAULT_NOTION_PROJECTION_ONLY_ROWS: dict[str, str] = {
+    "app": "local runtime/app shell placeholder; not a portfolio-truth repo",
+    "claude-code-harness": "local agent harness projection; outside repo-root truth",
+    "Sandbox Local Portfolio Project": "actuation sandbox fixture row",
+    "SecondBrain": "knowledge vault under /Users/d/Documents; not a /Users/d/Projects repo",
+}
+
 # Operator-machine source locations (overridable via the "sources" block of
 # config/project-registry-overrides.json). Every source is optional.
 DEFAULT_SOURCES: dict[str, str] = {
@@ -107,19 +124,31 @@ def _strip_alias_prefix(alias: str) -> str:
 
 def load_overrides_config(
     config_path: Path | None,
-) -> tuple[dict[str, str], list[dict], dict[str, str]]:
+) -> tuple[dict[str, str], list[dict], dict[str, str], dict[str, str], dict[str, str]]:
     """Load overrides + supplementary + memory-meta, falling back to defaults."""
     if config_path is None or not config_path.exists():
         return (
             dict(DEFAULT_OVERRIDES),
             [dict(s) for s in DEFAULT_SUPPLEMENTARY],
             dict(DEFAULT_MEMORY_META),
+            dict(DEFAULT_NOTION_TITLE_ALIASES),
+            dict(DEFAULT_NOTION_PROJECTION_ONLY_ROWS),
         )
     data = json.loads(config_path.read_text())
     overrides = data.get("overrides", DEFAULT_OVERRIDES)
     supplementary = data.get("supplementary", DEFAULT_SUPPLEMENTARY)
     memory_meta = data.get("memory_meta", DEFAULT_MEMORY_META)
-    return dict(overrides), [dict(s) for s in supplementary], dict(memory_meta)
+    title_aliases = data.get("notion_title_aliases", DEFAULT_NOTION_TITLE_ALIASES)
+    projection_only = data.get(
+        "notion_projection_only_rows", DEFAULT_NOTION_PROJECTION_ONLY_ROWS
+    )
+    return (
+        dict(overrides),
+        [dict(s) for s in supplementary],
+        dict(memory_meta),
+        dict(title_aliases),
+        dict(projection_only),
+    )
 
 
 def load_source_paths(config_path: Path | None) -> dict[str, object]:
@@ -281,7 +310,13 @@ def build_project_registry(
     ``snapshot`` is the serialized portfolio-truth (``snapshot.to_dict()``).
     All other sources are optional and degrade gracefully.
     """
-    overrides, supplementary, memory_meta = load_overrides_config(overrides_config_path)
+    (
+        overrides,
+        supplementary,
+        memory_meta,
+        notion_title_aliases,
+        notion_projection_only_rows,
+    ) = load_overrides_config(overrides_config_path)
     generated_at = generated_at or datetime.now(timezone.utc)
 
     entries: list[_Entry] = [
@@ -323,8 +358,14 @@ def build_project_registry(
                     }
                 )
     override_norm = {normalize(raw): key for raw, key in overrides.items()}
+    title_alias_norm = {
+        normalize(raw): target for raw, target in notion_title_aliases.items()
+    }
+    projection_only_norm = {
+        normalize(raw): raw for raw in notion_projection_only_rows
+    }
 
-    def resolve_entry(raw: str) -> _Entry | None:
+    def resolve_entry_direct(raw: str) -> _Entry | None:
         norm = normalize(raw)
         if not norm:
             return None
@@ -334,12 +375,31 @@ def resolve_entry(raw: str) -> _Entry | None:
                 return target
         return index.get(norm)
 
+    def resolve_entry(raw: str) -> _Entry | None:
+        entry = resolve_entry_direct(raw)
+        if entry is not None:
+            return entry
+        alias_target = title_alias_norm.get(normalize(raw))
+        if alias_target:
+            return resolve_entry_direct(alias_target)
+        return None
+
     notion_orphans: list[str] = []
+    notion_projection_only: list[dict[str, str]] = []
     for title in _read_notion_titles(notion_snapshot_path):
         entry = resolve_entry(title)
         if entry is not None:
             entry.notion_local_title = title
             entry.add_alias(f"notion:{title}")
+        elif normalize(title) in projection_only_norm:
+            notion_projection_only.append(
+                {
+                    "title": title,
+                    "reason": notion_projection_only_rows.get(title)
+                    or notion_projection_only_rows.get(projection_only_norm[normalize(title)])
+                    or "",
+                }
+            )
         else:
             notion_orphans.append(title)
 
@@ -402,7 +462,14 @@ def resolve_entry(raw: str) -> _Entry | None:
         },
         "entry_count": len(entries),
         "resolution_overrides": overrides,
+        "projection_policy": {
+            "notion_title_aliases": notion_title_aliases,
+            "notion_projection_only_rows": notion_projection_only_rows,
+        },
         "entries": [e.to_dict() for e in entries],
+        "projection_only": {
+            "notion_local": sorted(notion_projection_only, key=lambda row: row["title"])
+        },
         "unmatched": {
             "bridge": sorted(bridge_orphans),
             "memory": memory_orphans,

tests/test_project_registry.py

@@ -45,6 +45,7 @@ def _ident(project_key: str, display_name: str, repo: str | None = None) -> dict
     ),
     _ident("Notion", "Notion", "saagpatel/notion-operating-system"),
     _ident("PortfolioCommandCenter", "PortfolioCommandCenter", "saagpatel/PortfolioCommandCenter"),
+    _ident("Fun:GamePrjs/DesktopPEt", "DesktopPEt", "saagpatel/DesktopPEt"),
 )
 
 
@@ -109,6 +110,13 @@ def test_resolve_supplementary_from_each_spelling():
     assert resolve("SecondBrain", index)["canonical_key"] == "supp:SecondBrain"
 
 
+def test_projection_policy_is_published_from_defaults():
+    registry = build_project_registry(SNAPSHOT, overrides_config_path=None)
+    policy = registry["projection_policy"]
+    assert policy["notion_title_aliases"]["DesktopPEt-ready"] == "DesktopPEt"
+    assert "SecondBrain" in policy["notion_projection_only_rows"]
+
+
 def test_resolve_returns_none_for_non_projects():
     registry = build_project_registry(SNAPSHOT, overrides_config_path=None)
     index = build_index(registry)
@@ -134,7 +142,17 @@ def test_build_degrades_gracefully_without_external_sources():
 def test_build_attaches_external_sources(tmp_path: Path):
     bridge = _bridge_db(tmp_path, ["MCPAudit", "PortfolioCommandCenter", "weekly-review"])
     snap = tmp_path / "snapshot.json"
-    snap.write_text(json.dumps({"projects": [{"title": "MCP Audit"}, {"title": "app"}]}))
+    snap.write_text(
+        json.dumps(
+            {
+                "projects": [
+                    {"title": "MCP Audit"},
+                    {"title": "DesktopPEt-ready"},
+                    {"title": "app"},
+                ]
+            }
+        )
+    )
     memdir = tmp_path / "memory"
     memdir.mkdir()
     (memdir / "project_mcpaudit.md").write_text("x")
@@ -151,9 +169,18 @@ def test_build_attaches_external_sources(tmp_path: Path):
     assert mcp["bridge_project_names"] == ["MCPAudit"]
     assert mcp["notion_local_title"] == "MCP Audit"
     assert mcp["memory_slug"] == "project_mcpaudit"
-    # bridge noise + notion junk land in unmatched, not on an entry
+    desktop = by_key["Fun:GamePrjs/DesktopPEt"]
+    assert desktop["notion_local_title"] == "DesktopPEt-ready"
+    assert "notion:DesktopPEt-ready" in desktop["aliases"]
+    # bridge noise lands in unmatched; projection-only Notion rows are explained separately
     assert "weekly-review" in registry["unmatched"]["bridge"]
-    assert "app" in registry["unmatched"]["notion_local"]
+    assert registry["unmatched"]["notion_local"] == []
+    assert registry["projection_only"]["notion_local"] == [
+        {
+            "title": "app",
+            "reason": "local runtime/app shell placeholder; not a portfolio-truth repo",
+        }
+    ]
     # PortfolioCommandCenter resolves from bridge but has no Notion/memory row
     assert by_key["PortfolioCommandCenter"]["bridge_project_names"] == ["PortfolioCommandCenter"]
     assert by_key["PortfolioCommandCenter"]["notion_local_title"] is None