Spec Kitty

Contracts

body-sync.md

Contract: Body Sync (Post-Cutover)

Feature: 064-complete-mission-identity-cutover Date: 2026-04-06

Upload Request Payload

POST /api/dossier/push-content/

{
  "project_uuid": "uuid",
  "mission_slug": "064-my-mission",
  "target_branch": "main",
  "mission_type": "software-dev",
  "manifest_version": "1.0",
  "artifact_path": "kitty-specs/064-my-mission/spec.md",
  "content_hash": "sha256:...",
  "hash_algorithm": "sha256",
  "content_body": "..."
}

Required Fields

Field	Type	Description
project_uuid	string (UUID)	Project identity
mission_slug	string	Mission instance identifier
target_branch	string	Target branch for the mission
mission_type	string	Mission workflow kind
manifest_version	string	Artifact manifest version
artifact_path	string	Relative path to artifact
content_hash	string	Content hash with algorithm prefix
hash_algorithm	string	Hash algorithm name
content_body	string	Artifact content

Forbidden Fields

Field	Reason
feature_slug	Legacy; replaced by mission_slug
mission_key	Legacy intermediate field; replaced by mission_type

NamespaceRef Fields

The NamespaceRef dataclass identifies an artifact's position in the project hierarchy:

Field	Type	Description
project_uuid	string	Project identity
mission_slug	string	Mission instance identifier
target_branch	string	Target branch
mission_type	string	Mission workflow kind
manifest_version	string	Artifact manifest version

Queue Schema (SQLite)

CREATE TABLE body_upload_queue (
    row_id INTEGER PRIMARY KEY AUTOINCREMENT,
    project_uuid TEXT NOT NULL,
    mission_slug TEXT NOT NULL,      -- was: feature_slug
    target_branch TEXT NOT NULL,
    mission_type TEXT NOT NULL,       -- was: mission_key
    manifest_version TEXT NOT NULL,
    artifact_path TEXT NOT NULL,
    content_hash TEXT NOT NULL,
    hash_algorithm TEXT NOT NULL,
    content_body TEXT NOT NULL,
    size_bytes INTEGER NOT NULL,
    retry_count INTEGER NOT NULL DEFAULT 0,
    next_attempt_at REAL NOT NULL,
    created_at REAL NOT NULL
);

event-envelope.md

Contract: Event Envelope (3.0.0 Conformance)

Feature: 064-complete-mission-identity-cutover Date: 2026-04-06 Upstream: spec-kitty-events @ 5b8e6dc, spec-kitty-saas @ 3a0e4af

Envelope Shape

Every event emitted to SaaS (via WebSocket, batch sync, or offline queue) must include:

{
  "schema_version": "3.0.0",
  "build_id": "uuid-of-this-checkout",
  "aggregate_type": "Mission",
  "event_type": "MissionCreated | MissionClosed | WPStatusChanged | ...",
  "payload": {
    "mission_slug": "064-my-mission",
    "mission_number": "064",
    "mission_type": "software-dev",
    ...
  }
}

Required Envelope Fields

Field	Type	Description
schema_version	string	Must be "3.0.0"
build_id	string (UUID)	Unique checkout/worktree identity
aggregate_type	string	Must be "Mission" (never "Feature")
event_type	string	One of the canonical event types

Forbidden Envelope Fields

Field	Reason
feature_slug	Legacy alias; use mission_slug in payload
aggregate_type: "Feature"	Legacy aggregate type

Required Payload Fields (mission-scoped events)

Field	Type	Description
mission_slug	string	Mission instance identifier (e.g., "064-my-mission")
mission_number	string	Mission sequence number (e.g., "064")
mission_type	string	Mission workflow kind (e.g., "software-dev")

Forbidden Payload Fields

Field	Reason
feature_slug	Legacy; replaced by mission_slug
feature_number	Legacy; replaced by mission_number
feature_type	Legacy; replaced by mission_type

Canonical Event Types

Event Type	When Emitted
MissionCreated	New mission scaffolded
MissionClosed	Mission accepted/completed
WPStatusChanged	Work package lane transition
WPCreated	Work package added
WPAssigned	Work package claimed by actor
HistoryAdded	Audit log entry appended
ErrorLogged	Error event recorded
DependencyResolved	WP dependency resolved
MissionOriginBound	Tracker origin binding

Forbidden Event Types

Event Type	Reason
FeatureCreated	Legacy; replaced by MissionCreated
FeatureCompleted	Legacy; replaced by MissionClosed

build_id Invariants

• build_id must be present and non-null on every emitted envelope
• build_id must be preserved through serialization, queue storage, replay, and reduction
• Different checkouts/worktrees of the same repository must have different build_id values
• The same checkout must retain its build_id across sessions

orchestrator-api.md

Contract: Orchestrator API (Post-Cutover)

Feature: 064-complete-mission-identity-cutover Date: 2026-04-06 Consumer: spec-kitty-orchestrator (Priivacy-ai/spec-kitty-orchestrator)

Commands

Renamed Commands

Command	Purpose	Key Parameters
mission-state	Query mission status and WP lanes	--mission (mission slug), --policy
accept-mission	Mark all WPs done, accept mission	--mission (mission slug), --policy
merge-mission	Merge mission worktrees to target branch	--mission (mission slug), --strategy, --policy

Unchanged Commands

Command	Purpose
contract-version	Report contract version and minimum provider version
list-ready	List WPs ready for implementation/review
start-implementation	Claim and start implementing a WP
start-review	Start reviewing a WP
transition	Transition a WP between lanes
append-history	Append audit history entry

CLI Parameter Rename

All 8 commands currently use --feature as the CLI flag for the mission slug. After cutover, this parameter must be renamed to --mission across all commands. The --feature flag must not be accepted on any live command.

