research-diff 0.1.0__py3-none-any.whl

research_diff/__init__.py

@@ -0,0 +1,2 @@
+"""research-diff: your research as a map, and what each iteration changed in it."""
+__version__ = "0.1.0"

research_diff/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

research_diff/agent.py

@@ -0,0 +1,141 @@
+"""Claude Code: `research-diff hook`, run by its Stop hook after every turn, and `research-diff setup claude`, which adds
+the hook, a skill on when to show the research diff, and the MCP server. The hook never blocks and never fails a turn;
+setup prints each change, and `--undo` takes it back."""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Callable, Optional
+
+from system_diff.agent import _claude, _is_repo, _load, _save, _split
+from system_diff.sources import git
+
+from .compare import compare, sync_trackers
+
+NAME = "research-diff"
+SKILL_MARK = "<!-- written by research-diff setup claude -->"
+SKILL = f"""---
+name: research-diff
+description: Shows the person what an iteration did to their research (questions, hypotheses, experiments, results, claims). Use after running an experiment, changing a hypothesis, notes, a config or the paper, before asking them to review, or when they ask where the research stands.
+---
+{SKILL_MARK}
+
+# Showing the research diff
+
+The research is described by markers in the repository's own files: `H2: title` with `status:`, `tests:`,
+`supports:`, `weakens:`, `relies on:` lines in notes, `% C1: …` in the paper, a `research:` block or a
+`# research-diff: E5 tests H2` comment in experiment configs and scripts.
+
+1. When you add an idea, an experiment or a claim, write its marker, so it is on the map.
+2. After running an experiment, record what came out with the `log_result` tool (the metrics, and which hypothesis it
+   supports or weakens), or as a results file the experiment's `research:` block names.
+3. Call `research_diff` and tell the person, in two or three plain sentences built only from its plan, what changed:
+   statuses that moved, numbers that changed, new warnings (a claim relying on a refuted hypothesis, an open hypothesis
+   no experiment tests).
+4. Point them at the picture, or at `research-diff watch` for a live page.
+5. When they say they have understood it, call `checkpoint`, so the next diff shows only what is new to them.
+
+Never report a result the plan does not show, and never mark a hypothesis supported or refuted without their say.
+"""
+SCOPES = ("user", "project", "local")
+
+
+def hook_message(root: Path) -> Optional[str]:
+    sync_trackers(root)   # runs logged to MLflow or W&B during the turn count too
+    c = compare(root, "checkpoint", ".")
+    if not c.diff["changes"]:
+        return None
+    return f"Research diff since {c.base}: {c.diff['headline']} (`research-diff watch` shows the picture.)"
+
+
+def run_hook(stdin_text: str, emit: Callable[[str], None] = print) -> int:
+    try:
+        payload = json.loads(stdin_text) if stdin_text.strip() else {}
+    except ValueError:
+        payload = {}
+    cwd = Path(payload.get("cwd") or os.getcwd())
+    if not _is_repo(cwd):
+        return 0
+    try:
+        message = hook_message(Path(git("rev-parse", "--show-toplevel", cwd=cwd).strip()))
+    except (OSError, subprocess.CalledProcessError, ValueError, KeyError):
+        return 0
+    if message:
+        emit(json.dumps({"systemMessage": message}))
+    return 0
+
+
+def command() -> str:
+    if shutil.which(NAME):
+        return NAME
+    exe = sys.executable
+    return f'"{exe}" -m research_diff' if " " in exe else f"{exe} -m research_diff"
+
+
+def _paths(scope: str, root: Path) -> tuple:
+    home = Path.home() / ".claude"
+    settings = {"user": home / "settings.json", "project": root / ".claude" / "settings.json",
+                "local": root / ".claude" / "settings.local.json"}[scope]
+    return settings, (home / "skills" if scope == "user" else root / ".claude" / "skills") / NAME / "SKILL.md"
+
+
+def _ours(entry: dict) -> bool:
+    return any(c in h.get("command", "") for h in entry.get("hooks", []) for c in ("research-diff hook", "research_diff hook"))
+
+
+def setup_claude(root: Path, scope: str = "user", undo: bool = False, out: Callable[[str], None] = print) -> int:
+    settings_path, skill_path = _paths(scope, root)
+    settings = _load(settings_path)
+    stop = settings.setdefault("hooks", {}).setdefault("Stop", [])
+    ours = [e for e in stop if _ours(e)]
+    has_claude = shutil.which("claude") is not None
+    if undo:
+        if ours:
+            settings["hooks"]["Stop"] = [e for e in stop if not _ours(e)]
+            if not settings["hooks"]["Stop"]:
+                del settings["hooks"]["Stop"]
+            if not settings["hooks"]:
+                del settings["hooks"]
+            _save(settings_path, settings)
+            out(f"removed the Stop hook from {settings_path}")
+        if skill_path.is_file() and SKILL_MARK in skill_path.read_text(encoding="utf-8"):
+            skill_path.unlink()
+            if not any(skill_path.parent.iterdir()):
+                skill_path.parent.rmdir()
+            out(f"removed the skill {skill_path}")
+        if has_claude and _claude(["mcp", "get", NAME]).returncode == 0:
+            got = _claude(["mcp", "remove", NAME, "--scope", scope])
+            out("removed the MCP server" if got.returncode == 0 else f"could not remove the MCP server: {got.stderr.strip()[:200]}")
+        return 0
+    if ours:
+        out(f"the Stop hook is already in {settings_path}")
+    else:
+        stop.append({"hooks": [{"type": "command", "command": f"{command()} hook", "timeout": 30}]})
+        _save(settings_path, settings)
+        out(f"added a Stop hook to {settings_path}: after each turn, one line on what changed in the research")
+    if skill_path.is_file() and SKILL_MARK not in skill_path.read_text(encoding="utf-8"):
+        out(f"left {skill_path} alone: someone else wrote it")
+    elif not (skill_path.is_file() and skill_path.read_text(encoding="utf-8") == SKILL):
+        skill_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(skill_path, "w", encoding="utf-8", newline="\n") as f:
+            f.write(SKILL)
+        out(f"wrote the skill {skill_path}")
+    if not has_claude:
+        out("`claude` is not on PATH, so the MCP server was not registered; run setup again where it is")
+        return 0
+    try:
+        import mcp  # noqa: F401
+    except ImportError:
+        out('the MCP server needs its extra: pip install "research-diff[mcp]", then run setup again')
+        return 0
+    if _claude(["mcp", "get", NAME]).returncode == 0:
+        out("the MCP server is already registered")
+    else:
+        got = _claude(["mcp", "add", "--scope", scope, "--transport", "stdio", NAME, "--", *_split(command()), "mcp"])
+        out(f"registered the MCP server ({scope} scope)" if got.returncode == 0
+            else f"could not register the MCP server: {(got.stderr or got.stdout).strip()[:200]}")
+    return 0

