Files
repoctl/docs/research/legacy-knowledge-base-treatment.md
Alexander BaranovandClaude Opus 5 693211cee9 docs: record the open question about non-conformant knowledge bases
The adapter that adoption generates is schema-correct and inert: it is created
with empty topics on purpose, so `context` on such a repository returns an
empty bundle. That is the honest answer at apply time, but it leaves the
repository without routing indefinitely, which is the whole point of a KDB --
so whether the adapter should stay or the legacy file should be rebuilt into
one canonical index is a real open question, not a settled one.

Recorded as research rather than as a runbook change: no decision was taken and
no behaviour changed. The note argues against rebuilding, and identifies why
the adapter cannot yet grow into a replacement -- runbook 11.1 offers
`Topic.data.x-selector` as the way to index sections of a legacy source, and
build_context assembles bundles from document ids and never reads it. Until
that exists a topic can only reference a whole legacy file, so incremental
migration has nowhere to start.

Also names the question that precedes both options: whether the legacy file is
a knowledge base in a foreign format or domain data that was called kdb, which
adoption currently cannot distinguish and does not ask.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-24 23:26:50 +03:00

8.7 KiB
Raw Permalink Blame History

documentId, documentVersion, status, normative, language
documentId documentVersion status normative language
legacy-knowledge-base-treatment 0.1.0 research false 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 <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 — не установлено.