feat(adopt): point an existing CLAUDE.md at the contract, and derive managedPaths

Runbook 11.2 says an existing shared entrypoint should gain a narrow managed
block rather than be replaced, but build_plan only ever chose between "create"
and "preserve", so a repository that already had CLAUDE.md was adopted without
any pointer to its own contract -- an agent kept reading the large legacy
document first, which is the cost adoption was supposed to remove. The
patch-managed-block action existed in the schema and in apply_plan with nothing
producing it.

managedPaths was hardcoded to ops/contract.yaml even though the plan already
knows every file it authors, so the contract understated what adoption owns and
the missing entries had to be added by hand afterwards.

- emit patch-managed-block for an existing CLAUDE.md, and preserve when the
  block is already current, which makes re-planning idempotent
- assemble the contract last so managedPaths is derived from the actual changes
- keep the pointer block ASCII, matching the earlier em-dash cleanup

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Alexander Baranov
2026-08-24 18:31:53 +03:00
co-authored by Claude Opus 5
parent 5bb8914d72
commit 90bf25c49d
+69 -23
View File
@@ -66,8 +66,8 @@ def splice_managed_block(text: str, block: str) -> str:
end = text.index(MANAGED_BLOCK_END) + len(MANAGED_BLOCK_END) end = text.index(MANAGED_BLOCK_END) + len(MANAGED_BLOCK_END)
if end < start: if end < start:
raise AdoptionError("ADOPT_MANAGED_BLOCK_MALFORMED", "End marker precedes start marker") raise AdoptionError("ADOPT_MANAGED_BLOCK_MALFORMED", "End marker precedes start marker")
tail = text[end:].removeprefix("\n") tail = text[end:].lstrip("\n")
return text[:start] + normalized + tail return text[:start] + normalized + ("\n" + tail if tail else "")
lines = text.splitlines(keepends=True) lines = text.splitlines(keepends=True)
for position, line in enumerate(lines): for position, line in enumerate(lines):
@@ -75,8 +75,15 @@ def splice_managed_block(text: str, block: str) -> str:
insert_at = position + 1 insert_at = position + 1
if insert_at < len(lines) and not lines[insert_at].strip(): if insert_at < len(lines) and not lines[insert_at].strip():
insert_at += 1 insert_at += 1
return "".join(lines[:insert_at]) + "\n" + normalized + "".join(lines[insert_at:]) head = "".join(lines[:insert_at])
return normalized + "\n" + text if not head.endswith("\n"):
head += "\n"
if not head.endswith("\n\n"):
head += "\n"
tail = "".join(lines[insert_at:]).lstrip("\n")
return head + normalized + ("\n" + tail if tail else "")
tail = text.lstrip("\n")
return normalized + ("\n" + tail if tail else "")
_COLLISION_PATHS = [ _COLLISION_PATHS = [
@@ -265,6 +272,21 @@ def assess(root: Path) -> dict[str, Any]:
} }
def _entrypoint_pointer_block(knowledge_entrypoint: str) -> str:
"""The managed block adoption adds to an existing primary agent entrypoint."""
return render_managed_block(
f"""## Repository Stewardship
This repository is adopted at L1. Before reading anything else:
- `ops/contract.yaml` names the repository, its owner and its content roots.
- `{knowledge_entrypoint}` is the knowledge index; match the task to a topic
intent and open only what that topic names.
- `repoctl context --repo . --intent <intent>` returns just the context an
intent needs, instead of the whole knowledge base."""
)
def _knowledge_base(name: str, legacy_path: str | None) -> dict[str, Any]: def _knowledge_base(name: str, legacy_path: str | None) -> dict[str, Any]:
"""A minimal KnowledgeBase, indexing ``legacy_path`` when one was found. """A minimal KnowledgeBase, indexing ``legacy_path`` when one was found.
@@ -394,6 +416,46 @@ def build_plan(
) )
forbidden.extend(knowledge_forbidden) forbidden.extend(knowledge_forbidden)
changes.extend(knowledge_changes)
if not (root / "AGENTS.md").exists():
answers = BootstrapAnswers(
name=confirmed_name, title=confirmed_title or confirmed_name, owners=confirmed_owners or [],
repository_type=assessment["classification"]["proposedType"], lifecycle=confirmed_lifecycle,
)
changes.append({"action": "create", "path": "AGENTS.md", "ownership": "shared", "content": render_agents_md(answers)})
else:
changes.append({"action": "preserve", "path": "AGENTS.md", "ownership": "repository"})
claude_path = root / "CLAUDE.md"
if not claude_path.exists():
changes.append({"action": "create", "path": "CLAUDE.md", "ownership": "shared", "content": render_claude_md()})
else:
# An existing Claude entrypoint keeps its content; adoption only adds a
# short pointer so an agent finds the contract before it starts reading
# whatever large document the repository routes through.
block = _entrypoint_pointer_block(knowledge_entrypoint)
current = claude_path.read_text(encoding="utf-8", errors="ignore")
if splice_managed_block(current, block) == current:
changes.append({"action": "preserve", "path": "CLAUDE.md", "ownership": "repository"})
else:
changes.append(
{
"action": "patch-managed-block",
"path": "CLAUDE.md",
"ownership": "shared",
"reason": "Point the primary agent entrypoint at the contract and knowledge index",
"content": block,
}
)
# The contract is assembled last because managedPaths is a statement about
# the rest of the plan: anything this adoption authors, it owns.
managed_paths = ["ops/contract.yaml"] + [
change["path"]
for change in changes
if change["action"] in ("create", "patch-managed-block")
]
if not contract_exists: if not contract_exists:
contract = { contract = {
"apiVersion": API_VERSION, "apiVersion": API_VERSION,
@@ -414,32 +476,16 @@ def build_plan(
"version": "0.1.0", "version": "0.1.0",
"source": "repo:repository-stewardship", "source": "repo:repository-stewardship",
"mode": "adopted-overlay", "mode": "adopted-overlay",
"managedPaths": ["ops/contract.yaml"], "managedPaths": sorted(dict.fromkeys(managed_paths)),
}, },
"agent": {"primary": "CLAUDE.md", "portable": "AGENTS.md"}, "agent": {"primary": "CLAUDE.md", "portable": "AGENTS.md"},
"knowledge": {"entrypoint": knowledge_entrypoint}, "knowledge": {"entrypoint": knowledge_entrypoint},
"contentRoots": content_roots, "contentRoots": content_roots,
}, },
} }
changes.append({"action": "create", "path": "ops/contract.yaml", "ownership": "stewardship", "content": io.yaml_text(contract)}) changes.insert(0, {"action": "create", "path": "ops/contract.yaml", "ownership": "stewardship", "content": io.yaml_text(contract)})
else: else:
changes.append({"action": "preserve", "path": "ops/contract.yaml", "ownership": "repository"}) changes.insert(0, {"action": "preserve", "path": "ops/contract.yaml", "ownership": "repository"})
changes.extend(knowledge_changes)
if not (root / "AGENTS.md").exists():
answers = BootstrapAnswers(
name=confirmed_name, title=confirmed_title or confirmed_name, owners=confirmed_owners or [],
repository_type=assessment["classification"]["proposedType"], lifecycle=confirmed_lifecycle,
)
changes.append({"action": "create", "path": "AGENTS.md", "ownership": "shared", "content": render_agents_md(answers)})
else:
changes.append({"action": "preserve", "path": "AGENTS.md", "ownership": "repository"})
if not (root / "CLAUDE.md").exists():
changes.append({"action": "create", "path": "CLAUDE.md", "ownership": "shared", "content": render_claude_md()})
else:
changes.append({"action": "preserve", "path": "CLAUDE.md", "ownership": "repository"})
preserved_already = {c["path"] for c in changes if c["action"] == "preserve"} preserved_already = {c["path"] for c in changes if c["action"] == "preserve"}
for rel in ("kdb.yaml", "profiles-source", "profiles"): for rel in ("kdb.yaml", "profiles-source", "profiles"):