# Agent Team Rules

## Purpose

Rules define what each agent may decide independently and what requires
validation or user approval.

## Default Permissions

Agents may:

- search local docs and code
- propose factor or model candidates
- create dry-run scripts and focused tests
- generate JSON/HTML validation reports
- update documentation and compact memory notes

## Guarded Changes

These require coordinator approval, QA evidence, and explicit user approval
before production integration:

- `models/predictor.py` feature columns, thresholds, labels, and overlays
- `services/recommendation_service.py` scoring and BUY/SELL/HOLD behavior
- `services/predictor_service.py` cache publishability and production result
  acceptance
- `scripts/precompute_hot20.py` and `scripts/precompute_queried_stocks.py`
- Hugging Face publishing behavior
- Telegram daily BUY recommendation content
- `docs/validation_registry.json`

## Evidence Rules

- External survey evidence is not local proof.
- A passing unit test is not accuracy proof.
- A higher overall accuracy is not enough if BUY precision drops under
  precision-first mode.
- A higher overall accuracy is not enough if SELL precision drops under a
  protected SELL objective.  The config may be kept as `candidate_only`, but it
  must not be labeled `strict_golden`.
- A candidate that passes only on one small sample should be rerun on a larger
  stock set before integration.
- Factor weights must stay inside the documented search range.  For current
  multi-factor overlay work, that range is `0.00 <= weight <= 1.00`.
- Zero-weight factors are allowed only when the run explicitly permits them.
  Current research candidate runs allow at most 5 zero weights; strict
  all-factor participation runs require all selected weights to be non-zero.
- Optional external data factors, such as broker big-player power or manually
  exported chip scores, must remain zero/missing when the source data is
  unavailable.  Do not infer them from public OHLCV volume.
- Runtime overlay configs may use only factor names supported by
  `models/multi_factor_overlay.py`.  A search-harness factor is not
  production-adjacent until the equivalent runtime calculation exists.

## Factor Design Rules

- Prefer split factors when one aggregate mixes different trading actions:
  support bounce, support break, resistance rejection, and resistance breakout
  should be separate candidates before being recombined.
- Prefer combine or interaction factors when several highly correlated risk
  factors all push the same side.  For example, high base, high-volume upper
  shadow, bullish upper shadow, and short-term battle should be tested as a
  confirmed exhaustion cluster instead of independent SELL add-ons.
- Use gates for regime filters.  ADX, volatility regime, market breadth, and
  chop filters should usually enable/disable other factors rather than directly
  add BUY or SELL probability.
- Keep horizon-specific logic separate.  Intraday/short-term factors should not
  silently share one global weight with medium- or long-term momentum factors.
- If a factor improves accuracy by mostly increasing one class, report the
  class mix, BUY/SELL precision, and signal ratio before calling it useful.

## Conflict Resolution

When agents disagree:

1. QA correctness issues override implementation convenience.
2. No-lookahead concerns override promising metric gains.
3. User-stated metric priority overrides default gates.
4. Production safety overrides speed.