create-tradejs 3.1.22 → 3.1.23

package/dist/skill-bundle/.codex/skills/ai-train-local-research/references/gate-ablation.md

@@ -0,0 +1,324 @@
+# AI Gate Ablation Tool
+
+Use `scripts/ai-gate-ablation.mjs` for repeatable deterministic gate hypothesis
+checks. It streams every shard in a merged export, reconstructs the current AI
+payload and local gate, and evaluates causal feature expressions without using
+trade outcome fields as inputs.
+
+## Prerequisite
+
+Keep three roots explicit:
+
+- `PROJECT_CWD` owns datasets and reports.
+- `TRADEJS_SOURCE_REPOSITORY_ROOT` is the exact Git checkout that owns the
+  researched lineage: either the TradeJS framework or one standalone strategy.
+- `TRADEJS_FRAMEWORK_REPOSITORY_ROOT` supplies the built `@tradejs/node` and
+  `@tradejs/cli` research runtime. It is optional only when the source root is
+  itself the framework checkout.
+
+After adapter or gate changes, build the owning standalone strategy in its
+source checkout. Build framework packages only in the framework checkout when
+their sources changed:
+
+```bash
+cd "$TRADEJS_SOURCE_REPOSITORY_ROOT" && yarn build
+cd "$TRADEJS_FRAMEWORK_REPOSITORY_ROOT" && \
+  yarn workspace @tradejs/node build && \
+  yarn workspace @tradejs/cli build
+```
+
+The ablation tool imports `strategyEntries` from the standalone strategy build
+when the source root is a strategy. It never substitutes the Project's
+published strategy package for that source lineage. `--list` is inventory-only
+and does not require either source root.
+
+`yarn ai-train --localOnly --json -n 0` remains the baseline authority. Before
+interpreting a candidate, compare the tool's baseline qN+ support, PnL, PF,
+max drawdown, strict loss, and loss streak with the matching `ai-train` run.
+
+## Dataset Discovery
+
+List all merged groups or only one strategy:
+
+```bash
+node .codex/skills/ai-train-local-research/scripts/ai-gate-ablation.mjs --list
+node .codex/skills/ai-train-local-research/scripts/ai-gate-ablation.mjs --list --strategy LiquidityTails
+```
+
+`--strategy` selects the latest matching merge. `--file` accepts any shard and
+automatically resolves all sibling shards with the same strategy token and
+merge id.
+
+## Variants
+
+Pass each hypothesis as:
+
+```text
+name::mode[@quality][LONG|SHORT]::expression
+```
+
+Modes:
+
+- `filter`: keep current qN+ approvals that match the expression.
+- `exclude`: keep current qN+ approvals that do not match the expression.
+- `add`: keep baseline approvals and add matching rejected rows at the optional
+  assigned quality.
+- `replace`: ignore the current gate and approve only matching rows at the
+  optional assigned quality.
+
+Append `[LONG]` or `[SHORT]` to scope a variant to one direction. Rows from the
+other direction retain the current gate decision. Use this for release
+side-rescue studies instead of encoding direction through an unrelated feature.
+Use the literal expression `true` for an explicit direction-scoped pass-through.
+For a single replacement policy with different rules per side, use the causal
+metadata feature `derived.direction` in the expression.
+
+When `@quality` is omitted, `add` and `replace` use `--minQuality`.
+
+Example:
+
+```bash
+node .codex/skills/ai-train-local-research/scripts/ai-gate-ablation.mjs \
+  --file data/ai/export/ai-dataset-liquiditytails-merged-1784296244106-part1.jsonl \
+  --variant 'near-ma-and-zone::filter::additionalIndicators.baseContext.regime.trend.priceDistanceToMaSlowAtr <= 1.2 && additionalIndicators.baseContext.structure.liquidityZones.activeCount >= 1' \
+  --featurePattern 'priceDistanceToMaSlowAtr|liquidityZones.activeCount' \
+  --validationSplit 0.2 \
+  --testSplit 0.2 \
+  --output data/ai/output/liquiditytails-near-ma-and-zone.md
+```
+
+Direction-aware repair example:
+
+```text
+short-rescue::add@4[SHORT]::additionalIndicators.baseContext.structure.zones.resistance.ageBars <= 42
+short-pass-through::add@4[SHORT]::true
+direction-aware::replace@4::(derived.direction == LONG && derived.stopDistanceBps <= 465) || (derived.direction == SHORT && structure.pivots.barsSinceSwingHigh <= 47)
+```
+
+Repeat `--variant` to compare several rules in one dataset pass. For a reusable
+set, pass `--spec path/to/variants.json`:
+
+```json
+{
+  "variants": [
+    {
+      "name": "body-065",
+      "mode": "filter",
+      "expression": "additionalIndicators.baseContext.regime.momentum.bodyStrength >= 0.65"
+    },
+    {
+      "name": "q3-recovery",
+      "mode": "add",
+      "quality": 4,
+      "expression": "additionalIndicators.liquidityTailsContext.oldP2CorrelationDirection == LONG"
+    }
+  ]
+}
+```
+
+## Expression Grammar
+
+Expressions support parentheses, `&&`, `||`, and comparisons:
+
+```text
+<=  >=  <  >  ==  !=
+```
+
+Values can be numbers, booleans, `null`, quoted strings, or unquoted enum-like
+strings such as `LONG`, `high`, and `aligned`. Missing features never match a
+predicate, including `!=`; test availability separately through the feature
+inventory instead of treating missing data as approval evidence.
+
+The shared pocket feature collector also exposes causal signal-risk distances
+computed from the requested signal prices:
+
+- `derived.stopDistanceBps`
+- `derived.takeProfitDistanceBps`
+
+Both are absolute distances from `signal.prices.currentPrice` in basis points.
+They describe the signal-time order plan and do not use execution or outcome
+fields.
+
+Use `--featurePattern '<regex>'` to print matching causal paths, availability,
+ranges, and categories. Do not use `--includeGateContext` for discovery; it is
+only for auditing current gate output fields.
+
+For direction-specific discovery, use `yarn ai-pocket-search --direction LONG`
+or `--direction SHORT`. For release evidence reserve an untouched chronological
+tail with `--testSplit ... --sealTest`; the search ranks pockets using only the
+preceding train and validation rows and reports only the sealed test bounds.
+Plain `--testSplit` exposes test metrics and cannot be called untouched after
+the report is read. Open the sealed tail once with the frozen fixed-rule
+ablation.
+
+## Cross-Strategy Feasibility
+
+Use `--crossStrategy` to test whether the latest merged export for every
+available strategy contains shared LONG or SHORT approval/block pockets:
+
+```bash
+node .codex/skills/ai-train-local-research/scripts/ai-gate-ablation.mjs \
+  --crossStrategy \
+  --validationSplit 0.2 \
+  --testSplit 0.2 \
+  --portfolioCapacity 5 \
+  --output data/ai/output/cross-strategy-shared-pockets.md
+```
+
+This mode intentionally does not reconstruct current strategy gates. It reads
+the causal payload snapshots saved in the exports and classifies every supported
+`additionalIndicators.baseContext` primitive by provenance. It runs two
+independent searches:
+
+- `universal` — normalized target/setup state such as ATR/BPS distances,
+  ratios, ranks, target-relative state, structure events, and directional
+  derivatives;
+- `benchmarkReference` — normalized BTC/ETH/reference/global state, including
+  causal `derivatives.referenceContexts` OI changes, funding z-scores,
+  liquidation imbalance/spike ratios, pressure/divergence, breadth, and CMC
+  regimes.
+
+Top-level `baseContext.derivatives` is the primary BTC benchmark. Only
+`targetContext` / `targetDerived` is target derivatives evidence. Never relabel
+a configured `referenceContexts.<symbol>` branch as target evidence merely
+because the symbol happens to match a traded target.
+
+The mode:
+
+- selects the latest merge independently for each strategy;
+- restricts every strategy to their common chronological overlap;
+- keeps each decision timestamp wholly in global train, tuning, or held-out
+  historical test;
+- determines the eligible feature universe from train only, so tuning/test
+  availability cannot select a feature;
+- requires a feature to cover at least `--minFeatureStrategies` strategies;
+- uses `--minFeatureCoverage` for the universal profile (default `0.5`) and
+  `--minBenchmarkFeatureCoverage` for partial benchmark/reference history
+  (default `0.1`);
+- balances discovery with `--maxRowsPerStrategy` and
+  `--maxRowsPerEvent` caps;
+- builds each benchmark/reference snapshot by taking within-strategy consensus
+  first and then consensus across strategies, so symbol fan-out cannot outvote
+  other strategies;
+- deduplicates benchmark/reference discovery to one timestamp-direction event,
+  scores macro-average normalized LU across strategies, and applies that same
+  event snapshot to every signal row during acceptance evaluation;
+- searches LONG and SHORT separately for both profitable approval slices and
+  losing block slices;
+- normalizes search PnL by each strategy's median absolute train loss, so one
+  strategy's currency scale cannot dominate;
+- reports per-strategy historical-test behavior, strategy/symbol/event
+  concentration, temporal stability, benchmark snapshot consistency, and five
+  deterministic fixed-pocket circular-shift diagnostics that rotate whole
+  strategy/timestamp outcome blocks rather than individual signal rows;
+- requires a shared pocket to have support in at least 60% of the configured
+  feature-strategy floor (minimum 5, capped by available strategies), with the
+  expected sign in at least 60% of those strategies in every partition;
+- rejects approval pockets whose maximum simultaneous batch exceeds
+  `--portfolioCapacity` (default `5`) in train, tuning, or historical test, and
+  applies symbol concentration checks to all three partitions;
+- accepts a block hypothesis only when the blocked slice is at most 80% of the
+  flow and its kept complement improves LU/event and PF in train, tuning, and
+  historical test.
+
+The report does not silently drop the disputed fields. It emits separate audit
+buckets:
+
+- `dataQuality` — `stale`, availability, coverage, points, rows, and calculation
+  history. These fields can make a market feature ineligible, but never approve
+  a trade or act as bearish market evidence by themselves;
+- `rawNonstationary` — absolute price/OI/liquidation/volume/market-cap/notional
+  levels and raw-unit slopes. They remain visible with the required causal
+  transform (return, BPS/ATR distance, pct-change, ratio, share, or z-score),
+  but absolute pooled thresholds are not searched;
+- `derivedPolicy` — existing gate scores, risks, confirmations/conflicts, and
+  decision hints. They are causal but excluded from discovery to avoid merely
+  rediscovering the current hard-coded heuristic;
+- `metadata` — source, provider, symbol, interval, and universe lineage.
+
+Do not calculate rolling normalizations from the sparse export signal rows.
+Such features must be produced at signal time from the full causal market
+history and exported, or discovery/inference parity is broken.
+
+## Moving-average grid study
+
+Use the dedicated mode when an export needs a causal SMA/EMA/WMA comparison:
+
+```bash
+node .codex/skills/ai-train-local-research/scripts/ai-gate-ablation.mjs \
+  --strategy LiquidityTails \
+  --movingAverageStudy \
+  --maPeriods 5,10,15,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100 \
+  --validationSplit 0.2 \
+  --testSplit 0.2 \
+  --json \
+  --output data/ai/output/liquiditytails-ma-grid.json
+```
+
+This mode never rolls over sparse signal rows. It loads closed candles from
+Timescale for the export's provider and interval, bounded at each signal
+timestamp, and calculates:
+
+- SMA, finite-history EMA, and WMA for every requested period;
+- direction-normalized price distance in ATR units;
+- direction-normalized five-bar average slope in ATR units;
+- current-gate filters for direction-side and direction-side-plus-slope;
+- a standalone side-plus-slope negative/control comparison.
+
+`--maLookbackBars` controls the finite EMA history (default `600`). The JSON
+report includes the residual decay at the longest requested period and parity
+against exported SMA14/49/50. Do not interpret the study when candle coverage
+or parity is incomplete. Candidate ranking uses train and tuning only; the
+timestamp-grouped test tail is reported after selection and remains exposed
+historical evidence after the first run.
+
+`--crossStrategy` requires positive `--validationSplit` and `--testSplit`.
+Opening the historical test tail makes it exposed evidence. Re-running the tool
+on the same cutoff does not make it untouched again. Every candidate remains
+research-only until the exact frozen rule survives timestamps strictly after
+the report cutoff and live-env lineage validation. The five shifts are
+fixed-pocket diagnostics, not a family-wise permutation test. Cross-strategy LU
+metrics are discovery units, not qN+ gate metrics or production PnL.
+
+## Report Contract
+
+Every report contains:
+
+- baseline and candidate tables for full history, `180d`, `90d`, `30d`, `7d`;
+- q3+/q4+/q5+ summaries, configurable with `--qualityThresholds`;
+- timestamp-grouped, time-ordered train/tuning/untouched-test splits;
+- direction and monthly stability;
+- matched, removed, and added slices;
+- PnL, winrate, PF, Sharpe, Sortino, Calmar, max drawdown, DD ratios, strict
+  loss, max loss streak, losing months, cadence, and symbol concentration.
+- decision-event cadence, active-day share, trades per event, p95/max batch,
+  top-event concentration, and capacity stress at caps `1,3,5`.
+
+The JSON report also carries average trade, payoff ratio, recovery factor,
+ulcer index, profit per day/month, cadence per week, and risk-adjusted ratios.
+Use `--json` or an `.json` output path when downstream analysis needs those
+fields.
+
+Use `--maxLossValue` to turn batch capacity into maximum simultaneous stop-risk
+only after resolving the historical effective `MAX_LOSS_VALUE` for the
+backtest that produced the export. Prefer a config snapshot embedded in the
+export or the archived checkpoint addressed by `backtestRunId` and
+`backtestTestKey`. The current named Redis config, current strategy default,
+and current production value are not valid substitutes without matching
+lineage. Omit `--maxLossValue` and report stop-risk as `n/a` when the historical
+value is unavailable. Set `--capacities` when the intended portfolio cap is
+known; otherwise keep the default `1,3,5` stress grid. Timestamp groups are
+never split between train/tuning/test.
+
+## Maintenance Rule
+
+Do not create another `/tmp` parser, heredoc ESM replay, or strategy-specific
+one-off script for capabilities that belong here. Extend this script and its
+`node:test` coverage, then update this reference and `SKILL.md` when the
+research contract changes.
+
+Run the tool tests after every change:
+
+```bash
+node --test .codex/skills/ai-train-local-research/scripts/ai-gate-ablation.test.mjs
+```

