---
artifact_schema_version: 1
artifact_type: reference
---

# Automation Protocol

Day Shift automation protocol version `2` is independent from the CLI package,
artifact, manifest, and workspace schema versions. The runtime authority is
`src/lib/automation-protocol/index.ts`; checked-in JSON Schemas become the
language-neutral payload authority when the schema catalog is introduced.

## Compatibility Window

Protocol v1 preserves the full-detail meaning of `--format json`; select it with
`--protocol-version 1` or the equivalent structured `protocolVersion: 1` input.
Protocol v2 is the default for unpinned consumers and selects compact output on
approved bounded JSON surfaces. Pin `--protocol-version 1` for rollback during
the compatibility window, or request `--detail full` under v2 for audit output.
Additive optional fields and newly advertised implemented features may ship
without a protocol-version change. Removing a field, changing a field's type or
meaning, making an optional field required, or changing a discriminator is a
breaking change and requires a new protocol version.

Explicit `--detail compact`, `--detail summary`, and `--detail full` always
override the version default. Text output is unchanged. Unsupported selections
fail before command work with a typed no-write recovery envelope.

Consumers negotiate against `minimumSupportedVersion` and
`maximumSupportedVersion` and use only names present in `features`. Absence from
the feature list means unsupported, even when planning material describes the
feature as future work.

## Deprecation Rules

Deprecations are machine-readable entries containing the field, the protocol
version in which it was deprecated, the earliest removal protocol version, and
the replacement field or `null` when there is no replacement. A field remains
valid throughout every advertised protocol version that includes it. Removal
cannot occur in the same protocol version that first advertises deprecation.

## Serialization Rules

- Envelope keys have a canonical order beginning with `protocolVersion`, then
  status and command identity, command data or error data, and findings.
- Schema-defined object properties render in schema order. Map-like objects use
  ascending Unicode code-point key order when their contract does not define a
  semantic order.
- Lists preserve semantic producer order when that order is documented;
  set-like evidence and feature lists use stable ascending identifier order.
- Required nullable fields render as `null` when a value is known to be absent.
  Optional fields are omitted when they are not applicable or were not
  requested. Undefined values are never serialized as implicit protocol data.
- Pretty versus compact whitespace does not change protocol semantics.
- Bounded output must remain a complete JSON document; truncation requires a
  valid envelope that reports incomplete state and continuation guidance.

## Authority Boundary

The runtime constants and feature manifest own version negotiation. The
versioned schema catalog owns published payload structure. Generated TypeScript
types and Ajv validators must derive from that catalog and must not become an
independent contract authority. Protocol v1 advertises bounded JSON output,
pagination, feature discovery, typed terminal failures, executable workflow
actions, explicit work selection, artifact-scoped context, scoped health,
resume capsules, freshness evidence, constrained profiles, and bounded decision
traces. Executable
workflow actions carry descriptor-backed identity, callable state, exact
argument vectors when callable, effects, authorization, evaluated
preconditions, transition identity, and expected postconditions. Mutation
receipts remain capability-specific and must be consumed only when advertised
by the selected command descriptor.

For the agent operating loop, compact recovery, freshness, trust, and profile
rules, use `.day-shift/references/small-model-agent-operations.md`.
