Market_State_Board/README.md

# MarketStateBoard_MTF

Multi-timeframe market-state indicator for MetaTrader 5 / MQL5.

## Overview

MarketStateBoard_MTF is a MetaTrader 5 / MQL5 indicator that presents a market-state view of a trading symbol across nine fixed timeframes. It is a separate-window indicator (`indicator_separate_window`, height 128) that renders a compact market-state board as chart objects. It declares no indicator buffers and no plots.

Current production baseline: **version 1.190 (PATCH-19)**, frozen and published as an indicator-project publication on MQL5 Algo Forge.

## What the Indicator Does

The indicator performs an independent per-timeframe evaluation for each of the nine supported timeframes, combining:

- bar geometry (body ratio, wick dominance, close location);
- oscillator evidence (RSI, Stochastic, CCI, MACD);
- ATR context;
- tick-volume context.

Each timeframe's evidence is aggregated into a market-state assessment, and the nine assessments are combined into a single global market-state board with a global score panel. The board shows the global score on a -1.00…+1.00 ruler, a BULLISH / NEUTRAL / BEARISH reading, and a Global Market Dynamics type/strength summary (PATCH-19 semantic aggregation across all nine timeframes).

The implementation is deterministic and stateless: identical inputs produce identical output.

## Timeframe Universe

The production configuration uses a fixed nine-timeframe (9-TF) universe:

**M1 / M5 / M15 / M30 / H1 / H4 / D1 / W1 / MN1**

All nine timeframes are always analyzed. There are no per-timeframe enable or disable inputs.

## State Modes

The indicator selects the evaluated candle through a single input (`InpCandleSource`):

- **CURRENT** — the evaluation uses the current, in-progress bar of each timeframe.
- **CLOSED** — the evaluation uses the most recently completed (closed) bar of each timeframe.

In CURRENT mode each timeframe is re-evaluated on a rate-limited, round-robin schedule. In CLOSED mode a timeframe is re-evaluated only when that timeframe's own most recent closed-bar timestamp changes. The board caption always shows the active mode (`CURRENT` or `CLOSED`).

## Processing Architecture

The high-level processing pipeline is:

```
Base Market State -> Market Dynamics -> Dynamic Modifier -> Final State
```

- **Base Market State** — per-timeframe evaluation of bar geometry, oscillator evidence, ATR context and tick-volume context.
- **Market Dynamics** — the Market Dynamics Modifier (MDM) layer classifies the dynamic response as CONTINUATION / DAMPENING / REVERSAL / UNRESOLVED with strength WEAK / STRONG / VERY STRONG / EXTREME. PATCH-18 aggregates Market Dynamics semantically across all nine timeframes; PATCH-19 adds calendar-news evidence to the MDM evaluation.
- **Dynamic Modifier** — the MDM outcome produces a numeric modifier that is applied to the base state.
- **Final State** — the resulting per-timeframe and global market state is presented on the board.

## Main Components / Dependencies

The frozen source resolves three required include files at compile time:

| Include | Role |
|---|---|
| `Include/MarketStateBoard_Fuzzy.mqh` | PATCH-09 fuzzy membership layer — mathematical membership for the RSI, Stochastic, CCI and MACD evidence channels |
| `Include/MarketStateBoard_MDM_PATCH19.mqh` | PATCH-19 Market Dynamics Modifier (News Dynamic) |
| `Include/MarketStateBoard_Weights.mqh` | PATCH-11 dynamic weight engine — direction-neutral contextual weights |

