ci: exempt generated API reference pages from codeowner review

.github/codeowners/README.md

@@ -93,9 +93,17 @@ generated outputs together.
   `external_contributors.yaml`. Adding, deleting, or moving unrelated tracked
   files cannot rewrite the generated rules.
 - Rule precedence follows CODEOWNERS last-match-wins semantics: catch-all and
-  base area rules, file-type defaults, nested path overrides, then explicit
-  `shared` rules. Overlapping file-type rules retain their YAML declaration
-  order, so later entries refine earlier ones.
+  base area rules, file-type defaults, nested path overrides, explicit
+  `shared` rules, then `unowned` globs. Overlapping file-type rules retain
+  their YAML declaration order, so later entries refine earlier ones.
+- `unowned:` globs are emitted **last with no owner** — GitHub's ownerless-
+  pattern semantics — so matching files require no codeowner review at all.
+  Reserved for deterministic generator outputs whose integrity a CI freshness
+  gate already guards (hand edits fail `--check`); a human sign-off on such an
+  artifact adds a reviewer without adding scrutiny, and routes source-only PRs
+  to unrelated teams. The generators themselves stay owned. The coverage gate
+  counts unowned globs as claimed, and declaring the same glob `shared` and
+  `unowned` is rejected.
 - Legacy `classify.keyword_rules` are rejected because auto-classification and
   keyword co-ownership required a live tree. Declare ownership with explicit
   area `path_globs` or `shared` entries.

.github/codeowners/areas.yaml

@@ -1098,3 +1098,6 @@ classify:
   filetype_rules:
   - pattern: '*Dockerfile*'
     coowner: ops
