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 . 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)
|
||||||
|
|||||||
Reference in New Issue
Block a user