@jesdi/skills 0.0.30 → 0.0.31

package/skills/implement-spec/driver_fixloop.py

@@ -0,0 +1,170 @@
+"""A gated ticket tip in, a reviewed tip out: the review, the fixture corrections and the fix rounds.
+
+Reports of a ticket are `<role>-<K>.json`: K is the fix round the agent follows (reviewer, correctness) or is
+(fixer). A fixture correction after the review of round K is `test-writer-<K+1>.json`.
+"""
+from __future__ import annotations
+
+import json
+import os
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+
+import driver_agents
+import driver_review
+import driver_slots
+from driver_run import OUT, Blocked, Run, during, ledger
+from driver_tickets import Ticket
+
+ROUNDS = 4
+
+
+@dataclass
+class Job:
+    """One ticket between its gate and its merge."""
+    ticket: Ticket
+    slot: str
+    run: Run
+    values: dict[str, str]  # the pointers every prompt of the ticket gets
+    round: int  # fix rounds started
+    tip: str
+    previous: str = ""  # the tip before the last fix; "" makes the next review a full one
+    proofs: set[tuple[str, int]] = field(default_factory=set)  # mutation proofs so far, at `tip`
+    again: list[str] = field(default_factory=list)  # `file:line` of each proof the last fix made due again
+    corrected: bool = False  # the last step was a fixture correction
+
+    def pointers(self, review: int) -> dict[str, str]:
+        """The values of a prompt; `review` is the round whose findings the agent reads."""
+        entry = self.run.state.read()["tickets"][self.ticket.number]
+        findings = os.path.relpath(OUT / self.ticket.number / f"findings-{review}.json", self.slot)
+        return {**self.values, "start_sha": self.tip, "from_sha": self.previous, "round": str(self.round),
+                "locked": " ".join(entry["locked"]), "test_writer_sha": str(entry["test_writer_sha"] or ""),
+                "findings": findings, "proofs": " ".join(self.again)}
+
+
+def entry(models: dict[str, list[str]], round: int) -> str:
+    """The implementer entry of a fix round: the second one from round 3, when the list has one."""
+    entries = models["implementer"]
+    return entries[1] if round > 2 and len(entries) > 1 else entries[0]
+
+
+def _log_findings(job: Job, findings: list[dict]) -> list[dict]:
+    for finding in findings:
+        ledger(f"Ticket {job.ticket.number}: {finding['severity']} finding of kind {finding['kind']} from the "
+               f"{finding['source']} at {finding['file']}:{finding['line']}: {finding['title']}.")
+    return findings
+
+
+def _run_reviewers(job: Job, cast: list[tuple[str, str]], locked: list[str]) -> list[dict]:
+    """Run the (role, model entry) pairs of `cast` at the same time in the one slot. Returns their reports."""
+    values, running = job.pointers(job.round - 1), [role for role, _ in cast]
+    errors: dict[str, str] = {}
+
+    def call(role: str, entry: str) -> dict:
+        # The first review of a tip must give a mutation proof for each locked test.
+        first_review = not job.previous and role == "reviewer"
+        try:
+            return job.run.agent(role, job.ticket.number, job.slot, values, entry=entry, fix_round=job.round,
+                                 notes=["rereview"] if job.previous else [],
+                                 check={"round": 1, "locked": locked} if first_review else {},
+                                 alone=lambda: len(running) == 1)
+        except Blocked as blocked:
+            errors[role] = f"the {role}: {blocked}"
+            return {}
+        finally:
+            running.remove(role)
+
+    with ThreadPoolExecutor(len(cast)) as pool:
+        reports = list(pool.map(lambda agent: call(*agent), cast))
+    if errors:
+        raise Blocked("; ".join(errors[role] for role, _ in cast if role in errors))
+    return reports
+
+
+def _review(job: Job) -> list[dict]:
+    """Review `job.tip`. Returns the findings of the driver and of each reviewer."""
+    run, number = job.run, job.ticket.number
+    state = run.state.ticket(number, phase="review")
+    found = _log_findings(job, driver_review.locked_findings(job.slot, state))
+    cast = [("reviewer", "")]
+    if job.ticket.risk:
+        cast.append(("correctness", driver_agents.correctness_entry(run.models)))
+    reports = run.read_only(number, job.slot, job.values["branch"], job.tip,
+                            lambda: _run_reviewers(job, cast, state["locked"]))
+    for (role, _), report in zip(cast, reports):
+        found += _log_findings(job, [{**finding, "source": role} for finding in report["findings"]])
+        job.proofs |= {(proof["file"], proof["line"]) for proof in report.get("mutations", [])}
+    (OUT / number / f"findings-{job.round}.json").write_text(json.dumps(found, indent=1) + "\n")
+    return found
+
+
+def _correct_fixture(job: Job, fixture: list[dict]) -> None:
+    """One test-writer correction for the fixture findings. It is outside the fix rounds."""
+    run, number = job.run, job.ticket.number
+    if job.corrected:
+        titles = "; ".join(finding["title"] for finding in fixture)
+        raise Blocked(f"the review: a fixture finding is open after the test-writer correction: {titles}")
+    run.restore_locked_files(number, job.slot)
+    with during("the fixture correction"):
+        report = run.agent("test-writer", number, job.slot, job.pointers(job.round), notes=["correction"],
+                           fix_round=job.round + 1)
+    job.tip, job.previous, job.corrected = driver_slots.head(job.slot), "", True
+    entry = run.state.read()["tickets"][number]
+    run.state.ticket(number, tip=job.tip, **driver_review.written(job.slot, entry, report["locked"], job.tip))
+    for finding in fixture:
+        ledger(f"Ticket {number}: fixture correction in {finding['file']}, outside the fix rounds: "
+               f"{finding['title']}: {finding['evidence']}. The test-writer corrected it at {job.tip[:7]}.")
+
+
+def _fix(job: Job) -> None:
+    """Run the next fix round: a fixer on the implementer's list."""
+    run, number = job.run, job.ticket.number
+    job.round += 1
+    on = entry(run.models, job.round)
+    run.state.ticket(number, phase="fix", round=job.round)
+    if job.round == 3 and on != run.models["implementer"][0]:
+        ledger(f"Ticket {number} round 3: escalated to {on}.")
+    elif job.round == 3:
+        ledger(f"Ticket {number} round 3: the implementer has no next entry, so the round stays on {on}.")
+    with during(f"fix round {job.round}"):
+        run.agent("fixer", number, job.slot, job.pointers(job.round - 1), entry=on, fix_round=job.round)
+    before, job.tip = job.tip, driver_slots.head(job.slot)
+    # No review has seen a fixture correction, so the review after a fix on a corrected tip is a full one.
+    job.previous, job.corrected = "" if job.corrected else before, False
+    run.state.ticket(number, tip=job.tip)
+    followed = driver_review.follow(job.slot, before, job.tip, job.proofs)
+    job.proofs = set(followed)
+    job.again = [f"{file}:{line}" for (file, line), changed in sorted(followed.items()) if changed]
+
+
+def _act_on(job: Job, found: list[dict]) -> bool:
+    """Do what the findings of a review ask for: a fixture correction, a fix round, or a stop. True: none is open."""
+    fixture, to_fix = driver_review.route(found)
+    # A changed locked file is fixed first: a correction on top of it would make the changed file the reference.
+    locked_file_changed = any(finding["source"] == "driver" for finding in found)
+    if fixture and not locked_file_changed:
+        _correct_fixture(job, fixture)
+        if not to_fix:
+            return False
+    if not to_fix:
+        return True
+    if job.round == ROUNDS:
+        titles = [f"{finding['title']} ({finding['file']}:{finding['line']})" for finding in to_fix]
+        evidence = OUT / job.ticket.number / f"findings-{ROUNDS}.json"
+        job.run.ask(job.ticket.number, "finding", titles, str(evidence))
+        raise Blocked(f"the review: after round {ROUNDS} these findings are open: {'; '.join(titles)}")
+    _fix(job)
+    return False
+
+
+def run(ticket: Ticket, slot: str, run: Run, values: dict[str, str]) -> None:
+    """Gate, review and fix the ticket tip until a review leaves no finding open."""
+    state = run.state.read()["tickets"][ticket.number]
+    job = Job(ticket, slot, run, values, state["round"], state["tip"])
+    while True:
+        with during("the gate"):
+            run.gate(ticket.number, slot, job.tip)
+        with during("the review"):
+            found = _review(job)
+        if _act_on(job, found):
+            return

