kd-cli 2.3.0__tar.gz → 2.4.1__tar.gz

{kd_cli-2.3.0/kd_cli.egg-info → kd_cli-2.4.1}/PKG-INFO

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

kd_cli-2.4.1/kd/cli/core/confirm.py

@@ -0,0 +1,43 @@
+"""Confirmation guard for irreversible destructive commands.
+
+Some destructive commands bypass YouTrack's Deleted Items safety net —
+project, tag, and user deletes in particular. This helper enforces an
+opt-in ``--confirm`` flag: without it the command aborts with an
+actionable multi-line error; with it the delete proceeds.
+
+The error follows the ``_missing_tag_resolution`` pattern from
+``kd.client``: a human-readable explanation plus a ``suggestion`` line
+that spells out the literal retry command so an LLM reading the
+stderr can proceed without extra reasoning.
+"""
+
+from __future__ import annotations
+
+import shlex
+
+from kd.exceptions import ValidationError
+
+
+def require_confirm(
+    *,
+    confirmed: bool,
+    command: str,
+    entity_id: str,
+    caveat: str,
+) -> None:
+    """Abort unless ``--confirm`` was passed.
+
+    Args:
+        confirmed: Whether the caller passed ``--confirm``.
+        command: Full command path, e.g. ``/project delete``.
+        entity_id: The target identifier as given on the command line.
+        caveat: One or two sentences explaining why this particular
+            delete is unsafe — the per-entity failure mode (issues
+            vanishing, tag membership gone, identity refs detaching).
+    """
+    if confirmed:
+        return
+    raise ValidationError(
+        f"kd {command} {entity_id} is irreversible. {caveat}",
+        suggestion=(f"Retry with: kd {command} {shlex.quote(entity_id)} --confirm"),
+    )

{kd_cli-2.3.0 → kd_cli-2.4.1}/kd/cli/core/option_registry.py

@@ -38,6 +38,7 @@ class OptionDeclaration:
     help_text: str = ""
     is_list: bool = False
     aliases: list[str] = field(default_factory=list)
+    hidden_from_reference: bool = False
 
 
 @dataclass

{kd_cli-2.3.0 → kd_cli-2.4.1}/kd/cli/main.py

@@ -547,6 +547,8 @@ def _print_namespace_reference(ns: Namespace, depth: int = 0) -> None:
 
         # Options
         for opt in cmd.get_options():
+            if opt.hidden_from_reference:
+                continue
             flag = f"--{opt.name}"
             if opt.short_name:
                 flag += f"/-{opt.short_name}"

{kd_cli-2.3.0 → kd_cli-2.4.1}/kd/cli/namespaces/primer/__init__.py

@@ -26,6 +26,7 @@ from kd.primer import (
     clear_articles,
     clear_notes,
     clear_tags,
+    init_primer,
     load_primer,
     remove_article,
     remove_note,
@@ -107,6 +108,53 @@ class PrimerShowCommand(Command):
         }
 
 
