platformforge 0.1.0__py3-none-any.whl

platformforge/agents/debate.py

@@ -0,0 +1,161 @@
+"""Debate engine — bounded disagreement between positions (§126–133).
+
+Shape is small by default: ≤4 participants (typically 2 specialists +
+1 critic), ≤3 rounds, inside the run envelope. Every position must cite
+evidence — a position without evidence is refused, not debated. The
+referee adjudicates on declared axes and returns a receipt; a resolved
+debate still requires the independent verifier afterward (§133).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.agents.contracts import AgentRefusal, Debate, DebatePosition, refusal
+from platformforge.agents.referee import referee
+
+DEFAULT_MAX_PARTICIPANTS = 4
+DEFAULT_MAX_ROUNDS = 3
+
+
+def _position_errors(p: DebatePosition) -> list[str]:
+    errs = []
+    if not p.agent:
+        errs.append("position missing agent")
+    if not p.claim:
+        errs.append(f"{p.agent or '?'}: claim is empty")
+    if not p.evidence:
+        errs.append(f"{p.agent or '?'}: position cites no evidence "
+                    "(§131 — evidence is required to debate)")
+    return errs
+
+
+def run_debate(question: str, positions: list[dict[str, Any] |
+               DebatePosition], *, max_rounds: int = DEFAULT_MAX_ROUNDS,
+               max_participants: int = DEFAULT_MAX_PARTICIPANTS,
+               envelope_budget: dict[str, Any] | None = None,
+               ) -> dict[str, Any]:
+    """Adjudicate positions through the referee under explicit bounds.
+
+    positions: dicts with at least {agent, claim, evidence}. Rounds are
+    the positions' declared `round` field — a debate never exceeds
+    max_rounds or max_participants; over-bounds input is refused, not
+    silently truncated.
+    """
+    if not question.strip():
+        return refusal(AgentRefusal.NO_EVIDENCE,
+                       "debate has no question",
+                       "state the contested claim precisely")
+    pos = [p if isinstance(p, DebatePosition) else DebatePosition(
+        agent=p.get("agent", ""), claim=p.get("claim", ""),
+        evidence=tuple(p.get("evidence") or p.get("evidence_fact_ids") or ()),
+        evidence_tier=p.get("evidence_tier", 7),
+        freshness=p.get("freshness", "unresolved"),
+        round=p.get("round", 0)) for p in positions]
+    participants = {p.agent for p in pos}
+    if len(participants) > max_participants:
+        return refusal(AgentRefusal.DEBATE_UNRESOLVED,
+                       f"{len(participants)} participants exceeds bound "
+                       f"{max_participants} — debates are small, not swarms",
+                       "drop to the 2 strongest positions + critic")
+    if any(p.round > max_rounds for p in pos):
+        return refusal(AgentRefusal.DEBATE_UNRESOLVED,
+                       f"a position declares a round beyond {max_rounds}",
+                       "re-run inside the 1–3 round bound")
+    errs = [e for p in pos for e in _position_errors(p)]
+    if errs:
+        return refusal(AgentRefusal.NO_EVIDENCE, "; ".join(errs),
+                       "every position must cite at least one evidence "
+                       "ref — unsupported positions are dropped, not "
+                       "debated")
+    if not pos:
+        return refusal(AgentRefusal.NO_EVIDENCE,
+                       "no positions to adjudicate",
+                       "collect positions first")
+
+    # §136–137 — information gain / stagnation: group positions by round;
+    # a round that adds no new evidence ids signals "stop" — later rounds
+    # are trimmed (deterministic bound, no unlimited debate).
+    by_round: dict[int, list[DebatePosition]] = {}
+    for p in pos:
+        by_round.setdefault(p.round, []).append(p)
+    seen_evidence: set[str] = set()
+    kept: list[DebatePosition] = []
+    stagnant_at: int | None = None
+    for rnd in sorted(by_round):
+        new_ids = {e for p in by_round[rnd] for e in p.evidence}
+        gain = new_ids - seen_evidence
+        if rnd > 0 and not gain:
+            stagnant_at = rnd
+            break                       # §137 — no new evidence → stop
+        seen_evidence |= new_ids
+        kept.extend(by_round[rnd])
+    pos = kept
+
+    decision = referee([{"agent": p.agent, "claim": p.claim,
+                         "evidence": list(p.evidence),
+                         "evidence_tier": p.evidence_tier,
+                         "freshness": p.freshness, "round": p.round}
+                        for p in pos])
+    outcome = ("unresolved" if decision["unresolved"]
+               else "tied" if decision["tied"] else "winner")
+    debate = Debate(debate_id=decision["receipt"]["receipt_id"],
+                    question=question, positions=tuple(pos),
+                    max_participants=max_participants,
+                    max_rounds=max_rounds,
+                    round=max(p.round for p in pos),
+                    outcome=outcome,
+                    winner=(decision["winner"] or {}).get("agent", ""),
+                    axes=tuple(decision["axes"]),
+                    receipt={**decision["receipt"],
+                             "positions": decision["positions"],
+                             "verifier_required": True,
+                             "note": "referee adjudicates disagreement; "
+                                     "verification is still a separate "
+                                     "independent step (§133)"})
+    out = debate.to_dict()
+    out["stopped_early"] = stagnant_at is not None   # §135–137
+    if stagnant_at is not None:
+        out["stagnant_round"] = stagnant_at
+        out["stop_reason"] = "no information gain — round added no new evidence ids"
+    if envelope_budget is not None:
+        out["budget"] = envelope_budget
+    if outcome == "unresolved":
+        return {**refusal(AgentRefusal.DEBATE_UNRESOLVED,
+                          "no position carried enough evidence to win",
+                          "gather more evidence or escalate to a human "
+                          "— the gap is real, not a tie-break problem"),
+                "debate": out}
+    return {"debate": out, "verifier_required": True}
+
+
+def build_referee_packet(positions: list[dict[str, Any] | DebatePosition],
+                         *, budget: dict[str, Any] | None = None
+                         ) -> dict[str, Any]:
+    """§131–133 — RefereePacket: the compressed structured view the
+    referee receives. Positions + deltas + shared evidence +
+    contradictions + budget — never the full transcript."""
+    pos = [p if isinstance(p, DebatePosition) else DebatePosition(
+        agent=p.get("agent", ""), claim=p.get("claim", ""),
+        evidence=tuple(p.get("evidence") or p.get("evidence_fact_ids") or ()),
+        round=p.get("round", 0)) for p in positions]
+    evidence_counts: dict[str, int] = {}
+    for p in pos:
+        for e in p.evidence:
+            evidence_counts[e] = evidence_counts.get(e, 0) + 1
+    shared = sorted(e for e, n in evidence_counts.items() if n > 1)
+    # contradictions = claims citing the same evidence id to opposing ends
+    # is unresolvable deterministically here; contradictions are the
+    # pairwise claim/delta surface the referee must adjudicate.
+    deltas = [{"agent": p.agent, "claim": p.claim,
+               "own_evidence": sorted(set(p.evidence) - set(shared))}
+              for p in pos]
+    return {"schema": "platformforge/referee-packet/v1",
+            "positions": [{"agent": p.agent, "claim": p.claim,
+                           "evidence": list(p.evidence),
+                           "round": p.round} for p in pos],
+            "shared_evidence": shared,
+            "deltas": deltas,
+            "contradictions": "declared by position evidence overlap",
+            "budget": budget or {},
+            "note": "no full transcript — referee adjudicates structure"}

platformforge/agents/executors.py

@@ -0,0 +1,160 @@
+"""pf-* executor subagents — one deterministic job each (§57–66).
+
+Executors do ONE thing, return structured output, and never dispatch
+other agents. They are thin wrappers over the deterministic engines —
+collect/analyze/judge/graph/ops — so a caller can bound an executor's
+work inside a run envelope without giving it reasoning authority.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from platformforge.models.base import Fact, stable_id
+
+EXECUTORS = ("pf-inventory", "pf-extractor", "pf-judge",
+             "pf-graph-builder", "pf-reconciler", "pf-simulator",
+             "pf-synthesizer", "pf-verifier")
+
+
+def pf_inventory(root: str | Path) -> dict[str, Any]:
+    """§58 — discover artifacts, identify domains + available evidence,
+    emit a coverage map. Does not judge."""
+    from platformforge.collect.detect import collect
+    out = collect(root)
+    detected = out.get("detected", {})
+    return {"executor": "pf-inventory",
+            "domains": sorted(detected),
+            "coverage": {d: len(files) for d, files in detected.items()},
+            "undetected": len(out.get("undetected", [])),
+            "artifact_count": sum(map(len, detected.values())),
+            "artifacts": {d: sorted(files) for d, files in
+                          detected.items()}}
+
+
+def pf_extract(artifacts: dict[str, Any] | str | Path) -> dict[str, Any]:
+    """§59 — Artifact → Facts. Does not assign severity."""
+    from platformforge.collect.detect import collect
+    if isinstance(artifacts, (str, Path)):
+        out = collect(artifacts)
+    else:
+        out = {"facts": artifacts.get("facts", [])}
+    facts = []
+    for f in out.get("facts", []):
+        facts.append(f if isinstance(f, dict)
+                     else (f.to_dict() if hasattr(f, "to_dict")
+                           else {"value": str(f)}))
+    return {"executor": "pf-extractor",
+            "fact_ids": [f.get("fact_id", "") for f in facts],
+            "facts": facts, "count": len(facts)}
+
+
+def pf_judge(facts: list[dict[str, Any]],
+             rules: Any) -> dict[str, Any]:
+    """§60 — Facts → Rules → Findings. Never recommends a change."""
+    from platformforge.rules.engine import RuleEngine
+    fact_objs = [f if isinstance(f, Fact) else Fact.from_dict(f)
+                 for f in facts]
+    eng = rules if isinstance(rules, RuleEngine) else RuleEngine(rules)
+    findings, skipped = eng.evaluate(fact_objs)
+    return {"executor": "pf-judge",
+            "findings": [f.to_dict() for f in findings],
+            "skipped": skipped,
+            "count": len(findings)}
+
+
+def pf_graph_build(facts: list[dict[str, Any]]) -> dict[str, Any]:
+    """§61 — Facts → Graphfy. No edge without a contributing fact_id."""
+    from platformforge.graph.build import GraphBuilder
+    gb = GraphBuilder().from_facts(facts)
+    g = gb.graph
+    edges = g.edges if isinstance(g.edges, dict) else {}
+    no_prov = [k for k, e in edges.items()
+               if not getattr(e, "source_fact_ids", ())]
+    return {"executor": "pf-graph-builder",
+            "nodes": len(g.nodes), "edges": len(edges),
+            "unprovenanced_edges": sorted(no_prov),
+            "graph": g.to_dict() if hasattr(g, "to_dict") else {}}
+
+
+def pf_reconcile(*, desired: dict[str, Any],
+                 planned: dict[str, Any],
+                 observed: dict[str, Any]) -> dict[str, Any]:
+    """§62 — desired/planned/observed reconciliation. All three states
+    stay distinct; contradictions name both values."""
+    def keys(g): return set((g or {}).keys())
+    d, p, o = keys(desired), keys(planned), keys(observed)
+    return {"executor": "pf-reconciler",
+            "desired_only": sorted(d - p - o),
+            "planned_not_observed": sorted(p - o),
+            "observed_unplanned": sorted(o - p - d),
+            "converged": sorted(d & p & o),
+            "drift": sorted((p | d) ^ o),
+            "receipt": stable_id("PF-REC", str(sorted(d)),
+                                 str(sorted(p)), str(sorted(o)))}
+
+
+def pf_simulate(*, observed_graph: dict[str, Any] | None = None,
+                planned_graph: dict[str, Any] | None = None,
+                plan_hash: str = "") -> dict[str, Any]:
+    """§63 — safe simulation: planned graph → expected delta.
+    Never executes; output is a delta document, not a change."""
+    on = set((observed_graph or {}).get("nodes", {}))
+    pn = set((planned_graph or {}).get("nodes", {}))
+    oe = set((observed_graph or {}).get("edges", {}))
+    pe = set((planned_graph or {}).get("edges", {}))
+    return {"executor": "pf-simulator",
+            "expected_delta": {
+                "adds": {"resources": sorted(pn - on),
+                         "dependencies": sorted(pe - oe)},
+                "removes": {"resources": sorted(on - pn),
+                            "dependencies": sorted(oe - pe)}},
+            "plan_hash": plan_hash,
+            "simulation_id": stable_id("PF-SIM", plan_hash,
+                                       str(sorted(pn)))}
+
+
+def pf_synthesize(*, findings: list[dict[str, Any]],
+                  graph: dict[str, Any] | None = None,
+                  reviews: list[dict[str, Any]] | None = None,
+                  referee: dict[str, Any] | None = None) -> dict[str, Any]:
+    """§64 — final composition. References only — mints no new facts."""
+    return {"executor": "pf-synthesizer",
+            "finding_count": len(findings),
+            "statuses": {s: sum(1 for f in findings
+                              if f.get("status") == s)
+                         for s in {f.get("status") for f in findings}},
+            "graph_nodes": len((graph or {}).get("nodes", {})),
+            "reviews": len(reviews or []),
+            "referee": bool(referee),
+            "evidence": sorted({e for f in findings
+                                for e in (f.get("evidence") or [])}),
+            "unresolved": [f.get("claim", "") for f in findings
+                           if f.get("status") in ("unresolved",
+                                                  "unsupported",
+                                                  "not-observed")],
+            "synthesis_id": stable_id(
+                "PF-SYN", str(len(findings)),
+                str(len((graph or {}).get("nodes", {}))))}
+
+
+def pf_verify(*, doc: dict[str, Any],
+              expected_hash: str = "",
+              receipt_fields: tuple[str, ...] = ("receipt_id",)
+              ) -> dict[str, Any]:
+    """§65 — mechanical proof checks used by platform-verifier:
+    hash recompute, receipt-field presence, criterion→evidence shape."""
+    from platformforge.agents.contracts import doc_hash
+    problems = []
+    got = doc.get("spec_hash") or doc.get("receipt_id") or ""
+    if expected_hash and got != expected_hash:
+        problems.append(f"hash mismatch: {got[:24]}… != "
+                        f"{expected_hash[:24]}…")
+    for f in receipt_fields:
+        if f not in doc:
+            problems.append(f"missing receipt field: {f}")
+    return {"executor": "pf-verifier",
+            "ok": not problems, "problems": problems,
+            "doc_hash": doc_hash(doc),
+            "check_id": stable_id("PF-PVF", str(sorted(doc)))}

