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>
This commit is contained in:
co-authored by
Claude Opus 5
parent
c483d94f36
commit
693211cee9
@@ -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 <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 — не установлено.
|
||||||
@@ -54,6 +54,7 @@ spec:
|
|||||||
documents:
|
documents:
|
||||||
- adoption-runbook
|
- adoption-runbook
|
||||||
- stewardship-specification
|
- stewardship-specification
|
||||||
|
- legacy-kdb-treatment
|
||||||
data:
|
data:
|
||||||
loadPolicy: runbook-first
|
loadPolicy: runbook-first
|
||||||
phases:
|
phases:
|
||||||
@@ -192,6 +193,13 @@ spec:
|
|||||||
mediaType: text/markdown
|
mediaType: text/markdown
|
||||||
authority: manual
|
authority: manual
|
||||||
status: draft
|
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
|
- id: repoctl-human-guide
|
||||||
title: repoctl CLI reference for humans
|
title: repoctl CLI reference for humans
|
||||||
role: explanation
|
role: explanation
|
||||||
|
|||||||
Reference in New Issue
Block a user