boost-skill-cli 1.0.263__tar.gz → 1.0.265__tar.gz

{boost_skill_cli-1.0.263 → boost_skill_cli-1.0.265}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.263
+Version: 1.0.265
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

{boost_skill_cli-1.0.263 → boost_skill_cli-1.0.265}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.0.263'
-__version_tuple__ = version_tuple = (1, 0, 263)
+__version__ = version = '1.0.265'
+__version_tuple__ = version_tuple = (1, 0, 265)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.0.263 → boost_skill_cli-1.0.265}/boost_cli/commands/info.py

@@ -540,6 +540,26 @@ def cmd_explain(argv):
     return 0
 
 
+def _diag_line(line: str) -> str:
+    """Render one stored log line for display, whether it is text or JSON.
+
+    ``BOOST_LOG_FORMAT=json`` makes the file JSONL, which is the point — but
+    this command is the *human* view of that same file, and raw JSONL is not
+    it. Anything that is not a boost log object passes through untouched, so a
+    file whose format changed mid-life still reads end to end.
+    """
+    if not line.startswith("{"):
+        return line
+    try:
+        rec = json.loads(line)
+    except ValueError:
+        return line
+    if not isinstance(rec, dict) or "msg" not in rec:
+        return line
+    return "%s %-7s %s: %s" % (rec.get("ts", ""), rec.get("level", ""),
+                               rec.get("logger", ""), rec["msg"])
+
+
 def _show_diagnostics(limit):
     lp = logs.log_path()
     if not lp.exists():
@@ -548,7 +568,7 @@ def _show_diagnostics(limit):
     lines = lp.read_text(encoding="utf-8", errors="replace").splitlines()
     out.heading("diagnostic log — %s" % lp)
     for line in lines[-limit:]:
-        out.info(line)
+        out.info(_diag_line(line))
     return 0
 
 

{boost_skill_cli-1.0.263 → boost_skill_cli-1.0.265}/boost_cli/core/config.py

@@ -30,6 +30,10 @@ DEFAULTS = {
         # See core/logs.py and docs/DEBUGGING.md.
         "level": "OFF",
         "file": True,  # set false (or BOOST_NO_LOG=1) to disable the log file
+        # "text" (default) or "json". json emits one JSON object per line —
+        # the same fields, but readable by jq or a log collector without a
+        # regex. Overridden by BOOST_LOG_FORMAT.
+        "format": "text",
     },
 }
 

{boost_skill_cli-1.0.263 → boost_skill_cli-1.0.265}/boost_cli/core/logs.py

@@ -28,10 +28,21 @@ to disable the file.
 Each invocation bookends the trail with an ``invoke:`` line and a ``done:`` line
 that carries the exit code and wall-clock duration, so the log doubles as a
 lightweight timing record for spotting slow commands after the fact.
+
+Line *format* is resolved separately from verbosity, same precedence shape:
+
+  1. ``BOOST_LOG_FORMAT=json|text``
+  2. config ``logging.format`` (default ``text``)
+
+``json`` emits one JSON object per line — the same fields the text formatter
+renders — so ``~/.boost/logs/boost.log`` pipes straight into ``jq`` or a log
+collector instead of needing a regex. It is the same JSONL shape
+``core.journal`` already writes for the pulse feed.
 """
 from __future__ import annotations
 
 import contextlib
+import json
 import logging
 import logging.handlers
 import os
@@ -51,6 +62,9 @@ BACKUP_COUNT = 3       # … times (N+1) files kept = ~4 MB ceiling
 KEEP_CRASH_REPORTS = 20
 
 _LEVELS = ("DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL")
+_FORMATS = ("text", "json")
+_TEXT_FMT = "%(asctime)s %(levelname)-7s %(name)s: %(message)s"
+_DATE_FMT = "%Y-%m-%dT%H:%M:%SZ"
 
 # Set by configure(); read by main()'s exception handler to decide whether to
 # print a full traceback or a friendly one-liner.
@@ -98,6 +112,54 @@ def _console_level(verbose: bool, debug: bool, quiet: bool) -> Optional[int]:
     return getattr(logging, cfg) if cfg in _LEVELS else None
 
 
+class JsonFormatter(logging.Formatter):
+    """One JSON object per line, carrying the text formatter's own fields.
+
+    Hand-rolled rather than pulled from a dependency: the runtime is
+    stdlib-only, ``core.journal`` already writes JSONL by hand for the pulse
+    feed, and a formatter that can raise is a formatter that loses the trail it
+    exists to keep — hence ``default=str``, so an unexpected object in a record
+    degrades to its repr instead of killing the handler.
+
+    ``converter`` is set on the instance by :func:`_formatter`, not here: as a
+    class attribute mypy binds it as a method and the signature stops matching
+    the base class's.
+    """
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload = {
+            "ts": self.formatTime(record, _DATE_FMT),
+            "level": record.levelname,
+            "logger": record.name,
+            "msg": record.getMessage(),
+        }
+        if record.exc_info:
+            payload["exc"] = self.formatException(record.exc_info)
+        return json.dumps(payload, ensure_ascii=False, default=str)
+
+
+def log_format() -> str:
+    """Resolve the log line format: env first, then config, else ``text``."""
+    env = (os.environ.get("BOOST_LOG_FORMAT") or "").strip().lower()
+    if env in _FORMATS:
+        return env
+    from . import config
+    cfg = str(config.get("logging.format", "text") or "text").strip().lower()
+    return cfg if cfg in _FORMATS else "text"
+
+
+def _formatter(fmt_name: str) -> logging.Formatter:
+    """Build the formatter both handlers share."""
+    fmt: logging.Formatter = (JsonFormatter() if fmt_name == "json"
+                              else logging.Formatter(_TEXT_FMT,
+                                                     datefmt=_DATE_FMT))
+    # Both stamp a literal ``Z`` (UTC) suffix, so the timestamp has to be
+    # rendered in UTC — otherwise it uses local time and every line is
+    # mislabelled by the machine's offset. gmtime keeps it honest.
+    fmt.converter = time.gmtime
+    return fmt
+
+
 def _file_enabled() -> bool:
     if os.environ.get("BOOST_NO_LOG"):
         return False
@@ -141,14 +203,10 @@ def configure(verbose: bool = False, debug: bool = False,
         return logger
     _configured = True
 
-    fmt = logging.Formatter(
-        "%(asctime)s %(levelname)-7s %(name)s: %(message)s",
-        datefmt="%Y-%m-%dT%H:%M:%SZ",
-    )
-    # datefmt stamps a literal ``Z`` (UTC) suffix, so the timestamp must be
-    # rendered in UTC — otherwise ``%(asctime)s`` uses local time and every
-    # line is mislabelled by the machine's offset. gmtime keeps it honest.
-    fmt.converter = time.gmtime
+    # One formatter for both handlers: a user who asked for JSON asked for it
+    # everywhere, and a file/console split would make `--debug` disagree with
+    # the file it is meant to be showing.
+    fmt = _formatter(log_format())
 
     # File handler — always DEBUG, best-effort (never break the CLI over a log).
     if _file_enabled():

{boost_skill_cli-1.0.263 → boost_skill_cli-1.0.265}/boost_skill_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.263
+Version: 1.0.265
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

{boost_skill_cli-1.0.263 → boost_skill_cli-1.0.265}/docs/DEBUGGING.md

@@ -80,6 +80,33 @@ BOOST_NO_LOG=1 boost install foo      # this run writes no file
 boost config set logging.file false   # permanently
 ```
 
+### Structured (JSON) log lines
+
+The trail is plain text by default. `json` emits **one JSON object per line**
+carrying the same fields, so the file pipes straight into `jq` or a log
+collector instead of needing a regex:
+
+```bash
+BOOST_LOG_FORMAT=json boost install foo    # this run
+boost config set logging.format json       # permanently
+
+jq -r 'select(.level=="WARNING") | .msg' ~/.boost/logs/boost.log
+```
+
+| Field | Meaning |
+|-------|---------|
+| `ts` | UTC timestamp, `2026-07-27T14:03:11Z` |
+| `level` | `DEBUG` … `CRITICAL` |
+| `logger` | always `boost` today |
+| `msg` | the formatted message, arguments already interpolated |
+| `exc` | the traceback — present only on records logged with an exception |
+
+The format applies to the console channel too, so `--debug` shows the same
+shape the file is recording. `boost log --diagnostics` renders JSON lines back
+as text, so switching format doesn't cost you the built-in viewer, and a file
+whose format changed mid-life still reads end to end. An unrecognised value
+falls back to `text` rather than failing the run.
+
 ---
 
 ## Crash reports
@@ -149,6 +176,7 @@ Everything that changes boost's runtime behaviour, in one place:
 | `BOOST_AGENTS_STORE` | override `~/.agents/skills` (the canonical store) |
 | `BOOST_DEBUG` | `=1` → console `DEBUG` + tracebacks |
 | `BOOST_LOG_LEVEL` | explicit console diagnostic level |
+| `BOOST_LOG_FORMAT` | `text` (default) or `json` — one JSON object per log line |
 | `BOOST_NO_LOG` | `=1` → don't write the diagnostic log file |
 | `BOOST_NO_AI` | `=1` → disable all AI calls (offline / deterministic) |
 | `BOOST_ASSUME_YES` | `=1` → auto-confirm prompts (also `--yes`/`-y`) |

{boost_skill_cli-1.0.263 → boost_skill_cli-1.0.265}/scripts/build_roadmap.py

@@ -265,6 +265,40 @@ def build_design() -> tuple[Path, str]:
     return DESIGN_HTML, html
 
 
+_CARD_ID = re.compile(r'<article class="(?:cap rcard|ritem)" id="([^"]+)"')
+
+
+def diagnose(path, committed: str, fresh: str) -> list[str]:
+    """Explain *why* a board drifted, in the terms the reader needs.
+
+    The common cause is not a hand-edit. It is a rebase: another PR's card
+    merges in as a clean new ``docs/roadmap/items/*.md``, git merges the
+    generated HTML textually and succeeds, and the board is silently missing
+    that card. The old message said only "out of date", so a PR that changed no
+    Python at all went red across lint and every test leg with nothing in the
+    log pointing at the actual cause.
+    """
+    was = _CARD_ID.findall(committed)
+    now = _CARD_ID.findall(fresh)
+    missing = [i for i in now if i not in set(was)]
+    extra = [i for i in was if i not in set(now)]
+    lines = []
+    if missing:
+        lines.append("  missing %d card(s) present in docs/roadmap/items/: %s"
+                     % (len(missing), ", ".join(missing[:8])
+                        + (" …" if len(missing) > 8 else "")))
+        lines.append("  ↳ almost always a rebase: someone else's card landed on "
+                     "main and the generated HTML merged textually.")
+    if extra:
+        lines.append("  %d card(s) in the HTML have no item file: %s"
+                     % (len(extra), ", ".join(extra[:8])
+                        + (" …" if len(extra) > 8 else "")))
+    if not missing and not extra:
+        lines.append("  the same cards, rendered differently — an item file's "
+                     "fields or body changed, or the generator did.")
+    return lines
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(description="Regenerate the roadmap boards.")
     parser.add_argument(
@@ -277,21 +311,29 @@ def main(argv: list[str] | None = None) -> int:
     drift = []
     for path, fresh in targets:
         if args.check:
-            if path.read_text(encoding="utf-8") != fresh:
-                drift.append(path)
+            committed = path.read_text(encoding="utf-8")
+            if committed != fresh:
+                drift.append((path, committed, fresh))
         else:
             path.write_text(fresh, encoding="utf-8")
             print("wrote %s" % path)
 
     if args.check:
         if drift:
-            print(
-                "ERROR: roadmap HTML is out of date — regenerate with\n"
-                "    python3 scripts/build_roadmap.py\n"
-                "and commit the result (see CONTRIBUTING.md):\n  %s"
-                % "\n  ".join(str(p) for p in drift),
-                file=sys.stderr,
-            )
+            report = ["ERROR: the roadmap board is stale — regenerate with",
+                      "    python3 scripts/build_roadmap.py",
+                      "and commit the result (see CONTRIBUTING.md).",
+                      ""]
+            for path, committed, fresh in drift:
+                report.append("%s" % path)
+                report.extend(diagnose(path, committed, fresh))
+            print("\n".join(report), file=sys.stderr)
+            # One annotation so the cause is visible on the checks tab without
+            # opening a log: this failure lands on every matrix leg at once and
+            # reads as a broken build rather than a stale generated file.
+            print("::error::roadmap board is stale — run "
+                  "`python3 scripts/build_roadmap.py` and commit "
+                  "(usually needed after a rebase)")
             return 1
         print("roadmap boards are up to date.")
     return 0

{boost_skill_cli-1.0.263 → boost_skill_cli-1.0.265}/tests/unit/test_logs.py

@@ -1,10 +1,13 @@
 """Diagnostic logging & crash reporting."""
 from __future__ import annotations
 
+import json
 import logging
 import logging.handlers
 import pathlib
+import re
 import time
+from datetime import datetime, timezone
 
 import pytest
 
@@ -471,3 +474,140 @@ def test_a_real_crash_shows_up_in_the_listing(boost, monkeypatch):
     res = boost("log", "--crashes")
     assert crashed == ["count"]
     assert "command:  boost count" in res.out
+
+
+# ── BOOST_LOG_FORMAT=json ────────────────────────────────────────────────────
+
+class TestLogFormatResolution:
+    """Env beats config beats the `text` default — same shape as the level."""
+
+    def test_defaults_to_text(self, env):
+        assert logs.log_format() == "text"
+
+    def test_env_selects_json(self, env, monkeypatch):
+        monkeypatch.setenv("BOOST_LOG_FORMAT", "json")
+        assert logs.log_format() == "json"
+
+    def test_env_is_case_and_space_insensitive(self, env, monkeypatch):
+        monkeypatch.setenv("BOOST_LOG_FORMAT", "  JSON ")
+        assert logs.log_format() == "json"
+
+    def test_an_unknown_env_value_falls_back_to_text(self, env, monkeypatch):
+        # A typo must not silently disable logging or crash configure().
+        monkeypatch.setenv("BOOST_LOG_FORMAT", "yaml")
+        assert logs.log_format() == "text"
+
+    def test_config_selects_json_when_env_is_unset(self, env, monkeypatch):
+        from boost_cli.core import config
+        monkeypatch.delenv("BOOST_LOG_FORMAT", raising=False)
+        config.set_value("logging.format", "json")
+        assert logs.log_format() == "json"
+
+    def test_env_wins_over_config(self, env, monkeypatch):
+        from boost_cli.core import config
+        config.set_value("logging.format", "json")
+        monkeypatch.setenv("BOOST_LOG_FORMAT", "text")
+        assert logs.log_format() == "text"
+
+
+class TestJsonFileOutput:
+    def _records(self, env, monkeypatch):
+        monkeypatch.setenv("BOOST_LOG_FORMAT", "json")
+        logs.configure()
+        logs.get_logger().info("hello %s", "world")
+        text = logs.log_path().read_text(encoding="utf-8")
+        return [json.loads(ln) for ln in text.splitlines() if ln.strip()]
+
+    def test_one_json_object_per_line(self, env, monkeypatch):
+        recs = self._records(env, monkeypatch)
+        assert len(recs) == 1
+        assert recs[0]["msg"] == "hello world", "args must be interpolated"
+        assert recs[0]["level"] == "INFO"
+        assert recs[0]["logger"] == "boost"
+
+    def test_the_timestamp_is_utc_with_a_z(self, env, monkeypatch):
+        ts = self._records(env, monkeypatch)[0]["ts"]
+        assert re.match(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$", ts), ts
+        # Parsed as UTC it must be within a minute of now; a local-time stamp
+        # wearing a Z would be off by the machine's offset.
+        parsed = datetime.strptime(ts, "%Y-%m-%dT%H:%M:%SZ").replace(
+            tzinfo=timezone.utc)
+        assert abs((datetime.now(timezone.utc) - parsed).total_seconds()) < 60
+
+    def test_an_exception_is_carried_in_its_own_field(self, env, monkeypatch):
+        monkeypatch.setenv("BOOST_LOG_FORMAT", "json")
+        logs.configure()
+        try:
+            raise ValueError("boom")
+        except ValueError:
+            logs.get_logger().exception("caught it")
+        rec = [json.loads(ln) for ln in
+               logs.log_path().read_text(encoding="utf-8").splitlines()][-1]
+        assert rec["msg"] == "caught it"
+        assert "ValueError: boom" in rec["exc"]
+        assert "\n" not in json.dumps(rec), "one physical line per record"
+
+    def test_an_unserializable_arg_degrades_instead_of_losing_the_line(
+            self, env, monkeypatch):
+        # A formatter that raises loses the trail it exists to keep.
+        class Weird:
+            def __repr__(self):
+                return "<weird>"
+
+        monkeypatch.setenv("BOOST_LOG_FORMAT", "json")
+        logs.configure()
+        logs.get_logger().info("got %r", Weird())
+        rec = [json.loads(ln) for ln in
+               logs.log_path().read_text(encoding="utf-8").splitlines()][-1]
+        assert rec["msg"] == "got <weird>"
+
+    def test_text_mode_is_unchanged(self, env, monkeypatch):
+        monkeypatch.delenv("BOOST_LOG_FORMAT", raising=False)
+        logs.configure()
+        logs.get_logger().info("plain line")
+        text = logs.log_path().read_text(encoding="utf-8")
+        assert "INFO" in text and "boost: plain line" in text
+        assert not text.lstrip().startswith("{")
+
+
+class TestJsonConsoleOutput:
+    def test_the_console_handler_uses_the_same_format(self, env, monkeypatch,
+                                                      capsys):
+        # A `--debug` stream that disagrees with the file it is showing would
+        # be its own bug report.
+        monkeypatch.setenv("BOOST_LOG_FORMAT", "json")
+        logs.configure(debug=True)
+        logs.get_logger().error("stderr line")
+        err = capsys.readouterr().err.strip().splitlines()[-1]
+        assert json.loads(err)["msg"] == "stderr line"
+
+
+class TestDiagnosticsViewerReadsBothFormats:
+    """`boost log --diagnostics` is the human view of that same file."""
+
+    def _diag(self):
+        from boost_cli.commands import info
+        return info._diag_line
+
+    def test_a_json_line_is_rendered_back_as_text(self):
+        line = json.dumps({"ts": "2026-07-27T00:00:00Z", "level": "INFO",
+                           "logger": "boost", "msg": "invoke: boost count"})
+        assert self._diag()(line) == \
+            "2026-07-27T00:00:00Z INFO    boost: invoke: boost count"
+
+    def test_a_plain_text_line_passes_through(self):
+        line = "2026-07-27T00:00:00Z INFO    boost: invoke: boost count"
+        assert self._diag()(line) == line
+
+    def test_a_line_that_only_looks_like_json_passes_through(self):
+        # A mixed file (the format changed mid-life) has to read end to end.
+        for line in ("{not json at all", json.dumps({"other": "shape"}),
+                     json.dumps([1, 2, 3])):
+            assert self._diag()(line) == line
+
+    def test_the_command_renders_a_json_trail(self, boost, monkeypatch):
+        monkeypatch.setenv("BOOST_LOG_FORMAT", "json")
+        boost("count")
+        res = boost("log", "--diagnostics")
+        assert "invoke: boost count" in res.out
+        assert "{" not in res.out, "raw JSONL is not the human view"

boost_skill_cli-1.0.265/tests/unit/test_roadmap_fresh.py

@@ -0,0 +1,151 @@
+"""Committed roadmap HTML stays in lockstep with its item source files.
+
+The roadmap boards are generated from ``docs/roadmap/items/*.md`` by
+``scripts/build_roadmap.py`` and injected into the marker regions of the
+hand-authored pages. This test — the in-suite twin of the
+``build_roadmap.py --check`` CI step — fails if the committed HTML drifts from a
+fresh render, so a stale board can't merge.
+
+Skips when the repo-root files aren't reachable (e.g. the mutation sandbox,
+which only copies ``boost_cli/``).
+"""
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+import pytest
+
+_ROOT = Path(__file__).resolve().parents[2]
+_SCRIPT = _ROOT / "scripts" / "build_roadmap.py"
+_ITEMS = _ROOT / "docs" / "roadmap" / "items"
+
+
+def _load_builder():
+    spec = importlib.util.spec_from_file_location("build_roadmap", _SCRIPT)
+    assert spec and spec.loader
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+@pytest.mark.skipif(not (_SCRIPT.exists() and _ITEMS.exists()),
+                    reason="repo-root files not reachable (e.g. mutation sandbox)")
+def test_roadmap_html_is_regenerated():
+    builder = _load_builder()
+    path, fresh = builder.build_code()
+    committed = path.read_text(encoding="utf-8")
+    # Reuse the script's own diagnosis rather than restating "out of date".
+    # This assertion fires on all nine test legs at once, so what it says is
+    # what nine failures say — and the cause is a rebase far more often than a
+    # hand-edit.
+    assert committed == fresh, "\n".join(
+        ["docs/roadmap.html is stale — regenerate with",
+         "    python3 scripts/build_roadmap.py",
+         "and commit the result (see CONTRIBUTING.md).",
+         *builder.diagnose(path, committed, fresh)])
+
+
+@pytest.mark.skipif(not (_SCRIPT.exists() and _ITEMS.exists()),
+                    reason="repo-root files not reachable (e.g. mutation sandbox)")
+def test_design_roadmap_html_is_regenerated():
+    builder = _load_builder()
+    path, fresh = builder.build_design()
+    committed = path.read_text(encoding="utf-8")
+    assert committed == fresh, "\n".join(
+        ["docs/design-roadmap.html is stale — regenerate with",
+         "    python3 scripts/build_roadmap.py",
+         "and commit the result (see CONTRIBUTING.md).",
+         *builder.diagnose(path, committed, fresh)])
+
+
+@pytest.mark.skipif(not (_SCRIPT.exists() and _ITEMS.exists()),
+                    reason="repo-root files not reachable (e.g. mutation sandbox)")
+def test_check_flag_passes_on_fresh_tree():
+    builder = _load_builder()
+    assert builder.main(["--check"]) == 0
+
+
+@pytest.mark.skipif(not (_SCRIPT.exists() and _ITEMS.exists()),
+                    reason="repo-root files not reachable (e.g. mutation sandbox)")
+def test_every_code_item_has_required_fields():
+    builder = _load_builder()
+    for item in builder.load_items("code"):
+        for field in ("id", "section", "status", "title"):
+            assert item.get(field), "%s: missing %r" % (item["_file"], field)
+        assert item["status"] in builder.STATUS_LABEL, (
+            "%s: bad status %r" % (item["_file"], item["status"]))
+
+
+@pytest.mark.skipif(not (_SCRIPT.exists() and _ITEMS.exists()),
+                    reason="repo-root files not reachable (e.g. mutation sandbox)")
+def test_every_design_item_has_required_fields():
+    builder = _load_builder()
+    for item in builder.load_items("design"):
+        for field in ("id", "track", "status", "title"):
+            assert item.get(field), "%s: missing %r" % (item["_file"], field)
+        assert item["status"] in builder.DESIGN_STATUS, (
+            "%s: bad status %r" % (item["_file"], item["status"]))
+        assert str(item.get("impact", "")).lower() in builder.IMPACT_LABEL, (
+            "%s: bad impact %r" % (item["_file"], item.get("impact")))
+
+
+# ── the diagnosis itself ─────────────────────────────────────────────────────
+#
+# The failure above lands on lint and on all nine test legs simultaneously, for
+# a PR that may have changed no Python at all. Whether it reads as "the build is
+# broken" or as "regenerate the board after your rebase" is entirely down to
+# what these strings say, so they are tested rather than trusted.
+
+CARD = '<article class="cap rcard" id="%s">body</article>'
+
+
+@pytest.mark.skipif(not _SCRIPT.exists(), reason="repo-root files not reachable")
+class TestDiagnose:
+    def _lines(self, committed, fresh):
+        return _load_builder().diagnose(Path("docs/roadmap.html"),
+                                        committed, fresh)
+
+    def test_a_card_missing_from_the_html_names_it_and_blames_the_rebase(self):
+        # THE case this exists for: another PR's item file merged in cleanly,
+        # the generated HTML merged textually, and the card is simply absent.
+        lines = self._lines(CARD % "old-one",
+                            (CARD % "old-one") + (CARD % "someone-elses-card"))
+        text = "\n".join(lines)
+        assert "someone-elses-card" in text
+        assert "rebase" in text
+        assert "missing 1 card" in text
+
+    def test_several_missing_cards_are_summarised_not_dumped(self):
+        fresh = "".join(CARD % ("card-%d" % i) for i in range(20))
+        text = "\n".join(self._lines("", fresh))
+        assert "missing 20 card(s)" in text
+        assert text.count("card-") <= 9, "8 named plus the ellipsis"
+        assert "…" in text
+
+    def test_a_card_with_no_item_file_is_called_out_separately(self):
+        lines = self._lines(CARD % "deleted-item", "")
+        text = "\n".join(lines)
+        assert "no item file" in text
+        assert "deleted-item" in text
+        assert "rebase" not in text, "nothing is missing — different cause"
+
+    def test_same_cards_rendered_differently_says_so(self):
+        # A field or body edit, or a generator change — not a rebase.
+        lines = self._lines('<article class="cap rcard" id="a">old</article>',
+                            '<article class="cap rcard" id="a">new</article>')
+        text = "\n".join(lines)
+        assert "rendered differently" in text
+        assert "missing" not in text
+
+    def test_the_design_board_shape_is_recognised_too(self):
+        # design-roadmap.html uses <article class="ritem" …>, not "cap rcard".
+        fresh = ('<article class="ritem" id="BOOST-D99" data-track="x" '
+                 'data-impact="y">body</article>')
+        assert "BOOST-D99" in "\n".join(self._lines("", fresh))
+
+    def test_it_never_returns_nothing(self):
+        # An empty diagnosis would leave the assertion message ending on a
+        # colon with no explanation — worse than the message it replaced.
+        for committed, fresh in (("", ""), ("x", "y"), (CARD % "a", CARD % "a")):
+            assert self._lines(committed, fresh)