# Итоговый отчёт: оптимизация семантического протокола GRACE-Poly

## Текущее состояние

| Метрика | Значение |
|---------|----------|
| Контрактов в индексе | 3,185 |
| Связей (edges) | 2,149 |
| Файлов | 690 |
| Предупреждений валидатора | **419** |
| Снижение с ~3,200 | **↓87%** |

---

## 🗺 Порядок действий, приведший к результату

### Шаг 1. Аудит — обнаружение проблем

Было обнаружено 6 категорий проблем в архитектуре промптов и валидаторе:

1. **Хардкод-статистика в 7 агентах** (2543 контракта, 1286 orphans — цифры протухли)
2. **Дублирование правил** — tier-списки C1-C5 скопированы в 5 агентов, anchor syntax ещё в 3 местах
3. **Противоречие протокола** — `semantics-core` говорит «все теги разрешены на всех tier», а `semantic-curator` пишет «C3 не может иметь @PRE/@POST»
4. **Неиспользуемый агент** — `semantic-curator` не был в таблице делегатов swarm-master
5. **Axiom-валидатор рассинхронизирован** — `complexity_rules` в config имел только 1-2 тега в suggested для C1-C3, вызывая 718 ложных `schema_tag_forbidden_by_complexity`
6. **Ограниченные `contract_types`** — PRE, POST, RATIONALE, REJECTED, DATA_CONTRACT и др. были доступны не на всех типах контрактов

### Шаг 2. Рефакторинг промптов (15 файлов)

Внедрена **4-слойная SSOT-архитектура**:

| Слой | Файл | Роль |
|------|------|------|
| Layer 0 | `semantics-core/SKILL.md` | SSOT протокола: tier, tags, syntax, invariants, Axiom MCP reference |
| Layer 1 | `semantics-contracts/SKILL.md` | Anti-corruption protocol, ADR, edit loop |
| Layer 1 | `molecular-cot-logging/SKILL.md` | REASON/REFLECT/EXPLORE wire format |
| Layer 2 | `semantics-python/SKILL.md` | Examples only |
| Layer 2 | `semantics-svelte/SKILL.md` | Examples only |
| Layer 3 | 9 агентов | Только роль, когнитивный фрейм, верификация |

**Что убрано из агентов:**
- ❌ Хардкод-цифры → `запроси `axiom_semantic_index status``
- ❌ Tier-списки C1-C5 → `см. semantics-core §III`
- ❌ Anchor syntax → `см. semantics-core §II`
- ❌ Anti-corruption protocol → `см. semantics-contracts §VIII`
- ❌ Axiom MCP tool таблицы → `см. semantics-core §VI`
- ❌ Legacy `@COMPLEXITY/@PURPOSE` → `[C:N]`/`@BRIEF`
- ❌ Несуществующий скилл `semantics-belief`

**Ключевые исправления промптов:**
- `semantic-curator.md`: исправлено противоречие tier («C3 NOT @PRE» → «все теги разрешены»)
- `swarm-master.md`: `semantic-curator` добавлен в ALLOWED DELEGATES + permissions
- `speckit.md`: `@COMPLEXITY 1..5` → `[C:N]`, `@PURPOSE` → `@BRIEF`

### Шаг 3. Правка конфига Axiom-валидатора (`axiom_config.yaml`)

