ss-tools/final-audit-report.md

Финальный аудит — 469 warnings (инструкция агенту)

Сводка всей оптимизации

Метрика	Значение
Индекс	3185 контрактов, 2149 связей, 690 файлов
Было предупреждений	~3200
Стало	469
Снижение	↓85%

Динамика по этапам

Этап	Действие	Итого
Исходно	—	~3200
1	Config: complexity_rules + contract_types + contract_type_overrides	1419
2	Добавлены теги PARAM, RETURN, YIELDS, THROWS; LAYER Infra	1190
3	Фикс @LAYER Infra→Infrastructure, предикаты USES/EXPORTS, AuthService	1190
4	Нормализация @TAG: (2216 colon → space)	1190
5	DEF→Region (518 блоков, 37 файлов), bracket-predicates, BELONGS_TO→BINDS_TO	820
6	Переиндексация	610
7	Config: TEST, DEBT, NOTE, PROPERTY, TYPEDEF, RETURNS, UI_STATE, Frontend	532
8	Фикс :Module/:Function суффиксов (31 файл)	532
9	Обновление Axiom (DuckDB sync)	469

Текущие 469 предупреждений — инструкция агенту по исправлению

Ошибка A: unresolved_relation: 390 — parent-child BINDS_TO (баг Axiom ресолвера)

❗ Это баг Rust-кода axiom-mcp-server-rs, не чинится правкой кода.

Пример (не починить — дождаться фикса Axiom)

Файл: backend/src/api/routes/__tests__/test_datasets.py

#region DatasetsApiTests [TYPE Module] [C:3] [SEMANTICS test, dataset, api]
...
  #region test_get_datasets_success [TYPE Function]
  @RELATION BINDS_TO -> [DatasetsApiTests]  ← unresolved (но родитель В ТОМ ЖЕ ФАЙЛЕ!)
  #endregion

  #region test_get_datasets_env_not_found [TYPE Function]
  @RELATION BINDS_TO -> [DatasetsApiTests]  ← unresolved
  #endregion
...
#endregion DatasetsApiTests

Родитель DatasetsApiTests существует (строка 1), read_outline видит его, search_contracts — НЕТ. Resolver не регистрирует parent до резолва детей.

Затронутые файлы (одинаковый паттерн):

backend/src/api/routes/__tests__/test_datasets.py
backend/src/api/routes/__tests__/test_dashboards.py
backend/src/api/routes/__tests__/test_assistant_api.py
backend/src/api/routes/__tests__/test_assistant_authz.py
backend/src/api/routes/__tests__/test_clean_release_api.py
backend/src/api/routes/__tests__/test_clean_release_legacy_compat.py
backend/src/api/routes/__tests__/test_clean_release_source_policy.py
backend/src/api/routes/__tests__/test_clean_release_v2_api.py
backend/src/api/routes/__tests__/test_clean_release_v2_release_api.py
backend/src/api/routes/__tests__/test_tasks_logs.py
backend/tests/core/test_defensive_guards.py
backend/tests/test_migration_engine.py
backend/tests/services/clean_release/test_approval_service.py
backend/tests/services/clean_release/test_candidate_manifest_services.py

Что делать агенту с этими 350 предупреждениями: НИЧЕГО. Ждать фикса axiom-mcp-server-rs.

---

Ошибка B: unresolved_relation: ~40 — реальные битые ссылки (починить кодом)

Пример B1: ссылка на переменную, не на контракт

Файл: backend/src/api/routes/assistant/_admin_routes.py

# ❌ Сейчас:
# @RELATION DEPENDS_ON -> [CONVERSATIONS]

# ✅ Должно быть:
# Удалить строку — CONVERSATIONS это словарь в памяти, не контракт

Как найти: grep -rn '@RELATION.*-> \[CONVERSATIONS\]' --include='*.py' .

Пример B2: ссылка на функцию без #region

Файл: backend/src/api/auth.py

# ❌ Сейчас:
# @RELATION DEPENDS_ON -> [log_security_event]

# ✅ Должно быть:
# @RELATION DEPENDS_ON -> [EXT:superset-tools:log_security_event]
#   (функция есть в коде, но нет контракта)

Как найти: axiom_semantic_discovery search_contracts query="log_security_event" — если не найдено, это не контракт.

Пример B3: полный путь вместо ID

# ❌ Сейчас:
# @RELATION DEPENDS_ON -> [backend.src.models.report]

# ✅ Должно быть:
# @RELATION DEPENDS_ON -> [ReportModels]
#   (найти настоящее ID контракта через search_contracts)

