From a4b0fa5a8b6bf2b77adb3eb68b0cdba8fef23099 Mon Sep 17 00:00:00 2001 From: Alexander Baranov Date: Mon, 24 Aug 2026 18:40:11 +0300 Subject: [PATCH] fix(adopt): weigh classification evidence, and stop calling mirrors sources Classification counted directories that merely exist, so `docs/` -- present in nearly every repository -- carried the same weight as `policies/` and tied the two types against each other. That tie is why the Antivirus pilot came out as low confidence and demanded a confirmation it did not actually need; with weights it is high confidence on the same evidence. Ties are now explicit rather than settled by declaration order, and reported as ADOPT_TYPE_AMBIGUOUS. Content roots were emitted with authority "source" and writePolicy "managed" unconditionally, which meant a repository holding both profiles-source/ and profiles/ had its generated mirror declared a source -- precisely the error runbook section 7.2 names as the one not to make. Learned the tool has been producing the contract its own documentation warns against. - weighted evidence, deterministic tie-breaking, explicit ambiguity finding - declare a known mirror as authority mirror / writePolicy generated, with generatedFrom, and fall back to source only when nothing generates it here - give roots meaningful roles instead of reusing the directory name Co-Authored-By: Claude Opus 5 --- src/stewardship/adoption.py | 129 +++++++++++++++++++++++++++--------- 1 file changed, 97 insertions(+), 32 deletions(-) diff --git a/src/stewardship/adoption.py b/src/stewardship/adoption.py index 08f80f7..3bda154 100644 --- a/src/stewardship/adoption.py +++ b/src/stewardship/adoption.py @@ -104,13 +104,44 @@ _SECRET_SHAPED_GLOBS = [ ] _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"]), +# Weighted because presence alone is weak evidence: `docs/` exists in almost +# every repository and must not outvote a marker that actually identifies the +# kind of work a repository does, while a lockfile or a profile source does. +_TYPE_EVIDENCE: list[tuple[str, dict[str, int]]] = [ + ( + "infrastructure-config", + {"profiles-source": 3, "inventory": 3, "stacks": 3, "terraform": 3, "ansible": 3, "profiles": 2}, + ), + ("service-config", {"policies": 3, "acceptance": 3, "deployments": 3, "runbooks": 2}), + ("software", {"pyproject.toml": 3, "package.json": 3, "go.mod": 3, "Cargo.toml": 3, "src": 2}), + ("project", {"deliverables": 3, "decisions": 3, "docs": 1}), ] +# How a recognised directory should be declared. Authority is not cosmetic: the +# runbook singles out calling a generated mirror a source as the mistake to +# avoid, and `profiles/` is exactly that whenever `profiles-source/` is present. +_CONTENT_ROOT_SPECS: dict[str, dict[str, Any]] = { + "profiles-source": {"role": "profiles", "authority": "source", "writePolicy": "managed"}, + "profiles": { + "role": "observed", + "authority": "mirror", + "writePolicy": "generated", + "generatedFrom": ["profiles-source"], + }, + "inventory": {"role": "inventory", "authority": "source", "writePolicy": "managed"}, + "stacks": {"role": "stacks", "authority": "source", "writePolicy": "managed"}, + "terraform": {"role": "desired", "authority": "source", "writePolicy": "managed"}, + "ansible": {"role": "desired", "authority": "source", "writePolicy": "managed"}, + "policies": {"role": "policies", "authority": "source", "writePolicy": "managed"}, + "acceptance": {"role": "acceptance", "authority": "source", "writePolicy": "managed"}, + "deployments": {"role": "deployments", "authority": "source", "writePolicy": "managed"}, + "runbooks": {"role": "runbooks", "authority": "source", "writePolicy": "managed"}, + "src": {"role": "source", "authority": "source", "writePolicy": "managed"}, + "deliverables": {"role": "deliverables", "authority": "source", "writePolicy": "managed"}, + "decisions": {"role": "decisions", "authority": "source", "writePolicy": "managed"}, + "docs": {"role": "documentation", "authority": "source", "writePolicy": "managed"}, +} + 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} @@ -162,31 +193,41 @@ def _knowledge_entry(root: Path, rel: str) -> dict[str, str]: 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} +def _classify_type(root: Path) -> tuple[str, str, list[str], bool]: + """Propose a repository type, its confidence, its evidence, and whether it tied. + + Scores are weighted sums rather than marker counts, so a repository holding + both `policies/` and `docs/` is not a coin flip between two types the way a + plain count made it. + """ + scores: dict[str, int] = {} + evidence: dict[str, list[str]] = {} 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: + found = sorted(marker for marker in markers if (root / marker).exists()) + evidence[repo_type] = found + scores[repo_type] = sum(markers[marker] for marker in found) + + ranked = sorted(scores.items(), key=lambda item: (-item[1], item[0])) + best_type, best_score = ranked[0] + second_score = ranked[1][1] if len(ranked) > 1 else 0 + + if best_score == 0: + return "project", "low", [], False + tied = best_score == second_score + if tied: confidence = "low" - return best_type, confidence, best_evidence + elif best_score >= 3 and best_score >= 2 * second_score: + confidence = "high" + else: + confidence = "medium" + return best_type, confidence, evidence[best_type], tied def assess(root: Path) -> dict[str, Any]: head = gitutil.head_revision(root) dirty = gitutil.is_dirty(root) - proposed_type, confidence, evidence = _classify_type(root) + proposed_type, confidence, evidence, tied = _classify_type(root) claude_exists = (root / "CLAUDE.md").exists() agents_exists = (root / "AGENTS.md").exists() @@ -221,12 +262,29 @@ def assess(root: Path) -> dict[str, Any]: for repo_type, markers in _TYPE_EVIDENCE: if repo_type != proposed_type: continue - for marker in markers: + for marker in sorted(markers): candidate = root / marker - if candidate.is_dir(): - proposed_content_roots.append( - {"id": marker.replace("/", "-").lower(), "path": marker, "role": marker, "authority": "source"} - ) + if not candidate.is_dir(): + continue + spec = _CONTENT_ROOT_SPECS.get( + marker, {"role": marker, "authority": "source", "writePolicy": "managed"} + ) + content_root: dict[str, Any] = { + "id": marker.replace("/", "-").lower(), + "path": marker, + "role": spec["role"], + "authority": spec["authority"], + "writePolicy": spec["writePolicy"], + } + sources = spec.get("generatedFrom") or [] + if sources and all((root / source).exists() for source in sources): + content_root["generatedFrom"] = [ + source.replace("/", "-").lower() for source in sources + ] + elif sources: + # Nothing generates it here, so it is the source in this repository. + content_root.update(authority="source", writePolicy="managed", role=marker) + proposed_content_roots.append(content_root) collisions: list[str] = [] for rel in _COLLISION_PATHS: @@ -244,6 +302,11 @@ def assess(root: Path) -> dict[str, Any]: if dirty: findings.append(_finding("warning", "ADOPT_WORKTREE_DIRTY")) + if tied: + findings.append( + _finding("warning", "ADOPT_TYPE_AMBIGUOUS", None, f"Type evidence ties with {proposed_type}") + ) + questions: list[str] = [] confirmation_required = confidence != "high" if confirmation_required: @@ -411,17 +474,19 @@ def build_plan( forbidden: list[str] = [] contract_exists = (root / "ops/contract.yaml").exists() - content_roots = [ - { + content_roots: list[dict[str, Any]] = [] + for cr in assessment.get("proposedContentRoots", []): + entry: dict[str, Any] = { "id": cr["id"], "role": cr["role"], "path": cr["path"], "kind": "directory", "authority": cr.get("authority", "source"), - "writePolicy": "managed", + "writePolicy": cr.get("writePolicy", "managed"), } - for cr in assessment.get("proposedContentRoots", []) - ] + if cr.get("generatedFrom"): + entry["generatedFrom"] = cr["generatedFrom"] + content_roots.append(entry) for cr in content_roots: forbidden.append(f"{cr['path']}/**")