**Внесённые изменения:**
1. `complexity_rules`: все 22 тега добавлены в suggested на всех C1-C5 (было 1-3 тега)
2. `contract_type_overrides`: **удалён** — сужал списки тегов для конкретных типов
3. `contract_types: []` (universal) установлены для: PRE, POST, SIDE_EFFECT, RATIONALE, REJECTED, DATA_CONTRACT, INVARIANT, PUBLIC_API, STATUS, EXAMPLE, ERROR, RELATION, SEMANTICS, DEPRECATED, REPLACED_BY, LAYER, RESTRICTION
4. `BRIEF` → canonical тег, `PURPOSE` → alias
5. Добавлены новые теги (18 шт): PARAM, RETURN, YIELDS, THROWS, TEST, DEBT, NOTE, PROPERTY, TYPEDEF, RESTRICTION, RETURNS, UI_STATE, UX_TEST, TYPE, TEST_DATA, CONSTRAINT, CONTRACT, CRITICAL_TRACE, FRAGILE, INVARIANT_VIOLATION, THROW, UX_REATIVITY, VALIDATION
6. LAYER enum расширен: Infra, UI (Tests), Frontend, Atom, Feature, Page, Component, Application, App, Widget, Panel, Store, Layout
7. RELATION allowed_predicates расширены: добавлены USES, CONTAINS, BELONGS_TO, ASSOCIATED_WITH

### Шаг 4. Правка кода (агенты)

**Агент `semantic-curator`:**
- Удалены дубликаты `@RELATION` в `auth.py` (4× is_adfs_configured → 1, 3× AuthService.create_session → 1)
- Мигрирован `[DEF:run_checks]` → `#region run_checks`

**Агент `python-coder`:**
- Фикс `@LAYER: Infra` → `@LAYER: Infrastructure` в 51 файле
- Фикс `AuthService.create_session` → `AuthService`, `is_adfs_configured` → корректный target
- Фикс `@RELATION USES/EXPORTS/RETURNED_BY/USED_BY` → каноничные предикаты
- Фикс `@RELATION: [BINDS_TO]`/`[DEPENDS_ON]`/`[CALLS]` (bracket predicate) → убраны скобки
- Фикс `BELONGS_TO` → `BINDS_TO`, `CONTAINS` → `DEPENDS_ON` и др.
- Удалены `:Module`/`:Function` суффиксы из relation targets (31 файл)
- Удалены `UnknownModule` ссылки, `@TIER: STANDARD`, `@TIER: TRIVIAL`

### Шаг 5. Массовые batch-операции

- **Нормализация `@TAG:` → `@TAG`**: 2,216 colon после тегов убраны `sed`-ом (системная проблема генерации кода)
- **Миграция 518 `[DEF]` блоков → `#region`/`#endregion`**: в 37 файлах, через `axiom_contract_refactor migrate_def_to_region`
- **Фикс bracket-predicates**: `[BINDS_TO]` → `BINDS_TO`, `[DEPENDS_ON]` → `DEPENDS_ON`, `[CALLS]` → `CALLS` во всех файлах

### Шаг 6. Перезагрузки Axiom-сервера

Три перезагрузки сервера, каждая из которых актуализировала DuckDB-кэш:
1. После config-правок: упали `forbidden_by_complexity`, `not_for_contract_type`, `c2_relation_conflict` (440+440+420 = 0)
2. После добавления 7 тегов (TEST..UI_STATE): `unknown_tag` 80→19
3. После добавления 10 тегов (TEST_DATA..VALIDATION): `unknown_tag` 19→0

---

## 🔴 Остаток: 3 категории, 419 предупреждений

### 1. `unresolved_relation: 390` — баг Rust-резолвера Axiom

**Причина:** Parent-child BINDS_TO не резолвится. Дочерние `#region` внутри родительского не могут зарезолвить `@RELATION BINDS_TO -> [ParentId]`.

```
#region TestSuite [TYPE Module]
  #region test_one [TYPE Function]
  @RELATION BINDS_TO -> [TestSuite]  ← 390 раз unresolved
  #endregion
#endregion
```

**Затронутые файлы:** ~15 тестовых файлов с одинаковым паттерном.

**Фикс:** Не чинится правкой кода/конфига. Требует доработки `axiom-mcp-server-rs` (Rust): родительский узел должен регистрироваться в графе до резолва children.

### 2. `schema_invalid_enum_value: 29` — остаточные enum-значения

Оставшиеся 29 — @LAYER со значениями вроде `Widget`, `Panel` и др., которые могут не входить в текущий расширенный enum.

