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:
co-authored by
Claude Opus 5
parent
5bb8914d72
commit
90bf25c49d
+69
-23
@@ -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"):
|
||||||
|
|||||||
Reference in New Issue
Block a user