research_diff/cli.py

@@ -0,0 +1,153 @@
+"""research-diff: your research as a map (questions, hypotheses, experiments, results, claims), and what each iteration
+changed in it.
+
+    research-diff map  [--at REF|.] [--out DIR] [--check]           -> research.json, research.svg
+    research-diff diff [--base checkpoint|REF] [--head .|REF] [--out DIR]
+                                                                    -> diff.json, diff.svg, plan.txt, headline.txt
+    research-diff sync                                              -> MLflow / W&B runs into research/runs.json
+    research-diff suggest [FILE...]                                 -> your LLM proposes markers, as a patch
+    research-diff checkpoint [--ref REF]                            -> mark what you have understood
+    research-diff watch [--port 8766]                               -> a live page of the diff since then
+    research-diff readme [--check]                                  -> the README's generated research map
+    research-diff setup claude [--scope user|project|local] [--undo] -> the hook, a skill and the MCP server
+    research-diff hook | mcp                                        -> what Claude Code runs
+
+`.` is the working tree, untracked files included, read without touching your index, HEAD or branches.
+`checkpoint` is what you last marked as understood (HEAD until you mark something).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+from system_diff.pictures import write_if_changed
+from system_diff.sources import repo_root
+
+from . import __version__, compare, graph, readme
+from .diff import PLURAL
+
+
+def _write(path: Path, text: str, check: bool) -> bool:
+    if check:
+        return not path.is_file() or path.read_text(encoding="utf-8") != text
+    write_if_changed(path, text)
+    return False
+
+
+def _map(args, root: Path) -> int:
+    bp, cfg, label = compare.read(root, args.at, args.config)
+    out = Path(args.out)
+    if not args.check:
+        out.mkdir(parents=True, exist_ok=True)
+    stale = _write(out / "research.json", json.dumps(bp, indent=1, ensure_ascii=False) + "\n", args.check)
+    stale |= _write(out / "research.svg", graph.map_svg(bp, cfg), args.check)
+    if args.check:
+        print(f"research map {'is out of date' if stale else 'is current'}: {out}/research.svg")
+        return 1 if stale else 0
+    kinds = {}
+    for n in bp["nodes"].values():
+        kinds[n["kind"]] = kinds.get(n["kind"], 0) + 1
+    print(f"research map of {label}: " + ", ".join(f"{v} {k if v == 1 else PLURAL.get(k, k + 's')}" for k, v in kinds.items())
+          + f", {len(bp['warnings'])} warnings -> {out}/research.svg")
+    return 0
+
+
+def _diff(args, root: Path) -> int:
+    c = compare.compare(root, args.base, args.head, args.config)
+    out = Path(args.out)
+    out.mkdir(parents=True, exist_ok=True)
+    for name, text in (("diff.json", json.dumps(c.diff, indent=1, ensure_ascii=False)), ("plan.txt", c.diff["plan"]),
+                       ("headline.txt", c.diff["headline"])):
+        (out / name).write_text(text + "\n", encoding="utf-8", newline="\n")
+    svg = graph.diff_svg(c.diff, c.before, c.after, c.cfg)
+    if svg:
+        write_if_changed(out / "diff.svg", svg)
+    elif (out / "diff.svg").is_file():
+        (out / "diff.svg").unlink()
+    print(c.diff["headline"])
+    return 0
+
+
+def parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(prog="research-diff", description=__doc__.split("\n")[0],
+                                 formatter_class=argparse.RawDescriptionHelpFormatter,
+                                 epilog="\n".join(__doc__.split("\n")[2:]))
+    ap.add_argument("--version", action="version", version=f"research-diff {__version__}")
+    ap.add_argument("--repo", help="the repository (default: the one holding the current directory)")
+    ap.add_argument("--config", help="a TOML or JSON config (default: research-diff.toml or [tool.research-diff])")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    m = sub.add_parser("map", help="the research as it is: research.json and research.svg")
+    m.add_argument("--at", default=".", help="a commit, or . for the working tree (default)")
+    m.add_argument("--out", default=".")
+    m.add_argument("--check", action="store_true", help="write nothing; exit 1 if the files are out of date")
+    d = sub.add_parser("diff", help="what an iteration changed")
+    d.add_argument("--base", default="checkpoint", help="a commit, or checkpoint (default)")
+    d.add_argument("--head", default=".", help="a commit, or . for the working tree (default)")
+    d.add_argument("--out", default=".")
+    sub.add_parser("sync", help="copy MLflow and W&B runs tagged with an experiment id into research/runs.json")
+    sg = sub.add_parser("suggest", help="your LLM proposes markers for untagged files, as a patch you apply or not")
+    sg.add_argument("files", nargs="*", help="files to read (default: notes and paper files with no marker)")
+    sg.add_argument("--out", default="", help="where to write the patch (default .git/research-diff/suggest.patch)")
+    c = sub.add_parser("checkpoint", help="mark what you have understood")
+    c.add_argument("--ref", help="a commit to mark instead of the working tree")
+    w = sub.add_parser("watch", help="a live local page of the diff since the checkpoint")
+    w.add_argument("--base", default="checkpoint")
+    w.add_argument("--port", type=int, default=8766)
+    w.add_argument("--interval", type=float, default=2.0)
+    r = sub.add_parser("readme", help="rewrite the README's research-map section")
+    r.add_argument("--check", action="store_true")
+    st = sub.add_parser("setup", help="wire research-diff into an AI coding tool")
+    st.add_argument("tool", choices=["claude"])
+    st.add_argument("--scope", default="user", choices=["user", "project", "local"])
+    st.add_argument("--undo", action="store_true")
+    sub.add_parser("hook", help="what Claude Code's Stop hook runs")
+    sub.add_parser("mcp", help="the MCP server over stdio (needs the [mcp] extra)")
+    return ap
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = parser().parse_args(argv)
+    root = repo_root(Path(args.repo) if args.repo else None)
+    if args.cmd == "map":
+        return _map(args, root)
+    if args.cmd == "diff":
+        return _diff(args, root)
+    if args.cmd == "sync":
+        got = compare.sync_trackers(root, args.config)
+        print(f"{got['runs']} tracker runs" + (" written to research/runs.json" if got["written"] else ", nothing changed"))
+        return 0
+    if args.cmd == "suggest":
+        from . import suggest
+        return suggest.run(root, args.files, args.out, args.config)
+    if args.cmd == "checkpoint":
+        sha = compare.checkpoint(root, args.ref)
+        print(f"checkpoint: {args.ref or 'the working tree'} ({sha[:9]}) is what you have understood")
+        return 0
+    if args.cmd == "readme":
+        return readme.run(root, args.config, args.check)
+    if args.cmd == "watch":
+        from . import watch
+        watch.serve(root, args.base, args.port, args.config, args.interval)
+        return 0
+    if args.cmd == "setup":
+        from . import agent
+        return agent.setup_claude(root, args.scope, args.undo)
+    if args.cmd == "hook":
+        from . import agent
+        return agent.run_hook(sys.stdin.read() if not sys.stdin.isatty() else "")
+    if args.cmd == "mcp":
+        try:
+            from . import mcp_server
+        except ImportError:
+            print('research-diff: the MCP server needs its extra: pip install "research-diff[mcp]"', file=sys.stderr)
+            return 1
+        mcp_server.main()
+        return 0
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

research_diff/compare.py

@@ -0,0 +1,76 @@
+"""Two points in the research's life, compared: a commit, the working tree (`.`, read as a snapshot that touches
+nothing the person uses), or the CHECKPOINT, the last state they marked as understood. research-diff keeps its own
+checkpoint (refs/research-diff/checkpoint), apart from system-diff's, in this clone only."""
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from system_diff.compare import snapshot
+from system_diff.sources import GitSource, git
+
+from . import config
+from .diff import diff
+from .extract import extract
+
+CHECKPOINT_REF = "refs/research-diff/checkpoint"
+WORKTREE = (".", "worktree")
+
+
+def _rev(root: Path, ref: str) -> Optional[str]:
+    try:
+        return git("rev-parse", "--verify", "-q", ref, cwd=root).strip() or None
+    except subprocess.CalledProcessError:
+        return None
+
+
+def sync_trackers(root: Path, config_path: Optional[str] = None) -> Dict[str, Any]:
+    """Copy the trackers' tagged runs into research/runs.json (see trackers.py); a no-op without tracker folders."""
+    from .trackers import sync
+    t = config.load(None, root, config_path)["trackers"]
+    return sync(root, t.get("mlflow", "mlruns"), t.get("wandb", "wandb"))
+
+
+def checkpoint(root: Path, ref: Optional[str] = None) -> str:
+    sha = git("rev-parse", "--verify", f"{ref}^{{commit}}", cwd=root).strip() if ref else snapshot(root)
+    git("update-ref", CHECKPOINT_REF, sha, cwd=root)
+    return sha
+
+
+def resolve(root: Path, point: str) -> tuple:
+    if point == "checkpoint":
+        sha = _rev(root, CHECKPOINT_REF)
+        return (sha, "checkpoint") if sha else (_rev(root, "HEAD") or snapshot(root), "HEAD (no checkpoint yet)")
+    if point in WORKTREE:
+        return snapshot(root), "working tree"
+    return git("rev-parse", "--verify", f"{point}^{{commit}}", cwd=root).strip(), point
+
+
+def read(root: Path, point: str = ".", config_path: Optional[str] = None) -> tuple:
+    """(map, config, label) of one point."""
+    sha, label = resolve(root, point)
+    src = GitSource(sha, root)
+    cfg = config.load(src, root, config_path)
+    bp = extract(src, cfg)
+    bp["ref"] = label if point == "checkpoint" or point in WORKTREE else bp["ref"]
+    return bp, cfg, label
+
+
+@dataclass
+class Comparison:
+    diff: Dict[str, Any]
+    before: Dict[str, Any]
+    after: Dict[str, Any]
+    cfg: Dict[str, Any]
+    base: str
+
+
+def compare(root: Path, base: str = "checkpoint", head: str = ".", config_path: Optional[str] = None) -> Comparison:
+    b, cfg, _ = read(root, head, config_path)
+    a_sha, a_label = resolve(root, base)
+    a = extract(GitSource(a_sha, root), cfg)   # one vocabulary for both sides: the head's
+    if base == "checkpoint" or base in WORKTREE:
+        a["ref"] = a_label
+    return Comparison(diff(a, b), a, b, cfg, a_label)

