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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tcw-cli
-Version: 2.6.3
+Version: 2.6.5
 Summary: Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project.
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -1102,8 +1102,11 @@ that an agent read them. Running it starts real agent sessions and costs money;
 ### Releasing
 
 `python scripts/cut_version.py <patch|minor|major|X.Y.Z>` bumps the version in all
-five files that carry it, turns the `upcoming.md` changelog and release notes into
-that version's files, commits and tags. Pushing the tag publishes the release to
+five files that carry it, combines the waiting changelog and release-note entries
+into that version's files, commits and tags. Each change adds its entries as its
+own file in `docs/changelogs/upcoming/` and `docs/release-notes/upcoming/`, named
+after its work item, so changes finished on separate branches never edit the same
+file. Pushing the tag publishes the release to
 PyPI. Details, including the one-time PyPI setup, are in
 [`docs/releasing.md`](docs/releasing.md).
 

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

@@ -886,8 +886,11 @@ that an agent read them. Running it starts real agent sessions and costs money;
 ### Releasing
 
 `python scripts/cut_version.py <patch|minor|major|X.Y.Z>` bumps the version in all
-five files that carry it, turns the `upcoming.md` changelog and release notes into
-that version's files, commits and tags. Pushing the tag publishes the release to
+five files that carry it, combines the waiting changelog and release-note entries
+into that version's files, commits and tags. Each change adds its entries as its
+own file in `docs/changelogs/upcoming/` and `docs/release-notes/upcoming/`, named
+after its work item, so changes finished on separate branches never edit the same
+file. Pushing the tag publishes the release to
 PyPI. Details, including the one-time PyPI setup, are in
 [`docs/releasing.md`](docs/releasing.md).
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tcw-cli"
-version = "2.6.3"
+version = "2.6.5"
 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.6.5/tcw/__init__.py

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

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

@@ -406,6 +406,8 @@ def _cmd_validate(args: argparse.Namespace) -> int:
     for override in registry.overrides():
         print(f"connected project '{override.id}' is overridden by "
               f"{override.source} to {override.locator}", file=sys.stderr)
+        if override.warning:
+            print(f"  warning: {override.warning}", file=sys.stderr)
     registry_problems = registry.check()
     if registry_problems:
         for problem in registry_problems:

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

@@ -236,7 +236,7 @@ def _strict_refuses(work, action: str, slug: str = "", body: dict | None = None)
             or work.get(slug)) if slug else None
     epic = (body.get("type") == "epic") if action == "create" else (
         item is not None and item.type == "epic")
-    from tcw.tracker.intake import ever_bound
+    from tcw.tracker.intake import drop_refusal
     lead = "refused under strict tracker mode, which the web app cannot check; "
     if action == "create" and not epic:
         return lead + "create work from a ticket with `tcw work tracker import <ticket>`."
@@ -245,9 +245,8 @@ def _strict_refuses(work, action: str, slug: str = "", body: dict | None = None)
         return lead + f"use `tcw work start {slug}{take_over}`, which claims the ticket."
     if action == "complete" and not epic and body.get("resolution") == "done":
         return lead + f"use `tcw work complete {slug}`, which checks the ticket."
-    if action == "drop" and ever_bound(work, slug):
-        return lead + (f"{slug} is, or was, bound to a ticket. Discard it instead: "
-                       f"`tcw work complete {slug} --resolution wontfix --confirm`.")
+    if action == "drop" and (refusal := drop_refusal(work, slug)):
+        return lead + refusal
     return None
 
 
@@ -635,6 +634,12 @@ class TcwHandler(BaseHTTPRequestHandler):
                 return
             try:
                 resource = work.read_artifact(slug, name)
+            except UnicodeDecodeError:
+                # Before ValueError, which it is: the decoder's own message names
+                # a byte offset, not the file.
+                self._send(HTTPStatus.BAD_REQUEST,
+                           f"{name} is not valid UTF-8; fix or replace the file".encode("utf-8"))
+                return
             except ValueError as e:
                 self._send(HTTPStatus.BAD_REQUEST, str(e).encode("utf-8"))
                 return
@@ -806,6 +811,15 @@ class TcwHandler(BaseHTTPRequestHandler):
                         })
                     else:
                         artifacts_list.append({"name": name, "present": False})
