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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tcw-cli
-Version: 2.8.0
+Version: 2.8.2
 Summary: Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project.
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -218,8 +218,8 @@ Dynamic: license-file
 
 TCW keeps three things about a software project inside the repository, next to
 the code: what the project deals with, what a user can do with it, and what is
-being changed. One command-line tool, `tcw`, and an agent plugin for Claude Code
-and Codex keep all three in step with the code.
+being changed. One command-line tool, `tcw`, and an agent plugin for Claude Code,
+Codex, and Pi keep all three in step with the code.
 
 | Component        | Answers                                                 |
 | ---------------- | ------------------------------------------------------- |
@@ -309,7 +309,28 @@ skill — it runs the same install script Claude runs automatically. Every tcw
 skill also asks the agent to run the plugin's version check once per session,
 which warns when the CLI and the skills come from different releases.
 
-The plugin ships the skills and read-only review agents described in
+In **Pi**:
+
+```bash
+pi install git:github.com/brocef/TCW
+```
+
+Add `-l` to install for the current project instead of your personal settings.
+For a development checkout, use `pi install /absolute/path/to/TCW`.
+Start a new Pi session, then run `/skill:setup` to install or check the `tcw`
+CLI. You can also install it yourself with `pipx install tcw-cli`.
+Invoke skills with `/skill:work`, `/skill:capabilities`, or `/skill:taxonomy`.
+
+Pi loads the same skills through the official `pi` declaration in `package.json`.
+It does not run TCW's Claude session-start hook or shell injections; the skills
+provide explicit commands for setup, version checks, and lifecycle instructions.
+Claude's custom review agents are not installed as Pi agents. When delegation
+is unavailable, run ordinary lifecycle stages in the main session; autonomous
+work still requires the advisors named by that workflow.
+Git installation also installs the repository's Node package dependencies,
+which support the TCW web app; local-path installation uses the checkout directly.
+
+The plugin ships the skills and Claude Code read-only review agents described in
 [Skills and Agents](#skills-and-agents).
 
 ### CLI
@@ -702,7 +723,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; with `--already-integrated`, the branch is not merged into `HEAD`; 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; its worktree holds commits on no branch; 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                         |
@@ -940,7 +961,7 @@ resolve, what has to be true before an item completes. What a command cannot
 decide (what a request really asks for, whether a spec is good enough, whether
 the work is finished) is judgment, and the plugin's skills guide an agent through
 it. Skills name `tcw` commands and never reimplement them. Every entry point is a
-skill, so they work the same way under Claude Code and Codex.
+skill, with the same CLI-backed lifecycle under Claude Code, Codex, and Pi.
 
 The skills for a single axis are listed in that axis's section above. These cut
 across the axes.

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

@@ -2,8 +2,8 @@
 
 TCW keeps three things about a software project inside the repository, next to
 the code: what the project deals with, what a user can do with it, and what is
-being changed. One command-line tool, `tcw`, and an agent plugin for Claude Code
-and Codex keep all three in step with the code.
+being changed. One command-line tool, `tcw`, and an agent plugin for Claude Code,
+Codex, and Pi keep all three in step with the code.
 
 | Component        | Answers                                                 |
 | ---------------- | ------------------------------------------------------- |
@@ -93,7 +93,28 @@ skill — it runs the same install script Claude runs automatically. Every tcw
 skill also asks the agent to run the plugin's version check once per session,
 which warns when the CLI and the skills come from different releases.
 
-The plugin ships the skills and read-only review agents described in
+In **Pi**:
+
+```bash
+pi install git:github.com/brocef/TCW
+```
+
+Add `-l` to install for the current project instead of your personal settings.
+For a development checkout, use `pi install /absolute/path/to/TCW`.
+Start a new Pi session, then run `/skill:setup` to install or check the `tcw`
+CLI. You can also install it yourself with `pipx install tcw-cli`.
+Invoke skills with `/skill:work`, `/skill:capabilities`, or `/skill:taxonomy`.
+
+Pi loads the same skills through the official `pi` declaration in `package.json`.
+It does not run TCW's Claude session-start hook or shell injections; the skills
+provide explicit commands for setup, version checks, and lifecycle instructions.
+Claude's custom review agents are not installed as Pi agents. When delegation
+is unavailable, run ordinary lifecycle stages in the main session; autonomous
+work still requires the advisors named by that workflow.
+Git installation also installs the repository's Node package dependencies,
+which support the TCW web app; local-path installation uses the checkout directly.
+
+The plugin ships the skills and Claude Code read-only review agents described in
 [Skills and Agents](#skills-and-agents).
 
 ### CLI
@@ -486,7 +507,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; with `--already-integrated`, the branch is not merged into `HEAD`; 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; its worktree holds commits on no branch; 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                         |
@@ -724,7 +745,7 @@ resolve, what has to be true before an item completes. What a command cannot
 decide (what a request really asks for, whether a spec is good enough, whether
 the work is finished) is judgment, and the plugin's skills guide an agent through
 it. Skills name `tcw` commands and never reimplement them. Every entry point is a
-skill, so they work the same way under Claude Code and Codex.
+skill, with the same CLI-backed lifecycle under Claude Code, Codex, and Pi.
 
 The skills for a single axis are listed in that axis's section above. These cut
 across the axes.

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

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

tcw_cli-2.8.2/tcw/__init__.py

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

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

@@ -19,7 +19,9 @@ from tcw.store.fs import (
     FsWorkStore, declared_repository, find_node_root, git_root, init,
     provisioned_store_root,
 )
+from tcw.store.base import MultipleMatch
 from tcw.store.project import FsProjectRegistry
+from tcw.store.yaml_source import load as _load_named_yaml
 import yaml
 from tcw.taxonomy import cli as taxonomy_cli
 from tcw.work import cli as work_cli
@@ -56,7 +58,8 @@ def run_init(components: list[str], project_id: str | None = None,
     sentinel = root / SENTINEL
     if project_id is None:
         try:
-            configured = yaml.safe_load(sentinel.read_text(encoding="utf-8")) if sentinel.exists() else {}
+            configured = (_load_named_yaml(sentinel.read_text(encoding="utf-8"), sentinel)
+                          if sentinel.exists() else {})
         except yaml.YAMLError as error:
             print(f"tcw init: invalid {SENTINEL}: {error}", file=sys.stderr)
             return 1
@@ -548,7 +551,10 @@ def main(argv: list[str] | None = None) -> int:
     args = build_parser().parse_args(_normalize(argv))
     try:
         return args.func(args)
-    except ValueError as error:
+    except (ValueError, MultipleMatch) as error:
+        # `MultipleMatch` is not a `ValueError`, so a verb that does not catch it
+        # itself — `start`, `submit` — printed a traceback for a slug two folders
+        # hold. Its message names both folders; this is only the safety net.
         print(f"tcw: {error}", file=sys.stderr)
         return 1
     except yaml.YAMLError as error:
@@ -557,7 +563,7 @@ def main(argv: list[str] | None = None) -> int:
         # twenty-odd `load_yaml` calls that do not catch it: refusing is already
         # the right answer at every one of them — `init` must not overwrite a
         # config it cannot read — and only the presentation was wrong. The
-        # loader's message names the file.
+        # loader's message names the file (`tcw.store.yaml_source.load`).
         print(f"tcw: {error}", file=sys.stderr)
         return 1
     except subprocess.CalledProcessError as error:

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

@@ -20,7 +20,8 @@ from urllib.parse import unquote, urlparse
 from tcw.work.projection import work_item_json
 from tcw.store.base import (
     CAP_FIELDS, CAP_STATUSES, WORK_ARTIFACTS, WORK_SIDECARS, _UNSET,
-    IllegalTransition, PublicationError, RefError, StaleRevision, TransitionCommitError,
+    IllegalTransition, MultipleMatch, PublicationError, RefError, StaleRevision,
+    TransitionCommitError,
 )
 from tcw.store.fs import (
     FsCapabilitiesStore, FsTaxonomyStore, FsWorkStore, descendant_nodes,
@@ -300,6 +301,9 @@ def _map_store_error(e: Exception) -> tuple[int, bytes]:
         # because strict-tracker and generated-sidecar refusals are 409 too and
         # must show their own message instead.
         return _err(HTTPStatus.CONFLICT, str(e), code="stale-revision")
+    if isinstance(e, MultipleMatch):
+        # Two folders hold the slug: the data needs fixing, not the request.
+        return _err(HTTPStatus.CONFLICT, str(e))
     if isinstance(e, IllegalTransition):
         return _err(HTTPStatus.UNPROCESSABLE_ENTITY, str(e))
     if isinstance(e, RefError):
@@ -551,8 +555,17 @@ class TcwHandler(BaseHTTPRequestHandler):
         for root, prefix in self._board_roots():
             work = FsWorkStore.open(root)
             for it in work.board():
-                items.append(_item_payload(work, it.slug, it,
-                                           f"{prefix}{it.slug}" if prefix else None))
+                try:
+                    items.append(_item_payload(work, it.slug, it,
+                                               f"{prefix}{it.slug}" if prefix else None))
+                except MultipleMatch:
+                    # Two folders hold the slug, so its artifacts cannot be
+                    # read. Listed with none, so one duplicate does not take the
+                    # board down; the item's own route says why.
+                    data = work_item_json(it, [])
+                    if prefix:
+                        data["slug"] = f"{prefix}{it.slug}"
+                    items.append(data)
         return items
 
     def _board_roots(self) -> list[tuple[Path, str]]:
@@ -580,6 +593,8 @@ class TcwHandler(BaseHTTPRequestHandler):
             return
         try:
             self._get()
+        except MultipleMatch as e:
+            self._send(HTTPStatus.CONFLICT, str(e).encode("utf-8"))
         except Exception as e:
             self._send(HTTPStatus.INTERNAL_SERVER_ERROR, str(e).encode("utf-8"))
 
@@ -588,6 +603,8 @@ class TcwHandler(BaseHTTPRequestHandler):
             return
         try:
             self._post()
+        except MultipleMatch as e:
+            self._send(HTTPStatus.CONFLICT, str(e).encode("utf-8"))
         except Exception as e:
             self._send(HTTPStatus.INTERNAL_SERVER_ERROR, str(e).encode("utf-8"))
 
@@ -596,6 +613,8 @@ class TcwHandler(BaseHTTPRequestHandler):
             return
         try:
             self._patch()
+        except MultipleMatch as e:
+            self._send(HTTPStatus.CONFLICT, str(e).encode("utf-8"))
         except Exception as e:
             self._send(HTTPStatus.INTERNAL_SERVER_ERROR, str(e).encode("utf-8"))
 
@@ -604,6 +623,8 @@ class TcwHandler(BaseHTTPRequestHandler):
             return
         try:
             self._put()
+        except MultipleMatch as e:
+            self._send(HTTPStatus.CONFLICT, str(e).encode("utf-8"))
         except Exception as e:
             self._send(HTTPStatus.INTERNAL_SERVER_ERROR, str(e).encode("utf-8"))
 
@@ -612,6 +633,8 @@ class TcwHandler(BaseHTTPRequestHandler):
             return
         try:
             self._delete()
+        except MultipleMatch as e:
+            self._send(HTTPStatus.CONFLICT, str(e).encode("utf-8"))
         except Exception as e:
             self._send(HTTPStatus.INTERNAL_SERVER_ERROR, str(e).encode("utf-8"))
 

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

@@ -4339,7 +4339,9 @@ class WorkStore(ABC):
             remedies.append("Fix or replace each damaged state.yaml "
                             "(`tcw validate` lists them)")
         if any(reason == _HELD_TWICE for _, reason in found):
-            remedies.append("remove the extra folder of each slug held twice")
+            remedies.append("keep one folder of each slug held twice, merge any "
+                            "files it lacks from the others, and remove them "
+                            "(`tcw validate` names both folders)")
         remedy = "; ".join(remedies)
         many = len(blockers) > 1
         raise self._unreadable_refusal(
@@ -4449,8 +4451,12 @@ class WorkStore(ABC):
         holds its epic open). Built on `initiative_children` (cross-node in
         adapters that override it), so the "all resolved" signal and the
         `complete` gate share one source of truth. An empty epic is not
-        completable (nothing resolved)."""
-        if not self.epic_children_all_resolved(item):
+        completable (nothing resolved). Nor is one whose slug two folders hold:
+        which of them would close cannot be known."""
+        try:
+            if not self.epic_children_all_resolved(item):
+                return False
+        except MultipleMatch:
             return False
         # `complete` refuses while anything beneath the epic by `parent` is open,
         # so calling it ready then would promise a close that cannot happen —
@@ -4557,6 +4563,11 @@ class WorkStore(ABC):
                     # reference the rename could not rewrite would unblock.
                     if blocker is None and (renamed := self.renamed(b["slug"])):
                         blocker = self.get(renamed)
+                except MultipleMatch:
+                    # Still a blocker, and said why, since nothing else in this
+                    # item's refusal would explain it.
+                    out.append(f"{b['slug']} (held by more than one folder)")
+                    continue
                 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

{tcw_cli-2.8.0 → tcw_cli-2.8.2}/tcw/store/config_edit.py

@@ -40,6 +40,7 @@ from dataclasses import dataclass
 from pathlib import Path
 
 import yaml
+from tcw.store.yaml_source import load as _load_named_yaml
 
 
 class ConfigEditRefused(ValueError):
@@ -131,7 +132,7 @@ def edit_text(path: Path, text: str | None, edits: list[Edit]) -> str | None:
         if not target:
             return None
         return yaml.safe_dump(target, sort_keys=False, allow_unicode=True)
-    mapping = _load(text)
+    mapping = _load(text, path)
     if not isinstance(mapping, dict):
         mapping = {}
     target = intended(mapping, edits)
@@ -167,9 +168,9 @@ def edit_text(path: Path, text: str | None, edits: list[Edit]) -> str | None:
 
 # ── reading ─────────────────────────────────────────────────────────────────
 
-def _load(text: str):
+def _load(text: str, path: Path | str = "the edited text"):
     from tcw.store.fs import _UniqueKeyLoader    # fs.py imports this module
-    return yaml.load(text, Loader=_UniqueKeyLoader)
+    return _load_named_yaml(text, path, _UniqueKeyLoader)
 
 
 def _assemble(text: str, replacements: list[_Replacement]) -> str:

{tcw_cli-2.8.0 → tcw_cli-2.8.2}/tcw/store/fs.py

@@ -37,6 +37,7 @@ except ImportError:                                # not POSIX
 
 import yaml
 
+from tcw.store.yaml_source import load as _load_named_yaml
 from tcw.store.base import (
     _HELD_TWICE, BODY_ORDER, CAP_FIELDS, CAP_LIFECYCLES, CAP_PRIORITIES, CAP_STATUSES,
     DEFAULT_DOD, InboxEntryNotFound,
@@ -1134,7 +1135,21 @@ def branch_integration(node_root: Path, branch: str) -> str | None:
     Fails closed. A `git` without `merge-tree --write-tree` (older than 2.38)
     exits non-zero, which reads as "not shown to be merged", the same as a
     conflict does. Never run against the store's repository: the branch belongs
-    to the code the node's checkout holds."""
+    to the code the node's checkout holds.
+
+    **A repository's own merge drivers do not get a say.** `merge-tree` runs
+    them, and one configured to keep `HEAD`'s side (`merge.<name>.driver=true`
+    under a `merge=<name>` attribute, from any attributes file) hides every
+    change the branch made to a file both sides touched — the trial then
+    produces `HEAD`'s tree and a branch that was never merged would be deleted.
+    Every configured driver is replaced by `false` for the trial, so any file one
+    would decide becomes a conflict. That refusal rests on the **exit code**, not
+    the tree: git keeps `HEAD`'s side when the driver fails, so the tree still
+    matches — comparing trees alone would reopen this. The cost: a squash merge
+    touching such a file on both sides is not confirmed, and the way out is the
+    one every refusal names. Passed with `-c`, last on the command line, because
+    that beats an inherited `GIT_CONFIG_PARAMETERS` — which git exports to hooks
+    run under `git -c` — where the `GIT_CONFIG_COUNT` variables do not."""
     if git_root(node_root) is None:
         return (f"the primary checkout at {node_root} is not in a git repository, "
                 f"so {branch} cannot be checked")
@@ -1159,7 +1174,16 @@ def branch_integration(node_root: Path, branch: str) -> str | None:
     ref = f"refs/heads/{branch}"
     if run("merge-base", "--is-ancestor", ref, "HEAD").returncode == 0:
         return None
-    merged = run("merge-tree", "--write-tree", "HEAD", ref)
+    drivers, unusable = _merge_drivers(node_root)
+    if unusable:
+        return (f"{branch} cannot be checked against HEAD {head} ({current}): "
+                f"{unusable}. Pull the merge into this checkout, or merge {branch}, "
+                f"then re-run")
+    # `union` too, configured or not: the built-in keeps both sides' lines, so a
+    # line the branch deleted and `HEAD` changed comes back as `HEAD`'s.
+    overrides = [a for name in dict.fromkeys([*drivers, "union"])
+                 for a in ("-c", f"merge.{name}.driver=false")]
+    merged = run(*overrides, "merge-tree", "--write-tree", "HEAD", ref)
     tree = run("rev-parse", "HEAD^{tree}").stdout.strip()
     if merged.returncode == 0 and merged.stdout.split("\n", 1)[0].strip() == tree:
         return None
@@ -1169,17 +1193,105 @@ def branch_integration(node_root: Path, branch: str) -> str | None:
         detail = (merged.stderr.strip().splitlines() or ["no output"])[0]
         return (f"git could not check whether {branch} is merged into HEAD {head} "
                 f"({detail}); `git merge-tree --write-tree` needs git 2.38 or newer")
+    because = (f" This repository defines its own merge drivers "
+               f"({', '.join(drivers)}), which this check does not let decide a "
+               f"file (nor git's `union`), so a squash merge touching a file one "
+               f"governs is not confirmed." if drivers else "")
     return (f"{branch} is not merged into this checkout's HEAD {head} ({current}): "
-            f"merging it would still change files. Pull the merge into this "
-            f"checkout, or merge {branch}, then re-run")
+            f"merging it would still change files.{because} Pull the merge into "
+            f"this checkout, or merge {branch}, then re-run")
+
+
+def _merge_drivers(node_root: Path) -> tuple[list[str], str | None]:
+    """The names of the custom merge drivers configured for the node's
+    repository — every scope, includes and the environment's too — and a reason
+    the trial merge cannot be trusted, or None.
+
+    A name holding `=` cannot be written as `-c merge.<name>.driver=false`, and
+    git failing to list them at all (a malformed config) leaves unknown what
+    would run; both fail closed."""
+    r = _git(["git", "-C", str(node_root), "config", "--null", "--name-only",
+              "--get-regexp", r"^merge\..+\.driver$"], capture_output=True, text=True)
+    if r.returncode == 1:
+        return [], None                                # none configured
+    if r.returncode != 0:
+        detail = (r.stderr.strip().splitlines() or ["no output"])[0]
+        return [], f"git could not list the repository's merge drivers ({detail})"
+    names = list(dict.fromkeys(key[len("merge."):-len(".driver")]
+                               for key in r.stdout.split("\0") if key))
+    if odd := [n for n in names if "=" in n]:
+        return names, (f"it configures a merge driver whose name holds '=' "
+                       f"({', '.join(odd)}), which this check cannot switch off")
+    return names, None
+
+
+UNBRANCHED_SHOWN = 10
+
+
+def unbranched_commits(worktree: Path) -> "list[str] | str":
+    """Short hashes of the commits removing `worktree` would lose — reachable
+    from its `HEAD` and from no branch, tag or remote-tracking branch — or a
+    reason when git cannot say. `[]` when there is no such folder.
+
+    Only a detached `HEAD` can hold them: a worktree on a branch is covered by
+    `--branches`. `--all` would not do, since it counts every worktree's `HEAD`,
+    this one's included. A stash is deliberately not counted as keeping a commit:
+    it is a scratch area people clear without thinking of it as a save.
+
+    `git worktree remove` also deletes the worktree's own reflog, so these
+    commits then survive only as unreachable objects until garbage collection.
+
+    Checked to be the worktree's own top first: `.worktrees/` sits inside the
+    primary checkout, so `git -C` on a plain folder there answers silently for
+    the *primary checkout* — naming its commits as this folder's."""
+    if not worktree.is_dir():
+        return []
+    run = lambda *a: _git(["git", "-C", str(worktree), *a],   # noqa: E731
+                          capture_output=True, text=True)
+    top = run("rev-parse", "--show-toplevel")
+    # By folder identity, not text: git spells the path as the disk does, and a
+    # project reached through an override in other letter case spells it its way.
+    if top.returncode != 0 or not top.stdout.strip() or \
+            not _same_folder(Path(top.stdout.strip()), worktree):
+        return f"git could not check {worktree}: it is not a git worktree of its own"
+    r = run("rev-list", "--abbrev-commit", "HEAD",
+            "--not", "--branches", "--tags", "--remotes")
+    if r.returncode != 0:
+        detail = (r.stderr.strip().splitlines() or ["no output"])[0]
+        return f"git could not check {worktree} ({detail})"
+    return r.stdout.split()
+
+
+def unbranched_summary(commits: list[str]) -> str:
+    """`commits` as a refusal names them: at most `UNBRANCHED_SHOWN`."""
+    shown = ", ".join(commits[:UNBRANCHED_SHOWN])
+    more = len(commits) - UNBRANCHED_SHOWN
+    return shown + (f" and {more} more" if more > 0 else "")
+
+
+def unbranched_problem(worktree: Path) -> str | None:
+    """Why `worktree` must not be removed, or None when nothing would be lost."""
+    found = unbranched_commits(worktree)
+    if isinstance(found, str):
+        return f"{found}, so it was not removed"
+    if not found:
+        return None
+    return (f"the worktree at {worktree} has commits on no branch — "
+            f"{unbranched_summary(found)} — and removing it would lose them. Save "
+            f"them with `git -C {worktree} branch <name>`, then remove it with "
+            f"`git worktree remove {worktree}`")
 
 
 def remove_worktree(node_root: Path, slug: str, branch: str | None = None) -> list[str]:
     """Best-effort teardown (Spec 2 §3.4): `git worktree remove` refuses on a
-    dirty worktree — the safety net against losing uncommitted work. Returns
-    warnings (empty == clean)."""
+    dirty worktree — the safety net against losing uncommitted work — and this
+    refuses one whose detached `HEAD` holds commits no ref does, which git
+    would remove. Returns warnings (empty == clean); a refusal keeps the branch
+    as well as the worktree."""
     warns: list[str] = []
     wt = node_root / WORKTREES_DIR / slug
+    if problem := unbranched_problem(wt):
+        return [problem]
     r = _git(["git", "-C", str(node_root), "worktree", "remove", str(wt)],
              capture_output=True, text=True)
     if r.returncode != 0:
@@ -1547,7 +1659,8 @@ def load_yaml(path: Path, unique: bool = False) -> dict:
     if not path.exists():
         return {}
     text = path.read_text(encoding="utf-8")
-    data = yaml.load(text, Loader=_UniqueKeyLoader if unique else yaml.SafeLoader)
+    data = _load_named_yaml(text, path,
+                            _UniqueKeyLoader if unique else yaml.SafeLoader)
     if data is None:                       # absent content: empty file, or `null`
         return {}
     if not isinstance(data, dict):
@@ -4946,7 +5059,11 @@ class FsWorkStore(FsTreeStore, WorkStore):
             matches = [d for d in self._item_dirs() if d.name == slug]
             if len(matches) <= 1:
                 return matches[0] if matches else None
-        raise MultipleMatch(f"slug resolves to {len(matches)} items: {slug}")
+        raise MultipleMatch(
+            f"{slug} is held by {len(matches)} folders — "
+            f"{', '.join(self._shown_path(d) for d in sorted(matches))}. Keep the one "
+            f"whose state.yaml is right, merge any files it lacks from the others, "
+            f"and remove them; `tcw validate` lists every slug held twice")
 
     def _require_dir(self, slug: str) -> Path:
         d = self._find(slug)
@@ -5260,21 +5377,25 @@ class FsWorkStore(FsTreeStore, WorkStore):
             return "it is not a regular file"
         return None
 
-    @staticmethod
-    def _require_readable_state(d: Path, slug: str) -> None:
-        """Refuse to move an item whose `state.yaml` cannot be read.
+    def _require_readable_state(self, d: Path, slug: str) -> None:
+        """Refuse to move or edit an item whose `state.yaml` cannot be read.
 
         The board reads it through `_safe_yaml`, which degrades a damaged file
         to defaults — no blockers, no owner, no type — so every gate a move
         checks would pass on values the item does not hold, and the strict read
         that follows the move would fail with the item already moved. Asked
         before anything moves, so the refusal means nothing happened. A folder
-        gone meanwhile is the caller's lost race to report, not damage."""
-        reason = FsWorkStore._state_damage(d / "state.yaml")
+        gone meanwhile is the caller's lost race to report, not damage.
+
+        An edit asks too, before its own strict read: that read refuses as well,
+        but with only the parser's text, which names neither item nor file."""
+        state = d / "state.yaml"
+        reason = FsWorkStore._state_damage(state)
         if reason is None:
             return
-        raise ValueError(f"{slug}: state.yaml cannot be read ({reason}); "
-                         f"fix or replace it before changing the item")
+        raise ValueError(f"{slug}: {self._shown_path(state)} cannot be read "
+                         f"({reason}); fix or replace it before changing the item "
+                         f"— `tcw validate` lists every item it cannot read")
 
     def _item_from_dir(self, d: Path) -> WorkItem | None:
         """`None` when the folder went away mid-read — a concurrent claim moved
@@ -5301,27 +5422,28 @@ class FsWorkStore(FsTreeStore, WorkStore):
             return None
         return item if (d / "state.yaml").exists() else None
 
-    @staticmethod
-    def _read_capabilities_sidecar(caps: Path) -> object:
+    def _read_capabilities_sidecar(self, caps: Path) -> object:
         """The parsed sidecar, `None` if it went away, or the `_tcw_parse_error`
         value for anything that cannot be read: one item's bad file must list as
         that item's problem, never take down the board or hang a projection.
         `is_file()` comes first because no exception rescues a read that blocks
-        on a named pipe."""
+        on a named pipe. Problems name the file from the project root, so a
+        parse error says which item's sidecar it is."""
+        shown = self._shown_path(caps)
         problem = None
         try:
             if not caps.is_file():
-                return ({"_tcw_parse_error": f"{caps.name} is not a regular file"}
+                return ({"_tcw_parse_error": f"{shown} is not a regular file"}
                         if caps.exists() else None)
             if caps.stat().st_size > SIDECAR_MAX_BYTES:
-                problem = f"{caps.name} is larger than {SIDECAR_MAX_BYTES} bytes"
+                problem = f"{shown} is larger than {SIDECAR_MAX_BYTES} bytes"
             else:
-                parsed = yaml.safe_load(caps.read_text(encoding="utf-8"))
+                parsed = _load_named_yaml(caps.read_text(encoding="utf-8"), shown)
                 problem = sidecar_value_problem(parsed)
         except FileNotFoundError:
             return None
         except UnicodeDecodeError:
-            problem = f"{caps.name} is not valid UTF-8"
+            problem = f"{shown} is not valid UTF-8"
         except (OSError, ValueError, yaml.YAMLError, RecursionError) as e:
             problem = str(e)
         if problem is not None:
@@ -6977,7 +7099,7 @@ class FsWorkStore(FsTreeStore, WorkStore):
     def dod_checklist(self) -> list[str]:
         p = self.root / "dod.yaml"
         if p.exists():
-            data = yaml.safe_load(p.read_text(encoding="utf-8"))
+            data = _load_named_yaml(p.read_text(encoding="utf-8"), self._shown_path(p))
             if isinstance(data, list):
                 return [str(x) for x in data]
             if isinstance(data, dict) and isinstance(data.get("checklist"), list):
@@ -8154,6 +8276,7 @@ class FsWorkStore(FsTreeStore, WorkStore):
         locations by a move landing between them.
         """
         self._require_repository()
+        self._require_readable_state(d, d.name)
         state = load_yaml(d / "state.yaml")
         state.update(fields)
         self._write_staged([(d / "state.yaml",
@@ -8514,6 +8637,7 @@ class FsWorkStore(FsTreeStore, WorkStore):
         # Read current state. A body write always targets the request, never the
         # read fallback: following it would either mutate raw intake or quietly
         # satisfy the `request` stage with text the author meant as an edit.
+        self._require_readable_state(d, slug)
         state = load_yaml(d / "state.yaml")
         body_path = d / "initial-request.md"
         had_request = self._present(body_path)
@@ -8791,7 +8915,7 @@ class FsWorkStore(FsTreeStore, WorkStore):
         validation = sc_info.get("validation")
         if validation == "yaml_mapping":
             try:
-                parsed = yaml.safe_load(content)
+                parsed = _load_named_yaml(content, self._shown_path(p))
                 if parsed is not None and not isinstance(parsed, dict):
                     raise ValueError(
                         f"sidecar '{name}' must be a YAML mapping, "

{tcw_cli-2.8.0 → tcw_cli-2.8.2}/tcw/store/project.py

@@ -17,6 +17,7 @@ from tcw.store.base import (
     WORK_STATUSES, parse_connected_entry,
 )
 from tcw.store.checkouts import normalized_url, provisioned_root
+from tcw.store.yaml_source import load as _load_named_yaml
 
 SENTINEL = "tcw-config.yaml"
 PROJECT_ID_PATTERN = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
@@ -568,7 +569,8 @@ class FsProjectRegistry(ProjectRegistry):
                                    declaration)
             return None
         try:
-            raw = yaml.load(path.read_text(encoding="utf-8"), Loader=_UniqueKeyLoader) or {}
+            raw = _load_named_yaml(path.read_text(encoding="utf-8"), path,
+                                   _UniqueKeyLoader) or {}
         except (OSError, yaml.YAMLError) as error:
             self._problem(path, f"invalid YAML: {error}")
             return None