---
type: "API"
title: "Profile Invocation Reference"
description: "Reference for dispatch, profile-invocation complete, invocation trail fields, and lifecycle states."
status: "stable"
generated:
  by: "process:dockitty-export"
  at: "2026-11-01T00:00:00Z"
---

# Profile Invocation Reference

Profile invocation is the local audit-trail mechanism used by standalone
`spec-kitty dispatch` calls. Each dispatch loads Charter context, opens an Op,
and writes an append-only JSONL record. For an explanation of the model, see
[Understanding Governed Profile Invocation](/architecture/governed-profile-invocation.md).

`spec-kitty next` is the canonical mission loop. In the current 3.2.x CLI it
issues governed prompt files and separate mission-step lifecycle records; it
does not open these standalone Op JSONL files directly.

---

## spec-kitty dispatch

**Synopsis**: `spec-kitty dispatch [OPTIONS] REQUEST`

**Description**: Dispatch a natural-language request to a governed Op. The
router picks the best profile by default. Pass `--profile` only when the caller
has a specific profile in mind or needs to bypass routing.

| Argument/Flag | Description |
|---|---|
| `REQUEST` | Natural-language request [required] |
| `--profile TEXT` | Optional profile ID; bypasses routing |
| `--json` | Output JSON payload |
| `--dry-run` | Route the request only; no Op is opened and nothing is written |
| `--owned-checkout PATH` | Keep the Op record in this owned checkout (a linked checkout of the repository) instead of the checkout the command runs in. The repository root checkout is refused. |

**Example**:
```bash
uv run spec-kitty dispatch "Review this implementation approach" --json
uv run spec-kitty dispatch "Implement token validation" --profile implementer-ivan --json
```

### How routing picks a profile

`dispatch` stops at the first signal that matches. `--profile <id>`, when given,
bypasses the router entirely. Otherwise a canonical verb in the request (`review`,
`implement`, `plan`, …) selects every profile with that role; failing that, a
profile's declared domain keywords are consulted.

Documentation-artifact nouns — `adr`, `docs`, `documentation`, `docstring`,
`readme`, `changelog`, `guide`, `handbook`, `tutorial` — belong to the
documentation domain, so a docs-maintenance request routes without `--profile`.
Bare `index` is deliberately not a documentation signal: "index the invoice
table" is a database request, not a docs request.

A declared keyword or canonical verb containing a space or hyphen
(`knowledge base`, `transcribe-notes`) matches its own words as a phrase. That
phrase pass, and the documentation vocabulary above, run only when no literal
single-word keyword matched, so adding that vocabulary can never move a request
that already routed.

### When routing refuses

Two refusals are possible, and both exit 1:

- `ROUTER_NO_MATCH` — nothing matched. `candidates` lists up to three profiles
  sharing at least one word with the request, ordered by overlap, then routing
  priority, then profile id; each entry carries `profile_id`, `action`,
  `match_reason` and a `partial` confidence. When nothing overlaps, `candidates`
  is empty rather than inventing a closest match.
- `ROUTER_AMBIGUOUS` — several profiles tied. `candidates` lists the tied
  profiles and the router does not pick a winner.

Both carry a `suggestion` with a runnable remedy. Without `--json` the refusal
prints the error code, one line per candidate and the remedy as text; with
`--json` it prints the five-key `routing_failed` envelope (`error`,
`error_code`, `message`, `candidates`, `suggestion`).

```bash
uv run spec-kitty dispatch "mark ADR-0068 Accepted and regenerate the ADR index" --dry-run --json
uv run spec-kitty dispatch "reticulate the splines" --profile curator-carla
uv run spec-kitty profiles list
```

`--dry-run` keeps its own contract: a routed request returns the exit-0
`dry_run` payload including `alternatives`, and a `ROUTER_AMBIGUOUS` request
keeps that exit-0 payload; only `ROUTER_NO_MATCH` exits 1.

---

## spec-kitty profile-invocation complete

**Synopsis**: `spec-kitty profile-invocation complete [OPTIONS]`

**Description**: Close an open invocation record. This is the signal that closes
the invocation trail. Call it when execution finishes to append a `completed`
event to the trail file.

| Flag | Description |
|---|---|
| `--invocation-id`, `-i TEXT` | Invocation ULID to close [required] |
| `--outcome TEXT` | `done`, `failed`, or `abandoned` [required] |
| `--evidence TEXT` | Path to a UTF-8 text evidence file (Tier 2 promotion). Accepted for evidence-eligible records. |
| `--artifact TEXT` | Path to an artifact produced by this invocation (repeatable) |
| `--commit TEXT` | Git commit SHA most directly produced by this invocation (singular) |
| `--json` | Output JSON payload |
| `--owned-checkout PATH` | Look for the Op record in this owned checkout first (a linked checkout of the repository) instead of the checkout the command runs in. The repository root checkout is refused. |

