mt5-ai-xauusd-trader/docs/CONTRIBUTION_MAP.md

# 🗺️ Contribution Map

This map defines the "Safe Zones" and "Sensitive Zones" of the MT5 AI/ML Trading Bot repository to help contributors find the best starting point and understand the review expectations for different areas.

## 🚦 System at a Glance

| Zone | Path | Risk Level | Review Requirement | Evidence Required |
| :--- | :--- | :--- | :--- | :--- |
| **Safe Zone** | `docs/`, `tests/`, `scripts/`, `Makefile`, `.github/`, `.jules/`, `README.md`, `CONTRIBUTING.md`, `pyproject.toml`, `.gitignore`, `.env.example`, `.pre-commit-config.yaml`, `alembic.ini`, `SECURITY.md`, `DEVELOPMENT_PLAN.md`, `DATABASE_STANDARDS.md`, `DEPLOYMENT_GUIDE.md`, `RISK_LIMITS.md`, `TRADING_STANDARDS.md`, `ATTRIBUTIONS.md`, `CHANGELOG.md`, `SETUP_GUIDE.md`, `.python-version` | 🟢 Low | Standard Peer Review | Zero-Dep Unit Tests / Doc Lint |
| **Utility Zone** | `src/utils/`, `src/analytics/`, `src/monitoring/` | 🟡 Medium | Domain Expert Review | Integration Tests |
| **Sensitive Zone** | `src/trading/`, `src/models/`, `src/core/`, `src/research/`, `src/data/`, `src/environment/`, `main.py` | 🔴 High | Lead + Multi-Signature | Backtests + Stress Tests |

---

## 🟢 Clean Development Environment FAQ

Our development workspace prioritizes safety, clean checks, and clear pathways:

### 1. What is the current CI Status?
CI is fully **🟢 PASSING**. All formatting, linting, and core tests pass cleanly across `src/`, `scripts/`, and `migrations/`. You can confidently expect pull request pipelines to succeed when matching our standard quality gates.

### 2. Is there any branch turbulence?
No. Past sandbox-specific warnings about "history grafting" were false-positives caused by working inside shallow clones (depth=1). The remote repository history is **100% linear, stable, and perfectly intact**, ensuring complete auditability.

### 3. How do I make sure my PR is aligned?
Check the [Merge-Ready Checklist](./status/MERGE_READY_CHECKLIST.md) and keep your branch updated using `make resync` (or standard `git rebase`).

### 4. What PR title format is required?
Our CI enforces semantic PR titles via `.github/workflows/commit-check.yml`.
- **Allowed prefixes:** `feat`, `fix`, `docs`, `chore`, `test`, `refactor`, `style`, `perf`, `ci`.
- **Subject Casing:** The subject after the prefix **must start with a lowercase letter** (e.g., `docs: improve guide`, NOT `docs: Improve guide`).
- **Note:** Do NOT use non-standard prefixes like `DX:` in PR titles; use `docs:` for documentation/onboarding PRs or `chore:` for DX tool scripts.

---

<a name="safe-zones-recommended-for-first-prs"></a>
## 🟢 Safe Zones (Recommended for First PRs)

These areas are perfect for new contributors to get familiar with the project and provide immediate value with minimal risk to trading operations.

### 1. Documentation (`docs/`)
- **Improvement Areas:** Clarity, typos, missing diagrams, or adding new guides (e.g., specific cloud deployment steps).
- **Goal:** Make the system easier to understand and run for the next engineer.

### 2. Testing (`tests/`)
- **Improvement Areas:** Increasing coverage for `src/utils/`, adding edge-case unit tests, or performance benchmarks.
- **Goal:** Strengthen the system's reliability without changing production logic.

### 3. Developer Experience (`scripts/`, `Makefile`, `.github/`, `.jules/`)
- **Improvement Areas:** Improving `make doctor` checks, `bootstrap.sh` robustness, GitHub Actions workflows, or adding new CLI helpers for developers.
- **Goal:** Reduce the "Time to First Success" for new developers.

### 4. Root Safe Files (`README.md`, `CONTRIBUTING.md`, `pyproject.toml`, `.gitignore`, `.env.example`, `.pre-commit-config.yaml`, `alembic.ini`, `SECURITY.md`, `DEVELOPMENT_PLAN.md`, `DATABASE_STANDARDS.md`, `DEPLOYMENT_GUIDE.md`, `RISK_LIMITS.md`, `TRADING_STANDARDS.md`, `ATTRIBUTIONS.md`, `CHANGELOG.md`, `SETUP_GUIDE.md`, `.python-version`)
- **Improvement Areas:** Documentation clarity, developer environment templates, setup guides, runtime version declarations, database standards, and dependency management configs.
- **Goal:** Clarify contributor instructions, environmental templates, and project metadata without touching production logic.

