feat: enforce branch protection via .github/branch-protection.main.json (#167)

Closes #95

Implement automated, auditable branch protection enforcement for the `main`
branch by introducing a committed JSON source of truth, apply and verify
scripts, offline regression tests, and a post-merge workflow that
auto-applies the ruleset on changes.

Changes:
- Add .github/branch-protection.main.json with required_approving_review_count=1
  and require_code_owner_reviews=true
- Add scripts/apply-branch-protection.sh (PUT ruleset to GitHub API)
- Add scripts/verify-branch-protection.sh (GET and diff against JSON)
- Add scripts/verify-context-names.sh (validate all contexts map to real jobs)
- Add tests/branch-protection.test.sh (offline shim-based test suite)
- Add .github/workflows/apply-branch-protection.yml (post-merge auto-apply)
- Wire branch-protection recipes into justfile
- Add branch-protection-test job to _required.yml CI
- Update pixi.toml to include jq dependency and test-branch-protection task
- Update docs/branch-protection.md with enforcement procedure
- Update CLAUDE.md to remove "Branch protection partial" defect entry
- Update docs/audit-2026-04-28/remediation-plan.md (if exists)

Verification:
- All 15 required-status-check contexts map to real workflow job names
- JSON validates with jq
- Offline test suite passes (clean, drift, missing-token, malformed-JSON cases)
- Scripts pass shellcheck

References: Closes #95. Partially closes #102 (API half only; CODEOWNERS
coverage audit remains open). Refs #81 (audit remediation).

Signed-off-by: mvillmow <4211002+mvillmow@users.noreply.github.com>
Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>

Author: mvillmow

.github/branch-protection.main.json

@@ -0,0 +1,37 @@
+{
+  "required_status_checks": {
+    "strict": true,
+    "contexts": [
+      "lint",
+      "Lint Shell Scripts",
+      "TypeScript Type Check",
+      "forbid-suppressions",
+      "unit-tests",
+      "integration-tests",
+      "schema-validation",
+      "markdownlint",
+      "pixi-check",
+      "justfile-check",
+      "symlink-check",
+      "build",
+      "security/secrets-scan",
+      "security/dependency-scan",
+      "branch-protection-test"
+    ]
+  },
+  "enforce_admins": true,
+  "required_pull_request_reviews": {
+    "dismiss_stale_reviews": true,
+    "require_code_owner_reviews": true,
+    "required_approving_review_count": 1,
+    "require_last_push_approval": false
+  },
+  "restrictions": null,
+  "required_linear_history": true,
+  "allow_force_pushes": false,
+  "allow_deletions": false,
+  "block_creations": false,
+  "required_conversation_resolution": true,
+  "lock_branch": false,
+  "allow_fork_syncing": false
+}

.github/workflows/_required.yml

@@ -405,3 +405,20 @@ jobs:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
       - name: Run symlink check
         run: bash scripts/check-symlinks.sh
+
+  branch-protection-test:
+    name: branch-protection-test
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
+      - name: Setup pixi
+        uses: prefix-dev/setup-pixi@5185adfbffb4bd703da3010310260805d89ebb11  # v0.9.6
+        with:
+          pixi-version: v0.67.2
+      - name: Validate ruleset JSON
+        run: pixi run jq . .github/branch-protection.main.json >/dev/null
+      - name: Verify every context maps to a real workflow job name
+        run: bash scripts/verify-context-names.sh
+      - name: Run offline branch-protection verifier test
+        run: pixi run test-branch-protection

.github/workflows/apply-branch-protection.yml

