Running a full assess -> plan -> apply -> verify against Infra/LXD and Infra/Docker in throwaway worktrees, and a bootstrap into a scratch directory, surfaced the same two mistakes repeated across both commands: a shape was read where evidence was available, and a missing answer became a silent default rather than a refusal. adopt: - classify secret-shaped paths by content, not by filename. A live credential blocks; a file tracked against the repository's own ignore rules and a name-only match are warnings; findings name keys, never values. In Infra/Docker this turned 14 false blockers into 2 true ones and surfaced 14 files committed despite `**/.env`. - carry assess findings into the plan and refuse while an error-severity finding is unresolved. An owner may accept one through `acknowledgedFindings` with a reason; the acknowledgement enters the plan and therefore planHash, so approval covers it. - derive metadata.name from the git remote instead of the clone directory, and refuse to plan without a confirmed owner (runbook section 9). - propose content roots from the whole content vocabulary rather than the winning type's markers, and recognise N sibling directories sharing a marker file as one file-set root with a selector, as runbook 7.2 already specified. Authority defaulted rather than derived now asks. init: apply the guards adopt already had. Answers are validated against the vocabularies that already existed in constants (name, type, lifecycle, access) so init can no longer create a repository that fails its own validate; owners are required; a directory that already holds the planned paths is refused at plan time and pointed at adopt; and every path from a plan is confined before the first byte is written -- init wrote outside the repository from an edited plan. validate: mask fenced blocks and inline code spans before scanning for Markdown links. A PowerShell snippet in Infra/Docker's CLAUDE.md parsed as a link and kept validate red for a reason unrelated to the repository. paths: allow "." as a whole content-root path, never as a segment, so the file-set root runbook 7.2 describes can be declared. 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", 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)) == []
|