package/skills/implement-spec/driver_gate.py

@@ -0,0 +1,47 @@
+"""The gate: the repo's one check command, run by the driver on the commit it is about to trust.
+
+A gate record is `<folder>/gate-<first 7 hex of the commit>.log`. It is green only for exit 0 on a tree that is
+clean before the command and after it, with HEAD still on the commit.
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+
+from driver_slots import git, head
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _after(slot: str, commit: str) -> str:
+    """What the command left behind: "clean", or why the record cannot be green."""
+    if head(slot) != commit:
+        return f"HEAD moved to {head(slot)}"
+    status = git(slot, "status", "--short").stdout
+    return "not clean\n" + "".join(f"    {line}\n" for line in status.splitlines()).rstrip("\n") if status else "clean"
+
+
+def run(command: str, slot: str, folder: Path, pr_branch: str) -> tuple[bool, Path]:
+    """Gate the HEAD of `slot`. Returns (green, the record)."""
+    commit = head(slot)
+    status = git(slot, "status", "--short").stdout
+    folder.mkdir(parents=True, exist_ok=True)
+    record = folder / f"gate-{commit[:7]}.log"
+    # The cache of compiled Python stays out of the slot, so the gate leaves the tree clean.
+    env = dict(os.environ, IMPLEMENT_SPEC_BASE=pr_branch, PYTHONPYCACHEPREFIX=str(folder.parent.resolve() / "pycache"))
+    with record.open("w") as out:
+        out.write(f"start: {_now()}\ncommit: {commit}\nstatus: {'not clean' if status else 'clean'}\n")
+        out.writelines(f"    {line}\n" for line in status.splitlines())
+        out.write(f"command: {command}\n\n")
+        out.flush()
+        # shell=True: the command is the operator's own shell line, as `make check` is.
+        code = "not run" if status else subprocess.run(
+            command, shell=True, cwd=slot, env=env, stdin=subprocess.DEVNULL, stdout=out, stderr=subprocess.STDOUT
+        ).returncode
+        after = "not run" if status else _after(slot, commit)
+        out.write(f"\nexit: {code}\nafter: {after}\nend: {_now()}\n")
+    return code == 0 and after == "clean", record

package/skills/implement-spec/driver_graph.py

@@ -0,0 +1,42 @@
+"""The frontier: which tickets may start now, and which wait on a running ticket's Touches."""
+from __future__ import annotations
+
+import re
+
+from driver_tickets import Ticket
+
+
+def touches(ticket: Ticket) -> set[tuple[str, str]]:
+    """(file, function) per backticked entry of the Touches line; function "" is the whole file."""
+    entries = re.findall(r"`([^`]+)`", ticket.touches or "")
+    return {(file.strip(), function.strip()) for file, _, function in (entry.partition(":") for entry in entries)}
+
+
+def overlap(one: Ticket, other: Ticket) -> str:
+    """The first place both tickets name, "" when there is none. A whole file overlaps each function in it."""
+    for file, function in sorted(touches(one)):
+        for other_file, other_function in touches(other):
+            if file == other_file and (not function or not other_function or function == other_function):
+                return f"{file}: {function or other_function}".rstrip(": ")
+    return ""
+
+
+def _waits(ticket: Ticket, phases: dict[str, str], running: set[str]) -> bool:
+    return (ticket.number not in running and phases[ticket.number] not in ("merged", "blocked")
+            and all(phases[blocker] == "merged" for blocker in ticket.blocked_by))
+
+
+def frontier(tickets: list[Ticket], phases: dict[str, str], running: set[str]) -> tuple[list[Ticket], dict[str, str]]:
+    """(ready tickets in file order, held number -> why). Two ready tickets can overlap: start one, then ask again."""
+    by = {t.number: t for t in tickets}
+    ready: list[Ticket] = []
+    holds: dict[str, str] = {}
+    for ticket in tickets:
+        if not _waits(ticket, phases, running):
+            continue
+        holder = next((n for n in sorted(running) if overlap(ticket, by[n])), None)
+        if holder:
+            holds[ticket.number] = f"held while {holder} runs: both touch {overlap(ticket, by[holder])}"
+        else:
+            ready.append(ticket)
+    return ready, holds

