# DOLPHIN Branching Convention

Established 2026-04-21. The DOLPHIN repo (Gitea: `100.119.158.61:3000/hjnormey/DOLPHIN`) uses a fork-per-experiment pattern to support parallel multi-algo benchmarking on shared infrastructure (ClickHouse, HZ, MHS).

## Branches

| Branch         | Role                                                            |
|----------------|-----------------------------------------------------------------|
| `master`       | Production baseline. Only merged-and-validated work lands here. |
| `exp/<slug>`   | Experiment branches. Named `exp/<feature>-<YYYY-MM-DD>`.        |

Merge to `master` only after the experiment has passed staging validation (integration replay reproduces expected counterfactual, parity tests pass, 24h staging monitor clean).

## Active / recent experiments

- `exp/green-s6-esof-aem-shadow-2026-04-21` — S6 asset picker, EsoF regime gate (NEUTRAL→UNKNOWN), AEM shadow completeness, integer-leverage gate.

## Infrastructure suffixing (avoid collisions on shared CH / HZ / MHS)

When an experiment writes runtime state to shared infra, **suffix the table or map name with the branch slug** so parallel experiments don't stomp each other.

Examples:
- ClickHouse tables: `adaptive_exit_shadow_exp_green_s6`, `trade_events_exp_green_s6`
- HZ maps: `DOLPHIN_PNL_GREEN_S6`, `DOLPHIN_FEATURES_EXP_GREEN_S6`
- Supervisord program names: `dolphin-green-exp-s6`

The suffix slug is the part of the branch name after `exp/`, with `/` → `_` and `-` → `_` as needed.

## Workflow

1. Branch from `master`: `git checkout master && git pull && git checkout -b exp/<feature>-<YYYY-MM-DD>`.
2. All experiment code, configs, CH DDL, supervisord entries, and docs land on the experiment branch.
3. Staging deploy runs on the experiment branch only.
4. Validation + monitor period.
5. If the experiment is kept, open a merge request to `master`. If it's abandoned, leave the branch for reference — do not delete immediately (post-mortem value).

## Commit identity

Commits should use the operator's Gitea-bound identity (`hjnormey@gmail.com`). Agents making commits should pass identity per-command via `git -c user.email=... -c user.name=...` rather than mutating global config.