advisory-scan: attribute vendor-changelog CVEs to the release that fixed them

nginx publishes NO GitHub security advisories. Every nginx CVE we can see comes
from nginx.org/en/CHANGES, and the scan scraped ids out of it without attributing
them to a release - so they had no patched version, could never be classified, and
every nginx bump in the fleet reported 0 CVEs. nginx is a sidecar in most recipes,
so this was a fleet-wide blind spot.

Measured on the two PRs that prompted the question:
  lasuite-docs#7  nginx 1.31.1 -> 1.31.3   0 -> 6 CVEs
  lasuite-drive#6 nginx 1.31.2 -> 1.31.3   0 -> 3 CVEs
matching a hand count of the changelog exactly (three fixed in 1.31.2, three in
1.31.3; the narrower window correctly counts only the latter).

How: when a vendor page is organised by release, each CVE is attributed to the
nearest preceding release heading ('Changes with nginx 1.31.3', '## v1.31.3'),
and that becomes its fixed-in version. The CVE is tied to a window by the image
name appearing in the page URL (window 'nginx' <-> nginx.org/...). A changelog
lists the project's whole history, so only releases the window actually crosses
count - asserted by a test that the 2013 entries stay out.

76 tests. discourse 140 / gitea 2 / mailu 2 / keycloak 12 unchanged.

AGENTS.md

@@ -115,3 +115,29 @@ When the orchestrator, Builder, or assistant makes intentional repository change
 promptly and push them to `git.autonomic.zone` in append-only fashion (never force-push). Match the
 existing commit author and message style in this repo. Do not bundle unrelated worktree changes you
 did not make; stage only the intended files.
