DOLPHIN/prod/docs/BRANCHING_CONVENTION.md

# 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.
feat(config/scripts): GREEN config wiring + S6 recompute tooling prod/configs/green.yml: - asset_bucket_ban_set: [4] (B4 banned at selector level) - s6_size_table: inline bootstrap multipliers (B0→0.4, B1→0.3, B3→2.0, B5→0.5, B6→1.5) matching CRITICAL_ASSET_PICKING S6 scenario - esof_sizing_table: FAV→1.2, MILD_POS→0.6, UNKNOWN→0.25, MILD_NEG→0.0, UNFAV→0.0 - use_int_leverage: true (1x fixed pending winrate analysis) - s6_table_path: pointer to generated YAML (recompute updates this) BLUE (blue.yml) carries none of these keys → BLUE math unchanged. prod/configs/green_s6_table.yml: bootstrap stub with frontmatter (generated_at, source_branch, n_trades). Regenerated by recompute script. prod/scripts/recompute_s6_coefficients.py: Queries trade_events, maps assets to KMeans buckets, derives per-bucket sizing mults. Variance guard: >20% net-PnL move flags bucket in dolphin.s6_recompute_log for manual review before promote. prod/s6_recompute_flow.py: Prefect flow wrapping the recompute script. Cadence via S6_RECOMPUTE_INTERVAL_DAYS env (default 30). Kill-switch: S6_RECOMPUTE_DISABLED=1. prod/scripts/analyze_leverage_winrate.py: Read-only walk of CH trade_events; bins trades by leverage_raw, emits per-bin WR/net-PnL/avg-MAE. Output informs the int-leverage rounding rule choice (Option 1 round-half-up vs Option 2 banker's round vs stay-at-1x). Does not auto-apply a rule change. Plan refs: Tasks 3, 8, 10. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> 2026-04-22 06:08:08 +02:00			`# 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.