--- documentId: legacy-knowledge-base-treatment documentVersion: 0.1.0 status: research normative: false language: ru --- # Что делать с non-conformant KDB: адаптер или пересборка **Дата обсуждения:** 2026-08-24 **Статус:** открытый вопрос, решение не принято, изменений в поведении `repoctl` по итогам не выполнялось **Нормативный источник:** `docs/adoption-runbook.md` раздел 11.1 и `docs/specification.md`; этот документ их не заменяет ## Вопрос Когда `adopt` встречает knowledge base, не проходящую schema `KnowledgeBase`, есть два очевидных ответа: 1. оставить файл как есть и создать рядом compatibility index (текущее поведение L1); 2. пересобрать содержимое в один канонический `kdb/kdb.yaml`. Ниже — почему второй ответ отвергнут, чем неудовлетворителен первый в его нынешнем виде, и какой работой это лечится. ## Три факта, которые определяют ответ **Адаптер сегодня инертен.** `_knowledge_base` в `src/stewardship/adoption.py` создаёт индекс с `topics: []`. Это сделано намеренно — какие секции legacy source заслуживают отдельного intent, инструмент вывести не может. Но следствие в том, что `repoctl context --intent ` на таком репозитории возвращает пустой bundle и предупреждение `CONTEXT_INTENT_UNKNOWN` о том, что index не объявляет ни одного intent. Adoption даёт schema-корректность и стабильный entrypoint, но ноль маршрутизации — ровно то, ради чего KDB существует. **Перезапись запрещена нормативно.** Руннбук раздел 1: «`adopt` MUST NOT неявно превращаться в `normalize` или `migrate`». Спецификация требует для `normalize` явной стратегии, именованного recipe, полного rename/reference-rewrite плана и отдельного approval. На L1 ни `--strategy normalize`, ни `--recipe` не предлагаются CLI. **Обещанный мостик не реализован.** Руннбук раздел 11.1 говорит, что compatibility index MAY ссылаться на секции legacy source через `Topic.data.x-selector`, и schema поле `data` допускает. Но `build_context` в `src/stewardship/context.py` собирает bundle из **идентификаторов документов** и `x-selector` не читает вообще. Механизм задекларирован и не поддержан ничем. ## Почему пересборка в один канонический файл — неправильный ответ Не только потому, что запрещена. Запрет разумен по четырём причинам: 1. **Преобразование неверифицируемо.** Отображение произвольной legacy-структуры в topics/intents требует знать, какие секции соответствуют намерениям. Это суждение владельца; инструмент, который его угадывает, производит правдоподобный мусор. 2. **Ломается чужой интерфейс.** Legacy-файл почти наверняка кто-то читает — скрипты, другие агенты, люди. Adoption не владеет этим контрактом и не может его переписывать. 3. **План перестаёт быть ревьюабельным.** Diff вида «база знаний переписана целиком» невозможно осмысленно утвердить через `planHash`; approval-граница превращается в фикцию. 4. **Теряется provenance.** После пересборки `verify` нечего сравнивать, а происхождение каждой строки утрачено. ## Предлагаемое направление Адаптер — правильный ответ **на момент adoption**, но он должен быть strangler-миграцией, а не парковкой навсегда. Сейчас он парковка, и в этом суть вопроса. **Шаг 1. Реализовать `x-selector` в `context`.** Пока его нет, наращивать topics поверх legacy невозможно: topic может сослаться только на документ целиком, то есть на весь legacy-файл. С извлечением по yaml-path адаптер становится рабочим — один topic на одну секцию, topics добавляются по мере надобности, legacy-файл не трогается. Работа локальная: экстрактор yaml-path в `context.py` плюс поле в bundle. Альтернатива — убрать обещание из руннбука, но это хуже, механизм нужен. **Шаг 2. Пересборка становится осмысленной только после того, как topics покрыли секции.** К этому моменту маршрутизация уже находится в каноническом файле, а за legacy source остаётся только контент, и операция превращается в `normalize`-recipe с настоящей rename map вместо догадки. Снятие `forbiddenChanges` с legacy-пути тогда становится осознанным исключением, а не побочным эффектом. ## Вопрос, который стоит задать раньше обоих вариантов Точно ли legacy-файл является базой знаний. Сейчас код спрашивает только «проходит ли schema `KnowledgeBase`? нет — значит wrap». Но «нет» покрывает два разных случая: - это база знаний в чужом формате — адаптер уместен; - это **доменные данные**, исторически названные kdb (списки хостов, состояние раскатки) — тогда это не knowledge вообще, а content root со своим authority, и правильный ход иной: объявить его content root'ом и написать рядом небольшой настоящий KDB. Второй случай не лечится ни адаптером, ни пересборкой, а различить их автоматически нельзя. Это кандидат в вопросы фазы `assess`, рядом с уже существующим «Confirm repository type». ## Что уже сделано и что осталось открытым Реализовано и влито в `master`: - формат knowledge-файла определяется валидацией содержимого, а не путём, и это правило распространяется на `ops/knowledge.yaml` так же, как на `kdb/kdb.yaml`; - при занятом каноническом пути index создаётся в свободном слоте, регистрирует **все** найденные legacy-источники и запрещает запись в них; - тупик, когда оба канонических пути заняты non-conformant файлами, приводит к отказу `ADOPT_KNOWLEDGE_UNRESOLVED`, а не к контракту, указывающему на невалидный файл. Остаётся открытым: - `x-selector` в `context` (шаг 1 выше) — не реализован; - вопрос «knowledge или доменные данные» в `assess` — не задаётся; - `normalize`-recipe для legacy KDB (шаг 2) — за пределами L1; - к какому из двух случаев относится реальный `Services/Antivirus` как пилот Wave 1 — не установлено.