+
+## Ship as PRs, merge them yourself, operator reviews retrospectively
+
+**This applies to the two INFRASTRUCTURE repos — `recipe-maintainers/cc-ci-orchestrator` (here) and
+`recipe-maintainers/cc-ci` (the CI product).** For work in either:
+
+1. Branch, don't commit straight to `main`.
+2. Open a PR with a description written to be read **after** the fact: what changed, why, and what
+   evidence says it works (test output, a verified run, a before/after number). The PR *is* the
+   review artifact and the historical record.
+3. **Merge it yourself once it is verified** — do not wait for review. The invocation is the
+   authorization; blocking on review would stall the pipeline these repos exist to run.
+4. The operator reviews **retrospectively**, from the PR.
+
+So the PR is not a gate — it is how the work stays legible. A PR that merely says "fix scanner" has
+failed at its only job.
+
+> ### This does NOT extend to RECIPE repos
+> Recipe PRs — any `coop-cloud/<recipe>` or its `recipe-maintainers/<recipe>` mirror — are
+> **created and verified but NEVER merged by an agent**. Those change what deploys on other people's
+> infrastructure, so a human merges them. The split is deliberate: agents own the tooling, the
+> operator owns the recipes.
+
+If work has already landed on `main` without a PR, do not rewrite published history to fix it.
+Create a branch pinned at the pre-work commit and open the PR against that, so the diff is still
+reviewable and merging only advances the pointer (see PRs #2-#5, 2026-08-11).

cc-ci-plan/advisory-scan.SPEC.md

@@ -39,6 +39,8 @@ keeps landing in pass 2, the fix is a new deterministic method in pass 1. §4c i
 ```
 advisory-scan.py <recipe> [--from <version>] [--to <version>]
                           [--image <name>=<from>:<to>]... [--adjudicate] [--json] [--registry DIR]
+
+advisory-scan.py <recipe> --compose-to <URL> [--compose-from <URL>]   # windows derived, not typed
 ```
 
 | Input | Meaning |
@@ -46,6 +48,8 @@ advisory-scan.py <recipe> [--from <version>] [--to <version>]
 | `<recipe>` | Recipe name; selects `cc-ci-plan/upstream/<recipe>.md` (the per-recipe URL registry) |
 | `--from` / `--to` | The **primary app image's** version window being upgraded across |
 | `--image NAME=FROM:TO` | A **sidecar image and the versions it moved between** (repeatable, all in ONE call). `NAME` is substring-matched against source repo names. Malformed values warn on stderr and are skipped. Without it that image's advisories stay unclassified. |
+| `--compose-to URL` | **Derive every window by diffing this compose against its baseline**, instead of typing `--from/--to/--image`. Point it at a PR's `compose.yml`. |
+| `--compose-from URL` | Baseline for the above. Default: the same repo's **default branch, resolved from the API** — never assumed to be `main`. |
 | `--adjudicate` | Run pass 2: append the evidence dossier for judgement |
 | `--registry` | Registry dir; also `CCCI_UPSTREAM_REGISTRY` |
 | `GITHUB_TOKEN` / `GITHUB_TOKEN_FILE` | Read-only token; **rate limit only** (60/hr anonymous → 5000/hr). Default file `/srv/cc-ci/.github-token`, mode 600. Public advisories need **no scopes**. |
@@ -103,8 +107,21 @@ URLs containing `<`, `>`, `{`, `}`, `VERSION`, or `vX.Y.Z` are **skipped as temp
 human documentation (`…/changelog/v<VERSION>/`), not fetchable, and counting them as failures is wrong.
 
 This is the source that would have caught gitea: the vendor blog names both CVEs, the GitHub release
-page names neither. A CVE found **only** here carries no version data, so pass 1 cannot place it — it
-goes to pass 2 (§6).
+page names neither.
+
+**When the page is a changelog organised by release, each CVE is attributed to the release heading it
+appears under** (`Changes with nginx 1.31.3`, `## v1.31.3`, …) and that becomes its fixed-in version.
+Without this, a project that publishes no advisory feed can never contribute a CVE:
+
+> **nginx publishes NO GitHub security advisories.** Every nginx CVE we can see comes from
+> `nginx.org/en/CHANGES`. Scraping ids out of it without attributing them to a release left them with
+> no patched version, so they were never classifiable — and every nginx bump in the fleet reported
+> **0** forever. nginx is a sidecar in most recipes. Measured: `1.31.1 → 1.31.3` fixes **six** CVEs
+> (three in .2, three in .3); lasuite-docs#7 went 0 → 6 and lasuite-drive#6 went 0 → 3 on this alone.
+
+A changelog CVE is tied to a window by the **image name appearing in the page URL** (window `nginx` ↔
+`nginx.org/...`). A CVE found on a vendor page with no attributable release still has no version data,
+so pass 1 cannot place it — it goes to pass 2 (§6).
 
 ### 2c. OSV.dev — supplementary
 
@@ -140,6 +157,33 @@ Two invariants govern this step, both learned from a wrong answer in production.
 > `null` / `UNKNOWN`, never `0`. A `0` in a security column asserts safety. Equally, an advisory that
 > cannot be judged is **indeterminate** (§4d) — never silently counted as "not fixed".
 
+### 3b. Deriving the windows from a compose diff (`--compose-to`)
+
+Typing `--from/--to/--image` by hand means someone has to remember that the recipe also bumped its
+redis. That is how sidecar CVEs went uncounted for months. This mode reads the windows off the diff:
+
+1. Fetch both compose files (baseline = the repo's **default branch from the API**, since several
+   recipes keep a stale `main` beside a live `master`).
+2. Parse `{service: (image-repo, tag)}` — keyed by **service, not image repo**, because an upgrade
+   may change the repo itself (plausible moved `plausible/analytics` →
+   `ghcr.io/plausible/community-edition`; keyed by repo that reads as one image vanishing and an
+   unrelated one appearing, losing the app window entirely).
+3. Every service whose tag or repo changed becomes a window. The `app` service drives `--from/--to`
+   (coop-cloud convention: it is the recipe's primary image); the rest become `--image` windows.
+   Unchanged images produce no window — inventing one would be a false count.
+4. The derived windows are printed to stderr before the scan, so the inputs are auditable.
+
+Image names are matched against advisory sources **both ways** — an image name is often longer than
+its source repo (`clickhouse/clickhouse-server` vs `ClickHouse/ClickHouse`) and sometimes shorter
+(`redis` vs `redis/redis`).
+
+Verified on plausible PR #5: from the compose URL alone it derives `v2.0.0 → v3.2.1` plus
+`clickhouse-server 23.4.2.11-alpine → 24.12-alpine`, and reports **6** — identical to the
+hand-specified args.
+
+`--from/--to/--image` remain available for finer-grained checks (scanning a window that is not a
+literal compose diff, e.g. "what would the compatibility-safe target fix?").
+
 ### 4a. By patched version (preferred — exact)
 
 `patched_versions` is a **range expression** (`">= 2.18.1"`), possibly several joined by `;`. Extract

cc-ci-plan/advisory-scan.py

@@ -272,6 +272,37 @@ def github_advisories(urls: list[str]) -> list[dict]:
     return results
 
 
+# Release headings in a vendor changelog. nginx's CHANGES uses "Changes with nginx 1.31.3", most
+# markdown changelogs use "## 1.31.3" / "## v1.31.3".
+_HEADING_RE = re.compile(
+    r"^\s*(?:#{1,4}\s*)?(?:Changes with\s+\S+\s+|Version\s+|Release\s+)?v?(\d+\.\d+(?:\.\d+)*)\s*$"
+    r"|^\s*Changes with\s+\S+\s+(\d+\.\d+(?:\.\d+)*)", re.I)
+
+
+def _changelog_versions(text: str) -> dict:
+    """{cve: version} for a changelog that is ORGANISED BY RELEASE.
+
+    Why this exists: nginx publishes NO GitHub security advisories. Every nginx CVE we can see comes
+    from nginx.org/en/CHANGES, and scraping ids out of it without attributing them to a release
+    leaves them with no patched version — so they can never be classified, and an nginx bump reports
+    0 CVEs forever. nginx 1.31.1 -> 1.31.3 in fact fixes SIX (three in .2, three in .3), and nginx is
+    a sidecar in most of the fleet, so that was a fleet-wide blind spot.
+
+    Attributes each CVE to the nearest PRECEDING release heading — the release that fixed it.
+    """
+    plain = re.sub(r"<[^>]+>", " ", text)
+    out, cur = {}, None
+    for line in plain.splitlines():
+        m = _HEADING_RE.match(line)
+        if m:
+            cur = m.group(1) or m.group(2)
+            continue
+        if cur:
+            for cve in CVE_RE.findall(line):
+                out.setdefault(cve, cur)
+    return out
+
+
 def vendor_pages(urls: list[str]) -> list[dict]:
     """Fetch each registry URL and regex out CVE ids, with a little surrounding context."""
     out = []
@@ -284,7 +315,7 @@ def vendor_pages(urls: list[str]) -> list[dict]:
             # correct; counting them as failures would wrongly mark the recipe's count unreliable.
             out.append({"source": u, "status": "skipped: template URL (not fetchable)", "cves": [], "context": {}})
             continue
-        entry = {"source": u, "status": "ok", "cves": [], "context": {}}
+        entry = {"source": u, "status": "ok", "cves": [], "context": {}, "fixed_in": {}}
         try:
             text = _fetch(u)
             plain = re.sub(r"<[^>]+>", " ", text)
@@ -292,6 +323,7 @@ def vendor_pages(urls: list[str]) -> list[dict]:
                 entry["cves"].append(cve)
                 i = plain.find(cve)
                 entry["context"][cve] = re.sub(r"\s+", " ", plain[max(0, i - 160) : i + 200]).strip()
+            entry["fixed_in"] = _changelog_versions(text)
         except Exception as e:  # noqa: BLE001
             entry["status"] = f"error: {type(e).__name__}: {e}"
         out.append(entry)
@@ -595,7 +627,8 @@ def scan(recipe: str, v_from: str | None, v_to: str | None, registry_dir: str,
         e = report["cves"].setdefault(cve, {"sources": [], "severity": None, "ghsa": None,
                                             "vulnerable_range": None, "patched": None,
                                             "context": None, "published_at": None,
-                                            "description": None, "url": None, "cvss": None})
+                                            "description": None, "url": None, "cvss": None,
+                                            "changelog_fixed_in": None})
         if src not in e["sources"]:
             e["sources"].append(src)
         for k, v in extra.items():
@@ -616,7 +649,8 @@ def scan(recipe: str, v_from: str | None, v_to: str | None, registry_dir: str,
         report["sources"].append({"source": entry["source"], "status": entry["status"],
                                   "found": len(entry.get("cves", []))})
         for cve in entry.get("cves", []):
-            record(cve, entry["source"], context=entry["context"].get(cve))
+            record(cve, entry["source"], context=entry["context"].get(cve),
+                   changelog_fixed_in=(entry.get("fixed_in") or {}).get(cve))
 
     for version in filter(None, (v_from, v_to)):
         o = osv(recipe, version)
@@ -656,12 +690,22 @@ def scan(recipe: str, v_from: str | None, v_to: str | None, registry_dir: str,
     report["primary_source"] = primary
 
     windows = {}                                    # source name -> (from, to)
+    window_key = {}                                 # source name -> the image name it covers
     if primary:
         windows[primary] = (v_from, v_to)
+        window_key[primary] = primary.split("/")[-1]
     for key, wf, wt in (images or []):
         for src in gh_sources:
-            if key.lower() in src.lower() and src not in windows:
+            if src in windows:
+                continue
+            # Match BOTH ways: an image name is often longer than its source repo
+            # (`clickhouse/clickhouse-server` vs source `ClickHouse/ClickHouse`) and sometimes
+            # shorter (`redis` vs `redis/redis`). One-directional matching silently dropped the
+            # clickhouse window when the key was derived from a compose file.
+            k, name = key.lower(), src.split("/")[-1].lower()
+            if k in src.lower() or name in k:
                 windows[src] = (wf, wt)
+                window_key[src] = key
     report["windows"] = {k: {"from": f, "to": t} for k, (f, t) in windows.items()}
 
     def _classify_window(src, wf, wt):
@@ -719,6 +763,32 @@ def scan(recipe: str, v_from: str | None, v_to: str | None, registry_dir: str,
             report["cves"][cve]["classification"] = f"fixed-by-this-upgrade ({method}) via {src}"
             fixed_set.add(cve)
 
+    # A CVE seen only in a vendor CHANGELOG has no advisory feed behind it, but the changelog says
+    # which release fixed it (see _changelog_versions). Tie it to a window by the image name
+    # appearing in the page URL — nginx's window is `nginx`, and its changelog is nginx.org/... .
+    # Without this, projects that publish no GitHub advisories (nginx being the big one) can never
+    # contribute a CVE, and every nginx bump in the fleet silently reports 0.
+    from_changelog = {}
+    for cve, e in report["cves"].items():
+        if cve in fixed_set or not e.get("changelog_fixed_in"):
+            continue
+        for src, (wf, wt) in windows.items():
+            key = (window_key.get(src) or "").lower()
+            if not key:
+                continue
+            if not any(key in s_.lower() for s_ in e["sources"] if s_.startswith("http")):
+                continue
+            kf, kt = _vkey(wf), _vkey(wt)
+            cand = _vkey(e["changelog_fixed_in"])
+            if kf and kt and cand and _within(kf, kt, cand):
+                e["classification"] = (f"fixed-by-this-upgrade (named under {e['changelog_fixed_in']} "
+                                       f"in the vendor changelog) via {src}")
+                fixed_set.add(cve)
+                from_changelog[cve] = e["changelog_fixed_in"]
+            break
+    if from_changelog:
+        report["resolved_by_changelog"] = from_changelog
+
     unknown = []
     for cve, e in report["cves"].items():
         if cve in fixed_set:
@@ -893,6 +963,113 @@ def markdown(rep: dict) -> str:
     return "\n".join(L)
 
 
+def _gitea_auth(url: str) -> dict:
+    """Basic auth for the private mirror, from /srv/cc-ci/.testenv.
+
+    Sent as a HEADER, never embedded in the URL: in-URL credentials leak into shell history, process
+    lists and error messages, and urllib mis-parses a password containing a colon."""
+    host = re.sub(r"^https?://", "", url).split("/")[0]
+    env = {}
+    try:
+        for ln in open(os.environ.get("CCCI_TESTENV", "/srv/cc-ci/.testenv")):
+            if "=" in ln and not ln.strip().startswith("#"):
+                k, v = ln.strip().split("=", 1)
+                env[k] = v.strip().strip("\"'")
+    except OSError:
+        return {}
+    if host != env.get("GITEA_URL", "git.autonomic.zone"):
+        return {}
+    u, pw = env.get("GITEA_USERNAME"), env.get("GITEA_PASSWORD")
+    if not (u and pw):
+        return {}
+    import base64 as _b64
+    return {"Authorization": "Basic " + _b64.b64encode(f"{u}:{pw}".encode()).decode()}
+
+
+def _compose_images(url: str) -> dict[str, tuple[str, str]]:
+    """{service: (image-repo, tag)} for a compose file.
+
+    Keyed by SERVICE, not by image repo, because an upgrade may change the repo itself: plausible
+    moved `plausible/analytics` -> `ghcr.io/plausible/community-edition`. Keyed by repo that reads
+    as one image vanishing and an unrelated one appearing, and the app's version window is lost —
+    which is exactly the upgrade most worth scanning."""
+    txt = _fetch(url, _gitea_auth(url))
+    out, svc = {}, None
+    in_services = False
+    for line in txt.splitlines():
+        if re.match(r"^services:\s*$", line):
+            in_services = True
+            continue
+        if in_services and re.match(r"^\S", line):
+            in_services = False
+        if not in_services:
+            continue
+        m = re.match(r"^  (\S+):\s*$", line)
+        if m:
+            svc = m.group(1)
+            continue
+        m = re.match(r"^\s+image:\s*[\"']?([^\"'\s]+)", line)
+        if m and svc:
+            ref = m.group(1).split("@", 1)[0]
+            if "${" in ref or "$(" in ref:
+                continue
+            repo, _, tag = ref.rpartition(":")
+            if repo and tag:
+                out[svc] = (repo, tag)
+    return out
+
+
+def _default_branch_compose(url: str) -> str | None:
+    """Same repo as `url`, but its DEFAULT branch — resolved from the API, never assumed.
+
+    Several coopcloud recipes keep a stale `main` beside the real default `master` (gitea's `main`
+    is 1.24.2-rootless while `master` has 1.27.1-rootless), so guessing the branch produces a
+    confidently wrong baseline."""
+    m = re.match(r"(https?://[^/]+)/([^/]+)/([^/]+)/(?:raw|src)/branch/[^/]+/(.*)$", url)
+    if not m:
+        return None
+    host, owner, repo, path = m.groups()
+    try:
+        meta = json.loads(_fetch(f"{host}/api/v1/repos/{owner}/{repo}", _gitea_auth(host)))
+        br = meta.get("default_branch")
+    except Exception:  # noqa: BLE001
+        return None
+    return f"{host}/{owner}/{repo}/raw/branch/{br}/{path}" if br else None
+
+
+def windows_from_compose(to_url: str, from_url: str | None = None) -> tuple[list, str | None]:
+    """Derive the scan's version windows by DIFFING two compose files.
+
+    This is the deterministic alternative to a human (or a model) deciding which `--image` args a
+    given upgrade needs. Point it at a PR's compose and it reads the windows straight off the diff:
+    every image whose tag changed becomes a window, every image that did not change is correctly
+    left out, and nothing depends on anyone remembering that the recipe also bumped its redis.
+
+    Returns (windows, note) where windows is [(image-name, from, to)].
+    """
+    if from_url is None:
+        from_url = _default_branch_compose(to_url)
+        if not from_url:
+            raise SystemExit("could not resolve a baseline compose; pass --compose-from explicitly")
+    new, old = _compose_images(to_url), _compose_images(from_url)
+    app, others = None, []
+    for svc, (repo, tag) in sorted(new.items()):
+        if svc not in old:
+            continue
+        prev_repo, prev_tag = old[svc]
+        if prev_tag == tag and prev_repo == repo:
+            continue
+        # The `app` service is the recipe's primary image by coop-cloud convention; its window drives
+        # --from/--to so the scan's primary advisory source is judged against it. Everything else is
+        # a sidecar window keyed by its image name.
+        if svc == "app":
+            app = (repo.split("/")[-1], prev_tag, tag)
+        else:
+            others.append((repo.split("/")[-1], prev_tag, tag))
+    wins = ([app] if app else []) + others
+    return wins, f"baseline {from_url}"
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("recipe")
@@ -904,6 +1081,13 @@ def main() -> int:
                          "fix version published), fetch their full text + references and append a "
                          "block for the agent to judge. Additive: it never changes the count above.")
     ap.add_argument("--registry", default=REGISTRY_DIR)
+    ap.add_argument("--compose-to", default=None, metavar="URL",
+                    help="derive the windows by DIFFING this compose against its baseline, instead "
+                         "of passing --from/--to/--image by hand. Point it at a PR's compose.yml "
+                         "(e.g. .../raw/branch/<pr-branch>/compose.yml).")
+    ap.add_argument("--compose-from", default=None, metavar="URL",
+                    help="baseline compose for --compose-to. Default: the same repo's DEFAULT "
+                         "branch, resolved from the API (never assumed to be `main`).")
     ap.add_argument("--image", action="append", default=[], metavar="NAME=FROM:TO",
                     help="a sidecar image and the versions it moved between, e.g. "
                          "--image redis=7.4:8.10 (repeatable). NAME matches a source repo name; "
@@ -911,6 +1095,20 @@ def main() -> int:
                          "being left unclassified.")
     a = ap.parse_args()
     images = []
+    if a.compose_to:
+        wins, note = windows_from_compose(a.compose_to, a.compose_from)
+        if not wins:
+            print(f"### Advisory scan — {a.recipe}\n\n**No image versions changed between the two "
+                  f"compose files, so this upgrade fixes no CVEs by definition.**\n\n_{note}_")
+            return 0
+        print(f"_derived from compose diff ({note}):_", file=sys.stderr)
+        for n_, f_, t_ in wins:
+            print(f"_  {n_}: {f_} → {t_}_", file=sys.stderr)
+        # The `app` service (first entry when present) drives --from/--to; the rest are --image
+        # windows. Passing every window as --image too is harmless: each is matched by name against
+        # the advisory sources, and an unmatched name is simply ignored.
+        a.v_from, a.v_to = a.v_from or wins[0][1], a.v_to or wins[0][2]
+        images = list(wins[1:])
     for spec in a.image:
         name, _, rng = spec.partition('=')
         vf, _, vt = rng.partition(':')

cc-ci-plan/test-advisory-scan.py

@@ -537,6 +537,133 @@ class TestReleaseLineSemantics(unittest.TestCase):
         self.assertEqual(rep["fixed_by_this_upgrade"], ["CVE-2025-49844"])
 
 
+class TestChangelogAttribution(unittest.TestCase):
+    """Projects that publish no advisory feed still say which release fixed what — in their changelog."""
+
+    CHANGES = """
+Changes with nginx 1.31.3        11 Aug 2026
+    *) Security: a flaw ... (CVE-2026-60005)
+    *) Security: another ... (CVE-2026-56434)
+
+Changes with nginx 1.31.2        04 Aug 2026
+    *) Security: something ... (CVE-2026-48142)
+
+Changes with nginx 1.31.1        21 Jul 2026
+    *) Security: older ... (CVE-2026-9256)
+
+Changes with nginx 1.20.0        01 Jan 2021
+    *) Security: ancient ... (CVE-2013-2028)
+"""
+
+    def test_each_cve_is_attributed_to_the_release_that_fixed_it(self):
+        got = A._changelog_versions(self.CHANGES)
+        self.assertEqual(got["CVE-2026-60005"], "1.31.3")
+        self.assertEqual(got["CVE-2026-48142"], "1.31.2")
+        self.assertEqual(got["CVE-2026-9256"], "1.31.1")
+        self.assertEqual(got["CVE-2013-2028"], "1.20.0")
+
+    def _scan(self, wfrom, wto):
+        # nginx publishes NO GitHub advisories — the feed is empty and the changelog is everything.
+        return run_scan(
+            [gh("nginx/nginx", [])],
+            [{"source": "https://nginx.org/en/CHANGES", "status": "ok",
+              "cves": sorted(A._changelog_versions(self.CHANGES)),
+              "context": {}, "fixed_in": A._changelog_versions(self.CHANGES)}],
+            images=[("nginx", wfrom, wto)], urls=["https://github.com/nginx/nginx"])
+
+    def test_window_counts_only_the_releases_it_crosses(self):
+        rep = self._scan("1.31.1", "1.31.3")   # 1.31.1 is the FROM, so its CVE is already fixed
+        self.assertEqual(set(rep["fixed_by_this_upgrade"]),
+                         {"CVE-2026-48142", "CVE-2026-56434", "CVE-2026-60005"})
+
+    def test_a_narrower_window_counts_fewer(self):
+        rep = self._scan("1.31.2", "1.31.3")
+        self.assertEqual(set(rep["fixed_by_this_upgrade"]), {"CVE-2026-56434", "CVE-2026-60005"})
+
+    def test_ancient_entries_are_not_swept_in(self):
+        # The changelog lists the project's whole history; only the crossed releases may count.
+        rep = self._scan("1.31.1", "1.31.3")
+        self.assertNotIn("CVE-2013-2028", rep["fixed_by_this_upgrade"])
+
+    def test_evidence_is_recorded(self):
+        rep = self._scan("1.31.1", "1.31.3")
+        self.assertEqual(rep["resolved_by_changelog"]["CVE-2026-60005"], "1.31.3")
+
+
+class TestComposeDerivedWindows(unittest.TestCase):
+    """Windows read off a compose diff, so nobody has to remember which --image args an upgrade needs."""
+
+    OLD = """
+services:
+  app:
+    image: "plausible/analytics:v2.0.0"
+  db:
+    image: pgautoupgrade/pgautoupgrade:18-alpine
+  plausible_events_db:
+    image: clickhouse/clickhouse-server:23.4.2.11-alpine
+volumes:
+  data:
+"""
+    NEW = """
+services:
+  app:
+    image: "ghcr.io/plausible/community-edition:v3.2.1"
+  db:
+    image: pgautoupgrade/pgautoupgrade:18-alpine
+  plausible_events_db:
+    image: clickhouse/clickhouse-server:24.12-alpine
+volumes:
+  data:
+"""
+
+    def _windows(self, old=None, new=None):
+        pages = {"to": new if new is not None else self.NEW,
+                 "from": old if old is not None else self.OLD}
+        with unittest.mock.patch.object(A, "_fetch", lambda u, h=None: pages["to" if "to" in u else "from"]), \
+             unittest.mock.patch.object(A, "_gitea_auth", lambda u: {}):
+            return A.windows_from_compose("http://x/to", "http://x/from")[0]
+
+    def test_app_service_leads_and_sidecars_follow(self):
+        w = self._windows()
+        self.assertEqual(w[0], ("community-edition", "v2.0.0", "v3.2.1"))
+        self.assertIn(("clickhouse-server", "23.4.2.11-alpine", "24.12-alpine"), w)
+
+    def test_unchanged_images_are_not_windows(self):
+        # pgautoupgrade is identical in both; inventing a window for it would be a false count.
+        self.assertNotIn("pgautoupgrade", [n for n, _, _ in self._windows()])
+
+    def test_a_changed_image_REPO_is_still_the_same_service(self):
+        # plausible/analytics -> ghcr.io/plausible/community-edition. Keyed by image repo this reads
+        # as one image vanishing and another appearing, and the app window is lost entirely.
+        w = self._windows()
+        self.assertTrue(any(n == "community-edition" and f == "v2.0.0" for n, f, _ in w))
+
+    def test_no_change_yields_no_windows(self):
+        self.assertEqual(self._windows(old=self.NEW, new=self.NEW), [])
+
+    def test_templated_tags_are_skipped(self):
+        new = self.NEW.replace('ghcr.io/plausible/community-edition:v3.2.1', 'ghost:${IMAGE_VERSION}')
+        self.assertNotIn("ghost", [n for n, _, _ in self._windows(new=new)])
+
+
+class TestImageNameMatching(unittest.TestCase):
+    """An image name and its advisory source rarely spell each other exactly."""
+
+    def test_matches_when_the_image_name_is_LONGER_than_the_source(self):
+        # clickhouse/clickhouse-server vs source ClickHouse/ClickHouse — one-directional matching
+        # dropped this window silently when the key came from a compose file.
+        rep = run_scan([gh("ClickHouse/ClickHouse", [adv("CVE-1", patched="23.10.2.13")])],
+                       images=[("clickhouse-server", "23.4.2.11", "24.12")],
+                       urls=["https://github.com/ClickHouse/ClickHouse"])
+        self.assertIn("github-advisories:ClickHouse/ClickHouse", rep["windows"])
+        self.assertEqual(rep["cve_count_fixed"], 1)
+
+    def test_matches_when_the_image_name_is_SHORTER_than_the_source(self):
+        rep = run_scan([gh("redis/redis", [adv("CVE-2", patched="7.4.1")])],
+                       images=[("redis", "7.4", "8.10")], urls=["https://github.com/redis/redis"])
+        self.assertEqual(rep["cve_count_fixed"], 1)
+
+
 class TestAdjudicationEvidenceAssembly(unittest.TestCase):
     """Pass 2's JUDGEMENT is a model's and not testable; what IS testable is what it gets shown."""