@battlegrid/mcp-server 31.1.0 → 31.1.5

package/README.md

@@ -24,6 +24,195 @@ Seeing package `31.x` alongside handshake `battlegrid@33.x` — the package **be
 
 **What this changes for you:** nothing about how you call anything. Upgrading the package no longer waits on a server deploy, and a server deploy no longer strands you on a package that names the wrong contract — reconnect and the announcement follows. **Contract breaking-change notes are no longer keyed to package versions**, since a contract move is no longer a release here; the v11-and-earlier notes below are kept as history, and the live vocabulary is always discovery.
 
+## Contract history — v37 → v48.1
+
+Eleven majors reached authors while this section stopped at v36. That gap is the mechanism, not an
+oversight: since v31 a contract move needs no release here, so nothing forced a note to be written —
+and the documentation ships inside the tarball, so a note written but unpublished reaches nobody.
+Both halves are now closed by a rule keyed to the *served* contract rather than to a release of this
+package.
+
+### Changed meaning, unchanged shape
+
+- **Three tools serve different values for identical input** (47.3.0, `derive-scan-fetch-from-report`).
+  The radar scan leg now derives its timeframe fetch from the strategy's **report** rather than the
+  on-duty agent's three perception rungs, so a required condition addressing an absolute timeframe
+  outside those rungs — never evaluated at scan before — now is. No field moves; the values do:
+
+  | Tool | What moves |
+  |---|---|
+  | `preview_radar_resolution` | `conditionReach[].reachReason` goes `AGENT_TIMEFRAME` → `null` |
+  | `get_radar_activity` | `scanReachReason` moves the same way, **on new rows only** — rows already written keep what they were recorded with |
+  | `get_agent_coin_qualification` | `reachReason` moves the same way; its sibling `verdict` moves `UNMEASURABLE` → a decided verdict |
+
+  **Read the last one carefully:** a client treating `UNMEASURABLE` as "this gate is switched off"
+  will now see that gate **BLOCK**. `AGENT_TIMEFRAME` keeps its member and narrows to the one cause
+  no fetch can discharge. Nothing in the payload tells you this moved.
+
+### Rejected input — something you author is no longer accepted
+
+- **A benchmark-bound section no longer accepts crowd metrics or rank transforms** (49.0.0,
+  `fix-benchmark-legality-save-path`). On a custom section carrying a non-null `benchmarkTicker`, a
+  column whose metric is enrichment-stage (the `CROWD_*` family, `FLOW_ALIGN`, `SMART_RETAIL`,
+  `CAPTAIN_CONF`, `CONFIDENCE`, `SETTLED_AT`, the `PERP_SPOT_*` trio) is refused with
+  `REPORT_COLUMN_BENCHMARK_METRIC_UNSUPPORTED`, and one carrying a `rank` transform in either the
+  direct or the chained position with `REPORT_COLUMN_BENCHMARK_TRANSFORM_UNSUPPORTED`. Every tool
+  accepting a section array is affected, and no other byte of your body changes.
+
+  **Fix it by moving the column, not by retrying.** Both readings are defined *relative to the
+  cohort being evaluated* — a crowd reading is what this session's players did, a rank is a position
+  among the coins under evaluation — and a benchmark is deliberately outside that cohort. Neither
+  has a value there, which is why such a column could never render. Put it on an ordinary section
+  (`benchmarkTicker: null`), or drop it.
+
+  **This is a fix, not a new rule.** The restriction shipped with benchmark sections and was already
+  enforced by the column builder, by report materialization, and by `get_strategy_column_contract` —
+  so an author who checked a column against discovery first has been seeing this refusal all along.
+  What changed is that the SAVE path now asks the same question. Previously it did not, so such a
+  section persisted and then failed at every evaluation instead of at authoring.
+
+- **A custom report section no longer accepts `timeframe`** (48.0.0,
+  `remove-section-anchor-override`). The per-section anchor override is gone. Every tool accepting a
+  section array — `compile_strategy_plan`, `preview_strategy_report`, `derive_strategy_rule_view`,
+  and `apply_strategy_plan` — refuses a section carrying it: `sections[N]: Unrecognized key(s)`,
+  with no other byte of your body changing. Drop the key. A section's columns resolve against the
+  **strategy** timeframe, and a column reaches any other timeframe by pinning it on the column
+  (`timeframe: { abs: '4h' }`) — which it could always do. Relative column references
+  (`anchor`/`lower`/`regime`) are untouched, and are the point: they track the strategy.
+
+- **A custom report section requires `notes`** (43.0.0, `add-authored-section-notes`). Every tool
+  accepting a section array — `compile_strategy_plan`, `preview_strategy_report`,
+  `derive_strategy_rule_view` — refuses a section without it: `sections[N].notes: Required`, with no
+  byte of your body changing. Send explicit `null` for "no note". It is required rather than optional
+  because these payloads are a FULL REPLACE: an omitted key and an explicit `null` would be the same
+  request on the wire, so every rebuild site would silently clear a note its author wrote.
+  `benchmarkTicker` carries the same required-nullable discipline for the same reason.
+
+- **Every condition requires `clock` and `closes`** (44.0.0, `add-condition-clock`), and **`exit`**
+  arrives with them. A condition entry now carries eight keys, not five. `clock` is `"LIVE"` (the
+  previous behaviour — the forming bar) or `"CLOSE"` (settled bars); `closes` is how many consecutive
+  closed bars must read true, 1–5, and is always `1` under LIVE. No wire default, for the same
+  whole-set-replacement reason as `notes`: a defaulted key would let an unrelated re-save silently
+  un-clock an enforced money gate back to forming-bar evidence.
+
+  A `CLOSE` clock is accepted only where a closed frame can change the reading — the clause must
+  resolve from the coin's own candle series at offset 0. Frame-inert operands (perp-payload scalars,
+  published rolling changes, ranks, zone entities, regime labels, enrichment metrics, session
+  scalars) are refused with `CONDITION_CLOCK_OPERAND_ILLEGAL` naming the header and the remedy: split
+  that clause into its own LIVE condition and `conditionRef` it. `exit: true` is legal only under
+  `clock: "CLOSE"` — an exit fired on a forming bar is an intrabar exit.
+
+- **A strategy requires a seven-key `entry` object** (44.0.0 for four keys, 47.0.0 for three more —
+  `add-entry-on-close`, `add-level-trigger-execution`). Required on every CREATE, on
+  `compile_strategy_plan`, `apply_strategy_plan` and `update_intelligence_agent`. A client sending
+  44.0.0's four-key object is refused under 47 with `entry.levelSource: Required` without one byte of
+  it changing.
+
+  ```jsonc
+  "entry": {
+    "trigger": "AT_SIGNAL",          // | ON_CANDLE_CLOSE | STOP_THROUGH_LEVEL | ON_RETEST
+    "confirmTf": "4h",               // the strategy timeframe or the rung below it — nothing else
+    "closes": 1,                     // 1–5; must be 1 unless ON_CANDLE_CLOSE
+    "bandAtrMultiple": 1.0,          // > 0, and <= the platform's entry-deviation gate
+    "levelSource": "SWING_HIGH",     // | SWING_LOW | BOLLINGER_UPPER | BOLLINGER_LOWER
+    "levelOffsetAtrMultiple": 0,     // 0–2, UNSIGNED; must be 0 unless a level trigger
+    "validForBars": 4                // 1–24 of the strategy's own bars
+  }
+  ```
+
+  `AT_SIGNAL` with those values is byte-identical to pre-44 behaviour. The legality matrix runs one
+  way: all seven keys are always present, so a MEANINGFUL value under a trigger that ignores it is
+  refused rather than accepted-and-dropped — a dial never silently does nothing.
+
+- **A `strategyTimeframe` the platform does not ingest is refused** (39.0.0,
+  `move-renderer-to-rendered-section`) on `get_coin_market_context`, where it was previously
+  accepted. The number is the only signal a client gets.
+
+- **`eventType` gains `ENTRY_EXPIRED_UNCONFIRMED`** (48.1.0, `fix-entry-arming-lifecycle`) on
+  `get_radar_activity` and `get_radar_activity_summary` — an armed entry that reached its episode
+  lifetime without ever receiving a confirming close. A client holding its own closed copy of that
+  enum rejects the new member; one that switches exhaustively on it needs the branch.
+
+  `entryVoidCause` is deliberately **unchanged** and still carries exactly `BAND`, `CONDITIONS`,
+  `STRUCTURAL`. Each of those is a measurement taken *at* a close, so an episode that reached no
+  close gets its own event type rather than a fourth cause — `ENTRY_VOIDED` means "called off at the
+  close", a claim this outcome must not make.
+
+  The authoring boundary also gains a refusal with **no schema change**: a strategy declaring an
+  arming trigger whose `required` conditions read the `LIVE` clock is rejected on the existing
+  `VALIDATION_ERROR` code, naming the offending condition key. Same code, same shape, new reason —
+  so nothing in the published schema tells you it can now happen.
+
+### Removed — no alias exists
+
+- **`get_coin_market_context` is REMOVED** (40.0.0, `retire-get-coin-market-context`). Calling it
+  returns an unknown-tool error. There is deliberately **no alias**: a silent redirect would hide a
+  payload shape change from a client that never asked for one. Use `get_market_context`.
+
+- **`get_macd_heatmap` leaves the published surface** (41.0.0). Same shape of break, same absence of
+  an alias.
+
+- **`isPrimary` is removed from every published `EvaluatedSignal`** (38.0.0) — `get_signal_log`,
+  `get_public_agent_signal_log_detail`, and every other tool returning a signal scorecard. Reading it
+  now finds the key absent rather than false.
+
+### Reshaped output — the same call returns a different shape
+
+- **The normalized report section loses `timeframe`** (48.0.0, `remove-section-anchor-override`), on
+  every tool that publishes a strategy: `get_strategy`, `fork_strategy`, `archive_strategy`,
+  `restore_strategy`, `update_strategy_signal_rule`, `apply_strategy_plan`, and
+  `compile_strategy_plan`'s post-state. A strict parser rejects the shorter object; a lenient one
+  reads a section whose anchor is the strategy timeframe, which it now always is.
+
+- **`get_strategy_column_contract` renames its anchor, both ways** (48.0.0). The request field
+  `sectionTimeframe` becomes `anchorTimeframe` — same meaning, and still optional. On the response,
+  `timeframe.requiresSectionTimeframe` becomes `requiresAnchorTimeframe`, and
+  `timeframe.sectionTimeframeOverrideAllowed` is **removed**: it published whether a column could go
+  in an anchor-overridden section, and no section can be overridden. One call also stops being
+  refused — a timeframe-inert metric supplied with an anchor now compiles.
+  `REPORT_COLUMN_SECTION_TIMEFRAME_UNSUPPORTED` leaves the `authoringCode` vocabulary.
+
+- **`RenderedSection.notes` stops carrying provenance** (42.0.0, `separate-section-facts-from-read`),
+  on `preview_strategy_report`, `compile_strategy_plan` and `get_market_context`. A new REQUIRED
+  `provenance: string[]` carries it instead. A client reading provenance out of `notes` now reads an
+  author's prose, or nothing — which is a silent misread, not an error.
+
+- **`preview_strategy_report.renderedSections[]` gains `authoredNote`** (43.0.0), the author's read
+  for a custom row and `null` on a platform row. Additive, but published on a `.strict()` shape.
+
+- **`get_radar_activity` serves its evaluation curve on the FIRST PAGE ONLY** (37.0.0), and
+  `get_radar_activity_summary` is added. A client reading the curve off a later page finds it absent.
+
+### Widened enum — new members your own copy rejects
+
+- **The authorable metric vocabulary widens by 29 keys** (46.1.0, `add-indicator-catalog-coverage`):
+  Keltner (`KC_UPPER`/`KC_MID`/`KC_LOWER`), Supertrend (`ST_LINE`/`ST_DIR`), Hull (`HMA20`),
+  WaveTrend (`WT1`/`WT2`), QQE (`QQE_RSI_MA`/`QQE_STOP`), Parabolic SAR (`PSAR`), Ichimoku
+  (`ICHI_CONV`/`ICHI_BASE`/`ICHI_SPAN_A`/`ICHI_SPAN_B`/`ICHI_LAG`), Williams %R (`WILLR14`),
+  Stochastic RSI (`STOCH_RSI14`), session pivots (`PIVOT_P`/`PIVOT_R1`–`R3`/`PIVOT_S1`–`S3`), plus
+  four already-published fields that became addressable: `BB_UPPER`, `BB_LOWER`, `DI_PLUS`,
+  `DI_MINUS`.
+
+  Additive on the wire — every request you can send today is still accepted. It is called out here
+  because a client holding its own closed copy of the metric enum rejects the new members, and
+  because **an agent holding a cached belief that these are inexpressible will substitute for a
+  primitive the platform now serves**. That failure raises no error at all: the author is simply told
+  a strategy cannot be built.
+
+- **`EntryTrigger` gains `STOP_THROUGH_LEVEL` and `ON_RETEST`, and `EntryLevelSource` is published
+  for the first time** with four members (47.0.0). Additive on their own; the required keys above are
+  what make that bump a major.
+
+- **Each signal-checklist item's `measured` object gains a required `triggered` boolean** (47.2.0,
+  `fix-entry-prompt-signal-evidence`) on `get_signal_log` and `get_public_agent_signal_log_detail`,
+  on the `numeric` and `categorical` arms. Additive and MINOR — a client ignoring it is unaffected —
+  but it is named here because a client parsing that output strictly rejects the new key, and because
+  leaving 47.2 unlisted would make a reader wonder what happened to it.
+
+  The `unavailable` arm deliberately does **not** carry `triggered`: "the claim could not be joined to
+  a stored result" and "the signal did not fire" are different states, and leaving the key off that
+  arm makes conflating them a type error rather than a convention.
+
 ## Contract history — v12 → v36
 
 > **The number in this heading is a CONTRACT version, not this package's version.** The npm badge at the top
