# Branching Strategy

This repository uses a simple trunk-based model with short-lived branches and
`main` as the deploy branch.

For delivery workflow, see [workflow.md](workflow.md). For PR expectations, see
[CONVENTIONS.md](CONVENTIONS.md#git-and-prs).

## Default Model

```mermaid
gitGraph
    commit id: "main"
    branch docs-change
    checkout docs-change
    commit id: "work"
    commit id: "validate"
    checkout main
    merge docs-change
    commit id: "deploy"
```

## Branch Types

| Type | Pattern | Purpose |
| --- | --- | --- |
| Feature | `feature/<short-description>` | New user-facing or system capability. |
| Bug fix | `fix/<short-description>` | Defect correction. |
| Refactor | `refactor/<short-description>` | Behavior-preserving structural work. |
| Documentation | `docs/<short-description>` | Documentation-only changes. |
| Chore | `chore/<short-description>` | Tooling or maintenance work. |
| AI-assisted local work | `codex/<short-description>` | Short-lived Codex branch when branch creation is useful. |
| Hotfix | `hotfix/<short-description>` | Urgent production correction. |

## Main Branch

`main` should remain deployable.

Minimum expectations:

- required checks pass;
- risky migrations and config changes are documented;
- production-impacting changes include validation evidence;
- direct pushes are limited to maintainers or automation.

## Feature Branches

- Keep scope focused.
- Rebase or merge from `main` according to reviewer preference.
- Delete branches after merge.
- Avoid stacking unrelated changes.
- Do not include generated build output or handoff artifacts.

## Commit Messages

Use short imperative subjects that describe the outcome.

Examples:

- `Fix team profile auth recovery`
- `Refine admin risk workspace`
- `Document engineering workflow`

Use a longer body when context, migration notes, or validation evidence is
important for future archaeology.

## Hotfixes

Hotfixes should restore production safely:

1. Branch from the deployed commit or current `main`.
2. Apply the smallest safe fix.
3. Validate the failing path.
4. Deploy.
5. Merge back to `main`.
6. Add follow-up cleanup or tests when the hotfix intentionally stayed narrow.