DOX sistem

AGENTS.md

@@ -1,90 +1,54 @@
 # ATM — Automated Trading Monitor
 
-Personal Faza-1 tool for the M2D strategy. Python 3.11+.
+Personal Faza-1 tool pentru strategia M2D. Python 3.11+.
+
+> Acest repo folosește **DOX**: arborele de `AGENTS.md` de mai jos sunt contracte
+> de lucru pentru subarborii lor. Înainte să editezi un path, coboară din rădăcină
+> citind fiecare `AGENTS.md` întâlnit. După o schimbare semnificativă, fă un **DOX
+> pass**: actualizează `AGENTS.md`-ul cel mai apropiat care „deține" zona + indexul
+> părintelui, șterge ce devine învechit.
 
 ## Quick Reference
 
 ```bash
 pip install -e ".[windows]"    # Windows: live capture
-pip install -e ".[dev]"        # Linux/macOS: dev + tests (WSL: create venv first)
+pip install -e ".[dev]"        # Linux/macOS: dev + tests (WSL: venv întâi)
 cp .env.example .env           # secretele Discord/Telegram (vezi README §Secrets)
 atm calibrate                  # Tk wizard
 atm debug --delay 5            # one-shot capture + detect
-atm validate-calibration calibration/calibration_labels.json   # offline color gate
-atm run --start-at 16:30 --stop-at 23:00                   # live session
-atm run --tz America/New_York --oh-start 09:30 --oh-stop 16:00  # NYSE window override
-pytest -q                      # 230+ tests (core + 8 scenarii regresie + env loader)
-pytest tests/test_scenarios_regression.py -v    # FSM pe imagini reale
+atm validate-calibration calibration/calibration_labels.json   # color gate offline
+atm run --start-at 16:30 --stop-at 23:00                        # live session
+atm run --tz America/New_York --oh-start 09:30 --oh-stop 16:00  # NYSE window
+pytest -q                      # 230+ teste
 ```
 
-## Codex sandbox/tooling notes
+## DOX Protocol
 
-On this Windows checkout, do not assume `rg` or the global `python` has project deps.
-Use the repo venv for diagnostics that need Pillow/OpenCV:
+- **Citire** — traversează root → path-ul țintă, citind fiecare `AGENTS.md`. Dacă
+  un părinte indexează un copil al cărui scope conține path-ul, citește copilul și
+  continuă de acolo.
+- **Editare** — `AGENTS.md`-ul cel mai apropiat = contract local; părinții = reguli
+  globale. Un copil nu poate slăbi o constrângere impusă de un părinte.
+- **Update (closeout)** — re-verifică path-urile schimbate față de lanțul DOX;
+  actualizează doc-urile care le dețin + indexurile afectate; șterge textul învechit;
+  rulează verificarea relevantă.
 
-```powershell
-.\.venv\Scripts\python.exe scripts\inspect_image_pixels.py 6033117943853423831.jpg
-.\.venv\Scripts\python.exe scripts\inspect_image_pixels.py 6033117943853423831.jpg --point 1780 725
-```
+## Durable Rules (repo-wide)
 
-If `rg` is missing, use PowerShell fallbacks:
-`Get-ChildItem -Recurse -File src,tests,scripts | Select-String -Pattern "needle"`.
-If a command fails due to sandbox permissions and is required for the task, rerun it
-with an escalation request instead of stopping the investigation without a verdict.
+- **Pure-logic fără cv2/numpy** în `state_machine.py` și `config.py` (testele rulează
+  headless). cv2/I/O greu mereu în `asyncio.to_thread`.
+- **Secretele doar din env** (`.env`), niciodată în TOML sau cod.
+- **Mereu** `atm validate-calibration` după recalibrare (palette gotcha — vezi
+  `calibration/AGENTS.md`).
+- Modul nou în `src/atm/` ⇒ `test_<modul>.py` corespondent.
 
-## Calibration corpus
+> Skill routing (Claude Code) trăiește în [`CLAUDE.md`](CLAUDE.md) — sursa canonică.
 
-`calibration/` — persistent, auto-suficient. Conține:
-- `frames/` — PNG-uri raw `{ts}_{color}.png` scrise **automat** de live loop la fiecare schimbare de culoare (filename = culoarea detectată, poate fi greșită)
-- `calibration_labels.json` — ground truth **manual** (gate offline pentru `atm validate-calibration`)
-- `scenarios.json` — secvențe FSM pentru `tests/test_scenarios_regression.py`
+## Child DOX Index
 
