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