All three files must be present in the MQL5 `Include\` directory for the source to compile. In the implementation's documented semantics, membership values, weights and the MDM modifier are mathematical/descriptive quantities, not probabilities, confidence measures, or predictive statements.

## Installation

1. Copy the indicator files into the MetaTrader 5 MQL5 directory:
   - `Indicators\MarketStateBoard_MTF_PATCH19_NEWS_DYNAMIC_9TF_FINAL_v1.190.mq5` into `MQL5\Indicators\`; the published `.ex5` can be used without compiling;
   - the three `.mqh` files (`MarketStateBoard_Fuzzy.mqh`, `MarketStateBoard_MDM_PATCH19.mqh`, `MarketStateBoard_Weights.mqh`) into `MQL5\Include\`.
2. If using the source, compile it in MetaEditor (frozen compile gate: 0 errors, 0 warnings).
3. Attach the compiled indicator to a chart. The indicator renders its board in a separate window and creates chart objects with the `MSB_` prefix.

## Basic Usage

- Select the candle source (CURRENT or CLOSED). The board caption reflects the active mode.
- Context inputs: ATR period (14), body lookback (14), volume lookback (14).
- Panel inputs: X/Y position (10/10) and label / bullish / bearish / neutral / conflict / unavailable colors.
- Optional alerts on alignment change are disabled by default.
- The nine-timeframe universe is fixed; there are no per-timeframe switches.

## Validation Status

The production baseline has the following documented validation record:

| Gate | Result |
|---|---|
| Native compile | 0 errors / 0 warnings |
| R4 (sub-gates R4.1, R4.2, R4.3, R4.4A, R4.4B) | PASS |
| Final R4 | PASS |
| R4.4B independent recomputation | PASS for all 9 timeframes in the recorded validation snapshot |

These statements are scoped to the recorded validation evidence (frozen v1.190 source, XAUUSD, CLOSED-state snapshot, 2026-09-16). They establish that the frozen implementation compiles cleanly and that an independent recomputation matched the recorded published snapshot within the documented R4.4B scope. They do **not** establish profitability, accuracy guarantees, predictive edge, or future performance.

## Version / Publication Identity

| Field | Value |
|---|---|
| Project | MarketStateBoard_MTF |
| Version | 1.190 |
| Patch | PATCH-19 |
| Product type | MetaTrader 5 / MQL5 multi-timeframe market-state indicator |
| Forge | MQL5 Algo Forge |
| Repository | `chiki2bum2/Market_State_Board` (public, branch `main`) |
| Publication scope | Indicator project publication only |
| Publication commit | `822911bb74f7cca790ebcfb76c1d60fee306055e` |

## Scope and Limitations

- This repository documents an indicator implementation and its recorded validation snapshot.
- Validation evidence is specific to the recorded validation scope; it does not establish profitability and is not a guarantee of future performance.
- Research results, backtests, calibration data and strategy-performance material are outside this repository's publication scope.
- The published source and EX5 correspond to the frozen v1.190 baseline and must not be modified by documentation updates.

## Repository Structure

```
docs/       Governance and publication records
Include/    Required include files (MarketStateBoard_*.mqh)
Indicators/ Production source, compiled indicator, compile evidence, package descriptors
```

Published file set (root commit `822911bb`):

| Path | Role |
|---|---|
| `Indicators/MarketStateBoard_MTF_PATCH19_NEWS_DYNAMIC_9TF_FINAL_v1.190.mq5` | Production source (frozen) |
| `Indicators/MarketStateBoard_MTF_PATCH19_NEWS_DYNAMIC_9TF_FINAL_v1.190.ex5` | Compiled indicator (frozen) |
| `Indicators/MarketStateBoard_MTF_PATCH19_NEWS_DYNAMIC_9TF_FINAL_v1.190.log` | Compile log |
| `Indicators/MarketStateBoard_MTF_PATCH19_NEWS_DYNAMIC_9TF_FINAL_v1.190/README.md` | Package description |
| `Indicators/MarketStateBoard_MTF_PATCH19_NEWS_DYNAMIC_9TF_FINAL_v1.190/MANIFEST.json` | Artifact inventory with hashes and compile gate |
| `Indicators/MarketStateBoard_MTF_PATCH19_NEWS_DYNAMIC_9TF_FINAL_v1.190/LICENSE` | MIT license |
| `Indicators/NativeCompileEvidence/MarketStateBoard_MTF_PATCH19_NEWS_DYNAMIC_9TF_FINAL_v1.190_20260916_082759711.json` | Compile-gate evidence |
| `Include/MarketStateBoard_Fuzzy.mqh` | Required include |
| `Include/MarketStateBoard_MDM_PATCH19.mqh` | Required include |
| `Include/MarketStateBoard_Weights.mqh` | Required include |
| `docs/MSB_PUB_001_PUBLICATION_RECORD_2026-09-17.md` | Publication record |

## License

The repository includes an MIT License (`Indicators/MarketStateBoard_MTF_PATCH19_NEWS_DYNAMIC_9TF_FINAL_v1.190/LICENSE`).