From 90bf25c49dda165f5cc13cdadb7efa0cea82b61f Mon Sep 17 00:00:00 2001 From: Alexander Baranov Date: Mon, 24 Aug 2026 18:31:53 +0300 Subject: [PATCH] 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 --- src/stewardship/adoption.py | 92 +++++++++++++++++++++++++++---------- 1 file changed, 69 insertions(+), 23 deletions(-) diff --git a/src/stewardship/adoption.py b/src/stewardship/adoption.py index cf4c2bc..74d496c 100644 --- a/src/stewardship/adoption.py +++ b/src/stewardship/adoption.py @@ -66,8 +66,8 @@ def splice_managed_block(text: str, block: str) -> str: end = text.index(MANAGED_BLOCK_END) + len(MANAGED_BLOCK_END) if end < start: raise AdoptionError("ADOPT_MANAGED_BLOCK_MALFORMED", "End marker precedes start marker") - tail = text[end:].removeprefix("\n") - return text[:start] + normalized + tail + tail = text[end:].lstrip("\n") + return text[:start] + normalized + ("\n" + tail if tail else "") lines = text.splitlines(keepends=True) for position, line in enumerate(lines): @@ -75,8 +75,15 @@ def splice_managed_block(text: str, block: str) -> str: insert_at = position + 1 if insert_at < len(lines) and not lines[insert_at].strip(): insert_at += 1 - return "".join(lines[:insert_at]) + "\n" + normalized + "".join(lines[insert_at:]) - return normalized + "\n" + text + head = "".join(lines[:insert_at]) + 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 = [ @@ -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 ` 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]: """A minimal KnowledgeBase, indexing ``legacy_path`` when one was found. @@ -394,6 +416,46 @@ def build_plan( ) 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: contract = { "apiVersion": API_VERSION, @@ -414,32 +476,16 @@ def build_plan( "version": "0.1.0", "source": "repo:repository-stewardship", "mode": "adopted-overlay", - "managedPaths": ["ops/contract.yaml"], + "managedPaths": sorted(dict.fromkeys(managed_paths)), }, "agent": {"primary": "CLAUDE.md", "portable": "AGENTS.md"}, "knowledge": {"entrypoint": knowledge_entrypoint}, "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: - changes.append({"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"}) + changes.insert(0, {"action": "preserve", "path": "ops/contract.yaml", "ownership": "repository"}) preserved_already = {c["path"] for c in changes if c["action"] == "preserve"} for rel in ("kdb.yaml", "profiles-source", "profiles"):