-Workflow după sesiune: review frame-urile noi din `frames/`, adaugi entry-uri în `calibration_labels.json` cu culoarea pe care ai văzut-o TU pe chart (nu neapărat cea din filename), rulezi `atm validate-calibration`.
-
-## Telegram commands (live)
-
-`/ss` `/status` `/pause` `/resume` `/rebase` `/3` (interval min) `/stop`
-
-- `/rebase` — propune un `baseline_phash` nou pentru canary: capturează frame, crop pe `canary.roi`, phash → trimite screenshot adnotat (cerc roșu pe ROI) cu old/new hash + distance. `/rebase confirm` în ≤180s aplică: rescrie `baseline_phash` în TOML-ul activ (păstrează comentariile), mirror în `cfg` la runtime, clear `user_paused` + `drift_paused`. Fără confirm, nimic nu se modifică. Folosește-l când layout-ul TS s-a schimbat intenționat și vrei să re-ancorezi canary-ul fără `atm calibrate` full.
-
-- `/ss` — verify multi-bulină: adnotează top-3 buline din `dot_roi` (cerc roșu gros pe pick-ul FSM, cercuri colorate subțiri pe vecini) + caption cu clasificarea fiecăreia (nume, RGB, distanță, confidence) + `config: {version}`. Cercul colorat folosește `cfg.colors[name].rgb` la runtime — DRY cu paleta activă.
-- `/resume` clears BOTH user pause and canary drift-pause in one shot (`/resume force` still accepted as legacy alias). Trimite un singur Alert cu screenshot adnotat inline (capture rulează **înainte** de clearing state → zero race cu FSM tick-uri). Dacă capture eșuează, title conține `⚠️ captură eșuată` și resume-ul se execută oricum.
-- Drift-pause emits a single Telegram alert on transition. While paused, `/set_interval` is refused and `/ss` captions warn that detection is off.
-- Heartbeat shows `⚠️ pauzat (drift)` instead of `activ` while canary is paused.
-
-## Operating-hours config
-
-`[options.operating_hours]` in TOML: `enabled`, `timezone` (NYSE local, e.g. `America/New_York`), `weekdays`, `start_hhmm`, `stop_hhmm`. Timezone validated at load; `_tz_cache` reused per tick. Boundary crossings log `market_open` / `market_closed` and notify once. Startup in-window is silent.
-
-## Phase-skip backstop
-
-`[options.alerts] fire_on_phase_skip = true` (default) — ARMED→light_*  direct (dark_* missed) still emits a `⚠️ PHASE SKIP` alert using FSM lockout to suppress spam.
-
-## Palette gotcha (2026-04-21 recalibration)
-
-TradeStation M2D indicators paint the four bright colors at near-pure saturation:
-turquoise `(0,253,253)`, yellow `(253,253,0)`, light_green `(0,255,0)`, light_red `(255,0,0)`.
-If Tk-wizard calibration samples a slightly desaturated pixel, classifier returns `UNKNOWN`
-(distance > tolerance=60) → FSM never sees trigger → stuck in PRIMED → scheduler polls
-forever. Always run `atm validate-calibration calibration/calibration_labels.json` after
-recalibrating. Current active config: `configs/2026-04-21-recalib.toml`.
-
-## Skill routing
-
-When the user's request matches an available skill, ALWAYS invoke it using the Skill
-tool as your FIRST action. Do NOT answer directly, do NOT use other tools first.
-The skill has specialized workflows that produce better results than ad-hoc answers.
-
-Key routing rules:
-- Product ideas, "is this worth building", brainstorming → invoke office-hours
-- Bugs, errors, "why is this broken", 500 errors → invoke investigate
-- Ship, deploy, push, create PR → invoke ship
-- QA, test the site, find bugs → invoke qa
-- Code review, check my diff → invoke review
-- Update docs after shipping → invoke document-release
-- Weekly retro → invoke retro
-- Design system, brand → invoke design-consultation
-- Visual audit, design polish → invoke design-review
-- Architecture review → invoke plan-eng-review
-- Save progress, checkpoint, resume → invoke checkpoint
-- Code quality, health check → invoke health
+- **`src/atm/`** → `src/atm/AGENTS.md` — motorul: capture/detect/FSM/scheduler/
+  vision/canary/config. (copil: `notifier/`)
+- **`tests/`** → `tests/AGENTS.md` — suita de teste + regresie FSM.
+- **`calibration/`** → `calibration/AGENTS.md` — corpus culori + scenarii + palette gotcha.
+- **`configs/`** → `configs/AGENTS.md` — schema TOML (operating_hours, alerts, canary).
+- **`scripts/`** → `scripts/AGENTS.md` — diagnostic + note sandbox Windows/venv.