"""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", confirmed_owners=["platform"]) 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", confirmed_owners=["platform"]) 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)) == []