+# ---------------------------------------------------------------------------
+# /primer init
+# ---------------------------------------------------------------------------
+
+
+class PrimerInitCommand(Command):
+    """Scaffold ``.kd/primer.yaml`` from a packaged template."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "init",
+            "Scaffold .kd/primer.yaml from a template",
+            usage="kd /primer init [TEMPLATE]",
+            long_description=(
+                "Creates .kd/primer.yaml from a packaged template.  Default "
+                "template is `hitl` — a human-in-the-loop session workflow "
+                "scaffold with placeholder prose in the scope-guard, session-"
+                "workflow, and canonical-reference slots.  The template is "
+                "copied through unchanged so its banner and example-shape "
+                "comments survive.  Refuses if a primer already exists; "
+                "there is no --force (deletion is explicit operator work)."
+            ),
+            examples=[
+                "kd /primer init",
+                "kd /primer init hitl",
+            ],
+            see_also=["/primer show", "/primer/note list"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(project_option(help_text="Assert which project's primer this edits"))
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        _assert_workspace_project(self, options)
+        template = args[0] if args else "hitl"
+        created = init_primer(template)
+        return {
+            "ok": True,
+            "action": "init",
+            "template": template,
+            "created": str(created),
+            "next": "kd /primer show -o yaml",
+        }
+
+
 # ---------------------------------------------------------------------------
 # /primer/note
 # ---------------------------------------------------------------------------
@@ -534,6 +582,7 @@ def create_primer_namespace() -> Namespace:
         path="primer",
     )
     ns.register_command("show", PrimerShowCommand())
+    ns.register_command("init", PrimerInitCommand())
 
     # /primer/note
     note_ns = Namespace("note", "Primer notes and conventions", path="primer/note")

{kd_cli-2.3.0 → kd_cli-2.4.1}/kd/cli/namespaces/project/__init__.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 from typing import Any
 
 from kd.cli.core.command_base import Command, CommandResult
+from kd.cli.core.confirm import require_confirm
 from kd.cli.core.namespaces import Namespace
 from kd.cli.core.option_registry import (
     OptionDeclaration,
@@ -153,9 +154,22 @@ class ProjectDeleteCommand(Command):
             "Delete a project",
             requires_client=True,
             usage="kd /project delete KEY",
-            examples=["kd /project delete TST"],
+            examples=["kd /project delete TST --confirm"],
             see_also=["/project list"],
         )
+        self.register_option(
+            OptionDeclaration(
+                name="confirm",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                default=False,
+                help_text=(
+                    "Required — project delete is not recoverable from "
+                    "Deleted Items (issues and articles are permanently removed)"
+                ),
+                hidden_from_reference=True,
+            )
+        )
 
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
@@ -163,6 +177,16 @@ class ProjectDeleteCommand(Command):
         if not args:
             raise ValidationError("Usage: kd /project delete KEY")
         key = args[0]
+        require_confirm(
+            confirmed=bool(options.command.get("confirm")),
+            command="/project delete",
+            entity_id=key,
+            caveat=(
+                "All issues and articles in the project are permanently "
+                "deleted (they are not moved to Deleted Items) — recovery "
+                "requires a database backup restore."
+            ),
+        )
         client.projects.delete(key)
         return {"ok": True, "action": "delete", "project": key}
 

{kd_cli-2.3.0 → kd_cli-2.4.1}/kd/cli/namespaces/tag/__init__.py

@@ -10,6 +10,7 @@ import sys
 from typing import Any, Literal
 
 from kd.cli.core.command_base import Command, CommandResult
+from kd.cli.core.confirm import require_confirm
 from kd.cli.core.namespaces import Namespace
 from kd.cli.core.option_registry import (
     OptionDeclaration,
@@ -203,9 +204,22 @@ class TagDeleteCommand(Command):
             "Delete a tag",
             requires_client=True,
             usage="kd /tag delete TAG_NAME",
-            examples=["kd /tag delete sprint-47"],
+            examples=["kd /tag delete sprint-47 --confirm"],
             see_also=["/tag list", "/tag create"],
         )
+        self.register_option(
+            OptionDeclaration(
+                name="confirm",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                default=False,
+                help_text=(
+                    "Required — tag delete is not recoverable from Deleted "
+                    "Items (tag membership is lost across all entities)"
+                ),
+                hidden_from_reference=True,
+            )
+        )
 
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
@@ -213,6 +227,16 @@ class TagDeleteCommand(Command):
         if not args:
             raise ValidationError("Usage: kd /tag delete TAG_NAME")
         name = args[0]
+        require_confirm(
+            confirmed=bool(options.command.get("confirm")),
+            command="/tag delete",
+            entity_id=name,
+            caveat=(
+                "Tag membership is removed from every tagged issue and "
+                "article; recreating the tag does not restore assignments. "
+                "Full recovery requires a database backup restore."
+            ),
+        )
         client.tags.delete(name)
         return {"ok": True, "action": "delete", "tag": name}
 

{kd_cli-2.3.0 → kd_cli-2.4.1}/kd/cli/namespaces/user/__init__.py

@@ -9,8 +9,13 @@ from __future__ import annotations
 from typing import Any
 
 from kd.cli.core.command_base import Command, CommandResult
+from kd.cli.core.confirm import require_confirm
 from kd.cli.core.namespaces import Namespace
-from kd.cli.core.option_registry import ResolvedOptions
+from kd.cli.core.option_registry import (
+    OptionDeclaration,
+    OptionLayer,
+    ResolvedOptions,
+)
 from kd.exceptions import ValidationError
 
 
@@ -77,17 +82,42 @@ class UserDeleteCommand(Command):
             "Delete a user",
             requires_client=True,
             usage="kd /user delete HUB_USER_ID",
-            examples=["kd /user delete abc-123"],
+            examples=["kd /user delete abc-123 --confirm"],
             see_also=["/user list"],
         )
+        self.register_option(
+            OptionDeclaration(
+                name="confirm",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                default=False,
+                help_text=(
+                    "Required — user delete is not recoverable from Deleted "
+                    "Items (consider banning via the Hub UI instead)"
+                ),
+                hidden_from_reference=True,
+            )
+        )
 
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
     ) -> CommandResult:
         if not args:
             raise ValidationError("Usage: kd /user delete HUB_USER_ID")
-        client.users.delete(args[0])
-        return {"ok": True, "action": "delete", "user": args[0]}
+        user_id = args[0]
+        require_confirm(
+            confirmed=bool(options.command.get("confirm")),
+            command="/user delete",
+            entity_id=user_id,
+            caveat=(
+                "Identity references in issue history become detached, and "
+                "the account is removed from the Hub. Consider banning the "
+                "user in the Hub UI instead; full recovery requires a "
+                "database backup restore."
+            ),
+        )
+        client.users.delete(user_id)
+        return {"ok": True, "action": "delete", "user": user_id}
 
 
 def create_user_namespace() -> Namespace:

kd_cli-2.4.1/kd/locking.py

@@ -0,0 +1,97 @@
+"""Advisory file locking for read-modify-write transactions on kd-managed files.
+
+Provides :func:`file_transaction` — a context manager that acquires an
+exclusive advisory lock on a sidecar lockfile (``<path>.lock``) for the
+duration of a load → mutate → save cycle.  Concurrent kd processes that
+enter the same transaction serialize rather than clobber each other.
+
+Design notes:
+
+* **Sidecar lockfile, not the target file.**  Atomic writes elsewhere in
+  kd use ``tempfile.mkstemp`` + ``os.replace``, which changes the target
+  file's inode on every write.  Holding ``flock`` on the target inode
+  would not protect a second writer that opens the freshly-replaced file.
+  Locking a separate sidecar file that nobody rewrites keeps the lock
+  stable across atomic replaces of the data file.
+
+* **No unlink on release.**  Removing the lockfile after releasing the
+  lock is a classic race: process B can open the doomed inode while
+  process C creates a fresh one, and both end up holding "exclusive"
+  locks on different inodes.  Empty sidecar files are cheap; leave them.
+
+* **POSIX only.**  ``fcntl`` is imported lazily inside the context
+  manager so that unrelated kd commands remain importable on Windows.
+  On non-POSIX platforms, :func:`file_transaction` raises ``ConfigError``
+  with a suggestion to run the command sequentially.
+
+* **NFS caveat.**  ``flock`` on NFS has been unreliable historically.
+  Modern Linux kernels implement it correctly, but operators using a
+  networked ``$HOME`` should be aware that concurrency guarantees weaken.
+  Local ``.kd/`` directories inside a repo are unaffected.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+from collections.abc import Generator
+from contextlib import contextmanager
+from pathlib import Path
+
+from kd.exceptions import ConfigError
+
+LOCK_SUFFIX = ".lock"
+_POLL_INTERVAL_SECONDS = 0.05
+
+
+@contextmanager
+def file_transaction(path: Path, *, timeout: float = 30.0) -> Generator[None, None, None]:
+    """Hold an exclusive advisory lock on ``<path>.lock`` for the ``with`` body.
+
+    The sidecar lockfile is created if missing (``O_RDWR | O_CREAT``,
+    never truncated).  Acquisition polls non-blocking ``flock`` until
+    the lock is granted or *timeout* seconds elapse.  On timeout, raises
+    :class:`ConfigError` naming the contested file.  The lockfile is
+    intentionally left on disk after release.
+
+    Raises :class:`ConfigError` on non-POSIX platforms.
+    """
+    if sys.platform == "win32":
+        raise ConfigError(
+            "File locking is not available on this platform (POSIX only).",
+            suggestion="Run the kd command sequentially; concurrent mutations are not supported on Windows.",
+        )
+
+    import fcntl  # noqa: PLC0415 — lazy import keeps kd importable on Windows
+
+    lock_path = path.with_name(path.name + LOCK_SUFFIX)
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+
+    fd = os.open(lock_path, os.O_RDWR | os.O_CREAT, 0o644)
+    try:
+        deadline = time.monotonic() + timeout
+        while True:
+            try:
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                break
+            except BlockingIOError:
+                if time.monotonic() >= deadline:
+                    raise ConfigError(
+                        f"Another kd process is writing to {path}; retry in a moment.",
+                        suggestion=f"If no other kd process is running, remove the stale lockfile: {lock_path}",
+                    ) from None
+                time.sleep(_POLL_INTERVAL_SECONDS)
+
+        try:
+            yield
+        finally:
+            try:
+                fcntl.flock(fd, fcntl.LOCK_UN)
+            except OSError:
+                pass
+    finally:
+        try:
+            os.close(fd)
+        except OSError:
+            pass