+unowned:
+- docs/fern/pages/reference/api/python/*.mdx
+- docs/fern/pages/reference/api/rust/README.mdx

.github/codeowners/codeowners_match.py

@@ -113,6 +113,7 @@ class ResolvedModel:
     shared: list[SharedSpec]
     filetype_shared: list[FiletypeShared]
     meta: dict = field(default_factory=dict)
+    unowned: list[str] = field(default_factory=list)
 
     def label_to_team(self) -> dict[str, str]:
         return {a.label: a.github_team for a in self.areas}
@@ -138,6 +139,10 @@ def owned_patterns(self) -> list[str]:
         # keep them unanchored in the coverage set too.
         for fs in self.filetype_shared:
             pats.append(fs.glob)
+        # Explicitly unowned globs are a deliberate routing decision (review
+        # exemption), not a coverage hole -- the gate must not report them as
+        # catch-all-only.
+        pats.extend(anchor(g) for g in self.unowned)
         return pats
 
     def unmatched_paths(self, tree: Iterable[str]) -> list[str]:
@@ -232,15 +237,20 @@ def resolve_owners(rules: list[tuple[str, list[str]]], filepath: str) -> list[st
 
 
 def parse_codeowners(text: str) -> list[tuple[str, list[str]]]:
-    """Parse a CODEOWNERS file body into ordered ``(pattern, [owner, ...])``."""
+    """Parse a CODEOWNERS file body into ordered ``(pattern, [owner, ...])``.
+
+    A pattern with no owners is kept as ``(pattern, [])`` -- GitHub treats
+    such a line as an explicit review exemption (last-match still applies),
+    so dropping it would make ``resolve_owners`` fall back to whatever owner
+    an earlier, broader rule declared.
+    """
     rules: list[tuple[str, list[str]]] = []
     for line in text.splitlines():
         stripped = line.split("#", 1)[0].strip()
         if not stripped:
             continue
         pattern, *owners = stripped.split()
-        if owners:
-            rules.append((pattern, owners))
+        rules.append((pattern, owners))
     return rules
 
 
@@ -313,6 +323,11 @@ def compute_resolution(spec: dict, tree: Iterable[str] | None = None) -> Resolve
 
     * ``areas``       -- ``path_globs`` are emitted verbatim (sorted).
     * ``shared``      -- passed through as declared.
+    * ``unowned``     -- globs emitted LAST with no owner: an explicit
+      review exemption (GitHub's ownerless-pattern semantics) for content
+      whose integrity is guarded by CI rather than human review, e.g.
+      deterministic generator outputs. The coverage gate counts these as
+      claimed, not as catch-all holes.
     * ``advisory``    -- no longer supported. Every owner in CODEOWNERS blocks,
       so a leftover ``advisory:`` block, an ``advisory`` key on a ``shared``
       entry, or one on a filetype rule, is rejected rather than silently
@@ -373,6 +388,32 @@ def compute_resolution(spec: dict, tree: Iterable[str] | None = None) -> Resolve
                 "'advisory' key; shared entries always block -- remove it"
             )
 
+    raw_unowned = spec.get("unowned", []) or []
+    if not isinstance(raw_unowned, list):
+        # A scalar string would iterate per-character below and silently
+        # emit ownerless rules like ``/d`` ``/o`` ``/c`` ``/s``.
+        raise SystemExit(
+            f"areas.yaml: unowned must be a LIST of glob strings, got {raw_unowned!r}"
+        )
+    for g in raw_unowned:
+        if not isinstance(g, str) or not g.strip():
+            raise SystemExit(
+                f"areas.yaml: unowned entry {g!r} must be a non-empty glob string"
+            )
+    # Store anchored so the conflict check below compares the canonical
+    # spelling emission uses -- ``docs/x/`` and ``/docs/x/`` are the same
+    # emitted rule and must collide here (anchor() is idempotent, so the
+    # emitter and coverage gate re-anchoring is a no-op).
+    unowned = sorted({anchor(g) for g in raw_unowned})
+    shared_globs = {anchor(s["glob"]) for s in spec_shared}
+    conflict = shared_globs & set(unowned)
+    if conflict:
+        raise SystemExit(
+            "areas.yaml: glob(s) declared both shared and unowned "
+            f"({sorted(conflict)}); pick one -- unowned is emitted last and "
+            "would silently strip the shared owners"
+        )
+
     areas = [
         ResolvedArea(
             label=a["label"],
@@ -404,6 +445,7 @@ def compute_resolution(spec: dict, tree: Iterable[str] | None = None) -> Resolve
         shared=list(spec_shared),
         filetype_shared=filetype_shared,
         meta=dict(spec.get("meta", {})),
+        unowned=unowned,
     )
 
 

.github/codeowners/emit_codeowners.py

@@ -356,11 +356,25 @@ def fmt(path: str, team: str) -> str:
         ]
         lines += [fmt(p, deco(t)) for p, t in shared_rules]
 
+    unowned_rules = sorted(
+        (anchor(g) for g in model.unowned), key=lambda p: (len(p), p)
+    )
+    if unowned_rules:
+        lines += [
+            "",
+            "# --- Explicitly unowned: no codeowner review required (wins via last-match).",
+            "# Deterministic generator outputs whose integrity is guarded by CI",
+            "# (freshness --check gates), so human review of the artifact is redundant",
+            "# and would route source-only PRs to unrelated reviewers. ---",
+        ]
+        lines += unowned_rules
+
     stats = {
         "base": len(base_rules),
         "shared": len(shared_rules),
         "filetype": len(ft_rules),
         "overrides": len(overrides),
+        "unowned": len(unowned_rules),
         "teams": len(teams),
     }
     return lines, stats
@@ -413,11 +427,13 @@ def main() -> int:
         stats["base"]
         + stats["shared"]
         + stats["filetype"]
+        + stats["unowned"]
         + (1 if model.catch_all else 0)
     )
     print(
         f"wrote {args.out} | rules: {total} (base {stats['base']} | "
-        f"shared {stats['shared']} | file-type {stats['filetype']}) | "
+        f"shared {stats['shared']} | file-type {stats['filetype']} | "
+        f"unowned {stats['unowned']}) | "
         f"overrides pulled out: {stats['overrides']} | "
         f"teams referenced: {stats['teams']}"
     )

.github/codeowners/test_codeowners.py

@@ -1102,3 +1102,108 @@ def test_no_externals_is_unchanged(self) -> None:
         model = self._model()
         plain, _ = _render_codeowners(model, group=True, external=[])
         assert not any("@jane" in ln for ln in plain)
+
+
+class TestUnowned:
+    """``unowned:`` -- explicit review exemption for CI-guarded generated files."""
+
+    def _spec(self) -> dict:
+        return {
+            "meta": {"catch_all": "@root"},
+            "areas": [
+                {
+                    "label": "docs",
+                    "github_team": "@docs",
+                    "path_globs": ["docs/"],
+                },
+            ],
+            "shared": [],
+            "unowned": ["docs/fern/pages/reference/api/python/"],
+        }
+
+    def _rendered(self, spec: dict) -> str:
+        model = compute_resolution(spec)
+        lines, _ = _render_codeowners(model, group=True, external=[])
+        return "\n".join(lines) + "\n"
+
+    def test_unowned_line_wins_last_match_with_no_owner(self) -> None:
+        rules = parse_codeowners(self._rendered(self._spec()))
+        assert (
+            resolve_owners(rules, "docs/fern/pages/reference/api/python/frontend.mdx")
+            == []
+        )
+        # Everything else under docs/ stays docs-owned.
+        assert resolve_owners(rules, "docs/fern/scripts/gen_python_api.py") == ["@docs"]
+        assert resolve_owners(rules, "docs/fern/pages/reference/api/README.mdx") == [
+            "@docs"
+        ]
+
+    def test_unowned_is_emitted_after_shared(self) -> None:
+        spec = self._spec()
+        spec["shared"] = [
+            {"glob": "docs/fern/pages/", "owners": ["docs"]},
+        ]
+        rendered = self._rendered(spec)
+        shared_idx = rendered.index("/docs/fern/pages/ ")
+        unowned_idx = rendered.index("/docs/fern/pages/reference/api/python/\n")
+        assert unowned_idx > shared_idx
+
+    def test_unowned_counts_as_claimed_for_coverage(self) -> None:
+        model = compute_resolution(self._spec())
+        tree = [
+            "docs/fern/pages/reference/api/python/frontend.mdx",
+            "src/orphan.rs",
+        ]
+        assert model.unmatched_paths(tree) == ["src/orphan.rs"]
+
+    def test_parse_codeowners_keeps_ownerless_rules(self) -> None:
+        rules = parse_codeowners("*  @root\n/generated/\n")
+        assert rules == [("*", ["@root"]), ("/generated/", [])]
+
+    def test_glob_both_shared_and_unowned_is_fatal(self) -> None:
+        spec = self._spec()
+        spec["shared"] = [
+            {"glob": "docs/fern/pages/reference/api/python/", "owners": ["docs"]},
+        ]
+        with pytest.raises(SystemExit, match="shared and unowned"):
+            compute_resolution(spec)
+
+    def test_empty_unowned_entry_is_fatal(self) -> None:
+        spec = self._spec()
+        spec["unowned"] = ["  "]
+        with pytest.raises(SystemExit, match="non-empty glob"):
+            compute_resolution(spec)
+
+    def test_scalar_unowned_is_fatal(self) -> None:
+        # A scalar would iterate per-character and emit /d /o /c /s rules.
+        spec = self._spec()
+        spec["unowned"] = "docs/generated/"
+        with pytest.raises(SystemExit, match="LIST of glob strings"):
+            compute_resolution(spec)
+
+    def test_shared_unowned_conflict_detected_across_anchor_spellings(self) -> None:
+        # docs/x/ and /docs/x/ are the same emitted rule; the guard must
+        # compare canonical (anchored) forms, not raw spellings.
+        spec = self._spec()
+        spec["unowned"] = ["/docs/fern/pages/reference/api/python/"]
+        spec["shared"] = [
+            {"glob": "docs/fern/pages/reference/api/python/", "owners": ["docs"]},
+        ]
+        with pytest.raises(SystemExit, match="shared and unowned"):
+            compute_resolution(spec)
+
+    def test_star_glob_exempts_only_direct_mdx_files(self) -> None:
+        spec = self._spec()
+        spec["unowned"] = ["docs/fern/pages/reference/api/python/*.mdx"]
+        rules = parse_codeowners(self._rendered(spec))
+        assert (
+            resolve_owners(rules, "docs/fern/pages/reference/api/python/frontend.mdx")
+            == []
+        )
+        # A smuggled non-generated file in the same dir stays docs-owned.
+        assert resolve_owners(
+            rules, "docs/fern/pages/reference/api/python/custom.txt"
+        ) == ["@docs"]
+        assert resolve_owners(
+            rules, "docs/fern/pages/reference/api/python/sub/deep.mdx"
+        ) == ["@docs"]

.github/codeowners/who_owns.py

@@ -104,7 +104,7 @@ def main() -> int:
         owners_str = (
             " ".join(owners)
             if owners
-            else "(no owner -- falls through; CI coverage gate should block this)"
+            else "(no owner -- explicitly unowned or uncovered; no codeowner review requested)"
         )
         print(f"{f}\n    review: {owners_str}")
 

CODEOWNERS

@@ -720,3 +720,10 @@
 /components/src/dynamo/common/memory/multimodal_embedding_cache_manager.py   @ai-dynamo/dynamo-runtime-codeowners @ai-dynamo/dynamo-multimodal-codeowners
 /components/src/dynamo/mocker/utils/planner_profiler_perf_data_converter.py  @ai-dynamo/dynamo-performance-codeowners @ai-dynamo/dynamo-planner-codeowners
 /tests/fault_tolerance/hardware/fault_injection_service/api_service/main.py  @ai-dynamo/dynamo-fault-tolerance-codeowners @ai-dynamo/dynamo-observability-codeowners
+
+# --- Explicitly unowned: no codeowner review required (wins via last-match).
+# Deterministic generator outputs whose integrity is guarded by CI
+# (freshness --check gates), so human review of the artifact is redundant
+# and would route source-only PRs to unrelated reviewers. ---
+/docs/fern/pages/reference/api/python/*.mdx
+/docs/fern/pages/reference/api/rust/README.mdx