[GH-02] Establish team-based CODEOWNERS and protected review rules

[jaavid]

Background

CoreLink is managed as one product across multiple implementation boundaries. This work is owned by .github under EPIC-01.

Problem

CoreLink does not yet have verified, consistently maintained evidence that every active repository has an authoritative ownership map and protected-review enforcement. A central policy in the organization .github repository is useful, but GitHub CODEOWNERS files are repository-scoped and are not inherited automatically by other repositories.

Goal

Establish team-based ownership and protected review rules across all active repositories, with .github holding the authoritative policy/template and each repository carrying or receiving the enforcement artifacts it actually requires.

Parent

• Primary Product Epic: EPIC-01
• Backlog ID: GH-02

Scope

• Define the authoritative organization ownership policy and reusable CODEOWNERS template/generation approach in .github.
• Materialize repository-scoped CODEOWNERS in each active repository that requires code-owner review; do not assume organization-level inheritance.
• Configure or verify protected review enforcement through repository rulesets/branch protection as appropriate.
• Define a minimal documented exception path for repositories that intentionally use different ownership/review rules.
• Reconcile affected organization policy, product claims, security, release, documentation and repository maturity.
• Retain acceptance evidence for the Governance Baseline gate.

Active Repository Coverage Set

As reconciled on 2026-09-01, the active repository set in scope contains 17 repositories:

• platform
• .github
• product-planning
• api-contracts
• sdk-typescript
• sdk-python
• sdk-java
• cli
• mcp-server
• mock-server
• developer-docs
• website
• Console
• Control
• Deployment
• Identity
• design-system

Console is the canonical tenant/customer/partner/reseller frontend. Control is the separate private privileged platform-operator surface. Deployment is the canonical product-stack deployment boundary. Identity is the reusable Keycloak theme/identity presentation repository and must remain separated from deployment secrets and realm provisioning. design-system is the canonical runtime UI/design-system implementation boundary; product/design semantics remain authoritative in product-planning/design/system/. demo-repository is archived and excluded unless reactivated.

Out of Scope

• Runtime feature implementation in this Issue.
• Duplicating the product roadmap in repository README files.
• Presenting scaffolds or planned capability as a supported release.
• Treating a CODEOWNERS file in the organization .github repository as inherited enforcement for other repositories.
• Archived repositories unless they are explicitly restored to active status.

Acceptance Criteria

• Team and repository ownership is approved and documented in the authoritative organization policy.
• Every active repository in the coverage set has a repository-scoped CODEOWNERS file where code-owner review is required, or a documented approved exception.
• Protected review/ruleset configuration is verified for every active repository in scope.
• At least one real pull-request workflow demonstrates that the expected owner review is requested/enforced.
• Ownership, review and exception paths are explicit and linked from affected repositories without duplicating planning state.
• Security, license, privacy and release impacts are addressed where applicable.
• Acceptance evidence is linked and EPIC-01 is reconciled.

Current Audit Evidence — reconciled 2026-09-04

• Direct repository-content reads verify CODEOWNERS in 2 of 17 active repositories:
  • platform/.github/CODEOWNERS
  • Control/.github/CODEOWNERS
• Console/.github/CODEOWNERS is not present on the current default branch and remains part of the repository-wide enforcement backlog unless separately corrected.
• design-system/.github/CODEOWNERS is not present on the current default branch and requires CODEOWNERS or an approved exception.
• Deployment and Identity are active repository boundaries and remain in scope.
• Protected-review/ruleset enforcement still requires repository-by-repository verification where plan/integration access permits.
• Organization-wide GitHub code-search results for CODEOWNERS have produced false negatives during prior audits even when direct repository-content reads prove the file exists. Do not use organization code search as authoritative coverage evidence. Coverage validation must use direct per-repository content lookup (or an equivalent generated manifest/check) for all repositories in the active set.

Technical Notes

Use organization-wide policy/templates where useful, but keep enforcement semantics repository-local where GitHub requires it. Control should receive stricter review/security treatment than ordinary tenant-facing UI because it aggregates cross-tenant and provider/infrastructure diagnostics. Deployment should receive release/production-change ownership treatment. Identity should receive security/release review appropriate to authentication UX and published artifacts. design-system should have explicit UI-foundation/release ownership because changes propagate into multiple product surfaces and can create cross-repository accessibility/RTL/brand regressions.

The preferred durable control is a machine-generated active-repository manifest plus a coverage check that performs direct repository content verification. This avoids both stale hard-coded repository counts and false-negative organization code searches.

Dependencies

• Decision prerequisite: team and repository ownership approval must establish authoritative owners before CODEOWNERS/protection can be treated as accepted governance.
• Execution prerequisite: assign an ownership/protection disposition for each of the 17 active repositories: CODEOWNERS + enforcement, CODEOWNERS + plan-limited enforcement with explicit compensating control/risk acceptance, or documented approved exception.
• Blocks: protected review enforcement, repository ownership acceptance, and EPIC-01 governance completion.
• Cross-repository: implementation will require repository-specific changes/configuration; link concrete PRs or evidence instead of duplicating product planning.
• Current dependency state: See the CoreLink Product organization Project.

Planning Metadata

• Type: Technical Task
• Priority snapshot: P0
• Product milestone snapshot: Governance Baseline
• Domains snapshot: governance, security
• Area snapshot: operations
• Complexity: M
• Created in status: Triage
• Current status and DRI: See the CoreLink Product organization Project.
• Intended repository labels: type:technical-task

Definition of Done

• Acceptance criteria demonstrated across all 17 active repositories in scope.
• Required reviews and retained evidence pass.
• Organization and repository links are updated.
• Security and policy implications are reviewed.
• Documentation and release notes are updated where applicable.
• Pull request(s), ruleset/branch-protection evidence, compensating-control evidence, or approved exceptions are linked.

[jaavid]

Governance audit — 2026-08-27

A new enforcement constraint was confirmed while auditing GH-2:

• CoreLinkPlatform/platform is currently private.
• GET /repos/CoreLinkPlatform/platform/rulesets returns 403 with GitHub's message: “Upgrade to GitHub Pro or make this repository public to enable this feature.”
• GET /repos/CoreLinkPlatform/platform/branches/main/protection also returns 403 Resource not accessible by integration, so branch-protection state still cannot be certified from this connector.

Impact on GH-2

The current acceptance language assumes CODEOWNERS can be paired with enforceable ruleset/branch-protection review across every active repository. For private repositories on the current GitHub plan, repository rulesets are not available through GitHub's API, so this must now be treated as a concrete governance/platform constraint rather than an unknown implementation gap.

Recommended disposition per repository

Record one of these outcomes in the 12-repository ownership matrix:

1. CODEOWNERS + enforceable protected review — where the repository/plan supports it and evidence can be retained.
2. CODEOWNERS + plan-limited enforcement — ownership routing exists, but mandatory code-owner review cannot currently be certified/enforced with the available plan/API; record compensating review policy and explicit risk acceptance.
3. Approved exception — only where CODEOWNERS is intentionally not required.

Do not count a CODEOWNERS file by itself as satisfying the protected-review acceptance criterion. If organization-wide mandatory protected reviews for private repositories are a Governance Baseline requirement, the plan/visibility decision is itself a GH-2 prerequisite.