kd-cli 2.2.2__tar.gz → 2.4.0__tar.gz

{kd_cli-2.2.2/kd_cli.egg-info → kd_cli-2.4.0}/PKG-INFO

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

kd_cli-2.4.0/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.2.2 → kd_cli-2.4.0}/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.2.2 → kd_cli-2.4.0}/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.2.2 → kd_cli-2.4.0}/kd/cli/namespaces/article/__init__.py

@@ -181,7 +181,7 @@ class ArticlePushCommand(Command):
             requires_client=True,
             usage=(
                 "kd /article push FILE --project P --title T "
-                "[--slug S] [--parent ID] [--tag T] [--force] [--dry-run]"
+                "[--slug S] [--parent ID] [--tag T] [--create-tags] [--force] [--dry-run]"
             ),
             long_description=(
                 "Push a local markdown file to YouTrack as a knowledge base "
@@ -201,6 +201,7 @@ class ArticlePushCommand(Command):
                 'kd /article push guide.md --project FB --title "User Guide" --parent FB-A-1',
                 'kd /article push guide.md --project FB --title "Guide" --tag "type:guide"',
                 'kd /article push guide.md --project FB --title "Guide" --tag "type:guide" --tag "platform:rdk-e"',
+                'kd /article push guide.md --project FB --title "Guide" --tag "type:guide" --create-tags',
                 'kd /article push guide.md --project FB --title "Guide" --dry-run',
                 'kd /article push guide.md --project FB --title "Guide" --force',
             ],
@@ -264,6 +265,15 @@ class ArticlePushCommand(Command):
                 help_text="Resolve and validate, but do not write anywhere",
             )
         )
+        self.register_option(
+            OptionDeclaration(
+                name="create-tags",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                default=False,
+                help_text="Create missing tags before pushing",
+            )
+        )
 
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
@@ -289,6 +299,7 @@ class ArticlePushCommand(Command):
             force=bool(options.command.get("force")),
             dry_run=bool(options.command.get("dry-run")),
             tags=tags or None,
+            create_tags=bool(options.command.get("create-tags")),
         )
         return {
             "ok": True,

{kd_cli-2.2.2 → kd_cli-2.4.0}/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.2.2 → kd_cli-2.4.0}/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.2.2 → kd_cli-2.4.0}/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.2.2 → kd_cli-2.4.0}/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.2.2 → kd_cli-2.4.0}/kd/client.py

@@ -20,6 +20,7 @@ from __future__ import annotations
 
 import builtins
 import difflib
+import shlex
 from collections import OrderedDict
 from dataclasses import dataclass, field as dataclass_field
 from datetime import datetime, timezone
