feat(registry): version Notion projection policy

Author: saagpatel

config/notion-projection-policy.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://local.invalid/github-repo-auditor/notion-projection-policy.v1.schema.json",
+  "title": "Notion projection policy",
+  "description": "Explains Local Portfolio rows that are aliases of, or intentional projections outside, GithubRepoAuditor portfolio truth.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "notion_title_aliases",
+    "notion_projection_only_rows"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "notion_projection_policy.v1"
+    },
+    "notion_title_aliases": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "notion_projection_only_rows": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string",
+        "minLength": 1
+      }
+    }
+  }
+}

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). '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.",
+	"_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_projection_policy_schema_version', '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",
@@ -34,6 +34,7 @@
 		"skill_library_port_2026-05": "",
 		"skill_eval_harness_2026-05": ""
 	},
+	"notion_projection_policy_schema_version": "notion_projection_policy.v1",
 	"notion_title_aliases": {
 		"DesktopPEt-ready": "DesktopPEt",
 		"EarthPulse-readiness": "EarthPulse",

src/project_registry.py

@@ -26,6 +26,7 @@
 from pathlib import Path
 
 SCHEMA_VERSION = "1.0"
+NOTION_PROJECTION_POLICY_SCHEMA_VERSION = "notion_projection_policy.v1"
 
 # Built-in fallbacks, mirrored by config/project-registry-overrides.json.
 # Hard normalization failures: drifted identifier -> canonical project_key.
@@ -124,20 +125,32 @@ def _strip_alias_prefix(alias: str) -> str:
 
 def load_overrides_config(
     config_path: Path | None,
-) -> tuple[dict[str, str], list[dict], dict[str, str], dict[str, str], dict[str, str]]:
+) -> tuple[
+    dict[str, str],
+    list[dict],
+    dict[str, 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),
+            NOTION_PROJECTION_POLICY_SCHEMA_VERSION,
             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)
+    projection_policy_schema_version = data.get(
+        "notion_projection_policy_schema_version",
+        NOTION_PROJECTION_POLICY_SCHEMA_VERSION,
+    )
     title_aliases = data.get("notion_title_aliases", DEFAULT_NOTION_TITLE_ALIASES)
     projection_only = data.get(
         "notion_projection_only_rows", DEFAULT_NOTION_PROJECTION_ONLY_ROWS
@@ -146,6 +159,7 @@ def load_overrides_config(
         dict(overrides),
         [dict(s) for s in supplementary],
         dict(memory_meta),
+        str(projection_policy_schema_version),
         dict(title_aliases),
         dict(projection_only),
     )
@@ -314,6 +328,7 @@ def build_project_registry(
         overrides,
         supplementary,
         memory_meta,
+        notion_projection_policy_schema_version,
         notion_title_aliases,
         notion_projection_only_rows,
     ) = load_overrides_config(overrides_config_path)
@@ -463,6 +478,7 @@ def resolve_entry(raw: str) -> _Entry | None:
         "entry_count": len(entries),
         "resolution_overrides": overrides,
         "projection_policy": {
+            "schema_version": notion_projection_policy_schema_version,
             "notion_title_aliases": notion_title_aliases,
             "notion_projection_only_rows": notion_projection_only_rows,
         },

tests/test_project_registry.py

@@ -113,6 +113,7 @@ def test_resolve_supplementary_from_each_spelling():
 def test_projection_policy_is_published_from_defaults():
     registry = build_project_registry(SNAPSHOT, overrides_config_path=None)
     policy = registry["projection_policy"]
+    assert policy["schema_version"] == "notion_projection_policy.v1"
     assert policy["notion_title_aliases"]["DesktopPEt-ready"] == "DesktopPEt"
     assert "SecondBrain" in policy["notion_projection_only_rows"]