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>
364 lines
14 KiB
Python
364 lines
14 KiB
Python
"""The adoption compatibility tables, and the safety rules `apply` must enforce.
|
|
|
|
Runbook sections 11.1 and 11.2 are written as tables, and for a long time they
|
|
were only tables: the code implemented some rows, contradicted others and had no
|
|
test that noticed. These cases exist so a row cannot be changed in prose without
|
|
a corresponding branch here failing.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import pytest
|
|
|
|
from stewardship import adoption
|
|
from stewardship.markdown import load_yaml_text
|
|
from stewardship.schema_loader import validate_against_kind
|
|
|
|
CONFORMANT_KDB = """apiVersion: stewardship.corsus.ru/v1alpha1
|
|
kind: KnowledgeBase
|
|
metadata:
|
|
name: sample-kdb
|
|
spec:
|
|
repository: repo:sample
|
|
topics: []
|
|
documents: []
|
|
"""
|
|
|
|
LEGACY_KDB = "custom_format: true\nsections:\n - quick_facts\n"
|
|
|
|
BASE = {"README.md": "# Sample\n", "policies/.gitkeep": ""}
|
|
|
|
|
|
def _plan_for(repo):
|
|
assessment = adoption.assess(repo)
|
|
return assessment, adoption.build_plan(repo, assessment, confirmed_name="sample")
|
|
|
|
|
|
def _actions(plan):
|
|
return {change["path"]: change["action"] for change in plan["changes"]}
|
|
|
|
|
|
def _contract(plan):
|
|
entry = next(c for c in plan["changes"] if c["path"] == "ops/contract.yaml")
|
|
return load_yaml_text(entry["content"])
|
|
|
|
|
|
# --- runbook 11.1: knowledge base compatibility -----------------------------
|
|
|
|
@pytest.mark.parametrize(
|
|
("files", "expected_entrypoint", "expected_actions"),
|
|
[
|
|
pytest.param({}, "kdb/kdb.yaml", {"kdb/kdb.yaml": "create"}, id="no-kdb-creates-one"),
|
|
pytest.param(
|
|
{"kdb/kdb.yaml": CONFORMANT_KDB},
|
|
"kdb/kdb.yaml",
|
|
{"kdb/kdb.yaml": "preserve"},
|
|
id="conformant-kdb-is-kept",
|
|
),
|
|
pytest.param(
|
|
{"kdb.yaml": LEGACY_KDB},
|
|
"kdb/kdb.yaml",
|
|
{"kdb/kdb.yaml": "create", "kdb.yaml": "preserve"},
|
|
id="legacy-elsewhere-gets-an-index",
|
|
),
|
|
pytest.param(
|
|
{"kdb/kdb.yaml": LEGACY_KDB},
|
|
"ops/knowledge.yaml",
|
|
{"ops/knowledge.yaml": "create", "kdb/kdb.yaml": "preserve"},
|
|
id="legacy-occupying-canonical-path-gets-an-adapter",
|
|
),
|
|
pytest.param(
|
|
{"ops/knowledge.yaml": CONFORMANT_KDB},
|
|
"ops/knowledge.yaml",
|
|
{"ops/knowledge.yaml": "preserve"},
|
|
id="conformant-adapter-is-kept",
|
|
),
|
|
pytest.param(
|
|
{"ops/knowledge.yaml": LEGACY_KDB},
|
|
"kdb/kdb.yaml",
|
|
{"kdb/kdb.yaml": "create", "ops/knowledge.yaml": "preserve"},
|
|
id="legacy-occupying-adapter-path-is-not-the-entrypoint",
|
|
),
|
|
pytest.param(
|
|
{"kdb/kdb.yaml": LEGACY_KDB, "ops/knowledge.yaml": CONFORMANT_KDB},
|
|
"ops/knowledge.yaml",
|
|
{"ops/knowledge.yaml": "preserve", "kdb/kdb.yaml": "preserve"},
|
|
id="conformant-adapter-wins-over-legacy-canonical",
|
|
),
|
|
pytest.param(
|
|
{"kdb/kdb.yaml": CONFORMANT_KDB, "ops/knowledge.yaml": LEGACY_KDB},
|
|
"kdb/kdb.yaml",
|
|
{"kdb/kdb.yaml": "preserve", "ops/knowledge.yaml": "preserve"},
|
|
id="conformant-canonical-wins-over-legacy-adapter",
|
|
),
|
|
],
|
|
)
|
|
def test_knowledge_compatibility_table(synthetic_repo, files, expected_entrypoint, expected_actions):
|
|
repo = synthetic_repo({**BASE, **files})
|
|
_, plan = _plan_for(repo)
|
|
actions = _actions(plan)
|
|
|
|
assert _contract(plan)["spec"]["knowledge"]["entrypoint"] == expected_entrypoint
|
|
for path, action in expected_actions.items():
|
|
assert actions[path] == action
|
|
|
|
|
|
def test_legacy_kdb_is_not_declared_conformant(synthetic_repo):
|
|
"""The specific misreading that produced an invalid pilot contract."""
|
|
repo = synthetic_repo({**BASE, "kdb/kdb.yaml": LEGACY_KDB})
|
|
assessment, _ = _plan_for(repo)
|
|
entry = next(e for e in assessment["knowledge"] if e["path"] == "kdb/kdb.yaml")
|
|
assert entry["format"] == "legacy-yaml"
|
|
assert entry["action"] == "wrap"
|
|
|
|
|
|
def test_generated_adapter_registers_the_legacy_file_and_validates(synthetic_repo):
|
|
repo = synthetic_repo({**BASE, "kdb/kdb.yaml": LEGACY_KDB})
|
|
_, plan = _plan_for(repo)
|
|
adapter = next(c for c in plan["changes"] if c["path"] == "ops/knowledge.yaml")
|
|
document = load_yaml_text(adapter["content"])
|
|
|
|
assert validate_against_kind("KnowledgeBase", document) == []
|
|
assert document["spec"]["documents"][0]["path"] == "kdb/kdb.yaml"
|
|
assert "kdb/kdb.yaml" in plan["forbiddenChanges"]
|
|
|
|
|
|
def test_adapter_path_is_not_evidence_of_format(synthetic_repo):
|
|
"""The same misreading as `kdb/kdb.yaml`, one path over.
|
|
|
|
`ops/knowledge.yaml` is where adoption *puts* a generated index; a file
|
|
already sitting there is not one until it validates. Declaring it the
|
|
entrypoint regardless produced a contract that failed the KnowledgeBase
|
|
schema and only surfaced at `verify`.
|
|
"""
|
|
repo = synthetic_repo({**BASE, "ops/knowledge.yaml": LEGACY_KDB})
|
|
assessment, plan = _plan_for(repo)
|
|
|
|
entry = next(e for e in assessment["knowledge"] if e["path"] == "ops/knowledge.yaml")
|
|
assert entry["action"] == "wrap"
|
|
assert _contract(plan)["spec"]["knowledge"]["entrypoint"] == "kdb/kdb.yaml"
|
|
assert "ops/knowledge.yaml" in plan["forbiddenChanges"]
|
|
|
|
index = next(c for c in plan["changes"] if c["path"] == "kdb/kdb.yaml")
|
|
document = load_yaml_text(index["content"])
|
|
assert validate_against_kind("KnowledgeBase", document) == []
|
|
assert document["spec"]["documents"][0]["path"] == "ops/knowledge.yaml"
|
|
|
|
|
|
def test_several_knowledge_sources_are_all_registered(synthetic_repo):
|
|
"""Runbook 11.1, last row: index every source, with an id per document."""
|
|
repo = synthetic_repo(
|
|
{**BASE, "ops/knowledge.yaml": LEGACY_KDB, "kdb.yaml": LEGACY_KDB}
|
|
)
|
|
_, plan = _plan_for(repo)
|
|
|
|
index = next(c for c in plan["changes"] if c["path"] == "kdb/kdb.yaml")
|
|
document = load_yaml_text(index["content"])
|
|
assert validate_against_kind("KnowledgeBase", document) == []
|
|
|
|
indexed = {d["path"] for d in document["spec"]["documents"]}
|
|
assert indexed == {"ops/knowledge.yaml", "kdb.yaml"}
|
|
ids = [d["id"] for d in document["spec"]["documents"]]
|
|
assert len(set(ids)) == len(ids)
|
|
for path in indexed:
|
|
assert path in plan["forbiddenChanges"]
|
|
|
|
|
|
def test_both_canonical_paths_occupied_refuses_to_plan(synthetic_repo):
|
|
"""No canonical path is free, and neither occupant may be overwritten."""
|
|
repo = synthetic_repo(
|
|
{**BASE, "kdb/kdb.yaml": LEGACY_KDB, "ops/knowledge.yaml": LEGACY_KDB}
|
|
)
|
|
assessment = adoption.assess(repo)
|
|
|
|
with pytest.raises(adoption.AdoptionError) as excinfo:
|
|
adoption.build_plan(repo, assessment, confirmed_name="sample")
|
|
assert excinfo.value.code == "ADOPT_KNOWLEDGE_UNRESOLVED"
|
|
|
|
|
|
# --- runbook 11.2: agent entrypoints ----------------------------------------
|
|
|
|
@pytest.mark.parametrize(
|
|
("files", "expected_actions"),
|
|
[
|
|
pytest.param({}, {"AGENTS.md": "create", "CLAUDE.md": "create"}, id="neither-exists"),
|
|
pytest.param(
|
|
{"AGENTS.md": "# Portable\n"},
|
|
{"AGENTS.md": "preserve", "CLAUDE.md": "create"},
|
|
id="portable-only",
|
|
),
|
|
pytest.param(
|
|
{"CLAUDE.md": "# CLAUDE.md\n\nDomain rules.\n"},
|
|
{"AGENTS.md": "create", "CLAUDE.md": "patch-managed-block"},
|
|
id="claude-only-is-patched-not-replaced",
|
|
),
|
|
pytest.param(
|
|
{"AGENTS.md": "# Portable\n", "CLAUDE.md": "# CLAUDE.md\n\nDomain rules.\n"},
|
|
{"AGENTS.md": "preserve", "CLAUDE.md": "patch-managed-block"},
|
|
id="both-exist",
|
|
),
|
|
],
|
|
)
|
|
def test_agent_entrypoint_table(synthetic_repo, files, expected_actions):
|
|
repo = synthetic_repo({**BASE, **files})
|
|
_, plan = _plan_for(repo)
|
|
actions = _actions(plan)
|
|
for path, action in expected_actions.items():
|
|
assert actions[path] == action
|
|
|
|
|
|
def test_patching_claude_keeps_every_existing_line(synthetic_repo):
|
|
original = "# CLAUDE.md\n\nIntro.\n\n## Domain\n\nRules that must survive.\n"
|
|
repo = synthetic_repo({**BASE, "CLAUDE.md": original})
|
|
_, plan = _plan_for(repo)
|
|
adoption.apply_plan(repo, plan, plan["planHash"])
|
|
|
|
patched = (repo / "CLAUDE.md").read_text(encoding="utf-8")
|
|
for line in original.splitlines():
|
|
if line.strip():
|
|
assert line in patched
|
|
assert adoption.MANAGED_BLOCK_START in patched
|
|
|
|
|
|
def test_replanning_after_apply_is_idempotent(synthetic_repo):
|
|
repo = synthetic_repo({**BASE, "CLAUDE.md": "# CLAUDE.md\n\nRules.\n", "kdb/kdb.yaml": LEGACY_KDB})
|
|
_, plan = _plan_for(repo)
|
|
adoption.apply_plan(repo, plan, plan["planHash"])
|
|
|
|
_, second = _plan_for(repo)
|
|
assert set(_actions(second).values()) == {"preserve"}
|
|
|
|
|
|
def test_managed_paths_cover_everything_the_plan_authors(synthetic_repo):
|
|
repo = synthetic_repo({**BASE, "CLAUDE.md": "# CLAUDE.md\n\nRules.\n", "kdb/kdb.yaml": LEGACY_KDB})
|
|
_, plan = _plan_for(repo)
|
|
authored = {
|
|
c["path"] for c in plan["changes"] if c["action"] in ("create", "patch-managed-block")
|
|
}
|
|
assert set(_contract(plan)["spec"]["template"]["managedPaths"]) == authored
|
|
|
|
|
|
# --- apply safety -----------------------------------------------------------
|
|
|
|
def _replanned(plan, **changes):
|
|
"""Re-hash a mutated plan so apply rejects it on its merits, not on the hash."""
|
|
mutated = {**plan, **changes}
|
|
mutated.pop("planHash", None)
|
|
from stewardship import io
|
|
|
|
mutated["planHash"] = io.sha256(mutated)
|
|
return mutated
|
|
|
|
|
|
@pytest.mark.parametrize(
|
|
"escape",
|
|
["../escaped.md", "/etc/escaped.md", "C:/Windows/escaped.md"],
|
|
ids=["parent", "posix-absolute", "windows-absolute"],
|
|
)
|
|
def test_apply_refuses_paths_outside_the_repository(synthetic_repo, escape):
|
|
repo = synthetic_repo(BASE)
|
|
_, plan = _plan_for(repo)
|
|
hostile = _replanned(
|
|
plan,
|
|
changes=[{"action": "create", "path": escape, "ownership": "stewardship", "content": "x"}],
|
|
)
|
|
with pytest.raises(adoption.AdoptionError) as caught:
|
|
adoption.apply_plan(repo, hostile, hostile["planHash"])
|
|
assert caught.value.code == "ADOPT_PATH_OUTSIDE_REPOSITORY"
|
|
|
|
|
|
def test_apply_refuses_to_write_into_a_forbidden_path(synthetic_repo):
|
|
repo = synthetic_repo(BASE)
|
|
_, plan = _plan_for(repo)
|
|
hostile = _replanned(
|
|
plan,
|
|
changes=[
|
|
{"action": "create", "path": "policies/new.yaml", "ownership": "stewardship", "content": "x"}
|
|
],
|
|
forbiddenChanges=["policies/**"],
|
|
)
|
|
with pytest.raises(adoption.AdoptionError) as caught:
|
|
adoption.apply_plan(repo, hostile, hostile["planHash"])
|
|
assert caught.value.code == "ADOPT_FORBIDDEN_PATH"
|
|
|
|
|
|
def test_apply_refuses_when_a_path_it_writes_has_uncommitted_edits(synthetic_repo):
|
|
repo = synthetic_repo({**BASE, "CLAUDE.md": "# CLAUDE.md\n\nRules.\n"})
|
|
_, plan = _plan_for(repo)
|
|
(repo / "CLAUDE.md").write_text("# CLAUDE.md\n\nEditing right now.\n", encoding="utf-8")
|
|
|
|
with pytest.raises(adoption.AdoptionError) as caught:
|
|
adoption.apply_plan(repo, plan, plan["planHash"])
|
|
assert caught.value.code == "ADOPT_WORKTREE_DIRTY"
|
|
|
|
|
|
def test_apply_tolerates_dirt_it_does_not_touch(synthetic_repo):
|
|
repo = synthetic_repo(BASE)
|
|
_, plan = _plan_for(repo)
|
|
(repo / "UNRELATED.md").write_text("still drafting\n", encoding="utf-8")
|
|
|
|
assert "ops/contract.yaml" in adoption.apply_plan(repo, plan, plan["planHash"])
|
|
|
|
|
|
def test_failed_apply_leaves_no_partial_file(synthetic_repo):
|
|
repo = synthetic_repo({**BASE, "CLAUDE.md": "# CLAUDE.md\n\nRules.\n"})
|
|
_, plan = _plan_for(repo)
|
|
broken = _replanned(
|
|
plan,
|
|
changes=[
|
|
{"action": "create", "path": "ops/contract.yaml", "ownership": "stewardship", "content": "ok"},
|
|
{
|
|
"action": "patch-managed-block",
|
|
"path": "CLAUDE.md",
|
|
"ownership": "shared",
|
|
"content": adoption.MANAGED_BLOCK_START + "\nunterminated",
|
|
},
|
|
],
|
|
)
|
|
with pytest.raises(adoption.AdoptionError):
|
|
adoption.apply_plan(repo, broken, broken["planHash"])
|
|
|
|
assert not (repo / "ops" / "contract.yaml").exists()
|
|
assert (repo / "CLAUDE.md").read_text(encoding="utf-8") == "# CLAUDE.md\n\nRules.\n"
|
|
|
|
|
|
# --- verify -----------------------------------------------------------------
|
|
|
|
def test_verify_fails_when_a_preserved_file_was_modified(synthetic_repo):
|
|
repo = synthetic_repo({**BASE, "kdb/kdb.yaml": LEGACY_KDB})
|
|
_, plan = _plan_for(repo)
|
|
adoption.apply_plan(repo, plan, plan["planHash"])
|
|
assert adoption.verify(repo, plan)["outcome"] == "pass"
|
|
|
|
(repo / "kdb" / "kdb.yaml").write_text("tampered: true\n", encoding="utf-8")
|
|
report = adoption.verify(repo, plan)
|
|
assert report["outcome"] == "fail"
|
|
assert "ADOPT_PRESERVED_MODIFIED" in report["unresolvedFindings"]
|
|
|
|
|
|
def test_verify_without_a_plan_says_it_verified_nothing(synthetic_repo):
|
|
repo = synthetic_repo(BASE)
|
|
_, plan = _plan_for(repo)
|
|
adoption.apply_plan(repo, plan, plan["planHash"])
|
|
|
|
report = adoption.verify(repo)
|
|
assert "ADOPT_REPORT_UNSCOPED" in report["unresolvedFindings"]
|
|
|
|
|
|
# --- schemas ----------------------------------------------------------------
|
|
|
|
def test_adoption_outputs_match_their_schemas(synthetic_repo):
|
|
repo = synthetic_repo({**BASE, "kdb/kdb.yaml": LEGACY_KDB, "CLAUDE.md": "# CLAUDE.md\n\nRules.\n"})
|
|
assessment, plan = _plan_for(repo)
|
|
assert validate_against_kind("AdoptionAssessment", assessment) == []
|
|
assert validate_against_kind("AdoptionPlan", plan) == []
|
|
|
|
adoption.apply_plan(repo, plan, plan["planHash"])
|
|
assert validate_against_kind("AdoptionReport", adoption.verify(repo, plan)) == []
|
|
|
|
|
|
def test_generated_contract_matches_its_schema(synthetic_repo):
|
|
repo = synthetic_repo({**BASE, "kdb/kdb.yaml": LEGACY_KDB})
|
|
_, plan = _plan_for(repo)
|
|
assert validate_against_kind("RepositoryContract", _contract(plan)) == []
|