# Trader-MCP Hermes Compatibility TODO

This file is the structured upgrade plan for preparing `trader-mcp` for `hermes-mcp` supervision.

See also:
- `Hermes_Trader_Contract_v0.1.md`
- `Hermes_Compatibility_Plan.md`
- `Strategy_Runtime.md`
- `Strategy_Contract.md`
- `../hermes-mcp/hermes.md`
- `../hermes-mcp/hermes_and_strategies.md`

## Guiding rule

Trader-MCP concerns strategy behavior and the surfaces strategies must expose.
Hermes decides the market story and the active control stance.

## 1. Contract first
- Freeze the Hermes ⇄ Trader contract before adding new strategy behavior.
- Make all control verbs explicit and schema-validated.
- Keep every request and response machine readable.
- Require `decision_id`, `reason`, and `confidence` for Hermes control decisions.
- Require Trader to return a structured applied-result record.

## 2. Canonical strategy taxonomy
Reduce the strategy set to a small, orthogonal registry.
Treat parameter variants as modes inside a strategy, not separate strategies.

Canonical set:
- `idle`
- `defensive`
- `trend_following`
- `mean_reversion`
- `grid`
- `breakout`
- `event_driven`

Rules:
- Remove or fold redundant strategy names that differ only by tuning.
- Keep names human-readable and stable.
- Preserve a single conceptual strategy per regime.

## 3. Strategy metadata
Every strategy must declare:
- `expects`
- `avoids`
- `risk_profile`
- `capabilities`

The natural habitat fields should cover:
- trend
- volatility
- event risk
- liquidity

Example capability declaration:
```json
{
  "name": "mean_reversion",
  "capabilities": ["fade_extremes", "range_entry", "range_exit"],
  "expects": {
    "trend": "none",
    "volatility": "low",
    "event_risk": "low",
    "liquidity": "normal"
  },
  "avoids": {
    "trend": "strong",
    "volatility": "expanding",
    "event_risk": "high",
    "liquidity": "thin"
  },
  "risk_profile": "medium"
}
```

## 4. Strategy surface
Expose clean strategy state.
Each strategy should provide:
- `status`
- `recent_changes`
- `decision_history`
- `render_state`
- `risk_state`
- `execution_state`

Preferred additions:
- `confidence`
- `uncertainty`
- `last_transition`
- `last_error`

## 5. Trader surface for Hermes
Refactor the MCP tools toward Hermes usefulness.

Priority read tools:
- `list_strategies`
- `get_strategy`
- `get_runtime_state`
- `get_recent_changes`
- `get_decision_history`
- `get_execution_state`

Priority control tools:
- `apply_control_decision`
- `switch_strategy`
- `set_risk_mode`
- `pause_strategy`
- `resume_strategy`
- `reconcile_state`

## 6. Switching policy
Prevent flip-flopping.

Add:
- confidence threshold
- minimum hold time
- hysteresis
- explicit emergency override path
- degraded execution fallback

## 7. Ownership boundaries

### Strategy owns
- local logic
- local state
- local config
- own render output
- 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
- enable / disable / switch decisions
- risk-mode changes
- uncertainty and confidence weighting
- regime interpretation
- execution-degradation-driven downranking

## 8. First strategies to implement
Implement in this order:
1. `idle`
2. `defensive`
3. `trend_following`
4. `mean_reversion`
5. `grid`
6. `breakout`
7. `event_driven`

Notes:
- `idle` and `defensive` are safety exits.
- `trend_following` and `mean_reversion` are the first core alpha strategies.
- `grid` is structure-based, not signal-based.
- `breakout` is separate from trend-following.
- `event_driven` should remain explicit and temporary in behavior.

## 9. Stepwise upgrade path toward Hermes compatibility
### Phase 0, document the contract
- write `Hermes_Trader_Contract_v0.1.md`
- agree the control verbs
- agree the request/response schemas

### Phase 1, normalize the registry
- fold redundant strategy names
- mark parameter variants as modes
- add metadata to current strategies

### Phase 2, expose Hermes-facing inspection tools
- add the read tools listed above
- ensure dashboard and API agree

### Phase 3, add control tools
- add the control tools listed above
- validate every transition
- log the reason for every decision

### Phase 4, implement switching safety
- confidence threshold
- hold time
- hysteresis
- emergency override
- degraded execution fallback

### Phase 5, implement the initial strategy set
- `idle`
- `defensive`
- `trend_following`
- `mean_reversion`

### Phase 6, add structure strategies
- `grid`
- `breakout`

### Phase 7, add event-aware behavior
- `event_driven`
- event-risk metadata
- event-pressure aware selection

### Phase 8, feed back execution quality
- fills
- slippage
- latency
- rejected orders
- venue stress
- partial fill patterns
- degraded connectivity

### Phase 9, tighten dashboards and audit trails
- current strategy view
- why-active view
- recent changes timeline
- Hermes decision trace
- execution state panel

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

## 11. Cleanup and simplification
- Separate signal-based strategies from structure-based ones, especially `mean_reversion` vs `grid`.
- Avoid adding micro-strategies until the minimal taxonomy is stable.
- Keep strategy names human-readable and stable.

## 12. Current 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. implement `idle` and `defensive`
9. implement `trend_following` and `mean_reversion`
10. add `grid`, `breakout`, and `event_driven`
11. wire execution feedback into selection
12. polish dashboard and traceability