---
type: "API"
title: "CLI Command Reference"
description: "Complete Spec Kitty 3.2 CLI command reference with subcommands, options, mission workflow commands, and generated help output."
status: "stable"
generated:
  by: "process:dockitty-export"
  at: "2026-11-12T00:00:00Z"
---

# CLI Command Reference

This reference lists the user-facing `spec-kitty` CLI commands and their flags exactly as surfaced by `--help`. For agent-only commands, see `docs/api/agent-subcommands.md`.

Terminology note:
- `Mission Type` = reusable workflow blueprint
- `Mission` = tracked item under `kitty-specs/<mission-slug>/`
- `Mission Run` = runtime/session instance
- As of 3.1.0, `--mission` is the canonical flag name for specifying the mission slug. `--feature` was a hidden deprecated alias; as of 3.2.x it has been **removed everywhere** — from the internal/agent command cluster (#1060-A) and from the user-facing top-level commands (#1060). `--mission` is now the sole selector; passing `--feature` exits with `No such option`.
- `mission-state`/`accept-mission`/`consolidate-mission` are the canonical orchestrator-api command names

## Getting Started

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

## Practical Usage

- [Install Spec Kitty](/guides/how-to/installation/install-spec-kitty.md)
- [Upgrade to 0.11.0](/guides/how-to/installation/install-and-upgrade.md)

## Command Internals

For non-obvious runtime behaviour an operator may encounter:

- [`finalize-tasks` internals](/api/finalize-tasks-internals.md) — explicit empty `owned_files` semantics, lane-depth cycle safety, and the planning-commit pin refresh.
- [Issue-matrix verdict reference](/development/reference/issue-matrix-verdicts.md) — the five `issue-verdict` verdict values, which gate at `approved` vs `done`, and the reference-classification model behind `move-task`'s approval gate. `move-task`'s `--actor`/`--reason` aliases and `issue-verdict`'s `not-applicable` verdict are agent-only commands documented in full in `docs/api/agent-subcommands.md` (regenerated from the live Typer surface); this reference page is the durable, hand-authored explanation of the vocabulary and gating rules those generated sections don't narrate (#3469).

## Coordination-routed Missions: where writes land

These notes are the hand-authored companion to the generated sections below (which are
regenerated from live `--help` and cannot carry them). They apply to a Mission whose topology is
`coord` or `lanes_with_coord`; `lanes` and `single_branch` Missions are unchanged. The design
record is the 2026-10-01 amendment of
[ADR 2026-06-19-1](/adr/3.x/2026-06-19-1-coord-empty-surface-fallback.md) and the
[architecture page](/architecture/artifact-placement-seam.md#the-write-location-write_dir).

- **One home for coordination records.** A coordination record (status log, decision events,
  issue matrix, and so on) is written only to the coordination worktree, never to the
  repository root checkout. If the worktree is not there yet, the command creates it (when the
  coordination branch exists locally) or refuses with `COORDINATION_WORKTREE_UNMATERIALIZED`
  and a recovery hint (when the branch exists only on a remote).
- **`spec-kitty spec-commit`** reports one outcome per surface it touched. `success` is `false`
  and the exit code is non-zero when any surface is refused or errored. The `--json` payload
  gains two additive keys, `surfaces` (one entry per surface with its outcome) and
  `arguments`; existing keys are unchanged.
- **`spec-kitty accept`** commits the current Mission's uncommitted PRIMARY-partition decision
  ledger (`decisions/index.json` and `DM-*.md`) before its cleanliness check, instead of
  refusing on it. Which files count is decided by the artifact taxonomy, not by a filename
  allowlist, and only for the Mission being accepted. Another Mission's ledger and any other
  uncommitted change still fail closed. With `--json` the payload adds
  `residual_commit.surfaces`.
- **`spec-kitty consolidate`** materializes an `UNMATERIALIZED` coordination surface whose
  branch is present locally, and proceeds. A remote-only branch, a deleted branch, a forked
  coordination log or a held status lock abort the run before any state change.
  **`consolidate --dry-run` does not materialize** and stays fail-closed: on an unmaterialized
  or deleted coordination surface the forecast stops with the same error rather than creating
  a worktree. The asymmetry is deliberate: a preview must not change the repository.
  Consolidation and coordination teardown also refuse with `COORDINATION_LEDGER_UNREPAIRED`
  while a Mission's decision ledger exists only on the coordination branch (see
  `doctor decisions` below).
- **`spec-kitty materialize`** creates the coordination worktree (once per coordination-routed
  Mission) and seeds a Mission created before the fix; see its generated help below. A
  remote-only branch or a forked log is listed in the error summary and the remaining
  Missions are still processed.
- **`spec-kitty agent mission create`** (agent-only; see
  [`agent-subcommands.md`](/api/agent-subcommands.md)) materializes and seeds the coordination
  worktree for a coordination-routed Mission and commits the creation records there; the
  target branch receives no coordination record.
- **`spec-kitty doctor decisions`** also reports forks. The decision ledger is a PRIMARY
  partition kind, while its events live on the coordination surface. A ledger that exists only
  on the coordination branch is reported as `DECISION_LEDGER_ONLY_ON_COORDINATION`, and two
  logs that disagree as `DECISION_LOG_FORKED`. `--repair` copies a coordination-only ledger
  into the PRIMARY partition without committing (commit it with `spec-commit` or `accept`),
  and **exits 1 on a fork without dropping any entry**. `--repair` keeps an index entry whose
  event exists on either surface; an entry with no event on any surface is still dropped.
- **Fresh clone.** The coordination status log is not part of a fresh clone, so on one,
  `doctor decisions` reports `clean: false` with `orphaned_in_index` entries: the index is
  there, its events are not. Restore the coordination log before using `--repair`, because
  `--repair` drops a genuine orphan. `agent decision verify` on the same clone is not
  reported as forked, finds every opened decision id, and reports `ledger.state == "primary"`.
- **Decision-index merge driver.** `.gitattributes` registers `merge=spec-kitty-decision-index`
  for `kitty-specs/**/decisions/index.json`, so concurrent additions on lane branches union
  by `decision_id` instead of conflicting. Projects initialised earlier get the driver from the
  upgrade migration `m_4_0_0rc5_decision_index_merge_driver`; run `spec-kitty upgrade`. Git runs
  the driver itself during a merge; it is an internal command you never invoke by hand.

## `spec-kitty consolidate`: exit codes and refusal codes

Hand-authored companion to the generated `consolidate` section below. `consolidate` lands a
Mission on its **local** target branch only; it never publishes to a remote unless `--push`
is passed.

**What `--dry-run` does not check.** The dry run refuses with the real run's "Missing mission
branch" refusal when the Mission's mission branch does not exist (#7267), so a clean forecast
does prove that branch present. Under the default squash strategy the preview
also leaves out lanes not yet merged into the mission branch, so it can refuse a landing that the
real run makes (#7268). It does not run the real run's canceled-content checks, so it can also
pass a landing that the real run refuses (#7296).

| Exit code | Meaning |
|---|---|
| `0` | The Mission landed and the cleanup finished. |
| `75` | The landing stands, but the coordination branch (or the mission branch of a Mission without a coordination topology) moved after it and was kept instead of deleted. Error code `COORD_MOVED_AFTER_LANDING`. Nothing was lost and nothing was rolled back. |
| any other non-zero | A refusal or a failure. The message says whether anything had moved and reports, per branch, what the rollback restored. When the rollback restored every branch it moved, it also says it re-baselined the record: that attempt's target baseline, snapshot and restore targets are dropped, so the next run (plain or `--resume`) reads the target's current tip as its pre-mutation baseline instead of the failed attempt's, and `--abort` clears what is left and exits `0`. A run that leaves a branch `NOT restored` keeps its baseline, snapshot and record. |

Stable codes that appear in the output. Match on the code, not on the surrounding prose:

| Code | When | What to do |
|---|---|---|
| `APPROVAL_STAMP_MISSING` | A work package in the approved claim has no recorded approval stamp (its approval has no `lane_head`, for example one recorded before the stamp existed, or a work package forced to `done` with no `approved` transition), so the commit review approved cannot be determined. Exit code `1`, before any branch moves. | Move the work package back for review and approve it again, or check the lane by hand and re-run with `--attest-approved-reviewed <WP> --attest-reason "..."`. The message prints both as commands for your Mission, with one attest command that lists every unstamped work package. |
| `APPROVAL_STAMP_NOT_ON_LANE` | An approval stamp names a commit that is not on the lane (the lane was rewritten after review approved it). Exit code `1`, before any branch moves. | Move the work package back for review and approve it again. Not overridable. |
| `APPROVED_CONTENT_MISSING` | The reconciliation gate found that an approved code lane's own net change to a path is not on the target, while the target left that path alone since the lane was cut and no later approved lane superseded it. The run FAILs and rolls back. Typical cause: the staged deletions of a lagging worktree were committed before a `--resume`. | Restore the change on the mission branch (for example revert the commit that recorded the deletions), then re-run. Not overridable. |
| `CANCELED_REACHABLE_VIA_DEPENDENCY` | Content of a fully-canceled dependency lane reached an approved lane, is still live there and is on the target. The run FAILs and rolls back. Content that every carrying lane fully superseded is not counted. | Undo the change on the carrying lane through a surviving WP's governed work, then re-run. Not overridable: `--attest-canceled-superseded` never lifts it. |
| `COORD_MOVED_AFTER_LANDING` | Exit code `75`, see above. The message ends with `Error code: COORD_MOVED_AFTER_LANDING.` | Coordination branch: review the late commit(s) with the `git log` command in the message, then run `spec-kitty consolidate --resume`, which lands them on the target and finishes the teardown. Mission branch without a coordination topology: land the commit(s) and delete the branch yourself. |
| `COORD_LATE_PROJECTION_REFUSED` | The teardown found a change on the coordination branch it cannot prove landed on the target: a status event, a coordination record (a gate matrix verdict, a trace), a primary artifact such as `meta.json`, or a deletion. A first run judges what was committed after the coordination tip it verified. A `--resume` whose landing an earlier run verified judges the same window: what was committed after the coordination tip recorded with that verified landing (while that tip is still on the coordination branch), so the Mission's own merges of primary artifacts that the target changed later are not judged again (#7491). Any other `--resume` judges everything the coordination branch changed since the merge began. A real late change that did not land still refuses. Exit code `1`. The coordination branch, worktree and marker are kept and the verified landing is not rolled back. | Follow the repair the message names for the kind of refusal, then run `spec-kitty consolidate --resume` again. `spec-kitty consolidate --abort` does not clear it. |
| `DEPENDENCY_REF_COVERS_MISSION_WORK` | A `--dependency-ref` would exempt Mission-authored work: the ref is named inside the Mission's branch namespace, or its window holds a commit on a lane or the mission branch spine, a `lane_head` stamp a work package recorded, or a recorded lane work tip. Exit code `1`, before any branch moves. | Declare only an external dependency branch. Mission work that left a recorded lane head, lane-tip ref or namespaced branch is refused even after its branch is deleted; work that left none of these cannot be detected. |
| `DEPENDENCY_REF_MOVED` | A declared ref was pinned to a commit when the claim was built and now resolves elsewhere (checked at the reconciliation gate and on `--resume`). The message names both SHAs. The run rolls back. | Restore the ref to the pinned SHA, or `spec-kitty consolidate --abort` and re-run with the new ref. |
| `DEPENDENCY_REF_SET_CHANGED` | `--dependency-ref` names a different set than the interrupted run recorded. Exit code `1`; the record is kept. | Re-run with the recorded set (or none), or `spec-kitty consolidate --abort` and start again. |
| `DEPENDENCY_REF_UNREACHABLE` | A declared ref is not reachable from the mission branch or any lane branch, so the Mission never merged it. Exit code `1`, before any branch moves. | Declare the ref the lane actually merged. |
| `DEPENDENCY_REF_UNRESOLVED` | A declared ref does not resolve to a commit. Exit code `1`, before any branch moves. | Declare a branch, tag or SHA that resolves, or drop `--dependency-ref`. |
| `DEPENDENCY_REF_UNVERIFIABLE` | A declaration could not be checked: a git probe failed, a lane spine could not be read, the status log was unreadable, or the target's pre-run commit could not be resolved. Nothing is exempted. Exit code `1`. | Fix the repository state the message names and re-run. |
| `LANE_MOVED_AFTER_APPROVAL` | A code lane holds a content commit made after review approved it (or after an `--attest-approved-reviewed` attestation). Exit code `1`, before any branch moves; also checked again at the reconciliation gate. | Move the work package back for review so the new content is reviewed, approve it again, re-run. The message names the late commits and the command to move each work package of the lane back; see a commit with `git show <sha>`. No attestation lifts it: `--attest-approved-reviewed` and `--attest-canceled-superseded` never do. On a lane that mixes an approved and a canceled work package, `--attest-canceled-superseded` still exempts lane commits up to its own lane head from the closed-world refusal, but the commit still needs its work package approved again. Nothing a canceled work package does covers a commit: no commit of its own, no status move of a work package that stays canceled, no attestation. Forcing a canceled work package into `approved` is a forced approval, which stamps the lane at its current tip; the bound is as strong as the review model (issue #5721). If a canceled work package committed on the lane after the approval, also when that work was reverted, the approved work package needs a new approval. When both refusals apply, the first message names both under `This Mission also has:`. |
| `RELEASE_BRANCH_INVALID` | `--release-branch` without `--abort` or without `--release-reason`, naming a branch that is not the record's target, mission or coordination branch (a lane branch or an unknown name), or naming a branch that does not resolve to a commit. Exit code `2`; nothing changed. | Correct the flags and re-run `spec-kitty consolidate --abort`. |
| `SQUASH_PROJECTION_NOT_LANDED` | Under the default `squash` strategy, coordination bookkeeping content the run projected did not land on the target. The message keeps the phrase `projected coordination bookkeeping content did not land`, lists up to 20 paths as `<path> — <reason>` (then `... and N more`), and gives one remedy per reason. The reasons: the target's copy differs from the coordination branch; the coordination branch has no copy (deleted or renamed there); both sides changed the path and it has no merge driver; both sides changed it and the target's copy is not what its merge driver produces; its merge driver refused the two copies (for example malformed content); a git probe failed. Exit code `1`. Nothing was torn down; the run goes through the rollback, and the rollback report printed below the refusal says what it restored (a `--resume` at a landing an earlier run verified keeps that landing). The message ends with `Error code: SQUASH_PROJECTION_NOT_LANDED.` | Follow the remedy printed for each reason: make the target's copy match the coordination branch, or revert the coordination change; restore a path the coordination branch deleted or renamed; or fix content the merge driver refused. Then re-run `spec-kitty consolidate --resume`. Only a failed git probe can clear on its own: re-run `spec-kitty consolidate --resume`, and if it repeats check that both branches resolve (`git rev-parse`) and that the repository is readable (`git fsck`). |
| `UNEXPLAINED_BRANCH_MOVE` | A re-run or `--resume` found a target, mission or coordination branch of an unfinished record at a commit the record cannot explain: neither its restore target nor a commit this run recorded or saved as its next move (for example a run killed right after it moved the branch). Refused before anything moves; the record is kept. Exit code `1`. Not raised while the target still sits at a verified landing. | Inspect `git log <restore-target>..<live>`. If the commits should not stay, move the branch yourself. To keep them, `spec-kitty consolidate --abort --release-branch <branch> --release-reason "<why>"`; a release keeps every listed commit. See [troubleshooting](/guides/how-to/recovery/troubleshoot-merge.md#a-branch-moved-without-a-record). |
| `PROJECTION_TEARDOWN_ABORTED` | The same race caught earlier: the coordination branch moved before anything was torn down, so the coordination worktree, branch and marker all survive. Exit code `1`. | Re-run `spec-kitty consolidate --resume`. |

- **`--attest-canceled-superseded <WP>`** lifts a REFUSE whose attribution evidence can never
  appear later, for the named WP only. Since #5613 that includes a canceled WP without a
  `lane_head` stamp on a fully-canceled dependency lane, which REFUSEs before any branch
  moves. It never lifts a FAIL, and it never approves content: a commit made after an approved
  work package's approval is still refused with `LANE_MOVED_AFTER_APPROVAL`. The verdict table and the override rules are stated once, in
  the [status model](/architecture/status-model.md#commit-attribution-stamp-policy_metadatalane_head).
- **`--attest-approved-reviewed <WP>`** (repeatable, shares `--attest-reason`) records, after you
  checked by hand that the lane holds only reviewed work, an operator attestation for an approved
  work package whose approval recorded no lane head. It lifts `APPROVAL_STAMP_MISSING` for that work
  package only: the lane head at the moment of the attestation becomes its bound, so a commit made
  afterwards is still refused with `LANE_MOVED_AFTER_APPROVAL`. A work package that already has an
  approval stamp, or is not approved, is refused and nothing is recorded; with `--dry-run` nothing is
  recorded and a notice says so. The attestation is a forced operator transition in the Mission's
  status log. Attesting again after an unrelated failure is accepted while the lane holds nothing beyond
  the earlier attestation; once it holds a later commit the repeat is refused, nothing is recorded, and
  the work package must go back for review.
- **`--abort --release-branch <branch> --release-reason "<why>"`** (repeatable) keeps a
  branch that `--abort` reports `NOT restored` at the commit it has when you run the command,
  reports it `kept` with the reason and a warning that it may contain this consolidation's
  unverified changes, and lets the record clear once every other branch is restored. A release
  never keeps a branch that can be restored, and it no longer applies once the branch moves. A
  release saved by an `--abort` that then fails on another branch stays in the record and is
  still honoured by a later plain `--abort` while the branch sits at that commit. See
  [Keep a branch that cannot be restored](/guides/how-to/recovery/troubleshoot-merge.md#keep-a-branch-that-cannot-be-restored).
- **`--abort` that keeps the record** exits `1`, prints the rollback report, and under
  `Next steps:` names one step per branch it left `NOT restored`, each one a step `--abort` can
  take (#7600): a checkout with local changes blocked the restore, so commit or stash them in the
  named checkout and re-run `spec-kitty consolidate --abort`; another actor moved the branch, so
  inspect the commits with the `git log` range it prints and, to keep them, run
  `spec-kitty consolidate --abort --release-branch <branch> --release-reason "<why>"`. A landing an
  earlier run verified is never rolled back, so `--abort` cannot finish there: the report says so
  and names `spec-kitty consolidate --resume` as the way to finish the teardown of that landing.
  The closing line points at those next steps instead of the generic "resolve the branches named
  above".
- **`--resume`** refreshes in place a repository root checkout, coordination worktree,
  mission worktree or lane worktree that only lags its own HEAD, and refuses with the exact
  recovery commands when such a worktree also holds an edit of your own. See
  [Recover from an Interrupted Consolidation](/guides/how-to/recovery/recover-from-interrupted-merge.md).
- **`spec-kitty orchestrator-api consolidate-mission`** reports `COORD_MOVED_AFTER_LANDING` as
  `data.teardown_error_code`; see the
  [orchestrator API reference](/api/orchestrator-api.md#consolidate-mission-datateardown_error_code).
- A status write that follows a rolled-back consolidation can be refused with
  `COORD_STATUS_SURFACE_DIVERGED`; see the
  [status model](/architecture/status-model.md#coordination-status-write-guard).

## `spec-kitty archive reclaim`: reclaim an archived Mission's coordination triple

`spec-kitty archive create` only records the archive. A coordination Mission whose consolidation
kept its coordination worktree, branch and `meta.json` marker (a retention policy, or a teardown
that refused) still holds them after it is archived; `archive create` then prints
`Reclaim its coordination worktree and branch with: spec-kitty archive reclaim <mission>`
(with `--json`, the same command is the `reclaim_command` field, `null` when no marker remains).
`archive reclaim` (#4041) releases them in this order: it removes the coordination worktree
through the shared teardown, deletes the coordination branch at the tip it proved landed (a tip no
other branch holds is kept under `refs/spec-kitty/discarded/`), then flattens the marker and
commits it to the target branch. It deletes the branch only when the Mission records its landing
(`merged_at`) and the branch tip is the coordination tip that verified landing recorded, or behind
it. Every step already done is skipped, so a run after a partial one finishes the rest, and a run
with nothing left prints `Nothing left to reclaim for <mission>.` and exits `0`.

```bash
spec-kitty archive reclaim my-mission-01ABCDEF
```

Add `--json` for `{"ok": true, "mission_slug": ..., "nothing_left": ..., "steps": [...]}`; a
refusal under `--json` is `{"ok": false, "error": {"code": ..., "message": ...}, "remedy": ...}`. A refusal prints
`Reclaim refused:`, the reason, the remedy and `Error code: <CODE>.`:

| Code | When | What to do |
|---|---|---|
| `RECLAIM_NOT_ARCHIVED` | The Mission is not archived. Exit code `1`; nothing changed. | Archive it first: `spec-kitty archive create <mission> --by <operator> --reason <why>`. |
| `RECLAIM_NO_COORDINATION` | The Mission has no coordination topology, so there is no coordination worktree or branch to reclaim. Also raised when `meta.json` cannot be read, or names a coordination branch but no mid8. Exit code `1`; nothing changed. | Nothing to do for a Mission without a coordination topology. Otherwise repair `meta.json` (`spec-kitty doctor identity` for a missing mid8), then re-run. |
| `RECLAIM_UNABSORBED` | The coordination branch is not proved landed: the Mission records no landing (`merged_at`); no landed coordination tip is recorded (the Mission landed before spec-kitty recorded one, or its landing was rolled back); the branch holds commits not reachable from the recorded landing, which the target never received (listed, up to 20); or git could not answer. Exit code `1`; the branch is kept and nothing changed. | See what the branch holds that the target lacks with `git log <target>..<coordination branch>` (a listed commit with `git show <sha>`); land or move the commits, or keep the branch. Remove the branch by hand (`git branch -D <coordination branch>`) only after confirming the target has all of it, then re-run `spec-kitty archive reclaim <mission>`. A canceled Mission is abandoned instead with `spec-kitty mission close --discard --mission <mission>`. After a git failure, check the repository and re-run. |
| `RECLAIM_NOT_ON_TARGET` | The flattened marker could not be committed, checked before any change: the repository root checkout is not on the branch the marker commits to, or the commit is refused for another reason the message names. Exit code `1`; nothing changed. | Run `git checkout <target branch>` (the message names it), or clear the cause it names, then re-run `spec-kitty archive reclaim <mission>`. |
| `RECLAIM_WORKTREE_KEPT` | The coordination worktree is still registered after the teardown ran, or the teardown failed with an unexpected error (named in the message). Exit code `1`; the branch and marker are kept. | Check `git worktree list` (or clear the error the message names), then re-run `spec-kitty archive reclaim <mission>`. |
| `RECLAIM_MARKER_NOT_COMMITTED` | The coordination worktree and branch are gone, but the marker could not be flattened, or it was flattened and its commit failed, or git could not say whether the flattened marker is committed. Exit code `1`. | Clear the cause the message names (on a branch mismatch, check out the branch it names), then re-run `spec-kitty archive reclaim <mission>`; the re-run flattens and commits the marker. |

A coordination worktree that holds the only copy of files, or a coordination branch that moved
while the worktree was removed, is refused with the teardown's own code
(`COORD_TEARDOWN_KEPT_ONLY_COPY`, `PROJECTION_TEARDOWN_ABORTED`), and the worktree, branch and
marker are kept. A branch delete the destructive-operation guard refuses is reported with that
guard's code; re-run `spec-kitty archive reclaim <mission>`.

## Schema references

- [Bulk-edit gate (`occurrence_map.yaml`)](/api/bulk-edit-gate.md)

<!-- BEGIN GENERATED -->
# CLI Command Reference

## spec-kitty accept

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

 Validate mission readiness before merging to main.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission                                    <str>       Mission slug to     │
│                                                          accept              │
│ --mode                                       <str>       Acceptance mode:    │
│                                                          auto, pr, local, or │
│                                                          checklist           │
│                                                          [default: auto]     │
│ --actor                                      <str>       Name to record as   │
│                                                          the acceptance      │
│                                                          actor               │
│ --test                                       <str>       Validation command  │
│                                                          executed            │
│                                                          (repeatable)        │
│ --json                                                   Emit JSON instead   │
│                                                          of formatted text   │
│ --lenient                                                Skip strict         │
│                                                          metadata validation │
│                                                          and downgrade       │
│                                                          missing             │
│                                                          path-convention     │
│                                                          checks to warnings. │
│                                                          To waive only the   │
│                                                          path-convention     │
│                                                          check, use          │
│                                                          --waive-path-conve… │
│ --no-commit                                              Report acceptance   │
│                                                          readiness without   │
│                                                          writing metadata or │
│                                                          status changes      │
│ --diagnose                                               Diagnose acceptance │
│                                                          blockers without    │
│                                                          writing metadata or │
│                                                          matrix artifacts    │
│ --allow-fail                                             Return checklist    │
│                                                          even when issues    │
│                                                          remain              │
│ --normalize-encod…      --no-normalize-e…                Repair              │
│                                                          acceptance-artifact │
│                                                          encoding            │
│                                                          (Windows-1252/Lati… │
│                                                          -> UTF-8) before    │
│                                                          validating.         │
│                                                          [default:           │
│                                                          no-normalize-encod… │
│ --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.          │
│ --origin-check                               <function>  Refuse (enforce,    │
│                                                          the default) or     │
│                                                          only warn (warn)    │
│                                                          when the mission's  │
│                                                          status evidence is  │
│                                                          behind or           │
│                                                          unreachable on its  │
│                                                          remote; off         │
│                                                          contacts nothing    │
│                                                          and accepts stale   │
│                                                          evidence. Overrides │
│                                                          SPEC_KITTY_ORIGIN_… │
│                                                          --no-commit and     │
│                                                          --diagnose always   │
│                                                          warn.               │
│ --merge-commit                               SHA         With --mode pr:     │
│                                                          record this PR      │
│                                                          merge commit as the │
│                                                          mission's           │
│                                                          post-merge review   │
│                                                          baseline. The       │
│                                                          commit is verified  │
│                                                          against git before  │
│                                                          anything is written │
│                                                          — it must carry     │
│                                                          kitty-specs/<slug>… │
│                                                          its first parent    │
│                                                          must not, and it    │
│                                                          must have landed on │
│                                                          the target branch.  │
│                                                          Every landing shape │
│                                                          additionally needs  │
│                                                          --attest-first-lan… │
│ --target-branch                              <str>       With                │
│                                                          --merge-commit: the │
│                                                          branch the PR       │
│                                                          merged into (the    │
│                                                          PR's base branch).  │
│                                                          Defaults to the     │
│                                                          mission's declared  │
│                                                          target_branch, else │
│                                                          the repository's    │
│                                                          primary branch.     │
│ --attest-first-la…                                       With                │
│                                                          --merge-commit:     │
│                                                          attest that the     │
│                                                          supplied commit's   │
│                                                          first parent is the │
│                                                          pre-landing target  │
│                                                          tip — for a         │
│                                                          two-parent merge    │
│                                                          commit, that the    │
│                                                          merge was performed │
│                                                          ON the target       │
│                                                          branch (an internal │
│                                                          merge               │
│                                                          fast-forwarded onto │
│                                                          the target is       │
│                                                          graph-identical,    │
│                                                          and its first       │
│                                                          parent is an        │
│                                                          implementation      │
│                                                          commit); for a      │
│                                                          single-parent       │
│                                                          landing (squash or  │
│                                                          corpus-first        │
│                                                          stack), that it was │
│                                                          the first commit of │
│                                                          the landing.        │
│                                                          Required for every  │
│                                                          landing shape: git  │
│                                                          cannot prove        │
│                                                          either, and a wrong │
│                                                          anchor silently     │
│                                                          under-scans the     │
│                                                          dead-code gate. The │
│                                                          attestation is      │
│                                                          recorded in         │
│                                                          pr_merge_evidence,  │
│                                                          never presented as  │
│                                                          a git proof.        │
│ --attest-no-imple…                           <str>       Operator            │
│                                                          attestation         │
│                                                          (repeatable, one WP │
│                                                          id each): the named │
│                                                          approved work       │
│                                                          package owes no     │
│                                                          implementation (for │
│                                                          example its         │
│                                                          deliverable already │
│                                                          exists). Lifts      │
│                                                          IMPLEMENTATION_MIS… │
│                                                          for that work       │
│                                                          package only; never │
│                                                          lifts               │
│                                                          REVIEW_NOT_INDEPEN… │
│                                                          and is never read   │
│                                                          as a review.        │
│                                                          Requires            │
│                                                          --attest-reason;    │
│                                                          recorded durably in │
│                                                          the status event    │
│                                                          log before the      │
│                                                          readiness checks.   │
│ --attest-reason                              <str>       Why no              │
│                                                          implementation is   │
│                                                          owed, recorded with │
│                                                          --attest-no-implem… │
│                                                          (required with it). │
│ --waive-path-conv…                                       Treat missing       │
│                                                          layout directories  │
│                                                          (src/, tests/,      │
│                                                          docs/...) as        │
│                                                          warnings for this   │
│                                                          run only; metadata  │
│                                                          validation stays    │
│                                                          strict and a        │
│                                                          missing Mission     │
│                                                          artifact such as    │
│                                                          contracts/ still    │
│                                                          blocks. Requires    │
│                                                          --waive-reason; the │
│                                                          reason is recorded  │
│                                                          in the acceptance   │
│                                                          history. To waive   │
│                                                          them for every run, │
│                                                          set                 │
│                                                          "path_conventions": │
│                                                          "waived" with a     │
│                                                          "path_conventions_… │
│                                                          in the Mission's    │
│                                                          meta.json.          │
│ --waive-reason                               <str>       Why path            │
│                                                          conventions are     │
│                                                          waived for this run │
│                                                          (required with      │
│                                                          --waive-path-conve… │
│ --help              -h                                   Show this message   │
│                                                          and exit.           │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty archive

_Archive a terminal mission (operator-invoked only)._

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

 Archive a terminal mission (operator-invoked only).

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ create   Archive a terminal mission (AM-1..AM-5).                            │
│ list     Enumerate archived missions (AM-3).                                 │
│ reclaim  Remove the coordination worktree, branch and marker an archived     │
│          Mission still holds.                                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty archive create

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

 Archive a terminal mission (AM-1..AM-5).

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    mission      <str>  Mission selector (slug or mission_id). [required]   │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --by              <str>  Operator identity performing the archive         │
│                             (required).                                      │
│                             [required]                                       │
│ *  --reason          <str>  Why the mission is being archived (required).    │
│                             [required]                                       │
│    --json                   Emit the archive record as JSON.                 │
│    --help    -h             Show this message and exit.                      │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty archive list

```
 Usage: spec-kitty archive list [OPTIONS]

 Enumerate archived missions (AM-3).

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Emit the archive registry as JSON.                         │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty archive reclaim

```
 Usage: spec-kitty archive reclaim [OPTIONS] {mission}

 Remove the coordination worktree, branch and marker an archived Mission still
 holds.

 The branch is deleted only when the Mission records its landing (merged_at)
 and the
 coordination tip is the one that landing recorded (or behind it). A second run
 reports
 that nothing is left.

 Example: spec-kitty archive reclaim my-mission-01ABCDEF

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    mission      <str>  Slug of an archived Mission. [required]             │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Emit the result as JSON.                                   │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter

_Charter management commands_

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

 Charter management commands

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ activate           Activate a doctrine artifact by kind and ID (FR-004), or  │
│                    apply a pack's preset.                                    │
│ deactivate         Deactivate a doctrine artifact by kind and ID (FR-005),   │
│                    with optional cascade.                                    │
│ consistency-check  Check the active charter for coherence against the        │
│                    offering (FR-011).                                        │
│ new                Scaffold a stub doctrine artifact YAML (FR-016).          │
│ validate           Validate project-layer doctrine artifacts against their   │
│                    schemas (FR-017).                                         │
│ fetch              Fetch org Charter Pack(s) from their configured remote    │
│                    sources.                                                  │
│ interview          Capture charter interview answers for later generation.   │
│ generate           Generate charter bundle from interview answers + doctrine │
│                    references.                                               │
│ context            Render charter context for a specific workflow action.    │
│ status             Display charter sync status plus synthesis/operator       │
│                    state.                                                    │
│ synthesize         Validate and promote agent-generated project-local        │
│                    doctrine artifacts.                                       │
│ resynthesize       Regenerate a bounded set of project-local doctrine        │
│                    artifacts (partial resynthesis).                          │
│ lint               Detect decay in charter artifacts via graph-native        │
│                    checks.                                                   │
│ preflight          Verify charter-derived state before a governed session    │
│                    begins.                                                   │
│ bundle             Charter bundle validation commands.                       │
│ mission-type       Mission type commands (activated types only).             │
│ list               List activated charter artifacts by kind.                 │
│ pack               Charter pack management commands.                         │
│ org                Manage org Charter Pack authoring (init, validate) and    │
│                    registration (add, remove).                               │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter activate

```
 Usage: spec-kitty charter activate [OPTIONS] [kind] [artifact_id]

 Activate a doctrine artifact by kind and ID (FR-004), or apply a pack's
 preset.

 Two forms:

   spec-kitty charter activate KIND ARTIFACT_ID [--cascade SCOPE
 [--include-deactivated]] [--only] [--json]

   spec-kitty charter activate [--pack PACK] --preset PRESET [--force] [--json]

 A preset replaces every activation key it governs: keys it lists are
 written (plus the org's required ids), keys it leaves out are removed.
 A change to a customised key is refused without --force. A deactivated
 id the preset lists stays deactivated (and is left out) unless --force,
 which also clears its exclusion.

 The cascade stops at a deactivated artifact and reports it;
 --include-deactivated walks through and clears the exclusions.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│   kind             <str>  Activation kind (e.g. directive, agent-profile).   │
│   artifact_id      <str>  Artifact ID to activate.                           │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --cascade                                <str>  Cascade activation scope:    │
│                                                 'all' for every referenced   │
│                                                 kind, or a comma-separated   │
│                                                 kind list (e.g.              │
│                                                 'agent-profile,tactic').     │
│                                                 Omit to skip cascade         │
│                                                 (referenced artifacts are    │
│                                                 reported as a warning).      │
│ --resynthesize      --no-resynthesize           Eagerly refresh the FULL     │
│                                                 derived bundle/DRG (bundle   │
│                                                 content hash + project DRG   │
│                                                 layer, not just the compiled │
│                                                 catalog) after this          │
│                                                 activation via the EXISTING  │
│                                                 synthesize pipeline (the     │
│                                                 same one `charter generate`  │
│                                                 + `charter synthesize` use). │
│                                                 Default activation already   │
│                                                 recompiles                   │
│                                                 `catalog.references` on its  │
│                                                 own via `charter generate`'s │
│                                                 own compile seam (see        │
│                                                 --no-compile to opt out of   │
│                                                 that lightweight recompile); │
│                                                 --resynthesize goes further  │
│                                                 and reconciles the freshness │
│                                                 signal to fresh immediately  │
│                                                 (NFR-001).                   │
│                                                 [default: no-resynthesize]   │
│ --compile           --no-compile                Skip the default             │
│                                                 post-activation catalog      │
│                                                 recompile (FR-003): the fast │
│                                                 config-only write from       │
│                                                 before issue #4785's fix.    │
│                                                 `catalog.references` is left │
│                                                 as-is and may go stale until │
│                                                 a later `charter generate`   │
│                                                 or `charter activate         │
│                                                 --resynthesize`.             │
│                                                 [default: compile]           │
│ --preset                                 <str>  Apply this activation preset │
│                                                 of the pack with replace     │
│                                                 semantics instead of         │
│                                                 activating one artifact.     │
│ --pack                                   <str>  Pack whose preset --preset   │
│                                                 applies (built-in, an org    │
│                                                 pack name). Only with        │
│                                                 --preset.                    │
│                                                 [default: built-in]          │
│ --force                                         Apply the preset even when   │
│                                                 it changes a customised      │
│                                                 activation key, and clear    │
│                                                 the exclusion of every       │
│                                                 deactivated id the preset    │
│                                                 lists. Only with --preset.   │
│ --json                                          Output JSON (positional      │
│                                                 form: change report;         │
│                                                 --preset: applied preset).   │
│ --only                                          Replace this kind's          │
│                                                 activation list with this id │
│                                                 plus org-required ids        │
│                                                 (prints what stops being in  │
│                                                 force).                      │
│ --help          -h                              Show this message and exit.  │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Cascade options ────────────────────────────────────────────────────────────╮
│ --include-deactivated          Walk through deactivated artifacts during the │
│                                cascade: activate them and clear their        │
│                                exclusions. Without it the cascade stops at a │
│                                deactivated artifact and reports it. Only     │
│                                with --cascade.                               │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter bundle

_Charter bundle validation commands._

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

 Charter bundle validation commands.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ validate  Validate the charter bundle against CharterBundleManifest v1.0.0.  │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter bundle validate

```
 Usage: spec-kitty charter bundle validate [OPTIONS]

 Validate the charter bundle against CharterBundleManifest v1.0.0.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Emit structured JSON to stdout instead of a human-readable │
│                   report.                                                    │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter consistency-check

```
 Usage: spec-kitty charter consistency-check [OPTIONS]

 Check the active charter for coherence against the offering (FR-011).

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

## spec-kitty charter context

```
 Usage: spec-kitty charter context [OPTIONS]

 Render charter context for a specific workflow action.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --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.    │
│ --mission                                 <str>   Mission handle bound to    │
│                                                   the explicitly selected    │
│                                                   owned checkout.            │
│ --action                                  <str>   Workflow action            │
│                                                   (specify|plan|implement|r… │
│ --include                                 <str>   A single fetch selector,   │
│                                                   e.g. agent-profile:<id>,   │
│                                                   template:<mission>/<name>, │
│                                                   directive:<id>,            │
│                                                   section:<slug>. Repeat     │
│                                                   --include to fetch         │
│                                                   several; one <kind>:<id>   │
│                                                   per occurrence (a comma is │
│                                                   refused).                  │
│ --mark-loaded         --no-mark-loaded            Persist first-load state   │
│                                                   [default: mark-loaded]     │
│ --profile                                 <str>   Agent profile whose cited  │
│                                                   directives and tactics are │
│                                                   added to the rendered text │
│                                                   (same id `spec-kitty       │
│                                                   dispatch --profile`        │
│                                                   accepts). With --include   │
│                                                   it is ignored; the         │
│                                                   structured --json blocks   │
│                                                   stay profile-agnostic.     │
│ --mission-type                            <str>   Canonical mission type     │
│                                                   (e.g.                      │
│                                                   documentation|research|pl… │
│                                                   for the action doctrine    │
│                                                   grain. Required when       │
│                                                   rendering action context   │
│                                                   from the repo root —       │
│                                                   without it, and without a  │
│                                                   mission's meta.json, the   │
│                                                   action grain is typeless   │
│                                                   and never inherits         │
│                                                   software-dev (#883).       │
│ --json                                            Output JSON.               │
│                                                   `context_schema_version`   │
│                                                   stamps the top-level       │
│                                                   payload shape (#2787,      │
│                                                   tracking contract -- not   │
│                                                   yet frozen). `directives`  │
│                                                   is action-scoped;          │
│                                                   `all_directives` and       │
│                                                   `project_charter` describe │
│                                                   the project-local charter, │
│                                                   while `org_charter`        │
│                                                   describes imported org     │
│                                                   packs.                     │
│ --include-all                                     Escape hatch: materialise  │
│                                                   the entire reachable       │
│                                                   closure inline in the      │
│                                                   structured (--json)        │
│                                                   payload instead of the     │
│                                                   default progressive        │
│                                                   disclosure (requires       │
│                                                   eager, suggests linked).   │
│                                                   Output is a superset of    │
│                                                   the progressive render for │
│                                                   the same grain.            │
│ --help            -h                              Show this message and      │
│                                                   exit.                      │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter deactivate

```
 Usage: spec-kitty charter deactivate [OPTIONS] [kind] [artifact_id]

 Deactivate a doctrine artifact by kind and ID (FR-005), with optional cascade.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│   kind             <str>  Activation kind (e.g. directive, agent-profile).   │
│   artifact_id      <str>  Artifact ID to deactivate.                         │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --cascade                                <str>  Cascade deactivation scope:  │
│                                                 'all' for every              │
│                                                 exclusively-referenced kind, │
│                                                 or a comma-separated kind    │
│                                                 list. Shared artifacts are   │
│                                                 never removed. Omit to       │
│                                                 deactivate only the named    │
│                                                 artifact.                    │
│ --resynthesize      --no-resynthesize           Eagerly refresh the FULL     │
│                                                 derived bundle/DRG (bundle   │
│                                                 content hash + project DRG   │
│                                                 layer, not just the compiled │
│                                                 catalog) after this          │
│                                                 activation via the EXISTING  │
│                                                 synthesize pipeline (the     │
│                                                 same one `charter generate`  │
│                                                 + `charter synthesize` use). │
│                                                 Default activation already   │
│                                                 recompiles                   │
│                                                 `catalog.references` on its  │
│                                                 own via `charter generate`'s │
│                                                 own compile seam (see        │
│                                                 --no-compile to opt out of   │
│                                                 that lightweight recompile); │
│                                                 --resynthesize goes further  │
│                                                 and reconciles the freshness │
│                                                 signal to fresh immediately  │
│                                                 (NFR-001).                   │
│                                                 [default: no-resynthesize]   │
│ --compile           --no-compile                Skip the default             │
│                                                 post-activation catalog      │
│                                                 recompile (FR-003): the fast │
│                                                 config-only write from       │
│                                                 before issue #4785's fix.    │
│                                                 `catalog.references` is left │
│                                                 as-is and may go stale until │
│                                                 a later `charter generate`   │
│                                                 or `charter activate         │
│                                                 --resynthesize`.             │
│                                                 [default: compile]           │
│ --json                                          Output the change report as  │
│                                                 JSON.                        │
│ --help          -h                              Show this message and exit.  │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter fetch

```
 Usage: spec-kitty charter fetch [OPTIONS]

 Fetch org Charter Pack(s) from their configured remote sources.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --pack             <str>  Fetch only the named pack (default: fetch all      │
│                           configured packs).                                 │
│ --dry-run                 Show what would be fetched without contacting any  │
│                           remote.                                            │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter generate

```
 Usage: spec-kitty charter generate [OPTIONS]

 Generate charter bundle from interview answers + doctrine references.

 Behavior contract (issue #841 / WP06 T029-T030):

 - On success in a git working tree, the produced
 ``.kittify/charter/charter.md``
   is auto-staged via ``git add`` so a subsequent ``charter bundle validate``
   finds it tracked without any operator ``git add`` between the two
   commands. Staging (not committing) matches the parity contract — the
   ``bundle validate`` tracked-files check keys on ``git ls-files``.
 - When the cwd is not inside a git working tree, ``generate`` exits
   non-zero before any side effect with an actionable error message that
   names the remediation (``git init``).
 - When ``.kittify/charter/charter.md`` is a symlink, ``generate`` exits
   non-zero before interview/default loading, compilation, sync,
   gitignore updates, or staging. Update the symlink target directly or
   replace it with a regular runtime charter.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission-type                               <str>   Mission type for        │
│                                                      template-set defaults   │
│ --template-set                               <str>   Override charter        │
│                                                      offering template set   │
│                                                      (must exist in packaged │
│                                                      charter offering        │
│                                                      missions)               │
│ --from-interview      --no-from-interview            Load interview answers  │
│                                                      if present              │
│                                                      [default:               │
│                                                      from-interview]         │
│ --profile                                    <str>   Default profile when no │
│                                                      interview is available  │
│                                                      [default: minimal]      │
│ --force           -f                                 Overwrite existing      │
│                                                      charter bundle          │
│ --json                                               Output 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. │
│ --mission-handle                             <str>   Mission identity owned  │
│                                                      by the explicitly       │
│                                                      selected checkout       │
│ --help            -h                                 Show this message and   │
│                                                      exit.                   │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter interview

```
 Usage: spec-kitty charter interview [OPTIONS]

 Capture charter interview answers for later generation.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission-type                 <str>  Mission type for charter defaults      │
│                                       (default: software-dev)                │
│ --profile                      <str>  Interview profile: minimal or          │
│                                       comprehensive                          │
│                                       [default: minimal]                     │
│ --defaults                            Use deterministic defaults without     │
│                                       prompts                                │
│ --selected-paradigms           <str>  Comma-separated paradigm IDs override  │
│ --selected-directives          <str>  Comma-separated directive IDs override │
│ --available-tools              <str>  Comma-separated tool IDs override      │
│ --narrow-activation                   Replace (not append to) activated      │
│                                       directives, tactics and paradigms with │
│                                       the selection plus org-required ids    │
│ --json                                Output JSON                            │
│ --mission-slug                 <str>  Mission slug for Decision Moment paper │
│                                       trail (optional)                       │
│ --help                 -h             Show this message and exit.            │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter lint

```
 Usage: spec-kitty charter lint [OPTIONS]

 Detect decay in charter artifacts via graph-native checks.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission                 <str>  Scope lint to a specific mission slug       │
│ --orphans                        Run only orphan checks                      │
│ --contradictions                 Run only contradiction checks               │
│ --stale                          Run only staleness checks                   │
│ --json                           Output findings as JSON                     │
│ --severity                <str>  Minimum severity (low/medium/high/critical) │
│                                  [default: low]                              │
│ --help            -h             Show this message and exit.                 │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter list

_List activated charter artifacts by kind._

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

 List activated charter artifacts by kind.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --show-available            Also show available-but-not-activated artifacts. │
│ --all                       Show every available artifact per kind across    │
│                             the built-in, org, and project layers (annotated │
│                             by source layer), including the template kind.   │
│                             Supersedes --show-available.                     │
│ --json                      Output JSON. Every kind row always carries an    │
│                             'available' key and the payload always carries a │
│                             top-level 'templates' key — both are null unless │
│                             requested (available: null without               │
│                             --show-available/--all; templates: null without  │
│                             --all) rather than absent, so callers can rely   │
│                             on key presence and branch on the value instead  │
│                             of on which flags were passed.                   │
│ --help            -h        Show this message and exit.                      │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter mission-type

_Mission type commands (activated types only)._

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

 Mission type commands (activated types only).

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ list  List mission types for the current project (FR-016).                   │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter mission-type list

```
 Usage: spec-kitty charter mission-type list [OPTIONS]

 List mission types for the current project (FR-016).

 By default, returns only mission types that are explicitly activated in
 this project's charter. Pass ``--include-inactive`` to also see every
 type registered in the built-in/org/project layers regardless of
 activation state (it replaced the removed doctrine-group listing; it is
 not a straight alias: activation state still distinguishes the two row
 classes -- see ACTION SEQUENCE below).

 Output columns (table): ID, SOURCE, DISPLAY NAME, ACTION SEQUENCE. A
 non-activated ``--include-inactive`` row shows ``(not activated)`` in
 ACTION SEQUENCE: resolving a real action sequence requires activation
 (the FR-006 gate), so there is nothing to compute for it.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json                        Output as JSON.                                │
│ --include-inactive            Also list mission types registered in the      │
│                               built-in/org/project layers but NOT activated  │
│                               for this project (activation-blind).           │
│ --help              -h        Show this message and exit.                    │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter new

```
 Usage: spec-kitty charter new [OPTIONS] {kind} {ID}

 Scaffold a stub doctrine artifact YAML (FR-016).

 The scaffolder pre-fills the canonical schema's required fields with
 ``TODO …`` placeholders so the file passes ``charter validate`` on
 first emit.  Refuses to overwrite an existing file.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    kind      <str>  Artifact kind (singular): one of agent_profile, asset, │
│                       directive, mission_step_contract, paradigm, procedure, │
│                       styleguide, tactic, toolguide.                         │
│                       [required]                                             │
│ *    ID        <str>  Artifact identifier (kebab-case for most kinds;        │
│                       SCREAMING_SNAKE for directives).                       │
│                       [required]                                             │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --pack          <path>  Scaffold inside a Charter Pack directory instead of  │
│                         the project layer. When omitted, the stub lands      │
│                         under .kittify/charter-packs/.                       │
│ --help  -h              Show this message and exit.                          │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter org

_Manage org Charter Pack authoring (init, validate) and registration (add, remove)._

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

 Manage org Charter Pack authoring (init, validate) and registration (add,
 remove).

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ init      Scaffold a minimal org pack or render from a template.             │
│ validate  Validate an org Charter Pack using schema and DRG checks (FR-006). │
│ add       Register an org Charter Pack with this project (#6267).            │
│ remove    Retire an org Charter Pack registration (#6267).                   │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter org add

```
 Usage: spec-kitty charter org add [OPTIONS] {name}

 Register an org Charter Pack with this project (#6267).

 Validates the pack exactly as ``spec-kitty charter org validate`` does, then
 writes one ``charter_packs.org.packs[]`` entry through the registry's own
 write seam -- the operator never hand-edits ``.kittify/config.yaml``.

 Every refusal exits 1 and leaves the config byte-identical. With ``--url``
 the pack root may be absent: it is then registered for
 ``spec-kitty charter fetch`` rather than validated. Nothing here touches the
 network.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    name      <str>  Name to register the pack under. [required]            │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --local-path           <str>  Pack root: relative to the project root,    │
│                                  absolute, ~-prefixed, or a ${VAR} template  │
│                                  (tokens are never expanded or frozen;       │
│                                  redundant ./ and trailing separators are    │
│                                  normalised). May be absent when --url is    │
│                                  given.                                      │
│                                  [required]                                  │
│    --url                  <str>  Remote source URL. Registers the pack for   │
│                                  `charter fetch` instead of requiring a      │
│                                  local pack.                                 │
│    --ref                  <str>  Git ref to fetch (requires --url).          │
│    --source-type          <str>  Remote source type:                         │
│                                  git|https|artifactory|api (requires --url;  │
│                                  defaults to git).                           │
│    --subdir               <str>  Subdirectory of the pack root that holds    │
│                                  the doctrine artifacts.                     │
│    --force                       Replace an existing registration of the     │
│                                  same name (declaration order is kept).      │
│    --json                        Output as JSON.                             │
│    --help         -h             Show this message and exit.                 │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter org init

```
 Usage: spec-kitty charter org init [OPTIONS] {pack_path}

 Scaffold a minimal org pack or render from a template.

 Without ``--template``, creates four files under *pack-path*::

     org-charter.yaml     — governance policy stub
     drg/fragment.yaml    — DRG extension stub (with pydantic_model:
 frontmatter)
     presets/starter.yaml — example activation preset
     README.md            — authoring quickstart

 With ``--template``, copies the full template tree (minus
 ``.templateignore``),
 substitutes ``{{ORG_NAME}}`` / ``{{LOCAL_PATH}}``, and writes under
 *pack-path*.

 Refuses to overwrite an existing directory unless ``--force`` is passed.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    pack_path      <path>  Destination directory for the scaffold or        │
│                             rendered charter pack tree.                      │
│                             [required]                                       │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --force                      Overwrite an existing pack directory.           │
│ --template            <str>  Local template directory or git URL (HTTPS/SSH; │
│                              optional #branch). When omitted, scaffolds the  │
│                              minimal four-file pack.                         │
│ --org-name            <str>  Validated org/pack identity for {{ORG_NAME}}    │
│                              (required with --template).                     │
│ --local-path          <str>  Value for {{LOCAL_PATH}} (default: pack).       │
│                              Distinct from PACK_PATH.                        │
│ --branch              <str>  Git ref when --template is a git URL (may also  │
│                              be encoded in TEMPLATE).                        │
│ --help        -h             Show this message and exit.                     │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter org remove

```
 Usage: spec-kitty charter org remove [OPTIONS] {name}

 Retire an org Charter Pack registration (#6267).

 Deletes exactly that ``charter_packs.org.packs[]`` entry; every other key,
 comment and pack in ``.kittify/config.yaml`` is left alone. The pack
 directory is never deleted -- the command prints where it stays (C-003).
 An unknown name exits 1 listing the configured names; the config is then
 byte-identical.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    name      <str>  Name of the registered pack to retire. [required]      │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Output as JSON.                                            │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter org validate

```
 Usage: spec-kitty charter org validate [OPTIONS] {pack_path}

 Validate an org Charter Pack using schema and DRG checks (FR-006).

 Calls the WP06 :func:`charter.offering.packs.pack_validator.validate_pack`
 loader.  Prints per-file findings with file paths.  Exits non-zero when
 at least one error is found.

 Org fragments use id and plural kind (for example, directives) for nodes.
 Validation uses the runtime loader, which supplies pack provenance fields.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    pack_path      <path>  Path to the org Charter Pack directory to        │
│                             validate.                                        │
│                             [required]                                       │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter pack

_Charter pack management commands._

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

 Charter pack management commands.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ list              List the packs of the project's offering and the presets   │
│                   each ships (FR-004).                                       │
│ path              Print a pack's root, or with --preset the preset file      │
│                   (FR-006).                                                  │
│ validate          Validate a Charter Pack against schema and DRG             │
│                   constraints.                                               │
│ assemble          Assemble multiple Charter Packs into a single              │
│                   distributable.                                             │
│ regenerate-graph  Regenerate the shipped DRG graph source deterministically  │
│                   (FR-009).                                                  │
│ vendor            Bump (or verify) a pack pin; the pack tree itself is       │
│                   fetched by ``make sync-packs``.                            │
│ asset             Resolve shipped and overlay charter pack assets (no        │
│                   install — C-002).                                          │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter pack assemble

```
 Usage: spec-kitty charter pack assemble [OPTIONS] {output_path}
                                         {input_packs}...

 Assemble multiple Charter Packs into a single distributable.

 Exits 0 on success and 1 when conflicts block the merge or when the
 assembled output fails validation.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    output_path      <path>  Output directory for the assembled             │
│                               distributable pack.                            │
│                               [required]                                     │
│ *    input_packs      <path>  One or more input pack directories to          │
│                               assemble.                                      │
│                               [required]                                     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --conflicts-out          <path>  Write the conflict report to this path      │
│                                  (JSON).                                     │
│ --force                          Resolve artifact-id conflicts by            │
│                                  last-pack-wins and drop duplicate DRG edges │
│                                  silently.                                   │
│ --json                           Emit machine-readable JSON instead of rich  │
│                                  text.                                       │
│ --help           -h              Show this message and exit.                 │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter pack asset

_Resolve shipped and overlay charter pack assets (no install — C-002)._

```
 Usage: spec-kitty charter pack asset [OPTIONS] COMMAND [ARGS]...

 Resolve shipped and overlay charter pack assets (no install — C-002).

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ list  List all resolvable charter pack assets and their source tiers.        │
│ path  Resolve an asset identifier to a filesystem path (fail-closed on       │
│       miss).                                                                 │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter pack asset list

```
 Usage: spec-kitty charter pack asset list [OPTIONS]

 List all resolvable charter pack assets and their source tiers.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Emit machine-readable JSON instead of rich text.           │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter pack asset path

```
 Usage: spec-kitty charter pack asset path [OPTIONS] {ASSET_ID}

 Resolve an asset identifier to a filesystem path (fail-closed on miss).

 Exits ``0`` and prints the path on success. An unknown id or a containment
 refusal exits non-zero with the offending id named (A-7 / NFR-006).

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    ASSET_ID      <str>  Identifier of the asset to resolve (see `charter   │
│                           pack asset list`).                                 │
│                           [required]                                         │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Emit machine-readable JSON instead of rich text.           │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter pack list

```
 Usage: spec-kitty charter pack list [OPTIONS]

 List the packs of the project's offering and the presets each ships (FR-004).

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

## spec-kitty charter pack path

```
 Usage: spec-kitty charter pack path [OPTIONS] {pack}

 Print a pack's root, or with --preset the preset file (FR-006).

 Fails closed (exit 1) with PACK_NOT_FOUND or PRESET_NOT_FOUND, listing the
 valid names.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    pack      <str>  Pack name (built-in, an org pack name, or project).    │
│                       [required]                                             │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --preset          <str>  Print this preset's file instead of the pack root.  │
│ --json                   Output as JSON.                                     │
│ --help    -h             Show this message and exit.                         │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter pack regenerate-graph

```
 Usage: spec-kitty charter pack regenerate-graph [OPTIONS]

 Regenerate the shipped DRG graph source deterministically (FR-009).

 Composes the DRG extractor + calibrator into per-populated-node-kind
 ``packs/built-in/*.graph.yaml`` fragments (sharded per mission #2680 WP05;
 relocated from ``src/charter/offering/`` by the pack flatten),
 retiring the legacy ``graph.yaml`` monolith in the same write. Running twice
 on unchanged inputs yields byte-identical fragments. With ``--check`` the
 command never writes: it regenerates into a temp directory and compares the
 fragment set against the committed source, exiting non-zero when stale — the
 operator-facing twin of the freshness gate.

 Both the write path and ``--check`` merge in the enumerable hand-authored
 overlay (:mod:`charter.offering.drg.migration.hand_authored_overlay`) — the
 ``in_tension_with``/``reconciles_tension``/``rejects`` edges and
 ``anti_pattern`` nodes hand-authored directly in the graph fragments
 (mission doctrine-tension-edges-01KY1WPC). The extractor has no
 frontmatter mechanism that could ever mint these, so a bare pure
 regeneration would (a) silently drop them from the committed source on
 write, and (b) always report "stale" under ``--check`` even when nothing
 is actually stale.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --check                      Do not write; regenerate into a temp directory  │
│                              and compare the per-kind graph fragments        │
│                              against the committed packs/built-in source.    │
│                              Exit 1 when stale (operator-runnable freshness  │
│                              gate). Exit 0 when fresh.                       │
│ --pack-root          <path>  Regenerate the DRG fragments and pack manifest  │
│                              for the BUILT-IN-level pack at this root        │
│                              instead of the shipped built-in pack (e.g. a    │
│                              vendored copy). The root must carry a pack.yaml │
│                              declaring pack_level: built-in; org and project │
│                              packs are refused. Applies to both the write    │
│                              path and --check. Defaults to the built-in pack │
│                              root, leaving the no-flag behaviour             │
│                              byte-identical.                                 │
│ --json                       Emit machine-readable JSON instead of rich      │
│                              text.                                           │
│ --help       -h              Show this message and exit.                     │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter pack validate

```
 Usage: spec-kitty charter pack validate [OPTIONS] {pack_path}

 Validate a Charter Pack against schema and DRG constraints.

 Exits 0 when the pack passes validation (advisories do not affect the
 exit code) and 1 when at least one error is reported.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    pack_path      <path>  Path to the Charter Pack directory to validate.  │
│                             [required]                                       │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Emit machine-readable JSON instead of rich text.           │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter pack vendor

```
 Usage: spec-kitty charter pack vendor [OPTIONS]

 Bump (or verify) a pack pin; the pack tree itself is fetched by ``make
 sync-packs``.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --check                   Verify only (offline): compare packs/<pack>/ with  │
│                           its pin lockfile; exit 1 on drift. Mutates         │
│                           nothing.                                           │
│ --ref              <str>  Bump the pin to this open-packs commit SHA or      │
│                           branch (resolved to a SHA; only the SHA is         │
│                           persisted).                                        │
│ --pack             <str>  Pack whose packs/<pack>.source.yaml pin to use.    │
│                           [default: built-in]                                │
│ --subtree          <str>  Override the pin's subtree (the pack's path inside │
│                           the open-packs repository).                        │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter preflight

```
 Usage: spec-kitty charter preflight [OPTIONS]

 Verify charter-derived state before a governed session begins.

 Pipeline:

 1. Resolve the repo root (same logic as the rest of the ``charter``
    subcommand group).
 2. Invoke :func:`run_charter_preflight`.
 3. Render JSON or a Rich summary, then exit per the contract.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json                    Emit the result as JSON (binding shape, see        │
│                           contracts/charter-preflight-json.md).              │
│ --auto-refresh            When checks fail and the worktree has no           │
│                           uncommitted generated artifacts, run the safe      │
│                           refresh sequence (charter generate / upgrade --yes │
│                           -> synthesize -> bundle validate).                 │
│ --strict                  Exit non-zero on any non-fresh state (default:     │
│                           exit zero unless a hard error occurs).             │
│ --help          -h        Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter resynthesize

```
 Usage: spec-kitty charter resynthesize [OPTIONS]

 Regenerate a bounded set of project-local doctrine artifacts (partial
 resynthesis).

 Uses a structured selector to identify the target set:

 - ``directive:PROJECT_001`` — regenerate a specific project directive.
 - ``tactic:how-we-apply-directive-003`` — regenerate one tactic.
 - ``directive:DIRECTIVE_003`` — regenerate every artifact whose provenance
   references the built-in DIRECTIVE_003 URN.
 - ``testing-philosophy`` — regenerate all artifacts from that interview
 section.

 Unrelated artifacts are never touched (FR-017).

 Examples
 --------
 Resynthesize a single tactic::

     spec-kitty charter resynthesize --topic tactic:how-we-apply-directive-003

 Resynthesize all artifacts referencing a built-in directive::

     spec-kitty charter resynthesize --topic directive:DIRECTIVE_003

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --topic                       <str>  Structured topic selector:              │
│                                      <kind>:<slug> (project-local),          │
│                                      <drg-urn> (built-in+project graph), or  │
│                                      <interview-section-label>.              │
│ --list-topics                        List valid structured topic selectors   │
│                                      and exit.                               │
│ --adapter                     <str>  Adapter to use. 'generated' (default)   │
│                                      validates agent-authored YAML under     │
│                                      .kittify/charter/generated/. 'fixture'  │
│                                      is offline/testing only.                │
│                                      [default: generated]                    │
│ --skip-code-evidence                 Skip code-reading evidence collection.  │
│ --skip-corpus                        Skip best-practice corpus loading.      │
│ --json                               Output JSON                             │
│ --help                -h             Show this message and exit.             │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter status

```
 Usage: spec-kitty charter status [OPTIONS]

 Display charter sync status plus synthesis/operator state.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json                  Output JSON                                          │
│ --provenance            Include per-artifact provenance details.             │
│ --help        -h        Show this message and exit.                          │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter synthesize

```
 Usage: spec-kitty charter synthesize [OPTIONS]

 Validate and promote agent-generated project-local doctrine artifacts.

 Reads the charter interview answers, resolves synthesis targets from the
 DRG + doctrine, and writes all artifacts to ``.kittify/charter-packs/``.

 Doctrine generation is performed by the LLM harness (Claude Code, Codex,
 Cursor, etc.) via the spk-charter-governance skill. This command
 validates and promotes the artifacts the agent has written.

 Fresh-project behavior (issue #839 / WP06 T031-T033)
 ----------------------------------------------------
 On a fresh project where ``.kittify/charter/generated/`` is missing or
 empty (i.e. the LLM harness has not yet written agent artifacts), this
 command short-circuits the adapter pipeline and materializes the
 **minimal artifact set** the runtime requires:

 1. ``.kittify/charter-packs/`` — directory marker. The project-root
    resolver (``charter.activation._project_root_candidates``) is a
    presence-only check; an empty directory is a valid project layer.
 2. ``.kittify/charter-packs/PROVENANCE.md`` — human-readable record of the
    fresh-project seed path, citing #839.

 The runtime falls back to the built-in doctrine (``packs/built-in/``) for
 all artifact lookups until the harness writes per-target YAML and the
 operator re-runs ``synthesize`` (which then takes the normal adapter
 path). The fresh-project path is **idempotent**: re-running produces
 bytewise-identical output (T033). Charter prerequisites are still
 enforced — ``charter.md`` must exist (else ``TaskCliError`` is raised
 via ``_build_synthesis_request``).

 Examples
 --------
 Validate + promote generated artifacts written by the harness::

     spec-kitty charter synthesize

 Validate + promote with fixture adapter (offline/testing)::

     spec-kitty charter synthesize --adapter fixture

 Dry-run (stage + validate, no promote)::

     spec-kitty charter synthesize --dry-run

 Preserve-and-warn default (WP03): a plain run never drops backed
 content -- it exits 0 and reports what it retained. Remove divergent
 content explicitly::

     spec-kitty charter synthesize --prune

 Only orphaned content (backing artifact deleted) or an unparseable
 on-disk overlay make a plain run refuse (exit 1); backed divergence is
 always preserved and reported, never a refusal.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --adapter                     <str>  Adapter to use. 'generated' (default)   │
│                                      validates agent-authored YAML under     │
│                                      .kittify/charter/generated/. 'fixture'  │
│                                      is offline/testing only.                │
│                                      [default: generated]                    │
│ --dry-run                            Stage and validate artifacts but do not │
│                                      promote to live tree. Also reports the  │
│                                      reconciliation delta --prune would      │
│                                      remove. Wins over --prune when both are │
│                                      given (preview only, no write).         │
│ --prune                              Remove on-disk content the current run  │
│                                      no longer targets and list every        │
│                                      deletion. Without this flag, that       │
│                                      content is preserved (default) unless   │
│                                      it is orphaned (backing artifact        │
│                                      deleted), which refuses instead of      │
│                                      silently keeping a dangling reference.  │
│ --json                               Output JSON                             │
│ --skip-code-evidence                 Skip code-reading evidence collection.  │
│ --skip-corpus                        Skip best-practice corpus loading.      │
│ --dry-run-evidence                   Print evidence summary and exit without │
│                                      running synthesis.                      │
│ --help                -h             Show this message and exit.             │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty charter validate

```
 Usage: spec-kitty charter validate [OPTIONS] {path}

 Validate project-layer doctrine artifacts against their schemas (FR-017).

 When *path* is a single file, validates that file.  When *path* is a
 directory, walks the tree for ``*.yaml`` files whose filename suffix
 matches a canonical artifact kind and validates each one.

 Exit code: ``0`` if every artifact validates; ``1`` if any artifact
 fails.  A per-file error report is printed for failures.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    path      <path>  Artifact YAML file or a directory containing          │
│                        project-layer doctrine artifacts (recurses into       │
│                        per-kind subdirectories).                             │
│                        [required]                                            │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty config

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

 Display project configuration and asset resolution information.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --show-origin                 Show where each resolved asset comes from      │
│                               (tier label + path)                            │
│ --mission      -m      <str>  Mission to resolve assets for                  │
│                               [default: software-dev]                        │
│ --help         -h             Show this message and exit.                    │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty consolidate

```
 Usage: spec-kitty consolidate [OPTIONS]

 Consolidate a lane-based mission into its target branch.

 Exit codes: 0 on success. 75 (error code COORD_MOVED_AFTER_LANDING) when the
 landing stands but the coordination or mission branch moved after it and was
 kept instead of deleted; for a coordination branch, --resume lands the late
 commits and finishes the teardown. Any other non-zero code is a refusal or
 failure.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --strategy                                <merge|squash|r  Strategy for the  │
│                                           ebase>           branch-integrati… │
│                                                            step (git merge   │
│                                                            of                │
│                                                            mission→target):  │
│                                                            merge | squash |  │
│                                                            rebase. Default:  │
│                                                            squash.           │
│ --delete-branch        --keep-branch                       Delete lane       │
│                                                            branches after    │
│                                                            merge. Unset (the │
│                                                            default) defers   │
│                                                            to the mission's  │
│                                                            meta.json         │
│                                                            retention policy  │
│                                                            (#3131), falling  │
│                                                            back to delete    │
│                                                            when no policy is │
│                                                            recorded. Passing │
│                                                            either flag       │
│                                                            explicitly always │
│                                                            wins over the     │
│                                                            mission's policy. │
│ --remove-worktree      --keep-worktree                     Remove lane       │
│                                                            worktrees after   │
│                                                            merge. Unset (the │
│                                                            default) defers   │
│                                                            to the mission's  │
│                                                            meta.json         │
│                                                            retention policy  │
│                                                            (#3131), falling  │
│                                                            back to remove    │
│                                                            when no policy is │
│                                                            recorded. Passing │
│                                                            either flag       │
│                                                            explicitly always │
│                                                            wins over the     │
│                                                            mission's policy. │
│ --push                                                     Publish to origin │
│                                                            after the local   │
│                                                            merge (the        │
│                                                            operator publish  │
│                                                            step; distinct    │
│                                                            from local lane   │
│                                                            consolidation)    │
│ --target                                  <str>            Target branch for │
│                                                            the               │
│                                                            branch-integrati… │
│                                                            step              │
│                                                            (auto-detected)   │
│ --dry-run                                                  Show what would   │
│                                                            be done without   │
│                                                            executing;        │
│                                                            refuses like the  │
│                                                            real run when the │
│                                                            mission branch is │
│                                                            missing           │
│ --json                                                     Output            │
│                                                            deterministic     │
│                                                            JSON (dry-run     │
│                                                            mode)             │
│ --mission                                 <str>            Mission slug when │
│                                                            merging from main │
│                                                            branch            │
│ --resume                                                   Resume an         │
│                                                            interrupted merge │
│                                                            from the last     │
│                                                            incomplete WP     │
│ --abort                                                    Abort an          │
│                                                            in-progress       │
│                                                            merge, cleaning   │
│                                                            up state and      │
│                                                            worktrees         │
│ --context                                 <str>            Unused            │
│                                                            compatibility     │
│                                                            flag              │
│ --keep-workspace                                           Unused            │
│                                                            compatibility     │
│                                                            flag              │
│ --allow-sparse-c…                                          Proceed even if   │
│                                                            legacy            │
│                                                            sparse-checkout   │
│                                                            state is          │
│                                                            detected. Use of  │
│                                                            this override is  │
│                                                            logged. Does not  │
│                                                            bypass the        │
│                                                            commit-time       │
│                                                            data-loss         │
│                                                            backstop.         │
│ --yes              -y                                      Proceed after     │
│                                                            merge warnings    │
│                                                            without prompts   │
│ --skip-review-ar…                                          Bypass the        │
│                                                            review-artifact   │
│                                                            consistency gate  │
│                                                            (the #2959 escape │
│                                                            hatch). Requires  │
│                                                            --note; the skip  │
│                                                            is recorded as    │
│                                                            durable override  │
│                                                            evidence in the   │
│                                                            status log, never │
│                                                            a silent bypass.  │
│ --note                                    <str>            Reason recorded   │
│                                                            as override       │
│                                                            evidence when     │
│                                                            using             │
│                                                            --skip-review-ar… │
│                                                            (required with    │
│                                                            it).              │
│ --skip-lanes,--n…                                          Complete a        │
│                                                            merge-ready       │
│                                                            direct-on-target  │
│                                                            mission that has  │
│                                                            no lane branch    │
│                                                            (#2745, FR-012):  │
│                                                            when lanes.json   │
│                                                            is genuinely      │
│                                                            absent,           │
│                                                            synthesize a      │
│                                                            no-lane manifest  │
│                                                            instead of        │
│                                                            hard-failing with │
│                                                            the missing-lanes │
│                                                            error. A mission  │
│                                                            that has real     │
│                                                            lanes is          │
│                                                            unaffected -- an  │
│                                                            existing          │
│                                                            lanes.json is     │
│                                                            always honored    │
│                                                            as-is. Does NOT   │
│                                                            bypass the        │
│                                                            merge-ready       │
│                                                            precondition: a   │
│                                                            not-merge-ready   │
│                                                            mission still     │
│                                                            refuses before    │
│                                                            any mutation.     │
│ --attest-cancele…                         <str>            Operator          │
│                                                            attestation       │
│                                                            (repeatable, one  │
│                                                            WP id each): the  │
│                                                            named canceled    │
│                                                            WP's content is   │
│                                                            absent or         │
│                                                            superseded,       │
│                                                            verified by hand. │
│                                                            Lifts, for that   │
│                                                            WP only, a REFUSE │
│                                                            whose attribution │
│                                                            evidence can      │
│                                                            never appear      │
│                                                            later (a mixed    │
│                                                            lane, or an       │
│                                                            unstamped         │
│                                                            canceled WP on a  │
│                                                            canceled          │
│                                                            dependency lane); │
│                                                            never lifts a     │
│                                                            FAIL. Requires    │
│                                                            --attest-reason;  │
│                                                            recorded durably  │
│                                                            in the status     │
│                                                            event log.        │
│ --attest-approve…                         <str>            Operator          │
│                                                            attestation       │
│                                                            (repeatable, one  │
│                                                            WP id each): the  │
│                                                            named approved    │
│                                                            work package,     │
│                                                            whose approval    │
│                                                            recorded no lane  │
│                                                            head, was         │
│                                                            reviewed as it    │
│                                                            stands on its     │
│                                                            lane. Requires    │
│                                                            --attest-reason.  │
│                                                            Does not lift a   │
│                                                            refusal for       │
│                                                            commits made      │
│                                                            after a recorded  │
│                                                            approval.         │
│ --attest-no-impl…                         <str>            Operator          │
│                                                            attestation       │
│                                                            (repeatable, one  │
│                                                            WP id each): the  │
│                                                            named approved    │
│                                                            work package owes │
│                                                            no implementation │
│                                                            (for example its  │
│                                                            deliverable       │
│                                                            already exists).  │
│                                                            Lifts             │
│                                                            IMPLEMENTATION_M… │
│                                                            for that work     │
│                                                            package only;     │
│                                                            never lifts       │
│                                                            REVIEW_NOT_INDEP… │
│                                                            and is never read │
│                                                            as a review.      │
│                                                            Requires          │
│                                                            --attest-reason;  │
│                                                            recorded durably  │
│                                                            in the status     │
│                                                            event log.        │
│ --attest-reason                           <str>            What you checked, │
│                                                            recorded with     │
│                                                            --attest-cancele… │
│                                                            --attest-approve… │
│                                                            or                │
│                                                            --attest-no-impl… │
│                                                            (required with    │
│                                                            each); one reason │
│                                                            serves every      │
│                                                            attestation of    │
│                                                            the run.          │
│ --release-branch                          <str>            With --abort      │
│                                                            (repeatable):     │
│                                                            keep this branch  │
│                                                            at its current    │
│                                                            commit instead of │
│                                                            refusing because  │
│                                                            it cannot be      │
│                                                            restored. The     │
│                                                            branch keeps all  │
│                                                            of its current    │
│                                                            commits,          │
│                                                            including this    │
│                                                            consolidation's   │
│                                                            unverified        │
│                                                            changes; review   │
│                                                            them afterwards.  │
│                                                            Only the record's │
│                                                            target, mission   │
│                                                            or coordination   │
│                                                            branch can be     │
│                                                            released.         │
│                                                            Requires          │
│                                                            --release-reason. │
│ --release-reason                          <str>            Why the released  │
│                                                            branches are      │
│                                                            kept, printed in  │
│                                                            the --abort       │
│                                                            report (required  │
│                                                            with              │
│                                                            --release-branch… │
│ --dependency-ref                          <str>            External          │
│                                                            dependency ref    │
│                                                            (repeatable) that │
│                                                            a work-package    │
│                                                            branch brought in │
│                                                            with (for example │
│                                                            `git merge        │
│                                                            --no-ff <dep>`),  │
│                                                            so its commits    │
│                                                            are attributed as │
│                                                            inherited history │
│                                                            instead of        │
│                                                            removed/canceled  │
│                                                            work (#6771).     │
│                                                            Verified          │
│                                                            fail-closed: the  │
│                                                            ref must resolve, │
│                                                            the mission       │
│                                                            branch must reach │
│                                                            it, and no commit │
│                                                            of any mission    │
│                                                            lane or mission   │
│                                                            branch may sit in │
│                                                            it. Without a     │
│                                                            declaration the   │
│                                                            closed-world      │
│                                                            check stays       │
│                                                            exactly as strict │
│                                                            as before.        │
│ --origin-check                            <function>       Origin freshness  │
│                                                            check before      │
│                                                            anything lands:   │
│                                                            enforce (the      │
│                                                            default) refuses  │
│                                                            when the remote's │
│                                                            status log or an  │
│                                                            approved lane     │
│                                                            branch of this    │
│                                                            Mission is ahead  │
│                                                            of this clone, or │
│                                                            the remote cannot │
│                                                            be reached; warn  │
│                                                            reports the same  │
│                                                            findings and      │
│                                                            continues; off    │
│                                                            contacts nothing  │
│                                                            and accepts stale │
│                                                            evidence.         │
│                                                            Overrides         │
│                                                            SPEC_KITTY_ORIGI… │
│ --retarget                                                 Adopt --target as │
│                                                            the mission's new │
│                                                            recorded target   │
│                                                            for this run, and │
│                                                            record it         │
│                                                            (meta.json        │
│                                                            target_branch +   │
│                                                            retarget_history) │
│                                                            before anything   │
│                                                            else moves.       │
│                                                            Requires          │
│                                                            --target;         │
│                                                            --target naming   │
│                                                            the recorded      │
│                                                            target is not a   │
│                                                            retarget. Not     │
│                                                            with --abort.     │
│ --retarget-reason                         <str>            Why the mission   │
│                                                            is retargeted,    │
│                                                            recorded in       │
│                                                            retarget_history  │
│                                                            with --retarget   │
│                                                            (requires         │
│                                                            --retarget).      │
│ --help             -h                                      Show this message │
│                                                            and exit.         │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty context

_Query workspace context information_

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

 Query workspace context information

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ info             Show context information for current or specified           │
│                  workspace.                                                  │
│ list             List all workspace contexts.                                │
│ cleanup          Clean up orphaned workspace contexts.                       │
│ mission-resolve  Resolve and persist a MissionContext token.                 │
│ mission-show     Show all fields of a persisted MissionContext token.        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty context cleanup

```
 Usage: spec-kitty context cleanup [OPTIONS]

 Clean up orphaned workspace contexts.

 Removes context files for workspaces that no longer exist.

 Examples:
     # Preview cleanup
     spec-kitty context cleanup --dry-run

     # Clean up orphaned contexts
     spec-kitty context cleanup

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --dry-run            Show what would be cleaned up without deleting          │
│ --help     -h        Show this message and exit.                             │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty context info

```
 Usage: spec-kitty context info [OPTIONS]

 Show context information for current or specified workspace.

 Examples:
 # Auto-detect from current directory (if inside worktree)
 spec-kitty context info

 # Explicit workspace
 spec-kitty context info --workspace 010-mission-lane-a

 # JSON output
 spec-kitty context info --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --workspace  -w      <str>  Workspace name (auto-detected if inside          │
│                             worktree)                                        │
│ --json                      Output in JSON format                            │
│ --help       -h             Show this message and exit.                      │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty context list

```
 Usage: spec-kitty context list [OPTIONS]

 List all workspace contexts.

 Examples:
 # List all contexts
 spec-kitty context list

 # List only orphaned contexts (worktree deleted)
 spec-kitty context list --orphaned

 # JSON output
 spec-kitty context list --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json                Output in JSON format                                  │
│ --orphaned            Show only orphaned contexts                            │
│ --help      -h        Show this message and exit.                            │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty context mission-resolve

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

 Resolve and persist a MissionContext token.

 Creates a new bound context for the given work package and mission,
 writes it to .kittify/runtime/contexts/, and prints the token.

 The token can be passed to other commands via --context <token>.

 Examples:
     # Resolve and print token for piping
     TOKEN=$(spec-kitty context mission-resolve --wp WP01 --mission
 057-my-mission)

     # Resolve and print full JSON
     spec-kitty context mission-resolve --wp WP01 --mission 057-my-mission
 --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --wp               <str>  Work package code (e.g., WP01) [required]       │
│    --mission          <str>  Mission slug (e.g., 057-mission-name)           │
│    --agent            <str>  Agent name (default: 'unknown')                 │
│    --json                    Output full JSON context (default: token only)  │
│    --help     -h             Show this message and exit.                     │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty context mission-show

```
 Usage: spec-kitty context mission-show [OPTIONS]

 Show all fields of a persisted MissionContext token.

 Loads the context file and pretty-prints its bound fields.

 Examples:
     spec-kitty context mission-show --context ctx-01HVXYZ...
     spec-kitty context mission-show --context ctx-01HVXYZ... --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --context          <str>  Context token (e.g., ctx-01HV...) [required]    │
│    --json                    Output raw JSON                                 │
│    --help     -h             Show this message and exit.                     │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty cutover-guard

_Diff-scoped fail-closed cut-over gate (pre-merge required check)._

```
 Usage: spec-kitty cutover-guard [OPTIONS]

 Diff-scoped fail-closed cut-over gate (pre-merge required check).

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --base-ref            <str>  Diff HEAD against the merge-base with this ref  │
│                              to discover touched kitty-specs/<mission> paths │
│                              (e.g. origin/main).                             │
│ --paths-from          PATH   Read already-known changed paths from this file │
│                              (one per line) instead of running git diff. Use │
│                              when the CI host already provides the diff      │
│                              (e.g. a PR file list).                          │
│ --json                       Emit the guard verdict as structured JSON.      │
│ --help        -h             Show this message and exit.                     │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty dispatch

_Dispatch a request to a governed Op (canonical surface)._

```
 Usage: spec-kitty dispatch [OPTIONS] {request}

 Dispatch a request to a governed Op (canonical surface).

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    request      <str>  Natural language request. The router picks the best │
│                          profile.                                            │
│                          [required]                                          │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --profile                 <str>   Optional profile ID. Bypasses the router — │
│                                   use when the request is ambiguous.         │
│ --json                            Output JSON payload                        │
│ --brief                           Emit routing and orientation metadata      │
│                                   only: replace the embedded governance text │
│                                   with its digest and the exact command that │
│                                   fetches it. Use after this session has     │
│                                   already read the full text for the         │
│                                   resolved profile and action.               │
│ --dry-run                         Route the request and return the routing   │
│                                   signal without opening an Op or writing    │
│                                   anything.                                  │
│ --owned-checkout          <path>  Keep this Op's record in an owned          │
│                                   checkout: a linked checkout of this        │
│                                   repository. Refuses the repository root    │
│                                   checkout, coordination worktrees and lane  │
│                                   worktrees. A record already in another     │
│                                   checkout is closed where it lives.         │
│ --help            -h              Show this message and exit.                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty docs

_Common Docs retrieval commands_

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

 Common Docs retrieval commands

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ query  Query the Common Docs retrieval index for pages matching TERM.        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty docs query

```
 Usage: spec-kitty docs query [OPTIONS] {term}

 Query the Common Docs retrieval index for pages matching TERM.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    term      <str>  Case-insensitive substring matched against title,      │
│                       anchor text/slug, and abstract.                        │
│                       [required]                                             │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json                       Emit machine-readable JSON via plain print (no  │
│                              Rich markup).                                   │
│ --divio-type          <str>  Restrict to pages of this Divio type            │
│                              (tutorial|how-to|reference|explanation|none).   │
│ --section             <str>  Restrict to pages containing an anchor with     │
│                              this slug.                                      │
│ --help        -h             Show this message and exit.                     │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor

_Project health diagnostics; a bare invocation runs the default check set_

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

 Project health diagnostics; a bare invocation runs the default check set

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ bytecode                Flag a corrupt installed-package .pyc before it      │
│                         bites (#4124, #4130).                                │
│ channel                 Report the active release channel (stable vs.        │
│                         prerelease-opt-in).                                  │
│ env-file                Report ``.kitty.env`` operator env-file health       │
│                         (presence/tier/ignore).                              │
│ event-logs              Preview, then prune, local run journals, event logs  │
│                         and caches past retention (#6610, #6739).            │
│ provenance              Flag committed absolute built-in-pack leaks and      │
│                         ambiguous template sources (C-PRV-5).                │
│ run-index               Flag absolute run_dir paths in the run index that    │
│                         break on copy/move (#5390).                          │
│ command-files           Check all agent command files for correctness.       │
│ skills                  Check command-skill manifest drift for Codex, Vibe,  │
│                         Pi, Letta, and Antigravity.                          │
│ tool-surfaces           Audit (and optionally repair) every configured tool  │
│                         surface.                                             │
│ state-roots             Show state roots, surface classification, and safety │
│                         warnings.                                            │
│ workspaces              Report .worktrees/ husk directories and worktrees    │
│                         whose work has landed.                               │
│ identity                Report mission-identity health across kitty-specs/.  │
│ topology                Report each mission's STORED topology across         │
│                         kitty-specs/.                                        │
│ mission-type            Report mission-type resolution health across         │
│                         kitty-specs/.                                        │
│ sparse-checkout         Detect and optionally remediate legacy               │
│                         sparse-checkout state.                               │
│ shim-registry           Check for overdue compatibility shims in the shim    │
│                         registry.                                            │
│ contracts               Validate the Contract Registry for well-formedness.  │
│ invocation-pairing      List orphan profile-invocation lifecycle records.    │
│ ops                     List orphan Op records; --close-stale closes stale   │
│                         Ops and lifecycle records as abandoned.              │
│ mission-state           Audit or repair mission-state shapes.                │
│ charter-packs           Check org charter pack snapshot status and list      │
│                         installed pack artifacts.                            │
│ coordination            Run the WP04 #1348 coordination + sparse-checkout    │
│                         health checks.                                       │
│ cutover                 Audit every mission's cut-over status outside CI     │
│                         (FR-007).                                            │
│ review-cycle-reconcile  Find review-cycle / arbiter-override records         │
│                         stranded under a retired                             │
│                         resolver path, ahead of WP13's consumer-unification  │
│                         (FR-008).                                            │
│ decisions               Diagnose or repair divergence between                │
│                         ``decisions/index.json`` and the                     │
│                         authoritative                                        │
│                         ``DecisionPointOpened``/``DecisionPointResolved``    │
│                         event log                                            │
│                         (#4919).                                             │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor bytecode

```
 Usage: spec-kitty doctor bytecode [OPTIONS]

 Flag a corrupt installed-package .pyc before it bites (#4124, #4130).

 Reads each .pyc under the installed specify_cli package and flags one
 whose header Python's import machinery would trust (so it would be
 used as-is) but whose body fails to unmarshal into a code object --
 the truncated-write shape that crashed a training machine in #4124.
 A cache Python would already recompile from source (bad magic, stale
 timestamp/size) is not flagged; it never bites. Read-only -- never
 deletes anything.

 Examples:
     spec-kitty doctor bytecode
     spec-kitty doctor bytecode --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Machine-readable JSON output                               │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor channel

```
 Usage: spec-kitty doctor channel [OPTIONS]

 Report the active release channel (stable vs. prerelease-opt-in).

 Reads SPEC_KITTY_PRERELEASE (default OFF — stable channel). Never
 mutates state.

 Examples:
     spec-kitty doctor channel
     spec-kitty doctor channel --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Machine-readable JSON output                               │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor charter-packs

```
 Usage: spec-kitty doctor charter-packs [OPTIONS]

 Check org charter pack snapshot status and list installed pack artifacts.

 Exit code reflects health (WP01, operator directive: loud over hidden): the
 command exits **1 when the report is unhealthy** and 0 only when healthy
 (``report.healthy`` drives the code on every output path). A clear RC=1 with
 a surfaced error is preferred over an RC=0 that hides a defect.  It
 enumerates each configured org pack (from ``.kittify/config.yaml``), prints
 its on-disk version (``git describe`` for git-managed packs, otherwise the
 ``pack-manifest.yaml`` ``pack_version``), per-artifact YAML counts, and
 ``org-charter.yaml`` policy status when present.

 Override governance (FR-010 / FR-012): when org packs are configured, any
 ``org:``-provenance override of a built-in DRG node that is NOT sanctioned
 by ``.kittify/charter-packs/replaceable-builtins.yaml`` or by the overriding
 pack's own pack-root ``replaceable-builtins.yaml`` is reported as an
 ``unsanctioned_overrides`` finding and flips the report unhealthy (RC=1).
 A pack sanction applies only to overrides that same pack contributes, and
 the consumer file can withdraw it with ``revoked_pack_sanctions``. Sanctioned
 overrides and their source are listed as ``sanctioned_overrides``.
 Project-tier (``.kittify/charter-packs/``) overrides of built-ins are
 intentionally **ungoverned** — the project layer is the trusted operator tier
 and is not gated by the consumer-facing allowlist; only org-tier overrides
 are adjudicated.

 Examples:
     spec-kitty doctor charter-packs
     spec-kitty doctor charter-packs --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Machine-readable JSON output                               │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor command-files

```
 Usage: spec-kitty doctor command-files [OPTIONS]

 Check all agent command files for correctness.

 Verifies that every configured agent has the correct command files:
 - Full rendered prompts for prompt-driven commands (specify, plan, tasks, ...)
 - Thin shims for CLI-driven commands (implement, review, merge, ...)
 - Current version markers on all files

 Examples:
     spec-kitty doctor command-files
     spec-kitty doctor command-files --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Machine-readable JSON output                               │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor contracts

```
 Usage: spec-kitty doctor contracts [OPTIONS]

 Validate the Contract Registry for well-formedness.

 Reads docs/contracts/contract-registry.yaml and validates every record
 against the schema: required fields present, kind/status/enforcement in
 range, semver + tracker refs well-formed, anchors resolve, and — the DIR-041
 self-consistency gate (NFR-003) — NO positional file:line anchoring anywhere.
 Structural validation is the only enforcing gate in v1; the retirement
 absence-sweep is advisory.

 Exit codes:
   0  Registry is well-formed (or empty).
   2  Configuration error (registry file missing) or a schema violation.

 Examples:
     spec-kitty doctor contracts
     spec-kitty doctor contracts --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Machine-readable JSON output                               │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor coordination

```
 Usage: spec-kitty doctor coordination [OPTIONS]

 Run the WP04 #1348 coordination + sparse-checkout health checks.

 Iterates over every mission under ``kitty-specs/`` whose ``meta.json``
 declares a ``coordination_branch`` field, runs the coord-worktree
 and lane-sparse-checkout health checks, and prints findings.

 Also runs the minimum git-version (RR-01) check.

 Exits with code 1 if any ``error`` finding is emitted; ``warning``
 findings exit 0 but are still printed.

 With ``--fix``, automatically materializes a missing coordination worktree
 whose declared branch still exists in git (#5113 / FR-014, via the
 canonical ``materialize_coord_surface_for_write`` helper — idempotent, and
 it refuses rather than crashing when this clone holds no ref for the branch),
 flattens
 missions that have a stale ``coordination_branch`` key (branch never
 created or already deleted), re-derives topology, and attempts the Gap-1
 coord-vs-target fast-forward (FR-009) -- which fails loud with a unified
 diff and mutates nothing when
 the coord branch has diverged or its worktree is dirty, and refuses
 without mutating when the coord worktree is on another branch, detached,
 or not a worktree of this repository. ``Fast-forwarded`` is printed only
 once the coord branch really matches the target. Safe to run on
 100%-done missions before ``spec-kitty next`` or ``spec-kitty consolidate``.

 With ``--check-staleness``, also reports Gap-1 coord-branch-vs-target
 staleness (FR-008) — non-blocking either way.

 With ``--mission <handle>``, scopes every per-mission check, the
 stranded-revert markers and every ``--fix`` repair to the single mission the
 shared resolver maps the handle to (a Mission only its Mission branch carries
 is found too). An unresolvable / ambiguous handle fails closed with exit 1.

 ``--fix`` repairs only the Missions you name: pass ``--mission <handle>``, or
 ``--all-missions`` for every Mission. Without either it refuses and changes
 nothing.

 Examples:
     spec-kitty doctor coordination
     spec-kitty doctor coordination --fix --mission 083-my-mission
     spec-kitty doctor coordination --fix --all-missions
     spec-kitty doctor coordination --json
     spec-kitty doctor coordination --check-staleness
     spec-kitty doctor coordination --mission 083-my-mission

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --fix                             Repair coordination topology: materialize  │
│                                   a missing coordination worktree whose      │
│                                   branch exists, remove stale                │
│                                   `coordination_branch` keys for             │
│                                   never-created branches (then `migrate      │
│                                   backfill-topology`), and revert stranded   │
│                                   coordination state.                        │
│ --json                            Machine-readable JSON output               │
│ --check-staleness                 Also report coord-branch-vs-target-branch  │
│                                   staleness (Gap-1, FR-008): non-blocking,   │
│                                   whether the coord branch is behind or has  │
│                                   diverged from its mission's target_branch. │
│ --mission                  <str>  Scope the checks to a single mission       │
│                                   handle (mission_id / mid8 / slug),         │
│                                   resolved via the same resolver as `doctor  │
│                                   mission-state`.                            │
│ --all-missions                    With --fix, repair every Mission in the    │
│                                   repository. Without it, --fix needs        │
│                                   --mission.                                 │
│ --help             -h             Show this message and exit.                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor cutover

```
 Usage: spec-kitty doctor cutover [OPTIONS]

 Audit every mission's cut-over status outside CI (FR-007).

 Backed by ``migration.runtime_state_cutover.cutover_repo(dry_run=True)``:
 the same fail-closed seed-then-verify spine the birth-cutover migration
 uses, read-only and writing nothing. Reports each mission slug, whether
 it is cut over, and a reason when it is not.

 Informational only: always exits 0 with a summary count.

 Examples:
     spec-kitty doctor cutover
     spec-kitty doctor cutover --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Machine-readable JSON output                               │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor decisions

```
 Usage: spec-kitty doctor decisions [OPTIONS]

 Diagnose or repair divergence between ``decisions/index.json`` and the
 authoritative ``DecisionPointOpened``/``DecisionPointResolved`` event log
 (#4919).

 Diagnose (default): read-only; reports decisions present in the event
 log but missing from the index, index entries with no backing event, a
 decision_id whose event group cannot be folded at all (e.g. two openings
 whose payloads differ beyond the moment each was recorded), and an index
 entry whose status disagrees with the folded log (a stale entry). A log
 line that cannot be read (invalid JSON, a non-object row or payload, or a
 missing or non-string decision point id) is never a crash: it is named,
 with its line number and reason, in the human report and under the
 ``unreadable_lines`` key of ``--json`` (always present, empty when every
 line reads). Always exits 0 (report only).

 It additionally prints an INFORMATIONAL finding naming each decision whose
 event log holds several ``DecisionPointOpened`` rows that are equal apart
 from the moment each was recorded -- the duplicate rows an interrupted or
 concurrent open left behind before #4848. The fold tolerates them and keeps
 the earliest; the log is left unchanged, and the finding never affects the
 exit code or the clean verdict. ``--json`` carries the same list as
 ``duplicate_openings_tolerated`` (always present, empty when there is
 nothing to report).

 ``--repair``: rebuilds ``index.json`` from the log via the single
 canonical ``event -> IndexEntry`` fold
 (:mod:`specify_cli.decisions.index_fold`) under the same sidecar lock the
 write path uses — never invents an entry absent from the log, never
 drops a log-backed entry. It refuses to rebuild at all while the log has
 an unreadable line (a rebuild would silently drop every decision whose
 events sit on that line): it writes nothing, reports the line(s), and
 exits **1**; fix or remove the line, then re-run. A no-op (no write)
 when the log and index already agree. The fold is order-independent: a
 decision's documented
 ``open -> defer -> resolve`` flow emits a ``deferred``-outcome event and
 a later ``resolved``-outcome event, and folds to ``resolved`` regardless
 of which one the (git-merge-driver-resorted) log lists first (#4919).
 When a decision cannot be reconciled, ``--repair`` leaves it unchanged
 (never drops it), names it in the report, and the command then exits
 **1**. It exits 0 only when every decision the repair touched
 folds cleanly and no log line was unreadable.

 Run ``--repair`` as an offline maintenance step, not concurrently with
 live decision traffic: a decision that is mid-open (its index entry
 written under the sidecar lock, its event not yet appended) is briefly
 invisible to a log-authoritative rebuild, so a repair racing that window
 can drop the in-flight entry (a later ``--repair`` heals it). Like
 ``fsck``, it is meant to run when writers are quiesced.

 Examples:
     spec-kitty doctor decisions --mission my-mission-01ABCD
     spec-kitty doctor decisions --mission my-mission-01ABCD --repair
     spec-kitty doctor decisions --mission my-mission-01ABCD --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission          <str>  Mission handle (mission_id / mid8 / slug)       │
│                              [required]                                      │
│    --json                    Machine-readable JSON output                    │
│    --repair                  Rebuild decisions/index.json from the event log │
│                              (run offline; not against live decision         │
│                              traffic)                                        │
│    --help     -h             Show this message and exit.                     │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor env-file

```
 Usage: spec-kitty doctor env-file [OPTIONS]

 Report ``.kitty.env`` operator env-file health (presence/tier/ignore).

 Reads the repo- and home-tier ``.kitty.env`` files and the
 config.yaml ``env_file`` pointer, and reports which governed vars
 are set and from which tier -- names/presence only for anything not
 on the printable-var allowlist (C-SEC-1), values never leaked.
 Read-only -- never mutates state.

 Examples:
     spec-kitty doctor env-file
     spec-kitty doctor env-file --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Machine-readable JSON output                               │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor event-logs

```
 Usage: spec-kitty doctor event-logs [OPTIONS]

 Preview, then prune, local run journals, event logs and caches past retention
 (#6610, #6739).

 Reads ledger.retention (keep_runs, max_age_days) from .kittify/config.yaml;
 an item is removed only when it is outside the newest keep_runs of its kind
 AND older than max_age_days, and its work is over: a run once its Mission
 is merged or the run finished, a glossary log once its Mission is
 completed, an Op-scoped log (profile-invocation-<id>) once its Op is
 completed. A run that names no Mission is judged on age alone, and so is an
 Op-scoped log whose Op has no record here. Rebuildable caches are
 candidates whatever their age, unless locked. Committed ledgers, Op records
 and the Op index, lock files, an open Op's log, items of an open Mission, an
 item whose recorded Mission this checkout cannot find, and locked items are
 never removed.

 Without --apply nothing changes. Exit codes: 0 preview or clean apply,
 1 a deletion failed, 2 config, usage or internal error.

 Examples:
     spec-kitty doctor event-logs
     spec-kitty doctor event-logs --json
     spec-kitty doctor event-logs --apply

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --apply            Delete the listed candidates (default: preview only)      │
│ --json             Machine-readable JSON output                              │
│ --help   -h        Show this message and exit.                               │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor identity

```
 Usage: spec-kitty doctor identity [OPTIONS]

 Report mission-identity health across kitty-specs/.

 Classifies every mission into one of four states (FR-045), and every
 kitty-specs/ folder that is not a Mission as residue (#5875):

 \b
 - assigned: mission_id present AND mission_number non-null (fully migrated)
 - pending:  mission_id present AND mission_number null (pre-merge)
 - legacy:   mission_id missing AND mission_number present (needs backfill)
 - orphan:   both fields missing or meta.json unreadable (needs triage)
 - residue:  not a Mission; selection does not list it (see below)

 A folder is residue when it has no meta.json; or, in a git repository,
 when git tracks neither its meta.json nor its spec.md and the meta.json
 has no mission_id or cannot be read. Each residue row names its reason
 (no_meta, untracked_idless_meta, corrupt_meta) and the remedy for it; a
 corrupt meta.json is reported as corrupt, never as a folder to delete.
 A git index that cannot be read exits 1 with one error line
 (GIT_INDEX_UNREADABLE under --json).

 Also reports duplicate numeric prefixes (FR-011) and ambiguous selectors
 that would resolve to multiple missions (FR-012); residue is in neither.

 Examples:
     spec-kitty doctor identity
     spec-kitty doctor identity --json
     spec-kitty doctor identity --mission 083-foo
     spec-kitty doctor identity --fail-on legacy,orphan

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json                    Emit structured JSON output (suitable for CI)      │
│ --mission          <str>  Scope report to a single mission slug              │
│ --fail-on          <str>  Exit non-zero if any mission is in the given       │
│                           state(s). Comma-separated list of: assigned,       │
│                           pending, legacy, orphan, residue.                  │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor invocation-pairing

```
 Usage: spec-kitty doctor invocation-pairing [OPTIONS]

 List orphan profile-invocation lifecycle records.

 WP05 (#843) wiring: scans the lifecycle records (``kitty-ops/lifecycle/``)
 for ``started`` records with no paired completion (``completed``,
 ``failed`` or ``abandoned``). Mid-cycle agent crashes show up here. The
 check observes; ``doctor ops --close-stale`` closes stale ones (#7346).

 Exit codes:
   0  No orphans observed.
   1  At least one orphan found.

 Examples:
     spec-kitty doctor invocation-pairing
     spec-kitty doctor invocation-pairing --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Machine-readable JSON output                               │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor mission-state

```
 Usage: spec-kitty doctor mission-state [OPTIONS]

 Audit or repair mission-state shapes.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --audit                             Run mission-state audit (required to     │
│                                     proceed)                                 │
│ --fix                               Repair mission-state artifacts in place  │
│                                     and write a migration manifest           │
│ --json                              Emit JSON report to stdout               │
│ --mission                   <str>   Scope to a single mission handle         │
│ --fail-on                   <str>   Exit 1 if findings meet a gate           │
│                                     (error|warning|info|teamspace-blocker)   │
│ --fixture-dir               <path>  Override scan root (for testing)         │
│ --include-fixtures                  Audit the bundled mission-state survey   │
│                                     fixtures                                 │
│ --manifest-path             <path>  Path for --fix migration manifest        │
│ --allow-dirty                       Allow --fix when relevant git paths are  │
│                                     already dirty                            │
│ --help              -h              Show this message and exit.              │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor mission-type

```
 Usage: spec-kitty doctor mission-type [OPTIONS]

 Report mission-type resolution health across kitty-specs/.

 Classifies every mission into one of six states (FR-008):

 \b
 - resolved: mission_type present, activated, and loadable
 - activated-unresolvable: activated but has no loadable profile on disk
 - unknown: mission_type present but not activated/registered anywhere
 - typeless: no mission_type key (or a blank/null/non-string value)
 - legacy-key-only: only the retired `mission` key is present
 - error: meta.json unreadable or malformed

 Examples:
     spec-kitty doctor mission-type
     spec-kitty doctor mission-type --json
     spec-kitty doctor mission-type --mission 083-foo
     spec-kitty doctor mission-type --fail-on unknown,activated-unresolvable

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json                    Emit structured JSON output (suitable for CI)      │
│ --mission          <str>  Scope report to a single mission slug              │
│ --fail-on          <str>  Exit non-zero if any mission is in the given       │
│                           state(s). Comma-separated list of: resolved,       │
│                           activated-unresolvable, unknown, typeless,         │
│                           legacy-key-only, error.                            │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor ops

```
 Usage: spec-kitty doctor ops [OPTIONS]

 List orphan Op records; --close-stale closes stale Ops and lifecycle records
 as abandoned.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json                          Machine-readable JSON output                 │
│ --close-stale                   Close open Ops and work-package lifecycle    │
│                                 records older than --threshold as abandoned  │
│                                 (closed_by=doctor_sweep)                     │
│ --threshold            <float>  Staleness threshold in hours (default 24; 0  │
│                                 closes all). Requires --close-stale.         │
│ --help         -h               Show this message and exit.                  │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor provenance

```
 Usage: spec-kitty doctor provenance [OPTIONS]

 Flag committed absolute built-in-pack leaks and ambiguous template sources
 (C-PRV-5).

 Scans .kittify/charter/charter.yaml's catalog and
 .kittify/agent_profiles_manifest.json for source_path values that
 should be portable pack tokens. Read-only -- never mutates state;
 ambiguous former-checkout paths are reported without a heal hint.

 Examples:
     spec-kitty doctor provenance
     spec-kitty doctor provenance --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Machine-readable JSON output                               │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor review-cycle-reconcile

```
 Usage: spec-kitty doctor review-cycle-reconcile [OPTIONS]

 Find review-cycle / arbiter-override records stranded under a retired resolver
 path, ahead of WP13's consumer-unification (FR-008).

 Every retired resolver comes from WP08's reviewed retirement set, not a
 guessed set. Reports two DISTINCT stranded classes per finding: a
 deleted-coordination-branch mission (absorbed to PRIMARY, the measured
 45-mission corpus) and a live-coordination-branch mission still carrying a
 pre-ADR PRIMARY record. Never a bare count — every finding names its
 mission, WP, retired resolver, and resolved directory.

 Informational only: always exits 0. No ``--fix`` — a stranded record may
 have a legitimate divergent sibling, and this command does not pick a
 winner.

 Examples:
     spec-kitty doctor review-cycle-reconcile
     spec-kitty doctor review-cycle-reconcile --mission my-mission-01ABCD
     spec-kitty doctor review-cycle-reconcile --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission          <str>  Scope to a single mission (mission_id / mid8 /     │
│                           slug)                                              │
│ --json                    Machine-readable JSON output                       │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor run-index

```
 Usage: spec-kitty doctor run-index [OPTIONS]

 Flag absolute run_dir paths in the run index that break on copy/move (#5390).

 Scans .kittify/runtime/feature-runs.json for run_dir values stored as
 absolute paths (nonportable — a copied or moved project resolves the
 original folder's cursor). Read-only; heal with ``spec-kitty migrate``.

 Examples:
     spec-kitty doctor run-index
     spec-kitty doctor run-index --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Machine-readable JSON output                               │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor shim-registry

```
 Usage: spec-kitty doctor shim-registry [OPTIONS]

 Check for overdue compatibility shims in the shim registry.

 Reads docs/migrations/shim-registry.yaml and compares each entry's
 removal_target_release against the current project version. Fails with
 exit code 1 if any shim is overdue (removal release has shipped but
 shim file still exists on disk).

 Exit codes:
   0  All entries are pending, removed, or grandfathered.
   1  At least one entry is overdue — shim must be deleted or window extended.
   2  Configuration error (registry file or pyproject.toml missing/invalid).

 Examples:
     spec-kitty doctor shim-registry
     spec-kitty doctor shim-registry --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Machine-readable JSON output                               │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor skills

```
 Usage: spec-kitty doctor skills [OPTIONS]

 Check command-skill manifest drift for Codex, Vibe, Pi, Letta, and
 Antigravity.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --fix             Repair missing command-skill files                         │
│ --json            Machine-readable JSON output                               │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor sparse-checkout

```
 Usage: spec-kitty doctor sparse-checkout [OPTIONS]

 Detect and optionally remediate legacy sparse-checkout state.

 Without ``--fix``: scans the repo and prints a warning finding
 describing any active sparse-checkout state (primary + lane
 worktrees). Exits 0 when clean, 1 when state is present.

 With ``--fix``: in an interactive TTY, prints a step-by-step plan,
 prompts once for consent, and calls WP03's ``remediate()``. In
 non-interactive / CI environments, prints a remediation pointer and
 exits non-zero without mutating state (FR-023).

 Examples:
     spec-kitty doctor sparse-checkout
     spec-kitty doctor sparse-checkout --fix

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --fix             Apply remediation (disable sparse-checkout on primary +    │
│                   worktrees).                                                │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor state-roots

```
 Usage: spec-kitty doctor state-roots [OPTIONS]

 Show state roots, surface classification, and safety warnings.

 Displays the three state roots with resolved paths, all registered
 state surfaces grouped by root with authority and Git classification,
 and warnings for any runtime surfaces not covered by .gitignore.

 Examples:
     spec-kitty doctor state-roots
     spec-kitty doctor state-roots --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Machine-readable JSON output                               │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor tool-surfaces

```
 Usage: spec-kitty doctor tool-surfaces [OPTIONS]

 Audit (and optionally repair) every configured tool surface.

 Examples:
 spec-kitty doctor tool-surfaces --json
 spec-kitty doctor tool-surfaces --kind command-skill --json
 spec-kitty doctor tool-surfaces --tool codex --fix

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --kind          <str>  Filter to surface kind(s), e.g. command-skill         │
│ --tool          <str>  Filter to a single configured tool key                │
│ --fix                  Repair missing or stale surfaces                      │
│ --json                 Machine-readable JSON output                          │
│ --help  -h             Show this message and exit.                           │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor topology

```
 Usage: spec-kitty doctor topology [OPTIONS]

 Report each mission's STORED topology across kitty-specs/.

 Reads the authoritative ``topology`` value persisted in ``meta.json`` WITHOUT
 re-inferring from disk/git. Missions not yet backfilled surface
 ``topology: null`` — run ``spec-kitty migrate backfill-topology`` to persist
 the computed value.

 Lists Missions only: a ``kitty-specs/`` folder that Mission selection does
 not list (residue) is not a row. ``spec-kitty doctor identity`` reports such
 a folder with its reason and a remedy.

 Examples:
     spec-kitty doctor topology
     spec-kitty doctor topology --json
     spec-kitty doctor topology --mission 083-foo

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json                    Emit structured JSON output (suitable for CI)      │
│ --mission          <str>  Scope report to a single mission slug              │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty doctor workspaces

```
 Usage: spec-kitty doctor workspaces [OPTIONS]

 Report .worktrees/ husk directories and worktrees whose work has landed.

 A husk is not a usable git worktree: git commands run inside it fall
 through to the primary repository (#1833). Workspace resolution refuses
 husks with a structured error; this check is the recovery path.

 After the husk report, every registered worktree gets a verdict: landed
 (its commits are on the local <remote>/<primary> and nothing uncommitted or
 running is in it), not landed, unproven, or Mission-owned (#7173). The
 proving remote is `origin` unless `--remote` names another (#7214).

 With --prune, a commit that only the worktree HEAD reflog or the branch
 reflog still reached is recorded under
 refs/spec-kitty/discarded/reflog/<sha> before anything is removed (#7211),
 and printed as a `reflog-only commit kept at` line; --json names the refs
 in each pruned entry's kept_commits key.

 Examples:
     spec-kitty doctor workspaces
     spec-kitty doctor workspaces --fix
     spec-kitty doctor workspaces --prune
     spec-kitty doctor workspaces --prune --remote upstream
     spec-kitty doctor workspaces --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --fix                    Remove husks that are NOT registered in `git        │
│                          worktree list` (registered worktrees are never      │
│                          removed)                                            │
│ --prune                  Remove only worktrees proven landed into the local  │
│                          <remote>/<primary> (nothing is fetched: run `git    │
│                          fetch` first to see recent merges), then their      │
│                          branches. Never uses --force; prints a recreate     │
│                          command for each removal. Mission worktrees are     │
│                          only reported. Untracked ignored files (e.g.        │
│                          .venv/, .env) are deleted with the worktree.        │
│                          Removal is Linux only (it needs /proc to prove      │
│                          nothing runs in a worktree).                        │
│ --remote          <str>  The remote whose tracking refs prove a landing      │
│                          (default: origin). In a fork clone whose canonical  │
│                          repository is `upstream`, pass `--remote upstream`  │
│                          after fetching it, or every landing worktree        │
│                          reports not_landed (#7214). Nothing is fetched      │
│                          either way.                                         │
│                          [default: origin]                                   │
│ --json                   Machine-readable JSON output                        │
│ --help    -h             Show this message and exit.                         │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty events

_Event log tailing commands_

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

 Event log tailing commands

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ tail  Tail one of the mission's canonical event logs as lines on stdout.     │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty events tail

```
 Usage: spec-kitty events tail [OPTIONS]

 Tail one of the mission's canonical event logs as lines on stdout.

 Default output is one human-readable line per event; ``--json`` opts into
 the machine envelope (``docs query --json`` precedent, #6611).

 Ordered dispatch (plan.md's CLI Surface section -- "exactly four things, none
 of
 them novel domain logic"):

 1. FR-004 usage check: ``--from-invariant`` without ``--from-offset``.
 2. FR-009 mission resolve, then ``--log`` kind dispatch (Typer already
    rejected unknown kinds with a usage error before any file access).
 3. FR-013 resume validation against the SELECTED log (only when
    ``--from-offset`` is given).
 4. Drive the core.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission                 <str>                   Mission slug/handle     │
│                                                      whose event log to tail │
│                                                      (no legacy              │
│                                                      feature-alias flag,     │
│                                                      C-003).                 │
│                                                      [required]              │
│    --log                     <status|decisions|miss  Which canonical ledger  │
│                              ion|run|glossary|ops|c  to tail: status         │
│                              anonical>               (default,               │
│                                                      status.events.jsonl),   │
│                                                      decisions, mission, run │
│                                                      (the mission's latest   │
│                                                      run journal), glossary, │
│                                                      ops, or canonical.      │
│                                                      [default: status]       │
│    --json                                            Emit one JSON line per  │
│                                                      event (byte-identical   │
│                                                      to the pre-#6611        │
│                                                      output, cursor keys     │
│                                                      included). Default: one │
│                                                      human-readable          │
│                                                      plain-text line per     │
│                                                      event.                  │
│    --once                                            Poll exactly once and   │
│                                                      exit -- no generator,   │
│                                                      no sleep, ever.         │
│    --max-events              <int>                   Stop the stream after   │
│                                                      emitting this many      │
│                                                      events/signals.         │
│    --from-offset             <int>                   Resume from this byte   │
│                                                      offset in the selected  │
│                                                      log (FR-004/FR-013).    │
│    --from-invariant          <str>                   Content invariant       │
│                                                      (SHA-256 hex digest)    │
│                                                      paired with             │
│                                                      --from-offset for       │
│                                                      cross-restart content   │
│                                                      verification            │
│                                                      (FR-004/FR-013).        │
│                                                      Requires --from-offset; │
│                                                      supplying this alone is │
│                                                      a usage error.          │
│    --help            -h                              Show this message and   │
│                                                      exit.                   │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty glossary

_Glossary management commands_

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

 Glossary management commands

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ list       List all terms in glossary.                                       │
│ conflicts  Display conflict history from event log.                          │
│ resolve    Resolve a conflict asynchronously.                                │
│ show       Render the entity page for a glossary term.                       │
│ validate   Validate glossary seed file(s) against the schema.                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty glossary conflicts

```
 Usage: spec-kitty glossary conflicts [OPTIONS]

 Display conflict history from event log.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission             <str>  Filter conflicts by mission ID                  │
│ --unresolved                 Show only unresolved conflicts                  │
│ --strictness          <str>  Filter by effective strictness level (off,      │
│                              medium, max)                                    │
│ --json                       Output as JSON (machine-parseable)              │
│ --help        -h             Show this message and exit.                     │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty glossary list

```
 Usage: spec-kitty glossary list [OPTIONS]

 List all terms in glossary.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --scope           <str>  Filter by scope (mission_local, team_domain,        │
│                          audience_domain, spec_kitty_core)                   │
│ --status          <str>  Filter by status (active, deprecated, draft)        │
│ --json                   Output as JSON (machine-parseable)                  │
│ --help    -h             Show this message and exit.                         │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty glossary resolve

```
 Usage: spec-kitty glossary resolve [OPTIONS] {conflict_id}

 Resolve a conflict asynchronously.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    conflict_id      <str>  Conflict ID to resolve [required]               │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission          <str>  Mission ID for event log (auto-detected if         │
│                           omitted)                                           │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty glossary show

```
 Usage: spec-kitty glossary show [OPTIONS] {term}

 Render the entity page for a glossary term.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    term      <str>  Term surface name or glossary URN (e.g.                │
│                       'deployment-target' or 'glossary:deployment-target')   │
│                       [required]                                             │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty glossary validate

```
 Usage: spec-kitty glossary validate [OPTIONS] {path}

 Validate glossary seed file(s) against the schema.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    path      <path>  Path to a glossary seed file (.yaml) or directory of  │
│                        seed files                                            │
│                        [required]                                            │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Output validation results as JSON                          │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty implement

```
 Usage: spec-kitty implement [OPTIONS] {wp_id}

 Internal — allocate or reuse the lane worktree for a work package.

 This command is internal infrastructure, used by ``spec-kitty agent action
 implement``
 for workspace creation. It is not the canonical user-facing implementation
 path for
 spec-kitty 3.1.1.

 Canonical user workflow::

   spec-kitty next --agent <name> --mission <slug>   (loop entry)
   spec-kitty agent action implement <WP> --agent <name>  (per-WP verb)

 This command remains available as a compatibility surface for direct callers.
 See FR-503 and D-4 in the 3.1.1 spec.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    wp_id      <str>  Work package ID (for example, WP01) [required]        │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission                                      <str>  Mission handle: its    │
│                                                       slug, its human slug   │
│                                                       (the slug without the  │
│                                                       -<mid8> suffix), the   │
│                                                       mid8, or the full      │
│                                                       mission id.            │
│ --auto-commit              --no-auto-commit           Auto-commit status and │
│                                                       planning changes       │
│                                                       (default: from project │
│                                                       config)                │
│ --json                                                Output in JSON format  │
│ --recover                                             Recover from crashed   │
│                                                       implementation session │
│ --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.           │
│ --acknowledge-not-bu…                                 Suppress the bulk-edit │
│                                                       inference warning when │
│                                                       spec language          │
│                                                       resembles a bulk edit  │
│                                                       but the mission is not │
│                                                       one.                   │
│ --help                 -h                             Show this message and  │
│                                                       exit.                  │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty init

```
 Usage: spec-kitty init [OPTIONS] [project_name]

 Initialize a new Spec Kitty project.

 Creates project files. Never initializes a git repository. When the
 directory is the top of an existing git repository with at least one commit,
 init commits the files it wrote in one commit and leaves files that were
 already uncommitted alone; pass --no-commit to skip that commit.

 If PROJECT_NAME is omitted, init runs in the current directory.
 Re-running init in an already-initialized directory is idempotent for project
 state: it verifies the configured agents' skill surfaces, additively restoring
 missing per-agent skill roots (e.g. .claude/skills/) through the canonical
 installer, and exits 1 with the recovery command
 `spec-kitty agent config sync --create-missing --keep-orphaned` when shared
 command skills (codex/vibe/pi/letta) are missing or empty. An existing
 per-agent skill file that is empty, a directory, or a symlink exits 1 naming
 its path and is preserved untouched — rename or remove it and re-run init.

 Note: The --no-git flag from previous versions has been removed.
       init never runs `git init`.

 Interactive Mode (default):
 - Prompts you to select AI assistants

 Non-Interactive Mode:
 - Enabled with --non-interactive/--yes, SPEC_KITTY_NON_INTERACTIVE=1, or
 non-TTY
 - Skips all prompts; --ai is required
 - Perfect for CI/CD and automation

 What Gets Created:
 - .kittify/ - Project scaffold (memory, config)
 - Agent command and skill surfaces (.claude/commands/, .agents/skills/, etc.)
 - .gitignore and .claudeignore

 Specifying AI Assistants (--ai flag):
 Use comma-separated agent keys (no spaces). Valid keys include:
 codex, claude, gemini, cursor, qwen, opencode, windsurf, kilocode,
 auggie, copilot, q, kiro, antigravity, vibe, pi, letta, llxprt.

 Template Discovery (Development Mode):
 Set SPEC_KITTY_TEMPLATE_ROOT to override bundled templates for local
 development.

 Examples:
   spec-kitty init --ai codex                    # Current directory (default)
   spec-kitty init my-project                    # Interactive mode
   spec-kitty init my-project --ai codex         # With Codex
   spec-kitty init my-project --ai codex,claude  # Multiple agents
   spec-kitty init --ai claude --non-interactive # Non-interactive

 Canonical Next Steps (after init):
   spec-kitty next --agent <agent> --mission <slug>         # Enter mission
 loop
   spec-kitty agent action implement <WP> --agent <name>   # Implement a work
 package
   spec-kitty agent action review    <WP> --agent <name>   # Review a work
 package

 Missions:
 - Missions are selected per-feature during /spec-kitty.specify

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│   project_name      <str>  Name for your new project directory (omit to      │
│                            initialize current directory)                     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --non-interactive,--yes            Run without interactive prompts (suitable │
│                                    for CI/CD)                                │
│ --no-commit                        Do not commit the files init writes (by   │
│                                    default, inside a git repository init     │
│                                    commits them in one commit)               │
│ --help                   -h        Show this message and exit.               │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Selection ──────────────────────────────────────────────────────────────────╮
│ --ai        <str>  Comma-separated AI assistants (claude,codex,gemini,...)   │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty intake

```
 Usage: spec-kitty intake [OPTIONS] [path]

 Ingest a plan document as a mission brief for /spec-kitty.specify.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│   path      <str>  Path to plan document, or '-' to read from stdin. Omit    │
│                    when using --show, --auto or --clear.                     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --force            Overwrite existing brief.                                 │
│ --show             Print current brief and provenance; no writes.            │
│ --auto             Scan known harness plan locations and ingest              │
│                    automatically.                                            │
│ --clear            Delete the intake brief, provenance and ticket-origin     │
│                    artifacts.                                                │
│ --help   -h        Show this message and exit.                               │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty invocations

_Query local invocation records._

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

 Query local invocation records.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ list  List recent invocation records from the local audit log.               │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty invocations list

```
 Usage: spec-kitty invocations list [OPTIONS]

 List recent invocation records from the local audit log.

 # FR-008 / T031: This command does not open an InvocationRecord at baseline.
 # If a future version of `invocations list` opens an invocation, it should
 use:
 #   derive_mode("invocations.list")  -> ModeOfWork.QUERY
 # The mapping is reserved in _ENTRY_COMMAND_MODE (modes.py) for enforcement
 # consistency (QUERY mode disallows Tier 2 evidence promotion per FR-009).
 # TODO(future): wire derive_mode("invocations.list") when InvocationRecord is
 opened here.

 Records are returned newest-first, sorted by ``started_at`` from file
 content.  Use ``--profile`` to narrow to one agent profile.  Use
 ``--json`` for machine-readable output.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --profile         -p      <str>   Filter by profile ID (reads file content,  │
│                                   not filename)                              │
│ --limit           -n      <int>   Maximum number of records to return        │
│                                   (default: 20)                              │
│                                   [default: 20]                              │
│ --json                            Emit a JSON array instead of a table       │
│ --owned-checkout          <path>  List the Op records kept in an owned       │
│                                   checkout: a linked checkout of this        │
│                                   repository. Refuses the repository root    │
│                                   checkout, coordination worktrees and lane  │
│                                   worktrees.                                 │
│ --help            -h              Show this message and exit.                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty issue-matrix

_Issue-matrix commands (structured issue-matrix.json)._

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

 Issue-matrix commands (structured issue-matrix.json).

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ migrate  Bulk-migrate legacy ``issue-matrix.md`` missions to                 │
│          ``issue-matrix.json`` (FR-013).                                     │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty issue-matrix migrate

```
 Usage: spec-kitty issue-matrix migrate [OPTIONS]

 Bulk-migrate legacy ``issue-matrix.md`` missions to ``issue-matrix.json``
 (FR-013).

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission          <str>  Scope to a single mission handle. Omit to migrate  │
│                           all missions.                                      │
│ --json                    Emit structured JSON output.                       │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty lint

```
 Usage: spec-kitty lint [OPTIONS] [file_path]

 Run ruff and mypy on a file and report errors.

 This command is designed to be used as a post-edit hook for AI agents,
 providing immediate feedback on linting and type-checking violations.
 When invoked without a path (the wired hook form), the target file is read
 from the harness JSON payload on stdin.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│   file_path      <path>  File to lint/type-check; omit to read the path from │
│                          a hook stdin payload                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Output in JSON format for AI agents                        │
│ --fix             Attempt to automatically fix lint errors                   │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty materialize

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

 Regenerate all derived views from the canonical event log.

 For each feature (or a single feature when --mission is given),
 writes the following files to ``.kittify/derived/<slug>/``:

 - ``status.json`` — full StatusSnapshot
 - ``board-summary.json`` — lane counts and WP lists
 - ``progress.json`` — lane-weighted progress percentage
 - ``lifecycle.json`` — canonical active/recent/stale/abandoned mission state

 A coordination-routed Mission is reduced from its coordination surface's
 event log. To find that log this command may create the coordination
 worktree (one ``git worktree add`` per coordination-routed Mission, done
 once) and, for a Mission created before the coordination surface was
 seeded, seed it. ``lanes`` and ``single_branch`` Missions are reduced from
 the repository root checkout exactly as before. A Mission whose coordination
 branch exists only on a remote, or whose logs diverged, is reported in the
 error summary and the remaining Missions are still processed.

 Examples::

     spec-kitty materialize
     spec-kitty materialize --mission 034-my-feature
     spec-kitty materialize --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission          <str>  Mission slug to materialise (all if omitted)       │
│ --json                    Output a machine-readable JSON summary             │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty migrate

_Migration commands: update .kittify/ layout and backfill identity fields in legacy missions._

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

 Migration commands: update .kittify/ layout and backfill identity fields in
 legacy missions.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --dry-run            Show what would change without modifying the            │
│                      filesystem. Before a subcommand, forwarded if the       │
│                      subcommand declares it, else rejected (exit 2) — place  │
│                      it after the subcommand when unsure.                    │
│ --verbose  -v        Show file-by-file detail. Before a subcommand,          │
│                      forwarded if the subcommand declares it, else rejected  │
│                      (exit 2) — place it after the subcommand when unsure.   │
│ --force              Skip confirmation prompt. Before a subcommand,          │
│                      forwarded if the subcommand declares it, else rejected  │
│                      (exit 2) — place it after the subcommand when unsure.   │
│ --help     -h        Show this message and exit.                             │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ backfill-identity          Write a ULID mission_id into any meta.json that   │
│                            lacks one.                                        │
│ backfill-merge-commit      Record a GitHub PR's real merge commit as a       │
│                            mission's review baseline (#4231).                │
│ backfill-topology          Persist each legacy mission's MissionTopology     │
│                            into its meta.json.                               │
│ backfill-mission-type      Mint a profile-resolving ``mission_type`` into    │
│                            legacy ``meta.json`` (rc3 M0).                    │
│ charter-encoding           Scan charter content for non-UTF-8 encodings;     │
│                            normalize-or-fail-loud.                           │
│ backfill-provenance        FR-014: backfill provenance onto legacy           │
│                            acceptance-matrix.json invariants.                │
│ normalize-lifecycle        Normalize legacy ``kitty-specs`` missions for the │
│                            MVP lifecycle model.                              │
│ rewrite-opposed-by         Rewrite a pack's legacy ``opposed_by`` entries    │
│                            into DRG edges.                                   │
│ backfill-runtime-state     Seed legacy runtime state as events, verify       │
│                            fail-closed, and flip status_phase.               │
│ backfill-wp-status         Seed the lane events a Mission's WP files lack,   │
│                            so the status snapshot counts every WP (#5579).   │
│ rebaseline-dossier-hashes  One-time re-baseline of recorded dossier snapshot │
│                            hashes (FR-009, WP05).                            │
│ repin-hooks                Re-pin this repository's pre-commit hook to the   │
│                            current interpreter (#254).                       │
│ ledger                     Report the migration ledger: which setup steps    │
│                            have run, and their state.                        │
│ activation-ledger          Move charter activation keys into the activation  │
│                            ledger, and nothing else.                         │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty migrate activation-ledger

```
 Usage: spec-kitty migrate activation-ledger [OPTIONS]

 Move charter activation keys into the activation ledger, and nothing else.

 Runs exactly the move of the ``4.0.0rc8_activation_ledger`` upgrade
 migration: the ``activated_<kind>``, ``activated_kinds`` and
 ``mission_type_activations`` keys leave the ``charter.yaml`` that
 ``.kittify/config.yaml`` points to (or ``config.yaml`` itself, and any
 leftover copy there) for ``.kittify/charter/activation.yaml``, verbatim,
 and the synthesis manifest is re-stamped. Use it on a project that an
 older CLI wrote activation keys into again, without a full upgrade.

 * It refuses, writing nothing (exit 1), when the files disagree about a
   key, or when a legacy file holds a ``deactivated_<kind>`` key.
 * It is idempotent: a re-run reports nothing to do and writes nothing.
 * When ``.kittify/migration-ledger.jsonl`` exists it records the
   migration as applied (``ledger_record: written``); otherwise it records
   nothing (``not_recorded``) and a later upgrade finds nothing to move.

 Exit codes: 0 moved or nothing to do, 1 refused (nothing written), 2 usage
 error.

 Examples:

     spec-kitty migrate activation-ledger --dry-run

     spec-kitty migrate activation-ledger

     spec-kitty migrate activation-ledger --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --dry-run            List the moves (key, from-file, to-file) and write      │
│                      nothing.                                                │
│ --json               Emit the result, the moves, any refusal and the         │
│                      migration-ledger record as JSON.                        │
│ --help     -h        Show this message and exit.                             │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty migrate backfill-identity

```
 Usage: spec-kitty migrate backfill-identity [OPTIONS]

 Write a ULID mission_id into any meta.json that lacks one.

 This command is **idempotent** — running it twice produces identical
 state.  Existing ``mission_id`` values are never overwritten.  The
 command also coerces legacy string-typed ``mission_number`` values
 (e.g. ``"042"`` → ``42``) while walking each mission.

 After writing, the dossier parity hash is recomputed for every mission
 that was modified.  Individual dossier failures are logged as warnings
 and do not abort the run.

 **When to run:**

 - After upgrading from a spec-kitty version that predates ``mission_id``
 - After pulling a clone that has legacy missions (no ``mission_id``)
 - As part of CI checks on legacy repositories

 Exit codes:

 - ``0`` — all results are ``wrote`` or ``skip``
 - ``1`` — one or more ``error`` results (corrupt JSON, sentinel strings, …)

 Examples:

     spec-kitty migrate backfill-identity --dry-run --json

     spec-kitty migrate backfill-identity --mission 083-foo-bar

     spec-kitty migrate backfill-identity

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json                   Emit per-mission result list as structured JSON     │
│ --dry-run                Report what would change without writing any files. │
│                          The JSON shape is identical to a live run.          │
│ --mission          SLUG  Scope to a single mission slug (e.g. 083-foo-bar).  │
│                          Omit to process all.                                │
│ --help     -h            Show this message and exit.                         │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty migrate backfill-merge-commit

```
 Usage: spec-kitty migrate backfill-merge-commit [OPTIONS]

 Record a GitHub PR's real merge commit as a mission's review baseline (#4231).

 A mission accepted through ``acceptance_mode: pr`` never passes through
 ``spec-kitty consolidate``, so its ``meta.json`` never carried
 ``baseline_merge_commit`` — leaving ``spec-kitty review --mode post-merge``
 unreachable (``MISSION_REVIEW_MODE_MISMATCH``) and the lightweight
 dead-code gate failing a cleanly merged mission. This command repairs
 that state from REAL evidence: the merge commit you supply is verified
 against git (it must resolve in this repository, carry the mission's
 ``kitty-specs/<slug>/meta.json``, its first parent must not — proving it
 is the commit that introduced the mission corpus — and it must have
 landed on the target branch, so an unmerged mission-branch commit is
 refused) before ``baseline_merge_commit`` (the first parent) and the
 provenance pair ``pr_merge_commit`` (the landing commit itself) /
 ``pr_merge_evidence`` (what the anchor's completeness rests on) are
 written through the same canonical seam ``spec-kitty consolidate`` and
 ``accept --mode pr --merge-commit`` use.

 **What the anchor proves depends on the landing shape — and on your
 attestation, never on git.** Checks 1–6 prove the commit landed on the
 target branch and introduced the mission corpus; they cannot prove its
 first parent is the PRE-LANDING TARGET TIP for any shape. A two-parent
 merge commit's first parent is the tip only if the merge was performed
 on the target branch — an internal merge (the corpus branch merged into
 the implementation branch, the target then fast-forwarded to the
 result) is graph-identical and its first parent is an implementation
 commit. A single-parent landing commit (squash, or a corpus-first stack)
 has the tip as its parent only if it was the first commit of the
 landing. Both shapes therefore require ``--attest-first-landing-commit``
 — your explicit attestation — and record it as the anchor's evidence
 class (``pr_merge_evidence: merge-commit-parent-attested`` /
 ``corpus-parent-attested``), so the anchor's completeness rests on a
 recorded operator attestation, never on a claim git did not make.
 Anchoring at the wrong tip would silently under-scan the dead-code
 gate. Full forge commit-list evidence, which would prove the tip
 outright, is tracked in #4277.

 **Idempotent**: a mission whose ``meta.json`` already carries a
 ``baseline_merge_commit`` is skipped and never overwritten.

 Exit codes:

 - ``0`` — recorded, skipped (already recorded), or ``--dry-run``
 - ``1`` — the merge evidence could not be verified, or the mission handle
   is unknown

 Examples:

     spec-kitty migrate backfill-merge-commit --mission 321-mission
 --merge-commit <sha> --dry-run

     spec-kitty migrate backfill-merge-commit --mission 321-mission
 --merge-commit <sha>

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission                            HANDLE  Mission to repair            │
│                                                 (mission_id / mid8 / slug).  │
│                                                 [required]                   │
│ *  --merge-commit                       SHA     The PR merge commit that     │
│                                                 landed the mission on its    │
│                                                 target branch. Read it off   │
│                                                 the merged PR, then supply   │
│                                                 it here; the migration       │
│                                                 verifies it against git      │
│                                                 before writing anything — it │
│                                                 must carry the mission's     │
│                                                 kitty-specs/<slug>/meta.jso… │
│                                                 its first parent must not,   │
│                                                 and it must have landed on   │
│                                                 the target branch. Every     │
│                                                 landing shape additionally   │
│                                                 needs                        │
│                                                 --attest-first-landing-comm… │
│                                                 [required]                   │
│    --target-branch                      <str>   The branch the PR merged     │
│                                                 into (the PR's base branch), │
│                                                 for the landing check.       │
│                                                 Defaults to the mission's    │
│                                                 declared target_branch, else │
│                                                 the repository's primary     │
│                                                 branch.                      │
│    --attest-first-landing-com…                  Attest that the supplied     │
│                                                 --merge-commit's first       │
│                                                 parent is the pre-landing    │
│                                                 target tip. Required for     │
│                                                 every landing shape: for a   │
│                                                 two-parent merge commit,     │
│                                                 attest the merge was         │
│                                                 performed ON the target      │
│                                                 branch (a merge performed on │
│                                                 a mission or sibling branch  │
│                                                 and then fast-forwarded onto │
│                                                 the target is                │
│                                                 graph-identical, and its     │
│                                                 first parent is an           │
│                                                 implementation commit, not   │
│                                                 the tip); for a              │
│                                                 single-parent landing        │
│                                                 (squash or corpus-first      │
│                                                 stack), attest the supplied  │
│                                                 commit was the FIRST commit  │
│                                                 of the landing. Git cannot   │
│                                                 prove either — and a wrong   │
│                                                 anchor silently under-scans  │
│                                                 the dead-code gate. The      │
│                                                 attestation is recorded in   │
│                                                 pr_merge_evidence, never     │
│                                                 presented as a git proof.    │
│    --dry-run                                    Verify the merge evidence    │
│                                                 and report what would be     │
│                                                 written without writing any  │
│                                                 files. The JSON shape is     │
│                                                 identical to a live run.     │
│    --json                                       Emit the per-mission         │
│                                                 backfill result row as       │
│                                                 structured JSON.             │
│    --help                       -h              Show this message and exit.  │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty migrate backfill-mission-type

```
 Usage: spec-kitty migrate backfill-mission-type [OPTIONS]

 Mint a profile-resolving ``mission_type`` into legacy ``meta.json`` (rc3 M0).

 Legacy missions store their type only in the deprecated ``mission`` field.
 This command writes a canonical ``mission_type`` for every candidate whose
 legacy value resolves a governance profile at *any* layer (built-in / org
 / project) — activation-independent, per the M3 tolerance authority.  A
 mission that already has a ``mission_type`` key is always skipped and
 left byte-for-byte unchanged.

 This command is **idempotent** — running it twice reports ``wrote=0`` on
 the second pass.

 A candidate whose legacy value resolves **no** governance profile is
 never written; it is reported ``needs_manual_resolution`` instead. This
 does **not** by itself fail the command — see the exit codes below — but
 a distinct, actionable diagnostic is printed naming the affected
 mission(s): the fix is to assign a valid mission type whose governance
 profile resolves at some layer, or to author/activate that type. It is
 not necessarily a typo.

 Exit codes:

 - ``0`` — ``--dry-run`` (always, regardless of findings), or a live run
   with zero ``error`` results (``needs_manual_resolution`` alone does not
   fail the command)
 - ``1`` — a live run with one or more ``error`` results (corrupt /
   unreadable ``meta.json``), or ``--mission`` naming a slug that has no
   matching directory under ``kitty-specs/``

 Examples:

     spec-kitty migrate backfill-mission-type --dry-run --json

     spec-kitty migrate backfill-mission-type --mission 083-foo-bar

     spec-kitty migrate backfill-mission-type

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json                   Emit the per-mission backfill result list as        │
│                          structured JSON.                                    │
│ --dry-run                Report what would change without writing any files. │
│                          The JSON shape is identical to a live run.          │
│ --mission          SLUG  Scope to a single mission slug (e.g. 083-foo). Omit │
│                          to process all missions.                            │
│ --help     -h            Show this message and exit.                         │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty migrate backfill-provenance

```
 Usage: spec-kitty migrate backfill-provenance [OPTIONS]

 FR-014: backfill provenance onto legacy acceptance-matrix.json invariants.

 Walks every ``kitty-specs/*/acceptance-matrix.json`` and, for each negative
 invariant whose ``result`` is not ``pending`` and lacks ``provenance_origin``,
 stamps the ``legacy_unrecorded`` sentinel (data-model.md NI-1 / contract
 ``negative-invariant-provenance.md`` C1). ``verified_ref`` and
 ``verified_surface_kind`` are left null for those rows — the sentinel means
 the surface a pre-schema judgement was established against is genuinely
 unknowable, not empty by omission.

 This migration is **idempotent** (NI-2 / C3): re-running it on an
 already-migrated corpus is a no-op — a row already carrying
 ``provenance_origin`` (``recorded`` or ``legacy_unrecorded``) is never
 re-stamped.

 The whole-corpus write is enrolled in a commit-or-revert transaction: on
 any failure partway through, every file already written in that run is
 restored to its pre-migration bytes — no partial migration state is left
 on disk.

 AM-4: this migration never auto-archives. A matrix it cannot parse is
 reported as an error and skipped; it never routes into an archive
 operation.

 ``--mission`` (#6347) narrows the walk to that one Mission's acceptance
 matrix; omitting it keeps the whole-corpus walk exactly as before.

 Exit codes:

 - ``0`` — every matrix migrated cleanly (or needed no change)
 - ``1`` — one or more matrices could not be parsed (see the reported errors)
 - ``2`` — the ``--mission`` handle does not resolve (human mode)
 - ``1`` — the ``--mission`` handle does not resolve (``--json`` mode)

 Examples:

     spec-kitty migrate backfill-provenance --dry-run

     spec-kitty migrate backfill-provenance --json

     spec-kitty migrate backfill-provenance --mission 042-my-mission --dry-run

     spec-kitty migrate backfill-provenance

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --dry-run                       Report what would be stamped without writing │
│                                 any files. The JSON shape is identical to a  │
│                                 live run.                                    │
│ --json                          Emit a JSON-stable summary report on stdout. │
│ --mission               HANDLE  Scope to a single mission (mission_id / mid8 │
│                                 / slug). Omit to process the whole corpus.   │
│ --project-root          DIR     Root of the Spec Kitty project (default:     │
│                                 current working directory).                  │
│                                 [default: .]                                 │
│ --help          -h              Show this message and exit.                  │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty migrate backfill-runtime-state

```
 Usage: spec-kitty migrate backfill-runtime-state [OPTIONS]

 Seed legacy runtime state as events, verify fail-closed, and flip
 status_phase.

 Drives the shared
 :func:`~specify_cli.migration.runtime_state_cutover.cutover_mission`
 helper over the corpus (or a single ``--mission``). For every mission it seeds
 the frontmatter/checkbox runtime state into the event log, verifies the
 reduced
 snapshot equals the OLD reader by **count + value**, and flips ``meta.json``
 ``status_phase`` to snapshot-authority **only** for missions that verify.

 Per-mission best-effort (research D-03): a mission whose verify fails is left
 un-flipped (``status_phase`` untouched) and named in the summary; other
 missions
 still flip. Use ``--dry-run`` to preview would-seed and would-flip counts
 without writing. The summary's ``Flipped`` counter names the missions this
 run actually flipped — a mission with event-log evidence but no legacy
 frontmatter state to seed still flips and is counted there, never as
 "Skipped (already migrated)" (#3212).

 Exit codes:

 - ``0`` — every visited mission flipped or is already migrated (verify ok, no
 error)
 - ``1`` — one or more missions failed verify / errored, or ``--mission`` named
 an
   unknown handle

 Examples:

     spec-kitty migrate backfill-runtime-state --dry-run

     spec-kitty migrate backfill-runtime-state --mission my-mission-01ABCD

     spec-kitty migrate backfill-runtime-state --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --dry-run                  Seed nothing and flip nothing; report per-mission │
│                            would-seed counts and would-flip.                 │
│ --mission          HANDLE  Scope to a single mission (mission_id / mid8 /    │
│                            slug). Omit to process the whole corpus.          │
│ --json                     Emit the per-mission cutover result list as       │
│                            structured JSON.                                  │
│ --help     -h              Show this message and exit.                       │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty migrate backfill-topology

```
 Usage: spec-kitty migrate backfill-topology [OPTIONS]

 Persist each legacy mission's MissionTopology into its meta.json.

 Computes every mission's topology (the coordination × lanes grid cell) from
 its current on-disk signals via the single WP01 classifier and writes it to
 ``meta.json`` as the authoritative ``topology`` value. This command is
 **idempotent** — a mission that already has a valid ``topology`` is skipped
 and its value is never overwritten.

 Exit codes:

 - ``0`` — all results are ``wrote`` or ``skip``
 - ``1`` — one or more ``error`` results (corrupt / unreadable meta.json)

 Examples:

     spec-kitty migrate backfill-topology --dry-run --json

     spec-kitty migrate backfill-topology --mission 083-foo-bar

     spec-kitty migrate backfill-topology

     spec-kitty migrate backfill-topology --restamp-single-branch --dry-run

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json                                 Emit per-mission result list as       │
│                                        structured JSON                       │
│ --dry-run                              Report what would change without      │
│                                        writing any files. The JSON shape is  │
│                                        identical to a live run.              │
│ --mission                        SLUG  Scope to a single mission slug (e.g.  │
│                                        083-foo-bar). Omit to process all.    │
│ --restamp-single-branch                Re-stamp every single_branch mission  │
│                                        whose lanes.json has a code lane to   │
│                                        topology: lanes (Invariant T-1        │
│                                        repair, #5100). Mutually exclusive    │
│                                        with the ordinary backfill this       │
│                                        command otherwise runs; combine with  │
│                                        --dry-run to preview.                 │
│ --help                   -h            Show this message and exit.           │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty migrate backfill-wp-status

```
 Usage: spec-kitty migrate backfill-wp-status [OPTIONS]

 Seed the lane events a Mission's WP files lack, so the status snapshot counts
 every WP (#5579).

 The reduced status snapshot omits any WP with no lane event, so a Mission
 whose event log never seeded some ``tasks/WP*.md`` file under-counts on
 every read surface that lists WPs from the files. This command appends one
 deterministic ``planned`` seed per missing WP (actor
 ``migration:backfill_wp_status``)
 through the existing migration writer, on the Mission's resolved
 PRIMARY-partition status surface. It is idempotent: a re-run appends
 nothing. WPs the snapshot carries without a WP file are reported, never
 repaired. A Mission whose status log lives on a live coordination surface
 is refused (``COORD_SURFACE_LIVE``, counted as refused rather than skipped,
 nothing written):
 consolidate it first and rerun once the coordination branch is gone.

 A Mission with terminal evidence (``meta.json`` ``merged_at`` /
 ``accepted_at``, or an entry in ``--evidence-manifest``) has its freshly
 seeded WPs driven on to ``done`` with a forced, evidence-citing event, so
 its progress reads 100%. Nothing else counts as evidence.

 The evidence manifest must be complete on the first live run. Terminal
 evidence applies only to WPs seeded in that same run: a WP an earlier run
 already seeded ``planned`` is no longer a gap, so evidence supplied later
 is a silent no-op (the summary warns for every manifest entry that had
 nothing to seed). Run ``--dry-run`` with the full manifest first.

 The manifest is YAML, keyed by exact ``kitty-specs/`` directory name:

     missions:
       my-mission-01ABCDEF:
         reason: "PR #1234 merged 2026-09-01; dossier landed on main"

 A missing/empty reason or a slug that does not resolve is refused up front
 (exit 1, nothing written).

 Exit codes:

 - ``0`` — every visited Mission was repaired, needed nothing, or was refused
   as ``COORD_SURFACE_LIVE``
 - ``1`` — a per-Mission error, an invalid evidence manifest, or (with
   ``--json``) an unknown or ambiguous ``--mission`` handle
 - ``2`` — an unknown or ambiguous ``--mission`` handle (human output)

 Examples:

     spec-kitty migrate backfill-wp-status --dry-run

     spec-kitty migrate backfill-wp-status --mission my-mission-01ABCDEF --json

     spec-kitty migrate backfill-wp-status --evidence-manifest evidence.yaml

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --dry-run                            Report per-Mission would-seed plans;    │
│                                      write nothing.                          │
│ --mission                    HANDLE  Scope to a single mission (mission_id / │
│                                      mid8 / slug). Omit to process the whole │
│                                      corpus.                                 │
│ --evidence-manifest          FILE    YAML file marking Missions finished:    │
│                                      missions: {<slug>: {reason: <text>}}.   │
│                                      Applies only to WPs seeded in the same  │
│                                      run, so it must be complete on the      │
│                                      first live run.                         │
│ --json                               Emit the per-Mission repair result and  │
│                                      summary as structured JSON.             │
│ --help               -h              Show this message and exit.             │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty migrate charter-encoding

```
 Usage: spec-kitty migrate charter-encoding [OPTIONS]

 Scan charter content for non-UTF-8 encodings; normalize-or-fail-loud.

 Walks every existing mission's charter content
 (``kitty-specs/*/charter/*.{yaml,md,txt}``) and the global charter store
 (``.kittify/charter/*.{yaml,md,txt}``), detects the encoding of each file
 via the WP06 chokepoint, and either:

 \b
 * **skips** the file (already pure UTF-8; idempotency pre-check passes)
 * **normalizes** the file to UTF-8 in-place with a provenance record
 * **surfaces** the file as ambiguous (exits non-zero; manual repair required)

 This migration is **idempotent** (NFR-006): running it twice on an
 already-normalized corpus is a near-instant no-op — no new provenance
 records are written for already-UTF-8 files.

 Implements FR-026, FR-027, NFR-006.

 ``--mission`` (#6347) narrows the walk to one Mission's charter content and
 **excludes the global charter store**, which is reported in both the human
 summary and the ``--json`` payload (``global_store_excluded``) and left
 byte-for-byte untouched. Omitting ``--mission`` keeps the corpus-wide walk,
 global store included, exactly as before.

 Exit codes:

 - ``0`` — the walked corpus (the scoped Mission, or the whole corpus when
   ``--mission`` is omitted) is fully UTF-8 compliant (all files
   already-UTF-8 or successfully normalized)
 - ``1`` — one or more walked files are ambiguous (manual repair required)
 - ``2`` — the ``--mission`` handle does not resolve (human mode)
 - ``1`` — the ``--mission`` handle does not resolve (``--json`` mode)

 Examples:

     spec-kitty migrate charter-encoding --dry-run

     spec-kitty migrate charter-encoding --yes --json

     spec-kitty migrate charter-encoding --mission 042-my-mission --yes

     spec-kitty migrate charter-encoding

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --dry-run                       Show what would change without writing any   │
│                                 files.  Returns exit 0 unless ambiguous      │
│                                 files are found.                             │
│ --yes           -y              Apply normalizations without prompting.      │
│                                 Exits non-zero if any file is ambiguous      │
│                                 (CI-safe).  Do NOT pass --yes to silently    │
│                                 bypass ambiguous files — manual repair is    │
│                                 required for those.                          │
│ --json                          Emit a JSON-stable summary report on stdout. │
│ --mission               HANDLE  Scope to a single mission (mission_id / mid8 │
│                                 / slug). Omit to process the whole corpus.   │
│ --project-root          DIR     Root of the Spec Kitty project (default:     │
│                                 current working directory).                  │
│                                 [default: .]                                 │
│ --help          -h              Show this message and exit.                  │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty migrate ledger

```
 Usage: spec-kitty migrate ledger [OPTIONS]

 Report the migration ledger: which setup steps have run, and their state.

 A **read-only** view of the two-partition migration ledger. It lists every
 declared setup step in declared (manifest) order and, for each, shows:

 \b
 * whether it is **already in place** (recorded, effect present here),
 * **recorded elsewhere but not here** (a per-clone step the ledger records
   but whose effect is absent on this checkout — e.g. a freshly pulled clone),
 * **not yet applied**, and
 * whether its source **content changed since it ran** (drift).

 Drift is **audit-only**: it is reported, never re-applied. This command never
 commits and never writes a file.

 ``--json`` emits the one structured shape the human summary renders from.

 Examples:

     spec-kitty migrate ledger

     spec-kitty migrate ledger --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Emit the recorded setup steps and summary as structured    │
│                   JSON (the same shape the human summary renders).           │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty migrate normalize-lifecycle

```
 Usage: spec-kitty migrate normalize-lifecycle [OPTIONS]

 Normalize legacy ``kitty-specs`` missions for the MVP lifecycle model.

 This command repairs enough historical mission state to make the canonical
 lifecycle model reliable across old repositories. It backfills identity
 where needed, rebuilds missing event logs from legacy state, and regenerates
 status/progress/lifecycle projections used by the CLI and Teamspace.

 Exit codes:

 - ``0`` — all targeted missions normalized or skipped cleanly
 - ``1`` — one or more missions hit an unrecoverable error

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json                   Emit a structured per-mission normalization report  │
│ --dry-run                Preview lifecycle normalization without modifying   │
│                          the filesystem                                      │
│ --mission          SLUG  Scope to a single mission slug (e.g. 083-foo-bar).  │
│                          Omit to process all.                                │
│ --help     -h            Show this message and exit.                         │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty migrate rebaseline-dossier-hashes

```
 Usage: spec-kitty migrate rebaseline-dossier-hashes [OPTIONS]

 One-time re-baseline of recorded dossier snapshot hashes (FR-009, WP05).

 Recomputes every recorded ``.kittify/dossiers/<slug>/snapshot-latest.json``
 hash under the canonical definition (WP01/WP02) so content that did not
 change is not flagged divergent after the cutover. Idempotent (snapshots
 already in canonical ``sha256:`` form are skipped) and read-only over source
 artifacts — only the recorded snapshot cache files are written (#2263).

 ``--mission`` (#6347) narrows the sweep to that one Mission's recorded
 snapshot(s); omitting it keeps the whole-backlog sweep exactly as before.

 Exit codes:

 - ``0`` — completed (some snapshots may be reported as errors and skipped)
 - ``1`` — project root could not be located
 - ``2`` — the ``--mission`` handle does not resolve (human mode)
 - ``1`` — the ``--mission`` handle does not resolve (``--json`` mode)

 Examples:

     spec-kitty migrate rebaseline-dossier-hashes --dry-run

     spec-kitty migrate rebaseline-dossier-hashes --mission 042-my-mission

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json                     Emit a structured per-mission re-baseline report  │
│ --dry-run                  Preview which recorded snapshot hashes would be   │
│                            re-baselined, without writing                     │
│ --mission          HANDLE  Scope to a single mission (mission_id / mid8 /    │
│                            slug). Omit to process the whole corpus.          │
│ --help     -h              Show this message and exit.                       │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty migrate repin-hooks

```
 Usage: spec-kitty migrate repin-hooks [OPTIONS]

 Re-pin this repository's pre-commit hook to the current interpreter (#254).

 ``policy/hook_installer.py`` pins the absolute Python interpreter path
 into the pre-commit hook at install time. An install-method migration
 (e.g. pipx -> uv) moves that interpreter, and the OLD hook keeps pointing
 at a path that no longer exists. This command re-runs the same install
 the ``implement`` lane calls internally, but without requiring a mission
 or workspace — the repair does not depend on the very thing it is
 repairing (the ability to commit).

 Idempotent: safe to re-run; a hook already pinned to the current
 interpreter is re-written to the same effective hook (only the
 ``# Installed:`` timestamp comment differs).

 Exit codes:

 - ``0`` — the hook was (re-)installed
 - ``1`` — project root could not be located, or the current
   ``sys.executable`` does not refer to an existing file

 Examples:

     spec-kitty migrate repin-hooks

     spec-kitty migrate repin-hooks --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Emit a JSON-stable summary report on stdout.               │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty migrate rewrite-opposed-by

```
 Usage: spec-kitty migrate rewrite-opposed-by [OPTIONS]

 Rewrite a pack's legacy ``opposed_by`` entries into DRG edges.

 Scans every ``*.directive.yaml``/``*.tactic.yaml``/``*.paradigm.yaml``
 file under ``--pack`` for ``opposed_by`` entries, classifies each as
 tension-style (rewritten to an ``in_tension_with`` edge) or
 anti-pattern-rejection-style (rewritten to a ``rejects`` edge, creating
 the target ``anti_pattern`` node if absent), writes the new edges into
 the pack's ``<kind>.graph.yaml`` fragments, and removes the migrated
 ``opposed_by`` key from the source YAML.

 This command is **idempotent** — once a pack has no remaining
 ``opposed_by`` entries, running it again is a no-op.

 **When to run:**

 - Before upgrading to a spec-kitty release that drops ``opposed_by``
   from the ``directive``/``tactic``/``paradigm`` schemas
 - As part of CI checks on an org pack that still authors ``opposed_by``

 Exit codes:

 - ``0`` — every entry was rewritten (or, in ``--dry-run``, would be)
 - ``1`` — one or more entries could not be unambiguously classified

 Examples:

     spec-kitty migrate rewrite-opposed-by --pack ./org-packs/acme --dry-run

     spec-kitty migrate rewrite-opposed-by --pack ./org-packs/acme --json

     spec-kitty migrate rewrite-opposed-by --pack ./org-packs/acme

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --pack             PATH  Root directory of the target pack to migrate (org   │
│                          pack or any directory shaped like the built-in      │
│                          charter pack tree).                                 │
│                          [default: .]                                        │
│ --dry-run                Report planned rewrites without writing any files.  │
│                          The JSON shape is identical to a live run.          │
│ --json                   Emit a structured JSON report on stdout.            │
│ --help     -h            Show this message and exit.                         │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty mission

_Inspect mission types for this project._

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

 Inspect mission types for this project.

 Use 'list' to see activated types (charter-filtered) and 'show <id>' for a
 full resolved definition.

 Mission types are selected per mission run during /spec-kitty.specify.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ current    Show currently active mission for a mission                       │
│            (auto-detects mission from cwd).                                  │
│ info       Show details for a specific mission without                       │
│            switching.                                                        │
│ run        Start (or attach to) a runtime for a                              │
│            project-authored custom mission definition.                       │
│ close      Close a mission. Wraps FR-016 lifecycle teardown.                 │
│ reopen     Re-open a merged/closed mission, returning it to                  │
│            an actionable state (FR-002).                                     │
│ follow-up  Record a follow-up commit or PR against a mission                 │
│            (FR-001).                                                         │
│ switch     [REMOVED] Switch active mission - this command was  (deprecated)  │
│            removed in v0.8.0.                                                │
│ list       List activated mission types for the current                      │
│            project (FR-016).                                                 │
│ show       Show the fully resolved MissionType definition for                │
│            this project (FR-017).                                            │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty mission close

```
 Usage: spec-kitty mission close [OPTIONS]

 Close a mission. Wraps FR-016 lifecycle teardown.

 Without ``--discard``: fail-closed precondition (FR-004/FR-005, #4765) —
 refuses (non-zero exit, no writes) unless the mission has a recorded merge
 baseline (``is_mission_merged``). An all-terminal-but-unmerged mission
 (e.g. every work package cancelled) still refuses here; use ``--discard``
 to abandon it. Once merged: runs the merge-completion teardown — persists
 the mission retrospective to its durable home and tears down the
 coordination worktree. Idempotent after a successful ``spec-kitty
 consolidate``
 (which already ran the same teardown); useful when the teardown was
 skipped (e.g. the legacy plain-git/GitHub merge path) or interrupted.
 NOTE: on a merged mission without a retrospective, this generates one
 (``kitty-specs/<slug>/retrospective.yaml``) plus a ``RetrospectiveCaptured``
 event and commits both — it is not a pure no-op in that case. Tolerates a
 mission left with an orphaned ``coordination_branch`` marker (FR-013,
 #2745) — no traceback, the mission slug is rendered once.

 With ``--discard``: abandon the mission mid-flight. Deletes the
 coordination branch and every lane branch named in
 ``lanes.json``, then tears down the coordination worktree and the
 operator-visible lane worktrees. Requires confirmation unless
 ``--force`` is also passed. The coordination + lane branches are
 deleted with ``git branch -D`` (force-delete) because mid-flight
 abandonment by definition leaves uncommitted or unmerged work.
 A deleted Mission branch whose commits exist on no other branch keeps its
 tip under ``refs/spec-kitty/discarded/<branch>``; remove it with
 ``git update-ref -d refs/spec-kitty/discarded/<branch>`` once it is no
 longer needed.

 Implements FR-016 from
 ``kitty-specs/mission-coordination-branch-atomic-event-log-01KSPTVW``.

 ``--target`` names the branch this Mission was consolidated into, and aims
 the retrospective bookkeeping commit at it (#7201). Omit it to keep the
 placement resolution from ``meta.json``'s ``target_branch``, which is right
 for a Mission landed on its recorded target.

 Pass it when the Mission was landed with ``consolidate --target <branch>``:
 that resolved target is never written back to ``meta.json`` or
 ``lanes.json``. A close that re-derived it would ask ``safe_commit`` for
 ``main`` while the checkout sits on ``<branch>``, and the retrospective
 would be refused and left uncommitted. The refusal warning names this
 command with the right ``--target``.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission          <str>  Mission slug (auto-detected from cwd if omitted)   │
│ --discard                 Discard the mission mid-flight: delete the         │
│                           coordination branch + all lane branches and tear   │
│                           down all worktrees. Without --discard, requires    │
│                           that the mission has already been merged (no-op    │
│                           cleanup otherwise).                                │
│ --force                   Skip the confirmation prompt when --discard is     │
│                           set.                                               │
│ --target           <str>  Branch this Mission was consolidated into. Aimed   │
│                           at the retrospective bookkeeping commit; omit to   │
│                           resolve the target from meta.json (auto-detected). │
│ --json                    Emit a JSON envelope instead of a rich panel.      │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty mission current

```
 Usage: spec-kitty mission current [OPTIONS]

 Show currently active mission for a mission (auto-detects mission from cwd).

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

## spec-kitty mission follow-up

```
 Usage: spec-kitty mission follow-up [OPTIONS] {handle}

 Record a follow-up commit or PR against a mission (FR-001).

 Exactly one of ``--commit <40-hex>`` / ``--pr <int>`` must be supplied.
 Appends a ``FollowUpRecorded`` lifecycle event attributed to ``mission_id``.
 Fail-closed (#1926): only valid once the mission has reached completion
 (merged, or all WPs terminal) — a follow-up against a not-yet-completed
 mission exits non-zero with a structured error and writes no event.
 Idempotent on its dedup key ``(mission_id, commit_sha | pr_number)`` —
 re-recording the same reference is a successful no-op.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    handle      <str>  Mission handle: mission_id (ULID), mid8, or slug.    │
│                         [required]                                           │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --commit          <str>  40-hex commit SHA of the follow-up.                 │
│ --pr              <int>  Pull-request number of the follow-up.               │
│ --json                   Emit a JSON envelope instead of a rich panel.       │
│ --help    -h             Show this message and exit.                         │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty mission info

```
 Usage: spec-kitty mission info [OPTIONS] {mission_name}

 Show details for a specific mission without switching.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    mission_name      <str>  Mission name to display details for [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty mission list

```
 Usage: spec-kitty mission list [OPTIONS]

 List activated mission types for the current project (FR-016).

 Alias for ``spec-kitty charter mission-type list``.

 Returns only mission types that are explicitly activated in this
 project's charter (activation-filtered).  For all doctrine-layer
 types regardless of activation, use ``spec-kitty charter mission-type list
 --include-inactive``.

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

## spec-kitty mission reopen

```
 Usage: spec-kitty mission reopen [OPTIONS] {handle}

 Re-open a merged/closed mission, returning it to an actionable state (FR-002).

 Appends a ``MissionReopened`` lifecycle event (the authority for
 actionability — ``derive_mission_lifecycle`` reports the ``reopened``
 surface_state) and clears the ``merged_*`` markers from ``meta.json``. Does
 NOT mutate WP lanes — the operator repositions WPs explicitly afterwards.

 Fail-closed (NFR-004): the mission is unrecoverable when ``meta.json`` is
 absent/corrupt OR the mission branch resolves in neither the local repo nor
 any configured remote. A missing worktree directory alone is recoverable. On
 unrecoverable input the command exits non-zero with a remediation hint and
 writes no event / no metadata change.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    handle      <str>  Mission handle: mission_id (ULID), mid8, or slug.    │
│                         [required]                                           │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --reason          <str>  Why the mission is being re-opened (required,    │
│                             audited).                                        │
│                             [required]                                       │
│    --json                   Emit a JSON envelope instead of a rich panel.    │
│    --help    -h             Show this message and exit.                      │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty mission run

```
 Usage: spec-kitty mission run [OPTIONS] {mission_key}

 Start (or attach to) a runtime for a project-authored custom mission
 definition.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    mission_key      <str>  The reusable custom mission key. [required]     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission                   <str>  Tracked mission slug. [required]       │
│    --json         --no-json           Emit JSON envelope to stdout instead   │
│                                       of a rich panel.                       │
│                                       [default: no-json]                     │
│    --help     -h                      Show this message and exit.            │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty mission show

```
 Usage: spec-kitty mission show [OPTIONS] {mission_type_id}

 Show the fully resolved MissionType definition for this project (FR-017).

 Displays all fields of the activated mission type:
 id, display_name, action_sequence, template_set,
 source_layer, extends.

 Exits with code 1 and lists registered IDs when ``mission_type_id``
 is not an activated type.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    mission_type_id      <str>  Mission type ID (e.g. software-dev).        │
│                                  [required]                                  │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Output as JSON.                                            │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty mission switch

> **Deprecated**: this command is deprecated

```
 Usage: spec-kitty mission switch [OPTIONS] {mission_name}

 (deprecated)
 [REMOVED] Switch active mission - this command was removed in v0.8.0.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    mission_name      <str>  Mission name (no longer supported) [required]  │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --force            (ignored)                                                 │
│ --help   -h        Show this message and exit.                               │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty mission-type

_Inspect mission types for this project._

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

 Inspect mission types for this project.

 Use 'list' to see activated types (charter-filtered) and 'show <id>' for a
 full resolved definition.

 Mission types are selected per mission run during /spec-kitty.specify.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ current    Show currently active mission for a mission                       │
│            (auto-detects mission from cwd).                                  │
│ info       Show details for a specific mission without                       │
│            switching.                                                        │
│ run        Start (or attach to) a runtime for a                              │
│            project-authored custom mission definition.                       │
│ close      Close a mission. Wraps FR-016 lifecycle teardown.                 │
│ reopen     Re-open a merged/closed mission, returning it to                  │
│            an actionable state (FR-002).                                     │
│ follow-up  Record a follow-up commit or PR against a mission                 │
│            (FR-001).                                                         │
│ switch     [REMOVED] Switch active mission - this command was  (deprecated)  │
│            removed in v0.8.0.                                                │
│ list       List activated mission types for the current                      │
│            project (FR-016).                                                 │
│ show       Show the fully resolved MissionType definition for                │
│            this project (FR-017).                                            │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty mission-type close

```
 Usage: spec-kitty mission-type close [OPTIONS]

 Close a mission. Wraps FR-016 lifecycle teardown.

 Without ``--discard``: fail-closed precondition (FR-004/FR-005, #4765) —
 refuses (non-zero exit, no writes) unless the mission has a recorded merge
 baseline (``is_mission_merged``). An all-terminal-but-unmerged mission
 (e.g. every work package cancelled) still refuses here; use ``--discard``
 to abandon it. Once merged: runs the merge-completion teardown — persists
 the mission retrospective to its durable home and tears down the
 coordination worktree. Idempotent after a successful ``spec-kitty
 consolidate``
 (which already ran the same teardown); useful when the teardown was
 skipped (e.g. the legacy plain-git/GitHub merge path) or interrupted.
 NOTE: on a merged mission without a retrospective, this generates one
 (``kitty-specs/<slug>/retrospective.yaml``) plus a ``RetrospectiveCaptured``
 event and commits both — it is not a pure no-op in that case. Tolerates a
 mission left with an orphaned ``coordination_branch`` marker (FR-013,
 #2745) — no traceback, the mission slug is rendered once.

 With ``--discard``: abandon the mission mid-flight. Deletes the
 coordination branch and every lane branch named in
 ``lanes.json``, then tears down the coordination worktree and the
 operator-visible lane worktrees. Requires confirmation unless
 ``--force`` is also passed. The coordination + lane branches are
 deleted with ``git branch -D`` (force-delete) because mid-flight
 abandonment by definition leaves uncommitted or unmerged work.
 A deleted Mission branch whose commits exist on no other branch keeps its
 tip under ``refs/spec-kitty/discarded/<branch>``; remove it with
 ``git update-ref -d refs/spec-kitty/discarded/<branch>`` once it is no
 longer needed.

 Implements FR-016 from
 ``kitty-specs/mission-coordination-branch-atomic-event-log-01KSPTVW``.

 ``--target`` names the branch this Mission was consolidated into, and aims
 the retrospective bookkeeping commit at it (#7201). Omit it to keep the
 placement resolution from ``meta.json``'s ``target_branch``, which is right
 for a Mission landed on its recorded target.

 Pass it when the Mission was landed with ``consolidate --target <branch>``:
 that resolved target is never written back to ``meta.json`` or
 ``lanes.json``. A close that re-derived it would ask ``safe_commit`` for
 ``main`` while the checkout sits on ``<branch>``, and the retrospective
 would be refused and left uncommitted. The refusal warning names this
 command with the right ``--target``.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission          <str>  Mission slug (auto-detected from cwd if omitted)   │
│ --discard                 Discard the mission mid-flight: delete the         │
│                           coordination branch + all lane branches and tear   │
│                           down all worktrees. Without --discard, requires    │
│                           that the mission has already been merged (no-op    │
│                           cleanup otherwise).                                │
│ --force                   Skip the confirmation prompt when --discard is     │
│                           set.                                               │
│ --target           <str>  Branch this Mission was consolidated into. Aimed   │
│                           at the retrospective bookkeeping commit; omit to   │
│                           resolve the target from meta.json (auto-detected). │
│ --json                    Emit a JSON envelope instead of a rich panel.      │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty mission-type current

```
 Usage: spec-kitty mission-type current [OPTIONS]

 Show currently active mission for a mission (auto-detects mission from cwd).

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

## spec-kitty mission-type follow-up

```
 Usage: spec-kitty mission-type follow-up [OPTIONS] {handle}

 Record a follow-up commit or PR against a mission (FR-001).

 Exactly one of ``--commit <40-hex>`` / ``--pr <int>`` must be supplied.
 Appends a ``FollowUpRecorded`` lifecycle event attributed to ``mission_id``.
 Fail-closed (#1926): only valid once the mission has reached completion
 (merged, or all WPs terminal) — a follow-up against a not-yet-completed
 mission exits non-zero with a structured error and writes no event.
 Idempotent on its dedup key ``(mission_id, commit_sha | pr_number)`` —
 re-recording the same reference is a successful no-op.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    handle      <str>  Mission handle: mission_id (ULID), mid8, or slug.    │
│                         [required]                                           │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --commit          <str>  40-hex commit SHA of the follow-up.                 │
│ --pr              <int>  Pull-request number of the follow-up.               │
│ --json                   Emit a JSON envelope instead of a rich panel.       │
│ --help    -h             Show this message and exit.                         │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty mission-type info

```
 Usage: spec-kitty mission-type info [OPTIONS] {mission_name}

 Show details for a specific mission without switching.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    mission_name      <str>  Mission name to display details for [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty mission-type list

```
 Usage: spec-kitty mission-type list [OPTIONS]

 List activated mission types for the current project (FR-016).

 Alias for ``spec-kitty charter mission-type list``.

 Returns only mission types that are explicitly activated in this
 project's charter (activation-filtered).  For all doctrine-layer
 types regardless of activation, use ``spec-kitty charter mission-type list
 --include-inactive``.

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

## spec-kitty mission-type reopen

```
 Usage: spec-kitty mission-type reopen [OPTIONS] {handle}

 Re-open a merged/closed mission, returning it to an actionable state (FR-002).

 Appends a ``MissionReopened`` lifecycle event (the authority for
 actionability — ``derive_mission_lifecycle`` reports the ``reopened``
 surface_state) and clears the ``merged_*`` markers from ``meta.json``. Does
 NOT mutate WP lanes — the operator repositions WPs explicitly afterwards.

 Fail-closed (NFR-004): the mission is unrecoverable when ``meta.json`` is
 absent/corrupt OR the mission branch resolves in neither the local repo nor
 any configured remote. A missing worktree directory alone is recoverable. On
 unrecoverable input the command exits non-zero with a remediation hint and
 writes no event / no metadata change.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    handle      <str>  Mission handle: mission_id (ULID), mid8, or slug.    │
│                         [required]                                           │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --reason          <str>  Why the mission is being re-opened (required,    │
│                             audited).                                        │
│                             [required]                                       │
│    --json                   Emit a JSON envelope instead of a rich panel.    │
│    --help    -h             Show this message and exit.                      │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty mission-type run

```
 Usage: spec-kitty mission-type run [OPTIONS] {mission_key}

 Start (or attach to) a runtime for a project-authored custom mission
 definition.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    mission_key      <str>  The reusable custom mission key. [required]     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission                   <str>  Tracked mission slug. [required]       │
│    --json         --no-json           Emit JSON envelope to stdout instead   │
│                                       of a rich panel.                       │
│                                       [default: no-json]                     │
│    --help     -h                      Show this message and exit.            │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty mission-type show

```
 Usage: spec-kitty mission-type show [OPTIONS] {mission_type_id}

 Show the fully resolved MissionType definition for this project (FR-017).

 Displays all fields of the activated mission type:
 id, display_name, action_sequence, template_set,
 source_layer, extends.

 Exits with code 1 and lists registered IDs when ``mission_type_id``
 is not an activated type.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    mission_type_id      <str>  Mission type ID (e.g. software-dev).        │
│                                  [required]                                  │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Output as JSON.                                            │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty mission-type switch

> **Deprecated**: this command is deprecated

```
 Usage: spec-kitty mission-type switch [OPTIONS] {mission_name}

 (deprecated)
 [REMOVED] Switch active mission - this command was removed in v0.8.0.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    mission_name      <str>  Mission name (no longer supported) [required]  │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --force            (ignored)                                                 │
│ --help   -h        Show this message and exit.                               │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty next

```
 Usage: spec-kitty next [OPTIONS]

 Decide and emit the next agent action for the current mission.

 Agents call this command repeatedly in a loop.  The system inspects the
 mission state machine, evaluates guards, and returns a deterministic
 decision with an action and prompt file.

 Examples:
     spec-kitty next --mission 034-my-feature --json
 # query mode
     spec-kitty next --agent claude --mission 034-my-feature --result success
 --json
     spec-kitty next --agent codex --mission 034-my-feature
     spec-kitty next --agent gemini --mission 034-my-feature --result failed
 --json
     spec-kitty next --agent claude --mission 034-my-feature --answer "yes"
 --result success --json
     spec-kitty next --agent claude --mission 034-my-feature --answer "approve"
 --decision-id "input:review" --result success --json

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --agent                   <str>   Agent name (required for advancing mode)   │
│ --result                  <str>   Result of previous step:                   │
│                                   success|failed|blocked. If omitted,        │
│                                   returns current state without advancing    │
│                                   (query mode).                              │
│ --mission                 <str>   Mission slug                               │
│ --json                            Output JSON decision only                  │
│ --answer                  <str>   Answer to a pending decision               │
│ --decision-id             <str>   Decision ID (required if multiple pending) │
│ --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 ops

_Operation history (git reflog)_

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

 Operation history (git reflog)

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ log   Show operation history.                                                │
│ undo  Undo is not supported for git.                                         │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty ops log

```
 Usage: spec-kitty ops log [OPTIONS]

 Show operation history.

 Shows the git reflog (read-only history).

 Examples:
     # Show recent operations
     spec-kitty ops log

     # Show last 5 operations
     spec-kitty ops log --limit 5

     # Show with full details
     spec-kitty ops log --verbose

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --limit    -n      <int>  Number of operations to show [default: 20]         │
│ --verbose  -v             Show full operation IDs and details                │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty ops undo

```
 Usage: spec-kitty ops undo [OPTIONS]

 Undo is not supported for git.

 Git does not have reversible operation history.
 Consider using these alternatives manually:
   - git reset --soft HEAD~1  (undo last commit, keep changes)
   - git reset --hard HEAD~1  (undo last commit, discard changes)
   - git revert <commit>      (create reverting commit)
   - git reflog               (find previous states)

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

## spec-kitty orchestrator-api

_Machine-contract API for external orchestrators (JSON-first)_

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

 Machine-contract API for external orchestrators (JSON-first)

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ contract-version      Return the current API contract version.               │
│ mission-state         Return the full state of a mission (all WPs, lanes,    │
│                       dependencies).                                         │
│ list-ready            List WPs that are ready to start (planned and all deps │
│                       approved or done).                                     │
│ resolve-workspace     Read-only: resolve a WP's lane workspace_path +        │
│                       prompt_path (+ lane fields).                           │
│ start-implementation  Composite transition: planned->claimed->in_progress    │
│                       (idempotent).                                          │
│ start-review          Transition a WP from for_review to in_review (reviewer │
│                       claims review).                                        │
│ transition            Emit a single lane transition for a WP.                │
│ append-history        Append a history entry via an ``InnerStateChanged``    │
│                       ``note`` annotation.                                   │
│ accept-mission        Accept a mission after all WPs are approved or done.   │
│ consolidate-mission   Consolidate a lane-based mission into target.          │
│ specify               Create a mission scaffold, matching the host CLI's     │
│                       enriched ``specify --json`` contract.                  │
│ plan                  Scaffold plan.md for a mission -- an unenriched        │
│                       pass-through of ``setup_plan``.                        │
│ tasks                 Finalize WP task metadata -- an unenriched             │
│                       pass-through of ``finalize_tasks``.                    │
│ check-prerequisites   Read-only mission-prerequisite context for             │
│                       ``/spec-kitty.analyze`` (FR-004).                      │
│ record-analysis       Persist an ``/spec-kitty.analyze`` report, verified    │
│                       against disk (FR-005).                                 │
│ open-decision         Open a new Decision Moment ledger entry, or return     │
│                       idempotently if one                                    │
│                       already exists (FR-006). Wraps                         │
│                       ``decisions/service.py.open_decision`` 1:1.            │
│ resolve-decision      Resolve a decision with a concrete final answer        │
│                       (FR-007). Wraps                                        │
│                       ``decisions/service.py.resolve_decision`` 1:1.         │
│ defer-decision        Defer a decision for later resolution (FR-008). Wraps  │
│                       ``decisions/service.py.defer_decision`` 1:1.           │
│ cancel-decision       Cancel a decision (deemed no longer relevant)          │
│                       (FR-009). Wraps                                        │
│                       ``decisions/service.py.cancel_decision`` 1:1.          │
│ answer-decision       Resolve a ``spec-kitty next`` ``decision_required``    │
│                       moment (FR-013,                                        │
│                       Mechanism B) with full CLI event/lifecycle-log parity  │
│                       (FR-014, operator                                      │
│                       ruling SPEC-FRESH2-001). See the module comment block  │
│                       above this                                             │
│                       function for the full five-step composite and the      │
│                       response-shape                                         │
│                       contract.                                              │
│ design-status         Read-only design-phase status query (FR-010) --        │
│                       mirrors ``list-ready``'s                               │
│                       no-state-transition, no-event-emission,                │
│                       no-``--policy`` contract for the                       │
│                       design pipeline instead of the WP loop.                │
│ artifact-read         Read bounded canonical content and its exact revision  │
│                       (absent is explicit).                                  │
│ artifact-submit       Submit design content through host placement,          │
│                       validators and commit authority.                       │
│ design-validate       Check current canonical prerequisites without          │
│                       completing a lifecycle step.                           │
│ design-context        Read bounded resolved templates, governance and        │
│                       required interview slots.                              │
│ interview-record      Record incremental interview answers through the       │
│                       existing decision service.                             │
│ next                  Query or advance exactly the same authority and        │
│                       lifecycle as native next.                              │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty orchestrator-api accept-mission

```
 Usage: spec-kitty orchestrator-api accept-mission [OPTIONS]

 Accept a mission after all WPs are approved or done.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission               <str>       Mission slug [required]               │
│ *  --actor                 <str>       Actor identity [required]             │
│    --origin-check          <function>  Refuse (enforce, the default) or only │
│                                        warn (warn) when the mission's status │
│                                        evidence or approved lanes are behind │
│                                        or unreachable on their remote; off   │
│                                        contacts nothing and accepts stale    │
│                                        evidence. Overrides                   │
│                                        SPEC_KITTY_ORIGIN_CHECK.              │
│    --help          -h                  Show this message and exit.           │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty orchestrator-api answer-decision

```
 Usage: spec-kitty orchestrator-api answer-decision [OPTIONS]

 Resolve a ``spec-kitty next`` ``decision_required`` moment (FR-013, Mechanism
 B) with full CLI event/lifecycle-log parity (FR-014, operator ruling
 SPEC-FRESH2-001). See the module comment block above this function for the
 full five-step composite and the response-shape contract.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission              <str>  Mission slug [required]                     │
│ *  --agent                <str>  Agent/actor identity performing this call   │
│                                  (required)                                  │
│                                  [required]                                  │
│ *  --answer               <str>  The answer value to persist for the pending │
│                                  decision                                    │
│                                  [required]                                  │
│    --result               <str>  Outcome of the current issuance: success |  │
│                                  failed | blocked (required alongside        │
│                                  --answer)                                   │
│    --decision-id          <str>  Run-snapshot pending decision id to answer  │
│                                  (auto-resolved when omitted and exactly one │
│                                  decision is pending)                        │
│    --policy               <str>  Policy metadata JSON (required)             │
│    --help         -h             Show this message and exit.                 │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty orchestrator-api append-history

```
 Usage: spec-kitty orchestrator-api append-history [OPTIONS]

 Append a history entry via an ``InnerStateChanged`` ``note`` annotation.

 WP08 / FR-007 / T031: this cross-package (ACL-boundary) writer no longer
 mutates the WP prompt file's ``## Activity Log`` section directly -- it
 emits a ``note``-append delta through WP01's ``emit_inner_state_changed``.
 The write target is the coord-aware STATUS-partition mission directory
 (:func:`_resolve_mission_dir_or_fail` -- the SAME seam every other STATUS
 read/write in this module uses, e.g. ``accept_mission``'s
 ``materialize(mission_dir)``), never a ``Path.cwd()``-derived join
 (C-003 / #2647 -- see the SC-008 test).

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission          <str>  Mission slug [required]                         │
│ *  --wp               <str>  Work package ID [required]                      │
│ *  --actor            <str>  Actor identity [required]                       │
│ *  --note             <str>  History note to append [required]               │
│    --help     -h             Show this message and exit.                     │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty orchestrator-api artifact-read

```
 Usage: spec-kitty orchestrator-api artifact-read [OPTIONS]

 Read bounded canonical content and its exact revision (absent is explicit).

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission              <str>  Mission slug [required]                     │
│ *  --kind                 <str>  Registered authoring artifact kind          │
│                                  [required]                                  │
│    --artifact-id          <str>  Declared package key or contract basename   │
│    --help         -h             Show this message and exit.                 │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty orchestrator-api artifact-submit

```
 Usage: spec-kitty orchestrator-api artifact-submit [OPTIONS]

 Submit design content through host placement, validators and commit authority.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission               <str>  Mission slug [required]                    │
│ *  --request-json          <str>  Closed bounded artifact batch JSON; '-'    │
│                                   reads UTF-8 stdin                          │
│                                   [required]                                 │
│ *  --actor                 <str>  Accountable author [required]              │
│    --policy                <str>  Policy metadata JSON (required)            │
│    --help          -h             Show this message and exit.                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty orchestrator-api cancel-decision

```
 Usage: spec-kitty orchestrator-api cancel-decision [OPTIONS]

 Cancel a decision (deemed no longer relevant) (FR-009). Wraps
 ``decisions/service.py.cancel_decision`` 1:1.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission                 <str>  Mission slug [required]                  │
│ *  --decision-id             <str>  Decision ledger entry ID (ULID)          │
│                                     [required]                               │
│ *  --rationale               <str>  Explanation of why (required) [required] │
│    --resolved-by             <str>  Identity of the                          │
│                                     resolving/deferring/canceling party      │
│                                     (falls back to --actor)                  │
│ *  --actor                   <str>  Actor identity [required]                │
│    --policy                  <str>  Policy metadata JSON (required)          │
│    --owned-checkout          <str>  Path to a linked owned checkout that     │
│                                     owns this mission (single_branch only);  │
│                                     omit for the repository-root checkout    │
│    --help            -h             Show this message and exit.              │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty orchestrator-api check-prerequisites

```
 Usage: spec-kitty orchestrator-api check-prerequisites [OPTIONS]

 Read-only mission-prerequisite context for ``/spec-kitty.analyze`` (FR-004).

 C-002: this verb supplies context ONLY -- it never performs `analyze`'s
 cross-artifact reasoning itself (mirrors ``start-review``'s "cannot
 perform WP implementation itself" pattern). No ``--policy`` is required
 (read-only, per spec Edge Cases: "Read-only verbs (check-prerequisites,
 design-status) do not require --policy").

 In-process only (FR-001-style parity): calls the host CLI's OWN
 ``check_prerequisites`` Typer command function
 (``mission_check_prerequisites.py:498``) directly -- the exact
 established pattern WP03's ``plan``/``tasks`` verbs already use for a
 registered ``agent mission`` Typer command (``setup_plan``/
 ``finalize_tasks`` are registered identically:
 ``app.command(...)(func)`` in ``mission.py``), so field-parity with
 ``agent mission check-prerequisites --json --include-tasks`` is
 guaranteed by construction rather than by re-deriving
 ``validate_feature_structure``'s shaping logic a second time.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission                <str>  Mission slug [required]                   │
│    --include-tasks                 Include tasks.md validation (matches the  │
│                                    host CLI's own --include-tasks default)   │
│    --help           -h             Show this message and exit.               │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty orchestrator-api consolidate-mission

```
 Usage: spec-kitty orchestrator-api consolidate-mission [OPTIONS]

 Consolidate a lane-based mission into target.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission               <str>       Mission slug [required]               │
│    --target                <str>       Target branch to merge into           │
│                                        (auto-detected from meta.json)        │
│    --strategy              <str>       Merge strategy: merge, squash, or     │
│                                        rebase                                │
│                                        [default: merge]                      │
│    --push                              Push target branch after merge        │
│    --origin-check          <function>  Refuse (enforce, the default) or only │
│                                        warn (warn) when the mission's status │
│                                        evidence or approved lanes are behind │
│                                        or unreachable on their remote; off   │
│                                        contacts nothing and accepts stale    │
│                                        evidence. Overrides                   │
│                                        SPEC_KITTY_ORIGIN_CHECK.              │
│    --help          -h                  Show this message and exit.           │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty orchestrator-api contract-version

```
 Usage: spec-kitty orchestrator-api contract-version [OPTIONS]

 Return the current API contract version.

 Pass --provider-version to check compatibility before running state-mutating
 commands.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --provider-version            <str>  Caller's provider version; returns      │
│                                      CONTRACT_VERSION_MISMATCH if below      │
│                                      minimum                                 │
│ --require-capability          <str>  Require a supported Python command      │
│                                      before performing work                  │
│ --help                -h             Show this message and exit.             │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty orchestrator-api defer-decision

```
 Usage: spec-kitty orchestrator-api defer-decision [OPTIONS]

 Defer a decision for later resolution (FR-008). Wraps
 ``decisions/service.py.defer_decision`` 1:1.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission                 <str>  Mission slug [required]                  │
│ *  --decision-id             <str>  Decision ledger entry ID (ULID)          │
│                                     [required]                               │
│ *  --rationale               <str>  Explanation of why (required) [required] │
│    --resolved-by             <str>  Identity of the                          │
│                                     resolving/deferring/canceling party      │
│                                     (falls back to --actor)                  │
│ *  --actor                   <str>  Actor identity [required]                │
│    --policy                  <str>  Policy metadata JSON (required)          │
│    --owned-checkout          <str>  Path to a linked owned checkout that     │
│                                     owns this mission (single_branch only);  │
│                                     omit for the repository-root checkout    │
│    --help            -h             Show this message and exit.              │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty orchestrator-api design-context

```
 Usage: spec-kitty orchestrator-api design-context [OPTIONS]

 Read bounded resolved templates, governance and required interview slots.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission               <str>  Mission handle; omitted before creation       │
│ --stage                 <str>  specify | plan | tasks [default: specify]     │
│ --mission-type          <str>  Activated mission type before creation        │
│ --help          -h             Show this message and exit.                   │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty orchestrator-api design-status

```
 Usage: spec-kitty orchestrator-api design-status [OPTIONS]

 Read-only design-phase status query (FR-010) -- mirrors ``list-ready``'s
 no-state-transition, no-event-emission, no-``--policy`` contract for the
 design pipeline instead of the WP loop.

 Never delegates to ``resolve_next_workflow_action`` or
 ``decide_next``/``query_current_state`` -- see the Clarification-6
 module comment above ``_tasks_are_finalized``.

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

## spec-kitty orchestrator-api design-validate

```
 Usage: spec-kitty orchestrator-api design-validate [OPTIONS]

 Check current canonical prerequisites without completing a lifecycle step.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission          <str>  Mission slug [required]                         │
│ *  --stage            <str>  specify | plan | tasks [required]               │
│    --help     -h             Show this message and exit.                     │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty orchestrator-api interview-record

```
 Usage: spec-kitty orchestrator-api interview-record [OPTIONS]

 Record incremental interview answers through the existing decision service.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission          <str>  Mission handle [required]                       │
│ *  --stage            <str>  specify | plan [required]                       │
│ *  --answers          <str>  JSON mapping of canonical question IDs to       │
│                              nonempty answers                                │
│                              [required]                                      │
│ *  --actor            <str>  Actor identity [required]                       │
│    --policy           <str>  Required orchestrator policy JSON               │
│    --help     -h             Show this message and exit.                     │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty orchestrator-api list-ready

```
 Usage: spec-kitty orchestrator-api list-ready [OPTIONS]

 List WPs that are ready to start (planned and all deps approved or done).

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

## spec-kitty orchestrator-api mission-state

```
 Usage: spec-kitty orchestrator-api mission-state [OPTIONS]

 Return the full state of a mission (all WPs, lanes, dependencies).

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

## spec-kitty orchestrator-api next

```
 Usage: spec-kitty orchestrator-api next [OPTIONS]

 Query or advance exactly the same authority and lifecycle as native next.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission              <str>  Mission handle [required]                   │
│    --agent                <str>  Agent required for advancement              │
│    --result               <str>  Prior result; omit for read-only query      │
│    --answer               <str>  Native pending decision answer              │
│    --decision-id          <str>  Native decision identity                    │
│    --policy               <str>  Policy JSON required for advancement        │
│    --help         -h             Show this message and exit.                 │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty orchestrator-api open-decision

```
 Usage: spec-kitty orchestrator-api open-decision [OPTIONS]

 Open a new Decision Moment ledger entry, or return idempotently if one already
 exists (FR-006). Wraps ``decisions/service.py.open_decision`` 1:1.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission                 <str>  Mission slug [required]                  │
│ *  --origin                  <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>  Actor identity [required]                │
│    --policy                  <str>  Policy metadata JSON (required)          │
│    --owned-checkout          <str>  Path to a linked owned checkout that     │
│                                     owns this mission (single_branch only);  │
│                                     omit for the repository-root checkout    │
│    --help            -h             Show this message and exit.              │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty orchestrator-api plan

```
 Usage: spec-kitty orchestrator-api plan [OPTIONS]

 Scaffold plan.md for a mission -- an unenriched pass-through of
 ``setup_plan``.

 FR-002 / Clarification 1: deliberately asymmetric with ``specify`` -- the
 host CLI's own ``--json`` path returns ``agent_feature.setup_plan``'s raw
 dict verbatim (``lifecycle.py`` adds no enrichment here), so this verb
 does the same. Do not add fields ``setup_plan`` does not already return.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission          <str>  Mission slug [required]                         │
│    --policy           <str>  Policy metadata JSON (required)                 │
│    --help     -h             Show this message and exit.                     │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty orchestrator-api record-analysis

```
 Usage: spec-kitty orchestrator-api record-analysis [OPTIONS]

 Persist an ``/spec-kitty.analyze`` report, verified against disk (FR-005).

 NFR-004 / SK-93 (verified): a subprocess/call-level success signal
 (return code, "did not raise") is UNTRUSTWORTHY -- SK-93 documented
 ``record-analysis`` reporting a false timeout FAILURE after a write had
 already genuinely succeeded. This verb instead:

 1. Captures ``now_utc_iso()`` immediately before invoking the write path.
 2. Calls ``write_analysis_report``/``commit_for_mission`` directly
    (bypassing ``record_analysis``'s own unbounded dossier-sync trigger
    entirely -- option (a), plan.md § (j)), under an enforced
    :func:`_run_write_with_timeout` bound as defense-in-depth.
 3. Re-reads ``analysis-report.md`` off disk unconditionally afterward.
    ``success: true`` ONLY if BOTH (a) the re-read ``verdict`` matches
    what THIS call submitted, AND (b) the re-read ``generated_at`` is
    STRICTLY LATER than the call-start timestamp -- a verdict-string
    match alone is never sufficient (distinguishes a genuine fresh write
    from a stale, coincidentally-matching pre-existing artifact).

 SK-06 / #3133: an ``unknown`` verdict (no valid ``analysis-findings/v1``
 carrier in the submitted body) is NEVER reported as ``success: true``,
 even when the write genuinely, freshly succeeds -- silently writing
 ``verdict: unknown`` for an explicitly-intended report is this repo's
 dominant failure mode and this verb refuses to propagate it as success.

 A mutating verb: ``--policy`` is required (``POLICY_METADATA_REQUIRED``
 pattern, matching ``specify``/``plan``/``tasks``).

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission             <str>  Mission slug [required]                      │
│    --input-file          <str>  Markdown report path, or '-' to read the     │
│                                 report body from stdin                       │
│                                 [default: -]                                 │
│    --agent               <str>  Agent name that produced the analysis report │
│    --policy              <str>  Policy metadata JSON (required)              │
│    --help        -h             Show this message and exit.                  │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty orchestrator-api resolve-decision

```
 Usage: spec-kitty orchestrator-api resolve-decision [OPTIONS]

 Resolve a decision with a concrete final answer (FR-007). Wraps
 ``decisions/service.py.resolve_decision`` 1:1.

 Terminal-transition rejection (Edge Cases, spec.md): resolving an
 already-terminal decision with a DIFFERENT outcome/payload is NOT
 pre-checked here -- it is the service layer's own
 ``DecisionError(TERMINAL_CONFLICT)``, propagated verbatim, matching the
 host-CLI ``decision_app resolve`` subcommand's own error code. A
 redundant pre-check here could drift from the service layer's own
 validation.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission                 <str>  Mission slug [required]                  │
│ *  --decision-id             <str>  Decision ledger entry ID (ULID)          │
│                                     [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 the                          │
│                                     resolving/deferring/canceling party      │
│                                     (falls back to --actor)                  │
│ *  --actor                   <str>  Actor identity [required]                │
│    --policy                  <str>  Policy metadata JSON (required)          │
│    --owned-checkout          <str>  Path to a linked owned checkout that     │
│                                     owns this mission (single_branch only);  │
│                                     omit for the repository-root checkout    │
│    --help            -h             Show this message and exit.              │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty orchestrator-api resolve-workspace

```
 Usage: spec-kitty orchestrator-api resolve-workspace [OPTIONS]

 Read-only: resolve a WP's lane workspace_path + prompt_path (+ lane fields).

 Does NOT allocate/create/validate-clean/transition — the read-only companion
 of ``start-implementation`` for a WP already past implementation (e.g. a
 ``for_review`` WP an external orchestrator wants to review on resume, where
 calling start-implementation would wrongly re-transition it). Contract >=
 1.2.0.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission          <str>  Mission slug [required]                         │
│ *  --wp               <str>  Work package ID [required]                      │
│    --help     -h             Show this message and exit.                     │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty orchestrator-api specify

```
 Usage: spec-kitty orchestrator-api specify [OPTIONS]

 Create a mission scaffold, matching the host CLI's enriched ``specify --json``
 contract.

 In-process only (FR-001): calls
 ``specify_cli.cli.commands.lifecycle._create_mission_for_specify_json``,
 the SAME enrichment step the host CLI's ``--json`` path runs (adds
 ``scaffold_only``/``spec_state``/``next_action``/``next_step`` on top of
 ``agent_feature.create_mission``'s raw payload) -- never the unenriched
 payload one layer beneath it.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission               <str>                    Mission slug [required]  │
│ *  --mission-type          <str>                    Mission type (e.g.,      │
│                                                     software-dev)            │
│                                                     [required]               │
│    --topology              <single_branch|lanes|co  Mission shape:           │
│                            ord|lanes_with_coord>    single_branch | lanes |  │
│                                                     coord |                  │
│                                                     lanes_with_coord.        │
│                                                     Default (no --topology): │
│                                                     create mints one Mission │
│                                                     topic branch             │
│                                                     (kitty/mission-<slug>-<… │
│                                                     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).  │
│    --policy                <str>                    Policy metadata JSON     │
│                                                     (required)               │
│    --help          -h                               Show this message and    │
│                                                     exit.                    │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty orchestrator-api start-implementation

```
 Usage: spec-kitty orchestrator-api start-implementation [OPTIONS]

 Composite transition: planned->claimed->in_progress (idempotent).

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission          <str>  Mission slug [required]                         │
│ *  --wp               <str>  Work package ID [required]                      │
│ *  --actor            <str>  Actor identity [required]                       │
│    --policy           <str>  Policy metadata JSON (required)                 │
│    --help     -h             Show this message and exit.                     │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty orchestrator-api start-review

```
 Usage: spec-kitty orchestrator-api start-review [OPTIONS]

 Transition a WP from for_review to in_review (reviewer claims review).

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission             <str>  Mission slug [required]                      │
│ *  --wp                  <str>  Work package ID [required]                   │
│ *  --actor               <str>  Actor identity [required]                    │
│    --policy              <str>  Policy metadata JSON (required)              │
│    --review-ref          <str>  Review feedback reference (optional, not     │
│                                 required for for_review→in_review)           │
│    --help        -h             Show this message and exit.                  │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty orchestrator-api tasks

```
 Usage: spec-kitty orchestrator-api tasks [OPTIONS]

 Finalize WP task metadata -- an unenriched pass-through of ``finalize_tasks``.

 FR-003 / Clarification 1: same deliberate asymmetry as ``plan`` -- the
 host CLI's own ``--json`` path returns ``agent_feature.finalize_tasks``'s
 raw dict verbatim, so this verb does the same.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission          <str>  Mission slug [required]                         │
│    --policy           <str>  Policy metadata JSON (required)                 │
│    --help     -h             Show this message and exit.                     │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty orchestrator-api transition

```
 Usage: spec-kitty orchestrator-api transition [OPTIONS]

 Emit a single lane transition for a WP.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission                            <str>  Mission slug [required]       │
│ *  --wp                                 <str>  Work package ID [required]    │
│ *  --to                                 <str>  Target lane [required]        │
│ *  --actor                              <str>  Actor identity [required]     │
│    --note                               <str>  Reason/note for the           │
│                                                transition (required with     │
│                                                --force out of in_review or   │
│                                                approved)                     │
│    --policy                             <str>  Policy metadata JSON          │
│                                                (required for run-affecting   │
│                                                lanes)                        │
│    --force                                     Force the transition          │
│    --review-ref                         <str>  Review reference              │
│    --review-result-json                 <str>  JSON structured review        │
│                                                outcome for transitions from  │
│                                                in_review                     │
│    --evidence-json                      <str>  JSON string with done         │
│                                                evidence                      │
│    --subtasks-complete                         Whether required subtasks are │
│                                                complete for                  │
│                                                in_progress->for_review       │
│    --implementation-evidence-…                 Whether implementation        │
│                                                evidence exists for           │
│                                                in_progress->for_review       │
│    --help                       -h             Show this message and exit.   │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty plan

```
 Usage: spec-kitty plan [OPTIONS]

 Scaffold plan.md for a Mission.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission                 <str>   Mission slug (e.g.,                        │
│                                   001-user-authentication)                   │
│ --json                            Emit JSON result                           │
│ --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 plugin

_Plugin bundle commands_

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

 Plugin bundle commands

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ build  Build a Spec Kitty plugin bundle for a specific target harness.       │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty plugin build

```
 Usage: spec-kitty plugin build [OPTIONS]

 Build a Spec Kitty plugin bundle for a specific target harness.

 The bundle is written to ``<output-dir>/<target>/`` and includes a
 ``plugin.json`` manifest, rendered command skills, and agent profiles.

 Example::

     spec-kitty plugin build --target claude-code
     spec-kitty plugin build --target claude-code --output-dir /tmp/out
     spec-kitty plugin build --target claude-code --skip-validate

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --target                 <str>   Plugin target (claude-code, codex).      │
│                                     [required]                               │
│    --output-dir             <path>  Root directory under which the bundle is │
│                                     written.                                 │
│                                     [default: dist/spec-kitty-plugins]       │
│    --skip-validate                  Skip the 'claude plugin validate         │
│                                     --strict' step.                          │
│    --help           -h              Show this message and exit.              │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty profile-invocation

_Manage invocation records._

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

 Manage invocation records.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ complete  Close an open invocation record. --invocation-id and --outcome are │
│           required.                                                          │
╰──────────────────────────────────────────────────────────────────────────────╯

 Open:  spec-kitty dispatch "<request>"

 Close: spec-kitty profile-invocation complete --invocation-id <id> --outcome
 <outcome>
```

## spec-kitty profile-invocation complete

```
 Usage: spec-kitty profile-invocation complete [OPTIONS]

 Close an open invocation record. --invocation-id and --outcome are required.

 Use --artifact (repeatable) to link output artifacts to this invocation.
 Use --commit (singular) to link the primary git commit produced.
 Use --evidence to promote a file to a Tier 2 evidence artifact.
 Use --co-author to attribute this close's Op commit (overrides
 commit.co_author).
 Note: --evidence is rejected for records that are not execution records.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --invocation-id   -i      <str>   Invocation ULID to close [required]     │
│ *  --outcome                 <str>   done | failed | abandoned [required]    │
│    --evidence                <str>   Path to a UTF-8 text evidence file      │
│                                      (Tier 2 promotion); checked before the  │
│                                      Op closes                               │
│    --artifact                <str>   Path (repo-relative or absolute) or URL │
│                                      of an artifact produced by this         │
│                                      invocation. Repeatable.                 │
│    --commit                  <str>   Git commit SHA most directly produced   │
│                                      by this invocation. Singular.           │
│    --co-author               <str>   Operator attribution trailer for this   │
│                                      Op's auto-commit, as 'Name <email>'.    │
│                                      Overrides the repository's              │
│                                      commit.co_author for this close only.   │
│    --json                            Output JSON payload                     │
│    --owned-checkout          <path>  Keep this Op's record in an owned       │
│                                      checkout: a linked checkout of this     │
│                                      repository. Refuses the repository root │
│                                      checkout, coordination worktrees and    │
│                                      lane worktrees. A record already in     │
│                                      another checkout is closed where it     │
│                                      lives.                                  │
│    --help            -h              Show this message and exit.             │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty profiles

_Manage and list agent profiles._

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

 Manage and list agent profiles.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ list  List agent profiles (activated-only by default; --all for the full     │
│       catalog).                                                              │
│ show  Show the full resolved definition of an agent profile                  │
│       (FR-013/014/015).                                                      │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty profiles list

```
 Usage: spec-kitty profiles list [OPTIONS]

 List agent profiles (activated-only by default; --all for the full catalog).

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json                      Output JSON array.                               │
│ --all                       Show every profile across all source layers      │
│                             (annotated by source layer and                   │
│                             activated|available state). Supersedes the       │
│                             activated-only default and --show-available.     │
│ --show-available            Also show available-but-not-activated profiles   │
│                             (annotated by state).                            │
│ --help            -h        Show this message and exit.                      │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty profiles show

```
 Usage: spec-kitty profiles show [OPTIONS] {profile_id}

 Show the full resolved definition of an agent profile (FR-013/014/015).

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    profile_id      <str>  Profile ID to show. [required]                   │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Output JSON object.                                        │
│ --all             Bypass the activation gate for inspection (show            │
│                   non-activated profiles).                                   │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty reconcile

_Reconcile a mission dossier against its recorded snapshot (exit 0=parity, non-zero=divergence)._

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

 Reconcile a mission dossier against its recorded snapshot (exit 0=parity,
 non-zero=divergence).

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission          <str>  Mission slug to reconcile against its recorded  │
│                              snapshot                                        │
│                              [required]                                      │
│    --json                    Emit a machine-readable JSON result             │
│    --help     -h             Show this message and exit.                     │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty regen

_Regenerate the committed generated agent-command + skill fixtures from source (#3447)._

```
 Usage: spec-kitty regen [OPTIONS]

 Regenerate the committed generated agent-command + skill fixtures from source
 (#3447).

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --check            Do not write; render into memory and byte-compare against │
│                    the committed fixtures. Exit 1 when stale (prints the     │
│                    diff + the exact regen command), 0 when fresh. This is    │
│                    the fork-PR-safe freshness gate — a read-only token       │
│                    cannot commit back, so contributors run `spec-kitty       │
│                    regen` locally and push the result.                       │
│ --json             Emit a machine-readable JSON result instead of text.      │
│ --help   -h        Show this message and exit.                               │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty research

```
 Usage: spec-kitty research [OPTIONS]

 Scaffold research artifacts from the mission type's shipped templates.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission                 <str>   Mission slug to target                     │
│ --force                           Overwrite existing research artifacts      │
│ --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 retrospect

_Retrospective authoring and summary (create / backfill / summary)_

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

 Retrospective authoring and summary (create / backfill / summary)

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ create    Author a retrospective for one completed mission.                  │
│ backfill  Author retrospective records for historical missions in bulk.      │
│ summary   Cross-mission retrospective summary.                               │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty retrospect backfill

_Author retrospective records for historical missions in bulk._

```
 Usage: spec-kitty retrospect backfill [OPTIONS]

 Author retrospective records for historical missions in bulk.

 Iterates completed missions in the given time window and authors
 retrospective.yaml records for those that don't already have one.

 Per-mission failures are NOT fatal; aggregate report shows them.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --since                  <str>  Only consider missions completed on or after │
│                                 this ISO date (default: 30 days ago)         │
│ --until                  <str>  Only consider missions completed on or       │
│                                 before this ISO date (default: now)          │
│ --mission                <str>  Restrict backfill to a single mission handle │
│ --dry-run                       Report what would be authored without        │
│                                 writing                                      │
│ --emit-skipped                  Append a RetrospectiveSkipped event for      │
│                                 skipped missions                             │
│ --emit-failures                 Append RetrospectiveCaptureFailed events for │
│                                 failed missions                              │
│ --json                          Emit a single aggregate JSON object at the   │
│                                 end                                          │
│ --help           -h             Show this message and exit.                  │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty retrospect create

_Author a retrospective for one completed mission._

```
 Usage: spec-kitty retrospect create [OPTIONS]

 Author a retrospective for one completed mission.

 Validates mission completion, resolves policy, runs the generator,
 and writes the record. Use --overwrite or --update to handle existing records.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --mission            <str>  Mission handle (mission_id, mid8, or          │
│                                mission_slug)                                 │
│                                [required]                                    │
│    --overwrite                 Replace an existing record (mutually          │
│                                exclusive with --update)                      │
│    --update                    Merge into an existing record (mutually       │
│                                exclusive with --overwrite)                   │
│    --json                      Emit structured JSON output instead of Rich   │
│                                rendering                                     │
│    --help       -h             Show this message and exit.                   │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty retrospect summary

_Cross-mission retrospective summary._

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

 Cross-mission retrospective summary.

 Reads kitty-specs/*/retrospective.yaml and kitty-specs/*/status.events.jsonl
 to produce a cross-mission view.

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

 No mutation is performed.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --project                    <path>                  Project root (default:  │
│                                                      current working         │
│                                                      directory)              │
│ --json                                               Emit JSON to stdout     │
│                                                      instead of Rich         │
│                                                      rendering               │
│ --json-out                   <path>                  Also write JSON to this │
│                                                      file path               │
│ --limit                      <int range>             Top-N for ranked        │
│                              [1<=x<=100]             sections (default: 20)  │
│                                                      [default: 20]           │
│ --since                      <str>                   ISO-8601 date; only     │
│                                                      include missions        │
│                                                      started on or after     │
│                                                      DATE                    │
│ --include-malformed                                  Include malformed       │
│                                                      record detail in output │
│ --filter                     <str>                   Only show missions in   │
│                                                      this record state       │
│                                                      (has_findings|ran_no_f… │
│ --help               -h                              Show this message and   │
│                                                      exit.                   │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty review

```
 Usage: spec-kitty review [OPTIONS]

 Validate a merged mission: WP lane check, dead-code scan, BLE001 audit.

 Writes kitty-specs/<slug>/mission-review-report.md with a machine-readable
 verdict. A previous machine report there is replaced; any other file there
 (an agent-written review, say) is left alone and the command refuses with
 MISSION_REVIEW_REPORT_PATH_OCCUPIED.  See module docstring for known
 false-positive scenarios in the dead-code scan step.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission          <str>  Mission handle (id, mid8, or slug).                │
│ --mode             <str>  Review mode: 'lightweight' (consistency check      │
│                           only) or 'post-merge' (full release-gate           │
│                           contract). Auto-detected from                      │
│                           meta.json.baseline_merge_commit when omitted.      │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty safe-commit

```
 Usage: spec-kitty safe-commit [OPTIONS] {files}...

 Commit only the requested files via Spec Kitty's safe-commit path.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    files      <path>  Files or directories to commit, relative to the      │
│                         current worktree root or absolute. Directory         │
│                         arguments expand to their contained                  │
│                         changed/untracked files with an explicit expansion   │
│                         report.                                              │
│                         [required]                                           │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --message    -m      <str>  Commit message. Repeat -m to add paragraphs   │
│                                (joined by a blank line, the same way git     │
│                                does).                                        │
│                                [required]                                    │
│    --to-branch          <str>  Short branch name the commit must land on.    │
│                                The helper asserts HEAD matches this branch   │
│                                before staging. When omitted, the current     │
│                                HEAD branch is used (deprecated; --to-branch  │
│                                becomes required in v3.3). This is the only   │
│                                destination authority — no env-var inference. │
│    --json                      Output JSON                                   │
│    --help       -h             Show this message and exit.                   │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty service

_Fetch, vendor, inspect and stop the pinned service binaries_

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

 Fetch, vendor, inspect and stop the pinned service binaries

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ fetch   Fetch and verify the pinned build of a service for this host into    │
│         the cache.                                                           │
│ status  Show the pin, the cache state and the running instance of a service  │
│         (reads only: starts, writes and evicts nothing).                     │
│ stop    Stop this clone's running instance of a service.                     │
│ vendor  Bump (or --check) pins/<service>.source.yaml from the service's own  │
│         release; the only way to change a pin.                               │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty service fetch

```
 Usage: spec-kitty service fetch [OPTIONS]

 Fetch and verify the pinned build of a service for this host into the cache.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --service          <str>  The service: one of charter-service, read-service, │
│                           write-service.                                     │
│                           [default: write-service]                           │
│ --all                     Every pinned service this CLI launches (the        │
│                           CI-only read service only with --service).         │
│ --offline                 Never download: use the cache or                   │
│                           SPEC_KITTY_SERVICE_ASSET_DIR only.                 │
│ --json                    Print JSON.                                        │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty service status

```
 Usage: spec-kitty service status [OPTIONS]

 Show the pin, the cache state and the running instance of a service (reads
 only: starts, writes and evicts nothing).

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --service          <str>  The service: one of charter-service, read-service, │
│                           write-service.                                     │
│                           [default: write-service]                           │
│ --json                    Print JSON.                                        │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty service stop

```
 Usage: spec-kitty service stop [OPTIONS]

 Stop this clone's running instance of a service.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --service          <str>  The service: one of charter-service, read-service, │
│                           write-service.                                     │
│                           [default: write-service]                           │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty service vendor

```
 Usage: spec-kitty service vendor [OPTIONS]

 Bump (or --check) pins/<service>.source.yaml from the service's own release;
 the only way to change a pin.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --service                    <str>  The service: one of charter-service,     │
│                                     read-service, write-service.             │
│                                     [default: write-service]                 │
│ --tag                        <str>  The service's release tag to pin         │
│                                     (service-vX.Y.Z).                        │
│ --repository                 <str>  The service's release repository         │
│                                     (https:// or file://); default: the      │
│                                     current pin's, else the service's own    │
│                                     (spec-kitty-charter for charter-service, │
│                                     spec-kitty-events for the events         │
│                                     services).                               │
│ --commit                     <str>  The commit the tag names. Required for a │
│                                     file:// repository (no git remote to     │
│                                     ask); for https:// it must match the     │
│                                     tag.                                     │
│ --protocol-versions          <str>  Comma-separated protocol majors the      │
│                                     build speaks (default 1); must match the │
│                                     release notes.                           │
│ --check                             Verify the lockfile instead of bumping   │
│                                     it: shape rules, and online the          │
│                                     release's SHA256SUMS. Writes nothing.    │
│ --offline                           With --check: the shape rules only, no   │
│                                     network.                                 │
│ --asset-prefix               <str>  The release name prefix of this          │
│                                     service's builds                         │
│                                     (<prefix>-<ver>-<target>,                │
│                                     <prefix>-<ver>.jar); default: the        │
│                                     service's known prefix.                  │
│ --no-attestation                    Skip the release's build-provenance      │
│                                     check (`gh attestation verify`, signer   │
│                                     workflow and source tag ref). Only for   │
│                                     an offline mirror or a rehearsal; never  │
│                                     for a real bump.                         │
│ --help               -h             Show this message and exit.              │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty session-start

_Emit spec-kitty orientation for the Claude Code SessionStart hook._

```
 Usage: spec-kitty session-start [OPTIONS]

 Emit spec-kitty orientation for the Claude Code SessionStart hook.

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

## spec-kitty session-stop

_Emit the open-Ops reminder for the Claude Code Stop hook._

```
 Usage: spec-kitty session-stop [OPTIONS]

 Emit the open-Ops reminder for the Claude Code Stop hook.

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

## spec-kitty spec-commit

```
 Usage: spec-kitty spec-commit [OPTIONS] {files}...

 Commit spec artifacts to the mission's resolved placement.

 SPEC is a primary/planning artifact: it lands on the mission's primary target
 branch for every topology. On an unprotected or flattened primary the commit
 is direct. On a PROTECTED primary the commit is refused (there is no fallback
 surface); recover by either creating/checking out a non-protected feature
 branch ('spec-kitty agent mission create --start-branch <topic-branch>') or
 setting SPEC_KITTY_ALLOW_PROTECTED_BRANCH_COMMITS=1 to commit on the current
 branch.

 Pass individual FILES, not directories.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    files      <path>  Spec artifacts to commit (absolute or relative       │
│                         paths). Must belong to the mission resolved via      │
│                         --mission or the kitty-specs/<slug>/ path.           │
│                         [required]                                           │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --message         -m      <str>   Commit message. Repeat -m to add        │
│                                      paragraphs (joined by a blank line, the │
│                                      same way git does).                     │
│                                      [required]                              │
│    --mission                 <str>   Mission slug (e.g. '001-my-mission').   │
│                                      When omitted, the slug is derived from  │
│                                      the first file argument's               │
│                                      kitty-specs/<slug>/ path.               │
│    --target-branch           <str>   Short TARGET branch name for this       │
│                                      Mission (not the repository-root        │
│                                      checkout). Passed to the commit router  │
│                                      for placement resolution and, on an     │
│                                      --owned-checkout run, as the owned      │
│                                      checkout's target override. No longer   │
│                                      used for a post-commit fast-forward --  │
│                                      that best-effort advance was retired    │
│                                      (FR-008). Optional.                     │
│    --json                            Output 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 specify

```
 Usage: spec-kitty specify [OPTIONS] {mission}

 Create a Mission scaffold in kitty-specs/.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    mission      <str>  Mission name or slug (e.g., user-authentication)    │
│                          [required]                                          │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission-type          <str>                     Mission type (e.g.,        │
│                                                   software-dev, research)    │
│ --topology              <single_branch|lanes|coo  Mission shape:             │
│                         rd|lanes_with_coord>      single_branch | lanes |    │
│                                                   coord | lanes_with_coord.  │
│                                                   Default (no --topology):   │
│                                                   create mints one Mission   │
│                                                   topic branch               │
│                                                   (kitty/mission-<slug>-<mi… │
│                                                   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).            │
│ --json                                            Emit JSON result           │
│ --help          -h                                Show this message and      │
│                                                   exit.                      │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty tasks

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

 Finalize tasks metadata after task generation.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission          <str>  Mission slug (e.g., 001-user-authentication)       │
│ --json                    Emit JSON result                                   │
│ --help     -h             Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty tracker

_Task tracker commands_

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

 Task tracker commands

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ providers  List supported tracker providers.                                 │
│ bind       Bind the current project to a local issue tracker (beads, fp).    │
│ status     Show tracker binding and sync status.                             │
│ unbind     Remove tracker binding for this project.                          │
│ map        Work-package mapping commands                                     │
│ sync       Tracker synchronization commands                                  │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty tracker bind

```
 Usage: spec-kitty tracker bind [OPTIONS]

 Bind the current project to a local issue tracker (beads, fp).

 Requires --provider and --workspace; --credential supplies connector
 credentials stored locally.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --provider                <str>  Provider name (beads, fp) [required]     │
│    --workspace               <str>  Provider workspace/team/project          │
│                                     identifier                               │
│    --ownership-mode          <str>  Ownership mode: external_authoritative | │
│                                     spec_kitty_authoritative |               │
│                                     split_ownership                          │
│    --field-owner             <str>  Split ownership mapping: field=owner     │
│    --credential              <str>  Provider credential key/value: key=value │
│    --help            -h             Show this message and exit.              │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty tracker map

_Work-package mapping commands_

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

 Work-package mapping commands

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ add   Add or update a WP-to-external issue mapping.                          │
│ list  List tracker mappings from the local SQLite database.                  │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty tracker map add

```
 Usage: spec-kitty tracker map add [OPTIONS]

 Add or update a WP-to-external issue mapping.

 Stores the mapping in the local SQLite database.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --wp-id                 <str>  Work package ID (e.g., WP01) [required]    │
│ *  --external-id           <str>  External issue ID [required]               │
│    --external-key          <str>  External issue key                         │
│    --external-url          <str>  External issue URL                         │
│    --help          -h             Show this message and exit.                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty tracker map list

```
 Usage: spec-kitty tracker map list [OPTIONS]

 List tracker mappings from the local SQLite database.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Render mappings as JSON                                    │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty tracker providers

```
 Usage: spec-kitty tracker providers [OPTIONS]

 List supported tracker providers.

 Local providers use direct connectors with locally stored credentials. The
 former SaaS/hosted providers (linear, jira, github, gitlab) are no longer
 supported (#6164) and are listed only to explain the refusal a bind for one
 of them produces.

 This command is purely informational and prints the hard-coded provider
 categories.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Render provider list as JSON                               │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty tracker status

```
 Usage: spec-kitty tracker status [OPTIONS]

 Show tracker binding and sync status.

 Displays local cache statistics and configuration for the bound local
 provider.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Render status as JSON                                      │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty tracker sync

_Tracker synchronization commands_

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

 Tracker synchronization commands

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ pull     Pull tracker updates into the local cache via the direct connector. │
│ push     Push local mutations to the upstream provider via the direct        │
│          connector.                                                          │
│ run      Run pull+push synchronization in one operation via the direct       │
│          connector.                                                          │
│ publish  Publish local tracker snapshot.                                     │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty tracker sync publish

```
 Usage: spec-kitty tracker sync publish [OPTIONS]

 Publish local tracker snapshot.

 Local providers (beads/fp) have no snapshot-publish transport; the facade
 raises a clean error directing the operator to ``tracker sync push``.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json            Render publish result as JSON                              │
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty tracker sync pull

```
 Usage: spec-kitty tracker sync pull [OPTIONS]

 Pull tracker updates into the local cache via the direct connector.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --limit          <int range> [1<=x<=10000]  [default: 100]                   │
│ --json                                      Render sync result as JSON       │
│ --help   -h                                 Show this message and exit.      │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty tracker sync push

```
 Usage: spec-kitty tracker sync push [OPTIONS]

 Push local mutations to the upstream provider via the direct connector.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --limit          <int range> [1<=x<=10000]  Max items [default: 100]         │
│ --json                                      Render sync result as JSON       │
│ --help   -h                                 Show this message and exit.      │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty tracker sync run

```
 Usage: spec-kitty tracker sync run [OPTIONS]

 Run pull+push synchronization in one operation via the direct connector.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --limit          <int range> [1<=x<=10000]  [default: 100]                   │
│ --json                                      Render sync result as JSON       │
│ --help   -h                                 Show this message and exit.      │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty tracker unbind

```
 Usage: spec-kitty tracker unbind [OPTIONS]

 Remove tracker binding for this project.

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

## spec-kitty upgrade

```
 Usage: spec-kitty upgrade [OPTIONS]

 Upgrade a Spec Kitty project to the current version.

 Detects the project's current version and applies all necessary migrations
 to bring it to the installed CLI version.

 **New flags (WP09)**:
   ``--cli``     Emit CLI upgrade guidance only.  No project detection;
                 succeeds outside any project (FR-014).
   ``--project`` Run project migrations only; suppresses CLI nag.
                 Errors outside a project.
   ``--yes``/``-y``  Non-interactive confirmation (alias for ``--force``).
                     Does NOT bypass schema-incompatibility blocks
 (CHK037/A-006).
   ``--no-nag``  Suppress upgrade-nag banner even when a CLI update exists.

 Mutual exclusion: ``--cli`` and ``--project`` together exit 2.

 **Exit codes** (R-08):
   0  Success / ALLOW / ALLOW_WITH_NAG / a completed ``--dry-run`` preview
   2  ``--cli --project`` flag conflict; ``--no-worktrees`` or ``--cli``
      combined with ``--include-worktree`` / ``--all-worktrees``; an
      ``--include-worktree`` path that is not a worktree directly under
      ``.worktrees/`` (UPGRADE_WORKTREE_NOT_FOUND)
   4  Project migration required (BLOCK_PROJECT_MIGRATION)
   5  Project is too new for this CLI (BLOCK_CLI_UPGRADE) — not bypassable
   6  Project metadata corrupt (BLOCK_PROJECT_CORRUPT)
   1  General error, a managed file left for your review, or a ``--dry-run``
      preview that could not be completed

 See also: ``docs/guides/how-to/installation/install-and-upgrade.md``

 Examples:
     spec-kitty upgrade              # Upgrade to current version
     spec-kitty upgrade --dry-run    # Preview changes
     spec-kitty upgrade --target 0.6.5  # Upgrade to specific version
     spec-kitty upgrade --cli        # Show CLI upgrade hint, no project needed
     spec-kitty upgrade --project    # Project migrations only
     spec-kitty upgrade --yes        # Non-interactive (same as --force)
     spec-kitty upgrade --dry-run --json  # Machine-readable plan

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --dry-run                           Preview changes without applying         │
│ --force                             Skip confirmation prompts                │
│ --target                    <str>   Target version (defaults to current CLI  │
│                                     version)                                 │
│ --json                              Output results as JSON                   │
│ --plan-json                         Output the complete preview plan as JSON │
│ --verbose           -v              Show detailed migration information      │
│ --no-worktrees                      Skip upgrading worktrees                 │
│ --include-worktree          <path>  Upgrade and commit into this non-Mission │
│                                     worktree (repeatable)                    │
│ --all-worktrees                     Upgrade and commit into every            │
│                                     non-Mission worktree under .worktrees/   │
│ --cli                               Restrict to CLI guidance only; works     │
│                                     outside any project (FR-014)             │
│ --project                           Restrict to current-project compat +     │
│                                     migrations (FR-015)                      │
│ --yes               -y              Non-interactive confirmation; alias for  │
│                                     --force (FR-017). Upgrade never runs the │
│                                     mission-state repair; use `spec-kitty    │
│                                     doctor mission-state --fix`.             │
│ --no-nag                            Suppress upgrade-nag output explicitly   │
│ --help                              Show this message and exit.              │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty validate-encoding

```
 Usage: spec-kitty validate-encoding [OPTIONS]

 Validate and optionally fix file encoding in feature artifacts.

 Scans markdown files for Windows-1252 smart quotes and other problematic
 characters that cause UTF-8 encoding errors. Can automatically fix issues
 by replacing problematic characters with safe alternatives.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission                     <str>  Mission slug to validate                │
│ --fix                                Automatically fix encoding errors by    │
│                                      sanitizing files                        │
│ --all                                Check all features, not just one        │
│ --backup       --no-backup           Create .bak files before fixing         │
│                                      [default: backup]                       │
│ --help     -h                        Show this message and exit.             │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty validate-tasks

```
 Usage: spec-kitty validate-tasks [OPTIONS]

 LEGACY: Validate and repair directory/frontmatter lane mismatches.

 This command is for legacy projects that used directory-based lanes
 (tasks/planned/, tasks/doing/, etc.). Modern projects (3.0+) use
 flat tasks/ directories with canonical status in status.events.jsonl.

 For modern projects, use `spec-kitty agent mission finalize-tasks`
 to ensure canonical status state exists.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission            <str>  Mission slug to validate                         │
│ --fix                       Automatically repair metadata inconsistencies    │
│ --all                       Check all features, not just one                 │
│ --agent              <str>  Agent name for activity log                      │
│ --shell-pid          <str>  Shell PID for activity log                       │
│ --help       -h             Show this message and exit.                      │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty verify-setup

```
 Usage: spec-kitty verify-setup [OPTIONS]

 Verify that the current environment matches Spec Kitty expectations.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission              <str>  Mission slug to verify                         │
│ --json                        Output in JSON format for AI agents            │
│ --check-files                 Check mission file integrity [default: True]   │
│ --check-tools                 Check for installed development tools          │
│                               [default: True]                                │
│ --diagnostics                 Show detailed project diagnostics              │
│ --help         -h             Show this message and exit.                    │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty workflow

_Manage mission workflow definitions_

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

 Manage mission workflow definitions

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ list    List workflow ids available to a project.                            │
│ export  Export a resolvable workflow YAML file.                              │
│ import  Import a workflow YAML into `.kittify/overrides/workflows`.          │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty workflow export

```
 Usage: spec-kitty workflow export [OPTIONS] {workflow_id} {output}

 Export a resolvable workflow YAML file.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    workflow_id      <str>   Workflow id to export. [required]              │
│ *    output           <path>  Destination file or directory. [required]      │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --project-root          <path>  Project root used for .kittify workflow      │
│                                 discovery.                                   │
│                                 [default: .]                                 │
│ --force                         Overwrite an existing destination file.      │
│ --help          -h              Show this message and exit.                  │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty workflow import

```
 Usage: spec-kitty workflow import [OPTIONS] {source}

 Import a workflow YAML into `.kittify/overrides/workflows`.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    source      <path>  Workflow YAML file to import. [required]            │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --project-root          <path>  Project root that receives the workflow      │
│                                 override.                                    │
│                                 [default: .]                                 │
│ --force                         Overwrite an existing workflow file.         │
│ --help          -h              Show this message and exit.                  │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## spec-kitty workflow list

```
 Usage: spec-kitty workflow list [OPTIONS]

 List workflow ids available to a project.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --project-root          <path>  Project root used for .kittify workflow      │
│                                 discovery.                                   │
│                                 [default: .]                                 │
│ --help          -h              Show this message and exit.                  │
╰──────────────────────────────────────────────────────────────────────────────╯
```
<!-- END GENERATED -->

## Related

- [Bulk-edit gate reference](/api/bulk-edit-gate.md)
- [finalize-tasks internals reference](/api/finalize-tasks-internals.md)
- [Issue-Matrix Verdict Reference](/development/reference/issue-matrix-verdicts.md)