**Example**:
```bash
uv run spec-kitty profile-invocation complete \
  --invocation-id 01KQABCDEF1234567890 \
  --outcome done \
  --artifact docs/guides/my-guide.md \
  --commit abc123def456

uv run spec-kitty profile-invocation complete \
  --invocation-id 01KQABCDEF1234567890 \
  --outcome failed
```

---

## Invocation Trail Fields

Trail records are stored in `kitty-ops/{invocation_id}.jsonl`. Each file
contains a `started` event and, once closed, a `completed` event. It may also
contain additional append-only events such as `glossary_checked`,
`artifact_link`, or `commit_link`.

### started event fields

| Field | Type | Description |
|---|---|---|
| `invocation_id` | ULID string | Unique identifier for this invocation |
| `event` | string | `started` |
| `profile_id` | string | Resolved profile identifier |
| `action` | string | Action token resolved for governance context |
| `request_text` | string | Natural-language request supplied to `dispatch` |
| `governance_context_hash` | string | First 16 hex characters of the rendered Charter context SHA-256 |
| `governance_context_available` | boolean | Whether Charter context was available when the record was opened |
| `actor` | string | Caller identity such as `operator`, `claude`, or `codex` |
| `router_confidence` | string/null | Router confidence for auto-routed requests |
| `started_at` | ISO 8601 timestamp | When the invocation was opened |
| `mode_of_work` | string | `task_execution`, `mission_step`, or `query` |
| `mission_id`, `wp_id` | string/null | Mission-scoped dispatch context, when supplied |

**No model identifier is recorded (#7013).** `actor` is the harness key and the
only runtime identity the record carries. Records written before this change may
still hold `model_id`; they are immutable history, still readable, and never
rewritten.

### completed event fields

| Field | Type | Description |
|---|---|---|
| `event` | string | `completed` |
| `invocation_id` | ULID string | Matches the `started` event |
| `outcome` | string | `done`, `failed`, or `abandoned` |
| `completed_at` | ISO 8601 timestamp | When `profile-invocation complete` was called |
| `closed_by` | string | `agent` or `doctor_sweep` |
| `evidence_ref` | string/null | Evidence path or text supplied with `--evidence` |

### correlation events

When `--artifact` or `--commit` is supplied to `profile-invocation complete`,
the CLI appends separate correlation events after the completed record:

| Event | Key fields | Description |
|---|---|---|
| `artifact_link` | `kind`, `ref`, `at` | Repo-relative or absolute artifact reference |
| `commit_link` | `sha`, `at` | Primary git commit SHA |

---

## Lifecycle States

An invocation passes through two durable states:

1. **open**: A `started` event has been written. The invocation ID is
   available. Execution has not yet completed.
2. **closed**: `profile-invocation complete` has been called. A `completed`
   event with the final outcome is appended to the trail file.

An invocation that was opened but never completed is stale. Use
`spec-kitty invocations list` to find open records. It lists the records of the
checkout it runs in; pass `--owned-checkout PATH` to list those kept in an owned
checkout instead.

---

## Mode-of-work Enforcement

`--evidence` on `profile-invocation complete` is enforced against the
invocation's `mode_of_work`. Attempting to promote evidence on a non-eligible
record results in `InvalidModeForEvidenceError`, and no write occurs. Re-run
`complete` without `--evidence` to close the invocation cleanly.

Evidence must be UTF-8 text. A file that is not (for example a PNG screenshot),
or inline text that cannot be encoded as UTF-8, is refused **before any write**
with `complete_failed` (exit 1) and the message "No completion was recorded".
The invocation stays open, so re-run `complete` with a text evidence file. A
path that cannot be read, or a relative path that escapes the repository, is
still stored as the inline text you passed.

| mode_of_work | Tier 2 evidence (`--evidence`) eligible |
|---|---|
| `task_execution` | Yes |
| `mission_step` | Yes |
| `query` | No |

---

## Example Trail Record

```jsonl
{"event":"started","invocation_id":"01KQA1B2C3D4E5F6G7H8J9K0","profile_id":"implementer-ivan","action":"implement","request_text":"Implement token validation","governance_context_hash":"0123abcd4567ef89","governance_context_available":true,"actor":"operator","started_at":"2026-04-29T10:00:00Z","mode_of_work":"task_execution"}
{"event":"completed","invocation_id":"01KQA1B2C3D4E5F6G7H8J9K0","completed_at":"2026-04-29T10:45:00Z","outcome":"done","closed_by":"agent"}
{"event":"artifact_link","invocation_id":"01KQA1B2C3D4E5F6G7H8J9K0","kind":"artifact","ref":"src/auth/token.py","at":"2026-04-29T10:45:02Z"}
{"event":"commit_link","invocation_id":"01KQA1B2C3D4E5F6G7H8J9K0","sha":"abc123def456789","at":"2026-04-29T10:45:03Z"}
```

---

## See Also

- [Understanding Governed Profile Invocation](/architecture/governed-profile-invocation.md)
- [How to Run a Governed Mission](/guides/how-to/governance/run-governed-mission.md)
- [How Charter Works](/context/charter-overview.md)

## Related

- [How Charter Works](/context/charter-overview.md)
