kd-cli 2.8.1__tar.gz → 2.9.0__tar.gz

{kd_cli-2.8.1/kd_cli.egg-info → kd_cli-2.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kd-cli
-Version: 2.8.1
+Version: 2.9.0
 Summary: Knowledge Dispatcher for issue trackers and knowledge bases
 Author: Sergiy Gladkyy
 License-Expression: MIT

{kd_cli-2.8.1 → kd_cli-2.9.0}/kd/cli/namespaces/tag/__init__.py

@@ -138,8 +138,18 @@ class TagShowCommand(Command):
             "show",
             "Show tag details",
             requires_client=True,
-            usage="kd /tag show TAG_NAME",
-            examples=["kd /tag show sprint-47"],
+            usage="kd /tag show TAG_NAME_OR_ID",
+            long_description=(
+                "Accepts either a display name or the tag-id form "
+                "(NN-NN); the id form skips name resolution and is the "
+                "disambiguator when two visible tags share a name. A "
+                "name that resolves to multiple visible tags refuses "
+                "with a candidate list — pass the tag id to pick."
+            ),
+            examples=[
+                "kd /tag show sprint-47",
+                "kd /tag show 10-178",
+            ],
             see_also=["/tag list", "/tag issues"],
         )
 
@@ -162,13 +172,16 @@ class TagCreateCommand(Command):
             requires_client=True,
             usage="kd /tag create TAG_NAME",
             long_description=(
-                "Idempotent: if a tag with the requested name is already "
-                "visible, the command returns ``action: noop`` and does "
-                "not POST. Otherwise the tag is created with "
+                "Idempotent: if exactly one tag with the requested name "
+                "is already visible, the command returns ``action: noop`` "
+                "and does not POST. Otherwise the tag is created with "
                 "``action: created``. Returns a parseable single-line ack: "
                 "the last stdout line is ``ok: <NAME> created`` or "
                 "``ok: <NAME> noop``. Name resolution is case-insensitive "
-                "(same resolver /tag show uses). Pass --quiet to suppress "
+                "(same resolver /tag show uses). When the name collides "
+                "with multiple visible tags, create refuses with a "
+                "candidate list rather than picking one — inspect them "
+                "with ``kd /tag show <id>``. Pass --quiet to suppress "
                 "the detail block above the ack."
             ),
             examples=['kd /tag create "sprint-47"'],
@@ -206,17 +219,25 @@ class TagRenameCommand(Command):
             "rename",
             "Rename a tag",
             requires_client=True,
-            usage="kd /tag rename TAG_NAME NEW_NAME",
+            usage="kd /tag rename TAG_NAME_OR_ID NEW_NAME",
             long_description=(
                 "Returns a parseable single-line ack: the last stdout line "
                 "is ``ok: <NEW_NAME> renamed old_name=<TAG_NAME>``. The "
                 "tail-line ID is the **new name**, since scripts that "
                 "follow the rename refer to the tag by its new identity. "
                 "The previous name is preserved in ``old_name=`` so "
-                "audit/log consumers can correlate. Pass --quiet to "
-                "suppress the detail block above the ack."
+                "audit/log consumers can correlate. The first argument "
+                "accepts either a display name or the tag-id form "
+                "(NN-NN); the id form skips name resolution and is the "
+                "disambiguator when two visible tags share a name. A "
+                "name that resolves to multiple visible tags refuses "
+                "with a candidate list — pass the tag id to pick. Pass "
+                "--quiet to suppress the detail block above the ack."
             ),
-            examples=['kd /tag rename sprint-47 "sprint-48"'],
+            examples=[
+                'kd /tag rename sprint-47 "sprint-48"',
+                'kd /tag rename 10-178 "lifecycle:final"',
+            ],
             see_also=["/tag show"],
         )
         self.display_hint = "mutation"
@@ -244,15 +265,23 @@ class TagDeleteCommand(Command):
             "delete",
             "Delete a tag",
             requires_client=True,
-            usage="kd /tag delete TAG_NAME",
+            usage="kd /tag delete TAG_NAME_OR_ID",
             long_description=(
                 "Returns a parseable single-line ack: the last stdout line "
                 "is ``ok: <NAME> deleted``. --confirm is required and is "
                 "**not** softened by --quiet — the safety gate fires "
-                "before any envelope is rendered. Pass --quiet to suppress "
-                "the detail block above the ack."
+                "before any envelope is rendered. The argument accepts "
+                "either a display name or the tag-id form (NN-NN); the "
+                "id form skips name resolution and is the disambiguator "
+                "when two visible tags share a name. A name that "
+                "resolves to multiple visible tags refuses with a "
+                "candidate list — pass the tag id to pick. Pass "
+                "--quiet to suppress the detail block above the ack."
             ),
-            examples=["kd /tag delete sprint-47 --confirm"],
+            examples=[
+                "kd /tag delete sprint-47 --confirm",
+                "kd /tag delete 10-178 --confirm",
+            ],
             see_also=["/tag list", "/tag create"],
         )
         self.display_hint = "mutation"
@@ -298,13 +327,20 @@ class TagAddCommand(Command):
             "add",
             "Tag an issue or article",
             requires_client=True,