package/skills/implement-spec/driver_merge.py

@@ -0,0 +1,105 @@
+"""Merges into the PR branch through git plumbing: no checkout, so no slot's tree changes. Only a conflicting merge
+gets a tree: `begin` opens it in the ticket's own slot for the conflict agent.
+
+`refused` is the locked-file check of a landing. The caller holds the merge lock.
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+
+from driver_slots import git, names
+
+
+def ancestor(commit: str, of: str) -> bool:
+    return git(".", "merge-base", "--is-ancestor", commit, of).returncode == 0
+
+
+def identity(tip: str, slot: str = ".") -> dict[str, str]:
+    """git's own identity when it has one; else the identity of the ticket's last commit, so the merge can be made."""
+    if git(slot, "var", "GIT_COMMITTER_IDENT").returncode == 0:
+        return {}
+    name, email = git(slot, "log", "-1", "--format=%an%n%ae", tip).stdout.splitlines()
+    return {"GIT_AUTHOR_NAME": name, "GIT_AUTHOR_EMAIL": email, "GIT_COMMITTER_NAME": name, "GIT_COMMITTER_EMAIL": email}
+
+
+def commit(pr_tip: str, tip: str, message: str) -> tuple[str, str]:
+    """(the commit the PR branch gets, "") or ("", the error): `pr_tip` when the ticket is merged already, `tip`
+    for a fast-forward, else a new merge commit."""
+    if ancestor(tip, pr_tip):
+        return pr_tip, ""
+    if ancestor(pr_tip, tip):
+        return tip, ""
+    tree = git(".", "merge-tree", "--write-tree", "--name-only", "--no-messages", pr_tip, tip)
+    if tree.returncode:
+        files = ", ".join(tree.stdout.splitlines()[1:]) or tree.stderr.strip()
+        return "", f"the merge into the PR branch conflicts in {files}"
+    made = subprocess.run(["git", "commit-tree", tree.stdout.strip(), "-p", pr_tip, "-p", tip, "-m", message],
+                          capture_output=True, text=True, env={**os.environ, **identity(tip)})
+    return (made.stdout.strip(), "") if made.returncode == 0 else ("", f"git commit-tree failed: {made.stderr.strip()}")
+
+
+def begin(slot: str, pr_tip: str) -> list[str]:
+    """Open the merge of `pr_tip` into the branch of `slot`. Returns the files in conflict; with none, the slot is
+    as it was."""
+    # git merge needs a committer even with --no-commit.
+    env = {**os.environ, **identity("HEAD", slot)}
+    subprocess.run(["git", "-C", slot, "merge", "--no-commit", "--no-ff", pr_tip], capture_output=True, env=env)
+    files = git(slot, "diff", "--name-only", "--diff-filter=U").stdout.splitlines()
+    if not files:
+        abort(slot)
+    return files
+
+
+def abort(slot: str) -> None:
+    """Close the merge that `begin` opened."""
+    git(slot, "merge", "--abort")
+
+
+def protected(tickets: dict, number: str) -> list[str]:
+    """The locked files of the merged tickets that ticket `number` does not lock itself. `tickets` is that of
+    state.json; a record with no `locked` locked nothing."""
+    merged = {path for entry in tickets.values() if entry.get("phase") == "merged" for path in entry.get("locked") or []}
+    return sorted(merged - set(tickets.get(number, {}).get("locked") or []))
+
+
+def _entries(commit: str, paths: list[str]) -> tuple[dict[str, str], str]:
+    """({path: "mode type object-id"} for each of `paths` that `commit` has, "") or ({}, why git cannot tell)."""
+    tree = git(".", "ls-tree", "-z", f"{commit}^{{commit}}", "--", *paths)
+    if tree.returncode:
+        return {}, f"cannot read the locked files at {commit}: {tree.stderr.strip() or f'git ls-tree exit {tree.returncode}'}"
+    return {path: entry for entry, _, path in (line.partition("\t") for line in names(tree.stdout))}, ""
+
+
+def refused(tickets: dict, number: str, old: str, new: str) -> str:
+    """"" or why ticket `number` may not land `new` on the PR tip `old`: each locked file of a merged ticket must
+    be the same blob with the same mode in both."""
+    paths = protected(tickets, number)
+    if not paths:
+        return ""  # `git ls-tree` with no path lists the whole tree
+    (before, error), (after, failed) = _entries(old, paths), _entries(new, paths)
+    return error or failed or "; ".join(f"locked file changed: {path}" for path in paths
+                                        if before.get(path) != after.get(path))
+
+
+def restore(slot: str, pr_tip: str, paths: list[str]) -> list[str]:
+    """Put each of `paths` that the ticket changed back to the version of the PR tip, in the tree of `slot` only; a
+    file the PR tip does not have is removed. Returns those paths."""
+    # Against the merge base: a file that only the PR branch changed since then is not the ticket's change.
+    base = git(slot, "merge-base", "HEAD", pr_tip).stdout.strip() or pr_tip
+    changed = names(git(slot, "diff", "--name-only", "-z", base, "--", *paths).stdout) if paths else []
+    for path in changed:
+        if git(slot, "checkout", "-q", pr_tip, "--", path).returncode:
+            git(slot, "rm", "-q", "-f", "--", path)
+    return changed
+
+
+def land(pr_branch: str, new: str, old: str) -> str:
+    """Move the PR branch from `old` to `new`; "" or the error. git refuses when the branch is no longer at `old`."""
+    moved = git(".", "update-ref", "-m", "implement-spec: merge", f"refs/heads/{pr_branch}", new, old)
+    return moved.stderr.strip() if moved.returncode else ""
+
+
+def delete(branch: str, pr_branch: str) -> bool:
+    """Delete a ticket branch whose commits are all in the PR branch. git refuses one a worktree has checked out."""
+    return ancestor(branch, pr_branch) and git(".", "branch", "-q", "-D", branch).returncode == 0

package/skills/implement-spec/driver_report.py

@@ -0,0 +1,115 @@
+"""Report validation: validate(role, path, context) -> list of errors, empty when the report is accepted.
+
+context: repo (slot path), branch, start (HEAD when the role started), log, round (1 = first review), locked,
+  correction (a test-writer corrects locked tests), restored (locked files the driver put back before it),
+  owners (ticket numbers, for the final fix batch), merged (locked files of merged tickets, not its own), pr (tip)."""
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+from pathlib import Path
+
+import jsonschema
+
+PROMPTS = Path(__file__).resolve().parent / "prompts"
+RED = "red line not found in log"
+
+
+def schema(role: str) -> dict:
+    return json.loads(re.search(r"```json\n(.*?)\n```", (PROMPTS / f"{role}.md").read_text(), re.S).group(1))
+
+
+def _git(repo: str, *args: str, end: str = "\n") -> list[str]:
+    """The lines of a git answer. For a list of paths, pass `-z` and `end="\\0"`: git quotes no path there."""
+    out = subprocess.run(["git", "-C", repo, "-c", "core.quotePath=false", *args], capture_output=True, text=True).stdout
+    return [line for line in out.split(end) if line]
+
+
+def _seen(line: str, log: str) -> bool:
+    # A stream-json log holds tool output as JSON strings, so the escaped form of the line counts too.
+    return line in log or json.dumps(line)[1:-1] in log
+
+
+def _shas(report: dict) -> list[str]:
+    """`commits` as SHAs: the fix batch of the final review gives each commit with its ticket."""
+    return [commit["sha"] if isinstance(commit, dict) else commit for commit in report["commits"]]
+
+
+def _owner_errors(report: dict, context: dict) -> list[str]:
+    """The fix batch of the final review: each new commit on the branch is in the report with a ticket of the run."""
+    if "owners" not in context:
+        return []
+    given, branch = _shas(report), context["branch"]
+    new = _git(context["repo"], "rev-list", f"{context['start']}..{branch}")
+    errors = [f"commit {sha[:7]} is on {branch} and not in `commits`: each commit of the batch needs its ticket"
+              for sha in new if not any(sha.startswith(one) for one in given)]
+    return errors + [f"commit {commit['sha'][:7]}: {commit['ticket']} is not a ticket of this run"
+                     for commit in report["commits"] if commit["ticket"] not in context["owners"]]
+
+
+def _commit_errors(report: dict, context: dict) -> list[str]:
+    """Every commit is new since the role started and on the branch; every locked path is in such a commit."""
+    repo, branch, commits = context["repo"], context["branch"], _shas(report)
+    new = _git(repo, "rev-list", f"{context['start']}..{branch}")
+    errors = [f"commit {sha[:7]} is not a new commit on {branch}"
+              for sha in commits if not any(n.startswith(sha) for n in new)]
+    if locked := report.get("locked"):
+        changed = _git(repo, "log", "--name-only", "-z", "--format=", f"{context['start']}..{branch}", end="\0")
+        errors += [f"locked path {path} is not in the role's commits" for path in locked if path not in changed]
+    return errors
+
+
+def _correction_errors(report: dict, context: dict) -> list[str]:
+    """A correction changes only the files it lists in `locked` and the files the driver `restored`."""
+    if not context.get("correction"):
+        return []
+    changed = _git(context["repo"], "diff", "--name-only", "-z", context["start"], context["branch"], end="\0")
+    more = [path for path in changed if path not in report.get("locked", []) + context.get("restored", [])]
+    return [f"a correction may change only the files it lists in `locked`: its commits also change {', '.join(more)}"
+            ] if more else []
+
+
+def _merged_errors(report: dict, context: dict) -> list[str]:
+    """A test-writer changes a locked file of a merged ticket only when it lists the file in `locked`."""
+    def blob(commit: str, path: str) -> list[str]:
+        return _git(context["repo"], "rev-parse", "-q", "--verify", f"{commit}:{path}")
+
+    return [f"{path} is a locked file of a merged ticket, and `locked` does not list it: list it in `locked`, or "
+            "leave the file as it was" for path in context.get("merged", []) if path not in report.get("locked", [])
+            and blob(context["branch"], path) not in (blob(context["start"], path), blob(context["pr"], path))]
+
+
+def _proof_errors(report: dict, context: dict) -> list[str]:
+    """Every claimed red line (a test-writer `red`, a reviewer `mutations`) is in the agent's log."""
+    lines = [r["line"] for r in report.get("red", [])] + [m["red"] for m in report.get("mutations", [])]
+    errors = []
+    if lines and not all(_seen(line, Path(context["log"]).read_text(errors="replace")) for line in lines):
+        errors.append(RED)
+    if context.get("round") == 1 and "findings" in report and "mutations" not in report:
+        errors.append("mutations: required in round 1")
+    return errors
+
+
+def _locked_errors(report: dict, context: dict) -> list[str]:
+    """In the first review, each locked test file has a mutation proof (`mutations[].test` is `<file>::<test>`)."""
+    if context.get("round") != 1 or "findings" not in report:
+        return []
+    tests = [proof["test"] for proof in report.get("mutations", [])]
+    return [f"mutations: no mutation proof for the locked test file {path}" for path in context.get("locked", [])
+            if not any(test.startswith(path) for test in tests)]
+
+
+def validate(role: str, path: str, context: dict) -> list[str]:
+    try:
+        report = json.loads(Path(path).read_text())
+    except (OSError, ValueError) as exc:
+        return [f"report {path} is not readable JSON: {exc}"]
+    rules = schema(role)
+    found = sorted(jsonschema.Draft202012Validator(rules).iter_errors(report), key=lambda e: str(list(e.path)))
+    if found:
+        return [f"{'.'.join(map(str, e.path)) or 'report'}: {e.message}" for e in found]
+    # The schema types only the role's own fields: any other field of the report is dropped.
+    report = {name: value for name, value in report.items() if name in rules["properties"]}
+    return (_commit_errors(report, context) + _owner_errors(report, context) + _correction_errors(report, context)
+            + _merged_errors(report, context) + _proof_errors(report, context) + _locked_errors(report, context))

