tcw-cli 2.1.1__tar.gz → 2.1.2__tar.gz

{tcw_cli-2.1.1 → tcw_cli-2.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tcw-cli
-Version: 2.1.1
+Version: 2.1.2
 Summary: Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project.
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -229,6 +229,28 @@ They link by one-directional pointers — a capability names the taxonomy terms
 involves, a work item names the capability it changes — and never copy each
 other's content.
 
+## Contents
+
+- [The problem](#the-problem)
+- [What it looks like](#what-it-looks-like)
+- [Why many repositories is the case it is built for](#why-many-repositories-is-the-case-it-is-built-for)
+- [What it deliberately refuses](#what-it-deliberately-refuses)
+- [What adopting it costs](#what-adopting-it-costs)
+- [Who it's for](#who-its-for)
+- [Storage abstraction (the prime directive)](#storage-abstraction-the-prime-directive)
+- [Install](#install)
+  - [As a plugin (recommended)](#as-a-plugin-recommended)
+  - [As a Python package](#as-a-python-package)
+  - [In a cloud environment](#in-a-cloud-environment)
+- [Quickstart](#quickstart)
+- [Working from your Jira tickets](#working-from-your-jira-tickets)
+- [Documentation](#documentation)
+- [Skills — the judgment layer](#skills--the-judgment-layer)
+  - [Reading a lifecycle stage](#reading-a-lifecycle-stage)
+  - [Review agents and slash commands](#review-agents-and-slash-commands)
+- [Status](#status)
+- [Further reading](#further-reading)
+
 ---
 
 ## The problem
@@ -548,15 +570,17 @@ studies your code, proposes a first draft, refines it with you, and writes it.
 
 ---
 
-## Reading your Jira tickets
+## Working from your Jira tickets
 
-A project can name the Jira Cloud site it uses, and then read from it. Both
-commands are read-only: nothing here changes a ticket, and nothing yet turns a
-ticket into a work item.
+A project can name the Jira Cloud site it uses, read its tickets, and take one as
+a work item.
 
 ```sh
 tcw work tracker list              # tickets the configured query selects
 tcw work tracker show ENG-482      # one ticket, and whether it is yours to take
+tcw work tracker import ENG-482    # take the ticket and get a work item for it
+tcw work tracker link <slug> ENG-482       # take it for an item you already have
+tcw work tracker unlink <slug> --reason "wrong ticket"
 ```
 
 Configuration goes in the node's `tcw-config.yaml`:
@@ -594,6 +618,23 @@ reports `not determined`, because it cannot show you what happens to the second
 person. Making a workflow exclusive is a Jira administration change, not something
 TCW can do for you.
 
+**Taking a ticket.** `tracker import` moves the ticket through your configured
+claim transition, assigns it to you if nobody had it, and then checks Jira again:
+only when the ticket really is started and yours does it create a backlog item. The
+ticket's text goes into the item as its raw input, with a link back, and the item's
+request still gets written the usual way. A ticket assigned to someone else is
+refused, and so is one that is already closed.
+
+Running `import` again for the same ticket gives you the same item rather than a
+second one, and if the first run took the ticket but stopped before creating the
+item, the second run finishes the job. One ticket can deliberately become several
+items with `--part api`, `--part web`, and so on. `unlink` removes a wrong binding
+and keeps a record of it with your reason; it never changes the ticket in Jira.
+
+Two limits to know. On a workflow that lets anyone start a ticket from any status,
+two people can both take the same ticket, and TCW does not stop that. And two runs
+by the same Jira account at the same moment can both create an item.
+
 Two guarantees worth stating plainly. A project with no `tracker` block behaves
 exactly as before, with no new required setting and no network access. And
 `tcw validate` never contacts the tracker, which matters because projects commonly

{tcw_cli-2.1.1 → tcw_cli-2.1.2}/README.md

@@ -13,6 +13,28 @@ They link by one-directional pointers — a capability names the taxonomy terms
 involves, a work item names the capability it changes — and never copy each
 other's content.
 
+## Contents
+
+- [The problem](#the-problem)
+- [What it looks like](#what-it-looks-like)
+- [Why many repositories is the case it is built for](#why-many-repositories-is-the-case-it-is-built-for)
+- [What it deliberately refuses](#what-it-deliberately-refuses)
+- [What adopting it costs](#what-adopting-it-costs)
+- [Who it's for](#who-its-for)
+- [Storage abstraction (the prime directive)](#storage-abstraction-the-prime-directive)
+- [Install](#install)
+  - [As a plugin (recommended)](#as-a-plugin-recommended)
+  - [As a Python package](#as-a-python-package)
+  - [In a cloud environment](#in-a-cloud-environment)
+- [Quickstart](#quickstart)
+- [Working from your Jira tickets](#working-from-your-jira-tickets)
+- [Documentation](#documentation)
+- [Skills — the judgment layer](#skills--the-judgment-layer)
+  - [Reading a lifecycle stage](#reading-a-lifecycle-stage)
+  - [Review agents and slash commands](#review-agents-and-slash-commands)
+- [Status](#status)
+- [Further reading](#further-reading)
+
 ---
 
 ## The problem
@@ -332,15 +354,17 @@ studies your code, proposes a first draft, refines it with you, and writes it.
 
 ---
 
-## Reading your Jira tickets
+## Working from your Jira tickets
 
-A project can name the Jira Cloud site it uses, and then read from it. Both
-commands are read-only: nothing here changes a ticket, and nothing yet turns a
-ticket into a work item.
+A project can name the Jira Cloud site it uses, read its tickets, and take one as
+a work item.
 
 ```sh
 tcw work tracker list              # tickets the configured query selects
 tcw work tracker show ENG-482      # one ticket, and whether it is yours to take
+tcw work tracker import ENG-482    # take the ticket and get a work item for it
+tcw work tracker link <slug> ENG-482       # take it for an item you already have
+tcw work tracker unlink <slug> --reason "wrong ticket"
 ```
 
 Configuration goes in the node's `tcw-config.yaml`:
@@ -378,6 +402,23 @@ reports `not determined`, because it cannot show you what happens to the second
 person. Making a workflow exclusive is a Jira administration change, not something
 TCW can do for you.
 
+**Taking a ticket.** `tracker import` moves the ticket through your configured
+claim transition, assigns it to you if nobody had it, and then checks Jira again:
+only when the ticket really is started and yours does it create a backlog item. The
+ticket's text goes into the item as its raw input, with a link back, and the item's
+request still gets written the usual way. A ticket assigned to someone else is
+refused, and so is one that is already closed.
+
+Running `import` again for the same ticket gives you the same item rather than a
+second one, and if the first run took the ticket but stopped before creating the
+item, the second run finishes the job. One ticket can deliberately become several
+items with `--part api`, `--part web`, and so on. `unlink` removes a wrong binding
+and keeps a record of it with your reason; it never changes the ticket in Jira.
+
+Two limits to know. On a workflow that lets anyone start a ticket from any status,
+two people can both take the same ticket, and TCW does not stop that. And two runs
+by the same Jira account at the same moment can both create an item.
+
 Two guarantees worth stating plainly. A project with no `tracker` block behaves
 exactly as before, with no new required setting and no network access. And
 `tcw validate` never contacts the tracker, which matters because projects commonly

{tcw_cli-2.1.1 → tcw_cli-2.1.2}/pyproject.toml

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

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

{tcw_cli-2.1.1 → tcw_cli-2.1.2}/tcw/capabilities/cli.py

@@ -9,7 +9,8 @@ from tcw.store.base import AmbiguousRef
 from tcw.store.fs import FsCapabilitiesStore, find_node, git_root
 
 NAME = "capabilities"
-SUBCOMMANDS = {"init", "list", "show", "path", "add", "search", "check", "set", "reset", "extends", "drift"}
+SUBCOMMANDS = {"init", "list", "show", "path", "add", "search", "check", "set", "reset", "rm",
+               "extends", "drift"}
 DEFAULT_SUBCOMMAND = "show"  # `tcw capabilities <path>` == `tcw capabilities show <path>`
 
 
@@ -129,6 +130,19 @@ def _reset(args: argparse.Namespace) -> int:
     return 0
 
 
+def _rm(args: argparse.Namespace) -> int:
+    st = _store()
+    if st is None:
+        return 1
+    try:
+        st.remove(args.id)
+    except (ValueError, RefError) as e:              # AmbiguousRef carries its own message
+        print(f"tcw capabilities rm: {e}", file=sys.stderr)
+        return 1
+    print(f"Removed capability {args.id}")
+    return 0
+
+
 def _search(args: argparse.Namespace) -> int:
     st = _store()
     if st is None:
@@ -294,6 +308,10 @@ def add_subparser(sub: argparse._SubParsersAction) -> None:
     prst.add_argument("id", metavar="path")
     prst.set_defaults(func=_reset)
 
+    prm = g.add_parser("rm", help="remove a local capability")
+    prm.add_argument("id", metavar="path")
+    prm.set_defaults(func=_rm)
+
     pse = g.add_parser("search", help="search names + bodies")
     pse.add_argument("query")
     pse.set_defaults(func=_search)

{tcw_cli-2.1.1 → tcw_cli-2.1.2}/tcw/store/base.py

@@ -287,24 +287,27 @@ class ProjectRegistry(ABC):
 
 def declared_capabilities(capabilities: Any) -> dict[str, list[str]]:
     """Canonical read of a work item's ``capabilities.yaml`` into
-    ``{"new": [...], "changed": [...]}`` — the work→capability back-pointers the
-    DoD gate enforces.
+    ``{"new": [...], "changed": [...], "removed": [...]}`` — the work→capability
+    back-pointers the DoD gate enforces.
 
     ``capabilities`` is the already-parsed sidecar object (``WorkItem.capabilities``):
-    a mapping with ``new:``/``changed:`` lists of canonical ``namespace/path``
-    strings. ``added:`` is accepted as a deprecated alias of ``new:``. A trailing
+    a mapping with ``new:``/``changed:``/``removed:`` lists of canonical
+    ``namespace/path`` strings. ``removed:`` names capabilities the item deleted,
+    which cannot sit under ``changed:`` because they no longer resolve.
+    ``added:`` is accepted as a deprecated alias of ``new:``. A trailing
     `` # comment`` on a value is stripped (YAML strips it already; belt and
     suspenders). The reconcile list-form sidecar and any other shape declare
     nothing here. The ``_tcw_parse_error`` sentinel the FS adapter produces on bad
     YAML raises ``SidecarError`` so the gate fails closed rather than reading
     "no deltas".
     """
-    out: dict[str, list[str]] = {"new": [], "changed": []}
+    out: dict[str, list[str]] = {"new": [], "changed": [], "removed": []}
     if not capabilities or not isinstance(capabilities, dict):
         return out
     if "_tcw_parse_error" in capabilities:
         raise SidecarError(str(capabilities["_tcw_parse_error"]))
-    for key, bucket in (("new", "new"), ("added", "new"), ("changed", "changed")):
+    for key, bucket in (("new", "new"), ("added", "new"), ("changed", "changed"),
+                        ("removed", "removed")):
         vals = capabilities.get(key)
         if vals is None:
             continue
@@ -564,13 +567,27 @@ class CapabilitiesStore(ABC):
 
     @abstractmethod
     def remove(self, identifier: str) -> None:
-        ...
+        """Delete the local capability at `identifier`, writing nothing when
+        refused. Raise `AmbiguousRef` when a bare ref matches multiple extended
+        stores, and `ValueError` when:
+
+        - nothing resolves;
+        - the capability is inherited, overridden locally or not (an override
+          is dropped with `reset`, never with `remove`);
+        - another capability or override is nested under its path;
+        - another local capability or override still references it through
+          `Superseded by`, `Blocked by`, `Roles` or `When`.
+
+        Refusing rather than cascading is the contract: a delete never takes a
+        second capability with it or leaves a reference pointing at nothing.
+        Never mutates an extended store."""
 
     @abstractmethod
     def reset(self, identifier: str) -> None:
         """Drop the local override at `identifier`, re-inheriting the upstream
         capability verbatim. Raise `ValueError` when there is no override (a
-        standalone local capability is not an override — use `remove`; a bare
+        standalone local capability is not an override — the `remove` operation,
+        driven by `tcw capabilities rm`, deletes it; a bare
         inherited path has nothing to drop), or `AmbiguousRef` when a bare ref
         matches multiple extended stores. Never mutates an extended store."""
 
@@ -1940,6 +1957,16 @@ WORK_SIDECARS: dict[str, dict[str, str]] = {
         "media_type": "text/markdown",
         "generated": "yes",
     },
+    # The binding between an item and the tracker ticket it answers. Written by
+    # `tcw work tracker import | link | unlink`, never by hand, so it is
+    # `generated` like `rollup.md` and edit surfaces must not offer to write it.
+    # Nothing treats it as proof that a claim was made: every command that acts on
+    # a binding re-reads the ticket from the tracker.
+    "tracker.yaml": {
+        "media_type": "application/yaml",
+        "validation": "yaml_mapping",
+        "generated": "yes",
+    },
 }
 
 # Taxonomy term fields that the abstract ``update_term`` operation may modify.

{tcw_cli-2.1.1 → tcw_cli-2.1.2}/tcw/store/fs.py

@@ -565,7 +565,10 @@ def git_stage(node_root: Path, *paths: Path) -> None:
 
 def git_rm(node_root: Path, path: Path) -> None:
     # -f so a term staged-but-not-yet-committed (just `add`ed) can still be removed.
-    _git(["git", "-C", str(node_root), "rm", "-rfq", "--", str(path)], check=True)
+    # --literal-pathspecs: `--` ends options but a path is still a glob to git, so
+    # removing a folder named `a*` would also delete `abc`.
+    _git(["git", "-C", str(node_root), "--literal-pathspecs", "rm", "-rfq", "--", str(path)],
+         check=True)
 
 
 NOT_A_REPOSITORY = "not inside a git repository. Run `git init` first."
@@ -1077,8 +1080,13 @@ _UniqueKeyLoader.add_constructor(
 #: the Definition-of-Done gate reads, and the list form `reconcile` writes — so
 #: holding it to one of them would report a sound file, and worse, make that
 #: gate fail closed on it. See `declared_capabilities` in `tcw/store/base.py`.
+#:
+#: `tracker.yaml`, an item's binding to a tracker ticket, has one shape — a mapping,
+#: which `write_sidecar` already enforces — so it is held to the contract like
+#: `state.yaml`.
 OWNED_YAML_NAMES = frozenset({
     "state.yaml", "meta.yaml", "graveyard.yaml", "config.yaml", ".config.yaml",
+    "tracker.yaml",
 })
 
 
@@ -2480,18 +2488,84 @@ class FsCapabilitiesStore(FsTreeStore, _FederationCycles, CapabilitiesStore):
 
     def remove(self, identifier: str) -> None:
         cap = self.get(identifier)
+        # The exact listed spelling only. `get` resolves `routes/`, `./routes`,
+        # or `Routes` on a case-insensitive disk, to the `routes` folder but
+        # echoes the spelling back as the path, so everything below that works
+        # from the path would be working from the wrong one.
+        if cap is not None and cap.origin == "local" and cap.path not in self._local_paths():
+            cap = None
         if cap is None:
             raise ValueError(f"no such capability: {identifier}")
         if cap.origin != "local":
             raise ValueError(f"cannot remove inherited capability '{cap.qualified}' "
-                             f"(edit it at its source)")
-        self._rm(self.root / cap.path)
+                             f"(edit it at its source; to drop a local override use "
+                             f"`tcw capabilities reset`)")
+        d = self.root / cap.path
+        # Refused, never cascaded: `_rm` deletes the whole folder. Asked of the
+        # folder itself rather than `_all_meta_dirs`, which skips dot-directories
+        # and unreadable nodes that `git rm -rf` would delete all the same.
+        nested = sorted(str(m.parent.relative_to(self.root))
+                        for m in d.rglob("meta.yaml") if m.parent != d)
+        if nested:
+            raise ValueError(f"cannot remove '{cap.path}': nested under it: "
+                             f"{', '.join(nested)} (remove those first)")
+        referrers = self._referrers(d)
+        if referrers:
+            raise ValueError(f"cannot remove '{cap.path}': still referenced by "
+                             f"{', '.join(referrers)} (repoint or clear those fields first)")
+        self._rm(d)
+
+    def _referrers(self, target: Path) -> list[str]:
+        """`<folder> (<field>)` for every other local capability or override whose
+        reference fields resolve to the local capability folder `target`.
+
+        Each field is read exactly as `check` reads it (`_ref_problems`,
+        `_check_globals`), so this refuses on precisely the references `check`
+        would report as dangling afterwards. A hit is compared by folder identity,
+        not spelling: `a/b/`, `x/../a/b` and a differently-cased `A/B` all
+        resolve, and `set` accepts each.
+        """
+        def tokens(field: str, raw) -> list[str]:
+            if field in ("Superseded by", "Blocked by"):
+                return [str(raw)]
+            ns = "roles" if field == "Roles" else "conditions"
+            toks = raw if isinstance(raw, list) else str(raw).split(",")
+            refs = [str(s).strip().lstrip("!") for s in toks if str(s).strip()]
+            return [r for r in refs if r.startswith(f"{ns}/")]
+
+        def same(a: Path) -> bool:
+            try:
+                return a.samefile(target)
+            # Gone since it was listed or resolved: not the target. Only that —
+            # any other error leaves the question open, so it propagates and
+            # the delete stops.
+            except FileNotFoundError:
+                return False
+
+        out = []
+        for p in self._all_meta_dirs():
+            folder = self.root / p
+            if same(folder):
+                continue
+            meta = load_yaml(folder / "meta.yaml")
+            for field in ("Superseded by", "Blocked by", "Roles", "When"):
+                if field not in meta:
+                    continue
+                for ref in tokens(field, meta[field]):
+                    try:
+                        hit = self.get(ref)
+                    except RefError:
+                        continue
+                    if hit is not None and hit.origin == "local" and same(self.root / hit.path):
+                        out.append(f"{p} ({field})")
+                        break
+        return out
 
     def reset(self, identifier: str) -> None:
         # A standalone local capability is not an override — `remove` deletes it.
         if self.get_local(identifier) is not None:
             raise ValueError(f"'{identifier}' is a local capability, not an override "
-                             f"(use `remove` to delete it)")
+                             f"(use `tcw capabilities rm` to delete it)")
         cap = self.get(identifier)                     # federated; may raise AmbiguousRef
         if cap is None:
             raise ValueError(f"no such capability: {identifier}")

{tcw_cli-2.1.1 → tcw_cli-2.1.2}/tcw/tracker/claim.py

@@ -127,8 +127,10 @@ def assess(claim_transition: str, *, current_status: str, offered,
             exclusivity=NOT_DETERMINED,
             verdict=OK,
             landing_status=landing,
-            detail=(f"{matches[0].name!r} leads to {landing!r}. Exclusivity can only "
-                    f"be read from a ticket already in that status."),
+            detail=(f"{matches[0].name!r} leads to {landing!r}. A ticket already in "
+                    f"that status can show a workflow that is not exclusive, but never "
+                    f"one that is. That is confirmed only when a claim is made, or "
+                    f"from the workflow definition."),
         )
 
     # The claim is not offered. Two very different situations.
@@ -164,8 +166,9 @@ def assess(claim_transition: str, *, current_status: str, offered,
             detail=(f"work.tracker.transitions.claim is {claim_transition!r}, which "
                     f"this ticket does not offer. It offers: "
                     f"{', '.join(repr(n) for n in offered_names)}. Either the name "
-                    f"is wrong, or this ticket is past the point where it applies — "
-                    f"one ticket cannot tell those apart."),
+                    f"is wrong, or this ticket is not at the point where it applies — "
+                    f"it has not reached it yet, or is already past it. One ticket "
+                    f"cannot tell those apart."),
         )
 
     # No transitions at all: a resolved ticket, or one this account cannot move.