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 <noreply@anthropic.com>
This commit is contained in:
Alexander Baranov
2026-08-24 18:29:07 +03:00
co-authored by Claude Opus 5
parent c918bd8373
commit 5bb8914d72
+131 -47
View File
@@ -16,7 +16,9 @@ from typing import Any
from . import gitutil, io from . import gitutil, io
from .bootstrap import BootstrapAnswers, render_agents_md, render_claude_md from .bootstrap import BootstrapAnswers, render_agents_md, render_claude_md
from .constants import API_VERSION from .constants import API_VERSION
from .io import ResourceError
from .paths import PathViolation, confined_path from .paths import PathViolation, confined_path
from .schema_loader import validate_against_kind
from .validate import validate_repository from .validate import validate_repository
MANAGED_BLOCK_START = "<!-- stewardship:managed:start -->" MANAGED_BLOCK_START = "<!-- stewardship:managed:start -->"
@@ -130,6 +132,29 @@ def _detect_secret_shaped_paths(root: Path) -> list[tuple[str, bool]]:
return found 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]]: def _classify_type(root: Path) -> tuple[str, str, list[str]]:
scores: dict[str, list[str]] = {t: [] for t, _ in _TYPE_EVIDENCE} scores: dict[str, list[str]] = {t: [] for t, _ in _TYPE_EVIDENCE}
for repo_type, markers 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" canonical_direction = "agents-only"
knowledge: list[dict[str, Any]] = [] knowledge: list[dict[str, Any]] = []
if (root / "kdb" / "kdb.yaml").exists(): for rel in ("kdb/kdb.yaml", "kdb.yaml", "ops/knowledge.yaml"):
knowledge.append({"path": "kdb/kdb.yaml", "format": "stewardship-yaml", "action": "keep-or-validate"}) if not (root / rel).exists():
elif (root / "kdb.yaml").exists(): continue
knowledge.append({"path": "kdb.yaml", "format": "legacy-yaml", "action": "wrap"}) entry = _knowledge_entry(root, rel)
findings.append(_finding("info", "ADOPT_KDB_LEGACY", "kdb.yaml")) knowledge.append(entry)
if (root / "ops" / "knowledge.yaml").exists(): if entry["action"] == "wrap":
knowledge.append({"path": "ops/knowledge.yaml", "format": "stewardship-yaml", "action": "keep-or-validate"}) findings.append(_finding("info", "ADOPT_KDB_LEGACY", rel))
proposed_content_roots: list[dict[str, Any]] = [] proposed_content_roots: list[dict[str, Any]] = []
for repo_type, markers in _TYPE_EVIDENCE: 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( def build_plan(
root: Path, root: Path,
assessment: dict[str, Any], assessment: dict[str, Any],
@@ -272,6 +389,11 @@ def build_plan(
for cr in content_roots: for cr in content_roots:
forbidden.append(f"{cr['path']}/**") forbidden.append(f"{cr['path']}/**")
knowledge_entrypoint, knowledge_changes, knowledge_forbidden = _plan_knowledge(
assessment, confirmed_name
)
forbidden.extend(knowledge_forbidden)
if not contract_exists: if not contract_exists:
contract = { contract = {
"apiVersion": API_VERSION, "apiVersion": API_VERSION,
@@ -295,7 +417,7 @@ def build_plan(
"managedPaths": ["ops/contract.yaml"], "managedPaths": ["ops/contract.yaml"],
}, },
"agent": {"primary": "CLAUDE.md", "portable": "AGENTS.md"}, "agent": {"primary": "CLAUDE.md", "portable": "AGENTS.md"},
"knowledge": {"entrypoint": _knowledge_entrypoint(assessment)}, "knowledge": {"entrypoint": knowledge_entrypoint},
"contentRoots": content_roots, "contentRoots": content_roots,
}, },
} }
@@ -303,38 +425,7 @@ def build_plan(
else: else:
changes.append({"action": "preserve", "path": "ops/contract.yaml", "ownership": "repository"}) changes.append({"action": "preserve", "path": "ops/contract.yaml", "ownership": "repository"})
kdb_entries = assessment.get("knowledge", []) changes.extend(knowledge_changes)
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"})
if not (root / "AGENTS.md").exists(): if not (root / "AGENTS.md").exists():
answers = BootstrapAnswers( answers = BootstrapAnswers(
@@ -378,13 +469,6 @@ def build_plan(
return 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: def is_forbidden(rel_path: str, forbidden: list[str]) -> bool:
"""True when ``rel_path`` is covered by any ``forbiddenChanges`` pattern.""" """True when ``rel_path`` is covered by any ``forbiddenChanges`` pattern."""
return any(fnmatch.fnmatch(rel_path, pattern) for pattern in forbidden) return any(fnmatch.fnmatch(rel_path, pattern) for pattern in forbidden)