---
type: "API"
title: "Agent Subcommand Reference"
description: "Reference for spec-kitty agent subcommands. Learn how agent-only actions like config, status, decision, and retrospect behave in workflows."
status: "stable"
generated:
  by: "process:dockitty-export"
  at: "2026-11-11T00:00:00Z"
---

# Agent Subcommand Reference

The `spec-kitty agent` commands are designed for AI agents and automation tooling. They generally emit JSON and update task metadata or mission artifacts directly.

Terminology note:
- `Mission Type` = reusable blueprint
- `Mission` = tracked item under `kitty-specs/<mission-slug>/`
- `Mission Run` = runtime/session instance
- The `agent feature` command group remains a legacy compatibility alias; tracked-mission selectors are documented canonically as `--mission`

## Ambiguous mission selectors

`agent status` and `agent tasks` commands that resolve `--mission` never guess when a handle matches multiple missions. With `--json`, they emit the shared error envelope (`success: false`, `error_code: "MISSION_AMBIGUOUS_SELECTOR"`, `handle`, and `candidates`) and exit `1`. In human mode, they print the ambiguity diagnostic and exit `2`. The read-path fix in #429 deliberately changed this human-mode case from the earlier generic exit code `1` to `2`, aligning it with the other ambiguous mission-handle resolution path.

## Getting Started

- [Claude Code Workflow](/guides/tutorials/claude-code-workflow.md)

## Practical Usage

- [Non-Interactive Init](/guides/how-to/installation/non-interactive-init.md)

## Coordination-routed Missions: where agent writes land

