chore: implement org-wide governance logic

.github/workflows/pre-commit.yml

@@ -1,4 +1,4 @@
-#   Copyright 2026 Google LLC
+#   Copyright 2026 UCP Authors
 #
 #   Licensed under the Apache License, Version 2.0 (the "License");
 #   you may not use this file except in compliance with the License.
@@ -23,7 +23,7 @@ jobs:
   pre-commit:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
       - uses: actions/setup-python@v6
         with:
           python-version: "3.12"

.github/workflows/reusable-governance.yml

@@ -0,0 +1,114 @@
+#   Copyright 2026 UCP Authors
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+
+name: Reusable Governance Gate
+
+on:
+  workflow_call:
+    inputs:
+      repo-name:
+        required: true
+        type: string
+        description: "Path to the governance rules configuration file"
+    secrets:
+      ORG_READ_TOKEN:
+        required: true
+        description: "Org-level read token for team membership checks"
+
+jobs:
+  evaluate:
+    name: Approvals
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.draft == false
+    steps:
+      # 1. Check out the caller repository (the PR code)
+      - name: Check out PR code
+        uses: actions/checkout@v7
+
+      # 2. Check out the central governance scripts from the central repository
+      - name: Check out central governance scripts
+        uses: actions/checkout@v7
+        with:
+          repository: ${{ github.repository_owner }}/.github
+          path: .github-central
+          token: ${{ secrets.ORG_READ_TOKEN }}
+
+      # 3. Set up uv using the standard action
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      # 4. Run governance gate check and capture the exit code
+      - name: Evaluate Required Approvals
+        id: validator
+        run: |
+          set +e
+
+          uv run .github-central/org-tools/governance/scripts/pr_validator.py \
+            --token "${{ secrets.ORG_READ_TOKEN }}" \
+            --org "${{ github.repository_owner }}" \
+            --repo "${{ github.repository }}" \
+            --pr "${{ github.event.pull_request.number }}" \
+            --repo-name "${{ inputs.repo-name }}"
+
+          EVAL_EXIT_CODE=$?
+          set -e
+
+          # Save the exit code to the GitHub step outputs
+          echo "exit_code=$EVAL_EXIT_CODE" >> "$GITHUB_OUTPUT"
+
+          # --- NEW: Create the Job Summary and Annotation ---
+          if [ -f summary.txt ]; then
+            # 1. Write the rich Markdown report directly to the GitHub Job Summary page
+            cat summary.txt >> "$GITHUB_STEP_SUMMARY"
+
+            # 2. Properly escape newlines (%0A) and carriage returns (%0D)
+            # to prevent truncation in the inline workflow annotations
+            SUMMARY_TEXT=$(cat summary.txt | tr -d '\r' | sed ':a;N;$!ba;s/\n/%0A/g')
+
+            # 3. Post it as an annotation in the UI
+            if [ "$EVAL_EXIT_CODE" -eq 0 ]; then
+              echo "::notice title=Approval Status::$SUMMARY_TEXT"
+            else
+              echo "::error title=Missing Approvals::$SUMMARY_TEXT"
+            fi
+          fi
+          # ----------------------------------
+
+          exit 0
+
+      # 5. Post the static Commit Status to the GitHub API with a clickable log link
+      - name: Post Static Status Check
+        uses: actions/github-script@v9
+        with:
+          script: |
+            // Read the exit code from the previous step
+            const exitCode = parseInt('${{ steps.validator.outputs.exit_code }}', 10);
+
+            // Map the exit code to a GitHub status state
+            const state = (exitCode === 0) ? 'success' : 'failure';
+            const description = (exitCode === 0) ? 'Governance approvals met' : 'Pending required approvals';
+
+            // Construct the exact URL to the current GitHub Actions workflow run logs
+            const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+
+            // Post the status to the specific commit hash
+            await github.rest.repos.createCommitStatus({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              sha: context.payload.pull_request.head.sha,
+              state: state,
+              context: 'Governance / Approvals',
+              description: description,
+              target_url: runUrl  // <-- This makes the status check clickable
+            });

.github/workflows/tests.yml

@@ -0,0 +1,40 @@
+#   Copyright 2026 UCP Authors
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  run-tests:
+    name: Run Unit Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: "3.12"
+
+      - name: Run governance tests
+        run: uv run --with PyGithub --with PyYAML python -m unittest discover -s org-tools/governance/tests
+
+      - name: Run label-sync tests
+        run: uv run --with PyGithub --with PyYAML python org-tools/test_sync_labels.py

org-tools/governance/README.md

