Archmotif metrics bridge

docs/ECOSYSTEM.md

@@ -0,0 +1,111 @@
+# Карта экосистемы archlint: тракты реализации и их отношение
+
+- Статус: Accepted
+- Опора: ROADMAP.md (раздел ЦЕЛЕВАЯ РЕАЛИЗАЦИЯ), proof-catalog.md, adr/0002-...
+- Уровень: ЭКОСИСТЕМНЫЙ (тракты + отношение). Намеренно БЕЗ деталей модели
+  графа и состава метрик — они меняются ежедневно в Фазе 3; смотри ADR-0002
+  (модель) и proof-catalog.md (метрики), не этот документ.
+
+## 1. Зачем эта карта
+
+archlint — полиглот: в одном репозитории сосуществуют три параллельные
+реализации на разных языках плюс внешняя математическая зависимость. Без явной
+карты легко принять один тракт за другой (Rust-пласт можно ошибочно счесть
+актуальным направлением, а Python validator — живым гейтом). Карта фиксирует: КТО
+целевой, КТО заморожен, КТО музей, и КАК они относятся друг к другу и к внешним
+каналам (archmotif, MCP, watch-loop).
+
+Целевой язык = Go. Rust-rewrite заморожен. Карта отражает эту цель.
+
+## 2. Три тракта реализации
+
+### Go-тракт — ЦЕЛЕВОЙ / боевой
+
+- Где: `internal/` (model, analyzer, mcp, archmotifbridge, watcher, optimizer) +
+  `cmd/` (точки входа). Собранный бинарь: `bin/archlint`.
+- Роль: ЕДИНСТВЕННЫЙ боевой тракт. Здесь материализуется каталог доказуемости
+  (proof-catalog.md): формальное определение принципа -> метрика -> обоснование
+  соундности. Все Фазы 1/3 идут на Go/gonum.
+- Чем считает: структурные метрики боевого гейта (Тир1) — чистый Go на gonum, без
+  внешних процессов.
+- Это цель развития: новые метрики, порты структурных метрик из Python, вся
+  материализация принципов — сюда.
+
+### Rust-тракт (archlint-rs) — ЗАМОРОЖЕН
+
+- Где: `archlint-rs/src/` (analyzer.rs, session.rs, language_analyzer.rs,
+  config.rs, server.rs(axum), diagram.rs, fix.rs, costlint/perflint/seclint/
+  promptlint.rs). Граф = petgraph. Правила = конфиг `.archlint.yaml` (per-rule).
+- Статус: rewrite-направление ЗАМОРОЖЕНО. Был боевым для демо — это история, не цель.
+- Что с ним: НЕ удаляем (рабочий код, ценность как прецедент и для демо), но НЕ
+  развиваем и НЕ трогаем. Новой работы здесь нет. В карту внесён, чтобы его не
+  принимали за актуальное направление.
+
+### Python-тракт (validator/) — МУЗЕЙ
+
+- Где: `validator/` (NetworkX).
+- Роль: Тир3 "музей" из ADR-0002 — комбинаторно-взрывные / NP-hard метрики,
+  которые на реальных графах не досчитываются. ВНЕ боевого гейта.
+- Режим: ручной запуск по требованию, не в горячем пути. Исторический источник
+  структурных метрик, которые портируются в Go-тракт (после порта живут в Тир1).
+
+## 3. Внешняя зависимость: archmotif
+
+- Что: внешняя библиотека матядра. Даёт research-математику на Go/gonum (lambda2,
+  modularity, motif z-score, curvature, quotient-схлопывание, спектр).
+- Граница: Вариант B' из ADR-0002 — in-process Go-import через тонкий публичный
+  export-слой в форке. Потребляется Go-трактом через `archmotifbridge/`.
+- Принцип: archmotif НЕ вендорится и НЕ копируется внутрь archlint — это
+  единственный источник research-математики (гигиена зависимостей). archlint
+  отдаёт граф и получает числа.
+- Что обслуживает: Тир2 (research) — спектральное/алгебраическое, по требованию,
+  вне боевого гейта.
+
+## 4. Боевые каналы Go-тракта
+
+### MCP-сервер (internal/mcp)
+
+- archlint выставляет себя как MCP-сервер. Это боевой канал гейта: агент-потребитель
+  получает вердикты метрик (нарушения архитектуры) через MCP-инструменты.
+- Режим: боевой гейт качества в агентском loop.
+
+### watch-loop (агентский self-fix)
+
+- Цепочка: watch-скрипт запускает `archlint watch` + `archlint scan` +
+  `archlint callgraph` -> при нарушении пишет нарушения в файл -> агент читает файл и
+  исправляет; при исправлении файл очищается.
+- ТРАКТ: Go. Скрипт гонит бинарь `bin/archlint` (вызовы watch/scan/callgraph).
+  Rust/Python в этой петле НЕ участвуют.
+- Режим: непрерывный watch-гейт с автоматическим self-fix агентом (human-in-loop
+  по необходимости).
+
+## 5. Отношение трактов: что за какой режим отвечает
+
+| Режим | Тракт / канал | Назначение |
+|-------|---------------|------------|
+| Боевой гейт (структурный) | Go (bin/archlint: scan/watch) + MCP | вердикты качества в агентском loop, latency-критично |
+| Непрерывный watch + self-fix | Go (watch-loop) -> файл нарушений -> агент-фиксер | автокоррекция нарушений на лету |
+| Research (спектр/алгебра) | Go -> archmotifbridge -> archmotif | Тир2, по требованию, вне гейта |
+| Музей (комбинаторно-взрывное) | Python (validator/, NetworkX) | Тир3, ручной запуск, источник портов в Go |
+| Заморожено | Rust (archlint-rs) | не цель, не трогаем, прецедент/история |
+
+Поток потребления (боевой путь):
+
+    исходный код (Go/Rust/TS)
+         |
+         v
+    Go-тракт archlint: строит модель графа G (ADR-0002)
+         |
+         +--> Тир1 структурные метрики (gonum, in-process)  --> вердикт
+         |                                                         |
+         +--> Тир2 research: archmotifbridge -> archmotif         |
+         |        (по требованию, не в гейте)                     |
+         v                                                         v
+    каналы выдачи: MCP-сервер (агенту)  /  watch-loop (файл нарушений -> агент-фиксер)
+
+Python-музей (Тир3) и Rust (заморожен) в боевой поток НЕ входят.
+
+## 6. Что НЕ входит в эту карту
+
+- Детали модели графа G и состав/пороги метрик — живут в ADR-0002 и
+  proof-catalog.md (текут в Фазе 3, здесь не дублируются).