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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tcw-cli
-Version: 2.7.0
+Version: 2.8.0
 Summary: Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project.
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -688,9 +688,9 @@ The stages, and the document each one writes:
 | Stage        | Runs while the item is | Writes                                                            |
 | ------------ | ---------------------- | ----------------------------------------------------------------- |
 | `inbox`      | not yet an item        | nothing; it creates the item, keeping the raw text as `intake.md` |
-| `request`    | backlog                | `initial-request.md`: what is asked for, and why                  |
-| `spec`       | backlog                | `spec.md`: what to build, with acceptance criteria                |
-| `plan`       | backlog                | `plan.md`: how to build it, as ordered tasks                      |
+| `request`    | backlog (or active)    | `initial-request.md`: what is asked for, and why                  |
+| `spec`       | backlog (or active)    | `spec.md`: what to build, with acceptance criteria                |
+| `plan`       | backlog (or active)    | `plan.md`: how to build it, as ordered tasks                      |
 | `implement`  | active                 | `outcome.md`: what was built, and what the plan got wrong         |
 | `verify`     | review (or active)     | `refined-outcome.md` if accepted, `rework.md` if not              |
 | `postmortem` | review or completed    | `post-mortem.md`: which stage could first have caught a problem   |
@@ -702,7 +702,7 @@ The transitions, and what each one checks before it moves an item:
 | `start`      | `tcw work start <slug>`                                                          | backlog → active                      | a blocker is unresolved; the item belongs to an epic that is not active                                                                   |
 | `submit`     | `tcw work submit <slug>`                                                         | active → review                       | never                                                                                                                                     |
 | `rework`     | `tcw work rework <slug>`                                                         | review → active                       | `refined-outcome.md` is present (it says the work was accepted)                                                                           |
-| `complete`   | `tcw work complete <slug> --resolution done --confirm`                           | review or active → completed          | a blocker is unresolved; an epic has open children; declared capabilities are not reconciled; a worktree merge-back fails; the item's folder in its worktree has uncommitted changes; no `--confirm` |
+| `complete`   | `tcw work complete <slug> --resolution done --confirm`                           | review or active → completed          | a blocker is unresolved; an epic has open children; declared capabilities are not reconciled; a worktree merge-back fails; with `--already-integrated`, the branch is not merged into `HEAD`; the item's folder in its worktree has uncommitted changes; no `--confirm` |
 | discard      | `tcw work complete <slug> --resolution wontfix\|duplicate\|superseded --confirm` | backlog, active or review → discarded | no `--confirm`                                                                                                                            |
 | `drop`       | `tcw work drop <slug> --confirm`                                                 | backlog → removed                     | the item is not in backlog; no `--confirm`                                                                                                |
 | not retained | happens during `complete` or discard                                             | completed or discarded → removed      | only happens when `work.retain` says that status is not kept; `tcw work delete` finishes one that was interrupted                         |

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

@@ -472,9 +472,9 @@ The stages, and the document each one writes:
 | Stage        | Runs while the item is | Writes                                                            |
 | ------------ | ---------------------- | ----------------------------------------------------------------- |
 | `inbox`      | not yet an item        | nothing; it creates the item, keeping the raw text as `intake.md` |
-| `request`    | backlog                | `initial-request.md`: what is asked for, and why                  |
-| `spec`       | backlog                | `spec.md`: what to build, with acceptance criteria                |
-| `plan`       | backlog                | `plan.md`: how to build it, as ordered tasks                      |
+| `request`    | backlog (or active)    | `initial-request.md`: what is asked for, and why                  |
+| `spec`       | backlog (or active)    | `spec.md`: what to build, with acceptance criteria                |
+| `plan`       | backlog (or active)    | `plan.md`: how to build it, as ordered tasks                      |
 | `implement`  | active                 | `outcome.md`: what was built, and what the plan got wrong         |
 | `verify`     | review (or active)     | `refined-outcome.md` if accepted, `rework.md` if not              |
 | `postmortem` | review or completed    | `post-mortem.md`: which stage could first have caught a problem   |
@@ -486,7 +486,7 @@ The transitions, and what each one checks before it moves an item:
 | `start`      | `tcw work start <slug>`                                                          | backlog → active                      | a blocker is unresolved; the item belongs to an epic that is not active                                                                   |
 | `submit`     | `tcw work submit <slug>`                                                         | active → review                       | never                                                                                                                                     |
 | `rework`     | `tcw work rework <slug>`                                                         | review → active                       | `refined-outcome.md` is present (it says the work was accepted)                                                                           |
