trader-mcp/Hermes_Compatibility_Plan.md

Trader-MCP Hermes Compatibility Plan

This file turns TODO.md into a stepwise upgrade path toward hermes-mcp compatibility.

Goal

Prepare trader-mcp so Hermes can supervise strategy selection, risk posture, and switching without collapsing Trader into a monolith.

Trader should remain:

• strategy runtime
• execution feedback surface
• operator dashboard
• persistence owner for strategy state

Hermes should remain:

• selector
• supervisor
• regime interpreter
• switch/risk controller

Core design principles

1. Small interfaces.
2. Explicit ownership.
3. Human-readable strategy names.
4. Structured state over vibes.
5. Stable switch semantics.
6. Contract-first development.
7. Tests before expansion.

Canonical strategy set

The current Hermes-compatible primary set is:

• grid_trader
• trend_follower
• exposure_protector

Strategy ordering priority

1. grid_trader
2. trend_follower
3. exposure_protector

This is not a quality ranking. It is a sequencing plan for implementation and testing.

Ownership boundaries

Strategy owns

• its local logic
• its local state
• its local config
• its own render output
• its own explanation string

Trader runtime owns

• lifecycle
• persistence
• snapshots
• reconciliation
• dashboard presentation
• execution plumbing

Human observer owns

• inspection
• approval where configured
• operational overrides where explicitly allowed
• debugging and review

Hermes owns

• strategy enable/disable/switch decisions
• risk-mode changes
• uncertainty and confidence weighting
• regime interpretation
• execution-degradation-driven downranking

Upgrade phases

Phase 0, document the contract

Deliverables:

• Hermes_Trader_Contract_v0.1.md
• agreed strategy taxonomy
• agreed state and decision fields
• agreed control verbs

Acceptance criteria:

• every strategy has expects, avoids, and risk_profile
• Hermes request and Trader response shapes are machine readable
• no contract depends on hidden state

Phase 1, normalize the strategy registry

Deliverables:

• fold redundant names into the canonical set
• mark parameter variants as modes
• ensure strategy labels are stable and human-readable

Acceptance criteria:

• each strategy name maps to one conceptual regime
• no micro-strategy sprawl
• old names can be redirected or deprecated cleanly

Phase 2, harden the Hermes read path

Deliverables:

• list_strategies
• get_strategy
• stable report() shape

Acceptance criteria:

• Hermes can inspect state without knowing internals
• dashboard and API show the same truth
• every response is structured and auditable
• extra read tools are not added unless the canonical read path proves insufficient

Phase 3, add the Hermes action layer

Deliverables:

• apply_control_decision
• internal switch_strategy
• audit persistence for applied and rejected actions

Acceptance criteria:

• Hermes controls Trader through one canonical write entry point
• invalid or unsafe requests are rejected cleanly
• every transition records a reason and decision id
• keep remains Hermes-local and is not sent as a Trader write action

Phase 4, implement switching safety

Deliverables:

• confidence threshold
• minimum hold time
• hysteresis
• explicit emergency override path
• degraded execution fallback

Acceptance criteria:

• strategies do not flap on minor noise
• switching reasons are deterministic and testable
• defensive and idle are valid safe exits

Phase 5, implement initial strategies

Deliverables:

• grid_trader
• trend_follower
• exposure_protector

Acceptance criteria:

• each one has metadata and tests
• each one returns clear state/explanation data
• each one can be selected by Hermes-compatible contract shapes

Phase 6, add structure strategies

Deliverables:

• tighten switching semantics around real inventory pressure
• separate descriptive trader facts from Hermes decisions

Acceptance criteria:

• grid is clearly structure-based, not signal-based
• grid reports factual capacity and inventory shape, not switch advice
• tests cover the distinction

Phase 7, add event-aware behavior

Deliverables:

• event_driven
• event-risk metadata
• event-pressure aware selection logic

Acceptance criteria:

• Hermes can downrank normal strategies during event risk
• event handling remains temporary and explicit

Phase 8, feed back execution quality

Deliverables:

• fills
• slippage
• latency
• rejections
• stress
• degraded connectivity

Acceptance criteria:

• execution quality affects strategy selection
• Trader surfaces the feedback clearly
• Hermes can see why a strategy was penalized

Phase 9, tighten dashboards and audit trails

Deliverables:

• current strategy view
• why-active view
• recent changes timeline
• Hermes decision trace
• execution state panel

Acceptance criteria:

• a human can understand the system without reading code
• transitions are explainable from the UI

Tests to add

Contract tests

• strategy metadata validation
• Hermes request schema validation
• Trader response schema validation
• control verb validation

Runtime tests

• load/unload/switch transitions
• state snapshot and restore
• minimum hold enforcement
• hysteresis enforcement
• defensive fallback on degraded execution

Strategy tests

• expected regime matching
• avoided regime rejection
• deterministic state transitions
• readable explanation output

Integration tests

• Hermes decision to Trader control path
• Trader response parsing
• execution feedback influencing future selection

Suggested first implementation order

1. lock the contract paper
2. canonicalize the strategy registry
3. add metadata to current strategies
4. add validation tests
5. implement the inspection tools
6. implement the control tools
7. add switching safety
8. tighten supervision semantics on current strategies
9. wire execution feedback into selection
10. polish dashboard and traceability

Notes on ownership and scope

Trader should not become a second Hermes.

If a feature answers "what should the world do?", it belongs to Hermes. If a feature answers "how do we run the chosen strategy safely?", it belongs to Trader. If a feature answers "what happened and why?", it belongs to both through a shared contract.

Output philosophy

The end state should make Trader useful to Hermes, useful to humans, and still simple enough to debug.