ruflo/plugins/ruflo-neural-trader/docs/adrs/0001-neural-trader-contract.md at main

admin/ruflo

0 Fork 0

mirror of https://github.com/ruvnet/ruflo.git synced 2026-10-23 03:47:00 +09:00

Files

T

ruv 8d9e20f0c6 fix(neural-trader): #2068 ADR-126 Phase 1 — canonical 5-namespace alignment (was bug)

Resolves the three-way namespace mismatch surfaced by the ADR-126 dossier:
- README.md L198-205 previously claimed 4 (-strategies/-backtests/-risk/-analysis)
- docs/adrs/0001 L63 previously claimed 4 (-backtests/-risk/-signals/-models)
- skills/trader-signal/SKILL.md L35 actually writes to `trading-signals`
- skills/trader-train/SKILL.md L28 actually writes to `trading-models`

The smoke test previously validated only the README's four, so signal data
silently landed in `trading-signals` (undeclared) and model results landed
in `trading-models` (undeclared), invisible to any downstream consumer
scoped to the documented namespace surface.

Aligns README, ADR-0001, smoke.sh, and trader-train on the canonical 5
defined by ADR-126 Phase 1:

  trading-strategies   — strategy definitions, parameters, regime mappings
  trading-backtests    — backtest results (long-lived; signed in Phase 4)
  trading-risk         — risk model state, VaR/CVaR, circuit-breaker triggers
  trading-analysis     — regime classifications + model-training results
  trading-signals      — short-lived signal events (TTL in Phase 2)

trader-train now stores model results to `trading-analysis` (was the
undeclared `trading-models`). smoke.sh check 8 now asserts the fifth
namespace claim. All 11 smoke checks still pass.

Refs #2068

Co-Authored-By: RuFlo <ruv@ruv.net>

2026-05-19 21:57:26 -04:00

3.7 KiB

Raw Permalink Blame History

id, title, status, date, updated, authors, tags

title

status

date

updated

authors

Context

ruflo-neural-trader (v0.2.0) — neural trading via npx neural-trader (Rust/NAPI bindings, 112+ MCP tools, 8-19x faster than Python). 4 agents + 6 skills + 1 command.

Namespace audit — canonical 5-namespace set

Five namespaces in use, all kebab-case <plugin-stem>-<intent> compliant per ruflo-agentdb ADR-0001 §"Namespace convention". The canonical set is defined by ADR-126 Phase 1:

trading-strategies — strategy definitions, parameters, regime-condition mappings
trading-backtests — historical backtest results (long-lived; signed in ADR-126 Phase 4)
trading-risk — risk model state, VaR/CVaR snapshots, circuit-breaker triggers
trading-analysis — market-analyst output (regime classifications, technical-indicator summaries, model-training results)
trading-signals — short-lived signal events (intraday; TTL applied in ADR-126 Phase 2)

Note: namespace prefix is trading- (not neural-trader-) for ergonomic tightness — the trading concern is the actual intent. This is consistent with the convention's <plugin-stem>-<intent> form interpreted broadly (the plugin's primary concern is trading).

All access via memory_* (namespace-routed) — no bugs found.

Other gaps

No plugin-level ADR.
No smoke test.
No Compatibility section.

Decision

Add this ADR (Proposed).
README augment: Compatibility (pin v3.6 + neural-trader runtime); Namespace coordination block claiming the four namespaces; Verification + Architecture Decisions sections.
Plugin metadata stays at 0.2.0 (already at the cadence). Keywords add neural-trader-runtime, walk-forward, monte-carlo.
scripts/smoke.sh — 11 structural checks: version + new keywords; all 6 skills + 4 agents + 1 command with valid frontmatter; v3.6 pin; namespace coordination; 4 namespace claims; backtesting features documented (walk-forward, Monte Carlo, parameter optimization); ADR Proposed; no wildcard tools.

Consequences

Positive: plugin joins the cadence. The namespace-prefix design choice (trading- not neural-trader-) is now contractually documented as a deliberate ergonomic call.

Negative: none material.

Verification

bash plugins/ruflo-neural-trader/scripts/smoke.sh
# Expected: "11 passed, 0 failed"

plugins/ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md — namespace convention
plugins/ruflo-market-data/docs/adrs/0001-market-data-contract.md — feeds OHLCV data into trader
plugins/ruflo-cost-tracker/docs/adrs/0001-cost-tracker-contract.md — PnL + cost attribution downstream

Implementation status

Plugin version v0.2.0 shipped and listed in marketplace.json. Source exists at plugins/ruflo-neural-trader/. Contract elements implemented: all 5 namespaces (trading-strategies, trading-backtests, trading-risk, trading-analysis, trading-signals) compliant with kebab-case <plugin-stem>-<intent> convention per ADR-126 Phase 1 (was previously documented as 4, with a three-way mismatch between README, this ADR, and the trader-signal skill — fixed in ADR-126 Phase 1); 4 agents + 7 skills shipped; smoke-as-contract gate defined in scripts/smoke.sh (11 checks, fifth-namespace assertion added in ADR-126 Phase 1).

3.7 KiB Raw Permalink Blame History