# 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.