-            usage="kd /tag add ENTITY_ID TAG_NAME",
+            usage="kd /tag add ENTITY_ID TAG_NAME_OR_ID",
             long_description=(
-                "Entity type is auto-detected from the ID format: FB-123 = issue, FB-A-1 = article."
+                "Entity type is auto-detected from the ID format: FB-123 = "
+                "issue, FB-A-1 = article. The tag argument accepts either a "
+                "display name or the tag-id form (NN-NN); the id form skips "
+                "name resolution and is the disambiguator when two tags share "
+                "a name. Adding a name already attached to the entity is an "
+                "idempotent re-tag; adding a name that has multiple visible "
+                "tags refuses with a candidate list — pass the tag id to pick."
             ),
             examples=[
                 "kd /tag add FB-123 sprint-47",
                 "kd /tag add FB-A-1 reviewed",
+                "kd /tag add FB-A-1 10-178",
             ],
             see_also=["/tag remove", "/tag issues"],
         )
@@ -327,10 +363,15 @@ class TagRemoveCommand(Command):
             "remove",
             "Untag an issue or article",
             requires_client=True,
-            usage="kd /tag remove ENTITY_ID TAG_NAME",
+            usage="kd /tag remove ENTITY_ID TAG_NAME_OR_ID",
             long_description=(
                 "Entity type is auto-detected from the ID format: FB-123 = "
-                "issue, FB-A-1 = article. "
+                "issue, FB-A-1 = article. The tag argument is resolved "
+                "against the tags attached to the entity — names that are "
+                "not attached refuse loudly even when a same-name tag "
+                "exists globally. Pass the tag-id form (NN-NN) to skip name "
+                "resolution; this is the disambiguator when multiple "
+                "same-name tags are attached. "
                 "Returns a parseable single-line ack: the last stdout line "
                 "is ``ok: <ENTITY_ID> removed tag=<TAG_NAME>``. The "
                 "entity ID is the primary tail-line ID (``$2``); the "
@@ -340,6 +381,7 @@ class TagRemoveCommand(Command):
             examples=[
                 "kd /tag remove FB-123 sprint-47",
                 "kd /tag remove FB-A-1 reviewed",
+                "kd /tag remove FB-A-1 10-178",
             ],
             see_also=["/tag add", "/tag issues"],
         )
@@ -363,16 +405,26 @@ class TagIssuesCommand(Command):
             "issues",
             "List issues with a tag",
             requires_client=True,