-| `complete`   | `tcw work complete <slug> --resolution done --confirm`                           | review or active → completed          | a blocker is unresolved; an epic has open children; declared capabilities are not reconciled; a worktree merge-back fails; the item's folder in its worktree has uncommitted changes; no `--confirm` |
+| `complete`   | `tcw work complete <slug> --resolution done --confirm`                           | review or active → completed          | a blocker is unresolved; an epic has open children; declared capabilities are not reconciled; a worktree merge-back fails; with `--already-integrated`, the branch is not merged into `HEAD`; the item's folder in its worktree has uncommitted changes; no `--confirm` |
 | discard      | `tcw work complete <slug> --resolution wontfix\|duplicate\|superseded --confirm` | backlog, active or review → discarded | no `--confirm`                                                                                                                            |
 | `drop`       | `tcw work drop <slug> --confirm`                                                 | backlog → removed                     | the item is not in backlog; no `--confirm`                                                                                                |
 | not retained | happens during `complete` or discard                                             | completed or discarded → removed      | only happens when `work.retain` says that status is not kept; `tcw work delete` finishes one that was interrupted                         |

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

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

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

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

@@ -10,6 +10,7 @@ import subprocess
 import sys
 from pathlib import Path
 
+from tcw.cli_suggest import SuggestingParser, attach_index
 from tcw import __version__
 from tcw.capabilities import cli as capabilities_cli
 from tcw.serve import DEFAULT_PORT, serve
@@ -479,7 +480,7 @@ def _cmd_serve(args: argparse.Namespace) -> int:
 
 
 def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="tcw", description="Taxonomy · Capabilities · Work.")
+    parser = SuggestingParser(prog="tcw", description="Taxonomy · Capabilities · Work.")
     parser.add_argument("--version", action="version", version=f"tcw {__version__}")
     sub = parser.add_subparsers(dest="group", required=True)
 
@@ -528,6 +529,7 @@ def build_parser() -> argparse.ArgumentParser:
         p = sub.add_parser(name, help=f"{name} commands (not yet implemented)")
         p.set_defaults(func=_not_yet(name))
 
+    attach_index(parser)
     return parser
 
 
@@ -560,9 +562,9 @@ def main(argv: list[str] | None = None) -> int:
         return 1
     except subprocess.CalledProcessError as error:
         # Deliberately generic: the only policy here is "a git subprocess
-        # failed", which is true of every component. git's own diagnostic has
-        # already reached the terminal — no `check=True` call in the filesystem
-        # adapter captures output — so re-printing `error.stderr` would double it.
+        # failed", which is true of every component. The index-touching calls
+        # capture git's output (so a retried failure does not print once per
+        # try), and it is printed here; an uncaptured call has already shown it.
         # `cmd` is a sequence *or* a string (stdlib contract); joining a string
         # iterates its characters. No shipped raiser passes one, but a handler
         # whose whole justification is that it assumes nothing about its caller
@@ -571,6 +573,8 @@ def main(argv: list[str] | None = None) -> int:
             shlex.join(str(a) for a in error.cmd)
         print(f"tcw: git command failed (exit {error.returncode}): {cmd}",
               file=sys.stderr)
+        if isinstance(error.stderr, str) and error.stderr.strip():
+            print(error.stderr.rstrip("\n"), file=sys.stderr)
         return 1
 
 

tcw_cli-2.8.0/tcw/cli_suggest.py