@@ -176,6 +365,38 @@ Nothing in the proxy changes. No configuration, no environment variable, no call
 
 ### Additive in the same span
 
+- **`get_regime_snapshot` publishes the evidence behind the verdict** (47.1.0,
+  `publish-regime-classification-evidence`). The snapshot gains `evidence`: the quantities the
+  classifier read, the gates it tested them against, the signed margin to the gate deciding whether
+  the current label survives, and the two decision facts only the classifier holds — `gateState`
+  (`cleared` / `held` / `dropped`) and `directionSource` (`di` / `ema`). Nothing narrows; a client
+  that ignores the field is unaffected.
+
+  Read `gateState` before you trust a trend label: **`held` means the ADX hysteresis buffer is
+  carrying the PREVIOUS bar's label rather than this bar re-confirming it** — a materially weaker
+  claim wearing the same word, and one no client could previously detect. `directionSource: 'ema'`
+  is the same shape of warning: the direction came from the fallback that fires precisely when the
+  DI spread is indecisive. The margin is signed so **positive always means "the current label
+  survives by this much"**, in every gate state, so it is safe to branch on its sign.
+
+  `conviction` is a BRANCH DISCRIMINATOR, not a confidence: it encodes *which* rule in the priority
+  ladder matched, not how comfortably it matched. The margins carry comfort. A client reading
+  conviction as a strength score is reading it wrong, and always was — this release just makes the
+  alternative available.
+
+- **Thirteen metric keys join the catalog** (47.1.0) — the `regime` family gains `REGIME_STATE`,
+  `REGIME_CONVICTION`, `REGIME_RUN_BARS`, `REGIME_TREND_GATE`, `REGIME_TREND_MARGIN`,
+  `REGIME_TREND_SOURCE`, `REGIME_DI_SPREAD`, `REGIME_VOL_ATR_RATIO`, `REGIME_VOL_BBW_RATIO`,
+  `REGIME_MOM_BULL_VOTES`, `REGIME_MOM_BEAR_VOTES`, `REGIME_CRASH_MARGIN` and `REGIME_CRASH_LATCH`,
+  making the composite regime and its evidence addressable in a report column or condition for the
+  first time. Only a client that switches exhaustively on `MetricKey` needs new branches.
+
+  Not a contract change, but worth knowing if you author conditions: the report grammar's regime
+  metrics now resolve from the **confirmed close** on every path. They previously resolved from the
+  forming bar when a report was rendered and the confirmed close when the scan swept, so the same
+  condition could read differently in preview than in production. Same wire shape; same bar
+  everywhere now.
+
 `27.1.0` exit-policy authoring input on `compile_strategy_plan` · `19.2.0` `get_account_state` account identity · `19.1.0` Standing Orders marker authoring · `18.4.0` `list_gate_blocks` summary groups · `18.3.0` radar maintenance pause · `18.1.0` protection geometry · `17.2.0` break-even/trailing status · `17.1.0` `get_signal_log` condition evaluation · `13.1.0` four owner-scoped read tools · `12.1.0` cross-venue spot price metrics · `11.1.0` discoverable rate limit.
 
 ## v11 and earlier — contract history (v6 → v11)

