Skip to content

Trail Model

Who is this for (1)

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.
  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.

ModeDescriptionExample actionsTier 2 eligibleTier 3 eligible
task_executionStandalone governed work, including advice, review, code changes, and test runsdispatchYes (caller-triggered)No
mission_stepOne step in a governed mission workflowspecify, plan, tasks, merge, acceptYes (caller-triggered)Yes
queryRead-only, no executionprofiles list, invocations listNoNo

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:

{"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.

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), 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_workeventprojectinclude_request_textinclude_evidence_ref
task_executionstartedyesyesno
task_executioncompletedyesyesyes
task_executionartifact_linkyesnono
task_executioncommit_linkyesnono
mission_stepstartedyesyesno
mission_stepcompletedyesyesyes
mission_stepartifact_linkyesnono
mission_stepcommit_linkyesnono
queryanyno——

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

FieldTreatment
request_textRetained as-written in local JSONL. No automatic redaction.
governance_context_hashFirst 16 hex chars of SHA-256 only. Full governance context is never persisted.
JSONL filesPersist indefinitely unless the operator purges kitty-ops/.
SaaS propagationNone 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 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.