+                except UnicodeDecodeError:
+                    # Not valid UTF-8: listed with the snapshot's revision, so a
+                    # guarded save can replace it; opening it names the file.
+                    artifacts_list.append({
+                        "name": name,
+                        "present": name in lifecycle_present,
+                        "revision": detail.artifact_revisions.get(name, ""),
+                        "mediaType": "text/markdown",
+                    })
                 except ValueError:
                     pass
             # Sidecar discovery in detail

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

@@ -182,6 +182,10 @@ class ProjectOverride:
     source: str
     locator: Any
     problem: str | None = None
+    # It worked, and still may not be what was meant: set when the project it
+    # delivered disagrees with where the rest of the graph was read from. Never
+    # a problem, and never fatal — the override is followed as stated.
+    warning: str | None = None
 
 
 class ProjectRegistry(ABC):
@@ -3774,6 +3778,13 @@ class WorkStore(ABC):
         Returns the written ``SidecarResource`` with a fresh revision.
         """
 
+    def qualify_initiative(self, value: str) -> str:
+        """`value` as it should be stored: `<project-id>/<slug>` when the epic
+        lives in another project, so the reference cannot be taken by a
+        same-named epic nearer the item. A store that holds one project's items
+        only has nothing to qualify."""
+        return value
+
     def initiative_epic(self, item: WorkItem) -> WorkItem | None:
         """Resolve `item`'s initiative epic, if any.
 
@@ -3861,6 +3872,41 @@ class WorkStore(ABC):
         filesystem store does, and overrides this."""
         return [(item, False) for item in self.query()]
 
+    def unreadable_open_items(self) -> list[tuple[str, str]]:
+        """`(slug, reason)` for every open item whose recorded fields this store
+        cannot read. Such an item still lists, but without its `parent` or
+        `initiative`, so the gates that stop an item resolving over open work
+        cannot tell whether it belongs beneath one. A store that never holds a
+        record it cannot read has none."""
+        return []
+
+    def unreadable_slice_candidates(self) -> list[tuple[str, str]]:
+        """`(label, reason)` for every open item, wherever this store's epics
+        draw slices from, whose fields cannot be read. Local only by default;
+        a store that finds slices in other nodes also looks there."""
+        return self.unreadable_open_items()
+
+    def require_readable_slices(self, slug: str) -> None:
+        """Refuse to close epic `slug` while an open item where its slices live
+        cannot be read — it may be one of them. The epic's own damage is left
+        to the move, whose refusal names it plainly."""
+        found = [f for f in self.unreadable_slice_candidates() if f[0] != slug]
+        if found:
+            raise self._unreadable_refusal("complete epic", slug,
+                                           "its initiative children", found)
+
+    def _unreadable_others(self, slug: str) -> list[tuple[str, str]]:
+        return [f for f in self.unreadable_open_items() if f[0] != slug]
+
+    @staticmethod
+    def _unreadable_refusal(verb: str, slug: str, what: str,
+                            found: list[tuple[str, str]]) -> ValueError:
+        named = ", ".join(f"{label} ({reason})" for label, reason in found)
+        return ValueError(f"Cannot {verb} {slug}: the state of these open items "
+                          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.")
+
     def independent_descendants(self, slug: str) -> list[WorkItem]:
         """Every item beneath `slug` — the whole subtree, not only direct
         children — that has a status of its own, open or resolved.
