tcw-cli 1.2.2__tar.gz → 1.2.3__tar.gz

{tcw_cli-1.2.2/tcw_cli.egg-info → tcw_cli-1.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tcw-cli
-Version: 1.2.2
+Version: 1.2.3
 Summary: Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project.
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -947,6 +947,41 @@ Blocked-ness is a **derived overlay**: an item is blocked when it has at least
 one unresolved blocker recorded in its data — there is no separate "blocked"
 folder or status.
 
+### References to work that is finished
+
+Resolving an item takes its documents out of the tracked tree, so a
+`tcw://W/<slug>` link to it would have nothing to resolve against. Completing
+and discarding therefore **record the slug**, in `graveyard.yaml` beside the
+status folders, and the record rides the same commit as the status change. A
+reference to finished work then keeps resolving: `tcw validate` says nothing
+about it, and `tcw serve` shows it inert rather than broken. A reference to a
+slug the project never held is still an error, in the same words as before —
+that distinction is the whole point of the record.
+
+The record says the slug existed and how it was resolved. It deliberately does
+**not** say where the documents went: any such pointer stops working the moment
+history is squashed, rebased, or shallowly cloned, and a pointer that quietly
+breaks is worse than none. How long resolved documents are kept stays your
+call — `completed/` and `discarded/` are gitignored by default, and a project
+that wants them in the tracked tree simply does not ignore them.
+
+For work resolved **before** your project kept these records — including
+everything resolved before this feature existed — record a slug by hand:
+
+```bash
+tcw work tombstone add <slug> --resolution done --resolved 2026-09-01
+```
+
+Both flags are optional; omit them when nobody kept the detail, since the
+record's job is to say the slug existed.
+
+Run it wherever you are — including on the machine that resolved the work, where
+the item's folder is usually still sitting on disk. It refuses only a slug that
+is *live*, and a slug already in the graveyard, so re-running it over a list is
+safe and will not quietly replace a good record with a blank one. It commits
+what it writes, and on a store with a configured remote it publishes too, since
+a record nobody else can see does not do its job.
+
 ### Binding your own skills and commands to the lifecycle
 
 The lifecycle has named **stages** (each producing one document) and named

{tcw_cli-1.2.2 → tcw_cli-1.2.3}/README.md

@@ -731,6 +731,41 @@ Blocked-ness is a **derived overlay**: an item is blocked when it has at least
 one unresolved blocker recorded in its data — there is no separate "blocked"
 folder or status.
 
+### References to work that is finished
+
+Resolving an item takes its documents out of the tracked tree, so a
+`tcw://W/<slug>` link to it would have nothing to resolve against. Completing
+and discarding therefore **record the slug**, in `graveyard.yaml` beside the
+status folders, and the record rides the same commit as the status change. A
+reference to finished work then keeps resolving: `tcw validate` says nothing
+about it, and `tcw serve` shows it inert rather than broken. A reference to a
+slug the project never held is still an error, in the same words as before —
+that distinction is the whole point of the record.
+
+The record says the slug existed and how it was resolved. It deliberately does
+**not** say where the documents went: any such pointer stops working the moment
+history is squashed, rebased, or shallowly cloned, and a pointer that quietly
+breaks is worse than none. How long resolved documents are kept stays your
+call — `completed/` and `discarded/` are gitignored by default, and a project
+that wants them in the tracked tree simply does not ignore them.
+
+For work resolved **before** your project kept these records — including
+everything resolved before this feature existed — record a slug by hand:
+
+```bash
+tcw work tombstone add <slug> --resolution done --resolved 2026-09-01
+```
+
+Both flags are optional; omit them when nobody kept the detail, since the
+record's job is to say the slug existed.
+
+Run it wherever you are — including on the machine that resolved the work, where
+the item's folder is usually still sitting on disk. It refuses only a slug that
+is *live*, and a slug already in the graveyard, so re-running it over a list is
+safe and will not quietly replace a good record with a blank one. It commits
+what it writes, and on a store with a configured remote it publishes too, since
+a record nobody else can see does not do its job.
+
 ### Binding your own skills and commands to the lifecycle
 
 The lifecycle has named **stages** (each producing one document) and named

{tcw_cli-1.2.2 → tcw_cli-1.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tcw-cli"
-version = "1.2.2"
+version = "1.2.3"
 description = "Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project."
 readme = "README.md"
 requires-python = ">=3.11"

tcw_cli-1.2.3/tcw/__init__.py

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

{tcw_cli-1.2.2 → tcw_cli-1.2.3}/tcw/capabilities/cli.py

@@ -4,7 +4,7 @@ import argparse
 import sys
 
 from tcw.stdin import read_piped_stdin
-from tcw.store.base import Capability, RefError
+from tcw.store.base import Capability, RefError, resolution_status
 from tcw.store.base import AmbiguousRef
 from tcw.store.fs import FsCapabilitiesStore, find_node, git_root
 
@@ -184,9 +184,15 @@ def _drift(args: argparse.Namespace) -> int:
 
 
 def _shipped_but_missing(node, st) -> list[tuple[str, str]]:
-    """Local Missing capabilities whose `Planning doc` names a completed work item.
+    """Local Missing capabilities whose `Planning doc` names work that shipped.
+
     Read-only follow of an existing capability→work forward pointer; degrades to
-    empty when no work node is present (no hard cross-axis dependency)."""
+    empty when no work node is present (no hard cross-axis dependency).
+
+    "Shipped" is answered from the live item where there is one and from its
+    tombstone where there is not, so the verdict is a property of the project
+    rather than of whose working directory it runs in.
+    """
     from tcw.store.fs import FsWorkStore
     try:
         work = FsWorkStore.open(node)          # the *configured* store, wherever it is
@@ -199,16 +205,37 @@ def _shipped_but_missing(node, st) -> list[tuple[str, str]]:
         slug = c.fields.get("Planning doc")
         if not slug:
             continue
-        try:
-            item = work.get(str(slug))
-        except Exception:
-            item = None
         # `completed` alone, deliberately NOT `RESOLVED_STATUSES`: this asks
         # "did it ship?", not "is it closed?". A discarded item's capability is
         # *supposed* to stay Missing (or be marked Omitted) — reporting it as
         # shipped-but-unreconciled would be a false positive, which is exactly
         # what happened before `discarded` existed.
-        if item is not None and item.status == "completed":
+        #
+        # Asked of the tombstone as well as the item, because `get()` alone made
+        # the answer depend on who was asking: a resolved item's folder is
+        # gitignored, so it is present for whoever ran the transition and reaches
+        # no other clone. `get()` answered there and returned None everywhere
+        # else, so this reported drift on one machine and "no capability drift"
+        # in CI — failing in the quiet direction, which is the one nobody
+        # notices. `resolution_status` maps the record onto the same status
+        # `complete()` derives, so the ship/abandon distinction above is drawn
+        # once rather than twice.
+        try:
+            item = work.get(str(slug))
+            if item is not None:
+                shipped = item.status == "completed"
+            else:
+                grave = work.tombstone(str(slug))
+                # No record: the slug names nothing this store ever held, which
+                # is a typo, not finished work. An unrecorded resolution: the
+                # store held it but nobody kept how it ended — report nothing
+                # rather than guess, because guessing wrong here means calling
+                # abandoned work shipped.
+                shipped = bool(grave and grave.resolution
+                               and resolution_status(grave.resolution) == "completed")
+        except Exception:
+            shipped = False                    # a store that cannot answer is silent
+        if shipped:
             out.append((c.path, str(slug)))
     return out
 

{tcw_cli-1.2.2 → tcw_cli-1.2.3}/tcw/refs.py

@@ -8,9 +8,16 @@ Grammar: ``tcw://[<namespace>/]<axis>/<ref>``
 
 `parse_tcw_uri` is a pure, total function (never raises) — the abstract grammar.
 `resolve_tcw_ref` is thin CLI/serve adapter glue: it imports the FS stores and
-dispatches through their existing ``get()`` / ``resolve_qualified_work_ref`` (no
-new store-interface method — litmus-clean), and never propagates a store
-exception to a caller scanning many links.
+dispatches through ``get()`` / ``tombstone()`` / ``resolve_qualified_work_ref``,
+and never propagates a store exception to a caller scanning many links.
+
+This module once recorded that it added *no* new store-interface method. That
+stopped being true when work references learned to tell a resolved item from a
+slug nobody created: `get()` alone cannot draw that distinction, because a store
+whose resolved items leave it answers None to both. `tombstone()` is the second
+abstract read, and it is abstract rather than a filesystem check on purpose —
+any store can answer "did I ever hold this id", and one that keeps its resolved
+items answers it without storing anything extra.
 """
 
 from __future__ import annotations
@@ -44,6 +51,12 @@ class ResolveResult:
     key: str | None
     reason: str
     project: str = ""      # owning project id for a foreign work ref; "" = local
+    # A work ref that resolved to a *record* of a resolved item rather than to a
+    # live one. Still `ok` — the reference is sound and names real, finished work
+    # — but there is nothing to navigate to, so a viewer shows it inert rather
+    # than as a link, and `tcw validate` says nothing at all.
+    archived: bool = False
+    resolution: str = ""   # the archived item's resolution; "" when unrecorded
 
 
 def _segment_ok(seg: str) -> bool:
@@ -130,8 +143,20 @@ def resolve_tcw_ref(node_root: Path | None, uri: str) -> ResolveResult:
         # `tcw://W/<slug>` reporting ok for a slug nobody ever created — passing
         # `tcw validate` and rendering as a link that 404s.
         if store.get(bare) is None:
+            # Not live — but "not live" and "never existed" are different
+            # answers, and reporting them identically is what made this check
+            # machine-dependent: a resolved item's folder is ignored, so it is
+            # present for whoever ran the transition and absent for everyone
+            # else, and the same reference passed there and failed here.
+            grave = store.tombstone(bare)
+            if grave is None:
+                return ResolveResult(
+                    False, "W", None, qualified_work_ref_problem(node_root, ns_ref))
+            local = store.node_root == node_root.resolve()
             return ResolveResult(
-                False, "W", None, qualified_work_ref_problem(node_root, ns_ref))
+                True, "W", bare if local else f"{ns_ref.partition('/')[0]}/{bare}",
+                "", "" if local else ns_ref.partition("/")[0],
+                archived=True, resolution=grave.resolution)
         if store.node_root == node_root.resolve():        # landed locally
             return ResolveResult(True, "W", bare, "")
         # Foreign: the qualifier is a project id (a status-path locator is always

{tcw_cli-1.2.2 → tcw_cli-1.2.3}/tcw/serve/__init__.py

@@ -989,13 +989,37 @@ class TcwHandler(BaseHTTPRequestHandler):
                 r = resolve_tcw_ref(self.server.node_root, uri)
                 # Failure objects carry why, because the viewer renders "valid but
                 # not on this board" differently from "broken". The shape the SPA
-                # branches on: `reason` is exactly one of two values, `project` is
-                # non-empty iff "unhosted-project", `detail` present iff
-                # "unresolved". A bare {"ok": false} never occurs.
+                # branches on: `reason` is exactly one of three values, `project`
+                # is non-empty iff "unhosted-project", `detail` present iff
+                # "unresolved" or "archived", `resolution` present iff
+                # "archived". A bare {"ok": false} never occurs.
                 if not r.ok:
                     result[uri] = {"ok": False, "reason": "unresolved",
                                    "detail": r.reason}
                     continue
+                if r.archived:
+                    # Sound reference, real finished work, nothing to open: the
+                    # item's documents left the tracked tree when it resolved.
+                    # `ok: false` for the same reason an off-board target gets it
+                    # — it is what stops the SPA writing a link that 404s — and
+                    # not the same thing as "broken", which is what this looked
+                    # like before resolved slugs were recorded at all.
+                    #
+                    # A client that knows nothing of `archived` falls through to
+                    # its unrecognized-reason branch, which neutralizes the anchor
+                    # and shows `detail`. That is already the right rendering, so
+                    # no client change is required for this to read correctly.
+                    # "resolved", not "completed": with no resolution recorded
+                    # this covers a discarded item too, and calling abandoned
+                    # work completed would be worse than saying less.
+                    detail = f"{r.key} is resolved work; its documents are no " \
+                             f"longer in the tree"
+                    if r.resolution:
+                        detail = f"{r.key} was resolved as {r.resolution}; its " \
+                                 f"documents are no longer in the tree"
+                    result[uri] = {"ok": False, "reason": "archived",
+                                   "detail": detail, "resolution": r.resolution}
+                    continue
                 if r.project:
                     if hosted is None:
                         hosted = self._hosted_projects()

{tcw_cli-1.2.2 → tcw_cli-1.2.3}/tcw/store/base.py

@@ -1554,6 +1554,26 @@ class WorkItem:
     started: str = ""               # UTC claim timestamp
 
 
+@dataclass(frozen=True)
+class Tombstone:
+    """The record that `slug` named an item this store once held and has since
+    resolved.
+
+    Answers exactly one question — *did this slug ever exist here?* — so that a
+    reference to finished work is distinguishable from a reference to a slug
+    nobody created. `resolution` and `resolved` are context for the reader; both
+    may be empty on a degraded record, and neither changes the answer.
+
+    **There is deliberately no locator.** Recording where the item's documents
+    went would promise they are retrievable there, and that promise does not
+    survive a squash-merge, a rebase, or a shallow clone. A pointer that
+    silently stops working is worse than no pointer.
+    """
+    slug: str
+    resolution: str = ""
+    resolved: str = ""
+
+
 @dataclass
 class Artifact:
     """A named lifecycle artifact associated with a work item."""
@@ -1697,6 +1717,38 @@ class WorkStore(ABC):
     def get(self, slug: str) -> WorkItem | None:
         """Resolve a stable id (slug) to its item, or None. Raises `MultipleMatch`."""
 
+    @abstractmethod
+    def tombstone(self, slug: str) -> Tombstone | None:
+        """The record of an item this store once held and has since resolved, or
+        None if it never held one by that id.
+
+        Distinct from `get`, which answers about *live* items only. An adapter
+        whose resolved items remain retrievable by `get` — a tracker where a
+        closed issue never stops existing — may answer from those directly and
+        keep no separate record at all; one whose resolved items leave the store
+        has to record something at resolution time in order to answer later.
+
+        A `None` here means the store has genuinely never held this id, which is
+        what lets a caller report a typo as a typo.
+        """
+
+    @abstractmethod
+    def record_tombstone(self, slug: str, resolution: str = "",
+                         resolved: str = "") -> Tombstone:
+        """Record that `slug` named an item this store held and has resolved,
+        for one it resolved before it kept any record.
+
+        The backfill half of `tombstone`, and the only way an existing project
+        gets the benefit: every reference written before tombstones existed names
+        an item resolved before any record was kept. An adapter that already
+        answers `tombstone` from its own resolved items has nothing to store and
+        may treat this as a no-op.
+
+        Refuses a `slug` that is currently live — a store cannot both hold an
+        item and have finished with it, and claiming otherwise would let slug
+        assignment refuse an id that is legitimately in use.
+        """
+
     @abstractmethod
     def query(self, status: str | None = None) -> list[WorkItem]: ...