tcw-cli 2.5.1__tar.gz → 2.6.0__tar.gz

{tcw_cli-2.5.1/tcw_cli.egg-info → tcw_cli-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tcw-cli
-Version: 2.5.1
+Version: 2.6.0
 Summary: Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project.
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -731,10 +731,11 @@ to the transitions.
 | `request`, `spec`, `plan` stages        | unchanged                      | unchanged                                                                                                                                      |
 | at any time                             | —                              | `tcw work tracker link` / `unlink` records or removes the link between an existing item and a ticket; Jira itself is not touched               |
 | an item has no ticket                   | —                              | `tcw work tracker create <slug>` makes one for it and binds it; `--all` sweeps every open item without one. Needs `work.tracker.create` and `statuses.backlog`. With `create.on-new`, filing an item makes its ticket |
-| `start`                                 | moves the item                 | also claims a linked ticket, and posts a comment if `comments: true`                                                                           |
-| `submit`, `rework`, `complete`, discard | moves the item                 | also moves a linked ticket to the Jira status mapped under `statuses`, and posts a comment if `comments: true`                                 |
+| `start`                                 | moves the item                 | also claims a linked ticket (assigns it to you) and moves it to the status mapped for `active`; a ticket already past that stays where it is. Posts a comment if `comments: true` |
+| `submit`, `rework`                      | moves the item                 | refused before the item moves unless a linked ticket is assigned to you (`tcw work tracker claim` takes it). Then moves the ticket to the Jira status mapped under `statuses`, and posts a comment if `comments: true` |
+| `complete`, discard                     | moves the item                 | moves a linked ticket to its mapped status whoever holds it — finishing work needs no claim — and posts a comment if `comments: true`          |
 | the ticket could not follow             | —                              | the item still moves; the command exits 1 and records the ticket as pending or conflicting; `tcw work tracker sync` retries                    |
-| the ticket is behind its item           | —                              | with `tcw work tracker link --sync-status`, a ticket linked to work already under way is claimed and moved forward to where the item is      |
+| the ticket is behind its item           | —                              | for a ticket linked to work already under way: `tcw work tracker claim <slug>`, then `tcw work tracker sync <slug>`                          |
 | the ticket does not match its item      | —                              | `tcw work tracker sync <slug>` puts it where the item's status says, whether the ticket is ahead of the item or behind it; a backwards move says so |
 
 Setting `strict: true` changes several steps, so that no work happens without a
@@ -744,9 +745,17 @@ claimed ticket:
   and point you at `tcw work tracker import`. Where `inbox-query` is set, `inbox accept`
   of a ticket is allowed, because it claims the ticket.
 - `start` refuses an item with no ticket. For a linked item it claims the ticket
-  first, and moves the item only if the claim worked.
-- `submit`, `rework` and `complete --resolution done` read the ticket first, and
-  refuse unless it is assigned to you and where the item's last move left it.
+  first, through the transition `exclusive-claim-transition` names, and moves the
+  item only if the claim worked and the workflow would refuse a second person —
+  that is, it does not offer that transition again once the ticket has it. Every
+  strict claim checks this, `tracker claim` and `tracker import` included.
+- Strict mode needs `exclusive-claim-transition` and `transitions.start` set, and
+  `tcw validate` reports either one missing: `tracker import`, the way work is
+  created, claims through `transitions.start`.
+- `submit` and `rework` read the ticket first, and refuse unless it is assigned to
+  you and where the item's last move left it. `complete --resolution done` refuses
+  only if the ticket is not where the item's last move left it: who holds it does
+  not matter for finishing work.
 - Discarding is always allowed. `drop` refuses an item that was ever linked, so
   the record stays.
 - While Jira cannot be reached, those commands refuse, and `tcw serve` refuses

{tcw_cli-2.5.1 → tcw_cli-2.6.0}/README.md

@@ -515,10 +515,11 @@ to the transitions.
 | `request`, `spec`, `plan` stages        | unchanged                      | unchanged                                                                                                                                      |
 | at any time                             | —                              | `tcw work tracker link` / `unlink` records or removes the link between an existing item and a ticket; Jira itself is not touched               |
 | an item has no ticket                   | —                              | `tcw work tracker create <slug>` makes one for it and binds it; `--all` sweeps every open item without one. Needs `work.tracker.create` and `statuses.backlog`. With `create.on-new`, filing an item makes its ticket |
-| `start`                                 | moves the item                 | also claims a linked ticket, and posts a comment if `comments: true`                                                                           |
-| `submit`, `rework`, `complete`, discard | moves the item                 | also moves a linked ticket to the Jira status mapped under `statuses`, and posts a comment if `comments: true`                                 |
+| `start`                                 | moves the item                 | also claims a linked ticket (assigns it to you) and moves it to the status mapped for `active`; a ticket already past that stays where it is. Posts a comment if `comments: true` |
+| `submit`, `rework`                      | moves the item                 | refused before the item moves unless a linked ticket is assigned to you (`tcw work tracker claim` takes it). Then moves the ticket to the Jira status mapped under `statuses`, and posts a comment if `comments: true` |
+| `complete`, discard                     | moves the item                 | moves a linked ticket to its mapped status whoever holds it — finishing work needs no claim — and posts a comment if `comments: true`          |
 | the ticket could not follow             | —                              | the item still moves; the command exits 1 and records the ticket as pending or conflicting; `tcw work tracker sync` retries                    |
-| the ticket is behind its item           | —                              | with `tcw work tracker link --sync-status`, a ticket linked to work already under way is claimed and moved forward to where the item is      |
+| the ticket is behind its item           | —                              | for a ticket linked to work already under way: `tcw work tracker claim <slug>`, then `tcw work tracker sync <slug>`                          |
 | the ticket does not match its item      | —                              | `tcw work tracker sync <slug>` puts it where the item's status says, whether the ticket is ahead of the item or behind it; a backwards move says so |
 
 Setting `strict: true` changes several steps, so that no work happens without a
@@ -528,9 +529,17 @@ claimed ticket:
   and point you at `tcw work tracker import`. Where `inbox-query` is set, `inbox accept`
   of a ticket is allowed, because it claims the ticket.
 - `start` refuses an item with no ticket. For a linked item it claims the ticket
-  first, and moves the item only if the claim worked.
-- `submit`, `rework` and `complete --resolution done` read the ticket first, and
-  refuse unless it is assigned to you and where the item's last move left it.
+  first, through the transition `exclusive-claim-transition` names, and moves the
+  item only if the claim worked and the workflow would refuse a second person —
+  that is, it does not offer that transition again once the ticket has it. Every
+  strict claim checks this, `tracker claim` and `tracker import` included.
+- Strict mode needs `exclusive-claim-transition` and `transitions.start` set, and
+  `tcw validate` reports either one missing: `tracker import`, the way work is
+  created, claims through `transitions.start`.
+- `submit` and `rework` read the ticket first, and refuse unless it is assigned to
+  you and where the item's last move left it. `complete --resolution done` refuses
+  only if the ticket is not where the item's last move left it: who holds it does
+  not matter for finishing work.
 - Discarding is always allowed. `drop` refuses an item that was ever linked, so
   the record stays.
 - While Jira cannot be reached, those commands refuse, and `tcw serve` refuses

{tcw_cli-2.5.1 → tcw_cli-2.6.0}/pyproject.toml

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

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

{tcw_cli-2.5.1 → tcw_cli-2.6.0}/tcw/store/base.py

@@ -1259,11 +1259,11 @@ TRACKER_CREDENTIAL_KEYS = frozenset({"email-env", "token-env"})
 # These name *how* it gets there, and are needed only where the status cannot say: a
 # workflow offering two transitions into one status — a "finished" and an "abandoned"
 # route both landing in `Done` is the common shape — is otherwise unreachable, since
-# TCW will not guess which. A move with no name here keeps the status-derived rule.
-# `start` is the exception and is required: a start applies its transition through the
-# claim rather than through `assess_move`, so it has no status-derived rule to fall
-# back to. An unknown key is reported, because silently ignoring a key someone set is
-# silently not doing what they asked.
+# TCW will not guess which. A move with no name here keeps the status-derived rule, and
+# that now includes `start`: a start goes through `assess_move` like the other four, so
+# it derives its transition from the status it is heading for when nobody names one. An
+# unknown key is reported, because silently ignoring a key someone set is silently not
+# doing what they asked.
 TRACKER_TRANSITION_KEYS = frozenset({"start", "submit", "rework", "complete", "discard"})
 TRACKER_MOVE_TRANSITION_KEYS = ("start", "submit", "rework", "complete", "discard")
 # A key that used to exist, with what replaced it, so a config written for an older
@@ -1275,6 +1275,23 @@ TRACKER_RENAMED_KEYS = {
         "renamed to work.tracker.transitions.start, the transition the start move "
         "applies, alongside submit, rework, complete and discard",
 }
+# Strict mode promises that only one person can take a ticket. A claim that applies
+# this transition first keeps that promise, because a workflow that will not apply
+# it to a ticket already taken stops the second person there.
+STRICT_NEEDS_EXCLUSIVE_CLAIM = (
+    "work.tracker.exclusive-claim-transition: required when strict is true. Strict "
+    "mode promises that only one person can take a ticket, and this transition, "
+    "which your workflow will not apply to a ticket that has already been taken, "
+    "is what stops a second person. Name the transition that takes a ticket into "
+    "work.")
+# Strict mode creates work only from a ticket, and the two commands that do it claim
+# through this transition, so a strict project without it can create no work at all.
+STRICT_NEEDS_START_TRANSITION = (
+    "work.tracker.transitions.start: required when strict is true. Strict mode "
+    "creates work only from a ticket, and the two commands that do that — `tcw work "
+    "tracker import` and `tcw work inbox accept` — claim the ticket through this "
+    "transition. Name the transition that takes a ticket from the backlog status "
+    "into work.")
 # `backlog` first: it is where an item begins, and where creation puts its ticket.
 # The other four are the statuses a *bound* ticket is moved through afterwards.
 TRACKER_STATUS_KEYS = ("backlog", "active", "review", "completed", "discarded")
@@ -1431,7 +1448,13 @@ def parse_tracker_config(raw: Any) -> tuple["TrackerConfig | None", list[str]]:
         return value
 
     credentials = nested("credentials", TRACKER_CREDENTIAL_KEYS)
-    transitions = nested("transitions", TRACKER_TRANSITION_KEYS)
+    # Optional — every move derives its transition from the status when nobody names
+    # one — so a lone `null` is a wrong value rather than a missing required one, the
+    # shape `inbox-query` above and `exclusive-claim-transition` below both use.
+    if "transitions" in raw and raw["transitions"] is None:
+        problems.append("work.tracker.transitions: expected a mapping, got NoneType")
+    transitions = (nested("transitions", TRACKER_TRANSITION_KEYS)
+                   if raw.get("transitions") is not None else {})
 
     def nested_str(block: dict, key: str, path: str) -> str:
         value = block.get(key)
@@ -1453,8 +1476,10 @@ def parse_tracker_config(raw: Any) -> tuple["TrackerConfig | None", list[str]]:
                         f"got {type(strict).__name__}")
         strict = False
     if strict:
