From 7e8dcd3e5a965272dfe3cb51063f9f41a4d92e49 Mon Sep 17 00:00:00 2001
From: xj <gh-xj@users.noreply.github.com>
Date: Sun, 1 Mar 2026 18:20:32 -0800
Subject: [PATCH] docs(governance): align PR gate policy with hardened
 protection

---
 docs/operations/required-check-mapping.md | 19 +++++++++++++------
 docs/pr-workflow.md                       | 14 +++++++++-----
 2 files changed, 22 insertions(+), 11 deletions(-)

diff --git a/docs/operations/required-check-mapping.md b/docs/operations/required-check-mapping.md
index fe4aba9a7..ccf6b6245 100644
--- a/docs/operations/required-check-mapping.md
+++ b/docs/operations/required-check-mapping.md
@@ -7,9 +7,14 @@ This document maps merge-critical workflows to expected check names.
 | Required check name | Source workflow | Scope |
 | --- | --- | --- |
 | `CI Required Gate` | `.github/workflows/ci-run.yml` | core Rust/doc merge gate |
-| `Security Audit` | `.github/workflows/sec-audit.yml` | dependencies, secrets, governance |
-| `Feature Matrix Summary` | `.github/workflows/feature-matrix.yml` | feature-combination compile matrix |
-| `Workflow Sanity` | `.github/workflows/workflow-sanity.yml` | workflow syntax and lint |
+| `Security Required Gate` | `.github/workflows/sec-audit.yml` | aggregated security merge gate |
+
+Supplemental monitors (non-blocking unless added to branch protection contexts):
+
+- `CI Change Audit` (`.github/workflows/ci-change-audit.yml`)
+- `CodeQL Analysis` (`.github/workflows/sec-codeql.yml`)
+- `Workflow Sanity` (`.github/workflows/workflow-sanity.yml`)
+- `Feature Matrix Summary` (`.github/workflows/feature-matrix.yml`)
 
 Feature matrix lane check names (informational, non-required):
 
@@ -28,12 +33,14 @@ Feature matrix lane check names (informational, non-required):
 
 ## Verification Procedure
 
-1. Resolve latest workflow run IDs:
+1. Check active branch protection required contexts:
+   - `gh api repos/zeroclaw-labs/zeroclaw/branches/main/protection --jq '.required_status_checks.contexts[]'`
+2. Resolve latest workflow run IDs:
    - `gh run list --repo zeroclaw-labs/zeroclaw --workflow feature-matrix.yml --limit 1`
    - `gh run list --repo zeroclaw-labs/zeroclaw --workflow ci-run.yml --limit 1`
-2. Enumerate check/job names and compare to this mapping:
+3. Enumerate check/job names and compare to this mapping:
    - `gh run view <run_id> --repo zeroclaw-labs/zeroclaw --json jobs --jq '.jobs[].name'`
-3. If any merge-critical check name changed, update this file before changing branch protection policy.
+4. If any merge-critical check name changed, update this file before changing branch protection policy.
 
 ## Notes
 
diff --git a/docs/pr-workflow.md b/docs/pr-workflow.md
index 30a230e8c..eab401d9a 100644
--- a/docs/pr-workflow.md
+++ b/docs/pr-workflow.md
@@ -96,12 +96,16 @@ Automation assists with triage and guardrails, but final merge accountability re
 Maintain these branch protection rules on `dev` and `main`:
 
 - Require status checks before merge.
-- Require check `CI Required Gate`.
+- Require checks `CI Required Gate` and `Security Required Gate`.
+- Consider also requiring `CI Change Audit` and `CodeQL Analysis` for stricter CI/CD governance.
 - Require pull request reviews before merge.
+- Require at least 1 approving review.
+- Require approval after the most recent push.
 - Require CODEOWNERS review for protected paths.
-- For CI/CD-related paths (`.github/workflows/**`, `.github/codeql/**`, `.github/connectivity/**`, `.github/release/**`, `.github/security/**`, `.github/actionlint.yaml`, `.github/dependabot.yml`, `scripts/ci/**`, and CI governance docs), require an explicit approving review from `@chumyin` via `CI Required Gate`.
-- Keep branch/ruleset bypass limited to org owners.
-- Dismiss stale approvals when new commits are pushed.
+- For CI/CD-related paths (`.github/workflows/**`, `.github/codeql/**`, `.github/connectivity/**`, `.github/release/**`, `.github/security/**`, `.github/actionlint.yaml`, `.github/dependabot.yml`, `scripts/ci/**`, and CI governance docs), require CODEOWNERS review with `@chumyin` ownership.
+- Keep bypass allowances empty by default (use time-boxed break-glass only when absolutely required).
+- Enforce branch protection for admins.
+- Require conversation resolution before merge.
 - Restrict force-push on protected branches.
 - Route normal contributor PRs to `main` by default (`dev` is optional for dedicated integration batching).
 - Allow direct merges to `main` once required checks and review policy pass.
@@ -123,7 +127,7 @@ Maintain these branch protection rules on `dev` and `main`:
 
 ### 4.2 Step B: Validation
 
-- `CI Required Gate` is the merge gate.
+- `CI Required Gate` and `Security Required Gate` are the merge gates.
 - Docs-only PRs use fast-path and skip heavy Rust jobs.
 - Non-doc PRs must pass lint, tests, and release build smoke check.
 - Rust-impacting PRs use the same required gate set as `dev`/`main` pushes (no PR build-only shortcut).