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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tcw-cli
-Version: 2.5.1
+Version: 2.6.1
 Summary: Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project.
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -727,14 +727,15 @@ to the transitions.
 
 | Lifecycle step                          | Without Jira                   | With Jira configured                                                                                                                           |
 | --------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| an item is created                      | `tcw work inbox accept`, `new` | `tcw work tracker import <ticket>` claims the ticket (starts it and assigns it to you), then creates a backlog item whose intake is the ticket. With `inbox-query` set, `tcw work inbox accept <ticket>` does the same |
+| an item is created                      | `tcw work inbox accept`, `new` | `tcw work tracker import <ticket>` claims the ticket (starts it and assigns it to you), then creates a backlog item whose intake is the ticket and puts the ticket back where it was, still assigned to you. With `inbox-query` set, `tcw work inbox accept <ticket>` does the same |
 | `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
@@ -788,9 +797,9 @@ e-mail address or token themselves.
 
 ```sh
 tcw work tracker list                  # TCW: lists tickets the query selects.   Jira: unchanged
-tcw work tracker import ENG-482         # TCW: creates a backlog item.            Jira: ENG-482 → In Progress, assigned to you
+tcw work tracker import ENG-482         # TCW: creates a backlog item.            Jira: ENG-482 stays in To Do, assigned to you
 #   …the request, spec and plan stages run as usual…
-tcw work start <slug>                   # TCW: backlog → active.                  Jira: confirms the claim import made
+tcw work start <slug>                   # TCW: backlog → active.                  Jira: ENG-482 → In Progress
 tcw work submit <slug>                  # TCW: active → review.                   Jira: ENG-482 → In Review
 tcw work complete <slug> --resolution done --confirm
                                         # TCW: review → completed.                Jira: ENG-482 → Done

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

@@ -511,14 +511,15 @@ to the transitions.
 
 | Lifecycle step                          | Without Jira                   | With Jira configured                                                                                                                           |
 | --------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| an item is created                      | `tcw work inbox accept`, `new` | `tcw work tracker import <ticket>` claims the ticket (starts it and assigns it to you), then creates a backlog item whose intake is the ticket. With `inbox-query` set, `tcw work inbox accept <ticket>` does the same |
+| an item is created                      | `tcw work inbox accept`, `new` | `tcw work tracker import <ticket>` claims the ticket (starts it and assigns it to you), then creates a backlog item whose intake is the ticket and puts the ticket back where it was, still assigned to you. With `inbox-query` set, `tcw work inbox accept <ticket>` does the same |
 | `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
@@ -572,9 +581,9 @@ e-mail address or token themselves.
 
 ```sh
 tcw work tracker list                  # TCW: lists tickets the query selects.   Jira: unchanged
-tcw work tracker import ENG-482         # TCW: creates a backlog item.            Jira: ENG-482 → In Progress, assigned to you
+tcw work tracker import ENG-482         # TCW: creates a backlog item.            Jira: ENG-482 stays in To Do, assigned to you
 #   …the request, spec and plan stages run as usual…
-tcw work start <slug>                   # TCW: backlog → active.                  Jira: confirms the claim import made
+tcw work start <slug>                   # TCW: backlog → active.                  Jira: ENG-482 → In Progress
 tcw work submit <slug>                  # TCW: active → review.                   Jira: ENG-482 → In Review
 tcw work complete <slug> --resolution done --confirm
                                         # TCW: review → completed.                Jira: ENG-482 → Done

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

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

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

{tcw_cli-2.5.1 → tcw_cli-2.6.1}/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.1}/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.1}/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.1}/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)
 
 
@@ -445,6 +445,9 @@ class ClaimOutcome:
     # when no such step ran. Set on success and on a refusal alike: either way the
     # ticket has left triage, and the caller has to say so (`moved_out`).
     left_status: str = ""
+    # The status the claim found the ticket in, after any `pre-backlog` step: where
+    # `import` puts a ticket its claim moved (`put_back`). Set only on a claim.
+    claimed_from: str = ""
 
 
 def _fields(issue: dict) -> tuple[str, str, str, str]:
@@ -625,7 +628,8 @@ def claim(client, ticket: TicketRead) -> ClaimOutcome:
         if left:
             error.left_status = left
         raise
-    return replace(outcome, left_status=left)
+    return replace(outcome, left_status=left,
+                   claimed_from=ticket.status if outcome.claimed else "")
 
 
 def _claim_from(client, ticket: TicketRead) -> ClaimOutcome:
@@ -641,7 +645,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 +677,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}."
@@ -731,3 +749,47 @@ def _claim_from(client, ticket: TicketRead) -> ClaimOutcome:
     return refused("3f", f"could not tell whether this run's claim applied: {key} is "
                          f"in '{now_status}', unassigned. Check the ticket's history "
                          f"in the tracker before assigning it.", detail)
+
+
+def put_back(client, outcome: ClaimOutcome) -> tuple[str, str]:
+    """Move a ticket this run's claim took back to `outcome.claimed_from`, where the
+    claim found it. `import` does this once its backlog item exists, so the ticket
+    does not say the work has started while the item says it has not.
+
+    The claim's own transition is what kept a second claimant out, so it is taken
+    first and only undone here, after the item is bound. The way back is the one
+    transition the ticket offers to that status, chosen as a lifecycle move with no
+    named transition chooses it (`assess_move`); none, or more than one, sends
+    nothing.
+
+    Returns `(the status the ticket is in, why it is not back or "")`. Never raises a
+    tracker error: by now the item exists, so a ticket left where the claim put it is
+    something to report, not a reason to fail.
+    """
+    from tcw.tracker.claim import _normalize
+    from tcw.tracker.jira import TrackerError
+    from tcw.tracker.sync import CURRENT, assess_move
+
+    target = outcome.claimed_from
+    try:
+        ticket = read_ticket(client, outcome.issue_id)
+        state, found = assess_move(ticket, target=target, expected=(), move=None)
+        if state == CURRENT:
+            return ticket.status, ""
+        if state != "apply":
+            return ticket.status, found
+        client.apply_transition(ticket.issue_id, found.id)
+        status = _fields(client.issue(ticket.issue_id))[0]
+    except TrackerError as error:
+        # The transition may have landed with its answer lost, so where the ticket
+        # is has to be read rather than assumed.
+        try:
+            status = _fields(client.issue(outcome.issue_id))[0]
+        except TrackerError:
+            return outcome.status, f"{error}; where it is now could not be read"
+        if _normalize(status) == _normalize(target):
+            return status, ""
+        return status, str(error)
+    if _normalize(status) != _normalize(target):
+        return status, f"it is in '{status}' after '{found.name}'"
+    return status, ""