---
type: "Architecture"
title: "Trail Model"
description: "Operator reference for the Phase 4 trail model: how every standalone spec-kitty dispatch writes an auditable JSONL trail for accountability, SaaS coherence, and provenance."
status: "stable"
generated:
  by: "process:dockitty-export"
  at: "2026-11-10T00:00:00Z"
---

# Trail Model

*Operator reference for the Phase 4 runtime consumption baseline.*

## Overview

Every standalone Spec Kitty dispatch leaves an auditable trail. The trail serves three purposes:

1. **Local accountability**: operators can reconstruct what happened on any checkout without SaaS connectivity.
2. **Hosted coherence (design intent)**: a hosted timeline could show the same history as the local audit log. No hosted projection path is live today; see [SaaS Read-Model Policy](#saas-read-model-policy).
3. **Governance provenance**: downstream retrospective and doctrine work can reference specific invocations.

## minimal viable trail

**One JSONL file per invocation, written locally before the executor returns.**

Every `spec-kitty dispatch "<request>"` call writes a `started` event to:

```
kitty-ops/{invocation_id}.jsonl
```

When `spec-kitty profile-invocation complete` is called, a `completed` event is appended to the same file.

This is the unconditional minimum — it is always written, regardless of SaaS connectivity, charter state, or sync configuration. The data model is defined in `src/specify_cli/invocation/record.py`.

Mission-scoped dispatchers may also record `mission_id` and `wp_id` on the
`started` event. An implement or review claim that supplies `--invocation-id`
treats those values as a provenance assertion: the requested ULID and the
record's embedded ID, mission, WP, action and profile must agree exactly.

**No model identifier is recorded (#7013).** `actor` carries the harness key
(`claude`, `codex`, …) and is the only runtime identity a committed record holds.
The router's catalog pick stays advisory on the dispatch payload and is never
written into the journal, because a committed artifact may not carry an AI model
identifier. A claim therefore has no durable evidence for a resolved model: it
refuses `--model` and records the model slot as explicitly absent
(`RESOLVED_MODEL_ABSENT` in the WP's status snapshot) rather than fabricating one.

**Records written before #7013 still carry `model_id`, and they stay that way.**
`kitty-ops/<ULID>.jsonl` is an immutable archive root (the
historical-preservation gate), so no migration rewrites them; they keep parsing
because the record model ignores keys it no longer declares, and nothing copies
the value forward into a new record.

## Mode-of-Work Taxonomy

Every invocation belongs to one of four work modes. The mode determines which optional trail tiers are eligible — it does not override the mandatory Tier 1 rule.

| Mode | Description | Example actions | Tier 2 eligible | Tier 3 eligible |
|------|-------------|-----------------|-----------------|-----------------|
| `task_execution` | Standalone governed work, including advice, review, code changes, and test runs | `dispatch` | Yes (caller-triggered) | No |
| `mission_step` | One step in a governed mission workflow | `specify`, `plan`, `tasks`, `merge`, `accept` | Yes (caller-triggered) | Yes |
| `query` | Read-only, no execution | `profiles list`, `invocations list` | No | No |

Mode-of-work is recorded on the `started` event as the `mode_of_work` field. New standalone dispatch records use `task_execution`. Runtime enforcement is active: `profile-invocation complete --evidence` is rejected for records that are not evidence-eligible (see "Mode Enforcement at Tier 2 Promotion" below).

### Mode Enforcement at Tier 2 Promotion

`spec-kitty profile-invocation complete --evidence <path>` is rejected with `InvalidModeForEvidenceError` when the target invocation is not evidence-eligible. The enforcement runs **before** any write, so the invocation remains open and uncommitted — rerun `complete` without `--evidence` to close cleanly. Unsupported evidence (not UTF-8 text) is likewise rejected before any write, with `UnsupportedEvidenceError` surfacing as `complete_failed` (exit 1).

Pre-mission records (invocations opened before this enforcement landed) have no `mode_of_work` field and are accepted by enforcement — legacy behaviour is preserved. See ADR-002-mode-derivation.md for the full derivation table and rationale.

## Trail Tiers

### Tier 1 — Every Invocation (mandatory)

Written unconditionally before the executor returns.

- **Storage**: `kitty-ops/{invocation_id}.jsonl`
- **Content**: Two JSONL lines — a `started` event and (after completion) a `completed` event.
- **When**: All standalone `dispatch` invocations.

### Glossary Check Event (conditional, Tier 1)

When the invocation executor's glossary chokepoint scan detects at least one
conflict — or encounters an error — it appends a `glossary_checked` event to the
same Tier 1 JSONL file, immediately after the `started` event.

**Written ONLY when:**
- `all_conflicts` is non-empty (one or more semantic conflicts detected), OR
- `error_msg` is non-null (the chokepoint scan encountered an unexpected exception).

**Clean invocations produce NO `glossary_checked` line.** This keeps Tier 1
files minimal when there are no glossary issues to report.

Example `glossary_checked` event line:

```json
{"event": "glossary_checked", "invocation_id": "01HXYZ...", "matched_urns": ["glossary:d93244e7"], "high_severity": [{"term": "lane", "conflict_type": "ambiguous_scope", "severity": "HIGH", "candidate_senses": ["execution lane (WP routing)", "git branch lane (worktree)"]}], "all_conflicts": [...], "tokens_checked": 8, "duration_ms": 2.7, "error_msg": null}
```

Readers that encounter `"event": "glossary_checked"` and do not recognise this
event type may safely skip the line — it is additive metadata and never affects
the `started`/`completed` pair.

### Correlation Links (Tier 1 extension)

`spec-kitty profile-invocation complete` accepts two additional flags that append correlation events to the invocation JSONL:

- `--artifact <path>` — repeatable. Each value appends one `{event: "artifact_link", invocation_id, kind, ref, at}` line to `kitty-ops/<id>.jsonl`. Refs are stored repo-relative when the resolved path is under the checkout, absolute otherwise.
- `--commit <sha>` — singular. Appends one `{event: "commit_link", invocation_id, sha, at}` line.

Both events are append-only (never mutate existing lines) and readable by a single-file scan. Readers that do not recognise these event types may safely skip the line — the same additive-reader invariant that protects `glossary_checked`.

**SaaS projection status**: Correlation events are **local-only**. The projection policy (`POLICY_TABLE` in `src/specify_cli/invocation/projection_policy.py`) assigns `project=True` for `task_execution` / `mission_step` correlation events, but no SaaS client is registered (see [SaaS Read-Model Policy](#saas-read-model-policy)), so nothing leaves the checkout.

See ADR-001-correlation-contract.md for the design; contracts/profile-invocation-complete.md for the CLI shape.

### Tier 2 — Evidence Artifact (optional, caller-triggered)

Created when the caller explicitly flags that the invocation produced checkable output.

- **Trigger**: Caller sets `--evidence <path>` on `spec-kitty profile-invocation complete`.
- **Storage**: `.kittify/evidence/{invocation_id}/evidence.md` and `.kittify/evidence/{invocation_id}/record.json`
- **Format**: UTF-8 text only, checked before the `completed` event is recorded.
- **When**: `task_execution` and `mission_step` modes only.

### Tier 3 — Durable Project State (optional, action-driven)

Promotion to `kitty-specs/` or doctrine artifacts only when the invocation changes project-domain state.

- **Trigger**: Action is in `TIER_3_ACTIONS` — `{specify, plan, tasks, merge, accept}`.
- **Storage**: `kitty-specs/{mission_slug}/` — existing spec/plan/tasks/status files.
- **When**: `mission_step` mode only.

### Promotion Rules

```
Tier 1 always written
  |
  +-- If caller sets evidence_ref --> Tier 2 artifact created
  |
  +-- If action in TIER_3_ACTIONS --> Tier 3 artifacts produced by workflow
```

## Doctor-Sweep Closures and the Archive Freeze (#4397)

`kitty-ops/` is one of the four immutable archive roots under the
historical-preservation gate (`tests/architectural/test_archive_root_byte_identical.py`):
a **pre-existing** `kitty-ops/<invocation_id>.jsonl` file may never be modified
— not on disk, not in the index, committed or not. An agent close appends its
`completed` event to the per-record file and that is legal only because the
record was minted in the same session (new archive history, `A` status). The
`spec-kitty doctor ops --close-stale` sweep closes Ops that are, by definition,
already committed — so recording the closure by mutating the per-record file
(and auto-committing it) reds the preservation gate.

The resolved design (#4397, option "record closure on the append-only spine"):

- **Per-record `kitty-ops/<id>.jsonl` files are byte-frozen once committed.**
  The sweep never touches them.
- **Sweep closures are recorded on a dedicated append-only spine,
  `kitty-ops/op-closures.jsonl`** — one v2 `OpCompletedEvent` JSON line per
  closure (same frozen model as the per-record `completed` event, carrying
  `outcome="abandoned"`, `closed_by="doctor_sweep"`). The preservation gate
  admits this one path the same way it admits `kitty-ops/lifecycle.jsonl`:
  a modification is legal only as a byte-prefix-preserving append whose new
  rows parse as valid v2 completed events.
- **The close still goes through the canonical executor path**
  (`ProfileInvocationExecutor.complete_invocation`, research R4): the spine
  append *is* that path's write for a `closed_by="doctor_sweep"` close, the
  event is still submitted to the SaaS propagator, and the idempotent
  already-closed guard now checks both the per-record file (concurrent manual
  close) and the spine (concurrent sweep).
- **Open-Op detection reads both surfaces**: an Op is closed when its
  per-record file carries a `completed` event OR the spine carries a closure
  for its invocation id (`list_orphan_ops`).
- **The sweep covers every checkout of the repository** (#6661). Op records are
  written in the checkout the command ran in (#6564), so `doctor ops` enumerates the
  checkouts `git worktree list --porcelain` reports (one call per run, the same
  enumeration Op custody uses) and reads each checkout's own `kitty-ops/` and spine.
  `--close-stale` closes each stale Op through an executor rooted in the checkout
  that owns it, so a worktree's closure is appended to — and auto-committed on —
  that worktree's branch, never the root checkout's. The session-start/stop
  reminder stays a single-checkout, git-free scan.
- **The sweep auto-commits only the spine** (`op(<profile>): <action>
  [<id8>] (doctor sweep)`). A refused commit (e.g. the protected-branch guard
  on `main`) is reported per entry in the sweep output and stated in the
  command's output: the closure stays on disk, uncommitted. A committed one is
  visible only on branches that carry the commit. The agent close path is just
  as visible: a refused per-record auto-commit is printed as a warning
  (`executor.last_op_commit`) instead of dying in a `logger.warning`.
- **The auto-commit runs only where the repository tracks Op records (#6410).**
  Both close paths commit onto the checked-out branch, so they are skipped
  when:
  - the exact path being committed (the record, or the spine) matches an
    ignore rule (`git check-ignore --no-index`), or
  - the primary branch tracks no `kitty-ops/<ULID>.jsonl` record, locally or
    on `origin`. Special files such as `ops-index.jsonl`, `lifecycle.jsonl`,
    `propagation-errors.jsonl` and `op-closures.jsonl` do not count.

  The primary branch is `origin/HEAD`, else `main`, `master` or `develop`. It
  is never the checked-out branch, so an earlier `op(...)` commit on an issue
  branch cannot turn the commit back on. A skipped close keeps the record on
  disk, where `spec-kitty invocations list` and `doctor ops` find it. The
  close output says so (`OpCommitOutcome.skipped`, and `skipped:<reason>` in
  the sweep entry). An uncommitted spine can still block a checkout of a
  branch that commits `kitty-ops/op-closures.jsonl`; move or commit it first. The decision lives in
  `src/specify_cli/invocation/op_commit_policy.py`. A repository that tracks
  Op records, this one included, keeps the current-branch commit.

Rejected alternatives: letting the sweep mutate per-record files without
committing (still reds the gate, which compares the working tree against the
merge-base — and leaves closures non-durable), and narrowing the archive roots
themselves (weakens the preservation guarantee far beyond this surface).

### Lifecycle records in the same sweep (#7346)

`spec-kitty next` writes WP lifecycle records, one file per record under
`kitty-ops/lifecycle/` (ADR 2026-11-01-2), and pairs a `started` record only when
it reports a result. `doctor ops --close-stale` closes the rest:

- Every checkout is read first, the project root first. A record that several
  checkouts hold (tracked on a shared branch) is closed at most once: never when
  any checkout already holds its completion, otherwise once, in the first checkout
  that holds it. The branches therefore never collect two completions for one
  record when they meet. To tell which record a completion closed, the sweep pairs
  an `abandoned` record with the exact record its `metadata.closes_started_at`
  names, any other completion with the latest record of its agent and work
  package started before it, and a completion left over with the oldest remaining
  record; pairing counts per group are unchanged.
- One older than `--threshold` (any, at `0`) gets an **`abandoned`** record in the
  checkout that holds it: a new file, copying the action id, agent, Mission and
  work package, with a reason that names the sweep, `metadata.closed_by =
  doctor_sweep` and `metadata.closes_started_at`. Pairing counts it as a completion. Nothing is rewritten, so the
  preservation gate admits it as any other added `kitty-ops/` file.
- Each checkout's closures are committed once (`op(doctor): close N stale
  lifecycle record(s) (doctor sweep)`) through the same executor commit as an Op
  close, with the #6410 rules judged for lifecycle records: the commit is skipped
  when the path is ignored or the primary branch tracks no
  `kitty-ops/lifecycle/<ULID>.json` record. A protected-branch refusal is
  reported and the closures stay on disk. `consolidate` treats a root
  `kitty-ops/lifecycle/<ULID>.json` file as bookkeeping, so a closure committed on
  an approved lane branch does not count as a commit after the approval.
- Mission status, `meta.json` and work package files are never touched.
- `--json` lists them under the additive `lifecycle_records` key; a fresh one left
  open makes the command exit 1, as a fresh Op does.

## SaaS Read-Model Policy

**No SaaS projection path is live.** The invocation propagator (`src/specify_cli/invocation/propagator.py`) asks an adapter seam for a SaaS client, and no package registers one, so every call is a no-op (#3030, the hosted-consent incident whose fix removed the dead registration). The sync transport that once sat behind it was retired. Whoever registers a real transport owns the auth and admission gate that makes it safe, because the payload carries `request_text`, the verbatim agent prompt.

The policy table below is what the propagator consults per `(mode_of_work, event)` once a client exists (`src/specify_cli/invocation/projection_policy.py::POLICY_TABLE`).

| mode_of_work | event | project | include_request_text | include_evidence_ref |
|--------------|-------|---------|----------------------|----------------------|
| task_execution | started | yes | yes | no |
| task_execution | completed | yes | yes | yes |
| task_execution | artifact_link | yes | no | no |
| task_execution | commit_link | yes | no | no |
| mission_step | started | yes | yes | no |
| mission_step | completed | yes | yes | yes |
| mission_step | artifact_link | yes | no | no |
| mission_step | commit_link | yes | no | no |
| query | any | no | — | — |

Pre-mission records (no `mode_of_work`) project under the `task_execution` rules (the legacy behaviour, kept for them).

Policy is additive and resolvable from code/config alone. See ADR-003-projection-policy.md for the rationale.

Projection is additive. Events accumulate; there is no deletion, replay-based overwrite, or idempotency-key gating.

## Tier 2 SaaS Projection — Deferred

**Status**: Tier 2 evidence artifacts (`.kittify/evidence/<invocation_id>/evidence.md` and `record.json`) are **local-only**. They are not uploaded to SaaS. This decision was finalised by the Phase 4 closeout mission (ADR-004-tier2-saas-deferral.md).

**Reasoning**:
1. The product has always behaved this way (since the 3.2.0a5 baseline); operators see local-only evidence.
2. SaaS projection of evidence bodies requires privacy, redaction, and size-limit design that lies outside the Phase 4 closeout scope.
3. Future projection remains possible without contract change — a later epic can read the existing local artifact and emit its own envelope.

**Revisit trigger**: any of (a) a named future epic accepts SaaS evidence projection as scope, (b) operators actively request the feature with a concrete use case, (c) a regulatory or audit requirement mandates centralised retention.

## Retention and Redaction

| Field | Treatment |
|-------|-----------|
| `request_text` | Retained as-written in local JSONL. No automatic redaction. |
| `governance_context_hash` | First 16 hex chars of SHA-256 only. Full governance context is never persisted. |
| JSONL files | Persist indefinitely unless the operator purges `kitty-ops/`. |
| SaaS propagation | None live today. The policy is additive, with no delete-on-disable. |

Propagation failures are written to `kitty-ops/propagation-errors.jsonl` and never affect the CLI exit code.

## `spec-kitty intake` — Not a Profile Invocation

`spec-kitty intake` ingests a plan document into `.kittify/mission-brief.md` for use by `/spec-kitty.specify` brief-intake mode. It is **not** a standalone Op and produces no `InvocationRecord`. The governed trail begins when the host calls `spec-kitty dispatch "<request>"` — not when the user stages a brief.

## Host surfaces that teach the trail

The standalone dispatch surface is taught to host LLMs through per-host skill packs. See [`docs/host-surface-parity.md`](/architecture/host-surface-parity.md) for the authoritative matrix of supported hosts and each host's parity status.

## `spec-kitty explain` — Deferred to Phase 5

`spec-kitty explain` (issue #534) is not part of this release. It requires Phase 5 DRG glossary addressability to produce fully-cited answers. A partial implementation without glossary citations would be misleading.

## Related

- [Host-Surface Parity Matrix](/architecture/host-surface-parity.md)

## Audience

- [Stakeholder Persona: System Architect](/context/audience/internal/system-architect.md) - Written for the System Architect reader.
