# GitHub Branch Protection Baseline

This guide defines the minimum branch protection policy for `main` to enforce CI/CD quality gates.

## Target Branch

- `main`

## Required Pull Request Rules

Enable these options in GitHub branch protection for `main`:

1. Require a pull request before merging
2. Require approvals: at least `1`
3. Dismiss stale pull request approvals when new commits are pushed
4. Require conversation resolution before merging
5. Require status checks to pass before merging
6. Require branches to be up to date before merging
7. Include administrators (recommended)

## Required Status Checks

Mark the following checks as **required**:

1. `Quality Gates`
2. `Security Audit`
3. `Agent Rules Check`
4. `Backend Tests`
5. `Frontend Build`
6. `Python Package Check`
7. `CodeQL Analyze (javascript-typescript)`
8. `CodeQL Analyze (python)`

Notes:

- `Backend Tests` is an aggregate gate job. It fails if any backend shard fails.
- Avoid selecting shard job names directly (`Backend Tests (Shard x/3)`) as required checks.
- `Dependency Review` only runs on pull requests; keep it enabled in CI but do not set it as a required check for push events.

## Optional But Recommended Rules

1. Require signed commits
2. Restrict who can push to matching branches
3. Require linear history
4. Do not allow force pushes
5. Do not allow deletions

## Release Workflow Permissions

For release-related workflows (`release-preflight.yml`, `release.yml`), configure repository secrets:

1. `PYPI_API_TOKEN` (only required when `publish_pypi=true`)

## Operating Procedure

1. All feature branches open PRs to `main`.
2. CI (`CI` workflow) must pass required checks.
3. Run local gate before opening PR: `npm run check:quality-gates`.
4. Run `Release Preflight` manually before planned release.
5. Run `Release` with `dry_run=true` first.
6. Run `Release` with `dry_run=false` after dry run passes.
