Skip to content

Understanding Governed Profile Invocation

Who is this for (1)

This document explains governed profile invocation. For how to run a governed mission, see How to Run a Governed Mission. For the CLI reference, see Profile Invocation Reference.


The Governed Invocation Primitive

Standalone governed work in Spec Kitty is a triple:

  1. Profile: the resolved agent profile used to select the right governance context. Users normally do not need to choose this; the router does it. A caller can pass --profile <profile-id> when they intentionally want a specific profile.
  2. Action: the action token resolved for the request, such as implement, review, or plan.
  3. Governance context: the Charter bundle context injected at invocation time. This is the DRG-derived, action-scoped set of directives, tactics, and glossary terms that the agent receives.

When spec-kitty next prepares a prompt for the current mission step, it resolves the action and renders governance context into the prompt file returned to the calling agent. For standalone work, spec-kitty dispatch "<request>" does the same governance-context loading and records an Op trail.


Standalone Dispatch

Use standalone dispatch when the user wants Spec Kitty involved but is not asking for a full mission:

Terminal window
uv run spec-kitty dispatch "Review this approach" --json
uv run spec-kitty dispatch "Implement token validation" --profile implementer-ivan --json

The command returns governance_context_text, invocation_id, and a close_contract. The host agent must read governance_context_text, treat it as binding context, do the work, then close the Op.

Re-dispatching without re-embedding the payload (#6990)

Every dispatch assembles and returns the whole governance context — ~24 KB on this repository, mostly the profile-cited directives. A harness that dispatches repeatedly pays that as prompt context on every call, although after the first read the marginal information is near zero. --brief makes that re-read cheap without changing what is loaded:

Terminal window
uv run spec-kitty dispatch "Implement token validation" --profile python-pedro --brief --json

With --brief the envelope keeps every routing and orientation field (profile, action, router confidence, alternatives, model-routing advice, governance_context_hash, invocation_id, close_contract) and replaces governance_context_text with null plus governance_context_reference:

"governance_context_reference": {
"digest": "367d55bc23c18daf",
"bytes": 23739,
"lines": 308,
"fetch_command": "spec-kitty charter context --action generate --profile python-pedro --json --no-mark-loaded"
}

action here is the payload’s own derived action — generate, the implementer role’s default verb for that request, not the word “Implement” the caller typed. The reference therefore always names the grain that was actually omitted, and the printed command re-renders that grain. digest is the first 16 hex characters of the SHA-256 of the text, the same value the envelope’s governance_context_hash carries, so a consumer can verify a fetched text against it.

Three rules make this safe:

  • Opt-in, never automatic. There is no session detection and no state file; dispatch still assembles governance on every call. Use --brief only when this session has already read the full text for the resolved profile and action — the first contact must be the full payload (or the fetch command).
  • The reference must resolve. --brief leaves the payload untouched when there is no text or no way to reproduce it — governance unavailable, an empty render, or the empty-charter fallback (whose render suppresses the project resolver and charter context cannot reproduce it) — so it never hides governance it cannot hand back.
  • The fetch command is exact. --json gives the byte-identical text field (the plain render wraps long lines to the terminal width), and --no-mark-loaded mirrors dispatch’s own mark_loaded=False, so fetching does not record a first-load and shrink the next mission prompt.

The reference is a command that rebuilds the text on fetch, not a snapshot, so a charter, DRG or profile change made between dispatch and fetch can make the fetched text differ from the one digest describes. The consumer must compare the first 16 hex characters of the SHA-256 of the fetched text with digest and, on a mismatch, discard it and re-dispatch without --brief.

The Op record, the glossary scan and the routing decision are unchanged in brief mode: only the rendered text is replaced.


Invocation Lifecycle

Every standalone dispatch follows the same append-only lifecycle:

  1. Opened: A started event is written to kitty-ops/{invocation_id}.jsonl before the executor returns. This write is unconditional: it happens regardless of SaaS connectivity or charter state.
  2. Work happens outside the CLI: The CLI has returned the context payload. The caller or agent performs the work.
  3. Completed: When execution finishes, spec-kitty profile-invocation complete closes the trail. This appends a completed event to the same JSONL file. --artifact and --commit append separate correlation events after the completed event.
Terminal window
uv run spec-kitty profile-invocation complete \
--invocation-id <ULID> \
--outcome done \
--artifact path/to/produced/file.md \
--commit <git-sha>

Options for profile-invocation complete:

  • --outcome: done, failed, or abandoned
  • --artifact: path to an artifact produced by this invocation (repeatable)
  • --commit: the primary git commit SHA produced by this invocation (singular)
  • --evidence: promote a file to a Tier 2 evidence artifact when the record is evidence-eligible

The Invocation Trail

The invocation trail is the local audit record written by every governed invocation. It provides:

  1. Local accountability: operators can reconstruct what happened on any checkout without SaaS connectivity.
  2. SaaS coherence: the dashboard timeline shows the same history as the local audit log.
  3. Governance provenance: retrospective and doctrine work can reference specific invocations.

Trail files live at kitty-ops/{invocation_id}.jsonl: one JSONL file per invocation. Each line is an event (started, completed, glossary_checked, artifact_link, commit_link, or future additive events).

Key fields on the started event:

FieldTypeDescription
profile_idstringResolved profile identifier
actionstringResolved action token
request_textstringRequest supplied to dispatch
governance_context_hashstringHash of the rendered Charter context
governance_context_availablebooleanWhether Charter context was available
started_atISO timestampWhen the invocation was opened
mode_of_workstringWork mode used for trail policy

Key fields on the completed event:

FieldTypeDescription
invocation_idULIDMatches the started event
outcomestringdone, failed, or abandoned
completed_atISO timestampWhen profile-invocation complete was called
closed_bystringagent or doctor_sweep
evidence_refstring/nullEvidence path or text supplied with --evidence

Evidence and Artifact Correlation

Artifacts produced during an invocation are linked back to the trail record via separate artifact_link and commit_link events appended by the --artifact and --commit options on profile-invocation complete. This correlation provides:

  • A local audit link from an invocation to the artifacts or commit it produced
  • Governance provenance context for humans and future automated consumers

Evidence files promoted via --evidence receive Tier 2 status in the trail.


See Also