tcw-cli 2.6.5__tar.gz → 2.7.0__tar.gz

{tcw_cli-2.6.5 → tcw_cli-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tcw-cli
-Version: 2.6.5
+Version: 2.7.0
 Summary: Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project.
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -476,7 +476,10 @@ agent through. See [Skills and Agents](#skills-and-agents).
 
 **Many repositories, one model.** Projects are identified by ID, never by path.
 A project can connect to others, inherit their taxonomy and capabilities, and
-address their work items as `<project-id>/<slug>`. A checkout holding only some of
+address their work items as `<project-id>/<slug>`. A connection is normally
+declared by both projects; an `upstream` one is declared only by the reader and
+is read-only from its side, so a private project can read a public one that never
+names it. A checkout holding only some of
 the connected repositories still works: the absent ones drop out rather than
 breaking your commands. See [Working across repositories](docs/guide/multi-repo.md).
 
@@ -907,7 +910,7 @@ driving it to completion, verifying it, processing the inbox) described in
 | Command              | What it does                                                      |
 | -------------------- | ----------------------------------------------------------------- |
 | `tcw work inbox`     | `inbox list`, `inbox show` and `inbox accept` raw requests, and Jira tickets awaiting triage |
-| `tcw work nodes`     | lists this project's parent and child projects                    |
+| `tcw work nodes`     | lists this project's parent, child and upstream projects          |
 | `tcw work delegate`  | writes a request into the nearest child project with a board      |
 | `tcw work escalate`  | writes a request into the parent project's inbox                  |
 | `tcw work reconcile` | reads every project below with a board; writes the epic's roll-up |

{tcw_cli-2.6.5 → tcw_cli-2.7.0}/README.md

@@ -260,7 +260,10 @@ agent through. See [Skills and Agents](#skills-and-agents).
 
 **Many repositories, one model.** Projects are identified by ID, never by path.
 A project can connect to others, inherit their taxonomy and capabilities, and
-address their work items as `<project-id>/<slug>`. A checkout holding only some of
+address their work items as `<project-id>/<slug>`. A connection is normally
+declared by both projects; an `upstream` one is declared only by the reader and
+is read-only from its side, so a private project can read a public one that never
+names it. A checkout holding only some of
 the connected repositories still works: the absent ones drop out rather than
 breaking your commands. See [Working across repositories](docs/guide/multi-repo.md).
 
@@ -691,7 +694,7 @@ driving it to completion, verifying it, processing the inbox) described in
 | Command              | What it does                                                      |
 | -------------------- | ----------------------------------------------------------------- |
 | `tcw work inbox`     | `inbox list`, `inbox show` and `inbox accept` raw requests, and Jira tickets awaiting triage |
-| `tcw work nodes`     | lists this project's parent and child projects                    |
+| `tcw work nodes`     | lists this project's parent, child and upstream projects          |
 | `tcw work delegate`  | writes a request into the nearest child project with a board      |
 | `tcw work escalate`  | writes a request into the parent project's inbox                  |
 | `tcw work reconcile` | reads every project below with a board; writes the epic's roll-up |

{tcw_cli-2.6.5 → tcw_cli-2.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tcw-cli"
-version = "2.6.5"
+version = "2.7.0"
 description = "Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project."
 readme = "README.md"
 requires-python = ">=3.11"

tcw_cli-2.7.0/tcw/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.7.0"

{tcw_cli-2.6.5 → tcw_cli-2.7.0}/tcw/cli.py

@@ -210,12 +210,14 @@ def _declared_nodes_in_graph(
         # Every project the registry holds, not `ancestors + descendants`. That
         # triple omits a sibling and a sibling of an ancestor — the shapes a
         # workspace is actually made of — so a declaration living on one was
-        # never read, and the repository it named never obtained.
-        roots += [Path(project.locator) for project in
-                  FsProjectRegistry.open(root).projects()]
+        # never read, and the repository it named never obtained. Except an
+        # upstream: what it connects to is its own to obtain, not its readers'.
+        registry = FsProjectRegistry.open(root)
+        roots += [Path(project.locator) for project in registry.projects()
+                  if registry.read_only_reason(project.id) is None]
     except Exception:
         pass
-    found: list[tuple[Path, str, object]] = []
+    found: list[tuple[Path, str, object, str]] = []
     problems: list[str] = []
     for candidate in roots:
         candidate = candidate.resolve()
@@ -224,7 +226,7 @@ def _declared_nodes_in_graph(
         seen.add(candidate)
         declared, candidate_problems = declared_connected_projects(candidate)
         problems += [f"{candidate / SENTINEL}: {p}" for p in candidate_problems]
-        found += [(candidate, pid, d) for pid, d in declared]
+        found += [(candidate, pid, d, relation) for pid, d, relation in declared]
     return found, problems
 
 
@@ -250,7 +252,7 @@ def _provision_nodes(node_root: Path, *, refresh: bool, dry_run: bool) -> bool:
 
     failed = False
     seen: set[Path] = set()
-    queue: list[tuple[Path, str, object]] = []
+    queue: list[tuple[Path, str, object, str]] = []
     # "A project that is already here always wins" is the rule the whole feature
     # rests on, and the walk is the one place it was not applied: a declaration
     # is written by whichever node knows about that edge, so an ancestor
@@ -298,8 +300,14 @@ def _provision_nodes(node_root: Path, *, refresh: bool, dry_run: bool) -> bool:
             return None
         return located if located != target.resolve() else None
 
-    def enqueue(root: Path) -> None:
+    def enqueue(root: Path, relation: str = "children") -> None:
         nonlocal failed
+        if relation == "upstream":
+            # Obtained so it can be read; its own connections are not followed,
+            # as the registry does not follow them. A reader must never fetch a
+            # project named only by something it reads — a public upstream can
+            # still name the private repository it is migrating away from.
+            return
         found, problems = _declared_nodes_in_graph(root, enqueued)
         for problem in problems:
             print(f"tcw provision: {problem}", file=sys.stderr)
@@ -314,7 +322,7 @@ def _provision_nodes(node_root: Path, *, refresh: bool, dry_run: bool) -> bool:
     enqueued: set[Path] = set()
     enqueue(node_root)
     while queue:
-        source, project_id, declaration = queue.pop(0)
+        source, project_id, declaration, relation = queue.pop(0)
         target = provisioned_store_root(source, declaration)
         if target in seen:
             continue
@@ -335,13 +343,13 @@ def _provision_nodes(node_root: Path, *, refresh: bool, dry_run: bool) -> bool:
             # provisioning precisely when an earlier one was already in place.
             print(f"  {project_id}: already available")
             have.add(project_id)
-            enqueue(present)
+            enqueue(present, relation)
             continue
         provisioner = FsStoreProvisioner(source, NODE_TARGET, declaration)
         if provisioner.is_available() and not refresh:
             print(f"  {project_id}: already available at {target}")
             have.add(project_id)
-            enqueue(target)
+            enqueue(target, relation)
             continue
         print(f"→ {project_id}: {provisioner.describe().split(': ', 1)[1]}")
         try:
@@ -363,7 +371,7 @@ def _provision_nodes(node_root: Path, *, refresh: bool, dry_run: bool) -> bool:
         # routine when a parent and a grandparent both name it — report
         # "already available" in a run that fetched nothing.
         have.add(project_id)
-        enqueue(target)
+        enqueue(target, relation)
     return failed
 
 
@@ -437,6 +445,8 @@ def _cmd_validate(args: argparse.Namespace) -> int:
         print(f"{entry.declared_in}: connected project '{entry.id}' is declared "
               f"at {entry.locator}, which is not in this checkout; it was found "
               f"at {registry.get(entry.id).locator}", file=sys.stderr)
+    for warning in registry.warnings():
+        print(f"warning: {warning}", file=sys.stderr)
     from tcw.validate import validate
     recurse = args.path is None and not args.no_recurse
     projects = [registry.current, *registry.descendants()] if recurse else [registry.current]

{tcw_cli-2.6.5 → tcw_cli-2.7.0}/tcw/serve/__init__.py

@@ -24,7 +24,8 @@ from tcw.store.base import (
 )
 from tcw.store.fs import (
     FsCapabilitiesStore, FsTaxonomyStore, FsWorkStore, descendant_nodes,
-    find_node_root, heading_slug, registered_project_id, resolve_qualified_work_ref,
+    find_node_root, heading_slug, registered_project_id, qualified_work_ref_read_only,
+    resolve_qualified_work_ref,
 )
 from tcw.refs import resolve_tcw_ref
 from tcw.validate import ValidationTarget, validate
@@ -507,6 +508,21 @@ class TcwHandler(BaseHTTPRequestHandler):
             return resolve_qualified_work_ref(self.server.node_root, slug)
         return FsWorkStore.open(self.server.node_root), slug
 
+    def _refused_read_only(self, slug: str) -> bool:
+        """Answer 403 and return True when `slug` names an item in a project this
+        node reads but may not write — an upstream project, or one reached only
+        through one. Every route that changes an item or runs its project's
+        scripts asks this first; reads do not, so the board can still show it."""
+        if not self.server.include_descendants:
+            return False
+        reason = qualified_work_ref_read_only(self.server.node_root, slug)
+        if reason is None:
+            return False
+        self._send_err(HTTPStatus.FORBIDDEN,
+                       f"{reason}; change it from that project itself",
+                       code="read-only-project")
+        return True
+
     def _hosted_projects(self) -> set[str]:
         """Project IDs whose items this server actually serves — the descendants it
         aggregates, or nothing when not aggregating.
@@ -993,6 +1009,8 @@ class TcwHandler(BaseHTTPRequestHandler):
             slug = _decode_path_param(m.group(1))
             action = _decode_path_param(m.group(2))
             qslug = slug                          # preserve the addressed (qualified) slug
+            if self._refused_read_only(slug):
+                return
             resolved = self._resolve_work(slug)
             if resolved is None:
                 self._send(HTTPStatus.NOT_FOUND, b"no such work item")
@@ -1216,6 +1234,8 @@ class TcwHandler(BaseHTTPRequestHandler):
         if m:
             slug = _decode_path_param(m.group(1))
             qslug = slug                          # preserve the addressed (qualified) slug
+            if self._refused_read_only(slug):
+                return
             resolved = self._resolve_work(slug)
             if resolved is None:
                 self._send(HTTPStatus.NOT_FOUND, b"no such work item")
@@ -1370,6 +1390,8 @@ class TcwHandler(BaseHTTPRequestHandler):
             if name not in WORK_ARTIFACTS:
                 self._send(HTTPStatus.BAD_REQUEST, b"unknown artifact")
                 return
+            if self._refused_read_only(slug):
+                return
             resolved = self._resolve_work(slug)
             if resolved is None:
                 self._send(HTTPStatus.NOT_FOUND, b"no such work item")
@@ -1408,6 +1430,8 @@ class TcwHandler(BaseHTTPRequestHandler):
         if m:
             slug = _decode_path_param(m.group(1))
             stage_id = _decode_path_param(m.group(2))
+            if self._refused_read_only(slug):
+                return
             resolved = self._resolve_work(slug)
             if resolved is None:
                 self._send(HTTPStatus.NOT_FOUND, b"no such work item")
@@ -1443,6 +1467,8 @@ class TcwHandler(BaseHTTPRequestHandler):
                                f"{name} is written by `{owner}`, not edited; "
                                f"run that command instead.")
                 return
+            if self._refused_read_only(slug):
+                return
             resolved = self._resolve_work(slug)
             if resolved is None:
                 self._send(HTTPStatus.NOT_FOUND, b"no such work item")
@@ -1498,6 +1524,8 @@ class TcwHandler(BaseHTTPRequestHandler):
         if m:
             slug = _decode_path_param(m.group(1))
             stage_id = _decode_path_param(m.group(2))
+            if self._refused_read_only(slug):
+                return
             resolved = self._resolve_work(slug)
             if resolved is None:
                 self._send(HTTPStatus.NOT_FOUND, b"no such work item")
@@ -1515,6 +1543,8 @@ class TcwHandler(BaseHTTPRequestHandler):
         m = re.match(r"^/api/work/([^/]+)$", path)
         if m:
             slug = _decode_path_param(m.group(1))
+            if self._refused_read_only(slug):
+                return
             resolved = self._resolve_work(slug)
             if resolved is None:
                 self._send(HTTPStatus.NOT_FOUND, b"no such work item")
@@ -1584,6 +1614,8 @@ class TcwHandler(BaseHTTPRequestHandler):
         slug_q, _, stage_q = middle.partition("/plan-stages/")
         slug = _decode_path_param(slug_q)
         stage_id = _decode_path_param(stage_q)
+        if self._refused_read_only(slug):
+            return
         resolved = self._resolve_work(slug)
         if resolved is None:
             self._send(HTTPStatus.NOT_FOUND, b"no such work item")

{tcw_cli-2.6.5 → tcw_cli-2.7.0}/tcw/store/base.py

@@ -21,7 +21,7 @@ from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 from datetime import date, datetime, timezone
 from pathlib import PurePosixPath
-from typing import Any
+from typing import Any, Collection
 from urllib.parse import quote
 
 
@@ -216,6 +216,35 @@ class ProjectRegistry(ABC):
         `declared_parent_id`."""
         return [child.id for child in self.children(project_id)]
 
+    def declared_upstream_ids(self, project_id: str | None = None) -> list[str]:
+        """The ids of the declared upstream projects, reachable or not.
+
+        An upstream is a project this one reads from — its taxonomy, its
+        capabilities, its work items by reference — and never writes to, and
+        which does not name this project back. It is neither parent nor child,
+        so no walk over those relations reaches it. A registry that keeps no
+        such relation has none."""
+        return []
+
+    def read_only_reason(self, project_id: str,
+                         from_id: str | None = None) -> str | None:
+        """Why `from_id` (default: the current project) may not write to
+        `project_id`, or None when it may.
+
+        **The one place the write rule lives.** A project is writable from a
+        node only when the node reaches it by `parent` and `children`
+        connections alone, each followed as declared by the project it starts
+        from. Anything else the graph holds was reached across an upstream
+        connection and is read-only there — however many nodes declare it, and
+        from whichever side of the family it is named. A registry with no
+        upstream relation has nothing read-only."""
+        return None
+
+    def warnings(self) -> list[str]:
+        """Graph facts worth saying that are neither defects nor unreachable
+        projects — printed by `tcw validate`, never fatal."""
+        return []
+
     def overrides(self) -> list["ProjectOverride"]:
         """The locators the caller supplied for this graph, in place of declared ones.
 
@@ -2314,6 +2343,67 @@ STAGE_NEXT_STEPS: dict[str, str] = {
 }
 
 
+# What a reader does after a transition, keyed by the command that printed it.
+# The transition-side sibling of `STAGE_NEXT_STEPS`, and navigation text for the
+# same reason: it names a stage, never a status edge, so no store answers for it.
+#
+# These drifted while they were four literals in the CLI with nothing reading
+# them: `start` sent readers to `tcw work complete`, skipping implement and
+# verify, and `submit` told them to delete a `refined-outcome.md` that verify had
+# not written yet.
+#
+# `start` has one entry per stage it can choose (`start_next_stage`), rather than
+# one template, so every entry is a complete sentence the tests can check. No
+# entry names `spec.md` or `plan.md`: `start`'s warning names those files when
+# they are missing, and its tests assert they are absent when they are not.
+TRANSITION_NEXT_STEPS: dict[str, str] = {
+    # `inbox accept` of a raw entry prints this too: both leave a backlog item
+    # holding at most its intake.
+    "new": "run `tcw work stage gate request <slug>`",
+    "start:spec": "run `tcw work stage gate spec <slug>`",
+    "start:plan": "run `tcw work stage gate plan <slug>`",
+    "start:implement": "run `tcw work stage gate implement <slug>`",
+    "start:verify": "run `tcw work stage gate verify <slug>`",
+    # Both endings, and no command for either: the verify stage's own footer
+    # names `complete` and `rework`, and repeating them here is how this line
+    # went stale before.
+    "submit": ("run `tcw work stage gate verify <slug>`; it ends in "
+               "refined-outcome.md to accept the work or rework.md to send it back"),
+    "rework": "address rework.md: run `tcw work stage gate implement <slug>`",
+}
+
+# The status an item is in when each hint prints — what the tests check a named
+# stage against. Nothing else reads it.
+TRANSITION_LANDS_IN: dict[str, str] = {
+    "new": "backlog",
+    "start:spec": "active",
+    "start:plan": "active",
+    "start:implement": "active",
+    "start:verify": "active",
+    "submit": "review",
+    "rework": "active",
+}
+
+
+def start_next_stage(present: Collection[str]) -> str:
+    """The stage to run after `start`, from the artifacts the item holds.
+
+    Not always `implement`. An item can be started before it is specified or
+    planned, and `start` also takes an item already `active` — with
+    `--take-over`, or when nobody holds it — which may already have an outcome.
+    The order is the `work` skill's "Finding your place", restricted to stages
+    legal in `active` (so never `request`), with a reworked item sent back to
+    `implement` as `rework`'s own hint does.
+    """
+    if "spec" not in present:
+        return "spec"
+    if "plan" not in present:
+        return "plan"
+    if "outcome" not in present or "rework" in present:
+        return "implement"
+    return "verify"
+
+
 def _parse_condition(raw: Any, where: str, problems: list[str]) -> "Condition | None":
     """Parse a `when:` mapping. Every shape is validated, not just `type`'s value.
 
@@ -3058,6 +3148,9 @@ class PublicationError(TransitionCommitError):
 
 
 
+_HELD_TWICE = "more than one folder holds this slug"
+
+
 class MultipleMatch(Exception):
     """A slug resolves to more than one item folder (slug integrity broken)."""
 
@@ -3900,12 +3993,14 @@ class WorkStore(ABC):
 
     @staticmethod
     def _unreadable_refusal(verb: str, slug: str, what: str,
-                            found: list[tuple[str, str]]) -> ValueError:
+                            found: list[tuple[str, str]], *,
+                            noun: str = "open items",
+                            remedy: str = "Fix or replace each state.yaml "
+                                          "(`tcw validate` lists them)") -> ValueError:
         named = ", ".join(f"{label} ({reason})" for label, reason in found)
-        return ValueError(f"Cannot {verb} {slug}: the state of these open items "
+        return ValueError(f"Cannot {verb} {slug}: the state of these {noun} "
                           f"cannot be read, so whether they are {what} is "
-                          f"unknown: {named}. Fix or replace each state.yaml "
-                          f"(`tcw validate` lists them) and retry.")
+                          f"unknown: {named}. {remedy} and retry.")
 
     def independent_descendants(self, slug: str) -> list[WorkItem]:
         """Every item beneath `slug` — the whole subtree, not only direct
@@ -3998,36 +4093,153 @@ class WorkStore(ABC):
         return self._same_entry(entry, e) or (
             "slug" in entry and "external" in e and self._entry_for(e["external"]) == entry)
 
-    def _reaches(self, start: str, target: str, *,
-                 settled: frozenset[str] = frozenset()) -> bool:
-        """True if `start` (transitively, via blocked_by slugs) depends on `target`.
+    def unreadable_reason(self, slug: str) -> str | None:
+        """Why this store holds item `slug` but cannot read its recorded fields,
+        or `None` — when they can be read, or there is no such item. A store that
+        never holds a record it cannot read has none."""
+        return None
 
-        `settled` items are not expanded: a caller that has already started the
-        walk from an item's *proposed* blockers passes it, so its stored ones —
-        which the edit is replacing — cannot be followed back in."""
-        seen: set[str] = set(settled)
+    def _item_label(self, store: "WorkStore", slug: str) -> str:
+        """How a message from this store names `store`'s item `slug`. The slug
+        here; a store that can address other projects qualifies theirs."""
+        return slug
+
+    def _store_key(self) -> object:
+        """What makes two opens of this store one store, for walks that cross
+        stores. The object itself here; an adapter that can open the same store
+        twice says what the two opens share."""
+        return id(self)
+
+    def _blocker_target(self, entry: dict) -> "tuple[WorkStore, str] | None":
+        """Where a stored blocker entry points, if at a work item — the same
+        entries `external_blocker_state` settles against one, and no others.
+
+        Here: a slug, and an `external` text shaped like a slug, which settles
+        against this store's item of that name — including one not created yet,
+        since a slug is predictable and creating it would close any cycle the
+        entry is part of. A missing item is a dead end for the walk, not an
+        error. A store that can address other projects extends this for
+        `<project-id>/<slug>`."""
+        if not isinstance(entry, dict):            # hand-edited data: not followed
+            return None
+        if "slug" in entry:
+            return self, entry["slug"]
+        text = str(entry.get("external") or "").strip()
+        if re.fullmatch(r"[a-z0-9][a-z0-9-]*", text):
+            return self, text
+        return None
+
+    def _reaches(self, start: "tuple[WorkStore, str]", target: str, *,
+                 settled: frozenset[str] = frozenset(),
+                 unreadable: "list[tuple[str, str]] | None" = None) -> bool:
+        """True if the item at `start` — a (store, slug) pair — depends,
+        transitively through its blockers, on this store's item `target`.
+
+        The walk follows every blocker `_blocker_target` resolves, into other
+        stores too, each item through its own store: a qualified blocker means
+        what it meant to the node that stored it. An item that cannot be read —
+        an interrupted claim, an ambiguous slug, in this store or another — is
+        not followed: the state of an item the edit does not name never fails
+        the edit by raising. Those whose blockers are unknown — a slug more than
+        one folder holds, or recorded fields the store cannot read — are
+        appended to `unreadable` as `(label, reason)`, for the caller to decide
+        on; an interrupted claim is not one of them.
+
+        `settled` items (slugs of this store) are not expanded: a caller that has
+        already started the walk from an item's *proposed* blockers passes it,
+        so its stored ones — which the edit is replacing — cannot be followed
+        back in."""
+        stores: dict[object, WorkStore] = {self._store_key(): self}
+        goal = (self._store_key(), target)
+        seen: set[tuple[object, str]] = {(self._store_key(), s) for s in settled}
         stack = [start]
         while stack:
-            cur = stack.pop()
-            if cur == target:
+            store, slug = stack.pop()
+            key = store._store_key()
+            store = stores.setdefault(key, store)     # first open of a store wins
+            node = (key, slug)
+            if node == goal:
                 return True
-            if cur in seen:
+            if node in seen:
+                continue
+            seen.add(node)
+            try:
+                item = store.get(slug)
+            except MultipleMatch:
+                if unreadable is not None:
+                    unreadable.append((self._item_label(store, slug), _HELD_TWICE))
+                continue
+            except Exception:
                 continue
-            seen.add(cur)
-            item = self.get(cur)
             if item is None:
                 continue
-            stack += [b["slug"] for b in item.blocked_by if "slug" in b]
+            if not item.blocked_by and unreadable is not None:
+                # Damage always reads as no blockers, so only these need asking.
+                try:
+                    reason = store.unreadable_reason(slug)
+                except Exception:
+                    reason = None
+                if reason:
+                    unreadable.append((self._item_label(store, slug), reason))
+            for entry in item.blocked_by:
+                try:
+                    found = store._blocker_target(entry)
+                except Exception:
+                    found = None
+                if found is not None:
+                    stack.append(found)
         return False
 
+    def _refuse_blocker_walks(self, walks: "list[tuple[tuple[WorkStore, str], str]]",
+                              target: str, *, settled: frozenset[str] = frozenset(),
+                              blockers: list[str]) -> None:
+        """Walk from each `(start, cycle message)` of `walks` towards this
+        store's `target`, then decide once: a cycle in any walk refuses with its
+        message; otherwise an item on any path whose blockers could not be read
+        refuses, naming each, because whether the edit closes a cycle is
+        unknown; otherwise accept. Deciding after every walk is what stops a
+        damaged path hiding a cycle through another."""
+        unreadable: list[tuple[str, str]] = []
+        for start, cycle in walks:
+            if self._reaches(start, target, settled=settled, unreadable=unreadable):
+                raise ValueError(cycle)
+        if not unreadable:
+            return
+        found = list(dict.fromkeys(unreadable))
+        remedies = []
+        if any(reason != _HELD_TWICE for _, reason in found):
+            remedies.append("Fix or replace each damaged state.yaml "
+                            "(`tcw validate` lists them)")
+        if any(reason == _HELD_TWICE for _, reason in found):
+            remedies.append("remove the extra folder of each slug held twice")
+        remedy = "; ".join(remedies)
+        many = len(blockers) > 1
+        raise self._unreadable_refusal(
+            f"add {', '.join(blockers)} as {'blockers' if many else 'a blocker'} of",
+            target, "part of a blocking cycle with this edit", found,
+            noun="items", remedy=remedy[0].upper() + remedy[1:])
+
     def _check_new_blocker(self, slug: str, entry: dict, ref: str) -> None:
-        """Refuse `entry` as a new blocker of `slug`: a self-block, or a cycle
-        through the blockers as stored. The one rule every blocker write uses."""
-        if "slug" in entry:
-            if entry["slug"] == slug:
+        self._check_new_blockers(slug, [(ref, entry)])
+
+    def _check_new_blockers(self, slug: str, new: "list[tuple[str, dict]]") -> None:
+        """Refuse `(ref, entry)` pairs as new blockers of `slug`, together: a
+        self-block, or a cycle through the blockers as stored — across stores
+        when an entry names an item in another one — or walks that cannot see
+        through an item on the way. The one rule every blocker write uses;
+        decided once for all of them, so one blocker's damaged path cannot
+        hide another's cycle."""
+        walks, refs = [], []
+        for ref, entry in new:
+            found = self._blocker_target(entry)
+            if found is None:
+                continue
+            store, target = found
+            if store._store_key() == self._store_key() and target == slug:
                 raise ValueError("an item cannot block itself")
-            if self._reaches(entry["slug"], slug):
-                raise ValueError(f"{ref} → {slug} would create a blocking cycle")
+            walks.append((found, f"{ref} → {slug} would create a blocking cycle"))
+            refs.append(ref)
+        self._refuse_blocker_walks(walks, slug, blockers=refs)
 
     def add_blocker(self, slug: str, ref: str) -> None:
         item = self._require(slug)
@@ -4054,18 +4266,19 @@ class WorkStore(ABC):
         proposed = list(item.blocked_by)
         for ref in remove:
             proposed = self._without(proposed, slug, ref)
-        for ref in add:
-            entry = self._entry_for(ref)
-            self._check_new_blocker(slug, entry, ref)
+        adding = [(ref, self._entry_for(ref)) for ref in add]
+        self._check_new_blockers(slug, adding)
+        for ref, entry in adding:
             if not any(self._same_entry(entry, e) for e in proposed):
                 proposed = [e for e in proposed if not self._same_item(entry, e)] + [entry]
         for ref in blocks:
             target = self._require(ref).slug
             if target == slug:
                 raise ValueError("an item cannot block itself")
-            if any(self._reaches(e["slug"], target, settled=frozenset({slug}))
-                   for e in proposed if "slug" in e):
-                raise ValueError(f"{slug} → {ref} would create a blocking cycle")
+            cycle = f"{slug} → {ref} would create a blocking cycle"
+            self._refuse_blocker_walks(
+                [(f, cycle) for f in map(self._blocker_target, proposed) if f is not None],
+                target, settled=frozenset({slug}), blockers=[slug])
 
     def remove_blocker(self, slug: str, ref: str) -> None:
         """Remove one blocker. Fails closed on a ref that matches nothing.