prepare repo

BRANCHING.md

@@ -0,0 +1,105 @@
+# Branching Strategy
+
+This repository uses three long-lived branches and short-lived task branches.
+
+## Long-Lived Branches
+
+- `main`
+  - Production release branch
+  - Protected
+- `staging`
+  - Pre-production verification branch
+  - Protected
+- `dev`
+  - Integration branch for feature delivery
+  - Default merge target for task branches
+
+## Promotion Flow
+
+1. Task branches merge into `dev`.
+2. `dev` is validated by required checks.
+3. `dev` is promoted to `staging`.
+4. After staging validation, `staging` is promoted to `main`.
+
+## Required Checks Before Promotion
+
+Minimum gates:
+
+- `bun run lint`
+- `bun run typecheck`
+- `bun run test`
+- `bun run test:e2e --list` (or full e2e when infrastructure is available)
+
+Recommended for release candidate promotions:
+
+- `bun run test:e2e`
+- Build and smoke test Docker images for `web` and `admin`
+
+## Short-Lived Branch Types
+
+### Delivery Branches
+
+Use one dedicated branch per TODO item.
+
+Pattern:
+
+- `todo/<mvp>-<area>-<slug>`
+
+Examples:
+
+- `todo/mvp0-rbac-domain-model`
+- `todo/mvp1-media-enrichment-form`
+- `todo/mvp1-public-navigation-render`
+
+Rules:
+
+- One TODO item per branch.
+- One PR per branch.
+- PR description references exact TODO line text.
+
+### Refactor Branches
+
+For structural improvements not tied to one TODO task.
+
+Pattern:
+
+- `refactor/<scope>-<slug>`
+
+Examples:
+
+- `refactor/db-service-layer`
+- `refactor/admin-routing-structure`
+
+### Code Partition Branches
+
+For exploratory or larger code partitions outside immediate roadmap tasks.
+
+Pattern:
+
+- `code/<domain>-<slug>`
+
+Examples:
+
+- `code/commissions-kanban-poc`
+- `code/media-refinement-module`
+
+## Protection Rules (Gitea)
+
+Apply in repository settings:
+
+- Protect `main` and `staging` from direct push.
+- Require PR merge only.
+- Require status checks to pass.
+- Require at least one review approval.
+- Require branch up-to-date before merge.
+
+Optional:
+
+- Protect `dev` from direct push if team size/process requires stricter control.
+
+## Commit Signing Notes
+
+If commit signing is enabled with GPG, interactive signing prompts can fail in non-interactive contexts.
+
+- Local commits: verify GPG agent/session is available.
+- CI commits (if ever needed): use bot keys or skip signed commits for automation.