Old Flag	New Flag	Scope
--feature	--mission	All 8 commands that accept a mission slug

Error Codes

Code	Meaning
MISSION_NOT_FOUND	Mission slug does not resolve to a kitty-specs directory
MISSION_NOT_READY	Not all WPs are done (for accept-mission)
USAGE_ERROR	CLI parse/usage error
POLICY_METADATA_REQUIRED	--policy missing on run-affecting command
POLICY_VALIDATION_FAILED	Policy JSON invalid or contains secrets
WP_NOT_FOUND	WP ID does not exist in the mission
TRANSITION_REJECTED	Transition not allowed by state machine
WP_ALREADY_CLAIMED	WP claimed by a different actor
PREFLIGHT_FAILED	Preflight checks failed (for merge-mission)
CONTRACT_VERSION_MISMATCH	Provider version below minimum
UNSUPPORTED_STRATEGY	Merge strategy not implemented

Response Envelope

All commands emit a single JSON object to stdout. The envelope always includes:

{
  "ok": true,
  "command": "mission-state",
  "contract_version": "...",
  "mission_slug": "064-my-mission",
  "data": { ... }
}

Removed fields: feature_slug (was injected as alias, no longer present).

Required field: mission_slug (always present in data payloads that reference a mission).

Failure Envelope

{
  "ok": false,
  "command": "mission-state",
  "error_code": "MISSION_NOT_FOUND",
  "error": "Mission '064-nonexistent' not found in kitty-specs/",
  "contract_version": "..."
}

Unknown Command Behavior

Calling a removed command name (e.g., feature-state, accept-feature, merge-feature) results in a standard CLI unknown-command error. The orchestrator API does not recognize these names and does not provide a redirect or deprecation notice.

tracker-bind.md

Contract: Tracker Bind (Post-Cutover)

Feature: 064-complete-mission-identity-cutover Date: 2026-04-06

Bind Payload

The project_identity dict sent during tracker bind operations:

{
  "uuid": "project-uuid",
  "slug": "project-slug",
  "node_id": "node-uuid",
  "repo_slug": "repo-slug",
  "build_id": "build-uuid"
}

Required Fields

Field	Type	Description
uuid	string (UUID)	Project identity
slug	string	Project slug
node_id	string (UUID)	Causal emitter identity (Lamport ordering)
repo_slug	string	Repository slug
build_id	string (UUID)	Checkout/worktree identity

Change from Current

Added: build_id (previously absent from tracker bind payload).

All other fields unchanged.

upstream-3.0.0-shape.json

{ "_comment": "Machine-readable contract shape derived from spec-kitty-events @ 5b8e6dc and spec-kitty-saas @ 3a0e4af. The compatibility gate MUST load and enforce this artifact, not hand-maintained constants.", "_source_events_commit": "5b8e6dc", "_source_saas_commit": "3a0e4af", "_schema_version": "3.0.0", "envelope": { "required_fields": ["schema_version", "build_id", "aggregate_type", "event_type"], "forbidden_fields": ["feature_slug", "feature_number", "from_lane", "to_lane", "actor", "force", "reason", "review_ref", "execution_mode", "evidence"], "aggregate_type": { "allowed": ["Build", "Mission", "WorkPackage", "MissionDossier"], "forbidden": ["Feature"] }, "schema_version": { "value": "3.0.0" } }, "payload": { "mission_scoped": { "required_fields": ["mission_slug", "mission_number", "mission_type"], "forbidden_fields": ["feature_slug", "feature_number", "feature_type"] } }, "body_sync": { "required_fields": ["project_uuid", "mission_slug", "target_branch", "mission_type", "manifest_version"], "forbidden_fields": ["feature_slug", "mission_key"] }, "tracker_bind": { "required_fields": ["uuid", "slug", "node_id", "repo_slug", "build_id"], "forbidden_fields": [] }, "orchestrator_api": { "allowed_commands": ["contract-version", "mission-state", "list-ready", "start-implementation", "start-review", "transition", "append-history", "accept-mission", "merge-mission"], "forbidden_commands": ["feature-state", "accept-feature", "merge-feature"], "allowed_error_codes": ["USAGE_ERROR", "POLICY_METADATA_REQUIRED", "POLICY_VALIDATION_FAILED", "MISSION_NOT_FOUND", "WP_NOT_FOUND", "TRANSITION_REJECTED", "WP_ALREADY_CLAIMED", "MISSION_NOT_READY", "WORKFLOW_EVIDENCE_REQUIRED", "PREFLIGHT_FAILED", "CONTRACT_VERSION_MISMATCH", "UNSUPPORTED_STRATEGY", "HISTORY_COMMIT_FAILED", "DEPENDENCIES_NOT_SATISFIED", "SAFE_COMMIT_BACKSTOP", "SAFE_COMMIT_DESTINATION_NOT_FOUND", "SAFE_COMMIT_DESTINATION_REF_SHAPE", "SAFE_COMMIT_EMPTY_CHANGESET", "SAFE_COMMIT_GENERIC", "SAFE_COMMIT_HEAD_MISMATCH", "SAFE_COMMIT_NOT_A_WORKTREE", "SAFE_COMMIT_PROTECTED_BRANCH", "SAFE_COMMIT_PATH_POLICY", "SAFE_COMMIT_RECOVERY_FAILED"], "forbidden_error_codes": ["FEATURE_NOT_FOUND", "FEATURE_NOT_READY"], "forbidden_payload_fields": ["feature_slug"], "required_payload_fields": ["mission_slug"], "allowed_cli_flags": ["--mission"], "forbidden_cli_flags": ["--feature"] } }