@@ -0,0 +1,199 @@
+"""Answer a mistyped subcommand with the command that was probably meant.
+
+argparse reports a wrong subcommand by listing every valid choice at that level,
+which says nothing when the word exists one level down (`tcw tracker` for
+`tcw work tracker`) or is a synonym (`status` for `show`). `SuggestingParser`
+keeps argparse's message word for word and adds one line after it.
+
+Three rules, first match wins:
+
+1. The word is a subcommand somewhere else in the tree: name each full command,
+   and complete it with the word that followed when that is wrong there too —
+   `tcw tracker status` → `tcw work tracker show`.
+2. A small table of synonyms, offered only where their target is valid.
+3. Close spellings among the choices valid at that level.
+
+Only subcommands that `--help` lists are ever offered. That is what keeps the
+removed `tcw work stage <id>` spellings — registered without `help=` so that the
+old form can print its replacement — out of every suggestion, without naming
+them here.
+"""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+
+# One clear target each. Words for removal are left out on purpose: `drop`,
+# `delete` and `rm` destroy things, and pointing at one is worse than no hint.
+SYNONYMS: dict[str, tuple[str, ...]] = {
+    "status": ("show", "list"),
+    "info": ("show",),
+    "view": ("show",),
+    "get": ("show",),
+    "cat": ("show",),
+    "ls": ("list",),
+}
+
+# Never offered by any rule, and never answered either: pointing somebody at a
+# command that destroys things, when they typed something else, is worse than
+# no hint — and so is guessing what a mistyped removal was meant to remove
+# (`tcw work tracker delete` is not `tcw work delete`, which deletes an item).
+REMOVAL = frozenset({"rm", "drop", "delete"})
+
+_MAX = 3
+
+
+def _subparsers(parser: argparse.ArgumentParser) -> argparse._SubParsersAction | None:
+    for action in parser._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            return action
+    return None
+
+
+def visible_choices(action: argparse._SubParsersAction) -> list[str]:
+    """The subcommands this action lists in its help, in its own order."""
+    listed = {choice.dest for choice in action._choices_actions}
+    return [name for name in action.choices if name in listed]
+
+
+def _offered(word: str, choices: list[str]) -> list[str]:
+    """Rules 2 and 3 for one level: synonyms valid here, else close spellings."""
+    safe = [c for c in choices if c not in REMOVAL]
+    synonyms = [s for s in SYNONYMS.get(word, ()) if s in safe]
+    if synonyms:
+        return synonyms
+    return difflib.get_close_matches(word, safe, n=_MAX, cutoff=0.6)
+
+
+def _command(path: tuple[str, ...]) -> str:
+    return "`" + " ".join(path) + "`"
+
+
+def _phrase(commands: list[str]) -> str:
+    if len(commands) == 1:
+        return f"did you mean {commands[0]}?"
+    if len(commands) == 2:
+        return f"did you mean {commands[0]} or {commands[1]}?"
+    return f"did you mean one of {', '.join(commands)}?"
+
+
+class SuggestingParser(argparse.ArgumentParser):
+    """An `ArgumentParser` whose wrong-subcommand error suggests what was meant.
+
+    Every subparser gets this class too, since `add_subparsers` defaults to the
+    parent's. `attach_index` gives the whole tree what the hint needs."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        # Python 3.14 has argparse's own close-spelling hint. Off, explicitly,
+        # so a later default cannot print a second, different suggestion.
+        self.suggest_on_error = False
+
+    def parse_known_args(self, args=None, namespace=None):
+        # The root keeps what it was asked to parse: a nested parser reports its
+        # own error and needs the word after the one it rejected.
+        if getattr(self, "_tcw_root", None) is self:
+            self._tcw_argv = list(args) if args is not None else None
+        return super().parse_known_args(args, namespace)
+
+    def _check_value(self, action, value):
+        if not isinstance(action, argparse._SubParsersAction) or value in action.choices:
+            return super()._check_value(action, value)
+        choices = visible_choices(action)
+        hint = self._hint(str(value), choices)
+        if len(choices) == len(action.choices):
+            # Nothing hidden: argparse's own message, exactly as this Python
+            # version words it (3.12 and 3.13 leave the choices unquoted).
+            try:
+                super()._check_value(action, value)
+            except argparse.ArgumentError as error:
+                if not hint:
+                    raise
+                raise argparse.ArgumentError(action, f"{error.message}\n{hint}") from None
+        message = (f"invalid choice: {value!r} (choose from "
+                   f"{', '.join(repr(c) for c in choices)})")
+        if hint:
+            message += f"\n{hint}"
+        raise argparse.ArgumentError(action, message)
+
+    def _hint(self, word: str, choices: list[str]) -> str:
+        root = getattr(self, "_tcw_root", None)
+        here = getattr(self, "_tcw_path", None)
+        if root is None or here is None or word in REMOVAL:
+            return ""
+        # Same component first — `tcw work tags show` means a `tcw work …` show,
+        # not `tcw taxonomy show` — then shallowest: `tcw show` means
+        # `tcw work show` before `tcw work inbox show`. `sorted` is stable, so
+        # ties keep tree order.
+        elsewhere = sorted(
+            (p for p in root._tcw_index.get(word, ()) if p[:-1] != here),
+            key=lambda p: (-_shared(p, here), len(p)))
+        if elsewhere:
+            following = _following(root, here, word)
+            commands = []
+            for path in elsewhere[:_MAX]:
+                commands += [_command(path + tail) for tail in _completion(root, path, following)]
+            return _phrase(commands[:_MAX])
+        offered = _offered(word, choices)
+        return _phrase([_command(here + (o,)) for o in offered]) if offered else ""
+
+
+def _shared(path: tuple[str, ...], here: tuple[str, ...]) -> int:
+    """How many leading words `path` shares with `here`."""
+    n = 0
+    for a, b in zip(path, here):
+        if a != b:
+            break
+        n += 1
+    return n
+
+
+def _following(root: SuggestingParser, here: tuple[str, ...], word: str) -> str:
+    """The word after `word` on the command line, if it is not an option."""
+    argv = getattr(root, "_tcw_argv", None) or []
+    start = len(here) - 1                           # `here` includes "tcw"
+    for index in range(start, len(argv)):
+        if argv[index] == word:
+            after = argv[index + 1] if index + 1 < len(argv) else ""
+            return "" if after.startswith("-") else after
+    return ""
+
+
+def _completion(root: SuggestingParser, path: tuple[str, ...],
+                following: str) -> list[tuple[str, ...]]:
+    """How to finish `path` with the word typed after it: kept when it is valid
+    there or there is nothing to finish, else what that word was likely meant as."""
+    parser = root._tcw_parsers.get(path)
+    action = _subparsers(parser) if parser is not None else None
+    if not following or action is None:
+        return [()]
+    choices = visible_choices(action)
+    if following in choices:
+        return [(following,)]
+    offered = _offered(following, choices)
+    return [(o,) for o in offered] or [()]
+
+
+def attach_index(root: SuggestingParser) -> None:
+    """Walk the finished tree once: every parser learns its own path and the
+    root, and the root learns every listed subcommand's full paths."""
+    index: dict[str, list[tuple[str, ...]]] = {}
+    parsers: dict[tuple[str, ...], argparse.ArgumentParser] = {}
+
+    def walk(parser: argparse.ArgumentParser, path: tuple[str, ...]) -> None:
+        parser._tcw_root = root
+        parser._tcw_path = path
+        parsers[path] = parser
+        action = _subparsers(parser)
+        if action is None:
+            return
+        listed = set(visible_choices(action))
+        for name, child in action.choices.items():
+            if name in listed:
+                index.setdefault(name, []).append(path + (name,))
+            walk(child, path + (name,))
+
+    walk(root, (root.prog,))
+    root._tcw_index = index
+    root._tcw_parsers = parsers