package/dist/index.d.ts

@@ -49,7 +49,7 @@ import { type Implementation } from '@modelcontextprotocol/sdk/types.js';
  * being asked. Move it for a change to THIS package — a proxy fix, a dependency bump, a docs
  * correction. Never move it to track the server.
  */
-export declare const PACKAGE_VERSION = "31.1.0";
+export declare const PACKAGE_VERSION = "31.1.5";
 export declare const DEFAULT_URL = "https://mcp.battlegrid.trade/mcp";
 export interface EnvConfig {
     apiKeys: string[];

package/dist/index.js

@@ -52,7 +52,7 @@ import { ListToolsRequestSchema, CallToolRequestSchema, ListPromptsRequestSchema
  * being asked. Move it for a change to THIS package — a proxy fix, a dependency bump, a docs
  * correction. Never move it to track the server.
  */
-export const PACKAGE_VERSION = '31.1.0';
+export const PACKAGE_VERSION = '31.1.5';
 export const DEFAULT_URL = 'https://mcp.battlegrid.trade/mcp';
 const MAX_RETRIES = 3;
 const RETRY_DELAYS_MS = [2000, 4000, 8000];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@battlegrid/mcp-server",
-  "version": "31.1.0",
+  "version": "31.1.5",
   "description": "BattleGrid MCP server — play crypto prediction games from AI agents",
   "type": "module",
   "main": "dist/index.js",

package/skills/battlegrid-strategy-studio/SKILL.md

@@ -88,14 +88,22 @@ values instead of the evaluated coin's — the standard way to gate a whole book
 regime. `benchmarkTicker` is required-nullable on every custom section: send `null` for an
 ordinary section, never omit it.
 
+A bound section takes **indicator** columns only. Crowd/session metrics (the `CROWD_*` family,
+`FLOW_ALIGN`, `SMART_RETAIL`, `CAPTAIN_CONF`, `CONFIDENCE`, `SETTLED_AT`, `PERP_SPOT_*`) and any
+`rank` transform are refused there (contract 49), because both are defined relative to the cohort
+being evaluated and a benchmark sits outside it — a crowd reading is what this session's players
+did, a rank is a position among the coins under evaluation. Neither has a value for BTC-as-yardstick.
+Put those columns on an ordinary section and `conditionRef` across.
+
 Budgets are served by discovery (validated today: 32 sections, 32 custom columns, 8 distinct
 timeframes, 16 conditions, 16 clauses, 16k estimated report tokens). `preview_strategy_report`
 echoes your usage against each cap.
 
 ## Conditions — deterministic logic over your own report
 
-Each condition: `{ conditionKey, name, definition, verdict, required }` — all five required;
-`verdict` and `required` have no defaults.
+Each condition: `{ conditionKey, name, definition, verdict, required, exit, clock, closes }` —
+all eight required, no defaults. The conditions axis saves by whole-set replacement, so an omitted
+key would silently un-clock a money gate on the next unrelated edit rather than be refused.
 
 - **Clauses** compare one column: numeric/rank headers take `lt|lte|gte|gt|between`;
   classification/direction/event headers take `is|in` with the column's exact vocabulary
@@ -106,8 +114,11 @@ Each condition: `{ conditionKey, name, definition, verdict, required }` — all
   rejected, forward references are legal.
 - **Column addressing**: `{sectionKey, header}`. `sectionKey: null` is authoring sugar for a
   header unique across the whole report; a duplicated header (e.g. `ADX` in two sections) must
-  be section-qualified. To reference your own custom sections at CREATE time, mint the
-  `custom:<uuid>` sectionKey yourself and reuse it in the clauses.
+  be section-qualified. On a **CREATE you omit `sectionKey` entirely** — the server derives it
+  from the section itself, so the same submitted section yields the same key on every compile, and
+  minting a `custom:<uuid>` yourself is refused. On an UPDATE or RESTORE, send back the keys
+  `get_strategy` returned. To qualify a duplicated header, read the key from a preview's
+  `conditionColumns` or from the candidates a `CONDITION_COLUMN_AMBIGUOUS` refusal offers.
 - **Verdict**: `UP` | `DOWN` | `NEITHER` on deciding conditions, explicit `null` on building
   blocks. Declaration order is precedence: the first TRUE condition with a non-null verdict
   decides the coin's verdict. Put the more specific carrier first.
@@ -116,6 +127,48 @@ Each condition: `{ conditionKey, name, definition, verdict, required }` — all
   use it for liquidity floors, regime vetoes, and "never fight the HTF" rules.
 - Evaluation is three-valued: `UNRESOLVED` (missing input) is never collapsed to FALSE, and
   outcomes read from a still-forming bar are marked provisional.
+- **The evidence clock.** `clock: "LIVE"` reads the forming bar; `clock: "CLOSE"` reads settled
+  bars, and `closes` (1–5) is how many consecutive closed bars must read TRUE — always `1` under
+  LIVE, which has exactly one frame. A CLOSE clock is legal **only** over a header resolved from
+  the coin's own candle series at offset 0; frame-inert operands (perp-payload scalars, published
+  rolling changes, ranks, zone entities, regime labels, enrichment metrics, session scalars) are
+  refused with `CONDITION_CLOCK_OPERAND_ILLEGAL`. The remedy is a split, not a re-clock: move that
+  clause into its own LIVE condition and `conditionRef` it.
+- **The exit role.** `exit: true` makes a settled TRUE reading close open positions its verdict
+  opposes — UP exits SHORTs, DOWN exits LONGs, a `NEITHER` or `null` verdict exits both. Legal only
+  under `clock: "CLOSE"`, because an exit fired on a forming bar is an intrabar exit. Orthogonal to
+  `required`: the two act on disjoint lifecycles, pre-entry versus open.
+
+## Entry — when, and where, an entry is taken
+
+`{ trigger, confirmTf, closes, bandAtrMultiple, levelSource, levelOffsetAtrMultiple, validForBars }`
+— all seven required on every CREATE, no defaults. Replaced WHOLE on save, so an omitted key
+reverts an author's discipline silently rather than being refused.
+
+| `trigger` | What it does |
+|---|---|
+| `AT_SIGNAL` | Fire on the qualification flip, at whatever bar is on the tape. The platform's flat wall-clock entry window applies. |
+| `ON_CANDLE_CLOSE` | The flip ARMS the pair; entry is taken only after a `confirmTf` close that still reads the conditions true and has not displaced beyond the band. |
+| `STOP_THROUGH_LEVEL` | A TRIGGER order rests at the level ± offset; the exchange book is the watcher. |
+| `ON_RETEST` | A LIMIT order rests at the broken level. Not filling is a correct outcome, not a failure. |
+
+- `confirmTf` — exactly two values are legal: the strategy's own timeframe and the rung below it
+  (one only, at the ladder floor). Not the authorable main-candle set.
+- `closes` — 1–5 consecutive confirming closes. Must be `1` under any trigger but `ON_CANDLE_CLOSE`.
+- `bandAtrMultiple` — the veto width. The entry is VOIDED when the confirming close moved at or
+  beyond that many ATR against the armed verdict. Strictly `> 0` (zero voids on any adverse move,
+  which is a filter, not "off"), and at or below the platform's own entry-deviation gate — read it
+  from `get_trading_config_catalog`.
+- `levelSource` — `SWING_HIGH` | `SWING_LOW` | `BOLLINGER_UPPER` | `BOLLINGER_LOWER`, resolved once
+  at decision time.
+- `levelOffsetAtrMultiple` — 0–2, UNSIGNED. Direction is implied by the trigger and the verdict, so
+  a signed value would invert the trigger's meaning. Must be `0` under a non-level trigger.
+- `validForBars` — 1–24 of the strategy's OWN bars, not minutes: a 1h setup waiting for a retest has
+  not failed after fifteen minutes.
+
+The legality matrix runs **one way**: all seven keys are always present, so the question is never
+"is it set" but "is it set to something that MEANS anything under this trigger". Leave a dial at its
+inert value rather than setting one the platform will ignore.
 
 ## Signal weights — the scorecard is a weighted average, budget it
 

package/skills/battlegrid-strategy-studio/references/recipes.md

@@ -54,10 +54,16 @@ before any billing or LLM call:
 
 ```json
 { "conditionKey": "NO_EVENT_RISK", "name": "No liquidation tape", "verdict": null, "required": true,
+  "exit": false, "clock": "LIVE", "closes": 1,
   "definition": { "kind": "group", "op": "NOT", "members": [
     { "kind": "clause", "column": { "sectionKey": null, "header": "oiRegime" }, "op": "is", "label": "long liquidation" } ] } }
 ```
 
+All eight keys are required on every condition — `exit`, `clock` and `closes` included. `clock`
+selects the evidence frame (`LIVE` reads the forming bar, `CLOSE` reads settled bars) and `closes`
+(1–5) is how many consecutive closed bars must hold; `closes` is always `1` under `LIVE`. `exit:
+true` closes open positions the verdict opposes and is legal only under `clock: "CLOSE"`.
+
 **Quorum (N_OF).** Robust confirmation instead of a brittle ALL:
 
 ```json
@@ -72,11 +78,42 @@ directional carriers; the first TRUE carrier **in declaration order** decides
 most-specific first.
 
 **Benchmark gate.** Read regime off a `benchmarkTicker` section (all rows are the benchmark's
-values) and `conditionRef` it from every carrier — one place to flip the book risk-on/off.
+values) and `conditionRef` it from every carrier — one place to flip the book risk-on/off. Keep that
+section to indicators: crowd/session metrics and `rank` transforms are refused on a bound section
+(contract 49) — rank the coins on an ordinary section and `conditionRef` the two together.
 
 **Required-count trap.** `required: true` at `allocation: 0` on a *signal rule* is rejected
 (contract 34). A required *condition* is independent of signal weights — the two gates stack.
 
+## Entry discipline recipes
+
+The `entry` object is required on every CREATE, all seven keys, no defaults.
+
+| Intent | Object |
+|---|---|
+| Today's behaviour, unchanged | `{ "trigger": "AT_SIGNAL", "confirmTf": "<strategy tf>", "closes": 1, "bandAtrMultiple": 1.0, "levelSource": "SWING_HIGH", "levelOffsetAtrMultiple": 0, "validForBars": 4 }` |
+| Wait for the bar to close, skip a runaway | `{ "trigger": "ON_CANDLE_CLOSE", "confirmTf": "<strategy tf>", "closes": 1, "bandAtrMultiple": 1.0, … }` |
+| Two-close confirmation on the lower rung | `{ "trigger": "ON_CANDLE_CLOSE", "confirmTf": "<lower rung>", "closes": 2, "bandAtrMultiple": 0.75, … }` |
+| Break of the swing high, half an ATR through | `{ "trigger": "STOP_THROUGH_LEVEL", "levelSource": "SWING_HIGH", "levelOffsetAtrMultiple": 0.5, "validForBars": 8, "closes": 1, … }` |
+| Buy the retest of the broken level | `{ "trigger": "ON_RETEST", "levelSource": "SWING_HIGH", "levelOffsetAtrMultiple": 0, "validForBars": 12, "closes": 1, … }` |
+
+Bounds: `closes` 1–5 and `1` unless `ON_CANDLE_CLOSE`; `bandAtrMultiple` > 0 and ≤ the platform's
+`defaultMaxEntryDeviationAtrMultiple`; `levelOffsetAtrMultiple` 0–2 unsigned and `0` unless a level
+trigger; `validForBars` 1–24. `confirmTf` is the strategy timeframe or the rung below it, nothing
+else. A meaningful value under a trigger that ignores it is REFUSED, not ignored — that is
+deliberate, so a dial never silently does nothing.
+
+## Custom section shape
+
+`{ kind, sectionKey, title, benchmarkTicker, notes, columns }`. `benchmarkTicker` and
+`notes` are **required-nullable** — send explicit `null` rather than omitting them, because the
+section is rebuilt whole on save and an omitted key clears the value. **Omit `sectionKey` on a
+CREATE**: the server derives it from the section.
+
+A section carries **no `timeframe`** (48.0.0). Its relative columns resolve against the strategy
+timeframe; a column reaches any other timeframe by pinning it — `timeframe: { abs: '4h' }` on the
+column, which it could always do.
+
 ## Weight matrices (rules)
 
 **Conviction pyramid (default).** 1–2 × Critical (the thesis signals, usually `required`),
@@ -107,6 +144,10 @@ send the full replacement object. Examples validated as canonical defaults: `vol
 | Swing breakout (4h) | 0.75 – 1.75 | 2 | 1R | 1.2R, giveback 35, buffer 0.3 | off |
 | Swing trend (4h) | 1.0 – 2.5 | 2 | 1R | 1.5R, giveback 45–55, buffer 0.3 | off |
 
+Post-entry invalidation: `decisionInvalidationExitEnabled: true` closes a filled position when a
+**closed** strategy-timeframe candle finishes beyond the decision's invalidation level, reduce-only.
+Bar-close only — the protective stop still owns intrabar moves.
+
 Bounds to respect (validated): break-even trigger 0.5–2R; trailing trigger 0–2R step 0.01
 (0 = trail from entry); giveback 25–55%; buffer 0.01–1%; grace ≥ interval; stop-band floor <
 ceiling ≤ the 3×ATR structural cap; RR within the catalog's served range (0.5–3 today). Wider

package/skills/battlegrid-strategy-studio/references/tradingview-ports.md

@@ -37,8 +37,8 @@ closes while stops, trailing, and time decay keep managing the position intraday
 
 | TradingView script | Verdict | Port anchor |
 |---|---|---|
-| Squeeze Momentum [LazyBear] / TTM Squeeze | Process port (Keltner not in catalog — substitute named) | `bbWidthPct` + rank, `bollinger_squeeze`, momentum trajectory |
-| Supertrend / UT Bot Alerts | Split port: entry substitute + **native stop engine** | `EMA5_13`, `MAalign`, position-management trailing |
+| Squeeze Momentum [LazyBear] / TTM Squeeze | **Direct port** — Keltner is native | `BB_UPPER spread KC_UPPER`, `BB_LOWER spread KC_LOWER`, `bollinger_squeeze` |
+| Supertrend / UT Bot Alerts | **Direct port** for the state; flip still substituted | `ST_LINE`, `ST_DIR`, `EMA5_13` for the flip, position-management trailing |
 | Chandelier Exit | Direct port of the *mechanism* | trailing from entry (`trailingTriggerR: 0`) |
 | MACD + 200 MA filter | Direct process port | `MACD_cross`, `dist_SMA200`, `macd_bull_cross` |
 | Golden / Death Cross | Direct process port | `SMA50_SMA200_spread` + `_trend` |
@@ -46,7 +46,7 @@ closes while stops, trailing, and time decay keep managing the position intraday
 | VWAP reversion | Direct process port | `dist_VWAP`, `dist_VWAP_rank_far` |
 | Donchian / Turtle breakout | Process port (N-bar channel → swing structure) | `zone`, `dist_swingHi`, `sr_resistance_break` |
 | ICT/SMC: FVG + Order Blocks | Direct process port of the zone logic | `STRUCT_ZONES` columns + `structure_*` signals |
-| WaveTrend, QQE, Hull Suite, Ichimoku, Parabolic SAR, Keltner | **Not expressible** — say so; nearest neighbors below | — |
+| WaveTrend, QQE, Hull Suite, Ichimoku, Parabolic SAR, Keltner | **All native since contract 46.1** — port directly | `WT1`/`WT2`, `QQE_RSI_MA`/`QQE_STOP`, `HMA20`, `ICHI_*`, `PSAR`, `KC_*` |
 
 ---
 
@@ -55,7 +55,10 @@ closes while stops, trailing, and time decay keep managing the position intraday
 **Source process.** Squeeze ON while Bollinger Bands sit inside Keltner Channels (volatility
 coiled); wait; when the squeeze releases, enter in the direction of the momentum histogram.
 
-**Port.** Keltner Channels are not in the catalog, so squeeze detection substitutes
+**Port.** Keltner Channels are native (`KC_UPPER`/`KC_MID`/`KC_LOWER`), so the squeeze is the
+source's own definition: `BB_UPPER spread KC_UPPER` negative AND `BB_LOWER spread KC_LOWER`
+positive is bands-inside-Keltner. The board-relative proxy below remains serviceable but is no
+longer the only option — it substitutes
 *cross-sectional and absolute* Bollinger compression — a stricter, universe-aware read:
 `bbWidthPct_rank_lo lte 10` AND `ADX lt 20` as the `SQUEEZE_ON` building block. Momentum
 direction comes from the MACD histogram trajectory (`MACD_now gt 0` with `MACD_trend rising`
@@ -75,7 +78,10 @@ Pine script simulates with a plotted line, position management executes: enable
 `trailingTriggerR: 0` (trail from entry — the Supertrend/UT Bot behavior), `giveback` as the
 ATR-offset analog (30–40 tight like factor-2 Supertrend, 45–55 loose like factor-3), plus the
 stop band (`minStopLossAtrMultiple`/`max…`) bounding the initial distance. The *flip entry*
-has no direct equivalent (no supertrend metric) — the named substitute is a trend-state change:
+is native: `ST_DIR` carries the direction and `ST_LINE` the plotted stop. **`ST_DIR` is a
+persisting state, not a flip event** — it reads the same on every bar of a trend, so the FLIP
+itself still needs an event column beside it. The named substitute for the flip is a trend-state
+change:
 `MAalign is "bullish"` (state) with the `EMA5_13 is "Bullish"` cross event as the trigger, and
 `ma_ema_bull_cross` / `ma_ema_aligned_bull` Critical/Important-required in `rules`. Say the
 substitution out loud when presenting the strategy.
@@ -139,7 +145,8 @@ the book out of single-name traps. Rules: `ma_sma200_above` 3 required, `ma_ema_
 **Source process.** In an uptrend (close > 200 SMA), buy panic dips (RSI(2) < 10); exit fast
 (cross of the 5-period average / a few bars).
 
-**Port — named substitute.** The catalog carries no RSI(2); `RSI7` is the fastest RSI series
+**Port — named substitute.** The catalog carries `RSI14` and `RSI7` only, so there is no `RSI2`;
+`RSI7` is the fastest RSI series
 and `lte 10` on it is a rarer, deeper panic — state that trade-off rather than hiding it.
 `DIP_BUY` verdict UP = `dist_SMA200 gt 0` (ref a required `ABOVE_200`) AND `RSI7 lte 10`.
 Rules: `rsi_oversold` 3 required `{"threshold": 25}` (RSI14 gate tuned toward the fast-dip
@@ -193,22 +200,36 @@ quorum (`N_OF(2)`: `buyPres gte 0.55`, `RVOL gte 1.2`, `closeChg gt 0`). Rules:
 `structure_fvg_approach` / `structure_ob_approach` 3/2 required (their `proximityPct` params
 are the "in the zone" dial), `structure_zone_confluence` 2, `sr_at_support` 2. Stops: tight
 band (0.5–1.5 ATR) — the zone's far edge is the invalidation, and the studio places stops by
-ATR/structure natively. **Not expressible, say so:** liquidity sweeps, displacement legs,
+ATR/structure natively. **A grammar limit, not a missing metric** — a clause compares one column
+against a literal, so an ordered sequence of events has no expressible form at all: liquidity
+sweeps, displacement legs,
 killzone clocks, and Turtle-Soup false-break sequencing (ordering between events is outside
 the grammar) — offer this zone-reaction port as the nearest expressible neighbor, labelled.
 
-## Not expressible — and the honest nearest neighbor
+## Now native — do not substitute for these
 
-| Script | Missing primitive | Nearest expressible neighbor |
+WaveTrend (`WT1`/`WT2`), QQE (`QQE_RSI_MA`/`QQE_STOP`), Hull (`HMA20`), Ichimoku
+(`ICHI_CONV`/`ICHI_BASE`/`ICHI_SPAN_A`/`ICHI_SPAN_B`/`ICHI_LAG`), Parabolic SAR (`PSAR`), Keltner
+(`KC_UPPER`/`KC_MID`/`KC_LOWER`), daily pivots (`PIVOT_P`/`PIVOT_R1`–`R3`/`PIVOT_S1`–`S3`),
+Williams %R (`WILLR14`), Stochastic RSI (`STOCH_RSI14`), Bollinger boundaries
+(`BB_UPPER`/`BB_LOWER`), ADX components (`DI_PLUS`/`DI_MINUS`). All arrived with contract 46.1 —
+every one of them was listed as inexpressible in this file before it.
+
+## Not expressible — the catalog keys this needs
+
+The one section where a claim that the catalog LACKS something may live, and every row names the key
+it denies so the claim stays checkable. A claim about the grammar's SHAPE (a clause compares one
+column against a literal; `distance` rejects an `offset`) is permanent and belongs in prose above.
+A claim that a metric is absent belongs here, or nowhere.
+
+| Script / primitive | Key the catalog would need | Nearest expressible neighbour |
 |---|---|---|
-| WaveTrend [LazyBear] | WT oscillator | `STOCH_K`/`STOCH_D` zones + crosses (`stoch_*` signals) |
-| QQE / QQE MOD | smoothed-RSI ATR bands | `RSI7` trajectory + `rsi_*` signals with tuned thresholds |
-| Hull Suite | Hull MA | `EMA5/13/20` ribbon (`MAalign`, EMA spread trend) |
-| Ichimoku | cloud spans | `MAalign` + `SMA50_SMA200_spread` + `zones_htf_*` levels |
-| Parabolic SAR | SAR dots | trailing stop from entry (`trailingTriggerR: 0`) |
-| Keltner Channels | ATR envelope | `bbWidthPct` compression + `atrPct` band logic |
-| Pivot Points (daily) | session pivots | `VWAP` + `swingHi`/`swingLo` distances |
-| Previous-day / previous-week high-low (PDH/PDL) | offset-able levels (`distance` takes no `offset`; clauses are column-vs-literal) | daily swing structure: `zone_1d is "breakout high"`, `dist_swingHi_1d` / `dist_swingLo_1d` |
+| RSI-2 (Connors) | `RSI2` | `RSI7 lte 10` as a named fast-dip substitute |
+
+**PDH/PDL** stays inexpressible for a different reason, and the distinction matters: `distance`
+rejects an `offset` and a clause never compares two columns, so the *grammar* has no form for it.
+No metric would fix that. Use the daily swing structure (`zone_1d`, `dist_swingHi_1d`) and name the
+substitution.
 
 Never compile a "port" of these under the source's name without the substitution note — a
 player who asked for WaveTrend and silently got Stochastic has no way to learn otherwise.