package/skills/implement-spec/driver_review.py

@@ -0,0 +1,126 @@
+"""The driver's own part of a review: the locked-file check of the ticket's own tests, the routing of the findings,
+and the mutation proofs that a fix makes due again.
+
+A finding is the dict of the reviewer schema plus `source`: the role that reported it, or `driver`.
+A mutation proof is keyed by (production file, line); the line is the one the file has at the ticket tip.
+"""
+from __future__ import annotations
+
+import re
+import driver_agents
+from driver_slots import git, head, names
+from driver_tickets import Ticket
+
+# The correctness pass reads this file of the review-diff skill, which is installed next to this one.
+CORRECTNESS = driver_agents.SKILL.parent / "review-diff" / "correctness.md"
+OPEN = ("critical", "important")  # the severities that start a fix round
+_HUNK = re.compile(r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@", re.M)
+
+
+def precondition_errors(tickets: list[Ticket]) -> list[str]:
+    """[] or the error that stops the run before any agent: a ticket with a Risk line needs CORRECTNESS."""
+    risky = [ticket.number for ticket in tickets if ticket.risk]
+    if CORRECTNESS.exists() or not risky:
+        return []
+    return [f"{CORRECTNESS} is missing: ticket {', '.join(risky)} has a Risk line and its correctness pass reads "
+            "that file; install the review-diff skill next to implement-spec"]
+
+
+def locked_changes(slot: str, sha: str | None, locked: list[str]) -> list[dict]:
+    """One critical finding per locked file that differs from the test-writer's commit `sha`, or for a diff that
+    git cannot make."""
+    if not (sha and locked):
+        return []  # a refactor ticket has no test-writer
+    diff = git(slot, "diff", "--name-only", "-z", f"{sha}..HEAD", "--", *locked)
+    titles = ({path: f"locked file changed: {path}" for path in names(diff.stdout)} if diff.returncode == 0
+              else {locked[0]: f"locked file check failed: {diff.stderr.strip()}"})
+    return [{"severity": "critical", "file": path, "line": 1, "title": title, "kind": "code", "source": "driver",
+             "evidence": f"git diff {sha}..HEAD -- {path}"} for path, title in titles.items()]
+
+
+def _references(entry: dict) -> list[tuple[str | None, list[str]]]:
+    """(reference commit, the locked files it is the reference of): `test_writer_sha`, or the older commit that
+    `held` names for a file."""
+    held = entry["held"]
+    groups = [(entry["test_writer_sha"], [path for path in entry["locked"] if path not in held])]
+    return groups + [(sha, [path for path, at in held.items() if at == sha]) for sha in dict.fromkeys(held.values())]
+
+
+def locked_findings(slot: str, entry: dict) -> list[dict]:
+    """The locked-file check for the ticket record `entry`."""
+    return [finding for sha, paths in _references(entry) for finding in locked_changes(slot, sha, paths)]
+
+
+def restore_locked(slot: str, entry: dict) -> list[str]:
+    """Put each locked file that differs from its reference back to the reference version, in the tree only.
+    Returns those paths."""
+    restored = []
+    for sha, paths in _references(entry):
+        if sha and paths:
+            restored += names(git(slot, "diff", "--name-only", "-z", sha, "--", *paths).stdout)
+    for path in restored:
+        git(slot, "checkout", "-q", entry["held"].get(path, entry["test_writer_sha"]), "--", path)
+    return restored
+
+
+def written(slot: str, entry: dict, listed: list[str], tip: str) -> dict:
+    """The locked-file fields of the ticket record after a test-writer commit at `tip` that lists `listed`.
+    `tip` is the new reference. A locked file that a correction does not list and that differs from the old
+    reference keeps the old one in `held`, so a change the implementer made before stays a finding."""
+    held = {path: sha for path, sha in entry["held"].items() if path not in listed}
+    others = [path for path in entry["locked"] if path not in listed and path not in held]
+    if entry["test_writer_sha"] and others:
+        diff = git(slot, "diff", "--name-only", "-z", entry["test_writer_sha"], tip, "--", *others)
+        # A diff that git cannot make holds each file.
+        held.update(dict.fromkeys(names(diff.stdout) if diff.returncode == 0 else others, entry["test_writer_sha"]))
+    return {"test_writer_sha": tip, "locked": list(dict.fromkeys(entry["locked"] + listed)), "held": held}
+
+
+def route(findings: list[dict]) -> tuple[list[dict], list[dict]]:
+    """(the fixture findings, whatever their severity; the other findings that are severe enough for a fix round)."""
+    fixture = [finding for finding in findings if finding["kind"] == "fixture"]
+    return fixture, [finding for finding in findings if finding["kind"] != "fixture" and finding["severity"] in OPEN]
+
+
+def _hunks(slot: str, old: str, new: str, file: str) -> list[tuple[int, int, int, int]]:
+    """(first old line, old count, first new line, new count) per hunk of `file`, with no context lines."""
+    diff = git(slot, "diff", "-U0", old, new, "--", file).stdout
+    return [(int(a), int(b or 1), int(c), int(d or 1)) for a, b, c, d in _HUNK.findall(diff)]
+
+
+def _follow(line: int, hunks: list[tuple[int, int, int, int]]) -> tuple[int, bool]:
+    """(the number old `line` has after the hunks, whether a hunk changed the line)."""
+    shift = 0
+    for a, b, c, d in hunks:
+        if a <= line < a + b:
+            return c + min(line - a, max(d - 1, 0)), True
+        if line >= a + max(b, 1):  # a hunk with no old line is an insert after line `a`
+            shift += d - b
+    return line + shift, False
+
+
+def follow(slot: str, old: str, new: str, proofs: set[tuple[str, int]]) -> dict[tuple[str, int], bool]:
+    """The proofs of commit `old` as they are at `new`: (file, new line) -> whether the fix changed that line, so
+    its proof is due again."""
+    # ponytail: a renamed file reads as deleted, so each of its proofs is due again; follow renames if that costs.
+    hunks = {file: _hunks(slot, old, new, file) for file in {file for file, _ in proofs}}
+    found: dict[tuple[str, int], bool] = {}
+    for file, line in sorted(proofs):
+        at, changed = _follow(line, hunks[file])
+        found[file, at] = changed or found.get((file, at), False)
+    return found
+
+
+def restore(slot: str, branch: str, tip: str) -> None:
+    """Put the slot back on `branch` at `tip` with a clean tree. Only for a read-only role: its edits, commits and
+    untracked files go. Ignored files stay."""
+    git(slot, "checkout", "-q", "-f", "-B", branch, tip)
+    git(slot, "clean", "-q", "-fd")
+
+
+def disturbed(slot: str, branch: str, tip: str) -> str:
+    """"" when the slot is still on `branch` at `tip` with a clean tree, else what the read-only agents left."""
+    if git(slot, "symbolic-ref", "-q", "--short", "HEAD").stdout.strip() != branch or head(slot) != tip:
+        return f"the slot is no longer on {branch} at {tip[:7]}"
+    left = [line[3:] for line in git(slot, "status", "--porcelain").stdout.splitlines()]
+    return f"the tree is not as the review found it: {', '.join(left)}" if left else ""