---

## 🧪 Zero-Dependency Test Verification

New contributors in Safe Zones do **not** need to install heavy machine learning, PyTorch, or trading dependencies to verify their work. The core governance and diagnostic test suites run directly using Python's standard library `unittest` module:

```bash
# Run doctor diagnostic checks
PYTHONPATH=. python3 -m unittest tests/test_doctor_diagnostics.py

# Run repository governance vitals check
PYTHONPATH=. python3 -m unittest tests/test_governance_vitals.py

# Run PR triage dashboard tests
PYTHONPATH=. python3 -m unittest discover -s tests -p "test_triage*.py"
```

---

## 🟡 Utility & Analytics Zones

These areas require a deeper understanding of the system's data structures but do not directly influence live trading decisions.

### 1. Utilities (`src/utils/`)
- **Improvement Areas:** Optimization of generic helpers, logging improvements, or date/time formatting.

### 2. Analytics (`src/analytics/`)
- **Improvement Areas:** Post-trade analysis reports, visualization of backtest results, or journal mining logic.

### 3. Monitoring & Telemetry (`src/monitoring/`)
- **Improvement Areas:** Grafana dashboard JSON configurations (`trading_overview.json`), telemetry metrics definitions, and health status indicators.

---

## 🔴 Sensitive Zones (High-Stake Areas)

Changes to these directories affect the core financial and operational safety of the bot. Contributions here require extensive evidence (backtests, stress tests) and mandatory lead review.

### 1. Trading Logic (`src/trading/`)
- **Modules:** `mt5_connector.py`, `risk_manager.py`, `execution_filter.py`.
- **Constraint:** Do NOT modify without explicit coordination with Jules01/Jules03.

### 2. Model Architectures (`src/models/`)
- **Modules:** `dynamic_ensemble.py`, `ppo_agent.py`, `regime_detector.py`.
- **Constraint:** Changes must be backed by quantitative research and Jules04 approval.

### 3. Core Engine (`src/core/`)
- **Modules:** `config.py`, `health.py`, `constants.py`.
- **Constraint:** Affects system-wide invariants and startup safety.

### 4. Quant Research & Simulation (`src/research/`)
- **Modules:** `stress_lab.py`, `hyperopt_walkforward.py`, `rare_event_simulator.py`, `rl_evaluation.py`.
- **Constraint:** Owned by Jules04; changes require quantitative evaluation metrics and validation of experimental realism.

### 5. Event Intelligence & Market Feeds (`src/data/`)
- **Modules:** `event_intelligence.py`, `event_models.py`.
- **Constraint:** Feeds real-time event signals into execution and feature pipelines.

### 6. Gym Simulation Environment (`src/environment/`)
- **Modules:** `gym_env.py`.
- **Constraint:** Core reinforcement learning simulation, state transitions, and reward penalties.

### 7. CLI Entrypoint & System Orchestration (`main.py`)
- **Modules:** `main.py`.
- **Constraint:** Central entrypoint for trading modes, CLI safety gates, and component lifecycle initialization.

---

## 🛠️ How to Pick Your First Task

1.  **Read [Your First Real Contribution](./FIRST_REAL_CONTRIBUTION.md):** Follow our step-by-step guide to making a low-risk, high-impact first contribution.
2.  **Filter PRs by Label:** Use GitHub's label filters to find existing work in Safe Zones for inspiration or collaboration:
    - `is:pr is:open label:docs`: Documentation improvements.
    - `is:pr is:open label:test`: Testing and coverage enhancements.
    - `is:pr is:open label:chore`: Maintenance and developer experience tasks.
3.  **Run `make doctor`:** Run `make doctor` (or `python3 scripts/doctor.py`) to verify environment health and execute automated "Contributor Readiness" checks. The `Contribution Safety` check automatically validates that your changed files reside in Safe Zones (`docs/`, `tests/`, `scripts/`, `Makefile`) before opening a PR.
4.  **Check `docs/status/PR_TRIAGE_DAILY.md`:** Look for PRs categorized as **"Safe Surface"**. This report is updated daily and is the best source for finding approved first-task candidates.
5.  **Audit `tests/`:** Find a module with low coverage (check `make test` output) and add missing unit tests.
6.  **Use `make resync`:** Always run this command before submitting to ensure your branch is aligned with the latest commit.

---
*This map is maintained by Jules06 (qufuwan). If you are unsure where your change fits, please open a discussion or tag a maintainer.*