@@ -3917,10 +3963,24 @@ class WorkStore(ABC):
         """A blocker entry: a ref to an item this store holds or once held →
         {slug}, else {external}. A resolved item already reduced to its
         tombstone is still this store's item; recording it as external text
-        would make it block forever."""
+        would make it block forever.
+
+        So is a ref that names one of this store's items another way — as
+        `<status>/<slug>`, or qualified with this node's own project id. Left as
+        text, it escaped the self-block and cycle checks, which compare slugs,
+        and a reference to the item itself blocked it forever."""
         ref = self._normalize_ref(ref)
-        known = self.get(ref) is not None or self.tombstone(ref) is not None
-        return {"slug": ref} if known else {"external": ref}
+        for candidate in (ref, *self._local_forms(ref)):
+            if self.get(candidate) is not None or self.tombstone(candidate) is not None:
+                return {"slug": candidate}
+        return {"external": ref}
+
+    def _local_forms(self, ref: str) -> list[str]:
+        """Bare slugs `ref` may name in this store besides itself. `<status>/<slug>`
+        is model vocabulary every store shares; a store that knows its own
+        project id adds `<own-id>/<slug>`."""
+        status, sep, rest = ref.partition("/")
+        return [rest] if sep and status in WORK_STATUSES and rest and "/" not in rest else []
 
     @staticmethod
     def _same_entry(a: dict, b: dict) -> bool:
@@ -3931,6 +3991,13 @@ class WorkStore(ABC):
             return a["external"] == b["external"]
         return False
 
+    def _same_item(self, entry: dict, e: dict) -> bool:
+        """`_same_entry`, or `e` is text stored before this store read it as
+        `entry`'s item — `<status>/<slug>`, say. Re-adding that item must not
+        keep both, and the text form may block forever."""
+        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`.
@@ -3968,7 +4035,8 @@ class WorkStore(ABC):
         self._check_new_blocker(slug, entry, ref)
         if any(self._same_entry(entry, e) for e in item.blocked_by):
             return                                       # idempotent
-        self.set_field(slug, "blocked_by", item.blocked_by + [entry])
+        kept = [e for e in item.blocked_by if not self._same_item(entry, e)]
+        self.set_field(slug, "blocked_by", kept + [entry])
 
     def check_blocker_edits(self, slug: str, *, add: list[str] = (),
                             remove: list[str] = (), blocks: list[str] = ()) -> None:
@@ -3990,7 +4058,7 @@ class WorkStore(ABC):
             entry = self._entry_for(ref)
             self._check_new_blocker(slug, entry, ref)
             if not any(self._same_entry(entry, e) for e in proposed):
-                proposed.append(entry)
+                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:
@@ -4012,8 +4080,11 @@ class WorkStore(ABC):
     def _without(self, entries: list[dict], slug: str, ref: str) -> list[dict]:
         """`entries` less the blocker `ref` names; refuses a ref that names none."""
         norm = self._normalize_ref(ref)
+        # The forms `_entry_for` records as a slug remove it too: removing with
+        # the text that added it has to work.
+        slugs = {norm, *self._local_forms(norm)}
         kept = [e for e in entries
-                if e.get("slug") != norm and e.get("external") != norm]
+                if e.get("slug") not in slugs and e.get("external") != norm]
         if len(kept) == len(entries) and norm.endswith(")"):
             # A label copied from `list` may carry the reason it still blocks,
             # "external: <text> (<why>)"; the stored text has no reason, and the
@@ -4230,6 +4301,13 @@ class WorkStore(ABC):
                  force: bool = False) -> WorkItem:
         dest = resolution_status(resolution)          # raises on a bad resolution
         item = self._require(slug)
+        # Before the backlog shortcut is decided, since it reads the same slices:
+        # a slice whose state cannot be read has lost its `initiative`, so both
+        # would pass over it. Forceable, like the partial-graph refusal below —
+        # both say "cannot verify", not "something is open" — though a damaged
+        # item on this board still stops it at the unforceable parent gate.
+        if item.type == "epic" and not force:
+            self.require_readable_slices(slug)
         # A completable epic (all children resolved) may close straight from
         # `backlog` — coordinator epics never needed their own start/active. This
         # is a scoped exception, not a global `(backlog, completed)` transition,
@@ -4311,6 +4389,11 @@ class WorkStore(ABC):
         beneath = self.independent_descendants(slug)
         if beneath:
             raise ValueError(drop_refused_over_children(slug, beneath))
+        # A damaged item may name this one as its parent without it showing —
+        # and a drop leaves no record for it to name. Dropping the damaged item
+        # itself stays open, as a way out.
+        if (unreadable := self._unreadable_others(slug)):
+            raise self._unreadable_refusal("drop", slug, "beneath it", unreadable)
         self._delete(slug)
 
     def _require_live_parent(self, parent: str, *, moving: str | None = None,
@@ -4341,6 +4424,8 @@ class WorkStore(ABC):
         """Refuse when any item beneath `slug` is still open. Shared by `complete`
         and by callers that must refuse before doing anything irreversible of
         their own, such as merging a worktree branch."""
+        if (unreadable := self._unreadable_others(slug)):
+            raise self._unreadable_refusal(verb, slug, "beneath it", unreadable)
         still_open = self.open_descendants(slug)
         if still_open:
             raise ValueError(f"Cannot {verb} {slug}; these items beneath it are "