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:
co-authored by
Claude Opus 5
parent
c918bd8373
commit
5bb8914d72
+131
-47
@@ -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 = "<!-- stewardship:managed: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)
|
||||
|
||||
Reference in New Issue
Block a user