@@ -43,7 +44,7 @@ from kd.article_marker import (
 from kd.config import ResolvedConfig
 from kd.connection import ConnectionContext
 from kd.debug import DebugLog
-from kd.exceptions import APIError, ConfigError, NotFoundError, ValidationError, KdError
+from kd.exceptions import APIError, ConfigError, KdError, NotFoundError, ValidationError
 from kd.query_parser import youtrack_query_literal
 from kd.models import (
     Article,
@@ -1013,6 +1014,44 @@ class TimeOperations:
         raise ValidationError(f"Unknown work item type '{name}'. Available: {available}")
 
 
+def _tag_prefix_for_list(tag: str) -> str:
+    """Return the smallest useful prefix for missing-tag discovery."""
+    if ":" in tag:
+        return tag.split(":", 1)[0] + ":"
+    return tag
+
+
+def _extract_tag_suggestions(error: NotFoundError) -> builtins.list[str]:
+    """Extract close-match names from the existing tag resolver message."""
+    message = str(error)
+    marker = "Did you mean: "
+    if marker not in message:
+        return []
+    raw = message.split(marker, 1)[1].rstrip(".?")
+    return [part.strip() for part in raw.split(",") if part.strip()]
+
+
+def _missing_tag_resolution(tag: str, error: NotFoundError) -> str:
+    """Format an actionable missing-tag instruction for article push."""
+    lines = [f"Tag '{tag}' not found."]
+    suggestions = _extract_tag_suggestions(error)
+    if suggestions:
+        lines.append(f"  Near matches: {', '.join(suggestions)}")
+    prefix = _tag_prefix_for_list(tag)
+    lines.extend(
+        [
+            "",
+            f"To use an existing tag:   kd /tag list --prefix {shlex.quote(prefix)}",
+            f"To create a new tag:      kd /tag create {shlex.quote(tag)}",
+            f"To retry push without this tag: omit --tag {shlex.quote(tag)}",
+            "",
+            "If you are still curating the tag set, push without --tag and apply tags",
+            f"separately with kd /tag add ARTICLE-ID {shlex.quote(tag)}.",
+        ]
+    )
+    return "\n".join(lines)
+
+
 class ArticleOperations:
     """High-level knowledge base article operations."""
 
@@ -1137,6 +1176,41 @@ class ArticleOperations:
                 failed.append(f"{tag} ({exc})")
         return applied, failed
 
+    def _preflight_tags(
+        self,
+        tags: builtins.list[str],
+        *,
+        create_missing: bool = False,
+        dry_run: bool = False,
+    ) -> builtins.list[str]:
+        """Resolve tags before mutating an article.
+
+        Returns actionable failure blocks. When ``create_missing`` is true,
+        missing tags are created before the article write; ``dry_run`` never
+        writes tags and treats missing tags as would-create.
+        """
+        if self._tag_ops is None:
+            raise KdError("Tag operations not available")
+        failed: builtins.list[str] = []
+        for tag in tags:
+            try:
+                self._tag_ops.get(tag)
+            except NotFoundError as exc:
+                if create_missing:
+                    if dry_run:
+                        continue
+                    try:
+                        self._tag_ops.create(tag)
+                    except KdError as create_exc:
+                        failed.append(
+                            f"Tag '{tag}' not found and could not be created. {create_exc}"
+                        )
+                    continue
+                failed.append(_missing_tag_resolution(tag, exc))
+            except KdError as exc:
+                failed.append(f"Tag '{tag}' could not be resolved. {exc}")
+        return failed
+
     def update(
         self,
         article_id: str,
@@ -1160,6 +1234,7 @@ class ArticleOperations:
         force: bool = False,
         dry_run: bool = False,
         tags: builtins.list[str] | None = None,
+        create_tags: bool = False,
     ) -> PushResult:
         """Idempotently upsert a local markdown file as a YouTrack article.
 
@@ -1278,6 +1353,18 @@ class ArticleOperations:
                 f"move {existing_remote.id_readable} --parent {parent}."
             )
 
+        if tags:
+            preflight_failed = self._preflight_tags(
+                tags,
+                create_missing=create_tags,
+                dry_run=dry_run,
+            )
+            if preflight_failed:
+                raise KdError(
+                    f"Article {'update' if is_update else 'create'} aborted because "
+                    "tagging failed.\n\n" + "\n\n".join(preflight_failed)
+                )
+
         # Dry-run bails out here with all validation done but no writes.
         if dry_run:
             existing_sec = 0

{kd_cli-2.2.2 → kd_cli-2.4.0}/kd/primer.py

@@ -10,6 +10,7 @@ knowledge).  The file is created lazily on first write operation.
 
 from __future__ import annotations
 
+import importlib.resources
 from pathlib import Path
 from typing import Any
 
@@ -283,3 +284,49 @@ def clear_tags(path: Path | None = None) -> int:
     data.tags.clear()
     save_primer(data, primer_file)
     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.2.2 → kd_cli-2.4.0}/kd/resources/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to kd-cli are recorded here. The project follows [Semantic V
 
 ## [Unreleased]
 
+## [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
+- `/article push --create-tags` explicitly creates missing tags before pushing and attaching them, for scripted flows that own their tag namespace (KDCLI-85).
+
+### Fixed
+- `/article push --tag` missing-tag failures now print actionable recovery commands instead of a bare not-found / close-match message (KDCLI-85).
+
 ## [2.2.2] — 2026-04-18
 
 ### Fixed

{kd_cli-2.2.2 → kd_cli-2.4.0}/kd/resources/operating-guide.md

@@ -80,6 +80,15 @@ 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
 
@@ -105,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.
@@ -143,6 +154,8 @@ Use `/article show` for metadata plus rendered content. Use `/article pull` when
 
 Do not use push for one-off web edits or broad tree migration. It is single-file by design. If the remote changed, pull, diff, merge by hand, then push again. Use `--force` only after inspecting the remote state.
 
+When pushing with `--tag`, kd validates all tags before the article write. Missing tags abort with commands to list the namespace, create the tag, retry without it, or apply the tag separately after push. `--create-tags` is the explicit opt-in for automation that should create missing tags first.
+
 ## Tags And Discovery
 
 Tags are the main YouTrack-native cross-entity discovery primitive. A namespaced taxonomy such as `kind:*`, `component:*`, and `outcome:*` gives both humans and LLMs a stable way to move across issues and articles.
@@ -208,4 +221,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.0/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.2.2 → kd_cli-2.4.0/kd_cli.egg-info}/PKG-INFO

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

{kd_cli-2.2.2 → kd_cli-2.4.0}/kd_cli.egg-info/SOURCES.txt

@@ -32,6 +32,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 +69,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.2.2 → kd_cli-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kd-cli"
-version = "2.2.2"
+version = "2.4.0"
 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"]