fix(adopt): decide the adapter path by content too

The rule that a knowledge file's format comes from validating it, never from
the path it occupies, was applied to `kdb/kdb.yaml` and stopped there. The
first branch of _plan_knowledge declared `ops/knowledge.yaml` the entrypoint
without ever looking at its assessed action, so a repository holding a
non-conformant file at the adapter path was adopted with the contract pointing
straight at something that fails the KnowledgeBase schema -- the same defect,
one path over, with the same consequence: it surfaces only at verify and gets
repaired by hand outside the approved plan hash. assess had the answer all
along and build_plan discarded it.

Choosing the free canonical slot makes several legacy sources reachable at
once, so the generated index registers all of them rather than the first;
indexing one and dropping the rest in silence would be a new instance of the
omission runbook 11.1 exists to prevent. That also implements the table's last
row, which had no branch until now.

When both canonical paths hold non-conformant files there is no free slot and
neither occupant may be overwritten, so adoption refuses to plan. The plan
schema is closed and carries no findings field, which leaves nowhere to record
a decision left unresolved -- the same reason malformed markers raise instead
of being guessed at.

- gate the adapter branch on the assessed action, not on the file existing
- give each indexed document an id derived from its own path
- add ADOPT_KNOWLEDGE_UNRESOLVED for the dead end, and document it
- bind the four previously untested rows of 11.1 to the parametrized table

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Alexander Baranov
2026-08-24 22:56:50 +03:00
co-authored by Claude Opus 5
parent 1974155281
commit 6c6dfb6fb6
3 changed files with 162 additions and 42 deletions
+10 -2
View File
@@ -362,9 +362,16 @@ Plan MUST содержать rendered file contents или exact patch для к
| `kdb/kdb.yaml` уже соответствует Stewardship | использовать без переписывания |
| legacy KDB находится в другом path | создать `kdb/kdb.yaml` как небольшой index/adapter |
| legacy/custom KDB уже занимает `kdb/kdb.yaml` | создать `ops/knowledge.yaml` и указать его в contract |
| несколько knowledge sources | index с topics/documents и явным authority |
| `ops/knowledge.yaml` уже соответствует Stewardship | использовать без переписывания; занятый `kdb/kdb.yaml` — preserve и forbid |
| legacy/custom файл занимает `ops/knowledge.yaml`, а `kdb/kdb.yaml` свободен | создать `kdb/kdb.yaml` как index; занятый adapter path — preserve и forbid |
| оба canonical path заняты non-conformant файлами | отказать в `plan` с `ADOPT_KNOWLEDGE_UNRESOLVED` |
| несколько knowledge sources | index с topics/documents и явным authority; регистрируются **все** источники |
Выбор между второй и четвёртой строкой определяется **валидацией содержимого** против schema `KnowledgeBase`, а не расположением файла. Файл не является conformant KDB только потому, что лежит в каноническом path: ранняя реализация делала именно это допущение и в результате указывала contract на файл, не проходящий schema, что обнаруживалось только на `verify`.
Выбор строки определяется **валидацией содержимого** против schema `KnowledgeBase`, а не расположением файла. Файл не является conformant KDB только потому, что лежит в каноническом path: ранняя реализация делала именно это допущение и в результате указывала contract на файл, не проходящий schema, что обнаруживалось только на `verify`.
Это правило распространяется на `ops/knowledge.yaml` ровно так же, как на `kdb/kdb.yaml`. Adapter path — это место, куда adoption **кладёт** сгенерированный index, а не доказательство того, что лежащий там файл им является.
Последняя строка — тупик, а не выбор по умолчанию. Свободного canonical path под conformant index не остаётся, а перезапись любого из двух занятых противоречит разделу 3; schema `adoption-plan` закрыта и поля findings не имеет, поэтому записать нерешённое решение в план некуда. Adoption отказывается планировать и оставляет разрешение конфликта владельцу.
Сгенерированный index создаётся с пустым `topics`. Какие секции legacy source заслуживают отдельного intent — решение владельца, а не вывод инструмента: adoption регистрирует документ и оставляет routing на осознанный следующий шаг.
@@ -583,6 +590,7 @@ findingCodes:
ADOPT_PATH_OUTSIDE_REPOSITORY: blocker
ADOPT_FORBIDDEN_PATH: blocker
ADOPT_MANAGED_BLOCK_MALFORMED: blocker
ADOPT_KNOWLEDGE_UNRESOLVED: blocker
ADOPT_PRESERVED_MODIFIED: blocker
ADOPT_DIFF_OUTSIDE_PLAN: warning
ADOPT_REPORT_UNSCOPED: warning