---

Ошибка C: schema_unknown_tag: 19 — теги не в TagSchema (починить конфигом)

Что это: В коде используются @ТЕГ, которого нет в axiom_config.yaml → tags:.

Список неизвестных тегов

Тег	Где встречается	Фикс
@TEST_DATA	test файлы	Добавить в axiom_config.yaml: тестовая фикстура
@CONSTRAINT	model файлы	Добавить или заменить на @INVARIANT
@CONTRACT	model файлы	@RELATION DEPENDS_ON
@CRITICAL_TRACE	core/logging	Добавить
@FRAGILE	код	Добавить (хрупкий тест/код)
@INVARIANT_VIOLATION	тесты	Добавить
@THROW	код	Уже есть @ERROR, можно алиас
@UX_REATIVITY	svelte	Опечатка! Должно быть @UX_REACTIVITY
@VALIDATION	код	Заменить на @INVARIANT
@DEBT	код	✅ уже добавлен (возможно DuckDB не догнал)

Как добавить тег в конфиг

В .axiom/axiom_config.yaml, в раздел tags: (перед # #endregion TagSchema):

  TEST_DATA:
    type: string
    multiline: false
    description: 'Тестовая фикстура или данные. Универсально опциональный.'
    contract_types: []
    protected: false
    orthogonal: true
    decision_memory: false
  CONSTRAINT:
    type: string
    multiline: true
    alias_for: INVARIANT
    description: 'Алиас для INVARIANT. Универсально опциональный.'
    contract_types: []
    protected: false
    orthogonal: true
    decision_memory: false

Как проверить после добавления

axiom_semantic_index rebuild rebuild_mode="full"
axiom_semantic_validation audit_contracts

---

Ошибка D: schema_invalid_enum_value: 60 — невалидное значение enum

Что это: Тег имеет ограничение enum: в конфиге, но в коде написано другое значение.

Пример D1: @LAYER с нестандартным значением

Файл: frontend/src/lib/components/...

// ❌ Сейчас:
// @LAYER: Atom
// @LAYER: Feature
// @LAYER: Page

// ✅ Должно быть:
// @LAYER UI
// Эти компоненты — часть UI слоя

LAYER enum сейчас: [Core, Domain, API, UI, Service, Infrastructure, Plugin, Tests, Infra, UI (Tests), Frontend]

Не в enum: Atom, Feature, Page, Component, Application, App, Widget, Panel

Фикс: Или расширить enum, или исправить значение в коде.

Пример D2: @TYPE с произвольным значением

// ❌ Сейчас:
// @TYPE: {{ healthItems: Array<...> }}
// Значение — TypeScript тип, не enum

// ✅ Должно быть:
// Удалить @TYPE — это не тег, а TS тип

Как найти все проблемные значения

axiom_semantic_validation audit_contracts | grep invalid_enum_value | head -20

---

План агенту по уменьшению 469 → ~0

Шаг	Что делать	Инструмент	Ожидаемый результат
1	Добавить 19 неизвестных тегов в axiom_config.yaml	edit → rebuild	unknown_tag: 19 → 0
2	Исправить @UX_REATIVITY → @UX_REACTIVITY в svelte-файлах	sed	−1 unknown_tag
3	Исправить 60 invalid_enum: расширить LAYER enum или исправить в коде	edit конфига + sed по коду	invalid_enum: 60 → 0
4	Удалить ~40 битых @RELATION (CONVERSATIONS, CONFIRMATIONS и др.)	edit кода	unresolved: 390 → 350
5	Ждать фикса Axiom ресолвера (parent-child BINDS_TO)	—	unresolved: 350 → 0

Что было сделано за сессию

Область	Изменения
Промпты агентов	15 файлов: SSOT-архитектура, устранено дублирование tier/синтаксиса/anti-corruption
Конфиг Axiom	26 тегов в complexity_rules, 12 тегов universal (contract_types: []), удалён contract_type_overrides
Код	Нормализовано 2216 @TAG: → @TAG, 518 DEF→Region, 31 файл :Module/:Function суффиксы
Теги Axiom	Добавлены: PARAM, RETURN, YIELDS, THROWS, TEST, DEBT, NOTE, PROPERTY, TYPEDEF, RESTRICTION, RETURNS, UI_STATE, UX_TEST, TYPE
Enum LAYER	Добавлены: Infra, UI (Tests), Frontend
Предикаты RELATION	Добавлены: USES, CONTAINS, BELONGS_TO, ASSOCIATED_WITH