feat: implement repoctl L1 core (models, schemas, validate, discover, context, init, adopt)

Adds the repository-stewardship Python package (src/stewardship) with:
- JSON Schemas (Draft 2020-12) for RepositoryContract, KnowledgeBase, CatalogIndex,
  ContextBundle, BootstrapPlan, AdoptionAssessment/Plan/Report, user config and the
  repoctl-result envelope.
- Safe YAML I/O, path confinement, deterministic clock and canonical-JSON hashing.
- validate: schema, ID uniqueness, path safety, KDB references, freshness, secret-shaped
  fields, shell-string detection, and Markdown frontmatter/fence/link checks.
- discover/CatalogIndex with deterministic sorting and duplicate-name detection.
- describe (contract-only) and context (intent-scoped ContextBundle with budgeted
  materialization and --strict truncation).
- init: plan-then-apply bootstrap with SHA-256 plan-hash approval, no fake domain
  artifacts, bundled Claude skills.
- adopt: assess/plan/apply/verify overlay workflow per docs/adoption-runbook.md,
  preserving legacy content roots and KDB, with baseline-hash re-check and rollback.
- argparse-based `repoctl` CLI with human/yaml/json output and spec exit codes.
- pytest suite (39 tests) covering positive/negative fixtures, discovery, context,
  bootstrap and adoption (including LXD- and Antivirus-shaped legacy layouts).

Managed with uv (.venv), ruff clean, mypy --strict clean.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Alexander Baranov
2026-08-24 14:57:34 +03:00
co-authored by Claude Sonnet 5
parent 9a39b8a941
commit 96d4d08230
75 changed files with 4259 additions and 0 deletions
+396
View File
@@ -0,0 +1,396 @@
"""`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 .validate import validate_repository
_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 _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]] = []
if (root / "kdb" / "kdb.yaml").exists():
knowledge.append({"path": "kdb/kdb.yaml", "format": "stewardship-yaml", "action": "keep-or-validate"})
elif (root / "kdb.yaml").exists():
knowledge.append({"path": "kdb.yaml", "format": "legacy-yaml", "action": "wrap"})
findings.append(_finding("info", "ADOPT_KDB_LEGACY", "kdb.yaml"))
if (root / "ops" / "knowledge.yaml").exists():
knowledge.append({"path": "ops/knowledge.yaml", "format": "stewardship-yaml", "action": "keep-or-validate"})
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 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",
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"]
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']}/**")
if not contract_exists:
contract = {
"apiVersion": API_VERSION,
"kind": "RepositoryContract",
"metadata": {
"name": confirmed_name,
"title": confirmed_title or confirmed_name,
"owners": confirmed_owners or [],
},
"spec": {
"summary": f"Adopted repository {confirmed_name}",
"repository": {
"type": assessment["classification"]["proposedType"],
"lifecycle": confirmed_lifecycle,
},
"template": {
"id": "repository." + assessment["classification"]["proposedType"].split("-")[0],
"version": "0.1.0",
"source": "repo:repository-stewardship",
"mode": "adopted-overlay",
"managedPaths": ["ops/contract.yaml"],
},
"agent": {"primary": "CLAUDE.md", "portable": "AGENTS.md"},
"knowledge": {"entrypoint": _knowledge_entrypoint(assessment)},
"contentRoots": content_roots,
},
}
changes.append({"action": "create", "path": "ops/contract.yaml", "ownership": "stewardship", "content": io.yaml_text(contract)})
else:
changes.append({"action": "preserve", "path": "ops/contract.yaml", "ownership": "repository"})
kdb_entries = assessment.get("knowledge", [])
kdb_paths = {entry["path"] for entry in kdb_entries}
if "kdb/kdb.yaml" not in kdb_paths:
legacy = next((e for e in kdb_entries if e["action"] == "wrap"), None)
kdb: dict[str, Any] = {
"apiVersion": API_VERSION,
"kind": "KnowledgeBase",
"metadata": {"name": f"{confirmed_name}-knowledge-index"},
"spec": {
"repository": f"repo:{confirmed_name}",
"defaultLanguage": "en",
"topics": [],
"documents": [],
},
}
target_kdb_path = "kdb/kdb.yaml"
if legacy:
kdb["spec"]["documents"].append(
{
"id": "legacy-knowledge-base",
"title": "Existing knowledge base",
"role": "reference",
"path": legacy["path"],
"mediaType": "application/yaml",
"authority": "local-canonical",
"status": "verified",
}
)
forbidden.append(legacy["path"])
changes.append({"action": "create", "path": target_kdb_path, "ownership": "stewardship", "reason": "Compatibility index for legacy knowledge base" if legacy else "Minimal KDB", "content": io.yaml_text(kdb)})
else:
changes.append({"action": "preserve", "path": "kdb/kdb.yaml", "ownership": "repository"})
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"}
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 _knowledge_entrypoint(assessment: dict[str, Any]) -> str:
for entry in assessment.get("knowledge", []):
if entry["path"] == "kdb/kdb.yaml":
return "kdb/kdb.yaml"
return "kdb/kdb.yaml"
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 ValueError("Plan hash does not match plan content; re-plan before apply")
if approve_hash != plan["planHash"]:
raise ValueError("Approval hash does not match plan hash")
current_head = gitutil.head_revision(root)
if current_head != plan["baselineRevision"]:
raise ValueError("ADOPT_BASELINE_CHANGED: baseline revision changed since plan was built; re-plan")
to_write = [c for c in plan["changes"] if c["action"] in ("create", "patch-managed-block")]
for change in to_write:
target = root / change["path"]
if change["action"] == "create" and target.exists():
raise FileExistsError(f"ADOPT_PATH_COLLISION: refusing to overwrite existing path: {change['path']}")
written: list[str] = []
backups: dict[str, bytes | None] = {}
try:
for change in to_write:
target = root / change["path"]
backups[change["path"]] = target.read_bytes() if target.exists() else None
io.write_text_atomic(target, change["content"])
written.append(change["path"])
except Exception:
for rel, original in backups.items():
target = root / rel
if original is None:
if target.exists() and rel in written:
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,
}