From 5bb8914d72351ca0305489363bceaf7bc398576d Mon Sep 17 00:00:00 2001 From: Alexander Baranov Date: Mon, 24 Aug 2026 18:29:07 +0300 Subject: [PATCH] fix(adopt): decide KDB treatment by content, and implement runbook 11.1 assess declared kdb/kdb.yaml conformant on the strength of its path alone and never parsed it, so a legacy custom knowledge base was reported as stewardship-yaml and the contract was pointed straight at a file that fails the KnowledgeBase schema. The row of runbook 11.1 covering exactly that case -- a legacy KDB already occupying the canonical path -- had no branch in the code at all, and _knowledge_entrypoint could not have helped: both of its branches returned the same literal, so the loop was dead and the answer was always kdb/kdb.yaml. Learned that this is what made the pilot adoption of Services/Antivirus produce an invalid contract that only surfaced at verify, and had to be repaired by hand outside the approved plan hash. - classify a knowledge file by validating it against the KnowledgeBase schema - when a legacy KDB occupies kdb/kdb.yaml, index it from a new ops/knowledge.yaml, preserve the original and forbid writes to it - generate empty topics deliberately: which sections matter is not inferable - delete _knowledge_entrypoint and derive the entrypoint from the same decision Co-Authored-By: Claude Opus 5 --- src/stewardship/adoption.py | 178 ++++++++++++++++++++++++++---------- 1 file changed, 131 insertions(+), 47 deletions(-) diff --git a/src/stewardship/adoption.py b/src/stewardship/adoption.py index b778599..cf4c2bc 100644 --- a/src/stewardship/adoption.py +++ b/src/stewardship/adoption.py @@ -16,7 +16,9 @@ from typing import Any from . import gitutil, io from .bootstrap import BootstrapAnswers, render_agents_md, render_claude_md from .constants import API_VERSION +from .io import ResourceError from .paths import PathViolation, confined_path +from .schema_loader import validate_against_kind from .validate import validate_repository MANAGED_BLOCK_START = "" @@ -130,6 +132,29 @@ def _detect_secret_shaped_paths(root: Path) -> list[tuple[str, bool]]: return found +def _knowledge_format(path: Path) -> str: + """Return ``stewardship-yaml`` only when the file really is a KnowledgeBase. + + Location is not evidence of format: a repository may keep a large custom + knowledge file at the canonical path (runbook 11.1). Deciding by path alone + is what made adoption declare a legacy file conformant and then point the + contract at it, so validate the content against the schema instead. + """ + try: + data = io.load_yaml(path) + except ResourceError: + return "unparseable" + if not isinstance(data, dict): + return "legacy-yaml" + return "legacy-yaml" if validate_against_kind("KnowledgeBase", data) else "stewardship-yaml" + + +def _knowledge_entry(root: Path, rel: str) -> dict[str, str]: + fmt = _knowledge_format(root / rel) + action = "keep-or-validate" if fmt == "stewardship-yaml" else "wrap" + return {"path": rel, "format": fmt, "action": action} + + def _classify_type(root: Path) -> tuple[str, str, list[str]]: scores: dict[str, list[str]] = {t: [] for t, _ in _TYPE_EVIDENCE} for repo_type, markers in _TYPE_EVIDENCE: @@ -177,13 +202,13 @@ def assess(root: Path) -> dict[str, Any]: canonical_direction = "agents-only" knowledge: list[dict[str, Any]] = [] - if (root / "kdb" / "kdb.yaml").exists(): - knowledge.append({"path": "kdb/kdb.yaml", "format": "stewardship-yaml", "action": "keep-or-validate"}) - elif (root / "kdb.yaml").exists(): - knowledge.append({"path": "kdb.yaml", "format": "legacy-yaml", "action": "wrap"}) - findings.append(_finding("info", "ADOPT_KDB_LEGACY", "kdb.yaml")) - if (root / "ops" / "knowledge.yaml").exists(): - knowledge.append({"path": "ops/knowledge.yaml", "format": "stewardship-yaml", "action": "keep-or-validate"}) + for rel in ("kdb/kdb.yaml", "kdb.yaml", "ops/knowledge.yaml"): + if not (root / rel).exists(): + continue + entry = _knowledge_entry(root, rel) + knowledge.append(entry) + if entry["action"] == "wrap": + findings.append(_finding("info", "ADOPT_KDB_LEGACY", rel)) proposed_content_roots: list[dict[str, Any]] = [] for repo_type, markers in _TYPE_EVIDENCE: @@ -240,6 +265,98 @@ def assess(root: Path) -> dict[str, Any]: } +def _knowledge_base(name: str, legacy_path: str | None) -> dict[str, Any]: + """A minimal KnowledgeBase, indexing ``legacy_path`` when one was found. + + 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", + } + ) + return { + "apiVersion": API_VERSION, + "kind": "KnowledgeBase", + "metadata": {"name": f"{name}-knowledge-index"}, + "spec": { + "repository": f"repo:{name}", + "defaultLanguage": "en", + "topics": [], + "documents": documents, + }, + } + + +def _plan_knowledge( + assessment: dict[str, Any], confirmed_name: str +) -> tuple[str, list[dict[str, Any]], list[str]]: + """Choose the knowledge entrypoint and the changes that establish it. + + This is the compatibility table in runbook 11.1 expressed as code. The row + that matters most here is the last one: when a legacy or custom knowledge + base already occupies ``kdb/kdb.yaml`` it is indexed from a new + ``ops/knowledge.yaml`` and left untouched, never rewritten and never + declared conformant. + """ + entries = {entry["path"]: entry for entry in assessment.get("knowledge", [])} + changes: list[dict[str, Any]] = [] + forbidden: list[str] = [] + + canonical = entries.get("kdb/kdb.yaml") + 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"}) + if canonical is not None: + changes.append({"action": "preserve", "path": "kdb/kdb.yaml", "ownership": "repository"}) + forbidden.append("kdb/kdb.yaml") + 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"}) + 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")), + } + ) + 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) + changes.append( + { + "action": "create", + "path": "kdb/kdb.yaml", + "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)), + } + ) + return "kdb/kdb.yaml", changes, forbidden + + def build_plan( root: Path, assessment: dict[str, Any], @@ -272,6 +389,11 @@ def build_plan( for cr in content_roots: forbidden.append(f"{cr['path']}/**") + knowledge_entrypoint, knowledge_changes, knowledge_forbidden = _plan_knowledge( + assessment, confirmed_name + ) + forbidden.extend(knowledge_forbidden) + if not contract_exists: contract = { "apiVersion": API_VERSION, @@ -295,7 +417,7 @@ def build_plan( "managedPaths": ["ops/contract.yaml"], }, "agent": {"primary": "CLAUDE.md", "portable": "AGENTS.md"}, - "knowledge": {"entrypoint": _knowledge_entrypoint(assessment)}, + "knowledge": {"entrypoint": knowledge_entrypoint}, "contentRoots": content_roots, }, } @@ -303,38 +425,7 @@ def build_plan( else: changes.append({"action": "preserve", "path": "ops/contract.yaml", "ownership": "repository"}) - kdb_entries = assessment.get("knowledge", []) - kdb_paths = {entry["path"] for entry in kdb_entries} - if "kdb/kdb.yaml" not in kdb_paths: - legacy = next((e for e in kdb_entries if e["action"] == "wrap"), None) - kdb: dict[str, Any] = { - "apiVersion": API_VERSION, - "kind": "KnowledgeBase", - "metadata": {"name": f"{confirmed_name}-knowledge-index"}, - "spec": { - "repository": f"repo:{confirmed_name}", - "defaultLanguage": "en", - "topics": [], - "documents": [], - }, - } - target_kdb_path = "kdb/kdb.yaml" - if legacy: - kdb["spec"]["documents"].append( - { - "id": "legacy-knowledge-base", - "title": "Existing knowledge base", - "role": "reference", - "path": legacy["path"], - "mediaType": "application/yaml", - "authority": "local-canonical", - "status": "verified", - } - ) - forbidden.append(legacy["path"]) - changes.append({"action": "create", "path": target_kdb_path, "ownership": "stewardship", "reason": "Compatibility index for legacy knowledge base" if legacy else "Minimal KDB", "content": io.yaml_text(kdb)}) - else: - changes.append({"action": "preserve", "path": "kdb/kdb.yaml", "ownership": "repository"}) + changes.extend(knowledge_changes) if not (root / "AGENTS.md").exists(): answers = BootstrapAnswers( @@ -378,13 +469,6 @@ def build_plan( return plan -def _knowledge_entrypoint(assessment: dict[str, Any]) -> str: - for entry in assessment.get("knowledge", []): - if entry["path"] == "kdb/kdb.yaml": - return "kdb/kdb.yaml" - return "kdb/kdb.yaml" - - def is_forbidden(rel_path: str, forbidden: list[str]) -> bool: """True when ``rel_path`` is covered by any ``forbiddenChanges`` pattern.""" return any(fnmatch.fnmatch(rel_path, pattern) for pattern in forbidden)