# Git Flow Governance

## Scope

Governance rules for branch protections, PR gates, branch naming, and merge discipline.

## Branch Protection

Protected branches:

- `main`
- `staging`

Apply protections using:

- Gitea UI settings
- or automation script: `.gitea/scripts/configure-branch-protection.sh`

Minimum policy:

- no direct pushes
- PR merge required
- required status checks
- at least one reviewer approval

## PR Gates

Required checks are implemented in `.gitea/workflows/ci.yml`:

- Governance Checks
- Lint Typecheck Unit E2E

## Branch Naming and TODO Scope

Allowed branch prefixes:

- `todo/`
- `refactor/`
- `code/`

Validation script:

- `.gitea/scripts/check-branch-name.sh`

Rule:

- one primary TODO item per delivery branch

PR TODO reference enforcement:

- template: `.gitea/PULL_REQUEST_TEMPLATE.md`
- CI check: `.gitea/scripts/check-pr-todo-reference.sh`

## Branch Lifecycle

1. Create short-lived branch from latest integration tip.
2. Implement one primary scope.
3. Open PR and pass required checks.
4. Merge into `dev`.
5. Promote `dev -> staging -> main`.

## Commit and Tag Policy

- Conventional commits required (`CONTRIBUTING.md`)
- release tags: `vX.Y.Z`
- changelog generated from commit history