platformforge/agents/guardian.py

@@ -0,0 +1,48 @@
+"""platform-release-guardian — deterministic closure review (§27).
+
+Evaluates gates/tests/evals/lab/docs/package/receipts/versioning/
+compatibility/known-gaps from MEASURED inputs and returns READY or an
+explicit blocker list. The guardian never runs the gates itself — the
+CLI feeds it gate results; it never fudges a missing signal into a pass.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+REQUIRED_SIGNALS = ("tests", "evals", "lab", "docs_drift", "package",
+                    "gates")
+
+
+def release_review(signals: dict[str, Any],
+                   known_gaps: tuple[str, ...] = ()) -> dict[str, Any]:
+    """signals: {tests: {"pass": n, "fail": n}, evals: {...}, lab: {...},
+    docs_drift: bool(pass), package: bool, gates: {name: ok},
+    receipts: {...}, versioning: str, compatibility: [notes]}"""
+    blockers: list[str] = []
+    missing = [s for s in REQUIRED_SIGNALS if s not in signals]
+    for s in missing:
+        blockers.append(f"missing signal: {s} — unmeasured is not passed")
+    t = signals.get("tests") or {}
+    if t.get("fail", 0) or t.get("unresolved", 0):
+        blockers.append(f"tests: {t.get('fail', 0)} failed, "
+                        f"{t.get('unresolved', 0)} unresolved")
+    for s in ("evals", "lab"):
+        v = signals.get(s) or {}
+        if v.get("fail", 0) or v.get("unresolved", 0):
+            blockers.append(f"{s}: fail={v.get('fail', 0)} "
+                            f"unresolved={v.get('unresolved', 0)}")
+    if signals.get("docs_drift") is False:
+        blockers.append("docs drift gate failing")
+    if signals.get("package") is False:
+        blockers.append("package gate failing")
+    gates = signals.get("gates") or {}
+    for name, ok in gates.items():
+        if not ok:
+            blockers.append(f"gate failed: {name}")
+    return {"verdict": "READY" if not blockers else "BLOCKED",
+            "blockers": blockers,
+            "known_gaps": list(known_gaps),
+            "signals_seen": sorted(signals),
+            "note": "READY requires every signal measured; absent "
+                    "signals are blockers, not assumptions"}

platformforge/agents/mirrors.py

@@ -0,0 +1,240 @@
+"""Host mirrors — render the canonical roster to host surfaces
+(§92–96): agents/, .agents/agents/, .claude/agents/, .codex/agents/,
+.devin/agents/. The roster is the source of truth; mirrors are OUTPUT.
+Never edit a mirror by hand — `agents check` fails on drift.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from platformforge.agents.roster import AGENTS, AgentSpec
+
+GEN_BANNER = ("# GENERATED from platformforge/agents/roster.py "
+              "— do not edit; run `platformforge agents sync`\n")
+
+# every host gets the canonical mirror set (§92)
+TARGETS: dict[str, str] = {
+    "agents": "md",
+    ".agents/agents": "md",
+    ".claude/agents": "md",
+    ".codex/agents": "toml",
+    ".devin/agents": "md",
+}
+
+# §106 — host adapter: tier → concrete host tools/model. The roster
+# stays provider-free; only mirrors carry host vocabulary. No access
+# tier maps to Edit/Write: platform state is persisted through the
+# `platformforge` CLI (runs/artifacts), never by editing the tree.
+HOST_TOOLS: dict[str, str] = {
+    "read-only": "Read, Grep, Glob, Bash",
+    "state-writer": "Read, Grep, Glob, Bash",
+    "workspace-writer": "Read, Grep, Glob, Bash, Edit, Write",
+    "governed-writer": "Read, Grep, Glob, Bash",
+}
+HOST_MODEL: dict[str, str] = {
+    "deterministic": "haiku",
+    "fast": "haiku",
+    "standard": "sonnet",
+    "deep": "opus",
+    "critical-review": "opus",
+}
+
+# domain → host skill carrying the verb reference for that domain
+DOMAIN_SKILL: dict[str, str] = {
+    "graph": "platformforge-graph",
+    "change": "platformforge-change", "ops": "platformforge-change",
+    "plans": "platformforge-change", "release": "platformforge-change",
+    "simulate": "platformforge-change", "drift": "platformforge-change",
+    "sre": "platformforge-sre", "slo": "platformforge-sre",
+    "incident": "platformforge-sre", "capacity": "platformforge-sre",
+    "otel": "platformforge-sre", "reliability": "platformforge-sre",
+    "runtime": "platformforge-sre",
+    "finops": "platformforge-finops",
+    "security": "platformforge-security", "privacy": "platformforge-security",
+    "fleet": "platformforge-fleet", "federation": "platformforge-fleet",
+    "optimization": "platformforge-fleet", "ai": "platformforge-fleet",
+    "gpu": "platformforge-fleet",
+    "policy": "platformforge-governance",
+    "governance": "platformforge-governance",
+    "product": "platformforge-governance", "dx": "platformforge-governance",
+    "golden-paths": "platformforge-governance",
+    "economy": "platformforge-economy",
+    "evidence": "platformforge-agents", "closure": "platformforge-agents",
+    "proof": "platformforge-agents", "conflicts": "platformforge-agents",
+    "tasks": "platformforge-agents", "compose": "platformforge-agents",
+}
+
+
+def skills_for(spec: AgentSpec) -> list[str]:
+    out: list[str] = []
+    for d in spec.domains:
+        s = DOMAIN_SKILL.get(d, "platformforge-core")
+        if s not in out:
+            out.append(s)
+    return out
+
+
+def _description(spec: AgentSpec) -> str:
+    text = f"{spec.mission}. Use when: {spec.when_to_enter}."
+    if spec.when_not_to_enter:
+        text += f" Do NOT use when: {spec.when_not_to_enter}."
+    return text
+
+
+def _yaml_str(text: str) -> str:
+    return '"' + text.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def _body(spec: AgentSpec) -> str:
+    def bullets(items):
+        return "\n".join(f"- {i}" for i in items) or "- (none)"
+    verbs = ", ".join(f"`platformforge {v}`" for v in spec.allowed_verbs)
+    return f"""# {spec.name}
+
+You are `{spec.name}`, a Platform Forge {spec.role}. Mission: {spec.mission}.
+
+Role: {spec.role} · Access: {spec.access} · Write: {spec.write_scope}
+Model tier: {spec.model_tier} · Budget: {spec.max_context_budget}B ctx /
+{spec.max_tool_calls} tool calls / fanout ≤{spec.max_parallelism}
+Domains: {', '.join(spec.domains)}
+
+## Enter when
+{spec.when_to_enter}
+
+## Do NOT enter when
+{spec.when_not_to_enter}
+
+If the request matches "Do NOT enter when", stop and return a named
+refusal with the agent or skill that should take it — do not stretch.
+
+## Inputs
+{bullets(spec.inputs)}
+
+## How to work
+- Do the work through the `platformforge` CLI (fall back to
+  `.venv/bin/platformforge` when it is not on PATH). Verbs you may run:
+  {verbs or 'none — read-only inspection of supplied artifacts'}.
+- Verb reference and reading rules live in skill(s):
+  {', '.join(skills_for(spec))} — load them before running verbs.
+- Cite `fact_id` / `rule_id` / evidence ids for every claim; what you
+  cannot back with evidence goes to `unresolved`, never into prose.
+- Stay inside your budget; when it runs out, report `partial`.
+
+Capabilities: {', '.join(spec.allowed_capabilities) or '(none declared)'}
+Required evidence: {', '.join(spec.required_evidence) or '(none)'}
+
+## Output
+{', '.join(spec.outputs)}
+
+## Boundaries
+Delegates to: {', '.join(spec.delegates_to) or 'nobody'}
+Never delegates to: {', '.join(spec.cannot_delegate_to) or '(none)'}
+Reviewed by: {', '.join(spec.reviewers) or '(none)'}
+Verifier: {spec.verifier or '(none)'}
+Escalation: {spec.escalation or 'human operator'}
+
+## Done when
+{spec.done_when}
+
+## Never
+{spec.never}; edit repository files; run `change approve|apply` or any
+`ops`/`live` mutation — those stay host-side behind a human gate.
+"""
+
+
+def _md(spec: AgentSpec) -> str:
+    # frontmatter must open on line 1 or hosts ignore the agent; the
+    # banner therefore lives inside it as a YAML comment.
+    return f"""---
+{GEN_BANNER.rstrip()}
+name: {spec.name}
+description: {_yaml_str(_description(spec))}
+tools: {HOST_TOOLS.get(spec.access, HOST_TOOLS["read-only"])}
+model: {HOST_MODEL.get(spec.model_tier, "inherit")}
+---
+
+{_body(spec)}"""
+
+
+def _toml_str(text: str) -> str:
+    return '"""' + text.replace("\\", "\\\\").replace('"""', '\\"""') + '"""'
+
+
+def _toml(spec: AgentSpec) -> str:
+    lines = [GEN_BANNER.rstrip(),
+             f'name = "{spec.name}"',
+             f'description = {_toml_str(_description(spec))}',
+             f'developer_instructions = {_toml_str(_body(spec))}',
+             f'role = "{spec.role}"',
+             f'access = "{spec.access}"',
+             f'model_tier = "{spec.model_tier}"',
+             f'domains = {list(spec.domains)!r}'.replace("'", '"'),
+             f'verbs = {list(spec.allowed_verbs)!r}'.replace("'", '"'),
+             f'verifier = "{spec.verifier}"',
+             f'never = {_toml_str(spec.never)}']
+    return "\n".join(lines) + "\n"
+
+
+def render(spec: AgentSpec, fmt: str) -> str:
+    return _toml(spec) if fmt == "toml" else _md(spec)
+
+
+def expected(root: str | Path) -> dict[str, str]:
+    """Mirror path → expected content. The drift gate compares this."""
+    root = Path(root)
+    out: dict[str, str] = {}
+    for rel, fmt in TARGETS.items():
+        ext = ".toml" if fmt == "toml" else ".md"
+        for spec in AGENTS.values():
+            p = root / rel / f"{spec.name}{ext}"
+            out[p.relative_to(root).as_posix()] = render(spec, fmt)
+    return out
+
+
+def sync(root: str | Path) -> dict[str, list[str]]:
+    root = Path(root)
+    want = expected(root)
+    written: dict[str, list[str]] = {rel: [] for rel in TARGETS}
+    for rel in TARGETS:
+        (root / rel).mkdir(parents=True, exist_ok=True)
+    for rel_path, content in want.items():
+        p = root / rel_path
+        p.write_text(content, encoding="utf-8")
+        written[Path(rel_path).parent.as_posix()].append(rel_path)
+    return {k: sorted(v) for k, v in written.items()}
+
+
+def check(root: str | Path) -> dict[str, object]:
+    """Mirror drift gate — on-disk must equal generated; extra files in
+    mirror dirs that aren't generated are drift too."""
+    root = Path(root)
+    want = expected(root)
+    problems = []
+    for rel_path, content in want.items():
+        p = root / rel_path
+        if not p.is_file():
+            problems.append(f"missing mirror: {rel_path}")
+        elif p.read_text(encoding="utf-8") != content:
+            problems.append(f"stale mirror: {rel_path}")
+    stale_dirs = []
+    for rel in TARGETS:
+        d = root / rel
+        if d.is_dir():
+            for f in sorted(d.iterdir()):
+                rel_f = f.relative_to(root).as_posix()
+                if f.is_file() and rel_f not in want \
+                        and f.suffix in (".md", ".toml"):
+                    stale_dirs.append(rel_f)
+    problems += [f"stray mirror file (not generated): {s}"
+                 for s in stale_dirs]
+    return {"ok": not problems, "problems": problems,
+            "mirrors": len(want)}
+
+
+def lint() -> dict[str, object]:
+    problems = []
+    for a in AGENTS.values():
+        problems.extend(f"{a.name}: {e}" for e in a.contract_errors())
+    return {"agents": len(AGENTS), "problems": problems,
+            "ok": not problems}