Files
repoctl/src/stewardship/adoption.py
T
Alexander BaranovandClaude Opus 5 523ef61fe3 feat(adopt): let the owner answer the type question assess asks
assess sets confirmationRequired and asks "Confirm repository type" whenever
confidence is below high, but there was no way to answer it: --answers read only
name, title, owners and lifecycle, and build_plan took the type solely from the
classifier's guess. The confirmation boundary in runbook section 9 could not be
closed through the tool, and nothing in the resulting contract distinguished a
deliberate decision from an unreviewed low-confidence default.

- accept the type via --type or a repositoryType answer, validated against the
  known set rather than written through unchecked
- record classification, confidence and evidence in metadata.annotations, which
  the schema already allows as a free-form object
- omit any timestamp so re-planning stays deterministic and planHash stable

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-24 18:33:42 +03:00

650 lines
26 KiB
Python

"""`repoctl adopt`: assess -> plan -> apply -> verify for an existing repository.
Follows docs/adoption-runbook.md. Default strategy is `overlay`: it only adds
stewardship metadata and never moves, deletes or renames existing files. The
`documents-to-content-root` normalization recipe is a separate, explicitly opted-in
path (not implemented as an automatic heuristic) and is intentionally out of scope
for this first cut beyond structural support in the AdoptionPlan schema.
"""
from __future__ import annotations
import fnmatch
from pathlib import Path
from typing import Any
from . import gitutil, io
from .bootstrap import BootstrapAnswers, render_agents_md, render_claude_md
from .constants import API_VERSION
from .io import ResourceError
from .paths import PathViolation, confined_path
from .schema_loader import validate_against_kind
from .validate import validate_repository
MANAGED_BLOCK_START = "<!-- stewardship:managed:start -->"
MANAGED_BLOCK_END = "<!-- stewardship:managed:end -->"
class AdoptionError(ValueError):
"""An adoption step refused to proceed, carrying a stable finding code.
Subclasses ``ValueError`` so existing callers that catch ``ValueError`` keep
working, while ``code`` lets the CLI report the precise reason instead of
guessing one from the message text.
"""
def __init__(self, code: str, message: str) -> None:
super().__init__(f"{code}: {message}")
self.code = code
def render_managed_block(body: str) -> str:
"""Wrap ``body`` in the stewardship managed-block markers."""
return f"{MANAGED_BLOCK_START}\n{body.strip()}\n{MANAGED_BLOCK_END}\n"
def splice_managed_block(text: str, block: str) -> str:
"""Insert or replace the managed block inside ``text``, leaving the rest intact.
Adoption must never rewrite a shared agent entrypoint wholesale (runbook
section 3 and 11.2), so this only ever touches the marked region. When no
markers are present the block is inserted just below the first level-1
heading, keeping the stewardship pointer above the document body where an
agent reads it first. Malformed or duplicated markers raise rather than
guess at the author's intent.
"""
start_count = text.count(MANAGED_BLOCK_START)
end_count = text.count(MANAGED_BLOCK_END)
if start_count > 1 or end_count > 1:
raise AdoptionError("ADOPT_MANAGED_BLOCK_MALFORMED", "Duplicate managed-block markers")
if bool(start_count) != bool(end_count):
raise AdoptionError("ADOPT_MANAGED_BLOCK_MALFORMED", "Unpaired managed-block marker")
normalized = block if block.endswith("\n") else block + "\n"
if start_count == 1:
start = text.index(MANAGED_BLOCK_START)
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:].lstrip("\n")
return text[:start] + normalized + ("\n" + tail if tail else "")
lines = text.splitlines(keepends=True)
for position, line in enumerate(lines):
if line.startswith("# "):
insert_at = position + 1
if insert_at < len(lines) and not lines[insert_at].strip():
insert_at += 1
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 = [
"ops/contract.yaml",
"kdb/kdb.yaml",
"kdb.yaml",
"CLAUDE.md",
"AGENTS.md",
".claude/skills",
".agents/skills",
"ops/handlers",
"ops/template-answers.yaml",
]
_SECRET_SHAPED_GLOBS = [
"*.pem", "*.key", "id_rsa", "id_ed25519", "id_ecdsa", "id_dsa",
".env", ".env.*", "*.env", "*password*", "*secret*", "*.pfx", "*.p12",
]
_SECRET_EXCLUDE_SUFFIXES = (".pub", ".schema.json", ".example")
_TYPE_EVIDENCE: list[tuple[str, list[str]]] = [
("infrastructure-config", ["profiles-source", "profiles", "inventory", "stacks", "terraform", "ansible"]),
("service-config", ["policies", "acceptance", "runbooks", "deployments"]),
("software", ["src", "pyproject.toml", "package.json", "go.mod", "Cargo.toml"]),
("project", ["deliverables", "docs", "decisions"]),
]
def _finding(severity: str, code: str, path: str | None = None, message: str | None = None) -> dict[str, Any]:
item: dict[str, Any] = {"severity": severity, "code": code}
if path:
item["path"] = path
if message:
item["message"] = message
return item
def _detect_secret_shaped_paths(root: Path) -> list[tuple[str, bool]]:
"""Return (relative_path, is_tracked) for files matching secret-shaped name patterns."""
tracked = gitutil.tracked_files(root)
found: list[tuple[str, bool]] = []
for path in root.rglob("*"):
if not path.is_file():
continue
if ".git" in path.parts or ".venv" in path.parts or "node_modules" in path.parts:
continue
name = path.name
if name.lower().endswith(_SECRET_EXCLUDE_SUFFIXES):
continue
if any(fnmatch.fnmatch(name.lower(), pattern) for pattern in _SECRET_SHAPED_GLOBS):
rel = path.relative_to(root).as_posix()
found.append((rel, rel in tracked))
return found
def _knowledge_format(path: Path) -> str:
"""Return ``stewardship-yaml`` only when the file really is a KnowledgeBase.
Location is not evidence of format: a repository may keep a large custom
knowledge file at the canonical path (runbook 11.1). Deciding by path alone
is what made adoption declare a legacy file conformant and then point the
contract at it, so validate the content against the schema instead.
"""
try:
data = io.load_yaml(path)
except ResourceError:
return "unparseable"
if not isinstance(data, dict):
return "legacy-yaml"
return "legacy-yaml" if validate_against_kind("KnowledgeBase", data) else "stewardship-yaml"
def _knowledge_entry(root: Path, rel: str) -> dict[str, str]:
fmt = _knowledge_format(root / rel)
action = "keep-or-validate" if fmt == "stewardship-yaml" else "wrap"
return {"path": rel, "format": fmt, "action": action}
def _classify_type(root: Path) -> tuple[str, str, list[str]]:
scores: dict[str, list[str]] = {t: [] for t, _ in _TYPE_EVIDENCE}
for repo_type, markers in _TYPE_EVIDENCE:
for marker in markers:
if (root / marker).exists():
scores[repo_type].append(marker)
ranked = sorted(scores.items(), key=lambda kv: -len(kv[1]))
best_type, best_evidence = ranked[0]
second_count = len(ranked[1][1]) if len(ranked) > 1 else 0
if not best_evidence:
return "project", "low", []
if len(best_evidence) >= 2 and len(best_evidence) > second_count:
confidence = "high"
elif len(best_evidence) > second_count:
confidence = "medium"
else:
confidence = "low"
return best_type, confidence, best_evidence
def assess(root: Path) -> dict[str, Any]:
head = gitutil.head_revision(root)
dirty = gitutil.is_dirty(root)
proposed_type, confidence, evidence = _classify_type(root)
claude_exists = (root / "CLAUDE.md").exists()
agents_exists = (root / "AGENTS.md").exists()
canonical_direction = "none"
findings: list[dict[str, Any]] = []
if claude_exists and agents_exists:
claude_text = (root / "CLAUDE.md").read_text(encoding="utf-8", errors="ignore")
if "AGENTS.md" in claude_text:
canonical_direction = "claude-imports-agents"
else:
agents_text = (root / "AGENTS.md").read_text(encoding="utf-8", errors="ignore")
if "CLAUDE.md" in agents_text:
canonical_direction = "legacy-agents-to-claude"
findings.append(_finding("warning", "ADOPT_ENTRYPOINT_DIRECTION_LEGACY", "AGENTS.md"))
else:
canonical_direction = "independent"
elif claude_exists:
canonical_direction = "claude-only"
elif agents_exists:
canonical_direction = "agents-only"
knowledge: list[dict[str, Any]] = []
for rel in ("kdb/kdb.yaml", "kdb.yaml", "ops/knowledge.yaml"):
if not (root / rel).exists():
continue
entry = _knowledge_entry(root, rel)
knowledge.append(entry)
if entry["action"] == "wrap":
findings.append(_finding("info", "ADOPT_KDB_LEGACY", rel))
proposed_content_roots: list[dict[str, Any]] = []
for repo_type, markers in _TYPE_EVIDENCE:
if repo_type != proposed_type:
continue
for marker in markers:
candidate = root / marker
if candidate.is_dir():
proposed_content_roots.append(
{"id": marker.replace("/", "-").lower(), "path": marker, "role": marker, "authority": "source"}
)
collisions: list[str] = []
for rel in _COLLISION_PATHS:
if (root / rel).exists():
collisions.append(rel)
if (root / "kdb" / "kdb.yaml").exists() and (root / "kdb.yaml").exists():
findings.append(_finding("warning", "ADOPT_KDB_CANONICAL_PATH_OCCUPIED", "kdb/kdb.yaml"))
for rel, tracked in _detect_secret_shaped_paths(root):
if tracked:
findings.append(_finding("error", "ADOPT_SECRET_TRACKED", rel, "Tracked path matches a secret-shaped filename pattern"))
else:
findings.append(_finding("info", "ADOPT_SECRET_TRACKED", rel, "Untracked secret-shaped path (path only, content not read)"))
if dirty:
findings.append(_finding("warning", "ADOPT_WORKTREE_DIRTY"))
questions: list[str] = []
confirmation_required = confidence != "high"
if confirmation_required:
questions.append("Confirm repository type and confidence evidence")
questions.append("Confirm owner(s) and lifecycle")
return {
"schema": "stewardship/adoption-assessment@0.1",
"repository": {"path": str(root), "baselineRevision": head, "dirty": dirty},
"classification": {
"proposedType": proposed_type,
"confidence": confidence,
"evidence": evidence,
"confirmationRequired": confirmation_required,
},
"entrypoints": {
"claude": "CLAUDE.md" if claude_exists else None,
"portable": "AGENTS.md" if agents_exists else None,
"canonicalDirection": canonical_direction,
},
"knowledge": knowledge,
"proposedContentRoots": proposed_content_roots,
"collisions": collisions,
"findings": findings,
"questions": questions,
}
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]:
"""A minimal KnowledgeBase, indexing ``legacy_path`` when one was found.
Topics stay empty on purpose: which sections of a legacy file matter is a
judgement call the tool cannot make, so adoption registers the document and
leaves routing to be authored deliberately afterwards.
"""
documents: list[dict[str, Any]] = []
if legacy_path:
documents.append(
{
"id": "legacy-knowledge-base",
"title": "Existing knowledge base",
"role": "reference",
"path": legacy_path,
"mediaType": "application/yaml",
"authority": "local-canonical",
"status": "verified",
}
)
return {
"apiVersion": API_VERSION,
"kind": "KnowledgeBase",
"metadata": {"name": f"{name}-knowledge-index"},
"spec": {
"repository": f"repo:{name}",
"defaultLanguage": "en",
"topics": [],
"documents": documents,
},
}
def _plan_knowledge(
assessment: dict[str, Any], confirmed_name: str
) -> tuple[str, list[dict[str, Any]], list[str]]:
"""Choose the knowledge entrypoint and the changes that establish it.
This is the compatibility table in runbook 11.1 expressed as code. The row
that matters most here is the last one: when a legacy or custom knowledge
base already occupies ``kdb/kdb.yaml`` it is indexed from a new
``ops/knowledge.yaml`` and left untouched, never rewritten and never
declared conformant.
"""
entries = {entry["path"]: entry for entry in assessment.get("knowledge", [])}
changes: list[dict[str, Any]] = []
forbidden: list[str] = []
canonical = entries.get("kdb/kdb.yaml")
adapter = entries.get("ops/knowledge.yaml")
root_legacy = entries.get("kdb.yaml")
if adapter is not None:
changes.append({"action": "preserve", "path": "ops/knowledge.yaml", "ownership": "repository"})
if canonical is not None:
changes.append({"action": "preserve", "path": "kdb/kdb.yaml", "ownership": "repository"})
forbidden.append("kdb/kdb.yaml")
return "ops/knowledge.yaml", changes, forbidden
if canonical is not None and canonical["action"] == "keep-or-validate":
changes.append({"action": "preserve", "path": "kdb/kdb.yaml", "ownership": "repository"})
return "kdb/kdb.yaml", changes, forbidden
if canonical is not None:
changes.append({"action": "preserve", "path": "kdb/kdb.yaml", "ownership": "repository"})
forbidden.append("kdb/kdb.yaml")
changes.append(
{
"action": "create",
"path": "ops/knowledge.yaml",
"ownership": "stewardship",
"reason": "Compatibility index; kdb/kdb.yaml holds a non-conformant knowledge base",
"content": io.yaml_text(_knowledge_base(confirmed_name, "kdb/kdb.yaml")),
}
)
return "ops/knowledge.yaml", changes, forbidden
legacy_path = root_legacy["path"] if root_legacy is not None else None
if legacy_path:
forbidden.append(legacy_path)
changes.append(
{
"action": "create",
"path": "kdb/kdb.yaml",
"ownership": "stewardship",
"reason": "Compatibility index for legacy knowledge base" if legacy_path else "Minimal KDB",
"content": io.yaml_text(_knowledge_base(confirmed_name, legacy_path)),
}
)
return "kdb/kdb.yaml", changes, forbidden
def build_plan(
root: Path,
assessment: dict[str, Any],
*,
confirmed_name: str,
confirmed_title: str | None = None,
confirmed_owners: list[str] | None = None,
confirmed_lifecycle: str = "active",
confirmed_type: str | None = None,
strategy: str = "overlay",
) -> dict[str, Any]:
if strategy != "overlay":
raise ValueError("Only the overlay strategy is implemented; normalize requires an explicit recipe run")
baseline = assessment["repository"]["baselineRevision"]
classification = assessment["classification"]
repository_type = confirmed_type or classification["proposedType"]
# assess asks the owner to confirm the type whenever confidence is below
# high, so record which of the two answers the contract is built on. Without
# this a low-confidence guess and a deliberate decision look identical later.
annotations: dict[str, str] = {
"stewardship.corsus.ru/classification": "confirmed" if confirmed_type else "inferred",
"stewardship.corsus.ru/classification-confidence": classification["confidence"],
}
if classification.get("evidence"):
annotations["stewardship.corsus.ru/classification-evidence"] = ", ".join(
classification["evidence"]
)
changes: list[dict[str, Any]] = []
forbidden: list[str] = []
contract_exists = (root / "ops/contract.yaml").exists()
content_roots = [
{
"id": cr["id"],
"role": cr["role"],
"path": cr["path"],
"kind": "directory",
"authority": cr.get("authority", "source"),
"writePolicy": "managed",
}
for cr in assessment.get("proposedContentRoots", [])
]
for cr in content_roots:
forbidden.append(f"{cr['path']}/**")
knowledge_entrypoint, knowledge_changes, knowledge_forbidden = _plan_knowledge(
assessment, confirmed_name
)
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=repository_type, 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,
"kind": "RepositoryContract",
"metadata": {
"name": confirmed_name,
"title": confirmed_title or confirmed_name,
"owners": confirmed_owners or [],
"annotations": annotations,
},
"spec": {
"summary": f"Adopted repository {confirmed_name}",
"repository": {
"type": repository_type,
"lifecycle": confirmed_lifecycle,
},
"template": {
"id": "repository." + repository_type.split("-")[0],
"version": "0.1.0",
"source": "repo:repository-stewardship",
"mode": "adopted-overlay",
"managedPaths": sorted(dict.fromkeys(managed_paths)),
},
"agent": {"primary": "CLAUDE.md", "portable": "AGENTS.md"},
"knowledge": {"entrypoint": knowledge_entrypoint},
"contentRoots": content_roots,
},
}
changes.insert(0, {"action": "create", "path": "ops/contract.yaml", "ownership": "stewardship", "content": io.yaml_text(contract)})
else:
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"):
if (root / rel).exists() and rel not in preserved_already:
changes.append({"action": "preserve", "path": rel, "ownership": "repository"})
preserved_already.add(rel)
forbidden.append(".ssh/**")
plan: dict[str, Any] = {
"schema": "stewardship/adoption-plan@0.1",
"repository": f"repo:{confirmed_name}",
"baselineRevision": baseline,
"strategy": strategy,
"changes": changes,
"forbiddenChanges": sorted(set(forbidden)),
"validations": [
"stewardship-schema",
"path-confinement",
"knowledge-references",
"agent-entrypoint-cycle",
],
"approval": {"required": True},
}
plan_hash = io.sha256({k: v for k, v in plan.items() if k != "planHash"})
plan["planHash"] = plan_hash
return plan
def is_forbidden(rel_path: str, forbidden: list[str]) -> bool:
"""True when ``rel_path`` is covered by any ``forbiddenChanges`` pattern."""
return any(fnmatch.fnmatch(rel_path, pattern) for pattern in forbidden)
def _resolve_change_target(root: Path, rel_path: str) -> Path:
"""Confine a plan-supplied path to the repository before it is ever written.
A plan is an ordinary file that can be edited or moved between machines, and
``root / rel_path`` silently discards ``root`` when ``rel_path`` is absolute,
so this is the boundary that keeps `apply` from writing outside the repo.
"""
try:
return confined_path(root, rel_path)
except PathViolation as exc:
raise AdoptionError("ADOPT_PATH_OUTSIDE_REPOSITORY", f"{rel_path}: {exc}") from exc
def apply_plan(root: Path, plan: dict[str, Any], approve_hash: str) -> list[str]:
expected_hash = io.sha256({k: v for k, v in plan.items() if k != "planHash"})
if expected_hash != plan.get("planHash"):
raise AdoptionError("APPROVAL_FAILED", "Plan hash does not match plan content; re-plan before apply")
if approve_hash != plan["planHash"]:
raise AdoptionError("APPROVAL_FAILED", "Approval hash does not match plan hash")
current_head = gitutil.head_revision(root)
if current_head != plan["baselineRevision"]:
raise AdoptionError(
"ADOPT_BASELINE_CHANGED", "Baseline revision changed since plan was built; re-plan"
)
forbidden = list(plan.get("forbiddenChanges", []))
to_write = [c for c in plan["changes"] if c["action"] in ("create", "patch-managed-block")]
targets: dict[str, Path] = {}
for change in to_write:
rel = change["path"]
target = _resolve_change_target(root, rel)
if is_forbidden(rel, forbidden):
raise AdoptionError("ADOPT_FORBIDDEN_PATH", f"Plan writes into a forbidden path: {rel}")
if change["action"] == "create" and target.exists():
raise AdoptionError("ADOPT_PATH_COLLISION", f"Refusing to overwrite existing path: {rel}")
if change["action"] == "patch-managed-block" and not target.exists():
raise AdoptionError(
"ADOPT_PATH_COLLISION", f"Cannot patch a managed block into a missing file: {rel}"
)
targets[rel] = target
# Re-check the worktree immediately before writing rather than trusting the
# `assess` that preceded it: a dirty path unrelated to the plan is the user's
# business, but overwriting a file they have uncommitted edits in is not.
contested = gitutil.dirty_paths(root) & set(targets)
if contested:
raise AdoptionError(
"ADOPT_WORKTREE_DIRTY",
"Uncommitted changes in paths this plan writes: " + ", ".join(sorted(contested)),
)
backups: dict[str, bytes | None] = {}
written: list[str] = []
try:
for change in to_write:
rel = change["path"]
target = targets[rel]
backups[rel] = target.read_bytes() if target.exists() else None
if change["action"] == "patch-managed-block":
current = target.read_text(encoding="utf-8")
content = splice_managed_block(current, change["content"])
else:
content = change["content"]
io.write_text_atomic(target, content)
written.append(rel)
except Exception:
# Restore by what was on disk before, not by what we believe we finished:
# a write that failed part-way still leaves a file that never existed.
for rel, original in backups.items():
target = targets[rel]
if original is None:
if target.exists():
target.unlink()
else:
target.write_bytes(original)
raise
return written
def verify(root: Path, plan: dict[str, Any] | None = None) -> dict[str, Any]:
validation = validate_repository(root)
baseline = gitutil.head_revision(root)
changed_paths: list[str] = []
preserved_paths: list[str] = []
if plan is not None:
for change in plan["changes"]:
if change["action"] in ("create", "patch-managed-block"):
changed_paths.append(change["path"])
elif change["action"] == "preserve":
preserved_paths.append(change["path"])
unresolved = sorted({f.code for f in validation.findings if f.severity in ("warning", "error")})
if any(f.severity == "error" for f in validation.findings):
outcome = "fail"
elif unresolved:
outcome = "pass-with-warnings"
else:
outcome = "pass"
return {
"schema": "stewardship/adoption-report@0.1",
"repository": f"repo:{(validation.contract or {}).get('metadata', {}).get('name', 'unknown')}",
"baselineRevision": baseline,
"compatibilityLevel": "L1",
"outcome": outcome,
"changedPaths": sorted(set(changed_paths)),
"preservedPaths": sorted(set(preserved_paths)),
"unresolvedFindings": unresolved,
}