research_diff/config.py

@@ -0,0 +1,61 @@
+"""What a research project tells research-diff about itself: which files hold its notes, experiment configs, scripts
+and paper. Read from `--config`, else `research-diff.toml`, else `[tool.research-diff]` in pyproject.toml; every key
+is optional, and with none every Markdown, config, Python and LaTeX file is read for markers.
+"""
+from __future__ import annotations
+
+import json
+import tomllib
+from copy import deepcopy
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+FILE = "research-diff.toml"
+
+DEFAULTS: Dict[str, Any] = {
+    "notes": ["**/*.md"],
+    "configs": ["**/*.yaml", "**/*.yml", "**/*.json", "**/*.toml"],
+    "scripts": ["**/*.py", "**/*.ipynb"],
+    "paper": ["**/*.tex"],
+    "runs": ["research/runs.json"],               # tracker runs, written by `research-diff sync`
+    "trackers": {"mlflow": "mlruns", "wandb": "wandb"},
+    "skip": ["node_modules", "__pycache__", "dist", "build", ".venv*", "venv", ".git", "site-packages"],
+    "ignore": ["README.md", "CHANGELOG.md"],     # never read for markers (globs)
+    "kinds": {"Q": "question", "H": "hypothesis", "E": "experiment", "R": "result", "C": "claim"},
+    "picture": {"columns": [["question", "Questions"], ["hypothesis", "Hypotheses"], ["experiment", "Experiments"],
+                            ["result", "Results"], ["claim", "Claims"]]},
+    "readme": {"file": "README.md", "svg": "docs/research.svg",   # the picture's file; `image` links to it (default: the file)
+               "image": "",
+               "begin": "<!-- research-map:begin -->", "end": "<!-- research-map:end -->"},
+}
+
+
+def merge(base: Dict[str, Any], over: Dict[str, Any]) -> Dict[str, Any]:
+    out = deepcopy(base)
+    for k, v in (over or {}).items():
+        out[k] = merge(out[k], v) if isinstance(v, dict) and isinstance(out.get(k), dict) else deepcopy(v)
+    return out
+
+
+def parse(text: str, name: str) -> Dict[str, Any]:
+    if not text.strip():
+        return {}
+    if name.endswith(".json"):
+        return json.loads(text)
+    data = tomllib.loads(text)
+    return data.get("tool", {}).get("research-diff", {}) if name.endswith("pyproject.toml") else data
+
+
+def load(source=None, root: Optional[Path] = None, path: Optional[str] = None) -> Dict[str, Any]:
+    """The project's settings over the defaults; the commit's own research-diff.toml wins over the one on disk."""
+    if path:
+        p = Path(path)
+        return merge(DEFAULTS, parse(p.read_text(encoding="utf-8"), p.name))
+    for name in (FILE, "pyproject.toml"):
+        text = source.read(name) if source is not None and name in source.files else ""
+        if not text and root is not None and (root / name).is_file():
+            text = (root / name).read_text(encoding="utf-8")
+        got = parse(text, name) if text else {}
+        if got:
+            return merge(DEFAULTS, got)
+    return deepcopy(DEFAULTS)

