docs/CONTRIBUTING.md

Contributing

Change policy

• Work from the current repository implementation, not old loose reference files.
• Keep API changes additive and backward-compatible.
• Keep the existing Hermes application and port 7860.
• Prefer focused changes with explicit ownership boundaries.
• Do not accept “implemented” without code review, tests, and deployed evidence.

Coding style

Python configuration:

Python target: 3.10+
line length: 120
formatter: Black
lint: Ruff

The runtime image currently uses a newer Python version, but overlay code should remain compatible with the configured project target unless deliberately changed.

Module ownership

• Acquisition/normalization/provenance: dual_datasource_client.py.
• Binance-only HTTP/normalization: binance_public_client.py.
• Signal/plan orchestration: trade_cycle.py.
• Risk formulas: risk.py.
• Execution behavior: futures_execution.py.
• Bounded dashboard memory: state.py.
• HTTP contracts/runtime diagnostics: futures_dashboard_api.py.
• Visual/UI behavior: Luxury template.
• Webhook-only Telegram: telegram_bot.py.
• Overlay installation/process startup: sync_hf.py.

Do not duplicate logic across layers.

Adding a field

1. Define the legitimate source and authority.
2. Add narrow normalization aliases.
3. Add field validity rules.
4. Preserve source, provider timestamp, freshness, and fallback status.
5. Add the field to public bounded metadata only if safe.
6. Add additive API output.
7. Render missing value as Unavailable.
8. Add focused tests.

Changing deterministic logic

A change to score thresholds, weights, SL/TP, leverage, risk profile, sizing, slippage threshold, or expiry is safety-sensitive. The pull request must include:

• motivation;
• before/after behavior;
• test coverage;
• risk analysis;
• confirmation that DS4 authority and guard behavior remain intact;
• production verification plan.

Frontend contributions

• Keep a single template and existing route.
• Avoid duplicate DOM IDs.
• Avoid undefined CSS variables.
• Preserve keyboard accessibility and reduced motion.
• Never add a second Execute path or an execution shortcut.
• Do not trust localStorage for plan authorization.
• Keep raw errors out of primary cards.

Commit hygiene

Do not stage:

.env
credentials
cookies
tokens
.runtime_audit/
__pycache__/
*.pyc
cache files
runtime state
screenshots with secrets
ZIP packages
temporary probes

Pull request checklist

• Scope is focused.
• No architecture duplication.
• No deterministic guard weakened.
• Source attribution remains correct.
• Missing/stale data fails closed.
• Diagnostics are sanitized.
• API is additive.
• Static checks pass.
• Focused tests pass.
• Futures regression suite ran once.
• Deployment audit/browser plan is documented.
• No trade will be executed during verification.