These notes are the hand-authored companion to the generated sections below. They apply to a
Mission whose topology is `coord` or `lanes_with_coord`; the user-facing counterparts
(`accept`, `consolidate`, `materialize`, `spec-commit`, `doctor decisions`) are in
[`cli-commands.md`](/api/cli-commands.md#coordination-routed-missions-where-writes-land). Design
record: the 2026-10-01 amendment of
[ADR 2026-06-19-1](/adr/3.x/2026-06-19-1-coord-empty-surface-fallback.md).

- **`agent mission create`** materializes the coordination worktree, seeds it, and commits the
  creation records on the coordination branch. The target branch receives no coordination
  record. An `--owned-checkout` coordination create keeps its status log in the owned
  checkout's own PRIMARY dir (a named residual).
- **`agent mission finalize-tasks`** refreshes the recorded planning-commit pin automatically
  and reports it in the additive `planning_commit_refresh` JSON field. See
  [`finalize-tasks-internals.md`](/api/finalize-tasks-internals.md#4-automatic-planning-pin-refresh-and-planning_commit_refresh).
  For a Mission authored through `orchestrator-api` it also refuses stale or unfinished content
  with a `DESIGN_*` code, as does native `spec-kitty next --result success`
  ([details](/api/finalize-tasks-internals.md#6-stale-api-authored-content-is-refused)).
- **`agent decision verify`** reports a forked decision log as a `DECISION_LOG_FORKED` finding
  and **exits 1 on a fork regardless of `--fail-on-stale`**. A ledger that exists only on the
  coordination branch is not a fork; repair it with `doctor decisions --repair`. Coordination
  teardown and `consolidate` refuse with `COORDINATION_LEDGER_UNREPAIRED` until it is repaired.
- **Agent writes of coordination records** (status events, decision events, review cycles,
  tracer files) take their directory from the placement seam's write accessor, so a write on a
  not-yet-materialized or empty coordination surface materializes or seeds it (or refuses
  with `COORDINATION_WORKTREE_UNMATERIALIZED` / `COORD_SEED_FORK_REFUSED` / `STATUS_LOCK_HELD`)
  instead of landing on the repository root checkout.

## Coordination status writes: refusal on a diverged status log

Applies to `agent status emit`, `agent tasks move-task` and every other agent command that
records a lane transition on a Mission whose topology is `coord` or `lanes_with_coord`. The
rule and its recovery are stated once, in the
[status model](/architecture/status-model.md#coordination-status-write-guard); this section
only describes what a caller sees.

| Code | Meaning |
|---|---|
| `COORD_STATUS_SURFACE_DIVERGED` | The coordination worktree's status log lost events its branch HEAD has committed. |
| `COORD_STATUS_SURFACE_UNREADABLE` | The committed status log (or the working-tree log) cannot be read or is not a valid event log, so the check cannot be answered. |

Both exit `1` and write nothing: the event log, `status.json` and the coordination branch are
unchanged.

- **Human mode** prints `Error: <CODE>: <message>`.
- **`--json` mode** prints one object with a single `error` key whose value starts with the
  code, for example `{"error": "COORD_STATUS_SURFACE_DIVERGED: the coordination worktree ..."}`.
  There is no separate `error_code` key on this refusal, so match on the prefix of `error`.

The `COORD_STATUS_SURFACE_DIVERGED` message contains both recovery commands with the real
paths and the Mission slug filled in. Do not retry the write unchanged: it refuses again until the worktree log
holds every committed event.

## Owned Missions: where `agent tracer-append` writes

An owned Mission lives in a linked checkout (`P`) rather than in the repository root checkout
(`R`). `agent tracer-append` resolves that ownership fact before it selects its write surface
(#7081):

- **Flagless adoption (single_branch Missions today).** Running the command from inside `P` adopts `P` for the named Mission, so
the entry lands in `P`'s `kitty-specs/<mission-slug>/traces/<category>.md` on the branch `P` is
on. It no longer resolves `R`, writes an untracked `traces/` file there and refuses
`PROTECTED_BRANCH_REFUSED` on `main`.
- **`--owned-checkout <P>`.** The explicit spelling selects the same surface when the command runs
from `R`. It takes the shared owned-checkout help and validation: exactly one validation per
invocation, the repository root refused, lane and coordination worktrees refused, and the
lifecycle topology set (today `single_branch`) enforced.
- **Mission-scoped protection.** The protection policy comes from the Mission's own `meta.json`
(`commit_to_target`) in `P`, never from a copy the repository root happens to hold. Alternate handles
(mid8 or full Mission id) are canonicalized from the validated fact before the commit router
re-applies that policy, so a Mission's legitimate protected-target opt-in is retained.
- **Refuse before writing.** An invalid target exits `1` with the owned refusal envelope
(`{"ok": false, "error": {"code", "message"}}`) before the writer is reached: nothing is staged,
no coordination surface is materialised and neither checkout gains a file.
- **No owned checkout, no change.** Without a flag and without an adoptable checkout (for example
from `R`, or from a lane worktree, which adoption deliberately declines) the command keeps its
historical behaviour: the repository root is the write surface, and a coordination-routed Mission
is committed on its coordination branch.

<!-- BEGIN GENERATED -->
# Agent Subcommand Reference

## spec-kitty agent

_Commands for AI agents to execute spec-kitty mission actions programmatically_

```
 Usage: spec-kitty agent [OPTIONS] COMMAND [ARGS]...

 Commands for AI agents to execute spec-kitty mission actions programmatically

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ tracer-append       Append a dated, attributed finding to the mission's      │
│                     tracer surface.                                          │
│ issue-verdict       Set an issue-matrix row's verdict, routed via            │
│                     ``write_target(ISSUE_MATRIX)``.                          │
│ acceptance-verdict  Record an acceptance-criterion verdict, or               │
│                     register/execute a negative                              │
│                     invariant (FR-007/FR-008) — exactly one of               │
│                     ``--criterion``/                                         │
│                     ``--negative-invariant``, both routed through the WP03   │
│                     write seam.                                              │
│ config              Manage project AI agent configuration (add, remove, list │
│                     agents)                                                  │
│ mission             Mission lifecycle commands for AI agents                 │
│ tasks               Task workflow commands for AI agents                     │
│ context             Agent context management commands                        │
│ release             Release packaging commands for AI agents                 │
│ action              Mission action commands that display prompts and         │
│                     instructions for agents                                  │
│ status              Canonical status management commands                     │
│ tests               Test-related commands for AI agents                      │
│ decision            Decision Moment ledger for interview questions.          │
│ retrospect          Retrospective synthesis commands                         │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent acceptance-verdict

```
 Usage: spec-kitty agent acceptance-verdict [OPTIONS]

 Record an acceptance-criterion verdict, or register/execute a negative
 invariant (FR-007/FR-008) — exactly one of ``--criterion``/
 ``--negative-invariant``, both routed through the WP03 write seam.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission                                  <str>   Mission slug, mid8, or │
│                                                       mission_id             │
│                                                       [required]             │
│    --criterion                                <str>   Acceptance criterion   │
│                                                       id (e.g. FR-001);      │
│                                                       mutually exclusive     │
│                                                       with                   │
│                                                       --negative-invariant   │
│    --result                                   <str>   pass | fail | pending  │
│                                                       | deferred (required   │
│                                                       with --criterion)      │
│    --verification-method                      <str>   Criterion mode: how    │
│                                                       this was verified      │
│                                                       (updates proof_type).  │
│                                                       Negative-invariant     │
│                                                       mode: grep_absence |   │
│                                                       route_check |          │
│                                                       custom_command         │
│                                                       (required with         │
│                                                       --negative-invariant). │
│    --actor                                    <str>   Actor recording this   │
│                                                       verdict                │
│    --evidence                                 <str>   Evidence reference     │
│                                                       (URL/path/etc.)        │
│    --negative-invariant                       <str>   Negative invariant id  │
│                                                       to register/execute    │
│                                                       (FR-007/FR-008);       │
│                                                       mutually exclusive     │
│                                                       with --criterion       │
│    --description                              <str>   Negative invariant     │
│                                                       description (required  │
│                                                       with                   │
│                                                       --negative-invariant); │
│                                                       criterion mode:        │
│                                                       replaces the criterion │
│                                                       description            │
│    --notes                                    <str>   Criterion mode:        │
│                                                       replaces the criterion │
│                                                       notes                  │
│    --reason                                   <str>   Why the criterion is   │
│                                                       deferred (required     │
│                                                       with --result          │
│                                                       deferred)              │
│    --follow-up                                <str>   Follow-up reference:   │
│                                                       issue number/URL or    │
│                                                       ruling id (required    │
│                                                       with --result          │
│                                                       deferred)              │
│    --verification-comma…                      <str>   grep pattern or        │
│                                                       command verifying the  │
│                                                       invariant's absence    │
│    --scope                                    <str>   Whitespace-separated   │
│                                                       repo-relative search   │
│                                                       root(s); grep_absence  │
│                                                       only                   │
│    --execute                  --no-execute            Run the invariant's    │
│                                                       verification           │
│                                                       immediately after      │
│                                                       registering (FR-008;   │
│                                                       default: on)           │
│                                                       [default: execute]     │
│    --owned-checkout                           <path>  Run against an owned   │
│                                                       checkout: a linked     │
│                                                       checkout that owns     │
│                                                       this mission. Refuses  │
│                                                       the repository root    │
│                                                       checkout, lane         │
│                                                       worktrees and          │
│                                                       coordination           │
│                                                       worktrees.             │
│    --json                                             Output JSON format     │
│    --help                 -h                          Show this message and  │
│                                                       exit.                  │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent action

_Mission action commands that display prompts and instructions for agents_

```
 Usage: spec-kitty agent action [OPTIONS] COMMAND [ARGS]...

 Mission action commands that display prompts and instructions for agents

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ implement  Display work package prompt with implementation instructions.     │
│ review     Display work package prompt with review instructions.             │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent action implement

```
 Usage: spec-kitty agent action implement [OPTIONS] [wp_id]

 Display work package prompt with implementation instructions.

 This command outputs the full work package prompt content so agents can
 immediately see what to implement, without navigating the file system.

 Automatically moves WP from planned to in_progress (requires --agent to track
 who is working).

 Examples:
     spec-kitty agent action implement WP01 --agent claude
     spec-kitty agent action implement WP02 --agent claude
     spec-kitty agent action implement wp01 --agent codex
     spec-kitty agent action implement --agent gemini  # auto-detects first
 planned WP

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│   wp_id      <str>  Work package ID (e.g., WP01, wp01, WP01-slug) -          │
│                     auto-detects first planned if omitted                    │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission                            <str>   Mission slug                    │
│ --agent                              <str>   Agent name (required for        │
│                                              auto-move to in_progress). With │
│                                              --force, name the agent that    │
│                                              will implement: it is recorded  │
│                                              as the implementer of record.   │
│ --model                              <str>   Retired for claims: the         │
│                                              correlated Op record carries no │
│                                              model identifier (#7013), so    │
│                                              --model is refused; omit it and │
│                                              the claim records the model as  │
│                                              explicitly absent               │
│ --profile                            <str>   Agent profile id — a dispatch   │
│                                              registry / Op record profile or │
│                                              a local charter profile (the    │
│                                              same ids `agent profile show`   │
│                                              resolves). When omitted, the    │
│                                              work package's frontmatter      │
│                                              agent_profile is used.          │
│ --invocation-id                      <str>   Correlated Op record ULID whose │
│                                              mission, WP, action and profile │
│                                              are authoritative (the record   │
│                                              carries no model, #7013)        │
│ --force                                      Operator override: take a WP    │
│                                              out of for_review, in_review or │
│                                              approved. Requires --note.      │
│                                              Refused for a WP in any other   │
│                                              lane.                           │
│ --note                               <str>   Why the review lane is being    │
│                                              left; recorded in the status    │
│                                              event. Only valid with --force. │
│ --allow-sparse-checkout                      Proceed even if legacy          │
│                                              sparse-checkout state is        │
│                                              detected. Use of this override  │
│                                              is logged. Does not bypass the  │
│                                              commit-time data-loss backstop. │
│ --acknowledge-not-bulk-edit                  Suppress the bulk-edit          │
│                                              inference warning when spec     │
│                                              language resembles a bulk edit  │
│                                              but the mission is not one.     │
│ --owned-checkout                     <path>  Not yet supported. Refused:     │
│                                              owned checkouts use 'spec-kitty │
│                                              next --owned-checkout' and      │
│                                              'spec-kitty agent tasks         │
│                                              move-task --owned-checkout'     │
│                                              instead.                        │
│ --base                               <str>   Explicit base ref for the lane  │
│                                              workspace (default:             │
│                                              auto-detect). Use this when     │
│                                              upstream dependency branches    │
│                                              have been merged-and-deleted    │
│                                              and you want to start from the  │
│                                              current target branch tip, e.g. │
│                                              --base main.                    │
│ --help                       -h              Show this message and exit.     │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent action review

```
 Usage: spec-kitty agent action review [OPTIONS] [wp_id]

 Display work package prompt with review instructions.

 This command outputs the full work package prompt (including any review
 feedback from previous reviews) so agents can review the implementation.

 Automatically moves WP from for_review to in_review (requires --agent to track
 who is reviewing).

 Examples:
     spec-kitty agent action review WP01 --agent claude
     spec-kitty agent action review wp02 --agent codex
     spec-kitty agent action review --agent gemini  # auto-detects first
 for_review WP

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│   wp_id      <str>  Work package ID (e.g., WP01) - auto-detects first        │
│                     for_review if omitted                                    │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission                 <str>   Mission slug                               │
│ --agent                   <str>   Agent name (required for auto-move to      │
│                                   in_progress)                               │
│ --model                   <str>   Retired for claims: the correlated Op      │
│                                   record carries no model identifier         │
│                                   (#7013), so --model is refused; omit it    │
│                                   and the claim records the model as         │
│                                   explicitly absent                          │
│ --profile                 <str>   Agent profile id — a dispatch registry /   │
│                                   Op record profile or a local charter       │
│                                   profile (the same ids `agent profile show` │
│                                   resolves). When omitted, the work          │
│                                   package's frontmatter agent_profile is     │
│                                   used.                                      │
│ --invocation-id           <str>   Correlated Op record ULID whose mission,   │
│                                   WP, action and profile are authoritative   │
│                                   (the record carries no model, #7013)       │
│ --owned-checkout          <path>  Not yet supported. Refused: owned          │
│                                   checkouts use 'spec-kitty next             │
│                                   --owned-checkout' and 'spec-kitty agent    │
│                                   tasks move-task --owned-checkout' instead. │
│ --help            -h              Show this message and exit.                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent config

_Manage project AI agent configuration (add, remove, list agents)_

```
 Usage: spec-kitty agent config [OPTIONS] COMMAND [ARGS]...

 Manage project AI agent configuration (add, remove, list agents)

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ list    List configured agents and their status.                             │
│ add     Add agents to the project.                                           │
│ remove  Remove agents from the project.                                      │
│ status  Show which agents are configured vs present on filesystem.           │
│ sync    Sync filesystem with config.yaml.                                    │
│ set     Set a project-level agent configuration value.                       │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent config add

```
 Usage: spec-kitty agent config add [OPTIONS] {agents}...

 Add agents to the project.

 Creates agent directories and updates config.yaml.

 Example:
     spec-kitty agent config add claude codex

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    agents      <str>  Agent keys to add (e.g., claude codex) [required]    │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent config list

```
 Usage: spec-kitty agent config list [OPTIONS]

 List configured agents and their status.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent config remove

```
 Usage: spec-kitty agent config remove [OPTIONS] {agents}...

 Remove agents from the project.

 Deletes agent directories and updates config.yaml.

 Example:
     spec-kitty agent config remove codex gemini

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    agents      <str>  Agent keys to remove [required]                      │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --keep-config            Keep in config.yaml but delete directory            │
│ --help         -h        Show this message and exit.                         │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent config set

```
 Usage: spec-kitty agent config set [OPTIONS] {key} {value}

 Set a project-level agent configuration value.

 Currently supported keys:
     auto_commit  - Enable/disable automatic commits by agents (true/false)
     lint_on_edit - Enable/disable auto-linting feedback loop (true/false)

 Examples:
     spec-kitty agent config set auto_commit false
     spec-kitty agent config set lint_on_edit true

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    key        <str>  Configuration key (e.g., auto_commit) [required]      │
│ *    value      <str>  Configuration value (e.g., true, false) [required]    │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent config status

```
 Usage: spec-kitty agent config status [OPTIONS]

 Show which agents are configured vs present on filesystem.

 Identifies:
 - Configured and present (✓)
 - Configured but missing (⚠)
 - Not configured but present (orphaned) (✗)

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent config sync

```
 Usage: spec-kitty agent config sync [OPTIONS]

 Sync filesystem with config.yaml.

 By default, removes orphaned directories (present but not configured).
 Use --create-missing to also create directories for configured agents.
 Use --sync-hooks to update harness-specific post-edit hooks.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --create-missing                            Create directories for           │
│                                             configured agents that are       │
│                                             missing                          │
│ --remove-orphaned      --keep-orphaned      Remove directories for agents    │
│                                             not in config                    │
│                                             [default: remove-orphaned]       │
│ --sync-hooks                                Update AI harness hook           │
│                                             configurations (Claude, Cursor,  │
│                                             etc.)                            │
│ --json                                      Emit a JSON summary listing      │
│                                             every tracked-manifest mutation  │
│                                             (#2691).                         │
│ --help             -h                       Show this message and exit.      │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent context

_Agent context management commands_

```
 Usage: spec-kitty agent context [OPTIONS] COMMAND [ARGS]...

 Agent context management commands

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ resolve  Resolve canonical feature/work-package/action context for prompt    │
│          execution.                                                          │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent context resolve

```
 Usage: spec-kitty agent context resolve [OPTIONS]

 Resolve canonical feature/work-package/action context for prompt execution.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --action                  <str>   Action to resolve context for (specify, │
│                                      plan, analyze, tasks, tasks_outline,    │
│                                      tasks_packages, tasks_finalize,         │
│                                      implement, review, accept, status)      │
│                                      [required]                              │
│    --mission                 <str>   Mission slug (e.g., '020-my-mission')   │
│    --wp-id                   <str>   Work package ID (e.g., WP01)            │
│    --agent                   <str>   Agent name for exact command rendering  │
│    --json                            Output results as JSON                  │
│    --owned-checkout          <path>  Run against an owned checkout: a linked │
│                                      checkout that owns this mission.        │
│                                      Refuses the repository root checkout,   │
│                                      lane worktrees and coordination         │
│                                      worktrees.                              │
│    --help            -h              Show this message and exit.             │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent decision

_Decision Moment ledger for interview questions._

```
 Usage: spec-kitty agent decision [OPTIONS] COMMAND [ARGS]...

 Decision Moment ledger for interview questions.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ open                 Open a new Decision Moment or return idempotently if    │
│                      one already exists.                                     │
│ resolve              Resolve a decision with a concrete final answer.        │
│ defer                Defer a decision for later resolution.                  │
│ cancel               Cancel a decision (deemed no longer relevant).          │
│ verify               Cross-check deferred decisions against inline sentinel  │
│                      markers.                                                │
│ list                 List the mission's recorded decision moments            │
│                      (read-only).                                            │
│ repair-runtime-lock  Stop tracking the exact decision lock in an explicitly  │
│                      owned mission.                                          │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent decision cancel

```
 Usage: spec-kitty agent decision cancel [OPTIONS] {decision_id}

 Cancel a decision (deemed no longer relevant).

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    decision_id      <str>  ULID identifier of the decision to cancel       │
│                              [required]                                      │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission                          <str>   Mission handle [required]      │
│ *  --rationale                        <str>   Explanation of why it's being  │
│                                               canceled (required)            │
│                                               [required]                     │
│    --resolved-by                      <str>   Identity of canceling party    │
│    --actor                            <str>   Identity of the acting agent   │
│                                               [default: cli]                 │
│    --dry-run                                  Validate without writing       │
│    --json                --no-json            Output JSON (default true)     │
│                                               [default: json]                │
│    --owned-checkout                   <path>  Run against an owned checkout: │
│                                               a linked checkout that owns    │
│                                               this mission. Refuses the      │
│                                               repository root checkout, lane │
│                                               worktrees and coordination     │
│                                               worktrees.                     │
│    --help            -h                       Show this message and exit.    │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent decision defer

```
 Usage: spec-kitty agent decision defer [OPTIONS] {decision_id}

 Defer a decision for later resolution.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    decision_id      <str>  ULID identifier of the decision to defer        │
│                              [required]                                      │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission                          <str>   Mission handle [required]      │
│ *  --rationale                        <str>   Explanation of why it's being  │
│                                               deferred (required)            │
│                                               [required]                     │
│    --resolved-by                      <str>   Identity of deferring party    │
│    --actor                            <str>   Identity of the acting agent   │
│                                               [default: cli]                 │
│    --dry-run                                  Validate without writing       │
│    --json                --no-json            Output JSON (default true)     │
│                                               [default: json]                │
│    --owned-checkout                   <path>  Run against an owned checkout: │
│                                               a linked checkout that owns    │
│                                               this mission. Refuses the      │
│                                               repository root checkout, lane │
│                                               worktrees and coordination     │
│                                               worktrees.                     │
│    --help            -h                       Show this message and exit.    │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent decision list

```
 Usage: spec-kitty agent decision list [OPTIONS]

 List the mission's recorded decision moments (read-only).

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission                          <str>   Mission handle (slug,          │
│                                               mission_id, or mid8)           │
│                                               [required]                     │
│    --status                           <str>   Only list decisions in this    │
│                                               status: open | resolved |      │
│                                               deferred | canceled            │
│    --json                --no-json            Output JSON (default true)     │
│                                               [default: json]                │
│    --owned-checkout                   <path>  Run against an owned checkout: │
│                                               a linked checkout that owns    │
│                                               this mission. Refuses the      │
│                                               repository root checkout, lane │
│                                               worktrees and coordination     │
│                                               worktrees.                     │
│    --help            -h                       Show this message and exit.    │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent decision open

```
 Usage: spec-kitty agent decision open [OPTIONS]

 Open a new Decision Moment or return idempotently if one already exists.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission                          <str>   Mission handle (slug,          │
│                                               mission_id, or mid8)           │
│                                               [required]                     │
│ *  --flow                             <str>   Origin flow: charter | specify │
│                                               | plan                         │
│                                               [required]                     │
│ *  --input-key                        <str>   The input key this decision    │
│                                               governs                        │
│                                               [required]                     │
│ *  --question                         <str>   Human-readable question text   │
│                                               [required]                     │
│    --step-id                          <str>   Interview step identifier      │
│    --slot-key                         <str>   Slot key (use when step_id     │
│                                               unavailable)                   │
│    --options                          <str>   Candidate answers as a JSON    │
│                                               array string                   │
│    --actor                            <str>   Identity of the opening actor  │
│                                               [default: cli]                 │
│    --dry-run                                  Validate without writing       │
│    --json                --no-json            Output JSON (default true)     │
│                                               [default: json]                │
│    --owned-checkout                   <path>  Run against an owned checkout: │
│                                               a linked checkout that owns    │
│                                               this mission. Refuses the      │
│                                               repository root checkout, lane │
│                                               worktrees and coordination     │
│                                               worktrees.                     │
│    --help            -h                       Show this message and exit.    │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent decision repair-runtime-lock

```
 Usage: spec-kitty agent decision repair-runtime-lock [OPTIONS]

 Stop tracking the exact decision lock in an explicitly owned mission.

 Also adds the exact ignore rule to the Mission's decisions/.gitignore when
 the lock is untracked but not ignored.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission                 <str>   Mission whose decision runtime lock     │
│                                      needs repair                            │
│                                      [required]                              │
│    --owned-checkout          <path>  Run against an owned checkout: a linked │
│                                      checkout that owns this mission.        │
│                                      Refuses the repository root checkout,   │
│                                      lane worktrees and coordination         │
│                                      worktrees.                              │
│    --dry-run                         Validate and inspect without acquiring  │
│                                      the lock or writing                     │
│    --help            -h              Show this message and exit.             │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent decision resolve

```
 Usage: spec-kitty agent decision resolve [OPTIONS] {decision_id}

 Resolve a decision with a concrete final answer.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    decision_id      <str>  ULID identifier of the decision to resolve      │
│                              [required]                                      │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission                          <str>   Mission handle [required]      │
│ *  --final-answer                     <str>   The chosen answer (non-empty)  │
│                                               [required]                     │
│    --other-answer                             True if answer is a write-in   │
│    --rationale                        <str>   Explanation of the choice      │
│    --resolved-by                      <str>   Identity of resolver           │
│    --actor                            <str>   Identity of the acting agent   │
│                                               [default: cli]                 │
│    --dry-run                                  Validate without writing       │
│    --json                --no-json            Output JSON (default true)     │
│                                               [default: json]                │
│    --owned-checkout                   <path>  Run against an owned checkout: │
│                                               a linked checkout that owns    │
│                                               this mission. Refuses the      │
│                                               repository root checkout, lane │
│                                               worktrees and coordination     │
│                                               worktrees.                     │
│    --help            -h                       Show this message and exit.    │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent decision verify

```
 Usage: spec-kitty agent decision verify [OPTIONS]

 Cross-check deferred decisions against inline sentinel markers.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission                                   <str>   Mission handle        │
│                                                        [required]            │
│    --fail-on-stale       --no-fail-on-stale            Exit non-zero when    │
│                                                        findings are present  │
│                                                        (default true)        │
│                                                        [default:             │
│                                                        fail-on-stale]        │
│    --json                --no-json                     Output JSON (default  │
│                                                        true)                 │
│                                                        [default: json]       │
│    --owned-checkout                            <path>  Run against an owned  │
│                                                        checkout: a linked    │
│                                                        checkout that owns    │
│                                                        this mission. Refuses │
│                                                        the repository root   │
│                                                        checkout, lane        │
│                                                        worktrees and         │
│                                                        coordination          │
│                                                        worktrees.            │
│    --help            -h                                Show this message and │
│                                                        exit.                 │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent issue-verdict

```
 Usage: spec-kitty agent issue-verdict [OPTIONS]

 Set an issue-matrix row's verdict, routed via ``write_target(ISSUE_MATRIX)``.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission                 <str>   Mission handle (slug, mission_id, or    │
│                                      mid8).                                  │
│                                      [required]                              │
│ *  --issue                   <str>   Issue reference, e.g. "#1726".          │
│                                      [required]                              │
│ *  --verdict                 <str>   fixed | verified-already-fixed |        │
│                                      deferred-with-followup | in-mission |   │
│                                      not-applicable (non-gating: cited for   │
│                                      context or a PR/commit reference, no    │
│                                      work owed; unlike in-mission it is      │
│                                      terminal -- it also passes the          │
│                                      done/merge completeness gate unchanged) │
│                                      [required]                              │
│ *  --actor                   <str>   Identity of the acting agent.           │
│                                      [required]                              │
│    --wp                      <str>   Owning work-package id (e.g. WP01).     │
│    --evidence-ref            <str>   Evidence text or link for the verdict.  │
│                                      Required when --verdict is              │
│                                      deferred-with-followup: the value must  │
│                                      contain a follow-up handle ('#NNN' or a │
│                                      'Follow-up:' substring), or the row     │
│                                      fails validation.                       │
│    --title                   <str>   Issue title to stamp on the matrix row  │
│                                      (replaces a scaffold placeholder).      │
│    --owned-checkout          <path>  Run against an owned checkout: a linked │
│                                      checkout that owns this mission.        │
│                                      Refuses the repository root checkout,   │
│                                      lane worktrees and coordination         │
│                                      worktrees.                              │
│    --json                            Output JSON format.                     │
│    --help            -h              Show this message and exit.             │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent mission

_Mission lifecycle commands for AI agents_

```
 Usage: spec-kitty agent mission [OPTIONS] COMMAND [ARGS]...

 Mission lifecycle commands for AI agents

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ record-analysis      Persist `/spec-kitty.analyze` output as                 │
│                      `analysis-report.md`.                                   │
│ acceptance-verdict   Record an acceptance-criterion verdict, or              │
│                      register/execute a negative                             │
│                      invariant (FR-007/FR-008) — exactly one of              │
│                      ``--criterion``/                                        │
│                      ``--negative-invariant``, both routed through the WP03  │
│                      write seam.                                             │
│ branch-context       Return deterministic branch contract for planning-stage │
│                      prompts.                                                │
│ create               Create new mission directory structure in the project   │
│                      root checkout.                                          │
│ check-prerequisites  Validate mission structure and prerequisites.           │
│ setup-plan           Scaffold an implementation plan template in the         │
│                      repository root checkout or an owned checkout.          │
│ accept               Perform mission acceptance workflow.                    │
│ merge                Merge mission branch into target branch.                │
│ finalize-tasks       Parse dependencies from tasks.md and update WP          │
│                      frontmatter, then commit to target branch.              │
│ repair               Detect and forward-only repair a pre-existing           │
│                      cross-partition content                                 │
│                      split-brain for one mission (FR-005, NFR-005).          │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent mission accept

```
 Usage: spec-kitty agent mission accept [OPTIONS]

 Perform mission acceptance workflow.

 This command:
 1. Validates all tasks are in 'done' lane
 2. Runs acceptance checks from checklist files
 3. Creates acceptance report
 4. Marks mission as ready for merge

 Wrapper for top-level accept command with agent-specific defaults.

 Examples:
     # Run acceptance workflow
     spec-kitty agent mission accept --mission 077-my-mission

     # With JSON output for agents
     spec-kitty agent mission accept --mission 077-my-mission --json

     # Lenient mode (skip strict validation)
     spec-kitty agent mission accept --mission 077-my-mission --lenient --json

     # Waive only the path-convention check for this run (metadata stays
 strict)
     spec-kitty agent mission accept --mission 077-my-mission
 --waive-path-conventions --waive-reason "layout migration" --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission                              <str>   Mission slug (required in     │
│                                                multi-mission repos)          │
│ --mode                                 <str>   Acceptance mode: auto, pr,    │
│                                                local, checklist              │
│                                                [default: auto]               │
│ --json                                         Output results as JSON for    │
│                                                agent parsing                 │
│ --lenient                                      Skip strict metadata          │
│                                                validation                    │
│ --no-commit                                    Skip auto-commit (report      │
│                                                only)                         │
│ --diagnose                                     Diagnose acceptance blockers  │
│                                                without mutation              │
│ --merge-commit                         SHA     With --mode pr: record this   │
│                                                PR merge commit as the        │
│                                                mission's post-merge review   │
│                                                baseline (#4231).             │
│ --target-branch                        <str>   With --merge-commit: the      │
│                                                branch the PR merged into.    │
│                                                Defaults to the mission's     │
│                                                declared target_branch, else  │
│                                                the repository's primary      │
│                                                branch.                       │
│ --attest-first-landing-commit                  With --merge-commit: attest   │
│                                                the supplied commit's first   │
│                                                parent is the pre-landing     │
│                                                target tip (#4231). Required  │
│                                                for every landing shape.      │
│ --owned-checkout                       <path>  Run against an owned          │
│                                                checkout: a linked checkout   │
│                                                that owns this mission.       │
│                                                Refuses the repository root   │
│                                                checkout, lane worktrees and  │
│                                                coordination worktrees.       │
│ --waive-path-conventions                       Path-convention misses are    │
│                                                warnings for this run;        │
│                                                metadata validation stays     │
│                                                strict (#7566). Requires      │
│                                                --waive-reason.               │
│ --waive-reason                         <str>   Why path conventions are      │
│                                                waived for this run (required │
│                                                with                          │
│                                                --waive-path-conventions).    │
│ --help                         -h              Show this message and exit.   │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent mission acceptance-verdict

```
 Usage: spec-kitty agent mission acceptance-verdict [OPTIONS]

 Record an acceptance-criterion verdict, or register/execute a negative
 invariant (FR-007/FR-008) — exactly one of ``--criterion``/
 ``--negative-invariant``, both routed through the WP03 write seam.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission                                  <str>   Mission slug, mid8, or │
│                                                       mission_id             │
│                                                       [required]             │
│    --criterion                                <str>   Acceptance criterion   │
│                                                       id (e.g. FR-001);      │
│                                                       mutually exclusive     │
│                                                       with                   │
│                                                       --negative-invariant   │
│    --result                                   <str>   pass | fail | pending  │
│                                                       | deferred (required   │
│                                                       with --criterion)      │
│    --verification-method                      <str>   Criterion mode: how    │
│                                                       this was verified      │
│                                                       (updates proof_type).  │
│                                                       Negative-invariant     │
│                                                       mode: grep_absence |   │
│                                                       route_check |          │
│                                                       custom_command         │
│                                                       (required with         │
│                                                       --negative-invariant). │
│    --actor                                    <str>   Actor recording this   │
│                                                       verdict                │
│    --evidence                                 <str>   Evidence reference     │
│                                                       (URL/path/etc.)        │
│    --negative-invariant                       <str>   Negative invariant id  │
│                                                       to register/execute    │
│                                                       (FR-007/FR-008);       │
│                                                       mutually exclusive     │
│                                                       with --criterion       │
│    --description                              <str>   Negative invariant     │
│                                                       description (required  │
│                                                       with                   │
│                                                       --negative-invariant); │
│                                                       criterion mode:        │
│                                                       replaces the criterion │
│                                                       description            │
│    --notes                                    <str>   Criterion mode:        │
│                                                       replaces the criterion │
│                                                       notes                  │
│    --reason                                   <str>   Why the criterion is   │
│                                                       deferred (required     │
│                                                       with --result          │
│                                                       deferred)              │
│    --follow-up                                <str>   Follow-up reference:   │
│                                                       issue number/URL or    │
│                                                       ruling id (required    │
│                                                       with --result          │
│                                                       deferred)              │
│    --verification-comma…                      <str>   grep pattern or        │
│                                                       command verifying the  │
│                                                       invariant's absence    │
│    --scope                                    <str>   Whitespace-separated   │
│                                                       repo-relative search   │
│                                                       root(s); grep_absence  │
│                                                       only                   │
│    --execute                  --no-execute            Run the invariant's    │
│                                                       verification           │
│                                                       immediately after      │
│                                                       registering (FR-008;   │
│                                                       default: on)           │
│                                                       [default: execute]     │
│    --owned-checkout                           <path>  Run against an owned   │
│                                                       checkout: a linked     │
│                                                       checkout that owns     │
│                                                       this mission. Refuses  │
│                                                       the repository root    │
│                                                       checkout, lane         │
│                                                       worktrees and          │
│                                                       coordination           │
│                                                       worktrees.             │
│    --json                                             Output JSON format     │
│    --help                 -h                          Show this message and  │
│                                                       exit.                  │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent mission branch-context

```
 Usage: spec-kitty agent mission branch-context [OPTIONS]

 Return deterministic branch contract for planning-stage prompts.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json                          Output JSON format                           │
│ --target-branch          <str>  Planned landing branch (defaults to current  │
│                                 branch)                                      │
│ --help           -h             Show this message and exit.                  │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent mission check-prerequisites

```
 Usage: spec-kitty agent mission check-prerequisites [OPTIONS]

 Validate mission structure and prerequisites.

 This command is designed for AI agents to call programmatically.

 Examples:
     spec-kitty agent mission check-prerequisites --json
     spec-kitty agent mission check-prerequisites --mission 020-my-feature
 --paths-only --json
     spec-kitty agent mission check-prerequisites --mission my-feature
 --resume-probe --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission                 <str>   Mission slug (e.g., '020-my-mission')      │
│ --json                            Output JSON format                         │
│ --paths-only                      Only output path variables                 │
│ --resume-probe                    Return structured                          │
│                                   found/not_found/existing/ambiguous/malfor… │
│                                   state for safe specify resume              │
│ --include-tasks                   Include tasks.md in validation             │
│ --owned-checkout          <path>  Run against an owned checkout: a linked    │
│                                   checkout that owns this mission. Refuses   │
│                                   the repository root checkout, lane         │
│                                   worktrees and coordination worktrees.      │
│ --help            -h              Show this message and exit.                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent mission create

```
 Usage: spec-kitty agent mission create [OPTIONS] {mission_slug}

 Create new mission directory structure in the project root checkout.

 This command is designed for AI agents to call programmatically.
 Creates mission directory in kitty-specs/ and commits to the current branch.

 Examples:
     spec-kitty agent mission create "new-dashboard" --json

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    mission_slug      <str>  Mission slug (e.g., 'user-auth') [required]    │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission-type                            <str>            Mission type      │
│                                                            (e.g.,            │
│                                                            'documentation',  │
│                                                            'software-dev')   │
│ --json                                                     Output JSON       │
│                                                            format            │
│ --target-branch                           <str>            Target branch     │
│                                                            (defaults to the  │
│                                                            current branch;   │
│                                                            without           │
│                                                            --topology, a     │
│                                                            current branch    │
│                                                            that is another   │
│                                                            Mission's branch  │
│                                                            is replaced by    │
│                                                            the Primary       │
│                                                            Branch, and the   │
│                                                            create says so)   │
│ --friendly-name                           <str>            Human-friendly    │
│                                                            mission title     │
│ --purpose-tldr                            <str>            One-line          │
│                                                            stakeholder TLDR  │
│                                                            for the mission   │
│ --purpose-conte…                          <str>            Short             │
│                                                            stakeholder-faci… │
│                                                            paragraph for the │
│                                                            mission           │
│ --pr-bound            --no-pr-bound                        Mark mission as   │
│                                                            PR-bound (gate    │
│                                                            fires on          │
│                                                            merge_target_bra… │
│                                                            [default:         │
│                                                            no-pr-bound]      │
│ --topology                                <single_branch|  Mission shape:    │
│                                           lanes|coord|lan  single_branch |   │
│                                           es_with_coord>   lanes | coord |   │
│                                                            lanes_with_coord. │
│                                                            Default (no       │
│                                                            --topology):      │
│                                                            create mints one  │
│                                                            Mission topic     │
│                                                            branch            │
│                                                            (kitty/mission-<… │
│                                                            and checks it     │
│                                                            out, on any       │
│                                                            target, with no   │
│                                                            lanes, worktrees  │
│                                                            or coordination   │
│                                                            branch; the first │
│                                                            finalize-tasks    │
│                                                            then settles the  │
│                                                            shape by size:    │
│                                                            single_branch for │
│                                                            at most 2 work    │
│                                                            packages or at    │
│                                                            most 1 code lane, │
│                                                            else              │
│                                                            lanes_with_coord  │
│                                                            with the topic    │
│                                                            branch as the     │
│                                                            coordination      │
│                                                            branch. lanes and │
│                                                            coord are         │
│                                                            produced only by  │
│                                                            an explicit       │
│                                                            --topology. An    │
│                                                            explicit value    │
│                                                            always wins and   │
│                                                            is settled at     │
│                                                            create            │
│                                                            (--owned-checkout │
│                                                            implies           │
│                                                            single_branch).   │
│ --branch-strate…                          <str>            Branch-strategy   │
│                                                            gate control      │
│                                                            (e.g.,            │
│                                                            'already-confirm… │
│                                                            to bypass the     │
│                                                            prompt)           │
│ --start-branch                            <str>            Create or switch  │
│                                                            to this branch    │
│                                                            before mission    │
│                                                            files are written │
│ --force-recreat…                                           Delete and        │
│                                                            recreate the      │
│                                                            per-mission       │
│                                                            coordination      │
│                                                            branch if it      │
│                                                            already exists    │
│                                                            and has diverged  │
│                                                            from the target.  │
│                                                            Operator escape   │
│                                                            hatch; never used │
│                                                            by automation.    │
│ --owned-checkout                          <path>           Run against an    │
│                                                            owned checkout: a │
│                                                            linked checkout   │
│                                                            that owns this    │
│                                                            mission. Refuses  │
│                                                            the repository    │
│                                                            root checkout,    │
│                                                            lane worktrees    │
│                                                            and coordination  │
│                                                            worktrees.        │
│ --retain-branch…                                           Opt this          │
│                                                            mission's         │
│                                                            branches out of   │
│                                                            post-merge        │
│                                                            cleanup deletion. │
│ --retain-worktr…                                           Opt this          │
│                                                            mission's         │
│                                                            worktrees out of  │
│                                                            post-merge        │
│                                                            cleanup deletion. │
│ --commit-to-tar…      --no-commit-to-…                     single_branch     │
│                                                            only: skip the    │
│                                                            protected-target  │
│                                                            mission-branch    │
│                                                            mint (#5100       │
│                                                            FR-008) and       │
│                                                            commit directly   │
│                                                            onto              │
│                                                            --target-branch,  │
│                                                            even when it is   │
│                                                            protected.        │
│                                                            Persisted;        │
│                                                            honoured through  │
│                                                            ProtectionPolicy  │
│                                                            for every later   │
│                                                            write.            │
│                                                            [default:         │
│                                                            no-commit-to-tar… │
│ --allow-duplica…                                           Escape hatch for  │
│                                                            the idempotency   │
│                                                            guard (#4033):    │
│                                                            create a second   │
│                                                            mission even      │
│                                                            though a LIVE     │
│                                                            prior mission     │
│                                                            shares this slug  │
│                                                            and mission type. │
│                                                            Abandoned priors  │
│                                                            (canceled,        │
│                                                            genesis, or spec  │
│                                                            never committed)  │
│                                                            never need this   │
│                                                            flag.             │
│ --help            -h                                       Show this message │
│                                                            and exit.         │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent mission finalize-tasks

```
 Usage: spec-kitty agent mission finalize-tasks [OPTIONS]

 Parse dependencies from tasks.md and update WP frontmatter, then commit to
 target branch.

 This command is designed to be called after LLM generates WP files via
 /spec-kitty.tasks.
 It post-processes the generated files to add dependency information and
 commits everything.

 Use --validate-only to check for issues (missing requirement mappings,
 ownership overlaps,
 dependency cycles) without making any changes or committing.

 Use --refresh-planning-commit once execution has begun and a legitimate
 planning
 amendment has landed on the target branch: it advances the recorded
 planning_commit_sha in lanes.json to the current tip so lanes merge the
 amended
 planning state instead of a stale snapshot (#4141). It is refused when the
 recorded
 SHA is not an ancestor of the tip (a history rewrite, not an amendment) --
 unless
 that non-ancestor SHA is a proven ORPHAN (present, just unreachable -- a
 mid-mission
 rebase), in which case add --allow-orphaned to re-point to the live tip
 (#4827).

 Bootstrap Mutation Surface (FR-003 / SC-002)
 =============================================
 The 8 frontmatter fields below may be written or overwritten by this command.
 When ``--validate-only`` is active, ALL writes are skipped — the
 ``frontmatter_changed and not validate_only`` guard ensures zero bytes of
 mutation on disk (INV-6). In validate-only mode the bootstrap loop still
 infers all 8 fields in memory so downstream validation operates against the
 post-bootstrap state — not the stale on-disk frontmatter. The T017 tasks.md
 regeneration is likewise skipped (its staleness relative to wps.yaml is
 reported instead of repaired — #3221), so INV-6 covers every tracked-file
 write the command performs.

 See also: ``tasks.py:finalize-tasks()`` which writes ``dependencies`` via
 ``build_document() + write_text()`` — guarded the same way (T002).

 Examples:
     spec-kitty agent mission finalize-tasks --mission 020-my-feature --json
     spec-kitty agent mission finalize-tasks --mission 020-my-feature
 --validate-only --json
     spec-kitty agent mission finalize-tasks --mission 020-my-feature
 --refresh-planning-commit
     spec-kitty agent mission finalize-tasks --mission 020-my-feature
 --refresh-planning-commit --allow-orphaned

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission                          <str>   Mission slug (e.g.,               │
│                                            '020-my-mission')                 │
│ --json                                     Output JSON format                │
│ --validate-only                            Run all validations without       │
│                                            committing. Reports issues that   │
│                                            would block finalization.         │
│ --target-branch                    <str>   Override the canonical planning   │
│                                            target branch read from           │
│                                            meta.json. Use this for legacy    │
│                                            missions created before WP07      │
│                                            persisted target_branch in        │
│                                            meta.json, or to correct a        │
│                                            mission whose target_branch is    │
│                                            stale (FR-012 escape hatch). The  │
│                                            override is persisted into the    │
│                                            primary meta.json as part of this │
│                                            run, so every other target_branch │
│                                            consumer converges on it too      │
│                                            (#3466).                          │
│ --owned-checkout                   <path>  Explicit owned checkout for a     │
│                                            single-branch mission.            │
│ --refresh-planning-commit                  Force a refresh-ONLY run:         │
│                                            re-point the recorded             │
│                                            planning_commit_sha in lanes.json │
│                                            to the current target-branch tip  │
│                                            and exit, without running the     │
│                                            rest of finalize-tasks (#4141).   │
│                                            By default (no flag needed) a     │
│                                            normal re-finalize already        │
│                                            advances the pin automatically    │
│                                            whenever a PRIMARY planning file  │
│                                            genuinely changed since it was    │
│                                            recorded (FR-012); use this flag  │
│                                            only to force JUST the pin        │
│                                            refresh for an ADVANCED pin (the  │
│                                            common case) or to re-point a     │
│                                            deliberate mid-mission rebase     │
│                                            with --allow-orphaned (#4827). It │
│                                            is advance-only and REFUSES when  │
│                                            the recorded SHA is not an        │
│                                            ancestor of the tip without       │
│                                            --allow-orphaned, and it CANNOT   │
│                                            help a pin the automatic path     │
│                                            already warned about and kept     │
│                                            unchanged (a FOREIGN object       │
│                                            absent from this repository       │
│                                            entirely, or an INDETERMINATE pin │
│                                            whose target tip could not even   │
│                                            be resolved) -- WP15 cycle 2/3:   │
│                                            neither shape is inspectable, so  │
│                                            --refresh-planning-commit         │
│                                            --allow-orphaned refuses both the │
│                                            same as a bare                    │
│                                            --refresh-planning-commit would;  │
│                                            correct lanes.json's              │
│                                            planning_commit_sha by hand       │
│                                            instead, per that warning's own   │
│                                            text.                             │
│ --allow-orphaned                           Only meaningful with              │
│                                            --refresh-planning-commit         │
│                                            (#4827). Permits the re-pin to    │
│                                            re-point a recorded               │
│                                            planning_commit_sha that is       │
│                                            ORPHANED -- present in the        │
│                                            repository but no longer an       │
│                                            ancestor of the target-branch     │
│                                            tip, the mid-mission-rebase       │
│                                            shape. Without it, an orphaned    │
│                                            pin is refused (a bare            │
│                                            --refresh-planning-commit stays   │
│                                            advance-only; a plain finalize    │
│                                            fails closed before writing       │
│                                            lanes.json). Still refused        │
│                                            regardless for a FOREIGN (absent) │
│                                            object -- investigate that        │
│                                            divergence manually.              │
│ --help                     -h              Show this message and exit.       │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent mission merge

```
 Usage: spec-kitty agent mission merge [OPTIONS]

 Merge mission branch into target branch.

 This command:
 1. Validates the mission is accepted
 2. Merges the mission branch into target (usually 'main')
 3. Cleans up worktree
 4. Deletes the mission branch

 Auto-retry logic:
 If current branch doesn't match feature pattern and auto-retry is enabled,
 it retries only when --mission is provided so worktree selection is
 deterministic.

 Delegates to existing tasks_cli.py merge implementation.

 Examples:
     # Merge into main branch
     spec-kitty agent mission merge --mission 077-my-mission

     # Merge into specific branch with push
     spec-kitty agent mission merge --mission 077-my-mission --target develop
 --push

     # Dry-run mode
     spec-kitty agent mission merge --mission 077-my-mission --dry-run

     # Keep worktree and branch after merge
     spec-kitty agent mission merge --mission 077-my-mission --keep-worktree
 --keep-branch

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission                                 <str>  Mission slug (required in   │
│                                                  multi-mission repos)        │
│ --target                                  <str>  Target branch for the       │
│                                                  branch-integration step     │
│                                                  (required in multi-mission  │
│                                                  repos)                      │
│ --strategy                                <str>  Strategy for the            │
│                                                  branch-integration step:    │
│                                                  merge, squash, rebase       │
│                                                  [default: merge]            │
│ --push                                           Publish to origin after the │
│                                                  local merge (the operator   │
│                                                  publish step)               │
│ --dry-run                                        Show actions without        │
│                                                  executing                   │
│ --keep-branch        --delete-branch             Keep or delete mission      │
│                                                  branch after merge          │
│                                                  (default: retain-gate       │
│                                                  choice)                     │
│ --keep-worktree      --remove-worktree           Keep or remove worktree     │
│                                                  after merge (default:       │
│                                                  retain-gate choice)         │
│ --auto-retry         --no-auto-retry             Auto-navigate to a          │
│                                                  deterministic mission       │
│                                                  worktree if in the wrong    │
│                                                  location                    │
│                                                  [default: no-auto-retry]    │
│ --help           -h                              Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent mission record-analysis

```
 Usage: spec-kitty agent mission record-analysis [OPTIONS]

 Persist `/spec-kitty.analyze` output as `analysis-report.md`.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission                 <str>   Mission slug (e.g., '020-my-mission')      │
│ --input-file              <str>   Markdown report path, or '-' to read       │
│                                   report from stdin                          │
│                                   [default: -]                               │
│ --agent                   <str>   Agent name that produced the analysis      │
│                                   report                                     │
│ --json                            Output JSON format                         │
│ --report-only                     Commit only the report while preserving    │
│                                   unrelated work; require clean material     │
│                                   inputs                                     │
│ --owned-checkout          <path>  Run against an owned checkout: a linked    │
│                                   checkout that owns this mission. Refuses   │
│                                   the repository root checkout, lane         │
│                                   worktrees and coordination worktrees.      │
│ --help            -h              Show this message and exit.                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent mission repair

```
 Usage: spec-kitty agent mission repair [OPTIONS]

 Detect and forward-only repair a pre-existing cross-partition content
 split-brain for one mission (FR-005, NFR-005).

 Fast-forwards under strict-ancestor + clean worktree, zero data loss.
 Refuses with a unified diff (scoped to the mission's own content) and
 mutates NOTHING on genuine (non-ancestor) divergence.

 Examples:
     spec-kitty agent mission repair --mission 020-my-mission

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission          <str>  Mission slug/handle to repair [required]        │
│    --help     -h             Show this message and exit.                     │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent mission setup-plan

```
 Usage: spec-kitty agent mission setup-plan [OPTIONS]

 Scaffold an implementation plan template in the repository root checkout or an
 owned checkout.

 This command is designed for AI agents to call programmatically.
 Creates plan.md and commits to target branch.

 Examples:
     spec-kitty agent mission setup-plan --json
     spec-kitty agent mission setup-plan --mission 020-my-feature --json

 ------------------------------------------------------------------
 The SaaS-sync boundary gates this command used to enforce (FR-011 auth
 refusal, boundary preflight, dossier push) were removed with the sync
 transport (issue #5); only local planning artifacts are produced here.
 ------------------------------------------------------------------

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission                 <str>   Mission slug (e.g., '020-my-mission')      │
│ --json                            Output JSON format                         │
│ --owned-checkout          <path>  Run against an owned checkout: a linked    │
│                                   checkout that owns this mission. Refuses   │
│                                   the repository root checkout, lane         │
│                                   worktrees and coordination worktrees.      │
│ --help            -h              Show this message and exit.                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent release

_Release packaging commands for AI agents_

```
 Usage: spec-kitty agent release [OPTIONS] COMMAND [ARGS]...

 Release packaging commands for AI agents

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ prep  Prepare release artifacts (changelog draft, version bump, structured   │
│       inputs).                                                               │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent release prep

```
 Usage: spec-kitty agent release prep [OPTIONS]

 Prepare release artifacts (changelog draft, version bump, structured inputs).

 Reads kitty-specs/ artifacts and local git tags. No network calls.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --channel          <alpha|beta|stable>  Release channel: alpha | beta |   │
│                                            stable                            │
│                                            [required]                        │
│    --repo             <path>               Repository root (default: current │
│                                            directory)                        │
│                                            [default: .]                      │
│    --json                                  Emit JSON instead of              │
│                                            human-readable text               │
│    --help     -h                           Show this message and exit.       │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent retrospect

_Retrospective synthesis commands_

```
 Usage: spec-kitty agent retrospect [OPTIONS] COMMAND [ARGS]...

 Retrospective synthesis commands

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ synthesize  Apply staged proposals from a mission's retrospective record.    │
│ summary     Cross-mission retrospective summary.                             │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent retrospect summary

_Cross-mission retrospective summary._

```
 Usage: spec-kitty agent retrospect summary [OPTIONS]

 Cross-mission retrospective summary.

 Back-compat alias: equivalent to `spec-kitty retrospect summary`.

 Distinguishes four record states: has_findings / ran_no_findings / missing /
 failed.

 No mutation is performed.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --project                    <path>                  Project root (default:  │
│                                                      cwd)                    │
│ --json                                               Emit JSON to stdout     │
│ --json-out                   <path>                  Also write JSON to this │
│                                                      file                    │
│ --limit                      <int range>             Top-N for ranked        │
│                              [1<=x<=100]             sections                │
│                                                      [default: 20]           │
│ --since                      <str>                   ISO-8601 date filter    │
│ --include-malformed                                  Include malformed       │
│                                                      record detail           │
│ --filter                     <str>                   Filter by record state  │
│                                                      (has_findings|ran_no_f… │
│ --help               -h                              Show this message and   │
│                                                      exit.                   │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent retrospect synthesize

_Apply staged proposals from a mission's retrospective record._

```
 Usage: spec-kitty agent retrospect synthesize [OPTIONS]

 Apply staged proposals from a mission's retrospective record.

 --dry-run is the default; pass --apply to mutate project state.
 flag_not_helpful is the only auto-applied kind (Q2-A).
 Conflict detection is fail-closed: any conflict blocks the whole batch.

 When no retrospective.yaml exists, the command errors with
 RETROSPECTIVE_RECORD_MISSING (exit 1) and points to 'spec-kitty retrospect
 create'.
 Pass --fabricate-empty to use the legacy auto-fabrication path instead.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission                  <str>   Mission handle (mission_id / mid8 /    │
│                                       mission_slug)                          │
│                                       [required]                             │
│    --apply                            Execute application after checks pass  │
│                                       (default is dry-run)                   │
│    --proposal-id              <str>   Restrict the batch to the given        │
│                                       proposal ids, which must be accepted   │
│                                       (repeatable). Any id that is pending,  │
│                                       rejected or not in the record is       │
│                                       refused (exit 1) before anything is    │
│                                       applied.                               │
│    --json-out                 <path>  Write JSON envelope to PATH in         │
│                                       addition to other output               │
│    --json                             Emit JSON to stdout (suppresses Rich   │
│                                       rendering)                             │
│    --actor-id                 <str>   Override provenance actor id (default: │
│                                       inferred from environment)             │
│    --fabricate-empty                  Legacy: auto-fabricate an empty record │
│                                       when none exists (synthesize_fabricate │
│                                       provenance)                            │
│    --help             -h              Show this message and exit.            │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent status

_Canonical status management commands_

```
 Usage: spec-kitty agent status [OPTIONS] COMMAND [ARGS]...

 Canonical status management commands

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ emit         Emit a status transition event for a work package.              │
│ materialize  Rebuild status.json from the canonical event log.               │
│ doctor       Run health checks for status hygiene and global runtime.        │
│ lifecycle    Show the canonical lifecycle state for one mission.             │
│ migrate      [REMOVED] Frontmatter-to-event-log bootstrap migration has been │
│              removed.                                                        │
│ validate     Validate canonical status model integrity.                      │
│ reconcile    [REMOVED] Cross-repo reconciliation has been removed.           │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent status doctor

```
 Usage: spec-kitty agent status doctor [OPTIONS]

 Run health checks for status hygiene and global runtime.

 Detects global runtime issues (missing runtime directory, version mismatch,
 corrupted missions) and project-level issues (stale claims, orphan
 workspaces, drift).
 Exit code 0 = healthy, 1 = issues found.

 Examples:
     spec-kitty agent status doctor
     spec-kitty agent status doctor --mission 034-my-feature
     spec-kitty agent status doctor --stale-claimed-days 3 --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission                         <str>  Mission slug                        │
│ --stale-claimed-days              <int>  Threshold for stale claims (days)   │
│                                          [default: 7]                        │
│ --stale-in-progress-days          <int>  Threshold for stale in-progress     │
│                                          (days)                              │
│                                          [default: 14]                       │
│ --json                                   Machine-readable JSON output        │
│ --help                    -h             Show this message and exit.         │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent status emit

```
 Usage: spec-kitty agent status emit [OPTIONS] [wp_id]

 Emit a status transition event for a work package.

 Records a lane transition in the canonical event log, validates the
 transition against the state machine, materializes a snapshot, and
 updates legacy compatibility views.

 Examples:
     spec-kitty agent status emit WP01 --to claimed --actor claude
     spec-kitty agent status emit --wp WP01 --to claimed --actor claude
     spec-kitty agent status emit WP01 --to approved --actor claude
 --review-result-json '{"reviewer": "alice", "verdict": "approved",
 "reference": "PR#1"}'
     spec-kitty agent status emit WP01 --to in_progress --actor claude --force
 --reason "resuming after crash"

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│   wp_id      <str>  Work package ID (e.g., WP01)                             │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --to                                 <str>  Target lane (e.g., claimed,   │
│                                                in_progress, for_review,      │
│                                                approved, done)               │
│                                                [required]                    │
│ *  --actor                              <str>  Who is making this transition │
│                                                (a 'migration:'-prefixed      │
│                                                identity is refused:          │
│                                                reconstruction seeds are      │
│                                                written in-process by         │
│                                                migrations only)              │
│                                                [required]                    │
│    --mission                            <str>  Mission slug (required in     │
│                                                multi-mission repos)          │
│    --wp                                 <str>  Work package ID (alternative  │
│                                                to positional ID)             │
│    --force                                     Force transition bypassing    │
│                                                guards                        │
│    --reason                             <str>  Reason for forced transition  │
│                                                (required with --force out of │
│                                                in_review or approved)        │
│    --evidence-json                      <str>  JSON string with done         │
│                                                evidence                      │
│    --review-ref                         <str>  Review feedback reference     │
│    --review-result-json                 <str>  JSON structured review        │
│                                                outcome for transitions from  │
│                                                in_review                     │
│    --workspace-context                  <str>  Workspace context identifier  │
│                                                for claimed->in_progress      │
│    --subtasks-complete                         Whether required subtasks are │
│                                                complete for                  │
│                                                in_progress->for_review       │
│    --implementation-evidence-…                 Whether implementation        │
│                                                evidence exists for           │
│                                                in_progress->for_review       │
│    --execution-mode                     <str>  Execution mode (worktree or   │
│                                                direct_repo)                  │
│                                                [default: worktree]           │
│    --json                                      Machine-readable JSON output  │
│    --help                       -h             Show this message and exit.   │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent status lifecycle

```
 Usage: spec-kitty agent status lifecycle [OPTIONS]

 Show the canonical lifecycle state for one mission.

 This is the product-facing state layer above raw WP lanes. It answers
 whether a mission is active, recently completed, stale, abandoned, or
 now just recoverable/archive history.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission          <str>  Mission slug                                       │
│ --json                    Machine-readable JSON output                       │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent status materialize

```
 Usage: spec-kitty agent status materialize [OPTIONS]

 Rebuild status.json from the canonical event log.

 Reads all events from status.events.jsonl, applies the deterministic
 reducer to produce a snapshot, writes status.json, and updates legacy
 compatibility views.

 status.json is written into the checkout that holds the declared status
 source (the write checkout, the coordination worktree, or for a landed
 Mission the consolidated target). When no checkout holds it (the
 coordination worktree is empty or absent, or no checkout holds the
 Mission branch) the command refuses, writes nothing and names the remedy.

 Examples:
     spec-kitty agent status materialize
     spec-kitty agent status materialize --mission 034-my-feature
     spec-kitty agent status materialize --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission          <str>  Mission slug (required in multi-mission repos)     │
│ --json                    Machine-readable JSON output                       │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent status migrate

```
 Usage: spec-kitty agent status migrate [OPTIONS]

 [REMOVED] Frontmatter-to-event-log bootstrap migration has been removed.

 The canonical status model uses the event log as sole authority.
 One-shot bootstrap migration from frontmatter is handled by the
 upgrade migration system (``spec-kitty upgrade``), not this command.

 Examples:
     spec-kitty upgrade  # applies all pending migrations

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission          <str>  Single mission slug to migrate                     │
│ --all                     Migrate all features in kitty-specs/               │
│ --dry-run                 Preview migration without writing events           │
│ --json                    Output results as JSON                             │
│ --actor            <str>  Actor name for bootstrap events                    │
│                           [default: migration]                               │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent status reconcile

```
 Usage: spec-kitty agent status reconcile [OPTIONS]

 [REMOVED] Cross-repo reconciliation has been removed.

 The canonical status model uses the event log as sole authority.
 Cross-repo drift detection via frontmatter scanning is no longer
 supported. Use ``spec-kitty agent status validate`` to check
 event log integrity.

 Examples:
     spec-kitty agent status validate --mission 034-feature-name

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission                     <str>   Mission slug (required in              │
│                                       multi-mission repos)                   │
│ --dry-run          --apply            Preview vs persist reconciliation      │
│                                       events                                 │
│                                       [default: dry-run]                     │
│ --target-repo  -t             <path>  Target repo path(s) to scan            │
│ --json                                Machine-readable JSON output           │
│ --help         -h                     Show this message and exit.            │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent status validate

```
 Usage: spec-kitty agent status validate [OPTIONS]

 Validate canonical status model integrity.

 Runs all validation checks: event schema, transition legality,
 done-evidence completeness, materialization drift, and derived-view drift.

 Exit code 0 for pass (no errors), exit code 1 for fail (any errors).
 Warnings do not cause failure.

 Examples:
     spec-kitty agent status validate
     spec-kitty agent status validate --mission 034-my-feature
     spec-kitty agent status validate --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission          <str>  Mission slug (required in multi-mission repos)     │
│ --json                    Machine-readable JSON output                       │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent tasks

_Task workflow commands for AI agents_

```
 Usage: spec-kitty agent tasks [OPTIONS] COMMAND [ARGS]...

 Task workflow commands for AI agents

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ move-task            Move task between lanes (planned → claimed →            │
│                      in_progress → for_review → in_review → approved →       │
│                      done).                                                  │
│ mark-status          Record subtask status for one or more tasks.            │
│ list-tasks           List tasks with optional lane filtering.                │
│ add-history          Record a history note in the WP status event log.       │
│ finalize-tasks       Parse tasks.md and inject dependencies into WP          │
│                      frontmatter.                                            │
│ map-requirements     Register requirement-to-WP mappings with immediate      │
│                      validation.                                             │
│ validate-workflow    Validate task metadata structure and workflow           │
│                      consistency.                                            │
│ status               Display kanban status board for all work packages in a  │
│                      mission.                                                │
│ list-dependents      Find all WPs that depend on a given WP (downstream      │
│                      dependents).                                            │
│ check-terminability  Advisory scan for work packages that can only be        │
│                      terminated post-integration.                            │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent tasks add-history

```
 Usage: spec-kitty agent tasks add-history [OPTIONS] {task_id}

 Record a history note in the WP status event log.

 Examples:
 spec-kitty agent tasks add-history WP01 --note "Completed implementation"
 --json
 spec-kitty agent tasks add-history WP01 --note-file NOTES.md --json
 git show -s --format=%B | spec-kitty agent tasks add-history WP01 --note-file
 -

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    task_id      <str>  Task ID (e.g., WP01) [required]                     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --note               <str>  History note (inline; use --note-file for        │
│                             literal Markdown)                                │
│ --mission            <str>  Mission slug                                     │
│ --agent              <str>  Agent name                                       │
│ --shell-pid          <str>  Shell PID                                        │
│ --note-file          <str>  Read the note from this file ('-' for stdin)     │
│ --json                      Output JSON format                               │
│ --help       -h             Show this message and exit.                      │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent tasks check-terminability

```
 Usage: spec-kitty agent tasks check-terminability [OPTIONS]

 Advisory scan for work packages that can only be terminated post-integration.

 Warns when a WP's acceptance criteria contain a post-integration trigger
 phrase (the #3590 trap) — content that cannot be verified in the WP's own
 diff. This is **advisory only**: it never refuses or fails authoring
 (FR-008) — it exits 0 even when warnings fire. It does not touch the
 finalize / lane-compute path (C-005).

 Examples:
     spec-kitty agent tasks check-terminability --mission my-mission --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission          <str>  Mission slug                                       │
│ --json                    Output JSON format                                 │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent tasks finalize-tasks

```
 Usage: spec-kitty agent tasks finalize-tasks [OPTIONS]

 Parse tasks.md and inject dependencies into WP frontmatter.

 Scans tasks.md for "Depends on: WP##" patterns or phase groupings,
 builds dependency graph, validates for cycles, and writes dependencies
 field to each WP file's frontmatter.

 Examples:
     spec-kitty agent tasks finalize-tasks --mission 001-my-feature --json
     spec-kitty agent tasks finalize-tasks --mission 021-my-feature --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission                <str>  Mission slug                                 │
│ --json                          Output JSON format                           │
│ --validate-only                 Validate without writing changes             │
│ --help           -h             Show this message and exit.                  │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent tasks list-dependents

```
 Usage: spec-kitty agent tasks list-dependents [OPTIONS] {wp_id}

 Find all WPs that depend on a given WP (downstream dependents).

 This answers "who depends on me?" - useful when reviewing a WP to understand
 the impact of requested changes on downstream work packages.

 Also shows what the WP itself depends on (upstream dependencies).

 Examples:
     spec-kitty agent tasks list-dependents WP13
     spec-kitty agent tasks list-dependents WP01 --mission 001-my-feature
 --json

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    wp_id      <str>  Work package ID (e.g., WP01) [required]               │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission          <str>  Mission slug                                       │
│ --json                    Output JSON format                                 │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent tasks list-tasks

```
 Usage: spec-kitty agent tasks list-tasks [OPTIONS]

 List tasks with optional lane filtering.

 Examples:
 spec-kitty agent tasks list-tasks --json
 spec-kitty agent tasks list-tasks --lane doing --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --lane             <str>  Filter by lane                                     │
│ --mission          <str>  Mission slug                                       │
│ --json                    Output JSON format                                 │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent tasks map-requirements

```
 Usage: spec-kitty agent tasks map-requirements [OPTIONS]

 Register requirement-to-WP mappings with immediate validation.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --wp                                      <str>   WP ID (e.g., WP04)         │
│ --refs                                    <str>   Comma-separated            │
│                                                   requirement refs (e.g.,    │
│                                                   FR-001,FR-002)             │
│ --batch                                   <str>   JSON batch mapping (e.g.,  │
│                                                   '{"WP01":["FR-001"],"WP02… │
│ --replace                                         Replace existing refs      │
│                                                   instead of merging         │
│                                                   (default: merge/union)     │
│ --tracker-ref                             <str>   External tracker reference │
│                                                   (e.g., '#1298' or          │
│                                                   'JIRA-123'). Repeatable;   │
│                                                   requires --wp. Persists to │
│                                                   the WP frontmatter as      │
│                                                   tracker_refs.              │
│ --mission                                 <str>   Mission slug               │
│ --json                                            Output JSON format         │
│ --auto-commit         --no-auto-commit            Automatically commit WP    │
│                                                   file changes (default:     │
│                                                   from project config)       │
│ --owned-checkout                          <path>  Run against an owned       │
│                                                   checkout: a linked         │
│                                                   checkout that owns this    │
│                                                   mission. Refuses the       │
│                                                   repository root checkout,  │
│                                                   lane worktrees and         │
│                                                   coordination worktrees.    │
│ --help            -h                              Show this message and      │
│                                                   exit.                      │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent tasks mark-status

```
 Usage: spec-kitty agent tasks mark-status [OPTIONS] {task_ids}...

 Record subtask status for one or more tasks.

 Accepts multiple task IDs separated by spaces. Status is recorded in the
 mission event log. Use --wp when the same ID appears in more than one WP.

 Examples:
     # Single task:
     spec-kitty agent tasks mark-status T001 --status done

     # Multiple tasks (space-separated):
     spec-kitty agent tasks mark-status T001 T002 T003 --status done

     # Many tasks at once:
     spec-kitty agent tasks mark-status T040 T041 T042 T043 T044 T045 --status
 done --mission 001-my-feature

     # With JSON output:
     spec-kitty agent tasks mark-status T001 T002 --status done --json

     # When IDs repeat across work packages:
     spec-kitty agent tasks mark-status T001 --wp WP02 --status skipped

     # Naming the agent that did the work (default tool: user):
     spec-kitty agent tasks mark-status T001 --status done --agent claude

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    task_ids      <str>  Task ID(s) - space-separated (e.g., T001 T002      │
│                           T003)                                              │
│                           [required]                                         │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --status                                  <str>   Status:                 │
│                                                      done/pending/skipped/n… │
│                                                      [required]              │
│    --mission                                 <str>   Mission slug            │
│    --wp                                      <str>   Work package containing │
│                                                      the subtasks (e.g.,     │
│                                                      WP02)                   │
│    --agent                                   <str>   Agent name (compact     │
│                                                      tool:model:profile      │
│                                                      accepted)               │
│    --owned-checkout                          <path>  Explicit single-branch  │
│                                                      checkout root.          │
│    --auto-commit         --no-auto-commit            Commit the status       │
│                                                      events this writes,     │
│                                                      when supported; only an │
│                                                      explicit                │
│                                                      --no-auto-commit keeps  │
│                                                      them uncommitted        │
│    --json                                            Output JSON format      │
│    --help            -h                              Show this message and   │
│                                                      exit.                   │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent tasks move-task

```
 Usage: spec-kitty agent tasks move-task [OPTIONS] {task_id}

 Move task between lanes (planned → claimed → in_progress → for_review →
 in_review → approved → done).

 ``blocked`` and ``canceled`` are reachable from the other lanes. ``doing`` is
 accepted as an input alias of ``in_progress`` and is never recorded.

 Review-rejection edges (a backward move out of review — ``--to planned`` from
 in_progress/for_review/in_review/approved, or ``in_review → in_progress``)
 MUST
 carry a rationale: pass ``--review-feedback-file``. That rationale is emitted
 as the status event's ``review_ref``/reason and is required by the shared
 status contract; the move is refused without it, also with ``--force``, and a
 ``--note``/``--reason`` alone does not satisfy it.

 ``--actor``/``--reason`` are accepted as aliases of ``--agent``/``--note``
 (matching ``issue-verdict``'s vocabulary, #3469) — use whichever spelling
 reads naturally; both apply the same value.

 Subtask completion is NOT tracked by ticking a checkbox in ``tasks.md`` —
 that file is guidance/documentation only. Completion is event-sourced; mark
 a subtask done with ``spec-kitty agent tasks mark-status T0NN --status done
 --mission <handle>`` (#2816). Ticking a checkbox alone will not clear the
 unchecked-subtasks gate on a ``--to for_review`` move.

 Examples:
     spec-kitty agent tasks move-task WP01 --to in_progress --assignee claude
 --json
     spec-kitty agent tasks move-task WP02 --to for_review --agent claude
 --shell-pid $$
     spec-kitty agent tasks move-task WP02 --to for_review --actor claude
 --shell-pid $$
     spec-kitty agent tasks move-task WP03 --to approved --note "Review passed"
     spec-kitty agent tasks move-task WP03 --to approved --reason "Review
 passed"
     spec-kitty agent tasks move-task WP03 --to done --done-override-reason
 "Branch deleted after hotfix merge"
     spec-kitty agent tasks move-task WP03 --to planned --review-feedback-file
 feedback.md
     spec-kitty agent tasks move-task WP03 --to planned --review-feedback-file
 feedback.md --reset-subtasks T002 --note "T002 regressed"

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    task_id      <str>  Task ID (e.g., WP01) [required]                     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --to                                         <str>   Target lane          │
│                                                         (planned/claimed/in… │
│                                                         doing is accepted as │
│                                                         an alias of          │
│                                                         in_progress)         │
│                                                         [required]           │
│    --mission                                    <str>   Mission slug         │
│    --agent,--actor                              <str>   Agent name (alias:   │
│                                                         --actor, matching    │
│                                                         issue-verdict's      │
│                                                         vocabulary). When    │
│                                                         the move hands the   │
│                                                         WP back for work (a  │
│                                                         rejection, a reopen, │
│                                                         for_review ->        │
│                                                         in_progress) it      │
│                                                         records only who     │
│                                                         acted and does not   │
│                                                         reassign the WP; use │
│                                                         --assignee for that. │
│                                                         If both --agent and  │
│                                                         --actor are given,   │
│                                                         the one supplied     │
│                                                         LAST on the command  │
│                                                         line wins.           │
│    --model                                      <str>   Refused: the         │
│                                                         dispatch Op carries  │
│                                                         no model identifier  │
│                                                         (#7013); omit it     │
│    --profile                                    <str>   Dispatch-resolved    │
│                                                         agent profile actual │
│    --invocation-id                              <str>   Authoritative        │
│                                                         dispatch Op record   │
│                                                         id                   │
│    --assignee                                   <str>   Assignee name,       │
│                                                         recorded on this     │
│                                                         transition           │
│                                                         regardless of the    │
│                                                         target lane (not     │
│                                                         limited to --to      │
│                                                         in_progress). When   │
│                                                         the move hands the   │
│                                                         WP back for work it  │
│                                                         also reassigns the   │
│                                                         WP to this agent.    │
│    --shell-pid                                  <str>   Shell PID            │
│    --note,--reason                              <str>   History note (alias: │
│                                                         --reason, matching   │
│                                                         issue-verdict's      │
│                                                         vocabulary). If both │
│                                                         --note and --reason  │
│                                                         are given, the one   │
│                                                         supplied LAST on the │
│                                                         command line wins.   │
│    --review-feedback-…                          <path>  Path to review       │
│                                                         feedback file.       │
│                                                         Required for         │
│                                                         review-rejection     │
│                                                         edges (--to planned, │
│                                                         incl. with --force;  │
│                                                         and                  │
│                                                         in_review->in_progr… │
│                                                         the move is refused  │
│                                                         without it. On --to  │
│                                                         approved/done its    │
│                                                         content is recorded  │
│                                                         when the move writes │
│                                                         a new approval       │
│                                                         review-cycle record; │
│                                                         otherwise a warning  │
│                                                         on stderr says it    │
│                                                         was not recorded     │
│                                                         (JSON stdout is      │
│                                                         unchanged). Refused  │
│                                                         (exit 1) on every    │
│                                                         other edge: those    │
│                                                         edges write no       │
│                                                         review cycle, so the │
│                                                         file would be        │
│                                                         validated and then   │
│                                                         dropped.             │
│    --reset-subtasks                             <str>   Comma-separated      │
│                                                         subtask ids (e.g.    │
│                                                         T002,T003) to reset  │
│                                                         on a --to planned    │
│                                                         rollback; the others │
│                                                         keep their state.    │
│                                                         Requires             │
│                                                         --note/--reason.     │
│                                                         Without it every     │
│                                                         non-skipped subtask  │
│                                                         resets.              │
│    --approval-ref                               <str>   Approval reference   │
│                                                         for approval/done    │
│                                                         transitions (e.g.,   │
│                                                         PR#42)               │
│    --reviewer                                   <str>   Reviewer name        │
│                                                         (auto-detected from  │
│                                                         git if omitted)      │
│    --self-review-fall…                                  Record that approval │
│                                                         is a self-review     │
│                                                         fallback after the   │
│                                                         intended reviewer    │
│                                                         failed.              │
│    --as-implementer                                     With --to for_review │
│                                                         out of in_review:    │
│                                                         record this          │
│                                                         re-submission as the │
│                                                         implementer's own    │
│                                                         act (role            │
│                                                         implementer), so its │
│                                                         --agent identity     │
│                                                         completes a claim    │
│                                                         that recorded no     │
│                                                         profile or model.    │
│    --intended-reviewer                          <str>   Reviewer that should │
│                                                         have reviewed this   │
│                                                         WP before fallback.  │
│    --reviewer-failure…                          <str>   Reason the intended  │
│                                                         reviewer failed.     │
│    --done-override-re…                          <str>   Required when --to   │
│                                                         done and merge       │
│                                                         ancestry cannot be   │
│                                                         verified; recorded   │
│                                                         in history/event     │
│                                                         reason               │
│    --force                                              Force move even with │
│                                                         unchecked subtasks   │
│                                                         (does not bypass     │
│                                                         planned rollback     │
│                                                         feedback             │
│                                                         requirement). Out of │
│                                                         in_review or         │
│                                                         approved it needs    │
│                                                         --note.              │
│    --tracker-ref                                <str>   External tracker     │
│                                                         reference (e.g.,     │
│                                                         '#1298' or           │
│                                                         'JIRA-123').         │
│                                                         Repeatable; appended │
│                                                         to the WP            │
│                                                         frontmatter          │
│                                                         tracker_refs.        │
│    --skip-review-arti…                                  Override a rejected  │
│                                                         latest review        │
│                                                         artifact when        │
│                                                         arbiter-approving;   │
│                                                         requires --note and  │
│                                                         records override     │
│                                                         evidence.            │
│    --auto-commit            --no-auto-commit            Commit this move's   │
│                                                         record (the          │
│                                                         transition, its note │
│                                                         and its review       │
│                                                         verdict); only an    │
│                                                         explicit             │
│                                                         --no-auto-commit     │
│                                                         keeps it             │
│                                                         uncommitted. Lane    │
│                                                         deliverables follow  │
│                                                         the project config   │
│    --json                                               Output JSON format   │
│    --skip-pre-review-…                                  Skip the pre-review  │
│                                                         regression gate on a │
│                                                         --to for_review move │
│                                                         (also honored via    │
│                                                         the                  │
│                                                         SPEC_KITTY_SKIP_PRE… │
│                                                         env var). The gate   │
│                                                         still runs and       │
│                                                         enforces by default. │
│    --owned-checkout                             <path>  Use an owned         │
│                                                         single_branch        │
│                                                         checkout for the     │
│                                                         local review         │
│                                                         lifecycle            │
│                                                         (force/skip, done,   │
│                                                         and arbiter modes    │
│                                                         unsupported).        │
│    --help               -h                              Show this message    │
│                                                         and exit.            │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent tasks status

```
 Usage: spec-kitty agent tasks status [OPTIONS]

 Display kanban status board for all work packages in a mission.

 Shows a beautiful overview of work package statuses, progress metrics,
 and next steps based on dependencies.

 WPs in "doing" with no commits for --stale-threshold minutes are flagged
 as potentially stale (agent may have stopped).

 Example:
     spec-kitty agent tasks status                  # the sole active mission
     spec-kitty agent tasks status --mission 012-documentation-mission
     spec-kitty agent tasks status --json
     spec-kitty agent tasks status --stale-threshold 15

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission                  <str>   Mission slug (optional when exactly one   │
│                                    active mission exists)                    │
│ --json                             Output as JSON                            │
│ --stale-threshold          <int>   Minutes of inactivity before a WP is      │
│                                    considered stale                          │
│                                    [default: 10]                             │
│ --owned-checkout           <path>  Run against an owned checkout: a linked   │
│                                    checkout that owns this mission. Refuses  │
│                                    the repository root checkout, lane        │
│                                    worktrees and coordination worktrees.     │
│ --help             -h              Show this message and exit.               │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent tasks validate-workflow

```
 Usage: spec-kitty agent tasks validate-workflow [OPTIONS] {task_id}

 Validate task metadata structure and workflow consistency.

 Examples:
 spec-kitty agent tasks validate-workflow WP01 --json

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    task_id      <str>  Task ID (e.g., WP01) [required]                     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission          <str>  Mission slug                                       │
│ --json                    Output JSON format                                 │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent tests

_Test-related commands for AI agents_

```
 Usage: spec-kitty agent tests [OPTIONS] COMMAND [ARGS]...

 Test-related commands for AI agents

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ stale-check  Detect test assertions likely invalidated by source changes     │
│              between two refs.                                               │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent tests stale-check

```
 Usage: spec-kitty agent tests stale-check [OPTIONS]

 Detect test assertions likely invalidated by source changes between two refs.

 Compares BASE..HEAD and reports assertions in the test suite that reference
 symbols (functions, classes, string literals) that were renamed or removed in
 the source diff.  Uses AST analysis only — no regex on test text, no test
 execution.

 Confidence levels:
   high   — identifier referenced directly inside Assert or assert* call
   medium — identifier appears anywhere in an assertion node
   low    — string literal matches a Constant in an assertion-bearing position
   info   — message-content check (literal checked against captured
            diagnostic text); skipped from CI noise, surfaced for manual
            review (#3957)

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --base          <str>   Base git ref for the diff [required]              │
│    --head          <str>   Head git ref for the diff [default: HEAD]         │
│    --repo          <path>  Repository root (default: current directory)      │
│                            [default: .]                                      │
│    --json                  Emit JSON instead of human-readable text          │
│    --help  -h              Show this message and exit.                       │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty agent tracer-append

```
 Usage: spec-kitty agent tracer-append [OPTIONS]

 Append a dated, attributed finding to the mission's tracer surface.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission                 <str>   Mission handle (e.g.                    │
│                                      'my-mission-01ABCDEF')                  │
│                                      [required]                              │
│ *  --category                <str>   Tracer category: approach |             │
│                                      design-decisions | tooling-friction     │
│                                      [required]                              │
│ *  --entry                   <str>   Finding text [required]                 │
│ *  --actor                   <str>   Attribution (required, non-empty)       │
│                                      [required]                              │
│    --json                            Output JSON format                      │
│    --owned-checkout          <path>  Run against an owned checkout: a linked │
│                                      checkout that owns this mission.        │
│                                      Refuses the repository root checkout,   │
│                                      lane worktrees and coordination         │
│                                      worktrees.                              │
│    --help            -h              Show this message and exit.             │
╰──────────────────────────────────────────────────────────────────────────────╯
```
<!-- END GENERATED -->