research_diff/diff.py

@@ -0,0 +1,106 @@
+"""What an iteration did to the research: ideas added or dropped, statuses that moved, numbers that changed, links made
+or broken, and warnings that appeared or went away. One sentence (headline) and the exact list (plan)."""
+from __future__ import annotations
+
+from typing import Dict, List
+
+PLURAL = {"question": "questions", "hypothesis": "hypotheses", "experiment": "experiments", "result": "results",
+          "claim": "claims", "note": "notes"}
+
+
+def _num(x: float) -> str:
+    return f"{x:.4g}"
+
+
+def diff(a: dict, b: dict) -> dict:
+    changes: List[dict] = []
+
+    def add(op, entity, key, label="", detail=(), impact=()):
+        changes.append({"op": op, "entity": entity, "id": key, "label": label or key, "detail": list(detail),
+                        "impact": list(impact)})
+
+    na, nb = a["nodes"], b["nodes"]
+    for nid in [k for k in nb if k not in na] + [k for k in na if k not in nb]:
+        n = nb.get(nid) or na[nid]
+        op = "add" if nid in nb else "remove"
+        add(op, n["kind"], nid, f"{nid}: {n['title']}" if n["title"] else nid,
+            [f"status: {n['status']}"] if n["status"] and op == "add" else [], [("new-" if op == "add" else "dropped-") + n["kind"]])
+    for nid in [k for k in nb if k in na]:
+        x, y = na[nid], nb[nid]
+        if x["status"] != y["status"]:
+            impact = "refuted" if y["status"] == "refuted" else "supported" if y["status"] == "supported" else "status-change"
+            add("change", "status", nid, f"{nid}: {x['status'] or 'no status'} → {y['status'] or 'no status'}", [], [impact])
+        if x["title"] != y["title"] and x["title"] and y["title"]:
+            add("change", "title", nid, f"{nid}: {y['title']}", [f"was: {x['title']}"])
+        for key in sorted(set(x["metrics"]) | set(y["metrics"])):
+            u, v = x["metrics"].get(key), y["metrics"].get(key)
+            if u == v:
+                continue
+            if u is None:
+                add("add", "metric", f"{nid} {key}", f"{nid} {key}: {_num(v)}", [], ["new-result"])
+            elif v is None:
+                add("remove", "metric", f"{nid} {key}", f"{nid} {key}", [f"was {_num(u)}"], ["dropped-result"])
+            else:
+                d = v - u
+                add("change", "metric", f"{nid} {key}", f"{nid} {key}: {_num(u)} → {_num(v)}",
+                    [f"{'+' if d >= 0 else '−'}{_num(abs(d))}" + (f" ({d / u * 100:+.1f}%)" if u else "")], ["result-moved"])
+    la, lb = {tuple(x) for x in a["links"]}, {tuple(x) for x in b["links"]}
+    for link in sorted(lb - la) + sorted(la - lb):
+        add("add" if link in lb else "remove", "link", " ".join(link), "", [], [])
+    wa, wb = set(a["warnings"]), set(b["warnings"])
+    for w in sorted(wb - wa):
+        add("add", "warning", w, "", [], ["new-warning"])
+    for w in sorted(wa - wb):
+        add("remove", "warning", w, "", [], ["resolved-warning"])
+    return {"from": a["ref"], "to": b["ref"], "changes": changes, "headline": headline(changes),
+            "plan": plan(changes), "warnings": b["warnings"]}
+
+
+def headline(changes: List[dict]) -> str:
+    """One sentence: what the iteration did to the research."""
+    parts: List[str] = []
+    for op, verb in (("add", "adds"), ("remove", "drops")):
+        groups: Dict[str, List[str]] = {}
+        for c in changes:
+            if c["op"] == op and c["entity"] in PLURAL:
+                groups.setdefault(c["entity"], []).append(c["id"])
+        phrases = [f"{len(ids)} {k if len(ids) == 1 else PLURAL[k]} ({', '.join(ids[:3])}{' +' + str(len(ids) - 3) + ' more' if len(ids) > 3 else ''})"
+                   for k, ids in groups.items()]
+        if phrases:
+            parts.append(verb + " " + (", ".join(phrases[:-1]) + " and " + phrases[-1] if len(phrases) > 1 else phrases[0]))
+    parts += [c["label"] for c in changes if c["entity"] == "status"]
+    moved = [c for c in changes if c["entity"] == "metric" and c["op"] == "change"]
+    if moved:
+        shown = "; ".join(f"{c['label']} ({c['detail'][0]})" for c in moved[:2])
+        parts.append(shown + (f" and {len(moved) - 2} more numbers" if len(moved) > 2 else ""))
+    new_metrics = [c for c in changes if c["entity"] == "metric" and c["op"] == "add"]
+    if new_metrics:
+        parts.append(f"{len(new_metrics)} new number{'' if len(new_metrics) == 1 else 's'}")
+    links = [c for c in changes if c["entity"] == "link"]
+    if links:
+        made = sum(1 for c in links if c["op"] == "add")
+        parts.append(" and ".join(x for x in (f"{made} new link{'' if made == 1 else 's'}" if made else "",
+                                              f"{len(links) - made} link{'' if len(links) - made == 1 else 's'} gone"
+                                              if len(links) - made else "") if x))
+    new_w = [c["id"] for c in changes if c["entity"] == "warning" and c["op"] == "add"]
+    if new_w:
+        parts.append(f"{len(new_w)} new warning{'' if len(new_w) == 1 else 's'} ({new_w[0]}{'…' if len(new_w) > 1 else ''})")
+    gone_w = sum(1 for c in changes if c["entity"] == "warning" and c["op"] == "remove")
+    if gone_w:
+        parts.append(f"{gone_w} warning{'' if gone_w == 1 else 's'} resolved")
+    if not parts:
+        return "No change to the research."
+    s = "; ".join(parts)
+    return s[0].upper() + s[1:] + "."
+
+
+def plan(changes: List[dict]) -> str:
+    """The exact list, `terraform plan`-style."""
+    sym = {"add": "+", "change": "~", "remove": "-"}
+    out = []
+    for c in changes:
+        tag = f"   [{', '.join(c['impact'])}]" if c["impact"] else ""
+        label = f" — {c['label']}" if c["label"] != c["id"] else ""
+        out.append(f"{sym[c['op']]} {c['entity']} {c['id']}{label}{tag}")
+        out += [f"    {x}" for x in c["detail"]]
+    return "\n".join(out) or "no change to the research"