From 693211cee9bd40429a21787fc9611c2e7a80ec22 Mon Sep 17 00:00:00 2001 From: Alexander Baranov Date: Mon, 24 Aug 2026 23:26:50 +0300 Subject: [PATCH] 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 --- .../legacy-knowledge-base-treatment.md | 71 +++++++++++++++++++ kdb/kdb.yaml | 8 +++ 2 files changed, 79 insertions(+) create mode 100644 docs/research/legacy-knowledge-base-treatment.md diff --git a/docs/research/legacy-knowledge-base-treatment.md b/docs/research/legacy-knowledge-base-treatment.md new file mode 100644 index 0000000..abe72bc --- /dev/null +++ b/docs/research/legacy-knowledge-base-treatment.md @@ -0,0 +1,71 @@ +--- +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 — не установлено. diff --git a/kdb/kdb.yaml b/kdb/kdb.yaml index 8cb3d63..f0be880 100644 --- a/kdb/kdb.yaml +++ b/kdb/kdb.yaml @@ -54,6 +54,7 @@ spec: documents: - adoption-runbook - stewardship-specification + - legacy-kdb-treatment data: loadPolicy: runbook-first phases: @@ -192,6 +193,13 @@ spec: mediaType: text/markdown authority: manual status: draft + - id: legacy-kdb-treatment + title: Legacy knowledge base treatment options + role: explanation + path: docs/research/legacy-knowledge-base-treatment.md + mediaType: text/markdown + authority: manual + status: draft - id: repoctl-human-guide title: repoctl CLI reference for humans role: explanation