[INFRA] Contributor Guardrail Automation

[scottchronicity]

Context

Open source repositories require specific GitHub settings — Branch Protection on main, required code reviews, community health files (CODE_OF_CONDUCT, CONTRIBUTING, SECURITY) — that are easy to misconfigure and hard to audit manually. We need a script or workflow that verifies these guardrails are in place and alerts maintainers when they drift from the expected state.

This automates the 'repository hygiene' checklist that every new maintainer has to verify manually.

Architecturally Significant Requirements (ASRs)

Interface (Contract):

• Script: scripts/verify-repo-guardrails.sh that uses the GitHub CLI (gh) to check all guardrail conditions.
• GitHub Actions workflow: .github/workflows/guardrail-audit.yml running on a weekly cron schedule.
• Exit codes: 0 = all guardrails passing; 1 = one or more guardrails failing (CI-safe).
• Report output: human-readable checklist printed to stdout with [PASS]/[FAIL] per check.

Guardrails to Verify:

1. Branch Protection on main: enabled, requires PR before merging.
2. Required approvals: at least 1 approval required on all PRs to main.
3. Status checks required: CI must pass before merge.
4. CODE_OF_CONDUCT.md present at repository root or .github/.
5. CONTRIBUTING.md present at repository root.
6. SECURITY.md present at repository root or .github/.
7. Issue templates: at least one issue template in .github/ISSUE_TEMPLATE/.
8. PR template: .github/pull_request_template.md exists.

Implementation (Internal Logic):

• Branch protection checks: gh api repos/{owner}/{repo}/branches/main/protection and parse JSON response.
• Community health check: gh api repos/{owner}/{repo}/community/profile and verify files object.
• Cron schedule: run weekly on Monday 09:00 UTC; post a GitHub Issue if any check fails.
• make verify-guardrails target at the repo root for local maintainer use.

Architectural Constraints

• Must use the GitHub CLI (gh) — no third-party Python libraries for GitHub API calls.
• Must not require admin tokens in CI — use OIDC or the default GITHUB_TOKEN with repository scope.
• The script must be runnable locally by any maintainer with gh auth login.
• All checks must be idempotent — running the script twice has no side effects.
• Must work with GNU bash 3.2+ (macOS ships an old version).

Acceptance Criteria

Feature: Contributor Guardrail Automation

  Scenario: All guardrails passing
    Given all branch protection rules and community files are in place
    When verify-repo-guardrails.sh runs
    Then all checks show [PASS]
    And the script exits with code 0

  Scenario: Branch protection disabled — alert raised
    Given branch protection on main is disabled
    When verify-repo-guardrails.sh runs
    Then the branch protection check shows [FAIL]
    And the script exits with code 1

  Scenario: Weekly cron creates GitHub Issue on failure
    Given the guardrail audit workflow runs on its weekly schedule
    And one or more checks fail
    When the workflow completes
    Then a GitHub Issue is created titled "[Guardrail Audit] <date> — N checks failing"
    And the issue body lists the failing checks with remediation steps

  Scenario: Required approvals check passes
    Given branch protection requires at least 1 approval
    When verify-repo-guardrails.sh checks the approval requirement
    Then the required-approvals check shows [PASS]

Definition of Done

• scripts/verify-repo-guardrails.sh covering all 8 guardrail checks listed above.
• .github/workflows/guardrail-audit.yml running weekly cron with GitHub Issue creation on failure.
• make verify-guardrails target added to the root Makefile.
• All community health files verified present and linked in the GitHub repository settings.
• Documentation in CONTRIBUTING.md explaining the guardrail checks and how to fix failures.