maintainability-agent 2.5.0__tar.gz → 2.6.0__tar.gz

{maintainability_agent-2.5.0/src/maintainability_agent.egg-info → maintainability_agent-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 2.5.0
+Version: 2.6.0
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -44,7 +44,7 @@ Dynamic: license-file
 **A deterministic, offline maintainability audit whose output is a _bounded
 work order_ for an AI coding agent** — a copy-paste prompt, per finding, that
 says *fix exactly these and refactor nothing else*. Chat-primary; CLI for CI.
-Version **2.5.0**.
+Version **2.6.0**.
 
 **Languages parsed:** Python, Java, C, C++, C#, Swift, Fortran (free-form
 *and* fixed-form), and the JS/TS family — each by a scanner written for it, and
@@ -152,9 +152,8 @@ registered verdict stands at **INCONCLUSIVE**. Method, limits and raw data:
 every claim the project could not stand behind was removed. A scoring engine
 rebuilt after it was found to grade repo *size*; a headline claim about AI
 authorship retracted against a matched control; a score that is withheld rather
-than guessed. That arc is the credibility, and it is recorded in full — with the
-figures quoted from their approved summaries — in
-[the track record](docs/track-record.md).
+than guessed. That arc is the credibility, and it is recorded in full, with the
+figures quoted from their approved summaries, in [the track record](docs/track-record.md).
 
 ## Install
 
@@ -223,8 +222,8 @@ withheld and the scope is named as the reason.
 ### Checking that the agent did the work
 
 The work order tells an agent to fix exactly these findings and refactor nothing
-else. These flags check that the diff that came back obeyed it — read the
-diff's _shape_, not its correctness:
+else. These flags check that the diff obeyed it — they read its _shape_, not its
+correctness:
 
 ```bash
 maintainability-agent \
@@ -251,6 +250,11 @@ maintainability-agent \
   work order, and what moved. It is reproducible and **not signed** — nothing
   here holds a key, and the document says so in its own text. A check nobody ran
   renders as _not asked_, never as passed.
+- **`--transformation NAME`** names the class of work a scan followed and
+  reports how this run of it compares with earlier ones. **A report, never a
+  gate.** It says one run "moved further" than another, never that it was
+  _better_ — two runs of one codemod land on different code — and it measures
+  the interval, not the transformation.
 
 The [roadmap](docs/roadmap.md#the-remediation-hole-closed-in-210-through-230)
 has the history of why this was the hole under the product's central claim.

{maintainability_agent-2.5.0 → maintainability_agent-2.6.0}/README.md

@@ -5,7 +5,7 @@
 **A deterministic, offline maintainability audit whose output is a _bounded
 work order_ for an AI coding agent** — a copy-paste prompt, per finding, that
 says *fix exactly these and refactor nothing else*. Chat-primary; CLI for CI.
-Version **2.5.0**.
+Version **2.6.0**.
 
 **Languages parsed:** Python, Java, C, C++, C#, Swift, Fortran (free-form
 *and* fixed-form), and the JS/TS family — each by a scanner written for it, and
@@ -113,9 +113,8 @@ registered verdict stands at **INCONCLUSIVE**. Method, limits and raw data:
 every claim the project could not stand behind was removed. A scoring engine
 rebuilt after it was found to grade repo *size*; a headline claim about AI
 authorship retracted against a matched control; a score that is withheld rather
-than guessed. That arc is the credibility, and it is recorded in full — with the
-figures quoted from their approved summaries — in
-[the track record](docs/track-record.md).
+than guessed. That arc is the credibility, and it is recorded in full, with the
+figures quoted from their approved summaries, in [the track record](docs/track-record.md).
 
 ## Install
 
@@ -184,8 +183,8 @@ withheld and the scope is named as the reason.
 ### Checking that the agent did the work
 
 The work order tells an agent to fix exactly these findings and refactor nothing
-else. These flags check that the diff that came back obeyed it — read the
-diff's _shape_, not its correctness:
+else. These flags check that the diff obeyed it — they read its _shape_, not its
+correctness:
 
 ```bash
 maintainability-agent \
