fix(adopt): decide the adapter path by content too

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>
This commit is contained in:
Alexander Baranov
2026-08-24 22:56:50 +03:00
co-authored by Claude Opus 5
parent 1974155281
commit 6c6dfb6fb6
3 changed files with 162 additions and 42 deletions
+77
View File
@@ -67,6 +67,30 @@ def _contract(plan):
{"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):
@@ -99,6 +123,59 @@ def test_generated_adapter_registers_the_legacy_file_and_validates(synthetic_rep
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(