{tcw_cli-2.7.0 → tcw_cli-2.8.0}/tcw/refs.py

@@ -135,6 +135,10 @@ def resolve_tcw_ref(node_root: Path | None, uri: str) -> ResolveResult:
             return ResolveResult(
                 False, "W", None, qualified_work_ref_problem(node_root, ns_ref))
         store, bare = resolved
+        # A renamed item answers to its old slug too: a link is exactly the kind
+        # of reference a rename cannot rewrite.
+        if store.get(bare) is None and (renamed := store.renamed(bare)):
+            bare = renamed
         # Locating the store that would hold the item is not the item existing.
         # `resolve_qualified_work_ref` answers "which store addresses this ref",
         # which is what `tcw serve`'s routing wants; `ok` answers "does this

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

@@ -967,6 +967,7 @@ class TcwHandler(BaseHTTPRequestHandler):
                 initiative = body.get("initiative", "")
                 type_val = body.get("type", "")
                 tags = body.get("tags") or None
+                work.refresh_for_creation()
                 detail = work.create_work(
                     title=title,
                     created=created,
@@ -987,6 +988,14 @@ class TcwHandler(BaseHTTPRequestHandler):
                     # stale — which the next sidecar write from the page would
                     # be rejected on.
                     detail = work.get_detail(detail.item.slug) or detail
+                # After the owed record, so it is in the same commit. A refusal
+                # is logged, not returned: the item exists, and an error here
+                # would invite the browser to create it a second time.
+                folder = work.path(detail.item.slug)
+                if folder is not None and (reason := work.commit_writes(
+                        f"tcw work: new {detail.item.slug}", folder)):
+                    print(f"tcw serve: created {detail.item.slug}, but {reason}",
+                          file=sys.stderr)
                 response = {
                     "item": _item_payload(work, detail.item.slug, detail.item),
                     "coreRevision": detail.core_revision,

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

@@ -2255,6 +2255,7 @@ LIFECYCLE_STEPS: tuple[LifecycleStep, ...] = (
         objective="Close the item as shipped.",
         moves="review | active → completed",
         gates=("unresolved blockers", "open initiative children",
+               "refined-outcome.md from review",
                "declared capabilities reconciled", "worktree merge-back",
                "--confirm")),
     LifecycleStep(
@@ -2292,13 +2293,14 @@ LIFECYCLE_STEPS_BY_ID = {s.id: s for s in LIFECYCLE_STEPS}
 # * `spec` and `plan` include `active` because nothing moves an item back to
 #   `backlog`: an item started before it was specified or planned would
 #   otherwise never pass either gate again. `backlog` stays first — it is where
-#   they normally run.
+#   they normally run. `request` joined them in 2.8 for the same reason: work
+#   written up after it started had no gate for its request at all.
 #
 # `inbox` is empty: it runs before an item exists, so there is no status to be
 # legal in and no item to resolve a stage against.
 STAGE_STATUSES: dict[str, tuple[str, ...]] = {
     "inbox": (),
-    "request": ("backlog",),
+    "request": ("backlog", "active"),
     "spec": ("backlog", "active"),
     "plan": ("backlog", "active"),
     "implement": ("active",),
@@ -2360,6 +2362,7 @@ TRANSITION_NEXT_STEPS: dict[str, str] = {
     # `inbox accept` of a raw entry prints this too: both leave a backlog item
     # holding at most its intake.
     "new": "run `tcw work stage gate request <slug>`",
+    "start:request": "run `tcw work stage gate request <slug>`",
     "start:spec": "run `tcw work stage gate spec <slug>`",
     "start:plan": "run `tcw work stage gate plan <slug>`",
     "start:implement": "run `tcw work stage gate implement <slug>`",
@@ -2376,6 +2379,7 @@ TRANSITION_NEXT_STEPS: dict[str, str] = {
 # stage against. Nothing else reads it.
 TRANSITION_LANDS_IN: dict[str, str] = {
     "new": "backlog",
+    "start:request": "active",
     "start:spec": "active",
     "start:plan": "active",
     "start:implement": "active",
@@ -2385,16 +2389,64 @@ TRANSITION_LANDS_IN: dict[str, str] = {
 }
 
 
+def refined_outcome_missing(slug: str, stray: str = "") -> str:
+    """Why a completion from review was refused for want of its acceptance
+    record, and where to put it."""
+    return (f"{slug} has no refined-outcome.md, the verify stage's record that "
+            f"the work was accepted. Write it in the item's folder, which moved "
+            f"to review/ at submit — `tcw work path {slug}` prints it"
+            + (f"; {stray}" if stray else "")
+            + ". Use --force to complete without it.")
+
+
+def slugify(name: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", name.strip().lower()).strip("-")
+
+
+_DATE_PREFIX = re.compile(r"^\d{4}-\d{2}-\d{2}-")
+
+
+def rename_slug(old: str, new: str) -> str:
+    """The full slug `tcw work rename <old> <new>` means, or ValueError.
+
+    `new` may be a whole slug or only the part after the date. The date stays
+    the item's own — it records when the item was made, not when it was named —
+    so a different date is refused rather than quietly replaced. Never
+    rewritten into slug form: an argument that is not one already is refused
+    naming the form it would be, so the slug that lands is the slug typed."""
+    new = new.strip()
+    old_date = _DATE_PREFIX.match(old)
+    new_date = _DATE_PREFIX.match(new)
+    if new_date and old_date and new_date.group(0) != old_date.group(0):
+        raise ValueError(f"{new} has a different date than {old}; the date is when "
+                         f"the item was made, and a rename keeps it — give only "
+                         f"the part after it")
+    full = new if new_date or not old_date else old_date.group(0) + new
+    body = _DATE_PREFIX.sub("", full)
+    if not body or slugify(body) != body:
+        hint = slugify(body) if body and slugify(body) != "untitled" else ""
+        raise ValueError(f"'{new}' is not a slug (lower-case letters, digits and "
+                         f"single hyphens)" + (f"; did you mean '{hint}'?" if hint else ""))
+    if len(body) > 120:
+        raise ValueError(f"'{new}' is longer than 120 characters after the date")
+    return full
+
+
 def start_next_stage(present: Collection[str]) -> str:
     """The stage to run after `start`, from the artifacts the item holds.
 
     Not always `implement`. An item can be started before it is specified or
     planned, and `start` also takes an item already `active` — with
     `--take-over`, or when nobody holds it — which may already have an outcome.
-    The order is the `work` skill's "Finding your place", restricted to stages
-    legal in `active` (so never `request`), with a reworked item sent back to
-    `implement` as `rework`'s own hint does.
+    The order is the `work` skill's "Finding your place", with a reworked item
+    sent back to `implement` as `rework`'s own hint does.
+
+    The request counts as missing only while the spec is too. A spec supersedes
+    its job of recording what was asked, so an item already specified — the
+    usual shape of work written up after it started — is never sent back for it.
     """
+    if "initial-request" not in present and "spec" not in present:
+        return "request"
     if "spec" not in present:
         return "spec"
     if "plan" not in present:
@@ -3334,6 +3386,10 @@ def priority_order(items: list[WorkItem]) -> list[WorkItem]:
 class WorkStore(ABC):
     """The work axis: raw intake plus a three-status item state machine.
 
+    An adapter keeps concurrent state changes on one store apart — the
+    filesystem store with a lock around each commit, a database with a
+    transaction.
+
     The status vocabulary + legal-transition graph are core (above); adapters
     implement the abstract primitives and `_effect_transition`. The named
     operations (`start`/`complete`/`drop`) are concrete here so every adapter
@@ -3401,6 +3457,49 @@ class WorkStore(ABC):
     def get(self, slug: str) -> WorkItem | None:
         """Resolve a stable id (slug) to its item, or None. Raises `MultipleMatch`."""
 
+    def renamed(self, slug: str) -> str | None:
+        """The slug `slug` now goes by after `rename`, or None. A store that
+        keeps the slug as a field keeps a table of old names to answer this; one
+        that cannot rename never has an answer."""
+        return None
+
+    def rename(self, slug: str, new_slug: str, *,
+               owner: str = "") -> "tuple[WorkItem, list[str]]":
+        """Give an open item a new slug, rewriting what names it on this store.
+        Returns the renamed item and notes on what was left naming the old one.
+        An adapter checks `rename_refusal` first, which holds every refusal that
+        does not depend on how items are stored."""
+        raise NotImplementedError
+
+    def rename_refusal(self, item: WorkItem, new_slug: str, owner: str) -> str:
+        """The new slug for `item`, or raise `ValueError` saying why it may not
+        be renamed. Storage-neutral: status, fields, holder, and whether the new
+        slug is taken as a live item, a resolved item's record or an old name."""
+        slug = item.slug
+        new = rename_slug(slug, new_slug)
+        if new == slug:
+            raise ValueError(f"{slug} already has that slug")
+        if item.status in RESOLVED_STATUSES:
+            raise ValueError(f"{slug} is {item.status}; only an open item is renamed — "
+                             f"its folder may not exist in other clones, and its "
+                             f"old slug is already recorded as resolved")
+        if item.worktree or item.branch:
+            raise ValueError(
+                f"{slug} has a worktree or branch ({item.branch or item.worktree}), "
+                f"which a rename would strand. Complete or tear that down first, or "
+                f"rename by hand: `git branch -m`, move .worktrees/{slug}, and update "
+                f"the item's `branch` and `worktree` fields")
+        if item.owner and item.owner != owner:
+            raise ValueError(
+                f"{slug} is held by {item.owner}. Run it as them "
+                f"(`TCW_WORK_OWNER={item.owner} tcw work rename {slug} {new_slug}`), "
+                f"or take the item over with `tcw work start {slug} --take-over`")
+        if (self.get(new) is not None or self.tombstone(new) is not None
+                or self.renamed(new) is not None):
+            raise ValueError(f"{new} is already taken by an item, a resolved item's "
+                             f"record, or an earlier rename")
+        return new
+
     @abstractmethod
     def tombstone(self, slug: str) -> Tombstone | None:
         """The record of an item this store once held and has since resolved, or
@@ -3567,6 +3666,35 @@ class WorkStore(ABC):
         """
         return []
 
+    def commit_claim(self, slug: str, owner: str, label: str) -> None:
+        """Record that `owner` holds `slug` — a claim that is not a transition.
+        A store whose writes are already durable only sets the field."""
+        self.set_field(slug, "owner", owner)
+
+    def stray_folders(self, slug: str | None = None) -> list[tuple[Any, list[str]]]:
+        """`(location, files)` for each place named like an item that is not it —
+        what writing through a location held since before a transition leaves
+        behind. A store whose items have no location to go stale has none."""
+        return []
+
+    def duplicate_slugs(self) -> dict[str, list[Any]]:
+        """Slugs held by more than one item. A store that keys items by slug
+        cannot have any."""
+        return {}
+
+    def refresh_for_creation(self) -> None:
+        """Bring the store up to date before a creation writes, where it has a
+        remote copy to fall behind. A store with no copy of its own has nothing
+        to do."""
+
+    def commit_writes(self, message: str, *paths: Any, removed: tuple = (),
+                      publish: bool = True) -> str | None:
+        """Record what a creation just wrote, as a transition records its move.
+        None when recorded or when there is nothing to do; otherwise the rest of
+        a sentence beginning "created X, but …". A store whose every write is
+        already durable — a database, a tracker — records nothing more."""
+        return None
+
     @abstractmethod
     def artifacts(self, slug: str) -> list[Artifact]:
         """The bounded lifecycle artifact set for `slug`, with presence only.
@@ -4398,10 +4526,14 @@ class WorkStore(ABC):
         if not text or "/" in text:
             return False, ""
         try:
+            renamed = self.renamed(text)
             live = self.get(text)
+            if live is None and renamed:
+                live = self.get(renamed)
             if live is not None:
                 return live.status in RESOLVED_STATUSES, ""
-            return self.tombstone(text) is not None, ""
+            # Resolved under its new slug, whose record is the one written.
+            return self.tombstone(renamed or text) is not None, ""
         except Exception:                          # a blocker never fails its reader
             return False, ""
 
@@ -4421,6 +4553,10 @@ class WorkStore(ABC):
             elif "slug" in b:
                 try:
                     blocker = self.get(b["slug"])
+                    # A renamed blocker is still the same work: follow it, or a
+                    # reference the rename could not rewrite would unblock.
+                    if blocker is None and (renamed := self.renamed(b["slug"])):
+                        blocker = self.get(renamed)
                 except ValueError:
                     # An adapter can refuse to settle a blocker — a claim on it
                     # was abandoned. That is still a blocker, and reporting it as
@@ -4495,11 +4631,11 @@ class WorkStore(ABC):
         a transition is the wrong shape — so the refusal names the file and the
         action instead.
 
-        This is the *only* transition the artifact gates. `complete` from
-        `review` is unaffected on either resolution: a present
-        `refined-outcome.md` is the normal path into `--resolution done`, and
-        abandoning verified work as `wontfix` is a legitimate decision. Only
-        `rework` asserts the opposite of what the file says.
+        `complete` from `review` gates on the same file the other way round: it
+        needs it for `--resolution done`, since the file is what says the work
+        was accepted. Abandoning verified work as `wontfix` is a legitimate
+        decision, so a discard needs nothing. Only `rework` asserts the opposite
+        of what the file says.
         """
         if any(a.name == "refined-outcome" and a.present
                for a in self.artifacts(slug)):
@@ -4571,6 +4707,19 @@ class WorkStore(ABC):
                 if blockers:
                     raise ValueError("blocked by: " + ", ".join(blockers)
                                      + " (use --force to override)")
+            # Shipping out of review needs the verify stage's acceptance record.
+            # Without it nothing distinguishes accepted work from work nobody
+            # verified — and the usual way it goes missing is quiet: written to
+            # the folder the item left at `submit`. Completing from `active`
+            # skips verify on purpose (the CLI says so), and an epic closing
+            # from `backlog` never had one; neither is refused.
+            # An epic is exempt: its children carry the verification, and
+            # `reconcile --complete-when-ready` closes it with no `--force`.
+            if dest == "completed" and item.status == "review" \
+                    and item.type != "epic" and not any(
+                    a.name == "refined-outcome" and a.present
+                    for a in self.artifacts(slug)):
+                raise ValueError(refined_outcome_missing(slug))
         # The resolution rides the transition rather than preceding it: written
         # first, a `complete` that then loses the move would leave its resolution
         # on the item the winner moved — an item reading `wontfix` in