docs/agent_team/rules.md

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.