-        # Strict mode gates completing and discarding against these, so a missing
-        # one would be a gate that can never pass or never check.
+        # Strict mode gates completing and discarding against these statuses, so a
+        # missing one would be a gate that can never pass or never check. It also
+        # needs `exclusive-claim-transition`, the only thing that makes a claim
+        # exclusive; that check is after these.
         for key in ("active", "completed"):
             if not statuses.get(key):
                 problems.append(f"work.tracker.statuses.{key}: required when "
@@ -1466,6 +1491,10 @@ def parse_tracker_config(raw: Any) -> tuple["TrackerConfig | None", list[str]]:
             problems.append(f"work.tracker.statuses.discarded: required when strict "
                             f"is true, as one status or one for each of "
                             f"{', '.join(sorted(resolutions))}")
+        # Absent only: a key written as `null` or blank already has its own problem
+        # below, and one problem per key is enough.
+        if "exclusive-claim-transition" not in raw:
+            problems.append(STRICT_NEEDS_EXCLUSIVE_CLAIM)
 
     comments = raw.get("comments", False)
     if not isinstance(comments, bool):
@@ -1476,21 +1505,20 @@ def parse_tracker_config(raw: Any) -> tuple["TrackerConfig | None", list[str]]:
 
     email_env = nested_str(credentials, "email-env", "credentials.email-env")
     token_env = nested_str(credentials, "token-env", "credentials.token-env")
-    # Optional, so a lone `null` is a wrong value rather than a missing required one —
-    # the same shape `inbox-query` uses above.
+    # Optional unless strict (required above, only when the key is absent), so a lone
+    # `null` is a wrong value rather than a missing required one — the same shape
+    # `inbox-query` uses above.
     if "exclusive-claim-transition" in raw and raw["exclusive-claim-transition"] is None:
         problems.append("work.tracker.exclusive-claim-transition: expected a "
                         "non-empty string, got NoneType")
     exclusive_claim = (required_str("exclusive-claim-transition")
                        if raw.get("exclusive-claim-transition") is not None else "")
     move_transitions = _parse_tracker_transitions(transitions, problems)
-    # `start` is the one move whose transition is required: it is the only move with no
-    # status-derived fallback, because a start applies its transition through the claim
-    # rather than through `assess_move`. A wrong *value* is reported by the loop above,
-    # like its four siblings; an absent *key* is reported here.
-    if "start" not in transitions:
-        problems.append("work.tracker.transitions.start: required")
     start = move_transitions.get("start", "")
+    # After `transitions` is parsed, and absent only — the same rule as
+    # `exclusive-claim-transition`: `null` or blank already has its own problem.
+    if strict and "start" not in transitions:
+        problems.append(STRICT_NEEDS_START_TRANSITION)
 
     timeout: Any = raw.get("timeout-seconds", TRACKER_DEFAULT_TIMEOUT)
     # `bool` before `int`, because a bool *is* an int and `timeout-seconds: true`
@@ -1674,9 +1702,8 @@ def _parse_tracker_pre_backlog(raw: Any, statuses: dict, problems: list[str]) ->
 def _parse_tracker_transitions(raw: dict, problems: list[str]) -> dict:
     """The per-move keys of `work.tracker.transitions`, appending a problem per defect.
 
-    All five keys are parsed here, uniformly. That `start` is required is the
-    caller's check, not this one's: absent is `{}` here, which leaves every move on
-    the status-derived rule.
+    All five keys are parsed here, uniformly. Absent is `{}`, which leaves every
+    move on the status-derived rule; no key here is required.
     """
     where = "work.tracker.transitions"
 
@@ -1842,7 +1869,7 @@ def attribute_tracker_problems(problems: list[str], record: dict[TrackerKeyPath,
     """Prefix each parser problem with the label of the file that caused it.
 
     Matched on the problem's exact key path, never the nearest enclosing
-    mapping: `transitions.start: required` under a `transitions` an ancestor
+    mapping: `credentials.token-env: required` under a `credentials` an ancestor
     supplied is about a key nobody set, and goes to `own_label`. The parser
     writes a path as its keys joined with `.` followed by `: `, so the longest
     recorded path whose spelling prefixes the problem that way is the one it is
@@ -2925,13 +2952,21 @@ class MultipleMatch(Exception):
 
 
 class AlreadyClaimed(IllegalTransition):
-    """A single-winner start lost to an existing active claim."""
+    """A single-winner start lost to an existing active claim.
+
+    Names the command that takes the item over, because a refusal that stops somebody
+    has to say what to do instead. `tcw work tracker claim --take-over` is the one
+    for an item whose work is shared through a tracker; `start --take-over` stays for
+    a project with none, and for recovering an interrupted claim."""
 
     def __init__(self, slug: str, owner: str = "", started: str = ""):
         self.slug, self.owner, self.started = slug, owner, started
         who = owner or "an unknown owner"
         when = started or "an unknown time"
-        super().__init__(f"{slug} is already claimed by {who} since {when}")
+        super().__init__(f"{slug} is already claimed by {who} since {when}. To take "
+                         f"it over, run `tcw work tracker claim {slug} --take-over` "
+                         f"(or `tcw work start {slug} --take-over` where no tracker "
+                         f"is configured)")
 
 
 @dataclass
@@ -3876,7 +3911,9 @@ class WorkStore(ABC):
               take_over: bool = False) -> WorkItem:
         item = self._require(slug)
         if item.status == "active":
-            if not take_over:
+            # Active with nobody holding it — what `tcw work tracker release` leaves —
+            # is taken, not refused: there is nobody to displace.
+            if not take_over and item.owner:
                 raise AlreadyClaimed(slug, item.owner, item.started)
             if not owner:
                 raise ValueError("takeover requires an owner")

{tcw_cli-2.5.1 → tcw_cli-2.6.0}/tcw/store/fs.py

@@ -4053,7 +4053,9 @@ class FsWorkStore(FsTreeStore, WorkStore):
         if item is None:
             raise ValueError(f"no such work item: {slug}")
         if item.status == "active":
-            if not take_over:
+            # Active with nobody holding it — what `tcw work tracker release` leaves —
+            # is taken, not refused: there is nobody to displace.
+            if not take_over and item.owner:
                 raise AlreadyClaimed(slug, item.owner, item.started)
             if not owner:
                 raise ValueError("takeover requires an owner")
@@ -4061,7 +4063,8 @@ class FsWorkStore(FsTreeStore, WorkStore):
                                 {"owner": owner, "started": started})
             if self.auto_commit_transitions():
                 rel = str(self._require_dir(slug).relative_to(self.store_git_root))
-                err = git_commit_result(self.store_git_root, f"tcw work: take over {slug}", rel)
+                what = "take over" if item.owner else "claim"
+                err = git_commit_result(self.store_git_root, f"tcw work: {what} {slug}", rel)
                 if err:
                     raise TransitionCommitError(f"{slug} was taken over, but committing it failed:\n{err}")
             return self._require(slug)

{tcw_cli-2.5.1 → tcw_cli-2.6.0}/tcw/tracker/claim.py

@@ -48,6 +48,12 @@ CLAIM_NOT_OFFERED = "claim not offered by this ticket"
 # reporting one at all.
 MISCONFIGURED = "misconfigured"
 AMBIGUOUS = "ambiguous"
+# The project named no start transition at all. `work.tracker.transitions.start` is
+# optional — a lifecycle start works its transition out from the status it is heading
+# for — but a claim has no target status of its own to derive from. Distinct from
+# `CLAIM_NOT_OFFERED`, which is about a name this ticket does not offer: that one
+# sends the reader to the ticket's workflow, and this one to their own configuration.
+NOT_CONFIGURED = "no start transition configured"
 
 
 @dataclass(frozen=True)
@@ -92,6 +98,18 @@ def assess(claim_transition: str, *, current_status: str, offered,
     With no `landing_status` and no offered claim, the answer is `NOT_DETERMINED`.
     That is a real limitation, reported rather than papered over.
     """
+    # Nothing configured. Held here rather than in each caller: every reader of
+    # `config.start_transition` that has no status to derive from goes through this
+    # function, so one guard covers all of them.
+    if not claim_transition.strip():
+        return Assessment(
+            claimable=NOT_CLAIMABLE,
+            exclusivity=NOT_DETERMINED,
+            verdict=NOT_CONFIGURED,
+            detail=("work.tracker.transitions.start names no transition, so there is "
+                    "none to claim this ticket through."),
+        )
+
     wanted = _normalize(claim_transition)
     matches = [t for t in offered if _normalize(t.name) == wanted]
     offered_names = [t.name for t in offered]

{tcw_cli-2.5.1 → tcw_cli-2.6.0}/tcw/tracker/intake.py

@@ -195,15 +195,17 @@ def find_binding(store, *, project: str, provider: str, ticket_id: str,
 
 def binding_document(*, provider: str, project: str, part: str, ticket_id: str,
                      ticket_key: str, ticket_url: str, bound: str,
-                     unlinked: list, status_synced: bool = True,
-                     catch_up: bool = False) -> str:
+                     unlinked: list, status_synced: bool = True) -> str:
     """The `tracker.yaml` text for a new binding. No credential goes in it.
 
     The document records that an item and a ticket are the same work and nothing
     more: it names no account, because binding does not claim the ticket.
     `status_synced=False` notes that the item was already past `backlog` and the
-    ticket was not brought along; `catch_up=True` that `link --sync-status` asked for
-    it to be.
+    ticket was not brought along.
+
+    Nothing writes `catch-up: true` any more — `link --sync-status` did, and is
+    retired — but a binding already carrying it is still read (`Bound.catch_up`), so
+    the multi-rung walk it asked for stays reachable until those bindings age out.
     """
     document = {
         "schema": 1,
@@ -216,8 +218,6 @@ def binding_document(*, provider: str, project: str, part: str, ticket_id: str,
     }
     if not status_synced:
         document["status-synced"] = False
-    if catch_up:
-        document["catch-up"] = True
     return yaml.safe_dump(document, sort_keys=False, allow_unicode=True)
 
 
@@ -641,7 +641,7 @@ def _claim_from(client, ticket: TicketRead) -> ClaimOutcome:
     Authentication, permission, rate-limit and not-found errors on the transition
     propagate: the transition did not apply and there is nothing to read back.
     """
-    from tcw.tracker.claim import AMBIGUOUS, _normalize, assess
+    from tcw.tracker.claim import AMBIGUOUS, NOT_CONFIGURED, _normalize, assess
     from tcw.tracker.jira import (TrackerAuthError, TrackerError, TrackerNotFound,
                                   TrackerPermissionError, TrackerRateLimited,
                                   TrackerRequestInvalid)
@@ -673,9 +673,23 @@ def _claim_from(client, ticket: TicketRead) -> ClaimOutcome:
                              f"is ambiguous on this ticket.", assessment.detail)
     matches = [t for t in ticket.offered if _normalize(t.name) == _normalize(name)]
     if not matches:
+        # Row `1e` first, and that order is load-bearing: a ticket this account
+        # already holds needs no transition, which is what lets a claim that
+        # succeeded and then failed locally finish on a re-run, and what lets
+        # somebody take a ticket with `tcw work tracker claim` — assignment only —
+        # and then import it. A refusal above this row would break both.
         if ticket.assignee_id == ticket.me_id:
             return claimed("1e", f"not claimed by this run: {key} is already in "
                                  f"'{status}' and assigned to you.", status, False)
+        if assessment.verdict == NOT_CONFIGURED:
+            # Refused rather than derived: a claim is not a lifecycle move, it has no
+            # target status of its own to work a transition out from, and a wrong
+            # guess here assigns the ticket as well as moving it.
+            return refused("1d", f"{key} cannot be claimed: "
+                                 f"work.tracker.transitions.start is not set, and this "
+                                 f"command claims through it. Set it, or take the "
+                                 f"ticket with `tcw work tracker claim` and bind an "
+                                 f"item to it with `tcw work tracker link`.")
         offers = ", ".join(repr(t.name) for t in ticket.offered) or "nothing"
         return refused("1f", f"{key} is in '{status}', unassigned, and does not "
                              f"offer {name!r}. It offers: {offers}."

{tcw_cli-2.5.1 → tcw_cli-2.6.0}/tcw/tracker/ownership.py

@@ -27,8 +27,8 @@ The ceiling, for a project whose workflow genuinely refuses a second claimant:
 name a transition in `work.tracker.exclusive-claim-transition` and it is applied
 first, so a second claimant's transition is refused and never reaches the assign.
 That is `intake.claim`'s own reasoning, and it is the one case where claiming
-does move the ticket — which is why it is opt-in, and why the guide says plainly
-what opting in costs.
+does move the ticket — which is why it is opt-in (required under strict mode),
+and why the guide says plainly what opting in costs.
 
 One rule is carried across from `intake.claim` by hand rather than by import: a
 ticket already assigned to the caller is already held, whatever the workflow now
@@ -39,7 +39,7 @@ being idempotent the moment a project opted in.
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 
 from tcw.tracker.claim import _normalize
 from tcw.tracker.jira import TrackerError, TrackerRequestInvalid
@@ -50,8 +50,19 @@ class OwnershipOutcome:
     """What one claim or release attempt established.
 
     `settled` is whether the tracker now says what the caller asked it to say —
-    held by them for a claim, held by nobody for a release. Everything else is
-    for the message.
+    held by them for a claim, held by nobody for a release. `retry` is whether an
+    unsettled claim is worth simply running again: the tracker did not answer the
+    assignment or its read-back, rather than answering no. `transitioned` is whether
+    the assertion transition was applied — **set on a failure as well as a success**,
+    because a claim whose transition landed and whose assignment then did not has
+    moved the ticket and left it unassigned, and only the caller that knows this can
+    say so. `assigned` is whether this run's own assignment landed: false for every
+    refusal up to and including the assignment failing, true from the read-back
+    onwards. The two together are what separate *the ticket is unassigned* — the
+    assignment did not land — from *who holds it is unknown*, which is all a failed
+    read-back establishes. `status` is where the ticket is when the outcome is made,
+    so after an applied assertion it is where that transition led, not where the
+    ticket was found. Everything else is for the message.
     """
     settled: bool
     message: str
@@ -60,6 +71,11 @@ class OwnershipOutcome:
     status: str = ""
     detail: str = ""
     transitioned: bool = False
+    retry: bool = False
+    assigned: bool = False
+    # The ticket's key, so a caller holding only the outcome can name the ticket —
+    # `claim_refusal` serves this outcome and `intake.claim`'s alike.
+    key: str = ""
 
 
 def _holder(client, ticket):
@@ -70,6 +86,14 @@ def _holder(client, ticket):
 
 def assert_ownership(client, ticket, *, assertion: str = "",
                      take_over: bool = False) -> OwnershipOutcome:
+    """Make `ticket` held by the account `client` authenticates as — see
+    `_assert_ownership`. Every outcome carries the ticket's key."""
+    return replace(_assert_ownership(client, ticket, assertion=assertion,
+                                     take_over=take_over), key=ticket.key)
+
+
+def _assert_ownership(client, ticket, *, assertion: str = "",
+                      take_over: bool = False) -> OwnershipOutcome:
     """Make `ticket` held by the account `client` authenticates as.
 
     Idempotent for whoever already holds it. Refuses a second holder by name,
@@ -79,11 +103,18 @@ def assert_ownership(client, ticket, *, assertion: str = "",
     them is an answer about who holds the ticket.
     """
     key = ticket.key
+    # Where the ticket is as this runs. An applied assertion moves it, and every
+    # refusal after that has to report where it left the ticket, not where it found
+    # it: a caller told the old status cannot tell the user what to put right.
+    landed = ticket.status
+    transitioned = False
 
-    def refused(message: str, detail: str = "", holder=("", "")) -> OwnershipOutcome:
+    def refused(message: str, detail: str = "", holder=("", ""), retry: bool = False,
+                assigned: bool = False) -> OwnershipOutcome:
         return OwnershipOutcome(settled=False, message=message, detail=detail,
                                 holder_id=holder[0], holder_name=holder[1],
-                                status=ticket.status)
+                                status=landed, retry=retry,
+                                transitioned=transitioned, assigned=assigned)
 
     if ticket.category == "done":
         return refused(f"{key} is resolved ('{ticket.status}'), so there is nothing "
@@ -99,7 +130,6 @@ def assert_ownership(client, ticket, *, assertion: str = "",
                                 holder_id=ticket.me_id, holder_name=ticket.me_name,
                                 message=f"{key} is already held by you.")
 
-    transitioned = False
     if assertion:
         matches = [t for t in ticket.offered
                    if _normalize(t.name) == _normalize(assertion)]
@@ -115,7 +145,7 @@ def assert_ownership(client, ticket, *, assertion: str = "",
                            f"offers: {offers}.")
         try:
             client.apply_transition(ticket.issue_id, matches[0].id)
-            transitioned = True
+            transitioned, landed = True, matches[0].to_status
         except TrackerRequestInvalid as error:
             # The workflow refused it, which is the whole point of naming one: on a
             # workflow that excludes a second claimant this is where they stop, and
@@ -126,26 +156,33 @@ def assert_ownership(client, ticket, *, assertion: str = "",
     try:
         client.assign(ticket.issue_id, ticket.me_id)
     except TrackerError as error:
+        # Worth retrying unless the tracker answered and refused: a 400 is an answer.
         return refused(f"{key} could not be assigned to you, so it is not held.",
-                       str(error))
+                       str(error), retry=not isinstance(error, TrackerRequestInvalid))
 
     # The read-back. Everything above is what we asked for; this is what is true.
     try:
         status, category, now_id, now_name = _holder(client, ticket)
     except TrackerError as error:
+        # `assigned`: the write above landed, so the ticket is **not** known to be
+        # unassigned — a caller that says it is contradicts this very message, and
+        # replaces advice that works. Running the claim again does recover it, because
+        # a ticket already yours is returned as held before anything is sent.
         return refused(f"{key} was assigned to you, but reading it back failed, so "
                        f"whether you hold it is unknown. Run this again to find out.",
-                       str(error))
+                       str(error), retry=not isinstance(error, TrackerRequestInvalid),
+                       assigned=True)
     if now_id == ticket.me_id:
         return OwnershipOutcome(settled=True, message=f"{key} is held by you.",
                                 holder_id=now_id, holder_name=now_name,
-                                status=status, transitioned=transitioned)
+                                status=status, transitioned=transitioned,
+                                assigned=True)
     if not now_id:
         # Assigned, then unassigned before the read-back — somebody released it out
         # from under this claim. Nobody holds it, so saying somebody does would be a
         # lie, and there is nobody whose claim re-running could stamp on.
         return OwnershipOutcome(
-            settled=False, status=status, transitioned=transitioned,
+            settled=False, status=status, transitioned=transitioned, assigned=True,
             message=(f"{key} was assigned to you and then to nobody, so you do not "
                      f"hold it: somebody unassigned it while this claim was in "
                      f"flight. Run this again to take it."))
@@ -154,7 +191,7 @@ def assert_ownership(client, ticket, *, assertion: str = "",
     # between our write and our read — undoing it would stamp on their claim.
     return OwnershipOutcome(
         settled=False, holder_id=now_id, holder_name=now_name, status=status,
-        transitioned=transitioned,
+        transitioned=transitioned, assigned=True,
         message=(f"{key} is held by {now_name or 'another account'}, not by you: they "
                  f"took it while this claim was in flight. Nothing here is yours; "
                  f"run this again if they let it go."))

{tcw_cli-2.5.1 → tcw_cli-2.6.0}/tcw/tracker/progress.py

@@ -28,7 +28,7 @@ from tcw.store.base import link_for
 from tcw.tracker.intake import (BINDING_SIDECAR, Bound, binding_of, read_ticket,
                                 same_site, with_comment_record)
 from tcw.tracker.jira import TrackerError
-from tcw.tracker.sync import (CONFLICTING, CURRENT, MOVES_ALLOWING_UNASSIGNED, NONE,
+from tcw.tracker.sync import (CONFLICTING, CURRENT, MOVES_NEEDING_NO_CLAIM, NONE,
                               PENDING, REASON_LIMIT, Outcome, _now, classify_error)
 
 SKIPPED, CLEARED = "skipped", "cleared"
@@ -122,7 +122,7 @@ def _send(store, slug: str, client, config, bound: Bound, move: str, event: str,
     # comment is the only record of why the ticket closed, and skipping it would close
     # the ticket silently. A ticket somebody *else* holds is still theirs to annotate.
     if ticket.assignee_id != ticket.me_id and not (
-            not ticket.assignee_id and move in MOVES_ALLOWING_UNASSIGNED):
+            not ticket.assignee_id and move in MOVES_NEEDING_NO_CLAIM):
         holder = ticket.assignee_name if ticket.assignee_id else "nobody"
         _write(store, slug, None)
         return Outcome(SKIPPED, f"{key} is assigned to {holder}, so no progress comment "