docs/hermes/rules.md

# Hermes Rules Layer

## Purpose

Rules define what Hermes and agent-team utilities are allowed to change. They
are guardrails for collaboration, not trading rules.

## Allowed By Default

Hermes may change or add:

- standalone notification helpers
- experiment result formatting
- W&B or local experiment tracking wrappers
- data-quality validator checks
- memory and handoff documentation
- validation smoke scripts
- tests for Hermes helper utilities

## Requires Explicit User Approval And Validation

These changes are logic-sensitive and should not be touched as part of generic
Hermes cleanup:

- `models/predictor.py` model logic, feature columns, labels, thresholds, and
  weight overlays
- `services/recommendation_service.py` recommendation scoring and BUY/SELL/HOLD
  behavior
- `services/predictor_service.py` cache publishability, precompute selection,
  and production result acceptance
- `routers/stock.py` response contract changes that affect frontend behavior
- `scripts/precompute_hot20.py`, `scripts/precompute_queried_stocks.py`, and HF
  queue publishing behavior
- `docs/validation_registry.json` promotion status

## Promotion Boundary

Hermes may propose a production logic change, but production integration must
follow this sequence:

1. Write the proposal as an experiment or plan.
2. Run no-lookahead backward validation on historical data.
3. Compare against the same-window baseline.
4. Check accuracy, BUY precision, signal count, and coverage.
5. Record JSON/HTML evidence.
6. Ask for explicit user approval before editing production logic.

## Notification Boundary

Telegram or Hermes messages should report only validated artifacts or clearly
marked experimental findings. They should not present unvalidated candidates as
BUY recommendations.

## Secret Boundary

Never commit local secrets or runtime configs:

- `.env`
- `.env.telegram`
- `.env.wandb`
- `.hf_token`