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
+12
View File
@@ -54,6 +54,18 @@ def splice_managed_block(text: str, block: str) -> str:
agent reads it first. Malformed or duplicated markers raise rather than agent reads it first. Malformed or duplicated markers raise rather than
guess at the author's intent. guess at the author's intent.
""" """
# The block arrives from a plan file, which can be hand-edited: inserting one
# with unbalanced markers would corrupt the boundary this function relies on
# and only fail on some later run.
if block.count(MANAGED_BLOCK_START) != 1 or block.count(MANAGED_BLOCK_END) != 1:
raise AdoptionError(
"ADOPT_MANAGED_BLOCK_MALFORMED", "Replacement block must carry exactly one marker pair"
)
if block.index(MANAGED_BLOCK_END) < block.index(MANAGED_BLOCK_START):
raise AdoptionError(
"ADOPT_MANAGED_BLOCK_MALFORMED", "Replacement block ends before it starts"
)
start_count = text.count(MANAGED_BLOCK_START) start_count = text.count(MANAGED_BLOCK_START)
end_count = text.count(MANAGED_BLOCK_END) end_count = text.count(MANAGED_BLOCK_END)
if start_count > 1 or end_count > 1: if start_count > 1 or end_count > 1:
@@ -60,7 +60,9 @@
"id": { "type": "string" }, "id": { "type": "string" },
"path": { "type": "string" }, "path": { "type": "string" },
"role": { "type": "string" }, "role": { "type": "string" },
"authority": { "type": "string" } "authority": { "enum": ["source", "generated", "observed", "mirror", "evidence"] },
"writePolicy": { "enum": ["managed", "read-only", "generated"] },
"generatedFrom": { "type": "array", "items": { "type": "string" } }
} }
} }
}, },
+24
View File
@@ -34,6 +34,30 @@ def make_repo(tmp_path):
return _make 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 @pytest.fixture
def negative_repo(tmp_path): def negative_repo(tmp_path):
"""Materialize a negative/<name>/contract.yaml fixture as ops/contract.yaml under a fresh repo.""" """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)) == []