Merge pull request #13 from JohnCCarter/feature/mtf-behavior-research

MTF multi-leg labeling and behavior facit v3 (research)

Author: JohnCCarter

.gitignore

@@ -218,12 +218,17 @@ __marimo__/
 .streamlit/secrets.toml
 
 # --- Fibonacci-engine projekt-specifikt ---
+# Ephemeral markdown for `gh issue create` / `gh pr edit --body-file` (not project docs)
+.gh-*.md
 tmp/
 # Cachad marknadsdata och referensbilder versioneras inte.
 data/raw/
 data/screenshots/
 # Per-körning audit-mappar versioneras inte (artefakter, inte källa).
 # experiments/results/*.jsonl och experiments/label_review/ versioneras (default).
+# Timestamped per-run snapshots (not append-only ledgers):
+experiments/results/mtf_*.json
+experiments/results/*_compare_*T*.json
 experiments/runs/
 # Genererade human-review-paket (charts/sheets) är artefakter, inte källa.
 experiments/review/

.pre-commit-config.yaml

@@ -11,6 +11,11 @@ repos:
 
   - repo: local
     hooks:
+      - id: repo-bounds
+        name: repo bounds (anti-blob / module size)
+        entry: uv run python scripts/check_repo_bounds.py
+        language: system
+        pass_filenames: true
       - id: pytest
         name: pytest
         entry: uv run pytest -q

README.md

@@ -12,6 +12,7 @@ ZigZag-Fib. Den väljer swingar, ritar Fib automatiskt och förbättras iterativ
 > Premortem/reflektion är obligatoriskt: se `premortem/` och `REPO_POLICY.md` §11.
 > Spårmodell: se `docs/TRACKS.md` (Research / Validate / Promotion).
 > Backtest-roadmap: [`docs/FIB_BACKTEST_PLAN.md`](docs/FIB_BACKTEST_PLAN.md).
+> Bitfinex / Genesis validate: [`docs/GENESIS_BITFINEX_VALIDATE.md`](docs/GENESIS_BITFINEX_VALIDATE.md).
 > Arkiv (legacy/dubletter): [`archive/`](archive/README.md).
 
 ## Filosofi
@@ -126,6 +127,9 @@ leg än en ritning är det en signal att undersöka, inte automatiskt ett fel.
 
 ### Maskin-labeling (kandidater, inte facit)
 
+Två giltiga frågor (motor-swing vs synligt chartfönster) — se
+[`docs/MACHINE_LABELING.md`](docs/MACHINE_LABELING.md).
+
 `labeling/autolabel.py` kan generera **provisoriska** swing-kandidater
 (`source="machine"`) från motorns eget urval, så att du slipper börja från ett
 tomt chart. Tre hårda regler skyddar facit-integriteten:

REPO_POLICY.md

@@ -25,7 +25,7 @@ Allt nytt arbete ska följa indexet nedan. Fungerar något annorlunda i praktike
 | `tmp/` | Tillfälliga skript/artefakter | Valfritt (se §9) |
 
 Toppnivån ska bara innehålla: `README.md`, `REPO_POLICY.md`, `pyproject.toml`,
-`uv.lock`, `.gitignore`, och dessa mappar. **Inga stub-filer** som bara pekar
+`uv.lock`, `.gitignore`, `.pre-commit-config.yaml` (lokal hook-kedja), och dessa mappar. **Inga stub-filer** som bara pekar
 bort flyttat innehåll — uppdatera länkar till canonical path (t.ex. `docs/FIB_BACKTEST_PLAN.md`).
 Tillfälliga filer läggs i `tmp/`.
 
@@ -83,6 +83,51 @@ Varje modul ska ha ett tydligt ansvar. Inga “utils.py” utan kategori.
 | `experiment.py` | Standardrunner som loggar till `experiments/runs/` |
 | `core/logging_conf.py` | Loguru-setup |
 
+## 2B. Modulstorlek, ansvar och anti-blob (MÅSTE)
+
+Undvik **monolitiska moduler** (en fil som gör för många saker) och **blobs**
+(stora klumpiga filer utan tydlig struktur). En fil ska ha **en huvudorsak att ändras**.
+
+### Principer
+
+- **Ett ansvar per modul** — följ tabellen i §2; dela om en fil både CLI, domänlogik
+  och GUI i samma modul utan tydlig gräns.
+- **Inga generiska `utils.py`** — namnge efter domän (`store.py`, `stability.py`, …).
+- **Tunna entrypoints** — `experiment.py`, `runner.py`, `autolabel.py` ska orkestrera;
+  tung logik i paket undermappar.
+- **Data ≠ dokumentation** — rå metrics i `experiments/results/*.jsonl`; guider i `docs/`;
+  korta beslut i `premortem/reflections/`.
+
+### Storleksgränser (verkställs i pre-commit)
+
+| Mönster | Max rader | Max storlek | Kommentar |
+|---------|-----------|-------------|-----------|
+| `premortem/reflections/*.md` | 80 | 8 KiB | utom `INDEX.md`, `README.md` |
+| `src/fibengine/**/*.py` | 400 | 25 KiB | ny kod ska ligga under gränsen |
+| `tests/**/*.py` | 250 | 15 KiB | |
+| `docs/**/*.md` | 200 | 20 KiB | längre innehåll → flera docs-filer |
+| `scripts/*.py` | 120 | 8 KiB | |
+
+Kör lokalt: `uv run python scripts/check_repo_bounds.py`
+
+### Känd skuld (får inte växa)
+
+| Fil | Rader (ca) | Plan |
+|-----|------------|------|
+| `src/fibengine/labeling/tool.py` | ~595 | Dela workspace / plot / CLI — grandfather tills split |
+| `src/fibengine/labeling/behavior_facit.py` | ~530 | Dela I/O vs validate — grandfather tills split |
+| `scripts/behavior_facit.py` | ~220 | Tunn CLI-wrapper — grandfather tills split |
+| `scripts/compare_mtf_disambiguation.py` | ~245 | Dela argparse vs report — grandfather tills split |
+| `src/fibengine/research/human_review_level_events.py` | ~610 | Dela pack writer vs runner — grandfather (main PR #11) |
+
+Lägg **inte** till funktioner i grandfathered filer; fixa genom split.
+
+### När ska du dela?
+
+- Modul över gränsen **och** inte på grandfather-listan.
+- Flera orelaterade klasser eller `if __name__` + stor GUI i samma fil.
+- Du kan inte beskriva filens ansvar i en mening.
+
 ## 3. Namnkonventioner
 
 - **Filer i kod:** `snake_case.py`.
@@ -254,18 +299,30 @@ Premortem-tänk och reflektion är en **obligatorisk del** av arbetsflödet.
    ny backtest-matris) ska minst en reflektion skrivas i
    `premortem/reflections/`.
 3. Filnamn i `premortem/reflections/` **MÅSTE** följa:
-   `YYYY-MM-DD-<kort-beskrivning>.md`
-4. Reflektionen **MÅSTE** innehålla:
+   `YYYY-MM-DD-<kort-beskrivning>.md` (eller `premortem/reflections/YYYY/` när årsindelning
+   är aktiv — se `premortem/reflections/README.md`).
+4. **INDEX:** Nya reflektioner ska listas i `premortem/reflections/INDEX.md` (en rad:
+   datum, fil, typ, ämnen, status).
+5. Reflektionen **MÅSTE** innehålla:
    - Hypotes
    - Scope (symbol/timeframe/data)
    - Observationer (nyckelmetrics)
    - Beslut
    - Nästa steg
+6. **Storlek (MÅSTE):** varje fil i `premortem/reflections/*.md` (utom `INDEX.md`/`README.md`)
+   är **≤ 80 rader** och **≤ 8 KiB**. Detaljer → `docs/` eller `experiments/results/`.
+   Pre-commit hook `repo-bounds` verkställer detta (samma regler som §2B för kod/docs).
 
 ### Miniminivå per vecka
 
 - Minst **en** ny reflektion per aktiv vecka där experiment körs.
 
+### Skalning
+
+När `reflections/` växer: följ `premortem/reflections/README.md` (flat + INDEX → års-mappar
+→ arkiv för `historical`). Djupare guider (t.ex. maskin-labeling) i `docs/`, inte som
+långa reflektioner.
+
 ## 12. Skriva på policyn
 
 Policyn ändras genom att uppdatera den här filen direkt. Vid större ändringar i

config/README.md

@@ -9,9 +9,14 @@ Konfiguration för körningar.
 
 Baseline:
 
-- `settings.yaml` är baseline och ska hållas stabil.
+- `settings.yaml` är baseline (`exchange: bitfinex`, USD-par) och ska hållas stabil.
 - Experiment ska i första hand köras med `--config config/variants/<fil>.yaml`.
 
+Bitfinex / Genesis validate:
+
+- `settings.bitfinex.yaml` — samma som baseline (explicit profil för Genesis-dok).
+- Körordning och symbol-mappning: [`docs/GENESIS_BITFINEX_VALIDATE.md`](../docs/GENESIS_BITFINEX_VALIDATE.md).
+
 Spårkoppling:
 
 - `settings.yaml` = **Promotion** (canonical baseline).

config/settings.bitfinex.yaml

@@ -0,0 +1,65 @@
+# Bitfinex / Genesis-Core validate-profil (Research — ändrar INTE baseline).
+#
+# Samma pivot/scoring/backtest-gates som config/settings.yaml; endast data-källan
+# pekar på Bitfinex (CCXT) för att repetera Validate innan inport i Genesis-Core.
+#
+# Se docs/GENESIS_BITFINEX_VALIDATE.md för symbol-mappning och körordning.
+
+seed: 42
+
+data:
+  exchange: bitfinex       # CCXT exchange-id (paper/live via Genesis — samma OHLCV-semantik)
+  symbol: BTC/USD          # Bitfinex spot (inte USDT); justera mot er Genesis-paper-lista
+  timeframe: 1h
+  limit: 500
+  timeframe_limits:
+    4h: 1000
+    1d: 1000
+    1w: 1000
+    1M: 500
+
+pivots:
+  lookback: 3
+  atr_period: 14
+  min_prominence_atr: 0.5
+  mode: fractal
+  fractal_n: 1
+
+scoring:
+  weights:
+    magnitude: 0.8
+    recency: 0.6
+    prominence: 0.5
+    cleanliness: 0.9
+    round_number: 0.2
+    duration: -0.4
+    structure_alignment: 1.4
+    scale_confluence: 1.2
+  duration_target: 20
+  max_candidate_legs: 50
+  structure_window: 6
+  confluence_degrees: [5, 12]
+  confluence_tol_bars: 3
+  confirm_min_retrace: 0.1
+
+fib:
+  levels: [0.236, 0.382, 0.5, 0.618, 0.786]
+
+evaluation:
+  price_tol_atr: 0.5
+  time_tol_bars: 3
+  fib_level_tol: 0.02
+
+sizing:
+  enabled: false
+  entry_levels: [0.382, 0.5, 0.618]
+  sizes: [1.0, 2.0, 3.0]
+
+backtest:
+  warmup_bars: 60
+  step: 1
+  extension_tol_bars: 5
+  gate_max_flip_rate: 0.35
+  gate_min_confirmed_rate: 0.5
+  gate_min_direction_consistency: 0.8
+  gate_max_endpoint_drift_bars: 40.0

config/settings.yaml

@@ -2,8 +2,8 @@
 seed: 42
 
 data:
-  exchange: binance       # CCXT exchange-id
-  symbol: BTC/USDT
+  exchange: bitfinex      # CCXT exchange-id (Binance geo-blocked on some CI/cloud hosts)
+  symbol: BTC/USD         # Bitfinex spot (USD, not USDT)
   timeframe: 1h
   limit: 500              # antal candles att hämta (default per timeframe)
   timeframe_limits:       # override för långa TF så äldre labels inte hamnar out-of-window
@@ -52,6 +52,12 @@ sizing:
   entry_levels: [0.382, 0.5, 0.618]  # skala in i dessa retracement-nivåer
   sizes: [1.0, 2.0, 3.0]             # störst storlek i gyllene zonen (0.618)
 
+labeling:
+  # Research: 1W label med H+L på samma vecka → resolve via 1D (labeling.tool save).
+  enable_same_candle_mtf_resolution: true
+  # Research: motor MTF Disambiguation Layer (OFF = baseline; ON = läs LTF-ordning).
+  mtf_disambiguation: false
+
 backtest:
   # Kausalt walk-forward: mät hur stabilt urvalet är över tid (Lager A).
   warmup_bars: 60   # barer innan första urvalet

data/labels/README.md

@@ -12,14 +12,15 @@ labels/
       {timeframe}.json
 ```
 
-Exempel: `binance/BTC-USDT/1h.json`
+Exempel (ny default): `bitfinex/BTC-USDT/1h.json`  
+Legacy research-facit: `binance/` (Binance-perioden, behålls oförändrat).
 
 ## Index
 
 - `INDEX.md` — tabell över alla labels (path, exchange, symbol, timeframe).
 - `binance/README.md` — översikt per börs.
 
-Labels skrivs via `uv run python -m fibengine.labeling.tool`.
+Labels skrivs via `uv run python -m fibengine.labeling.tool` (begränsningar: [`docs/LABELING_TOOL.md`](../docs/LABELING_TOOL.md)).
 
 Kör `uv run python -m fibengine.labeling.worklist` för att se täckning mot
 20–30-setup-målet (PREMORTEM.md) och få färdiga `labeling.tool`-kommandon för de
@@ -32,4 +33,18 @@ Varje label har ett `source`-fält:
   från recall/agreement och räknas inte mot 20–30-målet. Granska i `labeling.tool`
   och spara → blir `human`.
 
+**Två giltiga typer av maskin-svar** (motor-swing vs chartfönster): [`docs/MACHINE_LABELING.md`](../docs/MACHINE_LABELING.md).
+
 Legacy platt filnamn (`binance_BTC-USDT_1h.json` på rot) stöds fortfarande vid läsning men nya sparas i kategoriserad struktur.
+
+## Multi-leg (research, 1d+)
+
+Flera fib-legs i **samma** fil när du märker ned + upp (eller fler segment) på daily:
+
+- Spara via labeling tool: `p` (push leg), sedan `s` — se [LABELING_TOOL.md](../docs/LABELING_TOOL.md) §5B.
+- JSON får `"legs": [ { "id": "leg_1", "high": ..., "low": ... }, ... ]`.
+- Top-level `high`/`low` = leg_1 (bakåtkompatibilitet för motor/recall idag).
+
+**Exempel:** `binance/BTC-USDT/1d.json` — 30 legs (BTC HUR-facit, 2026-05-29).
+
+**Motor använder inte** `legs[]` än — endast research/golden. Se [MTF_DAILY_RESEARCH.md](../docs/MTF_DAILY_RESEARCH.md).