kingdom-cli 0.5.2__tar.gz → 0.6.0__tar.gz

{kingdom_cli-0.5.2/src/kingdom_cli.egg-info → kingdom_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kingdom-cli
-Version: 0.5.2
+Version: 0.6.0
 Summary: A markdown file-based CLI for software development with multi-agent council design, markdown tickets, and background worker loops.
 Author: James Robinson-Bohnslav
 License-Expression: Apache-2.0

{kingdom_cli-0.5.2 → kingdom_cli-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kingdom-cli"
-version = "0.5.2"
+version = "0.6.0"
 description = "A markdown file-based CLI for software development with multi-agent council design, markdown tickets, and background worker loops."
 readme = "README.md"
 requires-python = ">=3.11"

{kingdom_cli-0.5.2 → kingdom_cli-0.6.0}/src/kingdom/agent.py

@@ -10,14 +10,19 @@ from __future__ import annotations
 
 import json
 import logging
+import os
 import shlex
 from collections.abc import Callable
 from dataclasses import dataclass, field
+from pathlib import Path
 
 from kingdom.config import AgentDef
 
 logger = logging.getLogger(__name__)
 
+CODEX_CLI_PATH_ENV = "CODEX_CLI_PATH"
+CODEX_APP_CLI_PATH = Path("/Applications/Codex.app/Contents/Resources/codex")
+
 
 # ---------------------------------------------------------------------------
 # Backend defaults — CLI invocation details that live in code, not config
@@ -429,7 +434,16 @@ def build_codex_command(
     if skip_permissions:
         parts.insert(1, "--dangerously-bypass-approvals-and-sandbox")
     else:
-        parts.extend(["-c", 'sandbox_permissions=["disk-full-read-access"]'])
+        parts.extend(
+            [
+                "-c",
+                'sandbox_permissions=["disk-full-read-access"]',
+                "-c",
+                "mcp_servers={}",
+                "-c",
+                "plugins={}",
+            ]
+        )
     if config.model:
         parts.extend(["--model", config.model])
     if config.reasoning_effort:
@@ -496,6 +510,38 @@ COMMAND_BUILDERS: dict[str, CommandBuilder] = {
 }
 
 
+def executable_file(path: Path) -> bool:
+    """Return True when path points at an executable file."""
+    return path.is_file() and os.access(path, os.X_OK)
+
+
+def find_codex_cli_path(env: dict[str, str]) -> Path | None:
+    """Find the preferred Codex CLI binary for spawned agent processes."""
+    configured = env.get(CODEX_CLI_PATH_ENV)
+    if configured and executable_file(Path(configured)):
+        return Path(configured)
+    if executable_file(CODEX_APP_CLI_PATH):
+        return CODEX_APP_CLI_PATH
+    return None
+
+
+def prepend_path_entry(path_value: str, entry: Path) -> str:
+    """Prepend entry to PATH unless it is already present."""
+    entry_text = str(entry)
+    parts = [part for part in path_value.split(os.pathsep) if part]
+    parts = [part for part in parts if part != entry_text]
+    return os.pathsep.join([entry_text, *parts])
+
+
+def prefer_codex_cli_path(env: dict[str, str]) -> None:
+    """Make plain ``codex`` resolve to the preferred Codex CLI binary."""
+    codex_cli = find_codex_cli_path(env)
+    if codex_cli is None:
+        return
+    env[CODEX_CLI_PATH_ENV] = str(codex_cli)
+    env["PATH"] = prepend_path_entry(env.get("PATH", ""), codex_cli.parent)
+
+
 def clean_agent_env(
     role: str | None = None,
     agent_name: str | None = None,
@@ -510,9 +556,8 @@ def clean_agent_env(
     ``KD_BASE`` ensures worktree agents resolve the project root against the
     main repo, not the worktree's copy of ``.kd/``.
     """
-    import os
-
     env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"}
+    prefer_codex_cli_path(env)
     if role:
         env["KD_ROLE"] = role
     if agent_name:

{kingdom_cli-0.5.2 → kingdom_cli-0.6.0}/src/kingdom/cli/hook.py

@@ -17,6 +17,17 @@ from pathlib import Path
 
 import typer
 
+from kingdom.state import (
+    archive_root,
+    backlog_root,
+    branch_root,
+    find_project_root,
+    normalize_branch_name,
+    read_terminal_ticket_context,
+    resolve_current_run,
+)
+from kingdom.ticket import read_ticket
+
 hook_app = typer.Typer(name="hook", help="Claude Code hook handlers (internal).")
 
 # ---------------------------------------------------------------------------
@@ -36,6 +47,7 @@ SESSION_START_BRIEF = (
 
 USER_PROMPT_REMINDER = (
     "Kingdom: keep the ticket accurate (body/AC/status/worklog)."
+    " Prefer the last ticket started in this terminal with `kd tk start` when logging."
     " Requirement or acceptance-criteria change -> edit ticket markdown now."
     " Work/findings -> kd tk log. New bug/scope -> kd tk create|move."
 )
@@ -74,6 +86,100 @@ def write_turn_state(path: Path, state: dict) -> None:
     path.write_text(json.dumps(state))
 
 
+def tool_file_path(data: dict) -> str | None:
+    file_path = data.get("tool_input", {}).get("file_path")
+    if isinstance(file_path, str) and file_path:
+        return file_path
+    return None
+
+
+def is_ticket_markdown_path(file_path: str, project_dir: str | None) -> bool:
+    path = Path(file_path)
+    if not path.is_absolute():
+        base = Path(project_dir) if project_dir else Path(".")
+        path = base / path
+
+    path = path.resolve(strict=False)
+    return path.suffix == ".md" and path.parent.name == "tickets" and ".kd" in path.parts
+
+
+def is_ticket_markdown_tool_use(data: dict, project_dir: str | None) -> bool:
+    file_path = tool_file_path(data)
+    return file_path is not None and is_ticket_markdown_path(file_path, project_dir)
+
+
+def ticket_paths_for_terminal_context(base: Path, ticket_id: str, feature: str, location: str | None) -> list[Path]:
+    if location == "backlog":
+        tickets_dir = backlog_root(base) / "tickets"
+    elif location and location.startswith("archive:"):
+        tickets_dir = archive_root(base) / location.removeprefix("archive:") / "tickets"
+    elif location and location.startswith("branch:"):
+        tickets_dir = branch_root(base, location.removeprefix("branch:")) / "tickets"
+    else:
+        tickets_dir = branch_root(base, feature) / "tickets"
+
+    return [tickets_dir / f"{ticket_id}.md", tickets_dir / f"kin-{ticket_id}.md"]
+
+
+def terminal_context_ticket_is_current(base: Path, ticket_id: str, feature: str, location: str | None = None) -> bool:
+    candidate_paths = ticket_paths_for_terminal_context(base, ticket_id, feature, location)
+    for ticket_path in candidate_paths:
+        try:
+            ticket = read_ticket(ticket_path)
+        except (FileNotFoundError, ValueError, OSError):
+            continue
+        return (
+            ticket.id == ticket_id
+            and ticket.status == "in_progress"
+            and not (ticket.assignee or "").startswith("peasant-")
+        )
+    return False
+
+
+def terminal_context_base(project_dir: str | None) -> Path:
+    fallback = Path(project_dir) if project_dir else Path(".")
+    try:
+        return find_project_root(fallback)
+    except ValueError:
+        return fallback
+
+
+def find_stop_ticket_id(project_dir: str | None, session_id: str) -> str | None:
+    base = terminal_context_base(project_dir)
+    terminal_context = read_terminal_ticket_context(base, session_id=session_id)
+    if terminal_context:
+        try:
+            current_feature = normalize_branch_name(resolve_current_run(base))
+        except (RuntimeError, ValueError):
+            current_feature = None
+        ticket_id = terminal_context["ticket_id"]
+        if (
+            current_feature
+            and terminal_context.get("feature") == current_feature
+            and terminal_context_ticket_is_current(
+                base,
+                ticket_id,
+                current_feature,
+                terminal_context.get("location"),
+            )
+        ):
+            return ticket_id
+
+    try:
+        proc = subprocess.run(
+            ["kd", "tk", "current", "--id", "--exclude-peasant"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        ticket_id = proc.stdout.strip()
+        if proc.returncode != 0 or not ticket_id:
+            return None
+        return ticket_id
+    except Exception:
+        return None
+
+
 # ---------------------------------------------------------------------------
 # Event handlers — each returns a string to print to stdout (or empty).
 # ---------------------------------------------------------------------------
@@ -130,10 +236,14 @@ def handle_post_tool_use(data: dict) -> str:
         return ""
 
     tool = data.get("tool_name", "")
+    ticket_markdown_edit = is_ticket_markdown_tool_use(data, project_dir)
 
-    if tool in WORK_TOOLS:
+    if tool in WORK_TOOLS and not ticket_markdown_edit:
         state["had_work"] = True
 
+    if ticket_markdown_edit:
+        state["did_log"] = True
+
     if tool == "Bash":
         cmd = data.get("tool_input", {}).get("command", "")
         if "kd tk log" in cmd or "kd ticket log" in cmd:
@@ -162,17 +272,8 @@ def handle_stop(data: dict) -> str:
         return ""
 
     # Check for an active ticket (fail-open on any error).
-    try:
-        proc = subprocess.run(
-            ["kd", "tk", "current", "--id", "--exclude-peasant"],
-            capture_output=True,
-            text=True,
-            timeout=5,
-        )
-        ticket_id = proc.stdout.strip()
-        if proc.returncode != 0 or not ticket_id:
-            return ""  # No active ticket — fail open.
-    except Exception:
+    ticket_id = find_stop_ticket_id(project_dir, session_id)
+    if not ticket_id:
         return ""  # Timeout or error — fail open.
 
     result = {

{kingdom_cli-0.5.2 → kingdom_cli-0.6.0}/src/kingdom/cli/ticket.py

@@ -27,6 +27,7 @@ from kingdom.state import (
     branch_root,
     branches_root,
     normalize_branch_name,
+    record_terminal_ticket_context,
     resolve_current_run,
 )
 from kingdom.ticket import (
@@ -471,6 +472,11 @@ def ticket_list(
         bool, typer.Option("--include-done", help="Include tickets from done branches (with --all).")
     ] = False,
     include_closed: Annotated[bool, typer.Option("--closed", help="Include closed tickets in output.")] = False,
+    recently_closed: Annotated[
+        bool,
+        typer.Option("--recently-closed", "--recent", help="Show closed tickets ordered by most recent closure."),
+    ] = False,
+    limit: Annotated[int | None, typer.Option("--limit", "-n", help="Limit the number of tickets shown.")] = None,
     ready: Annotated[bool, typer.Option("--ready", help="Show only tickets ready to work (no open deps).")] = False,
     blocked: Annotated[bool, typer.Option("--blocked", help="Show only tickets blocked by open deps.")] = False,
     status: Annotated[
@@ -497,6 +503,14 @@ def ticket_list(
         print_error("--ready and --blocked are mutually exclusive.")
         raise typer.Exit(code=1)
 
+    if recently_closed and (ready or blocked):
+        print_error("--recently-closed cannot be combined with --ready or --blocked.")
+        raise typer.Exit(code=1)
+
+    if limit is not None and limit < 1:
+        print_error("--limit must be 1 or greater.")
+        raise typer.Exit(code=1)
+
     # --jq implies --json
     if jq_filter:
         output_json = True
@@ -507,17 +521,31 @@ def ticket_list(
             print_error(f"Invalid status '{status}'. Valid statuses: {', '.join(sorted(STATUSES))}")
             raise typer.Exit(code=1)
 
+    if recently_closed:
+        if status is not None and status != "closed":
+            print_error("--recently-closed can only be combined with --status closed.")
+            raise typer.Exit(code=1)
+        status = "closed"
+        include_closed = True
+
     if priority is not None and priority not in (0, 1, 2, 3):
         print_error(f"Invalid priority {priority}. Must be 0, 1, 2, or 3.")
         raise typer.Exit(code=1)
 
+    def order_and_limit(tickets: list[Ticket]) -> list[Ticket]:
+        if recently_closed:
+            tickets = sorted(tickets, key=lambda ticket: ticket.closed_at or ticket.created, reverse=True)
+        if limit is not None:
+            tickets = tickets[:limit]
+        return tickets
+
     def apply_all_filters(tickets: list[Ticket], status_by_id: dict[str, str]) -> list[Ticket]:
         filtered = filter_tickets_by_status(tickets, status, include_closed)
         filtered = filter_tickets(filtered, assignee=assignee, tag=tag, priority=priority)
         filtered = filter_tickets_by_deps(filtered, status_by_id, ready=ready, blocked=blocked)
         if resolved_parent_id:
             filtered = [t for t in filtered if t.parent == resolved_parent_id]
-        return filtered
+        return order_and_limit(filtered)
 
     def output_tickets_json(tickets: list[Ticket], location_map: dict[str, str] | None = None) -> None:
         """Output tickets as JSON, optionally piping through jq."""
@@ -557,20 +585,34 @@ def ticket_list(
 
     # Build a global status lookup for dep-based filtering and dep annotations.
     # Always include done branches so deps in done branches get correct ✓ marks.
-    all_known_tickets = collect_all_tickets(base, include_done=True)
+    all_known_tickets = collect_all_tickets(base, include_archive=recently_closed, include_done=True)
     status_by_id = {t.id: t.status for t in all_known_tickets}
 
     if backlog:
         backlog_dir = backlog_root(base) / "tickets"
-        all_backlog_tickets = list_tickets(backlog_dir) if backlog_dir.exists() else []
+        backlog_pairs: list[tuple[str, Ticket]] = []
+        if backlog_dir.exists():
+            backlog_pairs.extend(("backlog", ticket) for ticket in list_tickets(backlog_dir))
+        if recently_closed:
+            archive_backlog_dir = archive_root(base) / "backlog" / "tickets"
+            if archive_backlog_dir.exists():
+                backlog_pairs.extend(("archive:backlog", ticket) for ticket in list_tickets(archive_backlog_dir))
+        all_backlog_tickets = [ticket for _, ticket in backlog_pairs]
         tickets = apply_all_filters(all_backlog_tickets, status_by_id)
+        filtered_ids = {ticket.id for ticket in tickets}
+        location_map = {
+            ticket.id: location_name for location_name, ticket in backlog_pairs if ticket.id in filtered_ids
+        }
 
         if output_json:
-            output_tickets_json(tickets, {t.id: "backlog" for t in tickets})
+            output_tickets_json(tickets, location_map)
         else:
             if not tickets:
-                closed_count = sum(1 for t in all_backlog_tickets if t.status == "closed")
-                if closed_count and not include_closed and status is None and not ready and not blocked:
+                if recently_closed:
+                    typer.echo("No recently closed backlog tickets.")
+                elif (closed_count := sum(1 for t in all_backlog_tickets if t.status == "closed")) and (
+                    not include_closed and status is None and not ready and not blocked
+                ):
                     typer.echo(f"No open backlog tickets ({closed_count} closed). Use --closed to show them.")
                 else:
                     typer.echo('No backlog tickets. Create one with `kd tk create --backlog "title"`.')
@@ -580,7 +622,7 @@ def ticket_list(
         return
 
     if all_tickets:
-        pairs = collect_tickets_by_location(base, include_done=include_done)
+        pairs = collect_tickets_by_location(base, include_archive=recently_closed, include_done=include_done)
         all_filtered: list[Ticket] = []
         location_map: dict[str, str] = {}
         for location_name, ticket in pairs:
@@ -595,8 +637,11 @@ def ticket_list(
             output_tickets_json(all_filtered, location_map)
         else:
             if not all_filtered:
-                closed_count = sum(1 for _, t in pairs if t.status == "closed")
-                if closed_count and not include_closed and status is None and not ready and not blocked:
+                if recently_closed:
+                    typer.echo("No recently closed tickets found across any branch or backlog.")
+                elif (closed_count := sum(1 for _, t in pairs if t.status == "closed")) and (
+                    not include_closed and status is None and not ready and not blocked
+                ):
                     typer.echo(f"No open tickets ({closed_count} closed). Use --closed to show them.")
                 else:
                     typer.echo('No tickets found across any branch or backlog. Create one with `kd tk create "title"`.')
@@ -613,8 +658,11 @@ def ticket_list(
             output_tickets_json(tickets)
         else:
             if not tickets:
-                closed_count = sum(1 for t in all_branch_tickets if t.status == "closed")
-                if closed_count and not include_closed and status is None and not ready and not blocked:
+                if recently_closed:
+                    typer.echo("No recently closed tickets found on this branch.")
+                elif (closed_count := sum(1 for t in all_branch_tickets if t.status == "closed")) and (
+                    not include_closed and status is None and not ready and not blocked
+                ):
                     typer.echo(f"No open tickets ({closed_count} closed). Use --closed to show them.")
                 else:
                     typer.echo('No tickets found. Create one with `kd tk create "title"`.')
@@ -709,7 +757,7 @@ def ticket_find(
     typer.echo(ticket_path.resolve())
 
 
-def update_ticket_status(ticket_id: str, new_status: str, *, assignee: str | None = None) -> None:
+def update_ticket_status(ticket_id: str, new_status: str, *, assignee: str | None = None) -> Ticket:
     """Helper to update a ticket's status."""
     base = require_project_root()
 
@@ -741,13 +789,53 @@ def update_ticket_status(ticket_id: str, new_status: str, *, assignee: str | Non
             for t in unblocked:
                 typer.echo(f"  {t.id} [P{t.priority}] — {t.title}")
 
+    return ticket
+
+
+def terminal_context_location_for_start(base: Path, ticket_path: Path) -> str:
+    backlog_tickets = (backlog_root(base) / "tickets").resolve()
+    archive_backlog_tickets = (archive_root(base) / "backlog" / "tickets").resolve()
+    ticket_parent = ticket_path.parent.resolve()
+
+    if ticket_parent in (backlog_tickets, archive_backlog_tickets):
+        return "backlog"
+
+    archive = archive_root(base).resolve()
+    try:
+        archived = ticket_parent.relative_to(archive)
+    except ValueError:
+        pass
+    else:
+        if len(archived.parts) >= 2 and archived.parts[1] == "tickets":
+            return f"archive:{archived.parts[0]}"
+
+    branches = branches_root(base).resolve()
+    try:
+        relative = ticket_parent.relative_to(branches)
+    except ValueError:
+        return f"branch:{normalize_branch_name(resolve_current_run(base))}"
+
+    if len(relative.parts) >= 2 and relative.parts[1] == "tickets":
+        return f"branch:{relative.parts[0]}"
+    return f"branch:{normalize_branch_name(resolve_current_run(base))}"
+
 
 @ticket_app.command("start", help="Mark a ticket as in_progress.")
 def ticket_start(
     ticket_id: Annotated[str, typer.Argument(help="Ticket ID (full or partial).")],
 ) -> None:
     """Set ticket status to in_progress and assign it to the Hand."""
-    update_ticket_status(ticket_id, "in_progress", assignee="hand")
+    base = require_project_root()
+    try:
+        feature = resolve_current_run(base)
+    except RuntimeError:
+        print_error("No active session. Use `kd start` first.")
+        raise typer.Exit(code=1) from None
+
+    _, ticket_path = resolve_ticket_or_exit(base, ticket_id)
+    location = terminal_context_location_for_start(base, ticket_path)
+    ticket = update_ticket_status(ticket_id, "in_progress", assignee="hand")
+    record_terminal_ticket_context(base, ticket.id, feature=feature, location=location)
 
 
 @ticket_app.command("current", help="Show the in-progress ticket for this branch.")

{kingdom_cli-0.5.2 → kingdom_cli-0.6.0}/src/kingdom/skill/SKILL.md

@@ -69,7 +69,7 @@ kd council ask "Should we use WebSockets or SSE for real-time updates? We need l
 
 **King says "ask the council."** Every `kd council ask` creates a new thread by default. If the conversation is a continuation of an active design discussion, use `kd council ask --continue "follow-up question"` to append to the current thread. When ambiguous, check existing threads with `kd council list` or `kd council show <thread>`, or ask the King a brief clarifying question before running the command.
 
-**King wants to note progress.** Update the active ticket's Markdown directly when you are already editing ticket content; use `kd tk log` for quick one-off entries:
+**King wants to note progress.** Update the active ticket's Markdown directly for anything more than a short one-line note. Use `kd tk log` only for quick one-off worklog entries:
 
 ```
 kd tk log ab12 "Finished the API refactor, all endpoint tests passing"
@@ -123,7 +123,7 @@ Use A when the King wants to be hands-on. Use B for throughput on well-scoped ti
 This applies regardless of execution mode.
 
 - **One at a time per worker**: `kd tk start <id>` → do the work → `kd tk close <id>` → commit → next ticket.
-- **Worklog**: append progress notes to the ticket's `## Worklog` section as you go. Prefer reading and editing the ticket Markdown directly when making multiple ticket updates in a turn; use `kd tk log` only for a quick one-off entry. Log what you're doing, what you found, commands and results, decisions and why. The King reads these to stay informed — don't make them ask.
+- **Worklog**: append progress notes to the ticket's `## Worklog` section as you go. Edit the ticket Markdown file directly when making ticket updates in a turn; use `kd tk log` only for a quick one-off entry. Log what you're doing, what you found, commands and results, decisions and why. The King reads these to stay informed — don't make them ask.
 - **Acceptance criteria**: only close a ticket when all acceptance criteria are met and the full test suite is green.
 - **Decisions**: ask the King or consult the council (`kd council ask "..."`) for difficult design decisions — don't guess. Never silently resolve ambiguity on architectural, product, or UX tradeoffs.
 - **For bugs: test BEFORE you fix!** Write a test that fails in the current state, fix it, then verify.
@@ -132,17 +132,42 @@ This applies regardless of execution mode.
 - **Commit often**: commit code changes as you go. Commit `.kd/` changes (ticket state, worklogs) alongside code.
 - **One-off tests**: write a script or temp file to test an end-to-end flow with real data. Then consider if it can be an automated integration test.
 
+## Ticket Markdown Is the Source of Truth
+
+Ticket files are plain Markdown and are meant to be edited directly. Direct file edits are normal, expected, and often the best tool for ticket content changes.
+
+Use `kd` for lifecycle and discovery: create, pull, move, start, close, reopen, assign, deps, list, show, and find. For creation, prefer making a quick stub with the CLI, then immediately editing the ticket Markdown for the real content:
+
+```
+kd tk create "Short working title"
+kd tk find <id>
+# edit the printed Markdown file directly
+```
+
+Keep CLI flags minimal when creating the stub. Rich descriptions, acceptance criteria, investigation notes, and scope changes belong in the Markdown file where agents can write clearly.
+
+Once you need to change ticket content, use `kd tk find <id>` or the `File:` line from `kd tk show <id>` to locate the file, then edit the Markdown directly.
+
+Edit the Markdown file directly for:
+
+- ticket descriptions, requirements, and scope changes
+- acceptance criteria additions, rewrites, and checkbox updates
+- multi-line worklog entries with context, evidence, commands, and decisions
+- correcting stale or misleading ticket text
+
+Do not search for a CLI command to encode every Markdown edit. If you already know the ticket file path and the change belongs in the ticket body, patch the file.
+
 ## Automatic Worklog Updates
 
 Proactively update the ticket worklog whenever a durable state change occurs. The King should never have to say "update the worklog." Log against the active ticket without asking which ticket — you know what you're working on.
 
 The threshold is **durable state change**, not every chat turn. If future-you or another agent would need this fact, log it now.
 
-**Log before you continue.** When you discover durable information — a relevant issue, a root cause, a key finding from research — update the ticket immediately, before continuing your work. Prefer direct Markdown edits after reading the ticket file; use `kd tk log` for quick one-off entries. The worklog survives context compaction; chat doesn't. Don't let valuable findings exist only in conversation history that will be compressed away.
+**Log before you continue.** When you discover durable information — a relevant issue, a root cause, a key finding from research — update the ticket immediately, before continuing your work. Edit the ticket Markdown directly after reading the file; use `kd tk log` only for short one-off entries. The worklog survives context compaction; chat doesn't. Don't let valuable findings exist only in conversation history that will be compressed away.
 
 **Edit ticket body vs worklog.** If the King changes requirements or acceptance criteria, update the ticket's Markdown directly (description, AC section). The worklog is for timeline events — decisions, findings, progress, blockers. Don't stuff requirements into `kd tk log`; edit the ticket file instead.
 
-**LLM-friendly ticket reading.** `kd tk show <id>` prints raw ticket Markdown by default so agents can read the same file they should edit. The final `File:` line gives the ticket path; when you only need that path, use `kd tk find <id>`, which searches branch, backlog, and closed/archive tickets and prints the full file path. This also works from a sibling git worktree whose checkout does not have `.kd/`. Use `kd tk show <id> --rich` only when a framed human display is useful.
+**LLM-friendly ticket reading.** `kd tk show <id>` prints raw ticket Markdown by default so agents can read the same file they should edit. The final `File:` line gives the ticket path; when you only need that path, use `kd tk find <id>`, which searches branch, backlog, and closed/archive tickets and prints the full file path. After you have the path, edit that file directly for content changes. This also works from a sibling git worktree whose checkout does not have `.kd/`. Use `kd tk show <id> --rich` only when a framed human display is useful.
 
 **Decision made** — King says "let's go with raw TypeScript over React":
 
@@ -242,6 +267,7 @@ Accept is idempotent: if the ticket branch is already merged into the feature br
 kd start / status / done                                # branch lifecycle
 kd design show / design approve                         # design doc
 kd tk list / show / find / list --ready                 # inspect tickets; find prints the ticket file path
+kd tk list --recently-closed --limit 10                 # inspect recently completed work
 kd tk start <id> / close <id>                           # work a ticket
 kd tk current                                           # show active ticket
 kd tk pull <id>...                                      # pull from backlog

{kingdom_cli-0.5.2 → kingdom_cli-0.6.0}/src/kingdom/skill/references/tickets.md

@@ -62,6 +62,8 @@ kd tk unassign <id>          # clear assignment
 
 ```bash
 kd tk list                   # list all tickets on current branch
+kd tk list --recently-closed # show closed tickets ordered by most recent close
+kd tk list --recent --limit 10  # short alias plus result limit
 kd tk show <id>              # print raw ticket Markdown (LLM-friendly)
 kd tk show <id> --rich       # show framed human-friendly ticket details
 kd tk move <id> --to <branch|backlog>  # move to another branch or backlog
@@ -76,6 +78,8 @@ The backlog at `.kd/backlog/tickets/` holds tickets not assigned to any branch.
 
 - **Commit `.kd/` changes as you go** — ticket state changes, closures, and moves are tracked in git
 - **Use dependencies** to enforce ordering when tickets have prerequisites
+- **Edit ticket Markdown directly** for body text, acceptance criteria, scope changes, and multi-line worklog entries
+- **Use `kd tk log` only for short one-off worklog notes**; do not contort ticket content edits through CLI commands
 - **Append a work log** to the ticket body when closing — record key decisions and what was done
-- **Prefer direct Markdown edits** when agents need to update ticket body, acceptance criteria, and worklog repeatedly in one turn
 - **Use `kd tk list --ready`** to find the next unblocked ticket rather than picking arbitrarily
+- **Use `kd tk list --recently-closed --limit 10`** when reviewing recently completed work