@@ -0,0 +1,40 @@
+name: Apply Branch Protection
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - '.github/branch-protection.main.json'
+      - 'scripts/apply-branch-protection.sh'
+      - 'scripts/verify-branch-protection.sh'
+      - '.github/workflows/apply-branch-protection.yml'
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+concurrency:
+  group: apply-branch-protection-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  apply:
+    name: apply-branch-protection
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
+      - name: Setup pixi
+        uses: prefix-dev/setup-pixi@5185adfbffb4bd703da3010310260805d89ebb11  # v0.9.6
+        with:
+          pixi-version: v0.67.2
+      - name: Validate JSON
+        run: pixi run jq . .github/branch-protection.main.json >/dev/null
+      - name: Apply ruleset
+        env:
+          GITHUB_TOKEN: ${{ secrets.BRANCH_PROTECTION_PAT }}
+        run: bash scripts/apply-branch-protection.sh
+      - name: Verify ruleset
+        env:
+          GITHUB_TOKEN: ${{ secrets.BRANCH_PROTECTION_PAT }}
+        run: bash scripts/verify-branch-protection.sh

CLAUDE.md

@@ -107,11 +107,14 @@ before assuming the defect is unfixed.
   Flip this entry to "resolved" only after #5 closes.
 - **GitHub Actions security gaps.** Gitleaks runs with `--exit-code 0` (#86);
   treat absence of a Gitleaks failure as inconclusive. (Trivy gate restored — #85 closed.)
-- **Branch protection partial.** PRs require zero reviews (#95); CODEOWNERS
-  enforcement is now applied via `scripts/branch-protection-apply.sh` (#102),
-  which preserves all sibling fields on the protection endpoint (status checks,
-  approving review count, push restrictions). See `docs/branch-protection.md`
-  for the target state and procedure.
+- **Branch protection is enforced** via `.github/branch-protection.main.json`.
+  The `.github/workflows/apply-branch-protection.yml` workflow re-applies the
+  ruleset on every change to that file using the `BRANCH_PROTECTION_PAT`
+  secret. `just verify-branch-protection` (read-only) detects drift;
+  `tests/branch-protection.test.sh` runs offline in CI as the
+  `branch-protection-test` required check. (Closes #95. Partially closes
+  #102 — `require_code_owner_reviews=true` flips here; the CODEOWNERS
+  coverage audit tracked in #102 remains open.)
 
 Agents must not silently work around these defects; instead, link the
 relevant issue from any PR that touches the affected code.

docs/branch-protection.md

@@ -20,9 +20,9 @@ provisioning. Branch protection is the last guardrail.
 | Restrict deletions | **on** | — |
 | Restrict pushes (no force-pushes, no direct commits) | **on** | — |
 | Require pull request before merging | **on** | — |
-| Required approving review count | **1** (minimum) | #95 |
+| Required approving review count | **1** (minimum) | #95 (enforced) |
 | Dismiss stale approvals on new commits | **on** | — |
-| Require review from code owners | **on** | #102 (applied via scripts/branch-protection-apply.sh) |
+| Require review from code owners | **on** | #102 (enforced via API; CODEOWNERS coverage audit remains open) |
 | Require status checks to pass | **on** | — |
 | Required status checks | see below | #94 |
 | Require branches to be up to date before merging | **on** | — |
@@ -31,52 +31,40 @@ provisioning. Branch protection is the last guardrail.
 
 ### Required status checks
 
-The following CI checks (from `.github/workflows/_required.yml`,
-`ci.yml`, `cross-repo-dispatch.yml`, and `promote.yml`) are the
-authoritative required set:
+The following CI checks (from `.github/workflows/_required.yml` and `ci.yml`)
+are the authoritative required set. Names match the workflow job `name:` field,
+which is what GitHub uses for protection contexts:
 
-- `lint-scripts` (CI / shellcheck)
-- `typecheck` (CI / `tsc --noEmit`)
+- `lint` (shellcheck + yamllint + mypy)
+- `Lint Shell Scripts` (ci.yml)
+- `TypeScript Type Check` (ci.yml)
 - `forbid-suppressions` (no-silent-failures guard)
-- `unit-tests` (YAML schema validation; to be replaced by real tests — #88)
-- `integration-tests` (cross-config reference check; to be expanded — #89)
-- `markdownlint` (docs lint)
-- `security/npm-audit` (npm audit for known CVEs — #23)
-- `security/secrets-scan` (Gitleaks SARIF upload + PR gating — #23, #86)
-- `CodeQL / javascript-typescript` (SAST for TypeScript — #23)
-
-A required status check that does not actually run on a PR will block
-merges; whenever a check is renamed, this list must be updated in the
-same PR.
-
-## Why we are not enforcing this today
-
-The defects in #95 (zero required approvals) and #102 (CODEOWNERS not
-enforced in branch protection) are tracked separately. This document
-exists so the next maintainer with admin access can apply the policy
-in one pass without re-deriving it.
-
-## Procedure to apply
-
-The repo-level apply is scripted and idempotent:
-
-1. `gh auth status` — confirm authentication has admin scope on the repo.
-2. `just branch-protection-dry-run` — prints the merged payload **without
-   PUT-ing it**. Review that `required_status_checks.contexts` lists the
-   expected checks from #94, `required_approving_review_count` matches #95,
-   and `restrictions` (if non-null) lists the expected users/teams/apps.
-3. `just branch-protection-apply` — performs read-modify-write: every sibling
-   field on `branches/main/protection` is round-tripped verbatim; only
-   `require_code_owner_reviews` is mutated to `true`. Safe to re-run.
-4. Verify:
-   `gh api repos/HomericIntelligence/ProjectProteus/branches/main/protection --jq '.required_pull_request_reviews.require_code_owner_reviews'`
-   prints `true`.
-5. Close #102 once step 4 returns `true`.
-
-The script uses `gh api -i` to parse HTTP status lines from stdout (a stable
-contract across `gh` versions), so 404 (no existing protection) is handled by
-creating minimal protection, while 401/403 (insufficient scope) fail fast with
-an explicit error.
+- `unit-tests` (placeholder; to be replaced — #88)
+- `integration-tests` (placeholder; to be expanded — #89)
+- `schema-validation` (YAML pipeline config validation)
+- `markdownlint` (documentation lint)
+- `pixi-check` (pixi lock file consistency)
+- `justfile-check` (justfile validation)
+- `symlink-check` (verify all symlinks resolve)
+- `build` (dagger build test)
+- `security/secrets-scan` (gitleaks)
+- `security/dependency-scan` (dependency audit)
+- `branch-protection-test` (offline branch protection verification)
+
+## Enforcement
+
+The ruleset above is the **literal** body of `.github/branch-protection.main.json`.
+It is applied automatically by `.github/workflows/apply-branch-protection.yml`
+on every push to `main` that modifies the JSON file, using the admin-scoped
+`BRANCH_PROTECTION_PAT` repository secret.
+
+Manual operations (admin token required):
+
+- Apply / re-apply: `GITHUB_TOKEN=<admin-pat> just apply-branch-protection`
+- Detect drift:    `GITHUB_TOKEN=<admin-pat> just verify-branch-protection`
+
+Offline regression coverage runs on every PR via `_required.yml` →
+`branch-protection-test`; no token is required.
 
 ## See also
 

justfile

@@ -89,8 +89,20 @@ lint-verify-92:
 test-plan-sync:
 	bash tests/remediation-plan-sync.test.sh
 
-# Run lint + validate together
-check: lint validate test-plan-sync
+# Apply branch protection ruleset to main (requires admin GITHUB_TOKEN) — Refs #95, #102.
+apply-branch-protection:
+    GITHUB_TOKEN={{GITHUB_TOKEN}} ./scripts/apply-branch-protection.sh
+
+# Verify live branch protection matches .github/branch-protection.main.json — Refs #95.
+verify-branch-protection:
+    GITHUB_TOKEN={{GITHUB_TOKEN}} ./scripts/verify-branch-protection.sh
+
+# Offline shim test — runs in CI without secrets.
+test-branch-protection:
+    bash tests/branch-protection.test.sh
+
+# Run lint + validate + plan-sync + branch-protection test together
+check: lint validate test-plan-sync test-branch-protection
 
 # Run the full local test suite (shell integration tests + config validation)
 test-all: