roadmap-core 0.3.0__tar.gz → 0.3.2__tar.gz

{roadmap_core-0.3.0/roadmap_core.egg-info → roadmap_core-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roadmap-core
-Version: 0.3.0
+Version: 0.3.2
 Summary: The roadmap work-item and arc graph: status derivation, validation, and markdown rendering. Stdlib-only, so any repo can adopt it without adopting a backend.
 License: MIT
 Project-URL: Source, https://github.com/gald33/roadmap-core

{roadmap_core-0.3.0 → roadmap_core-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "roadmap-core"
-version = "0.3.0"
+version = "0.3.2"
 description = "The roadmap work-item and arc graph: status derivation, validation, and markdown rendering. Stdlib-only, so any repo can adopt it without adopting a backend."
 requires-python = ">=3.11"
 readme = "README.md"

{roadmap_core-0.3.0 → roadmap_core-0.3.2}/roadmap_core/cli.py

@@ -1067,13 +1067,40 @@ def compare_sources(
         )
     for key in sorted(set(db) & set(files)):
         d, f = db[key], files[key]
-        if (d.get("status") == "done") != (f.get("status") == "done"):
+        done_differs = (d.get("status") == "done") != (f.get("status") == "done")
+        if done_differs:
             finished, stale = ("files", "DB") if f.get("status") == "done" else ("DB", "files")
             problems.append(
                 f"{key}: done in the {finished} but not in the {stale} — `done` is the "
                 f"one status the graph cannot derive, so the {stale} will keep offering "
                 f"finished work as startable"
             )
+        # `verifying` is underivable for exactly the same reason, and
+        # `derive_status` says so: `done`, `verifying` and an active claim are
+        # the three facts the graph cannot work out for itself. This compared
+        # two of the three. So a store holding `claimed` (or `ready`) against a
+        # file holding `verifying` read as AGREEMENT, and the committed
+        # ROADMAP.md kept offering shipped work as startable — the exact harm
+        # the `done` message above describes, reached by the one door left open.
+        #
+        # Measured in Lucille 2026-09-14: four items differed this way while
+        # `diff` reported "db and files agree", and the two committed artifacts
+        # disagreed with each other — ROADMAP.md listed
+        # `user-timezone-is-never-asked-only-defaulted` as `now` and startable
+        # while its own item file said `status: verifying`.
+        #
+        # Suppressed when `done` already differs: a db=`verifying` /
+        # files=`done` pair is ONE disagreement, and reporting it twice would
+        # make the commonest real case read as two problems.
+        elif (d.get("status") == "verifying") != (f.get("status") == "verifying"):
+            shipped, stale = (
+                ("files", "DB") if f.get("status") == "verifying" else ("DB", "files")
+            )
+            problems.append(
+                f"{key}: verifying in the {shipped} but not in the {stale} — `verifying` "
+                f"is underivable too, so the {stale} will keep offering shipped work as "
+                f"startable and its claim will read as an ordinary hold"
+            )
         if (d.get("claimed_by") or None) != (f.get("claimed_by") or None):
             problems.append(
                 f"{key}: claim differs — DB={d.get('claimed_by') or 'none'!r}, "
@@ -1171,6 +1198,23 @@ def cmd_diff(args: argparse.Namespace) -> int:
     return 1
 
 
+# How settled each of the two underivable statuses is. `derive_status` recomputes
+# every other status from the edges, so these are the only two a checkout cannot
+# work out for itself — and therefore the only two `pull` has to carry.
+#
+# THE ORDER IS THE DESIGN: `pull` moves a file UP this scale and never down. The
+# store's silence about `verifying` is IGNORANCE, NOT DENIAL — the backend honors
+# `status` on INSERT and ignores it on UPDATE, so a file's `verifying` has no path
+# into an existing store row at all. Projecting the store's `ready` back over it
+# would delete the only record that the work shipped and hand it to the next
+# session as startable, which is the very harm this projection exists to stop.
+#
+# Measured in Lucille from the two committed artifacts, 2026-09-17: 1 item where
+# the store holds the underivable status and the file does not, against 17 the
+# other way, 8 of them at store-status `ready`.
+_SETTLEMENT = {"verifying": 1, "done": 2}
+
+
 def cmd_pull(args: argparse.Namespace) -> int:
     """The inverse of ``push``: bring the store's reality back into the checkout.
 
@@ -1182,6 +1226,7 @@ def cmd_pull(args: argparse.Namespace) -> int:
     db = load(source)
     files = load_from_files()
     created, updated = [], []
+    projected: dict[str, str] = {}
     ITEMS_DIR.mkdir(parents=True, exist_ok=True)
     for key in sorted(db):
         item = db[key]
@@ -1198,11 +1243,27 @@ def cmd_pull(args: argparse.Namespace) -> int:
                 else None
             )
             changed = write_claim_to_file(key, claim) or changed
-        if item.get("status") == "done" and local.get("status") != "done":
+        # This projected `done` and nothing else. `verifying` post-dates it and
+        # was never added — not a considered rejection, just a gap — so a store
+        # that knew an item had shipped could not tell a checkout, and every
+        # tokenless session (which is how dispatch runs BY DESIGN) read `ready`
+        # for work that merged days earlier. `pull` would print "the files
+        # already match the store" while `diff` reported the divergence in the
+        # same second, and the sync workflow asserting `diff` stayed red with no
+        # automatic remedy.
+        #
+        # Strictly increasing, per `_SETTLEMENT`: add what the store knows, never
+        # remove what only the file knows.
+        db_rank = _SETTLEMENT.get(item.get("status"), 0)
+        local_rank = _SETTLEMENT.get(local.get("status"), 0)
+        if db_rank > local_rank:
             path = item_path(key)
             path.write_text(
-                _replace_top_level_key(path.read_text(), "status", ["status: done"])
+                _replace_top_level_key(
+                    path.read_text(), "status", [f"status: {item['status']}"]
+                )
             )
+            projected[key] = f"{local.get('status') or 'unset'} -> {item['status']}"
             changed = True
         # A priority set straight against the API (by an operator with no
         # checkout — the case that motivated the field) changes no file, so
@@ -1254,7 +1315,11 @@ def cmd_pull(args: argparse.Namespace) -> int:
     for key in created:
         print(f"created roadmap/items/{key}.yaml")
     for key in updated:
-        print(f"updated roadmap/items/{key}.yaml")
+        # Name the transition. A bare "updated <file>" does not say a status
+        # moved, and a repair that leaves no trace hides the next regression
+        # exactly as this one hid itself.
+        note = f" (status: {projected[key]})" if key in projected else ""
+        print(f"updated roadmap/items/{key}.yaml{note}")
     for key in arcs_created:
         print(f"created roadmap/arcs/{key}.yaml")
     if not created and not updated and not arcs_created:
@@ -1295,20 +1360,37 @@ def _stale_claim_notice(by_key: dict[str, dict[str, Any]]) -> None:
     if not stale:
         return
     print(
-        f"\nnote: {len(stale)} claim(s) held longer than {graph.STALE_CLAIM_DAYS}d — "
+        f"\nnote: {len(stale)} claim(s) held longer than expected — "
         f"likely finished sessions that never released:",
         file=sys.stderr,
     )
     for item in stale:
+        # Name the bar this item was actually judged against. A flat
+        # "longer than 3d" header was already wrong for `verifying`, which is
+        # held to a longer one; printing one number for a mixed list just moves
+        # that error rather than fixing it.
+        limit = item.get("claim_threshold_days", graph.STALE_CLAIM_DAYS)
+        status = str(item.get("status") or "")
         print(
             f"  {item['key']} — {item.get('claimed_by')} "
-            f"({item['claim_age_days']:.1f}d ago)",
+            f"({item['claim_age_days']:.1f}d ago, over {limit:g}d"
+            + (f", {status}" if status else "")
+            + ")",
             file=sys.stderr,
         )
     print(
         "  Verify the branch is merged or gone, then `roadmap.py release <key>`.",
         file=sys.stderr,
     )
+    if any(item.get("status") == "verifying" for item in stale):
+        # `release` is the WRONG first move for one of these: the item shipped
+        # and is waiting on an observation, so the usual outcome is that the
+        # effect landed and nobody said so.
+        print(
+            "  For a `verifying` item, `roadmap.py status <key> done` if the effect "
+            "has landed — release only if the watch was abandoned.",
+            file=sys.stderr,
+        )
 
 
 def _own_claims_notice(by_key: dict[str, dict[str, Any]], *, exclude: str = "") -> None:
@@ -1457,6 +1539,13 @@ def cmd_prune(args: argparse.Namespace) -> int:
     carrying forward should already be in ``ARCS.md`` or the design doc — an item
     is a work ticket, not an archive.
 
+    WITH ONE EXCEPTION: an item carrying ``tickets`` is withheld. That field is
+    the only copy of the edge from shipped work back to the person who reported
+    it, and unlike the prose above it has no second home in git history that
+    anything queries. ``--include-ticket-linked`` overrides, for an operator who
+    has checked those loops are closed. See the comment at the withholding for
+    why the predicate here is broader than the rule it implements.
+
     DB first, then the file: if the store delete fails the file stays, so a
     partial run is simply re-runnable rather than leaving an item that exists in
     a checkout and nowhere else.
@@ -1485,32 +1574,74 @@ def cmd_prune(args: argparse.Namespace) -> int:
         for line in blockers:
             print(f"  {line}", file=sys.stderr)
     files = load_from_files()
+    stored: dict[str, dict[str, Any]] = {}
     done = sorted(k for k, i in files.items() if i.get("status") == "done")
     try:
+        stored = load_from_db()
         done += sorted(
-            k for k, i in load_from_db().items() if i.get("status") == "done" and k not in done
+            k for k, i in stored.items() if i.get("status") == "done" and k not in done
         )
     except SystemExit as exc:  # no JWT / API down — the file side still prunes
         print(f"warning: could not read the store ({exc}); pruning files only", file=sys.stderr)
     if not done:
         print("no done items — nothing to prune")
         return 0
-    # A pruned item takes its `done_at`, `done_version` and ticket links with it,
-    # and those are exactly the fields `impact` reads — the answer to "is anybody
-    # still complaining about this after we fixed it" only exists while the item
-    # does. Warned, not blocked: rule 4 says do not accumulate a done pile, and
-    # silently refusing to prune would rebuild the pile this command exists to
-    # clear. Run `impact` first if the answer still matters.
-    linked = {k: files.get(k, {}).get("tickets") or [] for k in done}
+    # HYGIENE LOSES TO EVIDENCE. A pruned item takes its `tickets` with it, and
+    # that field is the ONLY copy of the link from shipped work back to the
+    # person who reported it — one writer, no second copy anywhere. `impact`
+    # reads it to answer "is anybody still complaining about this after we
+    # fixed it", and Lucille's ticket lifecycle walks it the other way to move
+    # a report to `handled`, the one status its reporter ever sees. Destroying
+    # it to tidy a done pile trades something irreplaceable for something
+    # cosmetic.
+    #
+    # So this used to warn and prune anyway. It now withholds them, which is
+    # the CEO ruling of 2026-09-14 (gald33/Lucille#1429).
+    #
+    # ⚠️ THE RULING IS NARROWER THAN WHAT IS IMPLEMENTED HERE, and the gap is
+    # deliberate rather than forgotten. The rule is "skip an item whose
+    # `tickets` is non-empty AND WHOSE LOOP IS STILL OPEN" — once the linked
+    # ticket reaches `handled` the edge has done its job and the item should
+    # prune normally. The predicate is "is this edge still load-bearing", not
+    # "does this field exist". This package cannot evaluate the first half:
+    # ticket status lives in the consumer's `feedback_tickets` table, and
+    # reaching for it would make a stdlib-only library depend on one specific
+    # backend — the one thing `pyproject.toml` says it must never do. So the
+    # conservative half is implemented, it is LOUD about being conservative,
+    # and `--include-ticket-linked` is the operator's way to say "I checked,
+    # the loops are closed" — the judgement a human can make and this code
+    # cannot.
+    linked = {k: ((files.get(k) or stored.get(k) or {}).get("tickets") or []) for k in done}
     linked = {k: v for k, v in linked.items() if v}
-    if linked:
+    if linked and not args.include_ticket_linked:
+        done = [k for k in done if k not in linked]
         print(
-            "warning: these carry ticket links; `impact` cannot answer for them "
-            "once pruned:",
+            f"withholding {len(linked)} item(s): they carry ticket links, which "
+            "are the only record of who reported the work.",
+            file=sys.stderr,
+        )
+        for key, ids in sorted(linked.items()):
+            print(f"  {key}  ({len(ids)} ticket(s): {', '.join(ids)})", file=sys.stderr)
+        print(
+            "This tool cannot see ticket status — that lives in the consuming\n"
+            "application, not in roadmap-core — so it cannot tell a loop that is\n"
+            "still open from one already closed, and withholds both. Check\n"
+            f"whether those tickets are handled (`{graph.CLI} impact <key>` shows\n"
+            "what the links answer); if they are, re-run with\n"
+            "--include-ticket-linked to prune them too.",
+            file=sys.stderr,
+        )
+    elif linked:
+        print(
+            f"--include-ticket-linked: pruning {len(linked)} item(s) WITH ticket "
+            "links; their link to the reporter is destroyed:",
             file=sys.stderr,
         )
         for key, ids in sorted(linked.items()):
             print(f"  {key}  ({len(ids)} ticket(s))", file=sys.stderr)
+    if not done:
+        print("nothing to prune — every done item is withheld for its ticket links")
+        return 0
 
     if not args.yes:
         print("would prune (re-run with --yes):")
@@ -1668,8 +1799,23 @@ def cmd_list(args: argparse.Namespace) -> int:
                     suffix += f"  ⚠️ held {age:.1f}d"
             elif unmet := graph.unmet_deps(item, by_key):
                 suffix = f"  ← {', '.join(unmet)}"
+            # The status token is ON THE LINE, not only in the band header
+            # above it. A header is read once and then scrolled past: a grep, a
+            # truncated read, a line quoted into a dispatch message, or plain
+            # scrollback all deliver the line WITHOUT it, and the line then
+            # says nothing about whether the work is open. Measured 2026-09-14
+            # in Lucille: 10 of its 18 `done` items carried a `now`/`next`
+            # priority, so they rendered as `now  <key>  <present-tense
+            # defect>` — byte-identical in shape to the repo's highest-priority
+            # open work. A session read one, believed it, and dispatched ~150k
+            # tokens re-fixing already-shipped work.
+            #
+            # Every item gets one, never only the finished ones: a marker that
+            # appears conditionally makes ABSENCE carry meaning, which is the
+            # exact shape of the bug — an unmarked line read as open work.
             print(
-                f"  {graph.priority_of(item) or '':<6} "
+                f"  {statename:<{graph.STATUS_WIDTH}} "
+                f"{graph.priority_of(item) or '':<6} "
                 f"{item['key']:<38} {item['title']}{suffix}"
             )
     _stale_claim_notice(by_key)
@@ -2277,6 +2423,13 @@ def main(argv: list[str] | None = None) -> int:
         help="prune even though roadmap/items/ disagrees with origin/main "
              "(you have read the difference and it is deliberate)",
     )
+    p_prune.add_argument(
+        "--include-ticket-linked",
+        action="store_true",
+        help="also prune done items that carry `tickets` links (withheld by "
+             "default: that field is the only record of who reported the work, "
+             "and this tool cannot see whether their loop is closed)",
+    )
     p_prune.set_defaults(func=cmd_prune)
 
     p_refile = sub.add_parser(

{roadmap_core-0.3.0 → roadmap_core-0.3.2}/roadmap_core/graph.py

@@ -20,6 +20,14 @@ from typing import Any
 
 STATUSES = ("ready", "deferred", "blocked", "claimed", "verifying", "done")
 
+#: Column width for a status token printed alongside other columns.
+#:
+#: Derived from ``STATUSES`` rather than written out, so adding a longer status
+#: cannot silently unalign every surface that prints one. Every renderer that
+#: puts a status in a column uses this, which is what makes ``roadmap list``
+#: line up with anything else that grows one later.
+STATUS_WIDTH = max(len(s) for s in STATUSES)
+
 #: How the generated markdown tells a reader to re-run this tool.
 #:
 #: The name of the console script this package installs, and DELIBERATELY A
@@ -90,6 +98,48 @@ _UNKNOWN_PRIORITY_RANK = _PRIORITY_RANK[None]
 #: the next reader, who can check the branch and decide.
 STALE_CLAIM_DAYS = 3
 
+#: How long a ``verifying`` claim may stand before it reads as suspect.
+#:
+#: The threshold above rests on "an agent claims, works, opens a PR and merges,
+#: usually inside a day". ``verifying`` is the one status where that is FALSE BY
+#: DESIGN, and this package says so itself — setting the status prints "verifying
+#: does NOT drop the claim — the branch that shipped this still owns confirming
+#: it. Move to `done` once the effect is actually observed". Observing a prod
+#: effect takes as long as it takes; a post-merge check can sit inside a 14-day
+#: window before it has anything to report.
+#:
+#: So the flat 3-day read made this package contradict itself between two of its
+#: own commands. Measured in Lucille 2026-09-14: ``ready`` reported
+#: ``closure-tool-fires-but-nothing-is-written`` as a "likely finished session
+#: that never released" and advised releasing it, while that repo's own claim
+#: audit reported the same item the same day as "'verifying', which is the one
+#: status that deliberately keeps its claim ... Nothing to decide." Releasing it
+#: would have stripped the claim from the branch that owns the watch — so the
+#: advice was not merely noisy, it was wrong.
+#:
+#: Still a surfacing threshold and never an expiry: a ``verifying`` claim CAN be
+#: abandoned, by a session that shipped and died before the effect landed. It is
+#: reported later, not never.
+VERIFYING_CLAIM_DAYS = 14
+
+#: Statuses whose claim is expected to outlive a session. Anything absent here
+#: uses ``STALE_CLAIM_DAYS``; a status is listed only when holding is the
+#: DOCUMENTED behaviour, never to quiet a noisy report.
+_CLAIM_THRESHOLD_DAYS: dict[str, float] = {"verifying": VERIFYING_CLAIM_DAYS}
+
+
+def claim_threshold_days(
+    item: dict[str, Any], *, threshold_days: float = STALE_CLAIM_DAYS
+) -> float:
+    """How long *this* item's claim may stand before it reads as suspect.
+
+    ``max`` rather than a plain override, so a caller that deliberately widens
+    the base threshold widens this one with it. Narrowing it does not narrow
+    this one — a status that holds on purpose still holds on purpose.
+    """
+    override = _CLAIM_THRESHOLD_DAYS.get(str(item.get("status") or ""))
+    return threshold_days if override is None else max(override, threshold_days)
+
 #: The second edge type, and the only non-blocking one.
 #:
 #: ``blocked_on`` says "do not start X until Y is done" — a claim about
@@ -334,12 +384,24 @@ def stale_claims(
     Copies rather than mutating, with ``claim_age_days`` added, so the CLI, the
     API and the generated markdown all report the same age from the same
     computation instead of each re-deriving it against its own clock.
+
+    The threshold is per-status (see ``claim_threshold_days``): ``verifying``
+    keeps its claim on purpose, and reporting that as an abandoned hold made
+    this package advise undoing something it had just told the caller to do.
+    ``claim_threshold_days`` is carried on each returned item so a caller can
+    say what bar was applied instead of assuming the base one.
     """
     aged = []
     for key in sorted(by_key):
-        age = claim_age_days(by_key[key], now=now)
-        if age is not None and age >= threshold_days:
-            aged.append({**by_key[key], "claim_age_days": round(age, 1)})
+        item = by_key[key]
+        age = claim_age_days(item, now=now)
+        if age is None:
+            continue
+        limit = claim_threshold_days(item, threshold_days=threshold_days)
+        if age >= limit:
+            aged.append(
+                {**item, "claim_age_days": round(age, 1), "claim_threshold_days": limit}
+            )
     return sorted(aged, key=lambda item: item["claim_age_days"], reverse=True)
 
 
@@ -572,6 +634,25 @@ def _node(key: str) -> str:
     return key.replace("-", "_")
 
 
+#: How each derived status is drawn in the dependency graph.
+#:
+#: One entry per ``STATUSES`` member — asserted by the tests, so a new status
+#: cannot be added without deciding how it looks, which is the failure mode
+#: where an unstyled node silently renders as the default and reads as open.
+#:
+#: Stroke properties only. This block is rendered on GitHub in both a light and
+#: a dark theme, and a hardcoded ``fill`` or text ``color`` that reads well on
+#: one is unreadable on the other.
+_MERMAID_STATUS_STYLE = {
+    "ready": "stroke:#2da44e,stroke-width:2px",
+    "deferred": "stroke:#9a6700,stroke-width:1px,stroke-dasharray:4 3",
+    "blocked": "stroke:#cf222e,stroke-width:2px",
+    "claimed": "stroke:#8250df,stroke-width:2px",
+    "verifying": "stroke:#0969da,stroke-width:2px,stroke-dasharray:6 3",
+    "done": "stroke:#8c959f,stroke-width:1px,stroke-dasharray:5 4",
+}
+
+
 def render_markdown(by_key: dict[str, dict[str, Any]]) -> str:
     """The agent-facing projection of the graph.
 
@@ -762,9 +843,39 @@ def render_markdown(by_key: dict[str, dict[str, Any]]) -> str:
         add("")
         add("```mermaid")
         add("graph TD")
+        # Six constant lines. They are byte-identical on every branch, so they
+        # add no conflict surface at all — unlike a `class a,b,c done` roll-up,
+        # which would be a graph-wide aggregate on ONE line and would conflict
+        # between any two branches that finished different items. That is the
+        # #1103 shape this function's docstring refuses, arriving through
+        # styling instead of through a count. Strokes only, no fill and no text
+        # colour, because this renders on both a light and a dark background
+        # and a hardcoded fill is unreadable on one of them.
+        for statename in STATUSES:
+            add(f"  classDef {statename} {_MERMAID_STATUS_STYLE[statename]}")
         for key in sorted(derived):
+            status = derived[key]["status"]
             label = derived[key]["title"].replace('"', "'")
-            add(f'  {_node(key)}["{label}"]')
+            # Every node carries its status, and it is carried BY THE NODE'S OWN
+            # LINE. Before this the 82 nodes of Lucille's committed graph
+            # rendered identically whether `ready` or `done`, in the one
+            # artifact a session reads to decide what to work on.
+            #
+            # Two markers, because the two readers of this block are different.
+            # `:::status` is for whoever reads the SOURCE — a grep, a diff, an
+            # agent reading the checked-in markdown — and it survives being
+            # quoted a line at a time. The `✓ ` prefix is for whoever reads the
+            # PICTURE, where a stroke colour is a distinction that can be
+            # missed and a glyph in the label cannot be. A `classDef` alone
+            # would have been invisible to the first reader and easy to miss
+            # for the second.
+            #
+            # `:::status` goes on every node, never only the done ones, for the
+            # reason `cmd_list` prints a status on every row: a conditional
+            # marker makes absence carry meaning, and "no marker" reading as
+            # "open" is the bug itself.
+            prefix = "✓ " if status == "done" else ""
+            add(f'  {_node(key)}["{prefix}{label}"]:::{status}')
         for key in sorted(derived):
             for dep in derived[key].get("blocked_on") or []:
                 add(f"  {_node(dep)} --> {_node(key)}")

{roadmap_core-0.3.0 → roadmap_core-0.3.2/roadmap_core.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roadmap-core
-Version: 0.3.0
+Version: 0.3.2
 Summary: The roadmap work-item and arc graph: status derivation, validation, and markdown rendering. Stdlib-only, so any repo can adopt it without adopting a backend.
 License: MIT
 Project-URL: Source, https://github.com/gald33/roadmap-core

{roadmap_core-0.3.0 → roadmap_core-0.3.2}/roadmap_core.egg-info/SOURCES.txt

@@ -20,5 +20,7 @@ tests/test_arcs.py
 tests/test_graph.py
 tests/test_impact.py
 tests/test_mcp_server.py
+tests/test_pull_projects_status.py
+tests/test_renderers.py
 tests/test_store.py
 tests/test_stores.py

{roadmap_core-0.3.0 → roadmap_core-0.3.2}/tests/test_graph.py

@@ -232,3 +232,167 @@ def test_cli_messages_name_no_path_from_the_extraction_repo():
                 f"cli.py prints {text!r}, naming {bad!r} — a path that exists only in "
                 f"the repository this package was extracted from. Use `graph.CLI`."
             )
+
+
+# --- a claim that is held on purpose is not a claim that was forgotten -------
+
+
+def _held(key, *, status, days_ago, now):
+    """An item claimed `days_ago` by a branch, in `status`."""
+    import datetime as _dt
+
+    return {
+        "key": key,
+        "title": key,
+        "status": status,
+        "blocked_on": [],
+        "evidence": "x",
+        "claimed_by": f"claude/{key}",
+        "claimed_at": (now - _dt.timedelta(days=days_ago)).isoformat(),
+    }
+
+
+def _now():
+    import datetime as _dt
+
+    return _dt.datetime(2026, 9, 14, 12, 0, tzinfo=_dt.timezone.utc)
+
+
+def test_a_verifying_claim_is_not_stale_at_the_base_threshold():
+    """The bug this package had against itself.
+
+    Setting `verifying` PRINTS "verifying does NOT drop the claim — the branch
+    that shipped this still owns confirming it". `ready` then reported that
+    same claim as a "likely finished session that never released" and advised
+    releasing it. Measured in Lucille 2026-09-14 on
+    `closure-tool-fires-but-nothing-is-written`, held 7.8 days; its own claim
+    audit said "Nothing to decide" about the identical row the same day.
+    Releasing it would have stripped the claim from the branch that owns the
+    watch — wrong advice, not merely noisy.
+    """
+    now = _now()
+    by_key = {
+        "claimed": _held("claimed", status="claimed", days_ago=7.8, now=now),
+        "verifying": _held("verifying", status="verifying", days_ago=7.8, now=now),
+    }
+    stale = graph.stale_claims(by_key, now=now)
+    assert [item["key"] for item in stale] == ["claimed"], (
+        "a `verifying` claim held under the verifying threshold must not be "
+        "reported as an abandoned hold"
+    )
+
+
+def test_a_verifying_claim_is_still_reported_once_it_outlives_its_own_window():
+    """Surfacing threshold, never an expiry — reported later, not never.
+
+    A session can ship and die before the effect lands, and that claim is just
+    as abandoned as any other. Excluding `verifying` outright would trade a
+    wrong report for a missing one.
+    """
+    now = _now()
+    by_key = {"v": _held("v", status="verifying", days_ago=20.0, now=now)}
+    stale = graph.stale_claims(by_key, now=now)
+    assert [item["key"] for item in stale] == ["v"]
+    assert stale[0]["claim_threshold_days"] == graph.VERIFYING_CLAIM_DAYS
+
+
+def test_the_verifying_window_is_longer_than_the_base_one():
+    """If these ever cross, the override silently becomes a no-op."""
+    assert graph.VERIFYING_CLAIM_DAYS > graph.STALE_CLAIM_DAYS
+
+
+def test_a_widened_threshold_widens_verifying_too():
+    """`max`, not override: a caller asking for a laxer bar gets it everywhere.
+
+    Otherwise `threshold_days=30` would report a 20-day `verifying` hold while
+    ignoring a 20-day `claimed` one — the laxer request making the stricter
+    answer.
+    """
+    now = _now()
+    by_key = {"v": _held("v", status="verifying", days_ago=20.0, now=now)}
+    assert graph.stale_claims(by_key, now=now, threshold_days=30) == []
+    assert graph.claim_threshold_days(by_key["v"], threshold_days=30) == 30
+
+
+def test_a_narrowed_threshold_does_not_narrow_verifying():
+    """A status that holds on purpose still holds on purpose."""
+    now = _now()
+    by_key = {"v": _held("v", status="verifying", days_ago=7.8, now=now)}
+    assert graph.stale_claims(by_key, now=now, threshold_days=0.1) == []
+
+
+def test_every_other_status_keeps_the_base_threshold():
+    """The override is a named exception, not a general loosening."""
+    now = _now()
+    for status in graph.STATUSES:
+        if status == "verifying":
+            continue
+        item = _held("k", status=status, days_ago=4.0, now=now)
+        assert graph.claim_threshold_days(item) == graph.STALE_CLAIM_DAYS, status
+        assert graph.stale_claims({"k": item}, now=now), status
+
+
+def test_an_unknown_status_keeps_the_base_threshold():
+    """A typo must not silently buy an item a two-week hold."""
+    now = _now()
+    item = _held("k", status="verifyng", days_ago=4.0, now=now)
+    assert graph.claim_threshold_days(item) == graph.STALE_CLAIM_DAYS
+    assert graph.stale_claims({"k": item}, now=now)
+
+
+# --- the drift detector compared two of the three underivable facts ---------
+
+
+def _pair(db_status, file_status, *, db_claim=None, file_claim=None):
+    from roadmap_core import cli
+
+    db = {"k": {"key": "k", "status": db_status, "claimed_by": db_claim}}
+    files = {"k": {"key": "k", "status": file_status, "claimed_by": file_claim}}
+    return cli.compare_sources(db, files)
+
+
+def test_a_verifying_disagreement_is_a_divergence():
+    """`derive_status` names three facts the graph cannot derive — `done`,
+    `verifying` and an active claim. `compare_sources` checked two of them.
+
+    So a store holding `claimed` against a file holding `verifying` read as
+    AGREEMENT. Measured in Lucille 2026-09-14: four items differed this way
+    while `diff` reported "db and files agree", and the two committed artifacts
+    contradicted each other — ROADMAP.md offered
+    `user-timezone-is-never-asked-only-defaulted` as `now` and startable while
+    its own item file said `status: verifying`.
+    """
+    problems = _pair("claimed", "verifying", db_claim="claude/x", file_claim="claude/x")
+    assert any("verifying" in p for p in problems), (
+        "a store/file disagreement on `verifying` must be reported; it is as "
+        "underivable as `done` and decides whether work is offered"
+    )
+
+
+def test_a_ready_store_against_a_verifying_file_is_a_divergence():
+    """The shape that actually offers shipped work as startable."""
+    assert any("verifying" in p for p in _pair("ready", "verifying"))
+
+
+def test_agreement_on_verifying_is_not_a_divergence():
+    """It must not cry wolf on the normal case."""
+    assert _pair("verifying", "verifying") == []
+
+
+def test_a_done_verifying_pair_is_reported_once():
+    """One disagreement, one line.
+
+    db=`verifying` / files=`done` is the commonest real case — a session marked
+    an item done in the checkout and the store has not caught up. Reporting it
+    under both the `done` and the `verifying` heading would make one problem
+    read as two.
+    """
+    problems = _pair("verifying", "done")
+    assert len(problems) == 1, problems
+    assert "done" in problems[0]
+
+
+def test_neither_status_underivable_is_still_quiet():
+    """`claimed` vs `ready` is derived from the claim, not stored — comparing it
+    would fire on every item whose claim the two sources already agree on."""
+    assert _pair("claimed", "ready", db_claim="claude/x", file_claim="claude/x") == []

roadmap_core-0.3.2/tests/test_pull_projects_status.py

@@ -0,0 +1,195 @@
+"""`pull` must carry the statuses the graph cannot derive — and only add them.
+
+`derive_status` names four facts the edges cannot produce: ``done``,
+``verifying``, an active claim and a deferral. `pull` carried two of them (the
+claim and ``done``); ``verifying`` post-dates it and was never added. So a
+checkout could read ``ready`` for work that had already shipped, and `pull`
+would print "the files already match the store" while `diff` — the assertion
+the sync workflow is built on — reported the divergence in the same second.
+
+The second half of this file is the harder half, and it is why the projection
+is DELIBERATELY ONE-DIRECTIONAL. The store's silence about ``verifying`` is
+IGNORANCE, NOT DENIAL: the backend honors ``status`` on INSERT and ignores it
+on UPDATE, so a file's ``verifying`` has no path into the store at all. A
+symmetric "the store wins" projection would therefore erase every such mark.
+
+Measured in Lucille from the two committed artifacts, 2026-09-17: ONE item
+where the store holds the underivable status and the file does not (which this
+fix heals), against SEVENTEEN where the file holds it and the store does not —
+eight of them sitting at store-status ``ready``. Projecting the store over the
+files would have deleted seventeen records and put eight shipped items back on
+the startable queue, which is the exact harm this item was filed about,
+manufactured by its own fix.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+pytest.importorskip("yaml", reason="pull reads and writes roadmap/items/*.yaml")
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[1]
+
+ITEM = """\
+id: first-thing
+title: Try the roadmap in a project that is not Lucille
+status: ready
+evidence: |
+  Adopting should take a checkout and nothing else.
+"""
+
+
+@pytest.fixture
+def project(tmp_path):
+    root = tmp_path / "myproject"
+    (root / "roadmap" / "items").mkdir(parents=True)
+    (root / "roadmap" / "items" / "first-thing.yaml").write_text(ITEM)
+    return root
+
+
+def run(cwd: Path, *args: str) -> subprocess.CompletedProcess:
+    env = dict(os.environ)
+    env["PYTHONPATH"] = str(PACKAGE_ROOT)
+    env["ROADMAP_SOURCE"] = "local"
+    env.pop("LUCILLE_ADMIN_JWT", None)
+    env.pop("BACKEND_URL", None)
+    return subprocess.run(
+        [sys.executable, "-m", "roadmap_core.cli", *args],
+        cwd=cwd, env=env, capture_output=True, text=True, timeout=60,
+    )
+
+
+def status_in_file(project: Path, key: str = "first-thing") -> str | None:
+    for line in (project / "roadmap" / "items" / f"{key}.yaml").read_text().splitlines():
+        if line.startswith("status:"):
+            return line.split(":", 1)[1].strip()
+    return None
+
+
+def set_status_in_file(project: Path, value: str, key: str = "first-thing") -> None:
+    path = project / "roadmap" / "items" / f"{key}.yaml"
+    path.write_text(
+        "\n".join(
+            f"status: {value}" if line.startswith("status:") else line
+            for line in path.read_text().splitlines()
+        )
+        + "\n"
+    )
+
+
+# --- the defect ---------------------------------------------------------------
+
+
+def test_pull_projects_verifying_from_the_store_onto_the_file(project):
+    """The whole item. A store that knows an item is `verifying` must be able to
+    tell a checkout, or every tokenless session — which is how dispatch runs BY
+    DESIGN — reads `ready` for work that shipped days ago."""
+    assert run(project, "push").returncode == 0
+    assert run(project, "status", "first-thing", "verifying").returncode == 0
+
+    # `status` writes the file as well as the store, so undo that half: this is
+    # the state a checkout reaches whenever the store moved and the file did not
+    # — an item set `verifying` from another session, or straight against the API.
+    set_status_in_file(project, "ready")
+    assert status_in_file(project) == "ready"
+
+    pulled = run(project, "pull")
+    assert pulled.returncode == 0, pulled.stderr
+    assert status_in_file(project) == "verifying", (
+        "the store holds `verifying`, the file still reads `ready`, and `pull` — "
+        "the command whose entire job is to bring the store's reality back into "
+        f"the checkout — left it there:\n{pulled.stdout}{pulled.stderr}"
+    )
+
+
+def test_pull_does_not_claim_agreement_that_diff_denies(project):
+    """`pull` and `diff` are two halves of one workflow: roadmap-sync runs `pull`
+    to heal, then `diff` to assert the heal worked. When `pull` prints "the files
+    already match the store" and `diff` reports a divergence on the same two
+    sources seconds later, one of them is lying and the workflow is red forever
+    with no automatic remedy."""
+    assert run(project, "push").returncode == 0
+    assert run(project, "status", "first-thing", "verifying").returncode == 0
+    set_status_in_file(project, "ready")
+
+    pulled = run(project, "pull")
+    diffed = run(project, "diff")
+
+    assert not (
+        "already match the store" in pulled.stdout and diffed.returncode == 1
+    ), (
+        "`pull` asserted the files already match the store, and `diff` "
+        "immediately reported a real divergence:\n"
+        f"pull : {pulled.stdout.strip()}\n"
+        f"diff : {diffed.stdout.strip()}"
+    )
+
+
+# --- the direction it must NOT go ---------------------------------------------
+
+
+def test_pull_does_not_erase_a_verifying_the_store_never_heard_of(project):
+    """THE GUARD ON THE FIX, and the reason it is one-directional.
+
+    The backend honors `status` on INSERT and ignores it on UPDATE, so a file's
+    `verifying` cannot reach an existing item in the store — the store's `ready`
+    is ignorance, not a denial. Projecting it back over the file would delete the
+    only record that the work shipped, and hand the item to the next session as
+    startable. In Lucille that is 17 items, 8 of them store-`ready`."""
+    assert run(project, "push").returncode == 0
+    set_status_in_file(project, "verifying")
+
+    pulled = run(project, "pull")
+    assert pulled.returncode == 0, pulled.stderr
+    assert status_in_file(project) == "verifying", (
+        "`pull` overwrote a file's `verifying` with the store's `ready`. The "
+        "store cannot be TOLD about `verifying` (honored on INSERT, ignored on "
+        "UPDATE), so this deletes the record and re-offers shipped work:\n"
+        f"{pulled.stdout}{pulled.stderr}"
+    )
+
+
+def test_pull_does_not_downgrade_a_done_file_to_verifying(project):
+    """Same rule one step further along. `done` is more settled than `verifying`;
+    a store that has only heard `verifying` must not walk a file's `done` back."""
+    assert run(project, "push").returncode == 0
+    assert run(project, "status", "first-thing", "verifying").returncode == 0
+    set_status_in_file(project, "done")
+
+    pulled = run(project, "pull")
+    assert pulled.returncode == 0, pulled.stderr
+    assert status_in_file(project) == "done", (
+        f"`pull` walked a `done` back to `verifying`:\n{pulled.stdout}{pulled.stderr}"
+    )
+
+
+def test_pull_still_projects_done(project):
+    """The behaviour that already existed, asserted so the generalisation cannot
+    quietly drop it."""
+    assert run(project, "push").returncode == 0
+    assert run(project, "status", "first-thing", "done").returncode == 0
+    set_status_in_file(project, "ready")
+
+    pulled = run(project, "pull")
+    assert pulled.returncode == 0, pulled.stderr
+    assert status_in_file(project) == "done", pulled.stdout + pulled.stderr
+
+
+def test_pull_says_which_status_it_projected(project):
+    """A repair that leaves no trace hides the next regression exactly as this one
+    hid itself. `updated <file>` alone does not say a status moved, so the one
+    line a reader gets must name the transition."""
+    assert run(project, "push").returncode == 0
+    assert run(project, "status", "first-thing", "verifying").returncode == 0
+    set_status_in_file(project, "ready")
+
+    pulled = run(project, "pull")
+    assert "ready -> verifying" in pulled.stdout, (
+        "`pull` healed a status and reported only that the file was updated:\n"
+        f"{pulled.stdout}"
+    )

roadmap_core-0.3.2/tests/test_renderers.py

@@ -0,0 +1,358 @@
+"""What the rendered surfaces say about an item's status — and what `prune`
+refuses to destroy on the way out.
+
+These three assertions exist because of one incident, on 2026-09-14, in the
+repository that consumes this package. A session ran `roadmap list`, read a line
+reading `now  engine-topic-id-populate  Populate topic_id on engine rows`, and
+dispatched a worker session to do the work. The item had shipped weeks earlier.
+~150k tokens went into re-fixing it.
+
+Nothing was broken in the graph: `derive_status` returned `done`, the band header
+said `DONE (18)`, and the committed `ROADMAP.md` listed it under Items with
+`- **status:** done`. The defect was entirely in the *rendering* — status lived
+somewhere the reader's eye and every mechanical reader (a grep, a truncated read,
+a line pasted into a dispatch message) did not have to pass through.
+
+So these are tests of rendered output, asserted as strings, which is normally a
+smell. Here it is the point: the thing that failed was the string. A test of
+`derive_status` would have been green throughout.
+
+Synthetic fixtures only, per the rule the rest of the suite follows — no
+committed `roadmap/items/`, no YAML, no store, nothing from any consumer.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+import pytest
+
+from roadmap_core import cli, graph
+
+
+def _item(key: str, **over):
+    base = {"key": key, "title": f"Title of {key}", "status": "ready",
+            "blocked_on": [], "evidence": "x"}
+    base.update(over)
+    return base
+
+
+# --- 1. `roadmap list`: status on the row, not only in the band header -------
+
+
+@pytest.fixture
+def listed(monkeypatch, capsys):
+    """Run `cmd_list` over a fixture and hand back its stdout lines."""
+
+    def run(by_key):
+        monkeypatch.setattr(cli, "load", lambda source: by_key)
+        monkeypatch.setattr(cli, "_offline_notice", lambda args: None)
+        monkeypatch.setattr(cli, "_stale_claim_notice", lambda by_key: None)
+        capsys.readouterr()
+        cli.cmd_list(argparse.Namespace(source="files", json=False))
+        return capsys.readouterr().out.splitlines()
+
+    return run
+
+
+def _row_for(lines: list[str], key: str) -> str:
+    """The one output row for ``key``.
+
+    Matched on the title rather than the key, because a key also appears in
+    *another* item's row as the `← <dep>` blocked-on suffix.
+    """
+    rows = [ln for ln in lines if f"Title of {key}" in ln]
+    assert len(rows) == 1, f"expected exactly one row for {key}, got {rows}"
+    return rows[0]
+
+
+def test_a_list_row_states_its_own_status(listed):
+    """THE INCIDENT, as an assertion.
+
+    The row for a done item must carry the word `done`. Band headers are read
+    once and scrolled past; this line has to survive being read alone, because
+    that is how it reached the session that acted on it.
+    """
+    shipped = _item("shipped", status="done", priority="now")
+    lines = listed({"shipped": shipped})
+    assert "done" in _row_for(lines, "shipped")
+
+
+def test_a_done_row_is_not_confusable_with_the_top_of_the_queue(listed):
+    """The specific collision: a `done` item and a `now` item rendered the same.
+
+    10 of the consumer's 18 done items carried a `now`/`next` priority, so they
+    rendered as `now  <key>  <present-tense defect title>` — the exact shape of
+    the highest-priority startable work. Strip the keys and titles, which differ
+    for unrelated reasons, and what is left must still differ.
+    """
+    by_key = {
+        "shipped": _item("shipped", status="done", priority="now"),
+        "startable": _item("startable", priority="now"),
+    }
+    lines = listed(by_key)
+    done_row = _row_for(lines, "shipped")
+    ready_row = _row_for(lines, "startable")
+
+    def shape(row: str, key: str) -> str:
+        return row.replace(key, "").replace(f"Title of {key}", "")
+
+    assert shape(done_row, "shipped") != shape(ready_row, "startable"), (
+        "a done row and a top-priority ready row are distinguishable only by "
+        "their key and title — which is what let a session act on a finished "
+        "item"
+    )
+
+
+def test_every_row_carries_a_status_not_only_the_finished_ones(listed):
+    """A marker that appears conditionally makes ABSENCE carry meaning.
+
+    That is the bug's own shape: an unmarked line read as open work. So the
+    token is on every row, for every status the graph can derive.
+    """
+    by_key = {
+        "ready-one": _item("ready-one"),
+        "deferred-one": _item("deferred-one", defer_reason="too early"),
+        "blocked-one": _item("blocked-one", blocked_on=["ready-one"]),
+        "claimed-one": _item("claimed-one", claimed_by="claude/x"),
+        "verifying-one": _item("verifying-one", status="verifying"),
+        "done-one": _item("done-one", status="done"),
+    }
+    lines = listed(by_key)
+    for key in by_key:
+        statename = graph.derive_status(by_key[key], by_key)
+        assert statename in _row_for(lines, key), (
+            f"the row for {key} does not state its status ({statename})"
+        )
+
+
+def test_the_status_column_is_wide_enough_for_every_status():
+    """`STATUS_WIDTH` is derived, so a longer status added later cannot silently
+    unalign every surface that prints one."""
+    for statename in graph.STATUSES:
+        assert len(statename) <= graph.STATUS_WIDTH
+
+
+# --- 2. the mermaid graph: a node states its own status ----------------------
+
+
+def _mermaid(by_key) -> list[str]:
+    block = graph.render_markdown(by_key).split("```mermaid")[1].split("```")[0]
+    return [ln.strip() for ln in block.splitlines() if ln.strip()]
+
+
+def _node_line(lines: list[str], key: str) -> str:
+    node = key.replace("-", "_")
+    rows = [ln for ln in lines if ln.startswith(f"{node}[")]
+    assert len(rows) == 1, f"expected one node line for {key}, got {rows}"
+    return rows[0]
+
+
+def test_a_done_node_is_not_drawn_like_an_open_one():
+    """Before this, all 82 nodes of the consumer's committed graph rendered
+    identically whether `ready` or `done` — in the one artifact a session reads
+    to decide what to pick up."""
+    by_key = {
+        "shipped": _item("shipped", status="done"),
+        "startable": _item("startable"),
+    }
+    lines = _mermaid(by_key)
+    done_line = _node_line(lines, "shipped")
+    ready_line = _node_line(lines, "startable")
+
+    def shape(line: str, key: str) -> str:
+        return line.replace(key.replace("-", "_"), "").replace(f"Title of {key}", "")
+
+    assert shape(done_line, "shipped") != shape(ready_line, "startable")
+    assert "done" in done_line, "the done node's own line does not say so"
+
+
+def test_every_node_line_carries_its_derived_status():
+    """On the node's own line, so a grep or a one-line quote keeps it — the same
+    property `cmd_list` needs, for the same reason."""
+    by_key = {
+        "ready-one": _item("ready-one"),
+        "deferred-one": _item("deferred-one", defer_reason="too early"),
+        "blocked-one": _item("blocked-one", blocked_on=["ready-one"]),
+        "claimed-one": _item("claimed-one", claimed_by="claude/x"),
+        "verifying-one": _item("verifying-one", status="verifying"),
+        "done-one": _item("done-one", status="done"),
+    }
+    lines = _mermaid(by_key)
+    for key in by_key:
+        statename = graph.derive_status(by_key[key], by_key)
+        assert _node_line(lines, key).endswith(f":::{statename}"), (
+            f"the node line for {key} does not carry its status"
+        )
+
+
+def test_the_status_marking_is_readable_in_the_picture_too():
+    """`:::done` serves whoever reads the source. The rendered diagram needs its
+    own marker, because a stroke colour is a distinction a reader can miss and a
+    glyph in the label is not."""
+    lines = _mermaid({"shipped": _item("shipped", status="done")})
+    assert "✓" in _node_line(lines, "shipped")
+
+
+def test_every_status_has_a_style():
+    """An unstyled node renders as the default, which reads as open — the same
+    failure with a new status name on it."""
+    lines = _mermaid({"a": _item("a")})
+    for statename in graph.STATUSES:
+        assert any(ln.startswith(f"classDef {statename} ") for ln in lines), (
+            f"no classDef for {statename}"
+        )
+
+
+def test_status_marking_adds_no_clock_and_no_graph_wide_aggregate():
+    """``render_markdown``'s standing constraint, checked against the thing just
+    added to it.
+
+    The file is regenerated wholesale and committed, so any line derived from a
+    total differs between two branches that finished different items and
+    conflicts on merge while saying nothing about what either changed. That is
+    why the classes are attached PER NODE and the `classDef` lines are constant,
+    rather than a single `class a,b,c done` roll-up — which would have been
+    exactly that aggregate.
+
+    Asserted by rendering two graphs that differ by one added item and checking
+    that no line about styling moved.
+    """
+    base = {
+        "one": _item("one", status="done"),
+        "two": _item("two"),
+    }
+    grown = dict(base, three=_item("three", status="done"))
+
+    def styling_lines(by_key):
+        return [ln for ln in _mermaid(by_key) if ln.startswith(("classDef ", "class "))]
+
+    assert styling_lines(base) == styling_lines(grown), (
+        "a styling line changed when an unrelated item was added — that line is "
+        "a graph-wide aggregate and will conflict between branches"
+    )
+    # And nothing anywhere in the block is a roll-up naming several nodes.
+    assert not [ln for ln in _mermaid(base) if ln.startswith("class ")], (
+        "a `class a,b,... done` roll-up is a single line that every branch "
+        "finishing an item has to edit"
+    )
+
+
+# --- 3. `prune` withholds the ticket edge ------------------------------------
+
+
+@pytest.fixture
+def pruner(monkeypatch, capsys):
+    """Run `cmd_prune` over a fixture, with everything that touches a store, a
+    checkout or the network stubbed out. Returns (deleted keys, stdout, stderr).
+    """
+
+    def run(files, *, yes=True, include_ticket_linked=False):
+        deleted: list[str] = []
+        monkeypatch.setattr(cli, "prune_staleness_blockers", lambda: [])
+        monkeypatch.setattr(cli, "load_from_files", lambda: {k: dict(v) for k, v in files.items()})
+        monkeypatch.setattr(cli, "load_from_db", dict)
+        monkeypatch.setattr(cli, "_api_delete_tolerant", lambda key: deleted.append(key) or "ok")
+        monkeypatch.setattr(cli, "item_path", lambda key: _MissingPath())
+        monkeypatch.setattr(cli, "_release_dependents", lambda pruned: None)
+        capsys.readouterr()
+        cli.cmd_prune(argparse.Namespace(
+            yes=yes, allow_stale=False, include_ticket_linked=include_ticket_linked
+        ))
+        captured = capsys.readouterr()
+        return deleted, captured.out, captured.err
+
+    return run
+
+
+class _MissingPath:
+    """Stands in for an item file that is not on disk, so the prune never
+    unlinks anything real."""
+
+    def exists(self) -> bool:
+        return False
+
+
+def test_prune_withholds_an_item_that_carries_ticket_links(pruner):
+    """The ticket edge has ONE writer and no second copy.
+
+    It is the only record of the link from shipped work back to the person who
+    reported it — `impact` reads it to ask whether anyone is still complaining,
+    and the consumer's lifecycle walks it the other way to tell that person the
+    thing they reported is handled. Hygiene loses to evidence: the done pile is
+    cosmetic, this is not recoverable.
+    """
+    deleted, out, err = pruner({
+        "plain": _item("plain", status="done"),
+        "reported": _item("reported", status="done",
+                          tickets=["6f1b0f6e-0000-4000-8000-000000000001"]),
+    })
+    assert deleted == ["plain"]
+    assert "reported" not in deleted
+
+
+def test_the_withholding_is_loud_and_says_it_is_conservative(pruner):
+    """A silent skip is how an operator ends up believing the pile was cleared.
+
+    It must also admit WHY it withheld: this package cannot see ticket status —
+    that lives in the consuming application — so it cannot tell a loop that is
+    still open from one already closed, and holds both. Saying so is what keeps
+    the gap from reading as the rule.
+    """
+    _, _, err = pruner({
+        "reported": _item("reported", status="done",
+                          tickets=["6f1b0f6e-0000-4000-8000-000000000001"]),
+    })
+    assert "reported" in err
+    assert "6f1b0f6e-0000-4000-8000-000000000001" in err, "name the tickets, not just a count"
+    assert "--include-ticket-linked" in err, "an operator needs the way past it"
+    assert "cannot see ticket status" in err, (
+        "the skip must state that it is broader than the rule it implements, or "
+        "the gap reads as the rule"
+    )
+
+
+def test_the_operator_can_override_once_they_have_checked(pruner):
+    """The judgement this code cannot make, a human can. Withholding forever
+    would rebuild the done pile `prune` exists to clear."""
+    deleted, _, err = pruner(
+        {"reported": _item("reported", status="done",
+                           tickets=["6f1b0f6e-0000-4000-8000-000000000001"])},
+        include_ticket_linked=True,
+    )
+    assert deleted == ["reported"]
+    assert "reported" in err, "destroying the edge deliberately is still worth saying out loud"
+
+
+def test_an_empty_tickets_list_is_not_a_link(pruner):
+    """The predicate is "is this edge load-bearing", and a field somebody emptied
+    carries no edge. Treating `[]` as a link would withhold every item a schema
+    default touched."""
+    deleted, _, _ = pruner({"empty": _item("empty", status="done", tickets=[])})
+    assert deleted == ["empty"]
+
+
+def test_nothing_left_to_prune_reports_why(pruner):
+    """`no done items — nothing to prune` would be a lie when there are done
+    items and all of them were withheld."""
+    deleted, out, _ = pruner({
+        "reported": _item("reported", status="done",
+                          tickets=["6f1b0f6e-0000-4000-8000-000000000001"]),
+    })
+    assert deleted == []
+    assert "withheld" in out
+
+
+def test_a_withheld_item_is_absent_from_the_dry_run_too(pruner):
+    """The dry run is what an operator reads before passing `--yes`. Listing an
+    item there that the real run will not touch teaches them to distrust it."""
+    _, out, _ = pruner(
+        {
+            "plain": _item("plain", status="done"),
+            "reported": _item("reported", status="done",
+                              tickets=["6f1b0f6e-0000-4000-8000-000000000001"]),
+        },
+        yes=False,
+    )
+    assert "plain" in out
+    assert "reported" not in out