{kd_cli-2.3.0 → kd_cli-2.4.1}/kd/primer.py

@@ -10,6 +10,9 @@ knowledge).  The file is created lazily on first write operation.
 
 from __future__ import annotations
 
+import importlib.resources
+from collections.abc import Generator
+from contextlib import contextmanager
 from pathlib import Path
 from typing import Any
 
@@ -17,6 +20,7 @@ import yaml
 from pydantic import BaseModel
 
 from kd.exceptions import ConfigError, ValidationError
+from kd.locking import file_transaction
 
 
 # ---------------------------------------------------------------------------
@@ -124,10 +128,15 @@ def load_primer(path: Path | None = None) -> PrimerData:
 
 
 def save_primer(data: PrimerData, path: Path | None = None) -> None:
-    """Write primer to YAML.
+    """Write primer to YAML — low-level primitive.
 
     Snapshots the current file before writing (copy-on-write) and uses
-    atomic writes to prevent partial-write corruption.
+    atomic writes to prevent partial-write corruption.  Does **not**
+    serialize concurrent writers on its own; callers that do
+    ``load_primer → mutate → save_primer`` across processes risk lost
+    updates.  Prefer the mutator functions below (:func:`add_note`,
+    :func:`update_note`, etc.), which wrap load/save in
+    :func:`primer_transaction` to guarantee per-file serialization.
     """
     from kd.history import atomic_write_text, snapshot_before_write
 
@@ -171,46 +180,56 @@ def _tag_dump(tag: dict[str, Any]) -> dict[str, Any]:
 # ---------------------------------------------------------------------------
 
 
+@contextmanager
+def _primer_transaction(path: Path) -> Generator[PrimerData, None, None]:
+    """Serialize a primer read-modify-write cycle under an advisory lock.
+
+    Holds an exclusive advisory lock on ``<path>.lock`` for the full
+    cycle: loads the primer, yields a ``PrimerData`` for the caller to
+    mutate in place, and saves on clean exit.  If the caller raises,
+    the save is skipped (the file is not modified).
+    """
+    with file_transaction(path):
+        data = load_primer(path)
+        yield data
+        save_primer(data, path)
+
+
 def add_note(text: str, path: Path | None = None) -> int:
     """Append a note. Returns the 1-based index."""
     primer_file = path or _primer_path()
-    data = load_primer(primer_file)
-    data.notes.append(text)
-    save_primer(data, primer_file)
-    return len(data.notes)
+    with _primer_transaction(primer_file) as data:
+        data.notes.append(text)
+        return len(data.notes)
 
 
 def remove_note(index: int, path: Path | None = None) -> str:
     """Remove a note by 1-based index. Returns the removed text."""
     primer_file = path or _primer_path()
-    data = load_primer(primer_file)
-    if index < 1 or index > len(data.notes):
-        raise ValidationError(f"Note index {index} out of range (1–{len(data.notes)})")
-    removed = data.notes.pop(index - 1)
-    save_primer(data, primer_file)
-    return removed
+    with _primer_transaction(primer_file) as data:
+        if index < 1 or index > len(data.notes):
+            raise ValidationError(f"Note index {index} out of range (1–{len(data.notes)})")
+        return data.notes.pop(index - 1)
 
 
 def update_note(index: int, text: str, path: Path | None = None) -> str:
     """Replace a note by 1-based index. Returns the old text."""
     primer_file = path or _primer_path()
-    data = load_primer(primer_file)
-    if index < 1 or index > len(data.notes):
-        raise ValidationError(f"Note index {index} out of range (1–{len(data.notes)})")
-    old = data.notes[index - 1]
-    data.notes[index - 1] = text
-    save_primer(data, primer_file)
-    return old
+    with _primer_transaction(primer_file) as data:
+        if index < 1 or index > len(data.notes):
+            raise ValidationError(f"Note index {index} out of range (1–{len(data.notes)})")
+        old = data.notes[index - 1]
+        data.notes[index - 1] = text
+        return old
 
 
 def clear_notes(path: Path | None = None) -> int:
     """Remove all notes. Returns the count removed."""
     primer_file = path or _primer_path()
-    data = load_primer(primer_file)
-    count = len(data.notes)
-    data.notes.clear()
-    save_primer(data, primer_file)
-    return count
+    with _primer_transaction(primer_file) as data:
+        count = len(data.notes)
+        data.notes.clear()
+        return count
 
 
 def add_article(
@@ -218,68 +237,106 @@ def add_article(
 ) -> PrimerArticle:
     """Pin an article. Raises if already pinned."""
     primer_file = path or _primer_path()
-    data = load_primer(primer_file)
-    for existing in data.articles:
-        if existing.id == article_id:
-            raise ValidationError(f"Article '{article_id}' is already pinned")
-    article = PrimerArticle(id=article_id, summary=summary)
-    data.articles.append(article)
-    save_primer(data, primer_file)
-    return article
+    with _primer_transaction(primer_file) as data:
+        for existing in data.articles:
+            if existing.id == article_id:
+                raise ValidationError(f"Article '{article_id}' is already pinned")
+        article = PrimerArticle(id=article_id, summary=summary)
+        data.articles.append(article)
+        return article
 
 
 def remove_article(article_id: str, path: Path | None = None) -> PrimerArticle:
     """Unpin an article by ID. Returns the removed entry."""
     primer_file = path or _primer_path()
-    data = load_primer(primer_file)
-    for i, article in enumerate(data.articles):
-        if article.id == article_id:
-            removed = data.articles.pop(i)
-            save_primer(data, primer_file)
-            return removed
-    raise ValidationError(f"Article '{article_id}' is not pinned")
+    with _primer_transaction(primer_file) as data:
+        for i, article in enumerate(data.articles):
+            if article.id == article_id:
+                return data.articles.pop(i)
+        raise ValidationError(f"Article '{article_id}' is not pinned")
 
 
 def clear_articles(path: Path | None = None) -> int:
     """Remove all pinned articles. Returns the count removed."""
     primer_file = path or _primer_path()
-    data = load_primer(primer_file)
-    count = len(data.articles)
-    data.articles.clear()
-    save_primer(data, primer_file)
-    return count
+    with _primer_transaction(primer_file) as data:
+        count = len(data.articles)
+        data.articles.clear()
+        return count
 
 
 def add_tag(name: str, summary: str | None = None, path: Path | None = None) -> PrimerTag:
     """Pin a tag. Raises if already pinned."""
     primer_file = path or _primer_path()
-    data = load_primer(primer_file)
-    for existing in data.tags:
-        if existing.name == name:
-            raise ValidationError(f"Tag '{name}' is already pinned")
-    tag = PrimerTag(name=name, summary=summary)
-    data.tags.append(tag)
-    save_primer(data, primer_file)
-    return tag
+    with _primer_transaction(primer_file) as data:
+        for existing in data.tags:
+            if existing.name == name:
+                raise ValidationError(f"Tag '{name}' is already pinned")
+        tag = PrimerTag(name=name, summary=summary)
+        data.tags.append(tag)
+        return tag
 
 
 def remove_tag(name: str, path: Path | None = None) -> PrimerTag:
     """Unpin a tag by name. Returns the removed entry."""
     primer_file = path or _primer_path()
-    data = load_primer(primer_file)
-    for i, tag in enumerate(data.tags):
-        if tag.name == name:
-            removed = data.tags.pop(i)
-            save_primer(data, primer_file)
-            return removed
-    raise ValidationError(f"Tag '{name}' is not pinned")
+    with _primer_transaction(primer_file) as data:
+        for i, tag in enumerate(data.tags):
+            if tag.name == name:
+                return data.tags.pop(i)
+        raise ValidationError(f"Tag '{name}' is not pinned")
 
 
 def clear_tags(path: Path | None = None) -> int:
     """Remove all pinned tags. Returns the count removed."""
     primer_file = path or _primer_path()
-    data = load_primer(primer_file)
-    count = len(data.tags)
-    data.tags.clear()
-    save_primer(data, primer_file)
-    return count
+    with _primer_transaction(primer_file) as data:
+        count = len(data.tags)
+        data.tags.clear()
+        return count
+
+
+# ---------------------------------------------------------------------------
+# Scaffolding
+# ---------------------------------------------------------------------------
+
+_PRIMER_TEMPLATE_PACKAGE = "kd.resources.primers"
+
+
+def list_primer_templates() -> list[str]:
+    """Return sorted names of shipped primer templates (without ``.yaml``)."""
+    root = importlib.resources.files(_PRIMER_TEMPLATE_PACKAGE)
+    return sorted(p.name[: -len(".yaml")] for p in root.iterdir() if p.name.endswith(".yaml"))
+
+
+def init_primer(template: str = "hitl", path: Path | None = None) -> Path:
+    """Scaffold ``.kd/primer.yaml`` from a packaged template.
+
+    Copies the template file through unchanged so its banner and inline
+    comments survive; no YAML load/dump round-trip.  Refuses if a primer
+    already exists — deletion is explicit operator work and there is no
+    ``--force``.
+    """
+    from kd.history import atomic_write_text
+
+    available = list_primer_templates()
+    if template not in available:
+        raise ValidationError(
+            f"Unknown primer template '{template}'. Available: {', '.join(available)}"
+        )
+
+    primer_file = path or _primer_path()
+    if primer_file.exists():
+        raise ValidationError(
+            f"Primer already exists at {primer_file}. "
+            f"Run `kd /primer show` to inspect it, or delete the file to start over."
+        )
+
+    content = (
+        importlib.resources.files(_PRIMER_TEMPLATE_PACKAGE)
+        .joinpath(f"{template}.yaml")
+        .read_text(encoding="utf-8")
+    )
+    primer_file.parent.mkdir(parents=True, exist_ok=True)
+    atomic_write_text(primer_file, content)
+    return primer_file

{kd_cli-2.3.0 → kd_cli-2.4.1}/kd/resources/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to kd-cli are recorded here. The project follows [Semantic V
 
 ## [Unreleased]
 
+## [2.4.1] — 2026-04-19
+
+### Fixed
+- Concurrent `kd /primer/note`, `/primer/tag`, and `/primer/article` commands against the same `.kd/primer.yaml` no longer silently lose writes. Before: running three `kd /primer/note update` calls in parallel (common in agent-driven sessions) all reported `ok: true` but only one update survived. Now: each command runs inside an advisory file lock on a sidecar `.kd/primer.yaml.lock`, so concurrent kd processes queue rather than clobber each other and every successful call is reflected in the final file. Concurrent acquirers wait up to 30 s before erroring with `Another kd process is writing to …; retry in a moment`; the error includes the path of the sidecar lockfile for stale-holder recovery. POSIX only; first lock attempt on Windows raises a clear error pointing at sequential invocation (KDCLI-98).
+
+## [2.4.0] — 2026-04-19
+
+### Added
+- `kd /primer init [TEMPLATE]` scaffolds `.kd/primer.yaml` from a packaged template so fresh workspaces don't start from a blank page. The default `hitl` template ships placeholder prose in three slots (scope guard, session workflow, canonical reference); the banner and example-shape comments are preserved verbatim. Refuses if a primer already exists; unknown template names reject with the available-templates list (KDCLI-97).
+- `--confirm` flag on `/project delete`, `/tag delete`, and `/user delete` — these three deletes bypass YouTrack's Deleted Items and require a backup restore to undo, so kd now rejects them without `--confirm` and prints the literal retry command in the error. The flag is hidden from `kd --reference` but visible in per-command `--help` (KDCLI-96).
+
 ## [2.3.0] — 2026-04-18
 
 ### Added

{kd_cli-2.3.0 → kd_cli-2.4.1}/kd/resources/operating-guide.md

@@ -82,6 +82,14 @@ kd /issue update KDCLI-42 --state Fixed -o yaml
 For article push, use `--dry-run` before a risky write and inspect conflicts with `/article pull`.
 `/article push --tag` rejects missing tags by default and prints the concrete recovery commands. Use `--create-tags` only for scripted flows that already own the tag namespace.
 
+Three delete commands bypass YouTrack's Deleted Items safety net and require an explicit `--confirm` flag:
+
+- `/project delete` — all issues and articles in the project are permanently removed, not moved to Deleted Items.
+- `/tag delete` — tag membership is lost across every tagged issue and article; recreating the tag does not restore assignments.
+- `/user delete` — identity references in issue history become detached; consider banning in the Hub UI instead.
+
+Without `--confirm` these commands exit non-zero with an error that names the failure mode and prints the literal retry command. Recovery for any of the three requires a database backup restore. `/issue delete`, `/article delete`, and attachment deletes do not require `--confirm` — they go to Deleted Items and are admin-restorable for roughly 14 days.
+
 ## YouTrack Gotchas
 
 YouTrack articles are not queryable like issues. `/api/articles` has no issue-style `query` parameter, and there is no server-side article-by-tag endpoint. kd article tag lookup scans article pages that include `tags(id,name)` and filters locally.
@@ -106,6 +114,8 @@ Tag existence, tag visibility, and tag sharing rights are different concerns. A
 
 ## Primer Practices
 
+For a fresh workspace, scaffold the primer with `kd /primer init`. The default `hitl` template drops placeholder prose into three slots — scope guard, session workflow, canonical reference — that the operator fills in an editor. The command refuses if a primer already exists and has no `--force`; deletion is explicit operator work.
+
 Primer notes should capture durable project rules, not temporary status. Good notes explain naming conventions, required workflows, dangerous assumptions, and pointers to canonical references.
 
 Do not use the primer as a session log. Avoid recording current focus, completed session lists, release-cadence details copied from a plan, or other progress facts that can become false by the next agent session. If the primer needs to point at active work, stop at the current master plan or equivalent planning document; the agent should open that document and derive the next step from there.
@@ -136,6 +146,8 @@ When both pinned tags and pinned articles exist, read them in order: notes tell
 
 Keep the primer local and curated. If a note becomes generally true for kd, move it into docs or this guide. If it is workspace-specific, keep it in `.kd/primer.yaml`.
 
+Primer mutations are serialized per file through an advisory lock on `.kd/primer.yaml.lock`; concurrent kd processes writing to the same primer queue rather than conflict, so agent-launched parallel `/primer/note`, `/primer/tag`, and `/primer/article` commands all converge without lost updates.
+
 ## Articles And Push
 
 Use `/article show` for metadata plus rendered content. Use `/article pull` when you need raw article content on stdout; `pull` is format-agnostic and ignores `--output`.
@@ -211,4 +223,4 @@ Use these sources together:
 - `docs/design/architecture.md` and ADRs for architectural constraints.
 
 ---
-Updated: 2026-04-18
+Updated: 2026-04-19

kd_cli-2.4.1/kd/resources/primers/hitl.yaml

@@ -0,0 +1,41 @@
+# DO NOT EDIT THIS FILE DIRECTLY. Use `kd /primer --help` to manage it.
+#
+# This is the `hitl` template — human-in-the-loop session workflow. Edit the
+# placeholders below to fit this workspace. Three slots:
+#   1. Scope guard — what this workspace is / is not; how to reject drift.
+#   2. Session workflow — the repeatable loop and local conventions.
+#   3. Canonical reference — pinned article(s) with durable background.
+
+notes:
+- '<WORKSPACE> is <one-sentence identity: what kind of tool, codebase, or knowledge
+  base this workspace represents>. Primary loop: <describe the repeatable action —
+  for example, pull context → reason → push focused updates back>. <State what this
+  workspace is NOT — adjacent shapes it should not drift toward, such as migration
+  platform, data warehouse, silent local mirror>. Before adding features that look
+  like the adjacent shape, re-read this guard. Test question: does this keep the
+  workspace <identity>-shaped, or does it drag it toward <adjacent shape>? Reject
+  drift toward the latter.'
+- 'Active planning entry point: <path to master plan, roadmap doc, or tracking
+  project>. The primer must not record session-level progress, current focus,
+  completed-session lists, or release-cadence details copied from the plan; those
+  stale quickly. A fresh agent reads this pointer, checks the active plan or
+  assigned ticket for scope, then follows the default session workflow recorded
+  in this primer.'
+- 'Default session workflow: 1) Load primer with `kd /primer show -o yaml`. 2) Read
+  the assigned ticket or active planning source; if tracked work lacks a ticket,
+  create one with `kd /issue create ... --project <PROJECT> --type <Feature|Bug|Task>`
+  and use the returned ID. 3) Enter plan mode for a full tracked session and write
+  the session doc from the local template, naming the file with the ticket ID when
+  present. 4) Execute code, tests, and docs together; run the project''s test, lint,
+  and type checks before commit. 5) Commit with `<TICKET-PREFIX>-NN: <subject>` for
+  tracked work. 6) Install the built artifact, run applicable HITL against a real
+  target, append the session conclusion, comment on the ticket, transition it to
+  <done-state>, and update the relevant plan and docs. If no ticket or user-visible
+  HITL surface exists, record that explicitly in the session doc.'
+
+tags: []
+
+# Pin canonical reference articles after `kd /primer init`. Example shape:
+#   - id: <ARTICLE-ID>
+#     summary: <one-line hook — what this pinned article gives the operator>
+articles: []

{kd_cli-2.3.0 → kd_cli-2.4.1/kd_cli.egg-info}/PKG-INFO

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

{kd_cli-2.3.0 → kd_cli-2.4.1}/kd_cli.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ kd/connection.py
 kd/debug.py
 kd/exceptions.py
 kd/history.py
+kd/locking.py
 kd/operating_guide.py
 kd/primer.py
 kd/query_parser.py
@@ -32,6 +33,7 @@ kd/cli/tree.py
 kd/cli/core/__init__.py
 kd/cli/core/command_base.py
 kd/cli/core/command_parser.py
+kd/cli/core/confirm.py
 kd/cli/core/namespaces.py
 kd/cli/core/option_registry.py
 kd/cli/namespaces/__init__.py
@@ -68,6 +70,8 @@ kd/resources/command-synonyms.yaml
 kd/resources/config-template.yaml
 kd/resources/error-messages.yaml
 kd/resources/operating-guide.md
+kd/resources/primers/__init__.py
+kd/resources/primers/hitl.yaml
 kd_cli.egg-info/PKG-INFO
 kd_cli.egg-info/SOURCES.txt
 kd_cli.egg-info/dependency_links.txt

{kd_cli-2.3.0 → kd_cli-2.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kd-cli"
-version = "2.3.0"
+version = "2.4.1"
 description = "Knowledge Dispatcher for issue trackers and knowledge bases"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -57,7 +57,7 @@ kd = "kd.cli.main:main"
 include = ["kd*"]
 
 [tool.setuptools.package-data]
-kd = ["resources/*.yaml", "resources/*.md"]
+kd = ["resources/*.yaml", "resources/*.md", "resources/primers/*.yaml"]
 
 [tool.ruff]
 exclude = ["docs"]