-            usage="kd /tag issues TAG_NAME [--tag TAG ...] [--project P] [--limit N]",
+            usage="kd /tag issues TAG_NAME_OR_ID [--tag TAG ...] [--project P] [--limit N]",
             long_description=(
-                "Lists issues tagged with the given tag.  Single-tag uses the "
+                "Lists issues tagged with the given tag. Single-tag uses the "
                 "fast server-side tag-issues endpoint; multi-tag composes a "
                 "YouTrack query and uses /issues?query=... with AND semantics. "
                 "Use --project to scope results to a single project (forces "
-                "the composed-query path)."
+                "the composed-query path). The tag argument accepts either a "
+                "display name or the tag-id form (NN-NN) on the fast path "
+                "(single tag, no --project); the id form skips name "
+                "resolution and is the disambiguator when two visible tags "
+                "share a name. On the composed-query path (--project set or "
+                "multiple --tag arguments), the id form is rejected because "
+                "YouTrack's ``tag:`` predicate is name-keyed — use the name "
+                "form (which refuses on duplicate-name collision) or the "
+                "fast path. A name that resolves to multiple visible tags "
+                "refuses with a candidate list before the query is composed."
             ),
             examples=[
                 "kd /tag issues sprint-47",
+                "kd /tag issues 10-178",
                 "kd /tag issues blocked --limit 100",
                 "kd /tag issues kind:note --tag component:authservice",
                 "kd /tag issues kind:note --tag component:authservice --project KDCLI",
@@ -414,16 +466,22 @@ class TagArticlesCommand(Command):
             "articles",
             "List articles with a tag",
             requires_client=True,
-            usage="kd /tag articles TAG_NAME [--tag TAG ...] [--project P] [--limit N]",
+            usage="kd /tag articles TAG_NAME_OR_ID [--tag TAG ...] [--project P] [--limit N]",
             long_description=(
                 "Lists articles tagged with the given tag. Uses client-side "
                 "filtering because the YouTrack API has no server-side "
                 "article-by-tag endpoint. Use --project to scope the scan "
                 "to a single project. Repeat --tag to require multiple tags "
-                "(AND semantics)."
+                "(AND semantics). Every tag argument accepts either a "
+                "display name or the tag-id form (NN-NN); the id form "
+                "filters precisely by id and is the disambiguator when "
+                "two visible tags share a name. A name that resolves to "
+                "multiple visible tags refuses with a candidate list — "
+                "pass the tag id to pick."
             ),
             examples=[
                 "kd /tag articles reviewed",
+                "kd /tag articles 10-178",
                 'kd /tag articles "type:guide" --project FB',
                 "kd /tag articles type:case --tag component:authservice -p CMCSA",
                 "kd /tag articles blocked --limit 100",
@@ -484,10 +542,23 @@ class TagEntitiesCommand(Command):
                 "--limit-issues and --limit-articles override per kind.  "
                 "--primer-scope substitutes the primer's pinned tags as an "
                 "OR scope (match=any); mutually exclusive with the positional "
-                "TAG and --tag arguments."
+                "TAG and --tag arguments. "
+                "The tag argument accepts either a display name or the "
+                "tag-id form (NN-NN); the id form skips name resolution "
+                "and is the disambiguator when two visible tags share a "
+                "name. Id-form scope: allowed when the issue half routes "
+                "through the fast path (single tag, no --project) or when "
+                "only --kind article is requested (article filtering is "
+                "client-side by id). With --project or multiple tags AND "
+                "the issue kind included, id-form is rejected because "
+                "YouTrack's ``tag:`` predicate is name-keyed. Names are "
+                "pre-validated before the issue/article fanout — a "
+                "duplicate-name refusal is the whole-command outcome, not "
+                "a partial-success row."
             ),
             examples=[
                 "kd /tag entities kind:note",
+                "kd /tag entities 10-178",
                 "kd /tag entities kind:note --tag component:authservice --project KDCLI",
                 "kd /tag entities kind:note --kind article --limit-articles 5",
                 "kd /tag entities kind:note --limit 20 -o json",

{kd_cli-2.8.1 → kd_cli-2.9.0}/kd/client.py

@@ -23,7 +23,7 @@ import difflib
 import re
 import shlex
 from collections import OrderedDict
-from collections.abc import Callable
+from collections.abc import Callable, Sequence
 from dataclasses import dataclass, field as dataclass_field
 from datetime import datetime, timezone
 from pathlib import Path
@@ -2184,6 +2184,52 @@ def _detect_entity_type(entity_id: str) -> str:
     return "article" if "-A-" in entity_id else "issue"
 
 
+_TAG_ID_RE = re.compile(r"\d+-\d+")
+
+
+def _is_tag_id(s: str) -> bool:
+    """True if *s* matches YouTrack's tag-id shape (``\\d+-\\d+``).
+
+    Names following kd's namespace convention (``lifecycle:draft``)
+    contain ``:`` and never match.
+    """
+    return bool(_TAG_ID_RE.fullmatch(s))
+
+
+# KDCLI-200: retry-line templates for the global tag resolver. Keyed by
+# command verb. ``{id}`` substitutes the candidate's tag id; ``rename``
+# carries a literal ``<new-name>`` placeholder because the operator
+# supplies the new name on retry. ``create`` has no valid retry shape
+# (creating with an existing id is meaningless), so it is absent from
+# this table and uses ``_TAG_INSPECT_HINTS`` instead.
+_TAG_RETRY_TEMPLATES: dict[str, str] = {
+    "show": "kd /tag show {id}",
+    "delete": "kd /tag delete {id}",
+    "rename": "kd /tag rename {id} <new-name>",
+    "issues": "kd /tag issues {id}",
+    "articles": "kd /tag articles {id}",
+    "entities": "kd /tag entities {id}",
+}
+
+# KDCLI-200: trailer-only hint when no valid retry shape exists. Used
+# by ``/tag create`` so an operator who hits a collision can inspect the
+# existing tags without inventing a ``create <id>`` shape.
+_TAG_INSPECT_HINTS: dict[str, str] = {
+    "create": "kd /tag show <id>",
+}
+
+
+def _format_owner(tag: Tag) -> str:
+    """Render the ``owner=`` field for a tag in ambiguity diagnostics.
+
+    ``Tag.owner`` is ``NamedEntity | None`` and ``NamedEntity.name`` is
+    itself ``str | None``, so both branches collapse to ``<unknown>``.
+    """
+    if tag.owner is None:
+        return "<unknown>"
+    return tag.owner.name or "<unknown>"
+
+
 class TagOperations:
     """High-level tag operations with name resolution and entity detection."""
 
@@ -2198,7 +2244,9 @@ class TagOperations:
         self._articles = articles_api
         self._yt = yt
         self._debug = debug_log or DebugLog()
-        self._name_cache: dict[str, str] = {}
+        # KDCLI-200: list-valued cache so display-name collisions can
+        # be detected and refused instead of silently last-one-wins.
+        self._name_cache: dict[str, builtins.list[Tag]] = {}
 
     def list(
         self,
@@ -2261,7 +2309,7 @@ class TagOperations:
         return (matched[:top], cap_hit)
 
     def get(self, name: str) -> Tag:
-        tag_id = self._resolve_tag(name)
+        tag_id = name if _is_tag_id(name) else self._resolve_tag(name, command="show")
         return self._tags.get_tag(tag_id)
 
     def create(self, name: str) -> TagCreateResult:
@@ -2276,11 +2324,11 @@ class TagOperations:
         naming sharing/visibility and name-acceptance as plausible causes.
         """
         try:
-            tag_id = self._resolve_tag(name)
+            tag_id = self._resolve_tag(name, command="create")
         except NotFoundError:
             self._debug.info("api", f"creating tag '{name}'")
             created = self._tags.create_tag(name)
-            self._name_cache[name.lower()] = created.id
+            self._name_cache.setdefault(name.lower(), []).append(created)
             self._debug.info("api", f"created tag '{name}' ({created.id})")
             return TagCreateResult(action="create", tag=created)
         self._debug.info("api", f"tag '{name}' already exists ({tag_id})")
@@ -2288,22 +2336,28 @@ class TagOperations:
         return TagCreateResult(action="exists", tag=existing)
 
     def rename(self, name: str, new_name: str) -> Tag:
-        tag_id = self._resolve_tag(name)
+        tag_id = name if _is_tag_id(name) else self._resolve_tag(name, command="rename")
         self._debug.info("api", f"renaming tag '{name}' → '{new_name}'")
         tag = self._tags.update_tag(tag_id, new_name)
-        del self._name_cache[name.lower()]
-        self._name_cache[new_name.lower()] = tag.id
+        self._invalidate_tag(tag.id)
+        self._name_cache.setdefault(new_name.lower(), []).append(tag)
         return tag
 
     def delete(self, name: str) -> None:
-        tag_id = self._resolve_tag(name)
+        tag_id = name if _is_tag_id(name) else self._resolve_tag(name, command="delete")
         self._debug.info("api", f"deleting tag '{name}' ({tag_id})")
         self._tags.delete_tag(tag_id)
-        self._name_cache.pop(name.lower(), None)
+        self._invalidate_tag(tag_id)
 
     def add(self, entity_id: str, tag: str) -> None:
-        """Add a tag to an issue or article. Entity type is auto-detected."""
-        tag_id = self._resolve_tag(tag)
+        """Add a tag to an issue or article. Entity type is auto-detected.
+
+        Tag resolution is entity-anchored (KDCLI-198 S1): if a same-name
+        tag is already attached, it is reused (idempotent re-tag);
+        otherwise exactly one visible global match is required. The
+        tag-id form (``\\d+-\\d+``) is a passthrough.
+        """
+        tag_id = self._resolve_tag_to_attach(tag, entity_id)
         entity_type = _detect_entity_type(entity_id)
         self._debug.info("api", f"tagging {entity_type} {entity_id} with '{tag}'")
         if entity_type == "article":
@@ -2312,8 +2366,13 @@ class TagOperations:
             self._tags.add_tag_to_issue(entity_id, tag_id)
 
     def remove(self, entity_id: str, tag: str) -> None:
-        """Remove a tag from an issue or article. Entity type is auto-detected."""
-        tag_id = self._resolve_tag(tag)
+        """Remove a tag from an issue or article. Entity type is auto-detected.
+
+        Tag resolution is attached-anchored (KDCLI-198 S1): the name
+        resolves only against the tags attached to the entity. The
+        tag-id form (``\\d+-\\d+``) is a passthrough.
+        """
+        tag_id = self._resolve_attached_tag(tag, entity_id)
         entity_type = _detect_entity_type(entity_id)
         self._debug.info("api", f"untagging {entity_type} {entity_id} from '{tag}'")
         if entity_type == "article":
@@ -2359,8 +2418,35 @@ class TagOperations:
         if not tag_names:
             raise ValidationError("At least one tag is required")
         if len(tag_names) == 1 and project is None:
-            tag_id = self._resolve_tag(tag_names[0])
+            arg = tag_names[0]
+            tag_id = arg if _is_tag_id(arg) else self._resolve_tag(arg, command="issues")
             return self._tags.list_tag_issues(tag_id, top=top, skip=skip)
+        # Multi-tag / project path composes a YouTrack query rather than
+        # hitting ``/tags/{id}/issues``. YouTrack's ``tag:`` predicate is
+        # name-keyed (see docs/specs/001-youtrack-api-reference.md §574
+        # and kd/query_parser.py); there is no id-keyed tag predicate.
+        # Accepting an id-form arg here would emit ``tag: 10-178`` which
+        # YouTrack parses as the literal tag *name* "10-178" — wrong
+        # rows, silently. Refuse before composition; the operator can
+        # use the fast path (single tag, no --project) for id-keyed
+        # precision or pass the name form (which refuses on collision).
+        id_args = [a for a in tag_names if _is_tag_id(a)]
+        if id_args:
+            raise ValidationError(
+                "Tag-id form ("
+                + ", ".join(id_args)
+                + ") is not supported with --project or multiple --tag arguments. "
+                "YouTrack's query DSL identifies tags by name. Use the fast path "
+                "(single tag, no --project) for id-keyed lookup, or pass the name "
+                "form (which refuses on duplicate-name collision)."
+            )
+        # Every name arg is pre-validated via ``_resolve_tag`` so
+        # duplicate visible names never reach the YouTrack query
+        # composition. The resolver result is discarded — the composed
+        # query uses the names directly, with YouTrack handling
+        # server-side matching.
+        for arg in tag_names:
+            self._resolve_tag(arg, command="issues")
         tag_clauses = [f"tag: {youtrack_query_literal(name)}" for name in tag_names]
         joiner = " or " if match == "any" else " and "
         query = joiner.join(tag_clauses)
@@ -2386,7 +2472,10 @@ class TagOperations:
         *top* matches are collected or the article source is exhausted.
         """
         tag_names = [tags] if isinstance(tags, str) else tags
-        tag_ids = frozenset(self._resolve_tag(name) for name in tag_names)
+        tag_ids = frozenset(
+            arg if _is_tag_id(arg) else self._resolve_tag(arg, command="articles")
+            for arg in tag_names
+        )
         self._debug.info("api", f"scanning articles for tags {tag_names} ({tag_ids}) match={match}")
 
         project_id: str | None = None
@@ -2480,6 +2569,38 @@ class TagOperations:
         if not kinds:
             raise ValidationError("At least one kind is required")
 
+        # KDCLI-200: refuse id-form when the issue half would route
+        # through the composed-query path (--project set or multiple
+        # tags) because YouTrack's ``tag:`` predicate is name-keyed —
+        # accepting an id literal there would silently emit wrong
+        # rows. The article half is client-side-filtered by id and
+        # works fine with id-form, so the refusal is scoped to runs
+        # that actually dispatch through ``issues()`` composed query.
+        id_args = [a for a in tag_names if _is_tag_id(a)]
+        issue_dispatched = "issue" in kinds
+        issue_would_compose = project is not None or len(tag_names) > 1
+        if id_args and issue_dispatched and issue_would_compose:
+            raise ValidationError(
+                "Tag-id form ("
+                + ", ".join(id_args)
+                + ") is not supported on /tag entities when the issue half "
+                "would route through a composed query (--project set or "
+                "multiple tags). YouTrack's query DSL identifies tags by "
+                "name. Drop --project and pass a single tag for id-keyed "
+                "issue lookup, restrict to --kind article (which filters "
+                "by id client-side), or use the name form (which refuses "
+                "on duplicate-name collision)."
+            )
+
+        # Pre-validate every name argument before fanout so an
+        # ambiguity diagnostic is the whole-command outcome rather than
+        # a partial-success row. The per-kind ``except KdError`` below
+        # (which converts transport-flavoured failures into a scanned=
+        # False meta entry) MUST NOT swallow resolver refusal.
+        for arg in tag_names:
+            if not _is_tag_id(arg):
+                self._resolve_tag(arg, command="entities")
+
         defaults = limit_per_kind or {}
         limits = {
             "issue": defaults.get("issue", 50),
@@ -2551,22 +2672,301 @@ class TagOperations:
         )
         return TagEntitiesResult(results=results, meta=meta)
 
-    def _resolve_tag(self, name: str) -> str:
-        """Resolve tag name to ID. Cached for client lifetime."""
+    def _invalidate_tag(self, tag_id: str) -> None:
+        """Remove a single tag from every name-cache bucket containing it.
+
+        Called by :meth:`rename` and :meth:`delete` after a successful
+        mutation. Sweeping every bucket (rather than relying on a
+        caller-supplied key) keeps invalidation correct when the
+        caller addressed the tag by id form and so does not know the
+        original cached name. Buckets that empty out are dropped; other
+        tags sharing the same case-folded name remain intact.
+        """
+        for key in list(self._name_cache.keys()):
+            bucket = self._name_cache[key]
+            bucket[:] = [t for t in bucket if t.id != tag_id]
+            if not bucket:
+                del self._name_cache[key]
+
+    def _resolve_tag(self, name: str, *, command: str) -> str:
+        """Resolve a tag name to a single tag id.
+
+        Lazily builds a list-valued name cache on first call (one
+        ``list_tags(top=500)`` round-trip) and reuses it for the
+        client's lifetime, with surgical invalidation on
+        create/rename/delete.
+
+        Three outcomes (KDCLI-200):
+
+        - exactly one visible tag with the given case-folded name →
+          returns that id.
+        - multiple visible tags share the name → refuses via
+          :meth:`_format_tag_ambiguity` with the supplied ``command``
+          so the caller's retry template renders correctly. The
+          legacy last-one-wins behaviour is gone.
+        - no visible match → :class:`NotFoundError` with the
+          close-match hint, same shape as before.
+
+        ``command`` threads through to the ambiguity diagnostic; each
+        call site is expected to pass its own verb. Tag-id form
+        (``\\d+-\\d+``) is handled at the call sites (not here): names
+        following kd's namespace convention never collide with the id
+        shape, and the passthrough belongs alongside other input-shape
+        decisions.
+        """
         key = name.lower()
-        if key in self._name_cache:
-            return self._name_cache[key]
-        self._debug.info("api", f"resolving tag '{name}'")
-        all_tags = self._tags.list_tags(top=500)
-        for t in all_tags:
-            self._name_cache[t.name.lower()] = t.id
-        if key in self._name_cache:
-            return self._name_cache[key]
-        available = [t.name for t in all_tags]
+        if not self._name_cache:
+            self._debug.info("api", f"resolving tag '{name}'")
+            for t in self._tags.list_tags(top=500):
+                self._name_cache.setdefault(t.name.lower(), []).append(t)
+        bucket = self._name_cache.get(key, [])
+        if len(bucket) == 1:
+            return bucket[0].id
+        if len(bucket) > 1:
+            raise self._format_tag_ambiguity(
+                name=name,
+                command=command,
+                global_candidates=list(bucket),
+                retry_template=_TAG_RETRY_TEMPLATES.get(command),
+                inspect_hint=_TAG_INSPECT_HINTS.get(command),
+            )
+        available = [t.name for ts in self._name_cache.values() for t in ts]
         close = difflib.get_close_matches(name, available, n=3, cutoff=0.5)
         hint = f" Did you mean: {', '.join(close)}?" if close else ""
         raise NotFoundError(f"Tag '{name}' not found.{hint}")
 
+    # --- Entity-anchored resolvers (KDCLI-198 S1) ---
+    #
+    # These bypass ``_resolve_tag`` / ``_name_cache`` deliberately: a
+    # display name can map to multiple tag ids, and the global cache
+    # silently picks one. ``/tag add`` and ``/tag remove`` both take an
+    # entity argument, so the attached tag list disambiguates by
+    # construction. S2 (KDCLI-200) replaces the global cache for the
+    # remaining tag commands.
+
+    def _fetch_attached_tags(self, entity_id: str) -> builtins.list[Tag]:
+        """Return the tags currently attached to ``entity_id``.
+
+        Uses the existing rich detail field set on both sides
+        (``_ARTICLE_DETAIL_FIELDS``, ``_ISSUE_RICH_FIELDS``) which
+        already projects ``tags(id,name)``. No additional request shape
+        is required.
+        """
+        if _detect_entity_type(entity_id) == "article":
+            return list(self._articles.get_article(entity_id).tags)
+        return list(self._yt.get_issue(entity_id, rich=True).tags)
+
+    def _resolve_attached_tag(self, name_or_id: str, entity_id: str) -> str:
+        """Resolve ``name_or_id`` to a tag id attached to ``entity_id``.
+
+        Used by ``/tag remove``.  Refuses to fall through to a global
+        lookup so the operator cannot accidentally address a same-name
+        tag that is not on the entity.
+
+        - id-form (``\\d+-\\d+``) → passthrough; existence checked by
+          the downstream HTTP call.
+        - exactly one same-name attached → return that id.
+        - none attached → :class:`ValidationError` ("not attached").
+          When a same-name tag exists globally, the diagnostic lists it
+          (without an ``[attached]`` marker) so the operator can see
+          the tag is real but not on this entity.
+        - multiple attached → :class:`ValidationError` with a candidate
+          diagnostic; require the id form.
+        """
+        if _is_tag_id(name_or_id):
+            return name_or_id
+        attached = self._fetch_attached_tags(entity_id)
+        key = name_or_id.lower()
+        matches = [t for t in attached if t.name.lower() == key]
+        if len(matches) == 1:
+            return matches[0].id
+        if not matches:
+            global_candidates = [t for t in self._tags.list_tags(top=500) if t.name.lower() == key]
+            raise self._format_tag_ambiguity(
+                name=name_or_id,
+                entity_id=entity_id,
+                attached=attached,
+                command="remove",
+                global_candidates=global_candidates,
+                reason="not_attached",
+            )
+        raise self._format_tag_ambiguity(
+            name=name_or_id,
+            entity_id=entity_id,
+            attached=attached,
+            command="remove",
+            retry_template="kd /tag {command} {entity_id} {id}",
+        )
+
+    def _resolve_tag_to_attach(self, name_or_id: str, entity_id: str) -> str:
+        """Resolve ``name_or_id`` to a tag id suitable for ``/tag add``.
+
+        - id-form (``\\d+-\\d+``) → passthrough.
+        - one same-name tag already attached → return that id
+          (idempotent re-tag).
+        - multiple same-name tags attached → :class:`ValidationError`
+          with a candidate diagnostic; require the id form.
+        - none attached, exactly one visible global match → return that
+          id.
+        - none attached, multiple visible global matches →
+          :class:`ValidationError` with a candidate diagnostic.
+        - none attached, no visible global match → :class:`NotFoundError`
+          with a close-match hint (same shape as :meth:`_resolve_tag`).
+        """
+        if _is_tag_id(name_or_id):
+            return name_or_id
+        attached = self._fetch_attached_tags(entity_id)
+        key = name_or_id.lower()
+        attached_matches = [t for t in attached if t.name.lower() == key]
+        if len(attached_matches) == 1:
+            return attached_matches[0].id
+        if len(attached_matches) > 1:
+            raise self._format_tag_ambiguity(
+                name=name_or_id,
+                entity_id=entity_id,
+                attached=attached,
+                command="add",
+                retry_template="kd /tag {command} {entity_id} {id}",
+            )
+        all_tags = self._tags.list_tags(top=500)
+        global_matches = [t for t in all_tags if t.name.lower() == key]
+        if len(global_matches) == 1:
+            return global_matches[0].id
+        if len(global_matches) > 1:
+            raise self._format_tag_ambiguity(
+                name=name_or_id,
+                entity_id=entity_id,
+                attached=attached,
+                command="add",
+                global_candidates=global_matches,
+                retry_template="kd /tag {command} {entity_id} {id}",
+            )
+        available = [t.name for t in all_tags]
+        close = difflib.get_close_matches(name_or_id, available, n=3, cutoff=0.5)
+        hint = f" Did you mean: {', '.join(close)}?" if close else ""
+        raise NotFoundError(f"Tag '{name_or_id}' not found.{hint}")
+
+    def _format_tag_ambiguity(
+        self,
+        *,
+        name: str,
+        command: str,
+        entity_id: str | None = None,
+        attached: Sequence[Tag] = (),
+        global_candidates: builtins.list[Tag] | None = None,
+        reason: Literal["ambiguous", "not_attached"] = "ambiguous",
+        retry_template: str | None = None,
+        inspect_hint: str | None = None,
+    ) -> ValidationError:
+        """Build a :class:`ValidationError` carrying the shared tag
+        diagnostic.
+
+        Candidates are the union of (same-name tags attached to the
+        entity) and (same-name tags visible globally), de-duplicated by
+        id. ``global_candidates`` is the pre-fetched global slice when
+        the caller already paid for ``list_tags`` — otherwise this
+        helper fetches it so attached-only ambiguity still gets enriched
+        with ``owner=`` metadata.
+
+        ``entity_id`` is omitted by S2 (global-command) callers; the
+        header drops the "on <entity>" clause and ``[attached]`` markers
+        do not appear because ``attached`` defaults to empty.
+
+        ``retry_template`` is rendered once per candidate via
+        ``.format(id=..., entity_id=..., command=...)``. When ``None``,
+        the retry block is omitted entirely (``/tag create`` collision
+        path, where ``create <id>`` is not a valid retry). The
+        ``inspect_hint`` parameter appends a single trailer line for the
+        no-retry case (e.g. ``kd /tag show <id>``).
+
+        ``reason="ambiguous"`` (default): the name resolves to multiple
+        candidates that the resolver cannot disambiguate. The diagnostic
+        lists candidates and the retry block proposes id-form retries.
+        When exactly one candidate is attached the retry block points to
+        that id (the operator clearly meant the attached one); otherwise
+        every candidate gets its own retry line so the emitter never
+        picks for the operator.
+
+        ``reason="not_attached"``: the name is not on the entity. When
+        same-name globals exist they are listed (no ``[attached]``
+        markers, since none are) so the operator can see the tag is
+        real but not here; there is no retry block. When no globals
+        match, the message is the bare "not attached" sentence.
+        ``reason="not_attached"`` is an S1 (entity-anchored) shape and
+        requires ``entity_id``.
+        """
+        key = name.lower()
+        if global_candidates is None:
+            global_candidates = [t for t in self._tags.list_tags(top=500) if t.name.lower() == key]
+        attached_ids = {t.id for t in attached if t.name.lower() == key}
+        # Prefer the global slice for each id (it carries owner metadata
+        # that the attached tags list, projected as ``tags(id,name)``,
+        # does not). Fall back to the attached entry only when the tag
+        # is invisible to the running principal in ``list_tags``.
+        by_id: dict[str, Tag] = {t.id: t for t in global_candidates}
+        for t in attached:
+            if t.name.lower() == key:
+                by_id.setdefault(t.id, t)
+        candidates = sorted(by_id.values(), key=lambda t: t.id)
+
+        if reason == "not_attached":
+            lines = [f"Tag '{name}' is not attached to {entity_id}."]
+            if candidates:
+                lines.extend(
+                    [
+                        "",
+                        "Same-name tags exist globally but are not on this entity:",
+                    ]
+                )
+                for t in candidates:
+                    lines.append(f"  {t.id}  {t.name}  owner={_format_owner(t)}")
+            return ValidationError("\n".join(lines))
+
+        header = (
+            f"Tag '{name}' is ambiguous on {entity_id}."
+            if entity_id is not None
+            else f"Tag '{name}' is ambiguous."
+        )
+        lines = [header, "", "Candidates:"]
+        for t in candidates:
+            mark = "  [attached]" if t.id in attached_ids else ""
+            lines.append(f"  {t.id}  {t.name}  owner={_format_owner(t)}{mark}")
+        attached_candidates = [t for t in candidates if t.id in attached_ids]
+        if retry_template is not None:
+            lines.append("")
+            if len(attached_candidates) == 1:
+                # Exactly one attached among many candidates: the
+                # operator clearly meant the attached one — emit a
+                # single retry.
+                only = attached_candidates[0]
+                lines.extend(
+                    [
+                        "Retry with the tag id:",
+                        "  "
+                        + retry_template.format(
+                            id=only.id,
+                            entity_id=entity_id,
+                            command=command,
+                        ),
+                    ]
+                )
+            else:
+                # Zero or multiple attached: do not pick. List every
+                # candidate's retry so the operator chooses.
+                lines.append("Retry with one of:")
+                for t in candidates:
+                    lines.append(
+                        "  "
+                        + retry_template.format(
+                            id=t.id,
+                            entity_id=entity_id,
+                            command=command,
+                        )
+                    )
+        elif inspect_hint is not None:
+            lines.extend(["", "Inspect a candidate with:", f"  {inspect_hint}"])
+        return ValidationError("\n".join(lines))
+
 
 class SavedQueryOperations:
     """High-level saved-query operations with name-or-ID resolution."""

{kd_cli-2.8.1 → kd_cli-2.9.0}/kd/resources/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to kd-cli are recorded here. The project follows [Semantic V
 
 ## [Unreleased]
 
+## [2.9.0] — 2026-05-12
+
+### Changed
+- Tag-name resolution now refuses on visible-global name collisions
+  instead of silently picking one tag id. The legacy last-one-wins
+  behaviour is gone across the entire `/tag` namespace: `/tag show`,
+  `/tag delete`, `/tag rename`, `/tag create`, `/tag add`, `/tag remove`,
+  `/tag issues`, `/tag articles`, and `/tag entities` all surface a
+  structured candidate list (id, name, owner) when two visible tags
+  share a display name. Each candidate is rendered with a retry shape
+  appropriate to the command (`kd /tag show <id>`, `kd /tag rename
+  <id> <new-name>`, etc.); `/tag create` lists candidates without a
+  retry block and suggests `kd /tag show <id>` for inspection. The
+  tag-id form (`NN-NN`) is a passthrough on every command that accepts
+  a tag identifier — use it to disambiguate (KDCLI-198: KDCLI-199 +
+  KDCLI-200).
+- `/tag issues` and `/tag entities` pre-validate every tag argument
+  before composing the YouTrack query or fanning out across kinds, so
+  ambiguity refusal is a hard precondition rather than a partial-
+  success row. The multi-tag / project slow path on `/tag issues`
+  previously bypassed the resolver entirely; that gap is closed.
+- Tag-id form scope is narrower on `/tag issues` and `/tag entities`
+  than on the other tag commands because YouTrack's `tag:` query DSL
+  predicate is name-keyed (no id-keyed predicate exists). `/tag issues`
+  accepts id form on the fast path only (single tag, no `--project`);
+  any combination with `--project` or multiple `--tag` arguments
+  refuses with guidance. `/tag entities` accepts id form when the
+  issue half stays on the fast path or when only `--kind article` is
+  requested; combining id form with `--project` or multiple tags AND
+  the issue kind refuses. The other tag commands (`show`, `delete`,
+  `rename`, `add`, `remove`, `articles`) are unaffected.
+
 ## [2.8.1] — 2026-05-08
 
 ### Fixed

{kd_cli-2.8.1 → kd_cli-2.9.0}/kd/resources/operating-guide.md

@@ -257,6 +257,24 @@ Do not treat `--primer-scope` as implicit global state. It is a deliberate flag
 
 `/tag create TAG_NAME` is idempotent. It resolves the name first (same case-insensitive resolver `/tag show` uses) and returns `{ok, action, tag}` with `action: exists` when the tag is already visible, or `action: create` after a successful POST. Taxonomy bootstrapping and fixture setup can re-run the command safely without decoding `Tag.name-is-invalid`. When the POST still fails — either a genuinely unacceptable name or an existing tag hidden by sharing/visibility — kd surfaces a factual diagnostic naming both plausible causes rather than the raw upstream error.
 
+### Tag Name Resolution And Duplicates
+
+Tags are a **global** YouTrack entity. Two different users can independently create tags with the same display name (e.g., one automation account owns a private `lifecycle:draft` taxonomy and a user re-creates `lifecycle:draft` they cannot see) — both tags are real and both can be visible to a third principal. The case-folded name is therefore not a unique identifier; the tag id (`NN-NN`) is.
+
+`kd` exposes this distinction directly:
+
+- **Name form (`sprint-47`, `lifecycle:draft`).** Used by every tag command. Resolves to exactly one visible tag, or refuses with a structured candidate list listing each id and owner. The resolver never silently picks among duplicates.
+- **Id form (`NN-NN`, e.g. `10-178`).** Skips name resolution. Accepted by `/tag show`, `/tag delete`, `/tag rename` (first arg), `/tag add`, `/tag remove`, `/tag articles`, and — with scope limits — `/tag issues` and `/tag entities`. Use the id form to disambiguate when a name collides.
+
+The id-form scope for `/tag issues` and `/tag entities` is narrower because YouTrack's query DSL `tag:` predicate is name-keyed; there is no id-keyed tag predicate. Concretely:
+
+- `/tag issues TAG_NAME_OR_ID` — id form works on the fast path (single tag, no `--project`). Add `--project` or another `--tag`, and the id form is refused with guidance to use the fast path or the name form.
+- `/tag entities TAG_NAME_OR_ID` — id form works when the issue half stays on the fast path (single tag, no `--project`) or when the run is restricted to `--kind article` (article filtering is client-side by id). With `--project` or multiple tags AND the issue kind included, id form is refused.
+
+`/tag create TAG_NAME` is the one exception: it refuses on visible-global collision rather than silently returning "the first existing tag", and does not accept an id form (creating with an existing id is meaningless). Inspect each candidate with `kd /tag show <id>` to decide whether to reuse or rename one.
+
+`/tag entities` pre-validates every tag argument before fanout. Ambiguity refusal is therefore the whole-command outcome — duplicate-name refusal is never reported as a per-kind partial-success row.
+
 ## Output And Debugging
 
 For deterministic machine consumption, always pass an explicit output format:

{kd_cli-2.8.1 → kd_cli-2.9.0/kd_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kd-cli
-Version: 2.8.1
+Version: 2.9.0
 Summary: Knowledge Dispatcher for issue trackers and knowledge bases
 Author: Sergiy Gladkyy
 License-Expression: MIT

{kd_cli-2.8.1 → kd_cli-2.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kd-cli"
-version = "2.8.1"
+version = "2.9.0"
 description = "Knowledge Dispatcher for issue trackers and knowledge bases"
 readme = "README.md"
 requires-python = ">=3.11"