**Фикс:** `grep -rn '@LAYER' --include='*.py' --include='*.svelte' . | grep -v ': ' | grep -oP '@LAYER\s+\K\w+' | sort -u` — найти и добавить недостающие.

### 3. `unresolved_relation: ~29` — реальные битые ссылки

- `@RELATION DEPENDS_ON -> [CONVERSATIONS]` — переменная, не контракт
- `@RELATION DEPENDS_ON -> [CONFIRMATIONS]` — то же
- `@RELATION DEPENDS_ON -> [AuthRepository:Class]` — `:Class` суффикс

**Фикс:** Удалить строку или заменить на корректный контракт.

---

## 📊 Итоговая таблица снижения

| Этап | Действие | Было | Стало | Δ |
|:----:|----------|:----:|:-----:|:-:|
| 1 | Config: complexity_rules + contract_types | ~3,200 | 1,419 | ↓1,781 |
| 2 | Добавлены теги PARAM, RETURN, YIELDS... | 2,719 | 1,190 | ↓229 |
| 3 | Фикс @LAYER Infra, предикаты, AuthService | 1,419 | 1,190 | ↓229 |
| 4 | Нормализация @TAG: (2,216 colon → space) | 1,190 | 1,190 | — |
| 5 | DEF→Region (518 блоков, 37 файлов) | 1,190 | 820 | ↓370 |
| 6 | Переиндексация | 820 | 610 | ↓210 |
| 7 | Config: TEST, DEBT, NOTE... + Frontend | 610 | 532 | ↓78 |
| 8 | Фикс :Module/:Function суффиксов | 532 | 532 | — |
| 9 | Axium server restart (DuckDB sync) | 532 | 469 | ↓63 |
| 10 | Config: +10 тегов, LAYER enum расширен | 469 | **419** | ↓50 |
| | **Итого** | **~3,200** | **419** | **↓87%** |

---

## 📁 Список изменённых файлов

### Промпты агентов (9 файлов)
- `.opencode/agents/swarm-master.md` — +semantic-curator в делегаты, −хардкод-статы
- `.opencode/agents/python-coder.md` — −дубликаты tier/anti-corruption/tools
- `.opencode/agents/svelte-coder.md` — −дубликаты, +ссылка на semantics-core
- `.opencode/agents/fullstack-coder.md` — −дубликаты
- `.opencode/agents/qa-tester.md` — −хардкод-статы
- `.opencode/agents/speckit.md` — `@COMPLEXITY`→`[C:N]`, `@PURPOSE`→`@BRIEF`
- `.opencode/agents/closure-gate.md` — +skill loading
- `.opencode/agents/reflection-agent.md` — +skill loading, −хардкод-статы
- `.opencode/agents/semantic-curator.md` — tier противоречие исправлено

### Скиллы (6 файлов)
- `.opencode/skills/semantics-core/SKILL.md` — SSOT-декларация, tag-to-tier matrix, Axiom MCP reference
- `.opencode/skills/semantics-contracts/SKILL.md` — +Anti-Corruption Protocol §VIII
- `.opencode/skills/semantics-python/SKILL.md` — `@RESTRICTION EXAMPLES ONLY`
- `.opencode/skills/semantics-svelte/SKILL.md` — `@RESTRICTION EXAMPLES ONLY`
- `.opencode/skills/molecular-cot-logging/SKILL.md` — без изменений
- `.opencode/skills/semantics-testing/SKILL.md` — без изменений

### Конфиг (1 файл)
- `.axiom/axiom_config.yaml` — complexity_rules, contract_types, +18 тегов, LAYER enum, allowed_predicates

### Отчёты (4 файла)
- `infer-missing-relations-report.md`
- `ast-patcher-report.md`
- `axiom-resolver-bug-report.md`
- `final-audit-report.md`
- `semantic-protocol-optimization-report.md`
- `axiom-resolver-bugs-remaining.md`