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
+75 -40
View File
@@ -11,6 +11,7 @@ from __future__ import annotations
import fnmatch
import os
import re
from pathlib import Path
from typing import Any
@@ -398,26 +399,43 @@ This repository is adopted at L1. Before reading anything else:
)
def _knowledge_base(name: str, legacy_path: str | None) -> dict[str, Any]:
"""A minimal KnowledgeBase, indexing ``legacy_path`` when one was found.
def _legacy_document_id(rel_path: str) -> str:
"""A schema-valid document id derived from the legacy file's own path.
Distinct ids matter as soon as more than one legacy source is indexed: the
KnowledgeBase schema constrains ids to ``^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$``,
so a single hardcoded id could only ever register one document.
"""
stem = rel_path.rsplit(".", 1)[0] if "." in Path(rel_path).name else rel_path
slug = re.sub(r"[^a-z0-9]+", "-", stem.lower()).strip("-")
return f"legacy-{slug}" if slug else "legacy-knowledge-base"
def _knowledge_base(name: str, legacy_paths: list[str]) -> dict[str, Any]:
"""A minimal KnowledgeBase, indexing every legacy source that was found.
Takes a list rather than a single path because the last row of runbook 11.1
-- several knowledge sources -- becomes reachable as soon as a canonical
path is free while both a root ``kdb.yaml`` and a non-conformant
``ops/knowledge.yaml`` exist. Registering one and dropping the other in
silence would repeat the omission this table exists to prevent.
Topics stay empty on purpose: which sections of a legacy file matter is a
judgement call the tool cannot make, so adoption registers the document and
leaves routing to be authored deliberately afterwards.
"""
documents: list[dict[str, Any]] = []
if legacy_path:
documents.append(
{
"id": "legacy-knowledge-base",
"title": "Existing knowledge base",
"role": "reference",
"path": legacy_path,
"mediaType": "application/yaml",
"authority": "local-canonical",
"status": "verified",
}
)
documents: list[dict[str, Any]] = [
{
"id": _legacy_document_id(legacy_path),
"title": f"Existing knowledge base ({legacy_path})",
"role": "reference",
"path": legacy_path,
"mediaType": "application/yaml",
"authority": "local-canonical",
"status": "verified",
}
for legacy_path in legacy_paths
]
return {
"apiVersion": API_VERSION,
"kind": "KnowledgeBase",
@@ -450,44 +468,61 @@ def _plan_knowledge(
adapter = entries.get("ops/knowledge.yaml")
root_legacy = entries.get("kdb.yaml")
if adapter is not None:
changes.append({"action": "preserve", "path": "ops/knowledge.yaml", "ownership": "repository"})
def conformant(entry: dict[str, Any] | None) -> bool:
return entry is not None and entry["action"] == "keep-or-validate"
def keep(rel: str, *, forbid: bool) -> None:
changes.append({"action": "preserve", "path": rel, "ownership": "repository"})
if forbid:
forbidden.append(rel)
if conformant(adapter):
keep("ops/knowledge.yaml", forbid=False)
if canonical is not None:
changes.append({"action": "preserve", "path": "kdb/kdb.yaml", "ownership": "repository"})
forbidden.append("kdb/kdb.yaml")
keep("kdb/kdb.yaml", forbid=True)
return "ops/knowledge.yaml", changes, forbidden
if canonical is not None and canonical["action"] == "keep-or-validate":
changes.append({"action": "preserve", "path": "kdb/kdb.yaml", "ownership": "repository"})
if conformant(canonical):
keep("kdb/kdb.yaml", forbid=False)
if adapter is not None:
keep("ops/knowledge.yaml", forbid=True)
return "kdb/kdb.yaml", changes, forbidden
if canonical is not None:
changes.append({"action": "preserve", "path": "kdb/kdb.yaml", "ownership": "repository"})
forbidden.append("kdb/kdb.yaml")
changes.append(
{
"action": "create",
"path": "ops/knowledge.yaml",
"ownership": "stewardship",
"reason": "Compatibility index; kdb/kdb.yaml holds a non-conformant knowledge base",
"content": io.yaml_text(_knowledge_base(confirmed_name, "kdb/kdb.yaml")),
}
if canonical is not None and adapter is not None:
# Both canonical slots hold knowledge bases that fail the schema.
# Overwriting either is precisely what adoption promises not to do, and
# the plan schema carries no field in which to record a decision left
# unresolved -- so refuse, rather than emit a contract whose entrypoint
# cannot validate and only fails later, at `verify`.
raise AdoptionError(
"ADOPT_KNOWLEDGE_UNRESOLVED",
"kdb/kdb.yaml and ops/knowledge.yaml both hold non-conformant knowledge bases; "
"neither may be overwritten and no canonical path is free for a generated index",
)
return "ops/knowledge.yaml", changes, forbidden
legacy_path = root_legacy["path"] if root_legacy is not None else None
if legacy_path:
forbidden.append(legacy_path)
# At most one canonical path is occupied here, so the other is free to hold
# the generated index; everything that was already there becomes a document
# it registers rather than a file adoption rewrites.
target = "ops/knowledge.yaml" if canonical is not None else "kdb/kdb.yaml"
legacy_paths: list[str] = []
for entry in (canonical, adapter, root_legacy):
if entry is None:
continue
legacy_paths.append(entry["path"])
keep(entry["path"], forbid=True)
changes.append(
{
"action": "create",
"path": "kdb/kdb.yaml",
"path": target,
"ownership": "stewardship",
"reason": "Compatibility index for legacy knowledge base" if legacy_path else "Minimal KDB",
"content": io.yaml_text(_knowledge_base(confirmed_name, legacy_path)),
"reason": (
"Compatibility index for legacy knowledge base" if legacy_paths else "Minimal KDB"
),
"content": io.yaml_text(_knowledge_base(confirmed_name, legacy_paths)),
}
)
return "kdb/kdb.yaml", changes, forbidden
return target, changes, forbidden
def build_plan(