test(adopt): bind the compatibility tables to code, and check apply's safety

Runbook 11.1 and 11.2 are decision tables, and nothing tied them to branches:
the two existing antivirus-legacy tests asserted only that kdb/kdb.yaml was
preserved, which stayed true while the surrounding behaviour was wrong. These
cases are parametrized over the table rows so prose and code cannot drift apart
again without a failure.

Writing them found two defects that no existing test could see. splice_managed_block
validated the file it patched but never the block being inserted, so a
hand-edited plan carrying unbalanced markers would have been written in and only
failed on a later run. And the adoption output schemas were validated nowhere,
which had let the richer content roots from the previous commit silently stop
conforming to AdoptionAssessment.

- table-driven coverage of the knowledge and agent-entrypoint rows
- path escape, forbidden path, dirty gate, rollback and preserve-tampering cases
- schema conformance for assessment, plan, report and the generated contract
- widen proposedContentRoots for writePolicy/generatedFrom, and constrain
  authority to the enum it always should have used
- add a synthetic_repo fixture instead of a fourth copy of git init

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Alexander Baranov
2026-08-24 18:48:54 +03:00
co-authored by Claude Opus 5
parent 005419a0ba
commit e5a42fa446
4 changed files with 325 additions and 1 deletions
+24
View File
@@ -34,6 +34,30 @@ def make_repo(tmp_path):
return _make
@pytest.fixture
def synthetic_repo(tmp_path):
"""Build a repository from an explicit path -> content mapping.
The checked-in fixtures cover two concrete legacy layouts; the adoption
compatibility tables need many small permutations of knowledge files and
agent entrypoints, which are clearer written inline than as dozens of
near-identical fixture trees.
"""
def _make(files: dict[str, str], *, name: str = "repo", git: bool = True) -> Path:
dest = tmp_path / name
dest.mkdir(parents=True, exist_ok=True)
for relative, content in files.items():
target = dest / relative
target.parent.mkdir(parents=True, exist_ok=True)
target.write_text(content, encoding="utf-8")
if git:
_git_init(dest)
return dest
return _make
@pytest.fixture
def negative_repo(tmp_path):
"""Materialize a negative/<name>/contract.yaml fixture as ops/contract.yaml under a fresh repo."""
+286
View File
@@ -0,0 +1,286 @@
"""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",
),
],
)
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"]
# --- 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)) == []