@@ -212,6 +211,11 @@ maintainability-agent \
   work order, and what moved. It is reproducible and **not signed** — nothing
   here holds a key, and the document says so in its own text. A check nobody ran
   renders as _not asked_, never as passed.
+- **`--transformation NAME`** names the class of work a scan followed and
+  reports how this run of it compares with earlier ones. **A report, never a
+  gate.** It says one run "moved further" than another, never that it was
+  _better_ — two runs of one codemod land on different code — and it measures
+  the interval, not the transformation.
 
 The [roadmap](docs/roadmap.md#the-remediation-hole-closed-in-210-through-230)
 has the history of why this was the hole under the product's central claim.

{maintainability_agent-2.5.0 → maintainability_agent-2.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "maintainability-agent"
-version = "2.5.0"
+version = "2.6.0"
 description = "Maintainability gate and AI remediation prompt generator for CI."
 readme = "README.md"
 # 3.11, not 3.10. `_discovery`, `_pillars` and `_runner` all import

{maintainability_agent-2.5.0 → maintainability_agent-2.6.0/src/maintainability_agent.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 2.5.0
+Version: 2.6.0
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -44,7 +44,7 @@ Dynamic: license-file
 **A deterministic, offline maintainability audit whose output is a _bounded
 work order_ for an AI coding agent** — a copy-paste prompt, per finding, that
 says *fix exactly these and refactor nothing else*. Chat-primary; CLI for CI.
-Version **2.5.0**.
+Version **2.6.0**.
 
 **Languages parsed:** Python, Java, C, C++, C#, Swift, Fortran (free-form
 *and* fixed-form), and the JS/TS family — each by a scanner written for it, and
@@ -152,9 +152,8 @@ registered verdict stands at **INCONCLUSIVE**. Method, limits and raw data:
 every claim the project could not stand behind was removed. A scoring engine
 rebuilt after it was found to grade repo *size*; a headline claim about AI
 authorship retracted against a matched control; a score that is withheld rather
-than guessed. That arc is the credibility, and it is recorded in full — with the
-figures quoted from their approved summaries — in
-[the track record](docs/track-record.md).
+than guessed. That arc is the credibility, and it is recorded in full, with the
+figures quoted from their approved summaries, in [the track record](docs/track-record.md).
 
 ## Install
 
@@ -223,8 +222,8 @@ withheld and the scope is named as the reason.
 ### Checking that the agent did the work
 
 The work order tells an agent to fix exactly these findings and refactor nothing
-else. These flags check that the diff that came back obeyed it — read the
-diff's _shape_, not its correctness:
+else. These flags check that the diff obeyed it — they read its _shape_, not its
+correctness:
 
 ```bash
 maintainability-agent \
@@ -251,6 +250,11 @@ maintainability-agent \
   work order, and what moved. It is reproducible and **not signed** — nothing
   here holds a key, and the document says so in its own text. A check nobody ran
   renders as _not asked_, never as passed.
+- **`--transformation NAME`** names the class of work a scan followed and
+  reports how this run of it compares with earlier ones. **A report, never a
+  gate.** It says one run "moved further" than another, never that it was
+  _better_ — two runs of one codemod land on different code — and it measures
+  the interval, not the transformation.
 
 The [roadmap](docs/roadmap.md#the-remediation-hole-closed-in-210-through-230)
 has the history of why this was the hole under the product's central claim.

{maintainability_agent-2.5.0 → maintainability_agent-2.6.0}/src/maintainability_agent.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ src/maintainability_audit/__init__.py
 src/maintainability_audit/__main__.py
 src/maintainability_audit/_adapters.py
 src/maintainability_audit/_analysis.py
+src/maintainability_audit/_arguments.py
 src/maintainability_audit/_aspects.py
 src/maintainability_audit/_attestation.py
 src/maintainability_audit/_backfill.py
@@ -67,6 +68,7 @@ src/maintainability_audit/_ranges_js.py
 src/maintainability_audit/_ranges_swift.py
 src/maintainability_audit/_ratchet.py
 src/maintainability_audit/_recurrence.py
+src/maintainability_audit/_run_comparison.py
 src/maintainability_audit/_runner.py
 src/maintainability_audit/_safe_write.py
 src/maintainability_audit/_scan_history.py
@@ -274,6 +276,7 @@ tests/test_report_remedy_copy.py
 tests/test_roles_recorded.py
 tests/test_root_grants.py
 tests/test_rubric_ignores_project_lint_config.py
+tests/test_run_comparison.py
 tests/test_runner.py
 tests/test_sarif.py
 tests/test_scan_history.py

{maintainability_agent-2.5.0 → maintainability_agent-2.6.0}/src/maintainability_audit/__init__.py

@@ -1,3 +1,3 @@
 """Maintainability Audit CI."""
 
-__version__ = "2.5.0"
+__version__ = "2.6.0"

maintainability_agent-2.6.0/src/maintainability_audit/_arguments.py

@@ -0,0 +1,186 @@
+"""What the command line accepts, separate from what the command does.
+
+Split out of `cli` when it crossed this project's own `max_file_lines`
+gate — the second time that gate has shaped this module, after
+`_add_gate_arguments` was split from `add_arguments` for the function
+budget. Both splits were forced by the tool on a change to the tool, which
+is the gate doing the job it exists for rather than an inconvenience.
+
+The boundary is deliberate and not merely a line count: everything here
+declares a flag and nothing here runs an audit. `cli` imports it, never
+the reverse.
+"""
+from __future__ import annotations
+
+import argparse
+
+from .config import VERSION
+
+
+def _add_gate_arguments(parser: argparse.ArgumentParser) -> None:
+    """What can make a run fail, and the conformance record behind one.
+
+    Split from `add_arguments` when the conformance flags took it past this
+    project's own function-length gate — which is the gate doing its job on
+    the change that added a gate.
+    """
+    parser.add_argument("--fail-on-gate", action="store_true", help="Exit 1 when hard gates fail.")
+    parser.add_argument(
+        "--conformance",
+        metavar="REVSPEC",
+        help="Report how a diff relates to the work order, e.g. `main...HEAD`. "
+             "The bounded work order says 'fix exactly these and refactor nothing "
+             "else'; without this the bound is an instruction nothing checks. "
+             "Reports only unless --fail-on-out-of-scope is passed.",
+    )
+    parser.add_argument(
+        "--fail-on-regression", action="store_true",
+        help="Exit 1 when any scoring category is lower than the previous "
+             "comparable scan. Reads the recorded history, and refuses to "
+             "compare across an instrument change rather than reporting a "
+             "false regression: two scans taken under different calibration "
+             "cannot be subtracted.",
+    )
+    parser.add_argument(
+        "--fail-on-out-of-scope", action="store_true",
+        help="With --conformance, exit 1 when the diff touched files the work "
+             "order did not name and that do not pair to one as its test, or "
+             "when it added a suppression to a file the work order flagged.",
+    )
+
+
+def _add_artifact_arguments(parser: argparse.ArgumentParser) -> None:
+    """The documents a run can write beside its report, and the run's label.
+
+    Split out for the same reason `_add_gate_arguments` was, and by the same
+    gate: `--transformation` took `add_arguments` past this project's own
+    function-length threshold, so the gate failed the change that added a
+    reporting flag. Grouped by what they produce rather than alphabetically
+    — every one of these is an artifact for somebody other than the person
+    running the command.
+    """
+    parser.add_argument("--prompt-output", help="Optional Markdown prompt for AI-assisted remediation.")
+    parser.add_argument("--comment-output", help="Optional Markdown body suitable for a PR comment.")
+    parser.add_argument("--agent-instructions-output", help="Optional reusable instructions for AI coding agents.")
+    parser.add_argument(
+        "--attestation-output",
+        help="Write the attestation: an independent, reproducible record of "
+             "what was measured, what the change was told to do, what it did, "
+             "and what moved. Populated by --conformance and "
+             "--fail-on-regression; a generator cannot produce this about its "
+             "own output.",
+    )
+    parser.add_argument(
+        "--transformation",
+        metavar="NAME",
+        help="Name the class of work this scan followed, e.g. `react-18`. "
+             "Records the name on the scan and reports how this run of it "
+             "compares with earlier ones. Nothing in a tree says which "
+             "transformation produced it, so this is your claim and the tool "
+             "records it without verifying it. A report, never a gate.",
+    )
+    parser.add_argument("--hostile-prompt-output",
+                        help="Optional adversarial audit brief seeded from this run (ADR 013). "
+                             "Text only: it does not gate, score, or send anything.")
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--version", action="version", version=f"maintainability-agent {VERSION}")
+    parser.add_argument("--root", default=".", help="Repository root to scan.")
+    parser.add_argument("--config", help="Path to JSON config.")
+    # Default None, not "markdown": the TTY question (8.4) only fires
+    # when the user stated nothing, and argparse cannot distinguish a
+    # stated default from an omitted flag.
+    parser.add_argument("--format", choices=["json", "markdown", "html"], default=None)
+    parser.add_argument("--html-output", help="Write the single-file HTML report here (ADR 011).")
+    parser.add_argument("--output", help="Output file. Defaults to stdout.")
+    _add_artifact_arguments(parser)
+    parser.add_argument("--sarif-output", help="Optional SARIF output path for GitHub code scanning.")
+    parser.add_argument("--sarif-input", action="append", help="Optional external SARIF file to summarize in reports. Repeatable.")
+    parser.add_argument("--changed-only", help="Audit only files changed in a git revspec, for example main...HEAD.")
+    parser.add_argument("--baseline", help="Existing baseline JSON. With --fail-on-new, only new findings fail.")
+    parser.add_argument("--write-baseline", help="Write current findings to a baseline JSON file.")
+    parser.add_argument("--fail-on-new", action="store_true", help="Fail only when findings are not in --baseline.")
+    parser.add_argument(
+        "--analyzers", action="store_true",
+        help="Force the external analyzer pool on for this run. The pool is "
+             "the primary evidence source (ADR 006, docs/analyzer-pool.md); a "
+             "repository with a config file runs it by default, so this flag "
+             "matters only for unconfigured trees or to override "
+             "analyzers.run=false. Measurements move the point estimate where "
+             "the full concept set was measured; otherwise the built-in "
+             "fallback stands and the range widens around the two.",
+    )
+    parser.add_argument(
+        "--no-analyzers", action="store_true",
+        help="Force the analyzer pool off for this run, overriding the "
+             "config. The report will say the built-in fallback supplied the "
+             "evidence (P8); it is a faster scan, not the full audit.",
+    )
+    parser.add_argument(
+        "--work", action="append", metavar="AXIS=VALUE",
+        help="Narrow the work order, for example --work band=quick-win or "
+             "--work path=src/. Repeatable; every criterion must match. "
+             "Axes: band, finding_class, path, verification. Narrowing "
+             "changes what is shown and never what anything scored.",
+    )
+    parser.add_argument(
+        "--record-history", action="store_true",
+        help="Append this scan to the history at paths.history (default "
+             ".maintainability/history.jsonl). Opt-in, like every other write "
+             "this tool performs. Once the file exists, every later successful "
+             "scan appends to it and reads the resulting history.",
+    )
+    parser.add_argument(
+        "--backfill", metavar="REVSPEC",
+        help="Scan each commit in a range into the history and exit, for "
+             "example --backfill HEAD~50..HEAD. Each commit is checked out in "
+             "a temporary worktree, so the working tree is never touched. "
+             "Expensive and therefore explicit: it never runs as part of a "
+             "normal scan. Records are marked as reconstructed.",
+    )
+    parser.add_argument(
+        "--backfill-interval", type=int, default=1, metavar="N",
+        help="With --backfill, scan every Nth commit instead of all of them. "
+             "The shape of a series is what a trend reads, and a thousand "
+             "commits is hours of work nobody asked for.",
+    )
+    _add_gate_arguments(parser)
+    _add_setup_actions(parser)
+
+
+def _add_setup_actions(parser: argparse.ArgumentParser) -> None:
+    """Flags that perform a setup action and exit instead of auditing."""
+    parser.add_argument("--init-agent-standards", action="store_true", help="Write model/tool-specific instruction files and exit.")
+    parser.add_argument(
+        "--install-skill", action="store_true",
+        help="Copy the packaged agent skill into the skills directory and "
+             "exit. Re-run after every upgrade: an installed skill that "
+             "drifts from the shipped one teaches agents a dead workflow.",
+    )
+    parser.add_argument(
+        "--skills-dir", default=None, metavar="DIR",
+        help="Where --install-skill writes (default: ~/.claude/skills).",
+    )
+    parser.add_argument(
+        "--force-skill", action="store_true",
+        help="With --install-skill: overwrite a differing installed copy "
+             "and remove files the package no longer ships. Without it, a "
+             "differing copy is refused with the list of differences.",
+    )
+    parser.add_argument(
+        "--target-path",
+        action="append",
+        metavar="TARGET=PATH",
+        help="Where a target's standing instructions go, e.g. "
+             "`--target-path bob=.bob/instructions.md`. Required for any agent "
+             "this tool has no built-in convention for; overrides the built-in "
+             "path for one it does. The target list will always trail the "
+             "market, and guessing a path writes a file the agent never opens.",
+    )
+    parser.add_argument(
+        "--target",
+        action="append",
+        help="Instruction target. Repeatable. Used with --init-agent-standards.",
+    )
+    parser.add_argument("--instructions-output-dir", default=".", help="Directory for generated instruction files.")

{maintainability_agent-2.5.0 → maintainability_agent-2.6.0}/src/maintainability_audit/_gates.py

@@ -51,18 +51,42 @@ def attach_ratchet(report: dict, history_path: Path) -> None:
     report["dimension_ratchet"] = dimension_ratchet(read_history(history_path))
 
 
+def attach_run_comparison(
+    args: argparse.Namespace, report: dict, history_path: Path
+) -> None:
+    """Compare this run of a named transformation with earlier ones.
+
+    Only when the operator named one: an unnamed run belongs to no series,
+    and inventing a series for it would be the tool answering a question
+    nobody asked.
+    """
+    label = getattr(args, "transformation", None)
+    if not label or not history_path.exists():
+        return
+    from ._run_comparison import compare_runs
+    from ._scan_history import read_history
+
+    report["run_comparison"] = compare_runs(read_history(history_path), label)
+
+
 def _attach_post_audit_records(
     args: argparse.Namespace, report: dict, history_path: Path
 ) -> None:
     """Records composed from the finished report, before it is rendered.
 
-    Both read the report rather than the tree, and neither reaches scoring:
-    whether a diff obeyed its work order, and whether a dimension slipped
-    since the last comparable scan, are facts about a change and its
-    history — not evidence about the code's condition.
+    All three read the report or the history rather than the tree, and none
+    reaches scoring: whether a diff obeyed its work order, whether a
+    dimension slipped since the last comparable scan, and how this run of a
+    transformation compares with earlier ones are facts about a change and
+    its history — not evidence about the code's condition.
+
+    The third is the only one that cannot fail a build. It is a report, by
+    design: "run seven moved further than run six" is worth knowing and is
+    not a thing to block a merge on.
     """
     attach_conformance(args, report)
     attach_ratchet(report, history_path)
+    attach_run_comparison(args, report, history_path)
 
 
 def _conformance_exit(args: argparse.Namespace, report: dict) -> int:

{maintainability_agent-2.5.0 → maintainability_agent-2.6.0}/src/maintainability_audit/_history_view.py

@@ -120,3 +120,49 @@ def escalations_markdown(escalated: list[dict[str, Any]] | None) -> list[str]:
         ])
     lines.append("")
     return lines
+
+
+def run_comparison_markdown(comparison: dict[str, Any] | None) -> list[str]:
+    """The markdown section. Presentation only — it computes no score.
+
+    Empty for a run nobody named, which is most of them.
+    """
+    if not comparison:
+        return []
+    label = comparison["label"]
+    lines = [f"## Runs of `{label}`", ""]
+    runs = comparison["runs"]
+    if not runs:
+        return [*lines, comparison["trend"].get("reason", "No runs recorded."), ""]
+
+    lines += ["| Recorded | Commit | Estimate | Moved | Files | Declarations |",
+              "|---|---|---|---|---|---|"]
+    for run in runs:
+        estimate = "withheld" if run["estimate"] is None else f"{run['estimate']:.2f}"
+        moved = "—" if run["moved"] is None else f"{run['moved']:+.2f}"
+        populations = run["populations"]
+        lines.append(
+            f"| {run['recorded_at']} | `{(run['commit'] or '')[:8]}` | {estimate} | "
+            f"{moved} | {populations.get('files_scanned', '—')} | "
+            f"{populations.get('declarations_scanned', '—')} |"
+        )
+    lines.append("")
+
+    trend = comparison["trend"]
+    lines.append(
+        f"**{trend['summary']}.**" if trend.get("comparable")
+        else f"**Not established:** {trend['reason']}."
+    )
+    if comparison.get("excluded_earlier_runs"):
+        lines += ["", (
+            f"{comparison['excluded_earlier_runs']} earlier run(s) under this "
+            f"name are excluded: {comparison['exclusion_reason']}."
+        )]
+    lines += ["", (
+        "*`Moved` is the change in estimate between the previous recorded "
+        "scan and this one — the movement across that interval, not the "
+        "effect of the transformation. Anything else that happened in the "
+        "same interval is inside the number, and two runs of one "
+        "transformation land on different code.*"
+    ), ""]
+    return lines

maintainability_agent-2.6.0/src/maintainability_audit/_run_comparison.py

@@ -0,0 +1,184 @@
+"""Did run seven of this transformation land better than run six?
+
+The last of the remediation-integrity items, and the only one that is a
+**report rather than a gate**. Where an agent performs one class of work
+repeatedly — a framework upgrade, a migration, a codemod applied across
+services — nobody measures whether the seventh run produced better code
+than the sixth. The generator cannot answer it: its output is not
+reproducible and it keeps no memory across runs. This tool has pinned
+references, structured finding identity and scan history, so the
+comparison is a join, not new machinery.
+
+**What names a run.** Nothing in a tree says "this scan followed the React
+18 upgrade", so the operator says it: `--transformation react-18`. The
+label rides on the scan record and groups runs into a series.
+
+**What it measures, stated precisely because the temptation is to
+overstate it.** For each labeled run, the movement between the *previous
+scan in history* and that run. That is the movement across an interval,
+and the transformation is what the operator says happened during that
+interval. This module does not and cannot verify that claim: anything else
+that happened in the same interval is inside the number. So the report
+speaks of a run's *movement*, never of its *effect*, and never says one
+run was "better" — it says one moved further than another, which is what
+was actually measured.
+
+**It refuses across an instrument change**, reusing `segments` exactly as
+`_ratchet` does. Two scans taken under different calibration cannot be
+subtracted, and a series that quietly spanned the 2.0 corpus extension
+would have reported every transformation on earth as catastrophic. When
+the newest labeled run sits in a different segment from its predecessors,
+the earlier runs are named as excluded rather than dropped in silence:
+a reader who cannot see the refusal will assume there was no history.
+
+Nothing here reaches scoring, and nothing here fails a build.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from ._scan_history import ScanRecord, segments
+
+#: The same rounding boundary `_ratchet` uses, and for the same reason:
+#: estimates are published to one decimal, so a smaller difference is the
+#: rounding and not a movement.
+TOLERANCE = 0.05
+
+
+def _movement(previous: ScanRecord | None, current: ScanRecord) -> float | None:
+    """How far the estimate moved across the interval ending at `current`.
+
+    `None` where either end is missing an estimate. A withheld estimate is
+    not a zero — P7 withholds it precisely because the evidence did not
+    support a number, and subtracting from it would manufacture one.
+    """
+    if previous is None or previous.estimate is None or current.estimate is None:
+        return None
+    return round(current.estimate - previous.estimate, 3)
+
+
+def _run_entry(
+    record: ScanRecord, previous: ScanRecord | None
+) -> dict[str, Any]:
+    return {
+        "recorded_at": record.recorded_at,
+        "commit": record.commit,
+        "scope": record.scope,
+        "estimate": record.estimate,
+        "evidence_status": record.evidence_status,
+        # Named so a reader can tell a movement in the code from a movement
+        # in what was measured: a run that doubled the tree is a different
+        # event from one that changed the same tree's condition.
+        "populations": dict(record.populations),
+        "moved": _movement(previous, record),
+        # A reconstructed scan carries today's tooling against an old
+        # commit, which is not the scan that would have happened then.
+        "backfilled": record.backfilled,
+    }
+
+
+def _direction(difference: float) -> str:
+    """How to say it. Never "better" — see `_trend`."""
+    if abs(difference) < TOLERANCE:
+        return "within tolerance of"
+    return "further than" if difference > 0 else "less than"
+
+
+def _trend(runs: list[dict[str, Any]]) -> dict[str, Any]:
+    """How the newest run's movement compares with the one before it.
+
+    Deliberately not called "better". Two runs of one codemod land on
+    different code, so a larger movement can come from the tree it was
+    applied to as easily as from the run. "Moved further" is what the
+    numbers support; "better" is a judgment about work this tool never saw.
+    """
+    movements = [run for run in runs if run["moved"] is not None]
+    if len(movements) < 2:
+        return {
+            "comparable": False,
+            "reason": (
+                "fewer than two runs in this series carry a movement, so "
+                "there is nothing to compare them on"
+            ),
+        }
+    latest, prior = movements[-1]["moved"], movements[-2]["moved"]
+    difference = round(latest - prior, 3)
+    direction = _direction(difference)
+    return {
+        "comparable": True,
+        "latest_moved": latest,
+        "previous_moved": prior,
+        "difference": difference,
+        "summary": (
+            f"the newest run moved {latest:+.2f}, {direction} the "
+            f"{prior:+.2f} of the run before it"
+        ),
+    }
+
+
+def _segment_holding(records: list[ScanRecord], wanted: ScanRecord) -> Any:
+    """The instrument-segment containing one record.
+
+    Membership is by **identity**, not equality: two scans of an unchanged
+    tree differ only in their timestamp, and an equality test would find
+    the wrong one — silently attributing a run to the wrong instrument.
+    """
+    return next(
+        segment for segment in segments(records)
+        if any(item is wanted for item in segment.records)
+    )
+
+
+def _entries_within(segment: Any, labelled: list[ScanRecord]) -> list[dict[str, Any]]:
+    """The labelled runs inside this segment, each with its predecessor.
+
+    A run's predecessor is the scan immediately before it *in the
+    segment*, whatever that scan was labelled — the movement being
+    measured is across the interval, not between two runs of the same
+    name.
+    """
+    order = {id(record): index for index, record in enumerate(segment.records)}
+    return [
+        _run_entry(
+            record,
+            segment.records[order[id(record)] - 1] if order[id(record)] else None,
+        )
+        for record in labelled if id(record) in order
+    ]
+
+
+def compare_runs(records: list[ScanRecord], label: str) -> dict[str, Any]:
+    """Every recorded run of one transformation, and how the last two differ.
+
+    The current scan is already in `records` when this is called — history
+    is appended before the post-audit records are attached — so the newest
+    labeled run is this one.
+    """
+    labelled = [record for record in records if record.transformation == label]
+    if not labelled:
+        return {
+            "label": label,
+            "runs": [],
+            "excluded_earlier_runs": 0,
+            "trend": {
+                "comparable": False,
+                "reason": f"no scan has been recorded under the name {label!r}",
+            },
+        }
+
+    current = _segment_holding(records, labelled[-1])
+    runs = _entries_within(current, labelled)
+    excluded = len(labelled) - len(runs)
+
+    comparison = {
+        "label": label,
+        "runs": runs,
+        "excluded_earlier_runs": excluded,
+        "trend": _trend(runs),
+    }
+    if excluded:
+        comparison["exclusion_reason"] = (
+            current.break_reason
+            or "those runs were produced by a different instrument"
+        )
+    return comparison