package/dist/skill-bundle/.codex/skills/ai-train-local-research/references/reporting.md

@@ -0,0 +1,227 @@
+# AI-gate reporting contract
+
+Use this contract for every user-facing AI-gate metrics report and every dated
+AI-gate notes entry. The goal is that repeated runs remain directly comparable.
+
+## Contents
+
+1. Chat report contract
+2. Metric definitions
+3. Formatting rules
+4. Notes contract
+
+## Chat report contract
+
+Use the exact section order and column names below. Do not replace required
+tables with prose. Use `current` for a single gate, `before` / `after` for a
+change, and `baseline` / `pocket-only` / `final` for an ablation.
+
+An explicitly narrow question such as "what is 7d cadence?" may receive a
+narrow answer. Otherwise, use the full contract.
+
+Reserve metric tables for the final report. Intermediate progress updates
+should describe status without ad hoc metric summaries unless the user
+explicitly asks for preliminary numbers.
+
+### 1. Header and lineage
+
+```md
+## <Strategy> — AI gate report (`qN+`)
+
+Decision: `<implement|observe|research-only|rollback|blocked>` — <one sentence>.
+
+Dataset: `<merge_id>` (`<part_count>` parts), rows `<rows>`, `<min_ts>` .. `<max_ts>`, lag `<data_lag_days>d`.
+Lineage: git `<sha>< dirty marker>`, gate `<gate_fingerprint>`, config `<config_ids_fingerprint>`, context `<context_fingerprint>`, `AI_MODE=<mode>`, `MIN_AI_QUALITY=<n>`, `DIRECTION_POLICY=<both|long_only|short_only|direction_aware>`.
+Runtime comparison: `<comparable|different experiment|not checked>` — <one sentence>.
+```
+
+### 2. Outcome and tail risk
+
+Always include `full`, `180d`, `90d`, `30d`, and `7d`, in that order. Keep a
+row with zero approvals. In a comparison, put all gate rows for a window next
+to each other before moving to the next window.
+
+```md
+### Outcome and tail risk
+
+| Window | Gate |   N |  WR |  PF | PnL | PnL/trade | MaxDD | Loss streak | Losing months |
+| ------ | ---- | --: | --: | --: | --: | --------: | ----: | ----------: | ------------- |
+```
+
+### 3. Cadence and fan-out
+
+Use the same windows and gate-row order as the outcome table.
+
+```md
+### Cadence and fan-out
+
+| Window | Gate | Trades/day | Events/day | Active days | Events | Trades/event | p95 batch | Max batch | Top event count | Top event PnL |
+| ------ | ---- | ---------: | ---------: | ----------: | -----: | -----------: | --------: | --------: | --------------: | ------------: |
+```
+
+### 4. Risk-adjusted metrics
+
+Use the same windows and gate-row order. Do not omit unavailable ratios.
+
+```md
+### Risk-adjusted metrics
+
+| Window | Gate | Sharpe | Sortino | Calmar | DD/gross | DD/PnL | Profit/day | Profit/month | Trades/week |
+| ------ | ---- | -----: | ------: | -----: | -------: | -----: | ---------: | -----------: | ----------: |
+```
+
+### 5. Quality and direction
+
+Use rows `qN+ total`, `q(N+1)+`, `LONG qN+`, and `SHORT qN+`, in that order.
+When `N=5`, keep `q(N+1)+` as `n/a`.
+
+For `long_only` or `short_only`, retain the suppressed direction as an explicit
+zero-approval row. The raw-core direction metrics belong beside the approved
+table in release research; never omit the losing or blocked counterfactual.
+
+```md
+### Quality and direction
+
+| Slice | Gate |   N | Events |  WR |  PF | PnL | MaxDD | Max batch |
+| ----- | ---- | --: | -----: | --: | --: | --: | ----: | --------: |
+```
+
+### 6. Runtime execution bridge
+
+Keep gate approvals, submitted orders, and filled trades distinct. When runtime
+or exchange evidence is outside the task, keep one row of `n/a` values instead
+of implying that every approval filled.
+
+```md
+### Runtime execution bridge
+
+| Scope | Window | Approved | Attempts | Filled | Balance rejects | Other rejects | Requested notional | Max simultaneous stop-risk |
+| ----- | ------ | -------: | -------: | -----: | --------------: | ------------: | -----------------: | -------------------------: |
+```
+
+### 7. Validation
+
+Do not rename row-based candidate-selection output to an untouched test.
+
+```md
+### Validation
+
+| Partition      | Rows | Events | Approved N |  WR |  PF | PnL | MaxDD | Max batch |
+| -------------- | ---: | -----: | ---------: | --: | --: | --: | ----: | --------: |
+| train          |      |        |            |     |     |     |       |           |
+| tuning         |      |        |            |     |     |     |       |           |
+| untouched test |      |        |            |     |     |     |       |           |
+```
+
+### 8. Acceptance checks
+
+Use only `PASS`, `FAIL`, or `UNKNOWN`.
+
+```md
+### Acceptance checks
+
+| Check                     | Status | Evidence |
+| ------------------------- | ------ | -------- |
+| Freshness                 |        |          |
+| Runtime lineage parity    |        |          |
+| Independent-event support |        |          |
+| Event concentration       |        |          |
+| Portfolio capacity        |        |          |
+| Symbol concentration      |        |          |
+| Temporal stability        |        |          |
+| Untouched test            |        |          |
+```
+
+### 9. Reject reasons and conclusion
+
+Show exactly the top five terminal-30d reject reasons when threshold or pocket
+tuning is in scope. Use `n/a` rows when the artifact does not contain them.
+
+```md
+### Top reject reasons (30d)
+
+| Rank | Reason |   N | Share |
+| ---: | ------ | --: | ----: |
+
+### Conclusion
+
+- Why: <short evidence-based explanation>.
+- Residual risk: <tail, support, capacity, env, or validation gap>.
+- Next check: <specific export, replay, or live observation>.
+```
+
+Put optional strategy-specific findings only after this fixed block under
+`### Strategy-specific findings`. Never reorder or rename the fixed sections.
+
+## Metric definitions
+
+- `Events`: unique decision timestamps by default. Use a broader market episode
+  only when its deterministic grouping rule is documented.
+- `Events/day`: events divided by the evaluated calendar span, using the same
+  minimum-one-day convention as `aiTrainMetrics.ts`.
+- `Active days`: percentage of evaluated calendar days with at least one
+  approved event.
+- `Trades/event`: approved trades divided by events.
+- `p95 batch` / `Max batch`: p95 and maximum approved trades sharing one event.
+- `Top event count`: largest event's percentage of approved trades.
+- `Top event PnL`: largest event's percentage of approved PnL. If total PnL is
+  zero, report `n/a`.
+- `Approved`: signals that passed the effective qN+ gate.
+- `Attempts`: order submissions, including rejected submissions.
+- `Filled`: successfully opened positions; do not call rejected attempts
+  cancelled or completed trades.
+- `Balance rejects`: attempts rejected specifically for insufficient available
+  balance.
+- `Max simultaneous stop-risk`: sum of configured per-order loss budgets in the
+  largest event, before fill/rejection effects.
+- `DD/gross` and `DD/PnL`: max drawdown divided by gross profit and total profit.
+- `PnL/trade`: total PnL divided by completed trades. The backtest CLI progress
+  `avg` is PnL per completed test/symbol and must not be used for this field.
+  Report `n/a` when `N=0`.
+- `Losing months`: count; append month ids in parentheses when non-zero.
+- `qN+`: all approvals with quality greater than or equal to `N`; never use
+  plain `qN` for this cumulative stream.
+
+## Formatting rules
+
+- Counts: integer.
+- WR, shares, active days, and drawdown percentages: one decimal plus `%`.
+- PF, Sharpe, Sortino, Calmar, PnL, PnL/trade, MaxDD, and profit rates: two decimals.
+- Trades/day, events/day, and trades/week: three decimals.
+- Trades/event and batch percentiles: two decimals.
+- Timestamps: ISO-8601 UTC.
+- Unknown or unavailable: exactly `n/a`; never use an empty cell, `null`,
+  `undefined`, `Infinity`, a dash, or a guessed zero.
+- Use `n/a` only after checking the source artifact; derive a metric from raw
+  evaluations when the data exists instead of treating a missing summary field
+  as missing evidence.
+- Zero approvals: `N=0`, `PnL=0.00`, cadence `0.000`; ratio metrics remain
+  `n/a`.
+- Use the artifact's PnL unit. Do not add `$` unless the artifact explicitly
+  establishes USD.
+- Keep the metric names, section order, window order, and rounding unchanged
+  between runs.
+
+## Notes contract
+
+Write each study to a new
+`notes/<Strategy>/YYYY-MM-DD-<short-kebab-slug>.md` file. Never append dated
+entries to a rolling strategy log. The file must first follow
+`../../strategy-backtest-research/references/research-notes.md`, including the
+resolved config and complete machine-readable metrics snapshot. Put the full
+chat report contract above under `## Reported metrics`, then append these
+sections in order when gate tuning is in scope:
+
+1. strategy intent and exact causal field paths
+2. existing gate audit with `keep`, `round`, `replace`, `disable`, or
+   `needs-more-data`
+3. live-env parity and feature provenance, including `target`, `benchmark`, or
+   `global` scope
+4. walk-forward evidence, symbol/event concentration, ablation, and negative
+   control
+5. raw and rounded thresholds, sensitivity, and boundary tests
+6. rollout, old-gate cleanup, and remaining production blockers
+
+Use migrated `notes/<Strategy>/*.md` files only as historical content
+references. The shared research-note contract and this reporting contract, not
+their legacy body formatting, control new records.