branch-protection/BRANCH_PROTECTION_POLICY.md

# Branch Protection Policy for Tier-1 Canonical Systems

**Version**: 1.0
**Date**: 2025-01-27
**Status**: Recommended Policy

---

## Overview

This document defines the recommended branch protection policies for Tier-1 canonical system repositories to enforce the constitutional governance framework.

---

## Applicable Repositories

This policy applies to:

- `dbis_core`
- `iccc_monorepo`
- `smom-dbis-138`
- `smoa`

---

## Protection Levels

### Level 1: Standard Protection (All Branches)

Applies to all branches:

- [ ] **Require Pull Request Reviews**
  - Required reviewers: 1
  - Dismiss stale reviews: Yes
  - Require review from code owners: Yes (if CODEOWNERS exists)

- [ ] **Require Status Checks**
  - CI/CD checks must pass
  - Required status checks: [Configure based on CI/CD setup]

- [ ] **Restrict Push Access**
  - Allow force pushes: No
  - Allow deletions: No (for main/master only)

### Level 2: Enhanced Protection (Main/Master Branch)

Additional protections for main/master branch:

- [ ] **Require Linear History**
  - Allow squash merging: Yes
  - Allow merge commits: No (preferred) or Restricted
  - Allow rebase merging: Yes

- [ ] **Require Branch to be Up to Date**
  - Require branches to be up to date before merging: Yes

- [ ] **Lock Branch**
  - Lock branch: No (only for emergency maintenance)

---

## Governance-Specific Protections

### Tier-1 Change Detection

For changes that require formal proposals:

- [ ] **Proposal Reference Check** (if automated)
  - Verify proposal ID in commit message or PR description
  - Format: `PROPOSAL-YYYY-MMDD-NNN` or `proposal: PROPOSAL-YYYY-MMDD-NNN`

- [ ] **Constitutional Change Detection**
  - If CANONICAL_CONSTITUTION.md modified, require:
    - Proposal ID in PR
    - Amendment log update
    - Version increment

### Recognition Verification (Manual Process)

- **Reviewer Guidelines**: Reviewers should verify:
  - [ ] Proposal exists in `proposals/` directory
  - [ ] Proposal shows recognition from all Tier-1 systems
  - [ ] Change aligns with approved proposal
  - [ ] Documentation updates included

---

## Exception Process

### Emergency Changes

For critical security/stability issues:

1. **Emergency Declaration**
   - Create issue/note declaring emergency
   - Justify emergency status
   - Tag with `emergency` label

2. **Expedited Review**
   - Reduced review requirements (still require review)
   - Fast-track approval process
   - Document emergency in commit/PR

3. **Post-Implementation**
   - Submit formal proposal retrospectively
   - Document emergency in proposal
   - Update tracking

### Bypass Procedure

If branch protection must be temporarily bypassed:

1. **Justification Required**
   - Document reason for bypass
   - Get approval from repository maintainers
   - Create issue documenting bypass

2. **Post-Bypass Review**
   - Review changes made
   - Verify compliance
   - Document in issue

3. **Prevent Future Need**
   - Identify process improvements
   - Update procedures if needed

---

## Implementation Steps

### Step 1: Configure Basic Protection

1. Navigate to repository Settings → Branches
2. Add branch protection rule for `main` (or `master`)
3. Configure basic settings:
   - Require pull request reviews
   - Require status checks
   - Restrict force pushes

### Step 2: Configure Enhanced Protection

1. Add linear history requirement
2. Require branch up to date
3. Configure merge options

### Step 3: Document Policy

1. Link to this policy in repository
2. Update README with protection information
3. Document exception process

### Step 4: Train Team

1. Share policy with repository maintainers
2. Explain protection rules
3. Document exception process

---

## Platform-Specific Notes

### GitHub

Settings location: `Settings → Branches → Branch protection rules`

Key settings:
- Require pull request reviews before merging
- Require status checks to pass before merging
- Require branches to be up to date before merging
- Do not allow force pushes
- Do not allow deletions

### GitLab

Settings location: `Settings → Repository → Protected branches`

Key settings:
- Allowed to merge: Maintainers (or appropriate role)
- Allowed to push: No one
- Allowed to force push: No

### Other Platforms

Adapt settings based on platform capabilities while maintaining core principles:
- Require reviews
- Prevent force pushes
- Require status checks

---

## Monitoring and Enforcement

### Regular Review

- [ ] Quarterly review of protection settings
- [ ] Verify rules still appropriate
- [ ] Check for bypasses/exceptions
- [ ] Review exception frequency

### Compliance

- [ ] Ensure all Tier-1 repos have protection
- [ ] Verify protection rules active
- [ ] Document any exceptions
- [ ] Track bypass requests

---

## Recommended Branch Strategy

### Main/Master Branch

- **Purpose**: Production-ready code
- **Protection**: Full Level 2 protection
- **Merges**: Via pull requests only
- **Requirements**: All checks pass, reviews approved

### Development/Feature Branches

- **Purpose**: Active development
- **Protection**: Level 1 protection (if applicable)
- **Merges**: To main/master via PR
- **Requirements**: Standard review process

### Release Branches

- **Purpose**: Release preparation
- **Protection**: Level 2 protection
- **Merges**: From main, to main only
- **Requirements**: Release process compliance

---

## Documentation Requirements

Each repository should document:

1. **Branch Protection Status**
   - Which branches are protected
   - Protection level
   - How to request exceptions

2. **Review Process**
   - Who can review
   - Review requirements
   - Approval process

3. **Exception Process**
   - How to request exceptions
   - Emergency procedures
   - Bypass documentation

---

## Reference Documents

- **[CANONICAL_CONSTITUTION.md](../CANONICAL_CONSTITUTION.md)** - Constitutional framework
- **[CANONICAL_CHANGE_CONTROL_PROCESS.md](../CANONICAL_CHANGE_CONTROL_PROCESS.md)** - Change control
- **[CANONICAL_GOVERNANCE_GUIDE.md](../CANONICAL_GOVERNANCE_GUIDE.md)** - Governance guide

---

**Policy Version**: 1.0
**Last Updated**: 2025-01-27
**Review Date**: [Quarterly review recommended]