> ## Documentation Index
> Fetch the complete documentation index at: https://docs.novosky.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> Development workflow, invariants to respect, and what to check before submitting changes.

## Before you change anything

1. Read `AGENTS.md` — it is the canonical shared context for all contributors
2. Check `docs/` for the relevant page before relying on memory
3. Read the affected source files before changing behavior
4. Make the smallest change that solves the request

***

## Development workflow

<Steps>
  <Step title="Validate the current state">
    ```bash theme={null}
    python backtest.py --balance 500 --no-swap --leverage 500 --spread 14.59 --oos-only --no-chart
    ```

    Record the baseline score before making changes.
  </Step>

  <Step title="Make your change">
    For ML changes: follow the three-file rule — `feature_engineering.py`, `ml_config.json`, and retrain all 4 models.

    For execution changes: update both `trading/bot.py` and `backtest/run.py`.

    For config changes only: use `scripts/sweep.py` without retraining.
  </Step>

  <Step title="Retrain if needed">
    ```bash theme={null}
    python scripts/retrain.py
    ```

    Always use this strict order.
  </Step>

  <Step title="Validate OOS">
    ```bash theme={null}
    python backtest.py --balance 500 --no-swap --leverage 500 --spread 14.59 --oos-only --no-chart
    ```

    The new score should beat the baseline. If it doesn't, investigate before proceeding.
  </Step>

  <Step title="Dry-run the bot">
    ```bash theme={null}
    python trading.py --dry
    ```

    Watch a few cycles to verify no errors.
  </Step>

  <Step title="Push models">
    ```bash theme={null}
    python ml/hf_hub.py --push
    ```

    Only push if the OOS score improved.
  </Step>
</Steps>

***

## Invariants

These rules must never be violated:

* **Never reorder, add, or remove ML features** without updating `ml_config.json` and retraining all 4 models
* **Never change execution logic** in `trading/bot.py` without mirroring the change in `backtest/run.py`
* **Training order is strict:** Signal → Position → SLTP → Risk
* **Never diverge `RISK_FEATURES`** across `ml/risk_trainer.py`, `ml/risk_predictor.py`, and `ml_config.json`
* **Never drop protected features** (`is_news_near`, `news_minutes_away`, `news_count_today`, `is_news_risk_window`, `is_london_session`, `is_ny_session`, `is_asian_session`) based on SHAP alone
* **Never run live trading before a dry-run**
* **Never train on Azure ML** — training is local-only, GPU first, CPU fallback

***

## What to check before committing

* [ ] `python backtest.py --oos-only --no-chart` passes with equal or better score
* [ ] `python trading.py --dry` runs without errors for 3+ cycles
* [ ] `ml_config.json` and `models/model_compat.json` are in sync if features changed
* [ ] `trading/bot.py` and `backtest/run.py` are in parity if execution logic changed
* [ ] `RISK_FEATURES` is consistent across all three risk files if risk features changed
* [ ] New models pushed to HF Hub: `python ml/hf_hub.py --push`

***

## Roadmap and open work

Active priorities (as of April 2026):

* **Multi-account support** — `--account` flag to run multiple profiles simultaneously
* **Multi-instrument** — XAUUSD, EURUSD alongside BTCUSD
* **Multi-datasource OHLCV** — secondary data source fallback
* **Broker-agnostic refactor** — full `config/brokers.json` registry coverage

To contribute to any of these, start a discussion or open a PR against `main`. Include an OOS backtest result showing the change is neutral or positive before requesting a merge.