ss-tools/docs/adr

Реестр архитектурных решений

ADR фиксирует принятое и проверяемое архитектурное решение. Это не план работ и не каталог желаемой архитектуры: обещание, которое ещё не реализовано, должно иметь статус PROPOSED или быть вынесено в spec.

Статусы

Статус	Значение
ACCEPTED	Решение действует и соответствует реализации.
IMPLEMENTED	Закрытое решение с подтверждённой реализацией; исторические счётчики тестов не являются текущим release gate.
PARTIALLY IMPLEMENTED	Направление принято, но в репозитории есть существенная незавершённая часть.
SUPERSEDED	Решение заменено указанным ADR; исторический файл не меняет действующую архитектуру.
REJECTED	Альтернатива запрещена; это не описание действующей реализации.
PROPOSED	Решение обсуждается и не должно считаться обязательным.

Актуальный реестр

ADR	Статус	Проверенное содержание
0001	PARTIALLY IMPLEMENTED	Границы backend/frontend/docs/specs и направление импортов; старое фиксированное дерево и фиктивное автообеспечение удалены.
0002	ACCEPTED	Семантические skills и контракты в исходном коде остаются правилом репозитория.
0003	ACCEPTED	Сервис остаётся внешним оркестратором Superset.
0004	SUPERSEDED	Заменён ADR-0016: исходный subprocess/TOML-контракт не был реализован.
0005	ACCEPTED	Локальная аутентификация, RBAC и ADFS JIT provisioning реализованы.
0006	ACCEPTED	Svelte 5, Screen Models и UI atoms применяются; вымышленный CI style-аудитор и устаревший список маршрутов удалены.
0007	REJECTED	Комбинация fromStore с несколькими $derived запрещена.
0008	ACCEPTED	Декораторный registry реализован в backend/src/api/routes/assistant/_tool_registry.py.
0009	ACCEPTED	Управление корпоративными CA реализовано в Docker и HTTP-клиентах.
0010	PARTIALLY IMPLEMENTED	Порог 400 строк / около 40 методов остаётся целью; два действующих Screen Model превышают предел, автоматического gate нет.
0011	PARTIALLY IMPLEMENTED	Async-клиент, registry и bounded executors существуют; существующие sync-пути остаются, прежний план полной миграции удалён.
0012	ACCEPTED	Интеграционные Superset-тесты используют Postgres, init/web контейнеры и superset_config.py.
0013	ACCEPTED	scripts/coverage-summary.sh существует и собирает сводный отчёт.
0014	SUPERSEDED	Заменён ADR-0015.
0015	SUPERSEDED	Заменён ADR-0022: agent-контейнер удалён, второй runtime исчез.
0016	ACCEPTED	Плагины загружаются в процессе из backend/src/plugins через PluginBase.
0017	ACCEPTED	Agent-centric traces achieved by editing call sites (meaningful intents, removal of per-request noise) rather than only adding complexity to the logger.
0018	REJECTED	Dataset Review is removed from the active product; specs/027-dataset-llm-orchestration/ is retained only as archived history.
0019	ACCEPTED	UUID-трансформация БД (не strip_databases), cross-filter patching через IdMappingService, password injection flow (await_input→wait_for_input→retry), разделение dry-run/execute, парсинг имён YAML-файлов БД.
0020	ACCEPTED	Обнаружение виртуальных (SQL) датасетов в maintenance discovery через серверный фильтр sql is_not_null (fallback — клиентский скан по непустому sql); AsyncAPIClient.request поднимает не-2xx ответы (raise_for_status); sqlparse token-limit (10000) fallback к regex-only для гигантских виртуальных датасетов.
0021	PARTIALLY IMPLEMENTED	EXPLORE и аналитика реализованы; заявленные baseline-файлы для тишины и bond-профиля отсутствуют, поэтому их пороги не считаются действующими.
0022	ACCEPTED	Пакет shared/ поглощён backend'ом после удаления агента: cot_logger → src/core/, CotJsonFormatter → src/core/cot_formatter.py, _llm_*/ssl → src/core/utils/; единый фасад src/core/logger.py; run.sh/Dockerfile без pip install -e ../shared.
0023	IMPLEMENTED	MCP-стадии inspect/compile/validate/resolve/draft-pack изначально не создавали серверные *Handle, а create_scenario/create_initial писали в graph_snapshot только provenance-метаданные (риск вакуумного false PASS, закрыт guard'ом BOOTSTRAP_REVISION_NOT_RUNNABLE). Реализован полный handle-слой: CompiledScenarioHandle/ValidationResultHandle/DraftPackHandle (migrations 0019–0021), canonical-bytes authority, single consumption под FOR UPDATE (PostgreSQL-proven), материализация графа в create-транзакции, outbox-worker в scheduler poll loop, MCP register_draft_pack + handle-only bootstrap, гибрид T029h (inspect_dashboard_context + context_authority binding + PROD gate). Guard демотирован до defense-in-depth.
0024	IMPLEMENTED	MCP create_agent_run/get_agent_run, внешний bootstrap без ORM-seed и live replay E2E-EXT-002 закрыты; правило достижимости предусловий и честного E2E остаётся обязательным.
0025	PARTIALLY IMPLEMENTED	Baseline определяется проверенным URL того же дашборда и замороженными native filters; browser→draft→local catalog подтверждён, Git receipt/run pin/scheduled replay открыты.
0026	PARTIALLY IMPLEMENTED	Общая literal-замена для viewer/migration реализована; preview fingerprint сейчас проверяет фронтенд, API не требует серверного подтверждения preview. Заменяет удалённый ненумерованный черновик.

Правила сопровождения

1. Новый ADR добавляется только для решения, которое меняет границу модулей, runtime/topology, безопасность, данные или постоянный способ разработки.
2. Каждый ADR содержит контекст, решение, последствия и отклонённые альтернативы.
3. При изменении решения создаётся новый ADR со ссылкой на заменённый, а прежний получает SUPERSEDED; историю не переписывают.
4. В ADR указываются существующие пути и проверяемые факты. Версии, пороги и команды обновляются вместе с кодом либо заменяются ссылкой на источник истины.