@@ -0,0 +1,155 @@
+# GitHub Org Governance Tools - PR Validator
+
+This directory contains the GitHub Org Governance validator tools. The `pr_validator.py` script acts as a CI/CD gated workflow step to enforce custom review rules and team-approval requirements on Pull Requests, using dynamic team hierarchies, file glob rules, and proxy review capabilities.
+
+---
+
+## Architecture Overview
+
+The system consists of the following key components:
+
+```mermaid
+graph TD
+    A[reusable-governance.yml Workflow] --> B(pr_validator.py main)
+    subgraph pr_validator.py
+        B
+        E[PullRequestValidator]
+    end
+    subgraph governance_config_parser.py
+        C[GovernanceConfigParser]
+        D[GovernanceConfigValidator]
+    end
+    B --> C
+    B --> D
+    B --> E
+    C -->|Reads Config| F(python-sdk-rules.yml)
+    D -->|Static Sanity Analysis| F
+    E -->|Evaluates approvals| G[GitHub API]
+```
+
+- **`pr_validator.py`**: The entrypoint script and validator logic.
+  - `PullRequestValidator`: Fetches PR metadata (changed files, reviews, authors) from GitHub, queries team memberships, and evaluates reviews against the governance rules.
+- **`governance_config_parser.py`**: Helper module for loading rules and analyzing configurations.
+  - `GovernanceConfigParser`: Parses YAML configuration files into typed python dataclasses (`Team`, `GovernanceRule`, `GovernanceConfig`, etc.).
+  - `GovernanceConfigValidator`: Performs static analysis on the repository files to detect rule design flaws (overlapping rules or files falling into default fallbacks).
+
+---
+
+## Configuration Schema
+
+Governance rules are defined using YAML. Below is an overview of the configuration schema (e.g. `rules/python-sdk-rules.yml`):
+
+### 1. `team_hierarchy`
+
+Defines hierarchical roles with integer clearance tiers. Approvals from higher levels automatically satisfy requirements for lower levels (e.g. an approval from a level 4 member counts as a level 2 approval):
+
+```yaml
+team_hierarchy:
+  devops-maintainers: 1
+  maintainers: 2
+  tech-council: 3
+  governance-council: 4
+```
+
+### 2. `fallback`
+
+Defines catch-all requirements applied to any file that does not match a specific custom rule:
+
+```yaml
+fallback:
+  requires:
+    - min_team: "maintainers"
+      min_approvals: 1
+```
+
+### 3. `rules`
+
+A list of review criteria matching specific file glob patterns:
+
+- `patterns`: File paths or wildcards (supports `*`, `**`, `?` globs) matching target files.
+- `excludes`: Optional glob patterns to exclude from the rule.
+- `requires`: The specific approval targets:
+  - `team`: Requires an approval from an exact team.
+  - `min_team`: Requires an approval from the specified team or any team higher in the hierarchy.
+  - `min_approvals`: Number of approvals required from members of that team/tier.
+
+```yaml
+rules:
+  - name: "core_protocol_src"
+    patterns:
+      - "source/**"
+    requires:
+      - min_team: "tech-council"
+        min_approvals: 1
+```
+
+### 4. `proxy_reviewers`
+
+A list of GitHub usernames allowed to approve PRs on behalf of any required team.
+
+```yaml
+proxy_reviewers:
+  - user_a
+  - user_b
+```
+
+---
+
+## How It Works
+
+### Step 1: Static Config Verification
+
+Before checking any PR, `pr_validator.py` instantiates the `GovernanceConfigValidator` to perform static validation checks:
+
+1.  **Overlap Detection**: Verifies that no file in the repository matches more than one rule (to prevent conflicting requirements).
+2.  **Coverage Verification (No-Fallback)**: If strict coverage is desired, it verifies that every single tracked file in the repository matches at least one explicit rule.
+
+### Step 2: PR Evaluation Logic
+
+When evaluating a pull request:
+
+1.  **Filter Author**: The PR author's own approvals are ignored.
+2.  **Match Rules**: Compares all modified files in the PR against the rules to collect the matching `RuleRequirement` sets. If a file matches no rule, the `fallback` requirements are applied.
+3.  **Resolve Approvals**:
+    - Retrieves active PR reviews from GitHub.
+    - Checks if the reviewer is a proxy reviewer.
+    - Queries team memberships for reviewers from the GitHub API.
+    - Maps team memberships to hierarchical levels.
+4.  **Evaluate Gates**: Validates that the approvals fulfill every required target. Prints results and writes a review summary to `summary.txt`.
+
+---
+
+## CLI Usage
+
+Run the validator CLI command in the root of the checked-out repository:
+
+```bash
+python3 org-tools/governance/scripts/pr_validator.py \
+  --token "<GITHUB_TOKEN>" \
+  --org "<ORG_NAME>" \
+  --repo "<REPO_NAME>" \
+  --pr <PR_NUMBER> \
+  --repo-name "<REPO_KEY>"
+```
+
+### CLI Arguments:
+
+- `--token`: Org-level read token for GitHub REST API calls (requires permission to read team memberships).
+- `--org`: The GitHub organization name.
+- `--repo`: The GitHub repository name.
+- `--pr`: The PR number to validate.
+- `--repo-name`: A lookup key mapping to the rules configuration file (e.g. `python-sdk` maps to `org-tools/governance/rules/python-sdk-rules.yml`).
+
+---
+
+## Running Unit Tests
+
+The test suite mock-patches the GitHub API and local git files to allow fast, isolated test runs:
+
+```bash
+# Run pr_validator tests
+python3 org-tools/governance/tests/test_pr_validator.py
+
+# Run config parser and validator tests
+python3 org-tools/governance/tests/test_governance_config_parser.py
+```