Files
repoctl/docs/research/legacy-knowledge-base-treatment.md
T
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

72 lines
8.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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 <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 — не установлено.