Skip to content

Orchestrator API Reference

spec-kitty orchestrator-api is the canonical JSON-first host interface for external orchestrators.

It is intentionally stricter than the human-facing CLI:

  • use --mission; the --feature flag has been removed from all user-facing commands
  • expect one JSON envelope on stdout for both success and failure
  • treat error_code as the stable machine discriminator
  • do not append --json; JSON is the default output for this command group

Canonical Terms

  • Mission Type = reusable blueprint key
  • Mission = tracked item under kitty-specs/<mission-slug>/
  • Mission Run = runtime/session instance

Contract Version

  • CONTRACT_VERSION: 1.29.0
  • MIN_PROVIDER_VERSION: 0.1.0
  • Startup probe: spec-kitty orchestrator-api contract-version
  • A --provider-version below MIN_PROVIDER_VERSION, or one that does not parse as a version string, always returns exit code 1 with error_code: CONTRACT_VERSION_MISMATCH — never a silent default. Call contract-version with --provider-version at startup to fail fast on an incompatible provider instead of discovering the mismatch mid-workflow.

Version history (the authoritative ledger lives at the CONTRACT_VERSION constant in src/specify_cli/orchestrator_api/envelope.py):

  • 1.1.0 — start-implementation allocates/reuses the lane worktree; its response carries lane_id / lane_branch / lane_base_ref, and workspace_path means that lane worktree. New error code LANE_ALLOCATION_FAILED.

  • 1.2.0 — new read-only resolve-workspace command (#2337). Purely additive.

  • 1.3.0 — transition accepts structured --review-result-json, allowing guarded in_review exits without recovery-only force overrides.

  • 1.4.0 — added 11 new verbs (#3837): design-phase scaffolding (specify, plan, tasks, check-prerequisites, record-analysis); decision-resolution (open-decision, resolve-decision, defer-decision, cancel-decision, answer-decision); plus the read-only design-status query verb. Purely additive — see Design-Phase Commands below. An external host can now drive the entire design pipeline (specify → plan → tasks → check-prerequisites/record-analysis → decision resolution) without crossing into host-CLI territory; see Host Boundary Rules for the updated Boundary Decision Matrix.

  • 1.5.0 — the tasks verb’s pass-through data gained the planning_commit object (action / sha / previous_sha / branch_tip) from the delegate finalize-tasks --json payload (#4141, the --refresh-planning-commit re-point affordance). Purely additive.

  • 1.6.0 — the planning_commit.action vocabulary gains "repinned" (#4827, the --refresh-planning-commit --allow-orphaned re-point affordance). Purely additive.

  • 1.7.0 — accept-mission now applies the host readiness verdict (#4934): it calls collect_feature_summary(..., strict_metadata=True) and refuses with MISSION_NOT_READY whenever summary.ok is False, carrying outstanding / activity_issues / skipped_checks / blocked_checks plus the mission identity fields — see Acceptance Payload below. Acceptance is now recorded only through the same FR-010 locked pre-stamp verdict guard the host accept CLI uses, so a verdict committed between the readiness check and the stamp is refused rather than silently accepted over. A behavioural tightening (a call that previously accepted can now refuse), not purely additive.

  • 1.8.0 — the tasks verb’s pass-through data gains three keys (parsed_spec_ids, rejected_requirement_refs, success_criteria_coverage) from the delegate finalize-tasks --json payload (requirement-id-grammar-01M3NRCA WP02). The plan verb’s pass-through data gains requirement_id_warnings, and its previously unregistered delegate error codes now remap onto the closed PLAN_SETUP_FAILED envelope with the real code preserved as data.reason (WP05) — this closes a latent leak: SPEC_FILE_MISSING, TEMPLATE_CONFIGURATION_ERROR and PLAN_CONTEXT_UNRESOLVED previously passed through verbatim as error_code (none was contract-registered) and now surface as PLAN_SETUP_FAILED too. Additive keys plus a closed-envelope remap on plan’s previously-leaking codes; minor bump.

  • 1.9.0 — the consolidate-mission failure envelope’s data gains teardown_error_code when the landing succeeded and only the cleanup after it refused (COORD_MOVED_AFTER_LANDING, #5613; see data.teardown_error_code). The envelope error_code stays PREFLIGHT_FAILED and data.errors is unchanged. Purely additive: the key is absent on every other failure.

  • 1.10.0 — consolidate-mission can newly refuse a mission before it merges any lane (#5668): a lane holding content committed after review approved it, or an approved work package whose approval records no usable lane head. The envelope error_code stays PREFLIGHT_FAILED and data gains preflight_error_code (see data.preflight_error_code). A call that used to succeed can now refuse, so a minor bump; the key is absent on every other failure. data also carries preflight_error_codes, every distinct code the refusal names, the first equal to preflight_error_code (#5720).

  • 1.11.0 — accept-mission and consolidate-mission take --origin-check [enforce|warn] and can newly refuse before they read evidence or move a lane, when the Mission’s status evidence (and, for consolidate-mission, its approved lane branches) is behind, diverged from or unreachable on its remote (#5780). The envelope error_code stays MISSION_NOT_READY / PREFLIGHT_FAILED; data gains preflight_error_code, preflight_error_codes and origin_freshness (see Origin freshness), and a successful warn run gains origin_warnings. A call that used to succeed can now refuse, so a minor bump; every key is absent otherwise.

  • 1.12.0 — adds governed context/interviews, bounded artifact authoring and native next, plus the truthful Python delivery profile and capability probe. Existing commands and envelope fields remain. For API-authored Missions, successful design completion/finalization through orchestrator-api now checks accepted provenance and canonical prerequisites; stale or unfinished inputs refuse. Native spec-kitty next --result success and agent mission finalize-tasks run the same check (#5879) and refuse with the same DESIGN_* code; agent tasks finalize-tasks does not. New error_code values: DESIGN_ARTIFACT_UNSUPPORTED, DESIGN_BOUNDS_EXCEEDED, DESIGN_COMMIT_FAILED, DESIGN_CONTEXT_FAILED, DESIGN_CONTEXT_STALE, DESIGN_FINALIZED, DESIGN_INTERVIEW_FAILED, DESIGN_INTERVIEW_INCOMPLETE, DESIGN_INTERVIEW_INVALID, DESIGN_IO_FAILED, DESIGN_LOCK_TIMEOUT, DESIGN_PARENT_STALE, DESIGN_PATH_REFUSED, DESIGN_PREREQUISITES_FAILED, DESIGN_RECEIPT_UNREADABLE, DESIGN_REQUEST_INVALID, DESIGN_REVISION_CONFLICT, DESIGN_STATUS_EVENT_LOG_UNREADABLE, RUNTIME_NEXT_FAILED, RUNTIME_BLOCKED and UNSUPPORTED_CAPABILITY. Behaviour change: plan now fails when its delegate payload result is blocked or error instead of emitting success. See Governed planning delivery.

  • 1.13.0 — start-implementation can newly fail with STATUS_LOCK_HELD (#5819) when the single_branch write-checkout claim lock stays held by another claimant past its bound (it used to escape as a traceback). The failure data carries the Mission identity, wp_id, message and lock_timeout_seconds. A new error_code on an existing verb, so a minor bump; no field is removed or renamed.

  • 1.14.0 — the safe-commit verbs (append-history) can newly fail with SAFE_COMMIT_PATH_LOOP (a requested path is a symlink loop), SAFE_COMMIT_INDEX_DELETION_CONFLICT (an index deletion conflicts with the commit) and SAFE_COMMIT_INDEX_RESIDUE (#5443). SAFE_COMMIT_INDEX_RESIDUE means the commit DID land (commit_sha names it) but the real index still stages a committed path; it refines SAFE_COMMIT_RECOVERY_FAILED, which keeps meaning the commit may not have landed. New error_code values on an existing verb, so a minor bump; no field is removed or renamed.

  • 1.15.0 — the safe-commit verbs (append-history) can newly fail with SAFE_COMMIT_UNREQUESTED_PATHS (#5903) when a pre-commit hook that runs git add -u sweeps the operator’s other modified tracked files into the commit: the commit DID land (commit_sha names it) but it carries paths the operation never requested, and the operator’s real index is re-synced for those paths before the failure is raised. Like SAFE_COMMIT_INDEX_RESIDUE it refines SAFE_COMMIT_RECOVERY_FAILED (the commit landed). A new error_code on an existing verb, so a minor bump; no field is removed or renamed.

  • 1.16.0 — answer-decision now surfaces decision-log commit warnings in its data under a warnings key (list of strings) when the decision record’s safe_commit is refused (#6222, follow-up to #3930, which fixed the host next --answer --json surface only). Previously an external orchestrator got success: true while the committed decision record diverged silently. The key is present only when non-empty — a clean commit leaves the payload byte-identical — so this is a purely additive, optional field; no field is removed or renamed.

  • 1.21.0 — consolidate-mission and accept-mission now run the implementation-evidence and review-independence axis on every topology (#6715; it covered single_branch only, #5939). consolidate-mission fails with the existing PREFLIGHT_FAILED envelope — the codes in data.preflight_error_code / data.preflight_error_codes — before it consolidates its first lane; accept-mission fails with the existing MISSION_NOT_READY and a new optional data.evidence_error_codes. The codes are IMPLEMENTATION_MISSING, REVIEW_NOT_INDEPENDENT, IMPLEMENTATION_UNREADABLE and EVIDENCE_WINDOW_UNCOMPUTABLE (single_branch keeps emitting its documented SINGLE_BRANCH_* aliases of the same meaning). A call that used to answer success: true while landing a work package approved with no change to its owned files, or approved by its own implementer, now refuses. A behaviour change on previously-success calls plus one additive optional field, so a minor bump; no field or error_code is removed or renamed.

  • 1.19.0 — resolve-decision, defer-decision and cancel-decision can newly fail with DECISION_LOCK_TIMEOUT (#4848): the bounded wait on the decisions lock (decisions/index.json.lock) ran out. It used to escape as a traceback with an empty stdout. Nothing is written, the call can be retried, and the failure data carries decision_id, mission_slug, lock_path and timeout_seconds. open-decision now waits on that lock without a bound, so it does not return this code. The same three verbs now record a decision’s missing DecisionPointOpened event (an interrupted open) before the terminal event, so DECISION_EVENT_REPAIR_FAILED gains a trigger on a first (non-idempotent) call: that opening could not be written, and nothing else was. A new error_code on existing verbs, so a minor bump; no field is removed or renamed.

  • 1.18.0 — consolidate-mission now skips a fully-canceled-with-provenance lane at parity with host consolidate (#5814): a lane whose every work package is an acceptable canceled-with-provenance ending is no longer merged, so its committed content never lands on the target and its work packages are neither gate-evaluated nor marked merged/done. A call that used to answer success: true while shipping that canceled content now still answers success: true but leaves the canceled lane off the target (the approved survivor lanes land unchanged). A behaviour change to the shipped tree of a previously-success call, so a minor bump; no envelope field or error_code is added, removed or renamed.

  • 1.17.0 — resolve-decision, defer-decision and cancel-decision can newly fail with DECISION_EVENT_REPAIR_FAILED (#5681), and DESIGN_STATUS_EVENT_LOG_UNREADABLE (already returned there for an unreadable decision index) gains a new trigger on them, an unreadable event log: an idempotent retry of an interrupted terminal call now re-writes the missing DecisionPointResolved event and reports its event_lamport (previously always null on an idempotent call). A newly reachable error_code on existing verbs and a non-null event_lamport on idempotent calls, so a minor bump; no field is removed or renamed.

  • 1.20.0 — host owned-checkout refusals embedded by check-prerequisites, next, plan, tasks and specify now use the CLI’s C2 error contract ({ok: false, error: {code, message}}, ADR 2026-10-27-2, #6353). Each verb reads the code and the plain-text message from that error object, so the owned error_code is the one it was before (plan still reports an unregistered code as PLAN_SETUP_FAILED with the real code in data.reason). The embedded host payload in data changes shape, so a minor bump; no error_code is added, removed or renamed.

  • 1.22.0 — the declared allowed_error_codes set now admits SAFE_COMMIT_DIRECTORY_ARGUMENT (#6997), the error_code of SafeCommitDirectoryArgument. The safe-commit path has emitted it since the #6750 fix, which refuses a directory pathspec in preflight_commit before any HEAD, ref or index mutation — so nothing was committed, and data.offending_path names the path — but the contract never registered it. This is a completeness fix to the declared set, not a new failure mode: no behaviour changes. The contract-visible error-code set grows, so a minor bump; no field or error_code is removed or renamed.

  • 1.23.0 — the implementation-evidence refusal of consolidate-mission and accept-mission gains the code OWNERSHIP_UNRESOLVED (#7149; single_branch emits the alias SINGLE_BRANCH_OWNERSHIP_UNRESOLVED). An approved work package whose owned_files cannot be read (its task file or the whole tasks/ directory is missing or unreadable) is absent from the resolved ownership map; it used to refuse as IMPLEMENTATION_MISSING, whose recovery cannot help. The verdict is decided before IMPLEMENTATION_MISSING, and no attestation lifts it. An authored owned_files list, an empty one included, stays resolved and keeps IMPLEMENTATION_MISSING. A call that was previously refused with IMPLEMENTATION_MISSING may now be refused with OWNERSHIP_UNRESOLVED, which no attestation lifts: a consumer that auto-attests must handle it. The code appears in data.preflight_error_code(s) and data.evidence_error_codes, so the contract-visible error-code set grows, a minor bump; no field or error_code is removed or renamed.

  • 1.24.0 — the planning_commit.action vocabulary of the tasks verb gains "derived" (#7210): finalize-tasks records a planning commit read from git for a lanes.json with none. Purely additive.

  • 1.25.0 — one bump for three additive fields (Mission lane-worktree-model-hardening, DM 01M6R0BJQ6Q1MV6492EH6HB66H):

    • consolidate-mission success data gains lane_cleanup, one object per code lane (see data.lane_cleanup). The mission branch is deleted first, then the lanes go through the same lane-cleanup module spec-kitty consolidate uses. A lane that cannot be removed after the landing is reported there as kept and the envelope stays success: true; it used to fail the call (a PREFLIGHT_FAILED or a raw DestructiveOpRefused envelope after the target had moved). data.teardown_error_code is now coordination-only.
    • specify gains topology_source (explicit | owned_checkout | default) and topology_provisional (true when no --topology was given: the topology is settled at the first tasks) and target_replacement (null, or the implicit target replaced because it was another Mission’s branch).
    • tasks gains topology_decision, the finalize-tasks settlement record (settled_this_run, topology_source, provisional_topology, settled_topology, rule, wp_count, code_lane_count, target_protected, preview).

    Additive fields, and a call that used to fail after a landing now succeeds, so a minor bump; no field or error_code is removed or renamed.

  • 1.26.0 — start-implementation, start-review and transition can newly fail with BOOKKEEPING_FAILED (#5642). Their status write goes through the transactional bookkeeping shell, whose BookkeepingError family — a policy refusal, a lock timeout, an unresolvable worktree, a diverged or unreadable coordination status surface — is not a TransitionError, so it escaped every except arm as a raw traceback with an empty stdout. The failure’s data.bookkeeping_error_code carries the exception’s own code, so a retryable BOOKKEEPING_LOCK_TIMEOUT stays distinguishable from a refusal that needs an operator. A new error_code on existing verbs, so a minor bump; no field or error_code is removed or renamed.

  • 1.27.0 — answer-decision success data (the Decision.to_dict() shape) gains an optional remediation object, {"kind": "materialized_coordination_worktree", "path": "<worktree>"}. It is present only when the advancing run materialized or restored the Mission’s coordination worktree, and absent otherwise, so every other payload is unchanged. Purely additive.

  • 1.28.0 — consolidate-mission --target <branch> can newly refuse before it consolidates any lane when the Mission’s recorded target cannot be written in this run (#5783): its done and coordination-flatten bookkeeping still go to the recorded target, which the checkout on the --target branch cannot commit to. The envelope error_code stays PREFLIGHT_FAILED; data.preflight_error_code / data.preflight_error_codes carry TARGET_OVERRIDE_RECORDED_TARGET_UNWRITABLE. A call that could answer success: true with the bookkeeping uncommitted now refuses, so a minor bump; no field or error_code is removed or renamed.

  • 1.29.0 — consolidate-mission can newly refuse before it consolidates any lane when a checkout holding the target or the Mission branch marks a file the run writes as skip-worktree (#7692). With the bit on status.events.jsonl the command used to land and then fail its done status commit with a traceback and no rollback. The envelope error_code stays PREFLIGHT_FAILED; data.preflight_error_code / data.preflight_error_codes carry CHECKOUT_SKIP_WORKTREE_ENTRIES. A call that could answer success: true (the bit on a file this path never writes) now refuses too, so a minor bump; no field or error_code is removed or renamed.

Response Envelope

Every command returns exactly one JSON object with these 7 top-level keys:

{
"contract_version": "1.29.0",
"command": "orchestrator-api.mission-state",
"timestamp": "2026-04-08T12:00:00+00:00",
"correlation_id": "corr-0123456789abcdef",
"success": true,
"error_code": null,
"data": {}
}
FieldMeaning
contract_versionHost API contract version.
commandFully-qualified command name.
timestampISO 8601 UTC response timestamp.
correlation_idUnique per-response correlation token.
successtrue for success, false for failure.
error_codeMachine-readable failure code, otherwise null.
dataCommand-specific payload.

Parser and usage failures also return the same envelope shape with error_code="USAGE_ERROR".

Canonical Mission Identity

Success payloads that identify a tracked mission emit:

FieldMeaning
mission_idCanonical ULID machine identity. Aggregate routing uses this field.
mission_slugHuman-readable mission slug. Display context only.
mission_numberDisplay-only numeric prefix. null pre-merge, assigned at merge time. Never used for identity.
mission_typeBlueprint key

The --mission selector accepts any of mission_id, mid8 (first 8 chars of the ULID), or mission_slug. Ambiguous handles return MISSION_AMBIGUOUS_SELECTOR and list the candidates — there is no silent fallback. See Mission ID Canonical Identity Migration.

Forbidden in orchestrator-api payloads:

  • feature_slug

Removed at the CLI boundary:

  • --feature (hard-removed in #1060; passing it yields exit code 2 with “No such option: —feature”)

Commands

CommandMutates statePurpose
contract-versionnoCheck API compatibility.
mission-statenoQuery mission state and WP lanes.
list-readynoList WPs ready to start.
resolve-workspacenoResolve a WP’s existing lane workspace (contract >= 1.2.0).
start-implementationyesAtomically move a WP into implementation.
start-reviewyesClaim active review for a WP.
transitionyesEmit one explicit lane transition.
append-historyyesAppend a WP activity-log note.
accept-missionyesRecord mission acceptance.
consolidate-missionyesConsolidate the mission into its target branch.
specifyyesCreate a mission scaffold (contract >= 1.4.0).
planyesScaffold plan.md for a mission (contract >= 1.4.0).
tasksyesFinalize WP task metadata (contract >= 1.4.0).
check-prerequisitesnoRead-only mission-prerequisite context for analyze (contract >= 1.4.0).
record-analysisyesPersist an analyze report, artifact-verified (contract >= 1.4.0).
open-decisionyesOpen a Decision Moment ledger entry (contract >= 1.4.0).
resolve-decisionyesResolve a decision with a final answer (contract >= 1.4.0).
defer-decisionyesDefer a decision for later resolution (contract >= 1.4.0).
cancel-decisionyesCancel a decision (contract >= 1.4.0).
design-statusnoRead-only design-phase status query (contract >= 1.4.0).
answer-decisionyesResolve a spec-kitty next decision_required moment, with full host-CLI event/lifecycle parity (contract >= 1.4.0).
artifact-readnoRead bounded canonical design content and its exact revision (contract >= 1.12.0).
artifact-submityesAuthor and commit bounded content with revision and lineage checks (contract >= 1.12.0).
design-validatenoCheck canonical prerequisites without completing a step (contract >= 1.12.0).
design-contextnoDiscover resolved templates, governance and interview slots (contract >= 1.12.0).
interview-recordyesRecord canonical specification or planning interview answers (contract >= 1.12.0).
nextquery: no; advancement: yesQuery or advance the native workflow authority (contract >= 1.12.0).

Legacy command names such as feature-state, accept-feature, and merge-feature are forbidden.

See Design-Phase Commands below for the full request/response/error-code contract of the 1.4 design verbs, and Governed Planning Delivery for the six 1.11 verbs.

Required Flags

The tracked-mission selector is always:

Terminal window
spec-kitty orchestrator-api mission-state --mission 077-mission-terminology-cleanup

Run-affecting implementation and review mutations require --policy. Today that means start-implementation, start-review, and transition when the target lane is run-affecting. append-history, accept-mission, and consolidate-mission do not accept --policy.

The policy JSON object must include:

  • orchestrator_id
  • orchestrator_version
  • agent_family
  • approval_mode
  • sandbox_mode
  • network_mode
  • dangerous_flags

Secret-like values in --policy are rejected.

Minimal policy example:

{
"orchestrator_id": "spec-kitty-orchestrator",
"orchestrator_version": "0.1.0",
"agent_family": "claude",
"approval_mode": "full_auto",
"sandbox_mode": "workspace_write",
"network_mode": "none",
"dangerous_flags": []
}

Lane Model for Orchestrators

External providers should treat these lanes as the public orchestration model:

LaneMeaning
plannedWP exists but has not started.
claimedWP is claimed by an actor as part of implementation start.
in_progressImplementation or rework is active.
for_reviewImplementation is ready for review.
in_reviewA reviewer has claimed active review.
approvedReview accepted but integration may still be pending.
doneWP is complete.
blockedWP cannot continue without intervention.
canceledWP was intentionally canceled.

The reference orchestrator normally drives:

planned -> claimed -> in_progress -> for_review -> in_review -> done

Rejected review cycles move back through:

in_review -> in_progress -> for_review

Acceptance Payload

accept-mission requires every WP to be approved or done. On success it returns:

FieldMeaning
accepted_wpsWPs counted by mission acceptance (approved plus done)
approved_wpsReview-passed WPs still awaiting merge/integration
done_wpsWPs already merged/integrated
merge_pending_wpsAlias of approved_wps; WPs accepted-ready but not done

accept-mission does not move WPs from approved to done; merge owns that transition.

MISSION_NOT_READY (contract >= 1.7.0)

Once every WP is approved/done, accept-mission additionally applies the SAME host readiness verdict the accept CLI computes via collect_feature_summary(..., strict_metadata=True) — one readiness authority, never a second computation of it. Before that summary is collected it runs the implementation-evidence and review-independence check (contract

= 1.21.0, #6715): the same predicate the accept CLI runs (consolidation.wp_evidence.mission_evidence_report), on every topology. When it refuses, accept-mission answers MISSION_NOT_READY with the refusal in data.errors and its codes in data.evidence_error_codes (see the table below), and the readiness summary is not computed. When summary.ok is False (a pending/failing acceptance matrix, a missing/corrupt lanes.json, a target-branch mismatch, an unmet path convention, a dirty working tree, and so on), accept-mission refuses with MISSION_NOT_READY and this error data:

FieldMeaning
outstandingdict[str, list[str]] — AcceptanceSummary.outstanding()’s buckets (e.g. lane_blockers, metadata, git_dirty, path_violations)
activity_issueslist[str] — human-readable readiness issues
skipped_checkslist[{check, detail}] — gates the readiness pass never reached
blocked_checkslist[{check, detail}] — gates that stopped readiness outright (e.g. a missing lanes.json reports check: "lanes_manifest")
evidence_error_codesoptional, contract >= 1.21.0: list[str] — present only on an evidence refusal, every distinct code it names in order (IMPLEMENTATION_MISSING, REVIEW_NOT_INDEPENDENT, IMPLEMENTATION_UNREADABLE, EVIDENCE_WINDOW_UNCOMPUTABLE, OWNERSHIP_UNRESOLVED (1.23.0), or a SINGLE_BRANCH_* alias on a single_branch Mission; meanings in the consolidate-mission table below). The readiness fields above are absent then.

No acceptance is recorded on this refusal: meta.json gains no accepted_at / acceptance_mode / acceptance_history, and HEAD is unchanged. The readiness gate may still update the matrix rows it judged in the working-tree acceptance-matrix.json, exactly as the host accept CLI does.

Acceptance is recorded only inside the same FR-010 locked pre-stamp verdict re-check the host accept CLI uses: the acceptance matrix is re-read fresh under the per-mission status lock immediately before the write. A verdict that a concurrent acceptance-verdict invocation commits between the readiness check above and this stamp — or a lock-acquisition timeout — is still refused with MISSION_NOT_READY, never silently accepted over.

Design-Phase Commands

Contract 1.4.0 (#3837) adds 11 verbs so an external host can drive the entire design pipeline — specify → plan → tasks → check-prerequisites/record-analysis → decision resolution — the same way it already drives the WP-implementation loop above, without ever calling spec-kitty next or another host-CLI command directly. See Host Boundary Rules for when to use these verbs versus the host CLI.

specify

Creates a mission scaffold — the same enriched payload the host CLI’s own specify --json returns (agent_feature.create_mission’s raw payload plus scaffold_only / spec_state / next_action / next_step), not the unenriched dict one layer beneath it.

Request:

Terminal window
spec-kitty orchestrator-api specify \
--mission 090-orchestrator-driven-mission \
--mission-type software-dev \
--topology lanes \
--policy '{"orchestrator_id":"ci","orchestrator_version":"1.0.0","agent_family":"ci-bot","approval_mode":"full_auto","sandbox_mode":"workspace_write","network_mode":"none","dangerous_flags":[]}'
FlagRequiredMeaning
--missionyesMission slug to create.
--mission-typeyesBlueprint key (e.g. software-dev).
--topologynoMission shape: single_branch | lanes | coord | lanes_with_coord, settled at create. When omitted, create mints one Mission topic branch on any target and the first tasks settles single_branch or lanes_with_coord by size; lanes and coord are explicit-only (same default as the host CLI).
--policyyesPolicy metadata JSON (see Required Flags).

Response data (contract >= 1.25.0) also carries:

KeyMeaning
topology_sourceexplicit (--topology given), owned_checkout, or default (no --topology).
topology_provisionaltrue when no --topology was given: topology is provisional and is settled at the first tasks (see topology_decision there). false otherwise.
target_replacementnull, or, when no --topology was given and the checked-out branch is another Mission’s branch, the replacement the create made: replaced_branch, owning_mission, target_branch (the target chosen instead) and remedy (pass --target-branch).

Error codes: POLICY_METADATA_REQUIRED, POLICY_VALIDATION_FAILED, MISSION_ALREADY_EXISTS (the mission-creation delegate refused a duplicate — a live same-key prior mission (#4033), or a retry whose scaffold is byte-identical to what is already committed — surfaced as the typed MissionAlreadyExistsError signal), MISSION_CREATE_FAILED (any other creation failure with no more specific error_code; a typed upstream code such as ACTIVE_CHARTER_CONFIG_INVALID (raised as ActiveCharterConfigError) is passed through verbatim instead). Classification consumes only the delegate’s typed error_code, never its message prose (#3861).

plan

Scaffolds plan.md. Deliberately unenriched — the response data is agent_feature.setup_plan’s raw payload verbatim (the host CLI’s own --json path adds no enrichment here either, unlike specify), with mission_slug filled in only if the delegate payload did not already carry it.

Request:

Terminal window
spec-kitty orchestrator-api plan \
--mission 090-orchestrator-driven-mission \
--policy '{"orchestrator_id":"ci","orchestrator_version":"1.0.0","agent_family":"ci-bot","approval_mode":"full_auto","sandbox_mode":"workspace_write","network_mode":"none","dangerous_flags":[]}'

Error codes: POLICY_METADATA_REQUIRED, POLICY_VALIDATION_FAILED, MISSION_NOT_FOUND, PLAN_SETUP_FAILED (delegate call failed with no more specific error_code of its own). A typed upstream code that is itself contract-registered passes through verbatim; a typed but unregistered delegate code (e.g. SPEC_REQUIREMENT_IDS_INVALID, SPEC_FILE_MISSING, TEMPLATE_CONFIGURATION_ERROR, PLAN_CONTEXT_UNRESOLVED) is instead reported as PLAN_SETUP_FAILED, with the real code preserved as data.reason (requirement-id-grammar-01M3NRCA WP05).

tasks

Finalizes WP task metadata. Same deliberate non-enrichment as plan — the response data is agent_feature.finalize_tasks’s raw payload verbatim, with mission_slug always filled in (unlike plan, the raw payload never carries it).

Request:

Terminal window
spec-kitty orchestrator-api tasks \
--mission 090-orchestrator-driven-mission \
--policy '{"orchestrator_id":"ci","orchestrator_version":"1.0.0","agent_family":"ci-bot","approval_mode":"full_auto","sandbox_mode":"workspace_write","network_mode":"none","dangerous_flags":[]}'

Response data (contract >= 1.25.0) also carries topology_decision, present on every successful run and on --validate-only:

KeyMeaning
settled_this_runtrue when this run settled a provisional topology; false when it was already settled (explicit, owned checkout, legacy, or an earlier tasks).
topology_sourceexplicit | owned_checkout | default | null (legacy meta.json).
provisional_topologyThe provisional topology before this run; null when settled_this_run is false.
settled_topologyThe stored topology after this run; a default settlement yields only single_branch or lanes_with_coord.
rulewp_count_le_2 | code_lanes_le_1 | lanes_with_coord | null.
wp_count / code_lane_countNon-canceled work packages (planning-artifact ones included) / code lanes (without lane-planning).
target_protectedInformational: the outcome is the same on an unprotected target.
previewtrue under --validate-only: nothing was written.

Error codes: POLICY_METADATA_REQUIRED, POLICY_VALIDATION_FAILED, MISSION_NOT_FOUND, TASKS_FINALIZE_FAILED (delegate call failed with no more specific error_code of its own; a typed upstream code is passed through verbatim instead).

check-prerequisites

Read-only mission-prerequisite context for /spec-kitty.analyze — it supplies context only and never performs analyze’s cross-artifact reasoning itself. No --policy required.

Request:

Terminal window
spec-kitty orchestrator-api check-prerequisites \
--mission 090-orchestrator-driven-mission \
--include-tasks
FlagRequiredMeaning
--missionyesMission slug.
--include-tasksnoInclude tasks.md validation (matches the host CLI’s own --include-tasks default of false).

Response data: the host CLI’s own validate_feature_structure shape, with mission_slug filled in (the raw shape does not already carry it).

Error codes: MISSION_NOT_FOUND (also returned — translated — when the delegate call reports its own MISSION_CONTEXT_UNRESOLVED, which never crosses this surface verbatim per the Terminology Canon), CHECK_PREREQUISITES_FAILED (fallback; any other typed upstream error_code is passed through verbatim).

record-analysis

Persists an /spec-kitty.analyze report. Success is determined by re-reading the artifact off disk after the write, never by the underlying write call’s own return/raise/hang behavior (NFR-004): a caller MUST NOT build retry logic that assumes a raised exception or a timeout means the write did not happen — it may have. Concretely, success: true requires BOTH (a) analysis-report.md’s re-read generated_at is strictly later than this call’s start timestamp, AND (b) the re-read verdict matches the verdict submitted in this call’s body. An unknown verdict (no valid analysis-findings/v1 carrier in the submitted body) is never reported as success, even when the write itself genuinely, freshly succeeds.

Request:

Terminal window
spec-kitty orchestrator-api record-analysis \
--mission 090-orchestrator-driven-mission \
--input-file analysis-report-draft.md \
--agent ci-bot \
--policy '{"orchestrator_id":"ci","orchestrator_version":"1.0.0","agent_family":"ci-bot","approval_mode":"full_auto","sandbox_mode":"workspace_write","network_mode":"none","dangerous_flags":[]}'
FlagRequiredMeaning
--missionyesMission slug.
--input-fileno (default -)Markdown report path, or - to read the report body from stdin.
--agentnoAgent name that produced the analysis report.
--policyyesPolicy metadata JSON.

Response data (success): mission_slug, path (the written analysis-report.md), verdict, generated_at.

Error codes: POLICY_METADATA_REQUIRED, POLICY_VALIDATION_FAILED, MISSION_NOT_FOUND, RECORD_ANALYSIS_INPUT_FILE_NOT_FOUND (--input-file could not be read), RECORD_ANALYSIS_EMPTY_BODY (body was empty), RECORD_ANALYSIS_MALFORMED_CARRIER (the body carried a present-but-invalid analysis-findings/v1 carrier), PLACEMENT_RESOLUTION_REQUIRED, DIRTY_WORKTREE (pre-existing uncommitted changes block the write), RECORD_ANALYSIS_WRITE_NOT_CONFIRMED (no fresh write could be confirmed by re-reading the artifact), RECORD_ANALYSIS_VERDICT_UNRELIABLE (a fresh write WAS confirmed but its re-read verdict either disagrees with what this call submitted, or the submission itself computed to unknown).

open-decision

Opens a new Decision Moment ledger entry, or returns idempotently if a matching one already exists.

Request:

Terminal window
spec-kitty orchestrator-api open-decision \
--mission 090-orchestrator-driven-mission \
--origin specify \
--input-key clarification.scope \
--question "Should this mission include the legacy migration path?" \
--step-id interview-scope \
--options '["yes", "no"]' \
--actor ci-bot \
--policy '{"orchestrator_id":"ci","orchestrator_version":"1.0.0","agent_family":"ci-bot","approval_mode":"full_auto","sandbox_mode":"workspace_write","network_mode":"none","dangerous_flags":[]}'
FlagRequiredMeaning
--missionyesMission slug.
--originyesOrigin flow: charter | specify | plan.
--input-keyyesThe input key this decision governs.
--questionyesHuman-readable question text.
--step-idnoInterview step identifier.
--slot-keynoSlot key (use when --step-id is unavailable).
--optionsnoCandidate answers as a JSON array string.
--actoryesActor identity.
--policyyesPolicy metadata JSON.

Response data: mission identity fields (mission_slug / mission_number / mission_type — no mission_id, unlike the Canonical Mission Identity payload shape documented above), decision_id, status ("open"), idempotent, artifact_path, event_lamport.

Error codes: POLICY_METADATA_REQUIRED, POLICY_VALIDATION_FAILED, MISSION_NOT_FOUND, INVALID_ORIGIN_FLOW (--origin outside {charter, specify, plan}, rejected before the decision service is ever called), DECISION_MISSING_STEP_OR_SLOT (neither --step-id nor --slot-key supplied), DECISION_ALREADY_CLOSED (a matching logical-key entry already exists in a terminal state), DECISION_EVENT_REPAIR_FAILED (the idempotent-open path could not re-emit a missing ledger event).

resolve-decision

Resolves a decision with a concrete final answer.

Request:

Terminal window
spec-kitty orchestrator-api resolve-decision \
--mission 090-orchestrator-driven-mission \
--decision-id 01HXYZDECISIONULID \
--final-answer "yes" \
--rationale "Legacy migration is in scope per stakeholder sign-off." \
--actor ci-bot \
--policy '{"orchestrator_id":"ci","orchestrator_version":"1.0.0","agent_family":"ci-bot","approval_mode":"full_auto","sandbox_mode":"workspace_write","network_mode":"none","dangerous_flags":[]}'
FlagRequiredMeaning
--missionyesMission slug.
--decision-idyesDecision ledger entry ID (ULID).
--final-answeryesThe chosen answer (non-empty).
--other-answernoSet when the answer is a write-in, not one of the offered options.
--rationalenoExplanation of the choice.
--resolved-bynoIdentity of the resolving party (falls back to --actor).
--actoryesActor identity.
--policyyesPolicy metadata JSON.

Response data: mission identity fields (mission_slug / mission_number / mission_type — no mission_id, unlike the Canonical Mission Identity payload shape documented above), decision_id, status ("resolved"), terminal_outcome, idempotent, event_lamport.

On an idempotent retry, event_lamport is the lamport of the terminal event the retry re-wrote when it was missing (contract >= 1.17.0), and null when the event was already present.

Error codes: POLICY_METADATA_REQUIRED, POLICY_VALIDATION_FAILED, MISSION_NOT_FOUND, DECISION_NOT_FOUND (--decision-id not present in the ledger), DECISION_TERMINAL_CONFLICT (the decision is already terminal with a different outcome/payload than requested — never pre-checked locally, always the service layer’s own verdict, matching the host-CLI decision_app resolve subcommand’s own error code), DECISION_EVENT_REPAIR_FAILED (an idempotent retry could not re-write the missing terminal event; contract >= 1.17.0), DECISION_LOCK_TIMEOUT (the decisions lock stayed held past the bounded wait; nothing was written, retry; contract >= 1.19.0), DESIGN_STATUS_EVENT_LOG_UNREADABLE (an idempotent retry found the event log unreadable, or decisions/index.json is unreadable).

defer-decision

Defers a decision for later resolution.

Request:

Terminal window
spec-kitty orchestrator-api defer-decision \
--mission 090-orchestrator-driven-mission \
--decision-id 01HXYZDECISIONULID \
--rationale "Awaiting stakeholder input; revisit after design review." \
--actor ci-bot \
--policy '{"orchestrator_id":"ci","orchestrator_version":"1.0.0","agent_family":"ci-bot","approval_mode":"full_auto","sandbox_mode":"workspace_write","network_mode":"none","dangerous_flags":[]}'
FlagRequiredMeaning
--missionyesMission slug.
--decision-idyesDecision ledger entry ID (ULID).
--rationaleyesExplanation of why (must be non-empty).
--resolved-bynoIdentity of the deferring party (falls back to --actor).
--actoryesActor identity.
--policyyesPolicy metadata JSON.

Response data: mission identity fields (mission_slug / mission_number / mission_type — no mission_id, unlike the Canonical Mission Identity payload shape documented above), decision_id, status ("deferred"), terminal_outcome, idempotent, event_lamport.

On an idempotent retry, event_lamport is the lamport of the terminal event the retry re-wrote when it was missing (contract >= 1.17.0), and null when the event was already present.

Error codes: POLICY_METADATA_REQUIRED, POLICY_VALIDATION_FAILED, MISSION_NOT_FOUND, DECISION_MISSING_STEP_OR_SLOT (empty/whitespace-only --rationale, rejected before the service layer is ever called — reuses this code rather than minting a new one, matching the host CLI’s own cmd_defer guard verbatim), DECISION_NOT_FOUND, DECISION_TERMINAL_CONFLICT, DECISION_EVENT_REPAIR_FAILED (an idempotent retry could not re-write the missing terminal event; contract >= 1.17.0), DECISION_LOCK_TIMEOUT (the decisions lock stayed held past the bounded wait; nothing was written, retry; contract >= 1.19.0), DESIGN_STATUS_EVENT_LOG_UNREADABLE (an idempotent retry found the event log unreadable, or decisions/index.json is unreadable).

cancel-decision

Cancels a decision deemed no longer relevant. Same request/response/error shape as defer-decision above (status is "canceled" instead of "deferred"; --rationale is likewise required and non-empty).

Request:

Terminal window
spec-kitty orchestrator-api cancel-decision \
--mission 090-orchestrator-driven-mission \
--decision-id 01HXYZDECISIONULID \
--rationale "Superseded by a later decision; no longer applicable." \
--actor ci-bot \
--policy '{"orchestrator_id":"ci","orchestrator_version":"1.0.0","agent_family":"ci-bot","approval_mode":"full_auto","sandbox_mode":"workspace_write","network_mode":"none","dangerous_flags":[]}'

Error codes: POLICY_METADATA_REQUIRED, POLICY_VALIDATION_FAILED, MISSION_NOT_FOUND, DECISION_MISSING_STEP_OR_SLOT, DECISION_NOT_FOUND, DECISION_TERMINAL_CONFLICT, DECISION_EVENT_REPAIR_FAILED (an idempotent retry could not re-write the missing terminal event; contract >= 1.17.0), DECISION_LOCK_TIMEOUT (the decisions lock stayed held past the bounded wait; nothing was written, retry; contract >= 1.19.0), DESIGN_STATUS_EVENT_LOG_UNREADABLE (an idempotent retry found the event log unreadable, or decisions/index.json is unreadable).

design-status

Read-only design-phase status query — no --policy required, no state transition, no event emission (mirrors list-ready’s contract for the design pipeline instead of the WP loop).

Fails closed rather than reporting a wrong phase. If status.events.jsonl cannot be read cleanly — a torn/truncated line, or a structural drift between the persisted status.json and a fresh event-log reduction — this verb returns DESIGN_STATUS_EVENT_LOG_UNREADABLE instead of a plausible-but-wrong current_phase/next_action. A caller can trust any current_phase this verb actually returns; it must handle the explicit unreadable case rather than treating a non-success response as “phase unknown, assume the beginning.”

Request:

Terminal window
spec-kitty orchestrator-api design-status --mission 090-orchestrator-driven-mission

Response data: mission identity fields (mission_slug / mission_number / mission_type — no mission_id, unlike the Canonical Mission Identity payload shape documented above), current_phase (specify | plan | tasks | analyze), next_action (the verb the host should call next, or null once the design phase is complete; overridden to resolve-decision whenever any decision is open, regardless of phase), open_decisions (list of {decision_id, origin} for every open ledger entry, from any phase).

Error codes: MISSION_NOT_FOUND, DESIGN_STATUS_EVENT_LOG_UNREADABLE.

answer-decision

Resolves a spec-kitty next control-loop decision_required moment (a blocking audit checkpoint, or a missing required input) for a DAG step in any mission phase.

This is a composite verb, not a simple single-purpose call. One invocation performs, in order: (1) persists the answer against the resolved decision_id; (2) pairs the previous issuance’s lifecycle record before the DAG advances; (3) advances the DAG (the engine call that produces the next Decision, using this call’s own --result); (4) emits the mission’s MissionNextInvoked event-log entry; (5) writes a new issuance lifecycle record whenever the resulting decision’s kind is "step". Steps 2/4/5 are full host-CLI lifecycle parity — answer-decision reaches them through the same extracted seam spec-kitty next --answer ... itself calls (operator ruling SPEC-FRESH2-001), so a host driving decisions exclusively through answer-decision produces the identical event log and lifecycle-record trail a host shelling spec-kitty next --answer would have produced. Treat this parity as a promise: an external host does not need to also call the host CLI to keep the mission’s audit trail complete.

Request:

Terminal window
spec-kitty orchestrator-api answer-decision \
--mission 090-orchestrator-driven-mission \
--agent ci-bot \
--answer "yes" \
--result success \
--policy '{"orchestrator_id":"ci","orchestrator_version":"1.0.0","agent_family":"ci-bot","approval_mode":"full_auto","sandbox_mode":"workspace_write","network_mode":"none","dangerous_flags":[]}'
FlagRequiredMeaning
--missionyesMission slug.
--agentyesAgent/actor identity performing this call.
--answeryesThe answer value to persist for the pending decision.
--resultyesOutcome of the current issuance: success | failed | blocked.
--decision-idnoRun-snapshot pending decision id to answer; auto-resolved when omitted and exactly one decision is pending.
--policyyesPolicy metadata JSON.

Response data: the SAME shape spec-kitty next --answer ... --json returns — every Decision.to_dict() field (kind, agent, mission_slug, mission_number, mission_type, mission, mission_state, timestamp, action, wp_id, workspace_path, prompt_file, reason, guard_failures, progress, origin, run_id, step_id, decision_id, input_key, question, options, is_query, preview_step) — plus one sibling field, answered_decision_id (the decision_id this call persisted the answer against). Note Decision.to_dict() does NOT carry a mission_id field (unlike the Canonical Mission Identity payload shape documented above, its mission_identity_fields() helper here only normalizes mission_slug / mission_number / mission_type). data does not carry an answer echo key; the host CLI’s terser answered key is similarly not used.

Since contract 1.16.0, data also carries a warnings key (a list of strings) only when the Step-1 decision-log safe_commit was refused — byte-identical to the host next --answer --json surface (#6222, follow-up to #3930). On a clean commit the key is absent and the payload is unchanged. A warnings entry means the answer event was written to decisions.events.jsonl but not committed to git, so the committed decision record may be stale; the answer itself is not lost locally.

Error codes: POLICY_METADATA_REQUIRED, POLICY_VALIDATION_FAILED, MISSION_NOT_FOUND, RESULT_REQUIRED (--result omitted), INVALID_RESULT (--result is not one of success/failed/blocked, rejected before any decision resolution or persistence), NO_PENDING_DECISION (no pending decision exists to answer), AMBIGUOUS_PENDING_DECISION (more than one pending decision and --decision-id was omitted — lists the candidate ids), DECISION_NOT_PENDING (an explicit --decision-id does not match any currently-pending entry).

Example Commands

Terminal window
spec-kitty orchestrator-api contract-version
spec-kitty orchestrator-api mission-state --mission 077-mission-terminology-cleanup
spec-kitty orchestrator-api list-ready --mission 077-mission-terminology-cleanup
spec-kitty orchestrator-api start-implementation \
--mission 077-mission-terminology-cleanup \
--wp WP12 \
--actor codex \
--policy '{"orchestrator_id":"local","orchestrator_version":"1.0.0","agent_family":"codex","approval_mode":"never","sandbox_mode":"danger-full-access","network_mode":"enabled","dangerous_flags":[]}'

Start implementation

Terminal window
spec-kitty orchestrator-api start-implementation \
--mission 077-mission-terminology-cleanup \
--wp WP12 \
--actor spec-kitty-orchestrator \
--policy '{"orchestrator_id":"spec-kitty-orchestrator","orchestrator_version":"0.1.0","agent_family":"claude","approval_mode":"full_auto","sandbox_mode":"workspace_write","network_mode":"none","dangerous_flags":[]}'

Important response fields:

FieldMeaning
workspace_pathPath where the provider should run the implementation agent.
prompt_pathWP markdown prompt file to feed to the implementation agent.
to_laneExpected to be in_progress on a fresh start.
no_optrue when the same actor already owns the compatible state.

Resolve an existing workspace (read-only, contract >= 1.2.0)

Terminal window
spec-kitty orchestrator-api resolve-workspace \
--mission 077-mission-terminology-cleanup \
--wp WP12

Returns the WP’s lane workspace_path / prompt_path (plus lane_id / lane_branch / lane_base_ref when the WP is lane-assigned) for its existing lane — without allocating, creating, validating-clean, or transitioning. Use it to resume a WP already past start-implementation (for example, dispatching a reviewer to a WP parked in for_review after an interrupted run, where calling start-implementation would wrongly re-transition it). No --policy is required: the command mutates nothing. The composed path is not guaranteed to exist for a WP that was never started.

Mark implementation ready for review

Terminal window
spec-kitty orchestrator-api transition \
--mission 077-mission-terminology-cleanup \
--wp WP12 \
--to for_review \
--actor spec-kitty-orchestrator \
--policy '{"orchestrator_id":"spec-kitty-orchestrator","orchestrator_version":"0.1.0","agent_family":"claude","approval_mode":"full_auto","sandbox_mode":"workspace_write","network_mode":"none","dangerous_flags":[]}' \
--subtasks-complete \
--implementation-evidence-present \
--note "Implementation complete"

in_progress -> for_review requires evidence that the implementation handoff is ready. Providers may supply the explicit guard hints shown above or omit them and let the host derive the facts. --force is reserved for recovery.

Claim review

Terminal window
spec-kitty orchestrator-api start-review \
--mission 077-mission-terminology-cleanup \
--wp WP12 \
--actor spec-kitty-orchestrator \
--policy '{"orchestrator_id":"spec-kitty-orchestrator","orchestrator_version":"0.1.0","agent_family":"codex","approval_mode":"full_auto","sandbox_mode":"workspace_write","network_mode":"none","dangerous_flags":[]}' \
--review-ref review/WP12/attempt-1

On current hosts this moves for_review -> in_review.

Complete approved review

Terminal window
spec-kitty orchestrator-api transition \
--mission 077-mission-terminology-cleanup \
--wp WP12 \
--to done \
--actor spec-kitty-orchestrator \
--policy '{"orchestrator_id":"spec-kitty-orchestrator","orchestrator_version":"0.1.0","agent_family":"codex","approval_mode":"full_auto","sandbox_mode":"workspace_write","network_mode":"none","dangerous_flags":[]}' \
--review-ref review/WP12/attempt-1 \
--review-result-json '{"reviewer":"codex","verdict":"approved","reference":"review/WP12/attempt-1"}' \
--evidence-json '{"review":{"reviewer":"codex","verdict":"approved","reference":"review/WP12/attempt-1"}}' \
--note "Codex review approved"

The structured review result satisfies the in_review exit guard; done evidence keeps the terminal event independently auditable. --force remains recovery-only.

Send rejected review back to rework

Terminal window
spec-kitty orchestrator-api transition \
--mission 077-mission-terminology-cleanup \
--wp WP12 \
--to in_progress \
--actor spec-kitty-orchestrator \
--policy '{"orchestrator_id":"spec-kitty-orchestrator","orchestrator_version":"0.1.0","agent_family":"codex","approval_mode":"full_auto","sandbox_mode":"workspace_write","network_mode":"none","dangerous_flags":[]}' \
--review-ref review/WP12/attempt-1 \
--review-result-json '{"reviewer":"codex","verdict":"changes_requested","reference":"review/WP12/attempt-1"}' \
--note "Review rejected; rework required"

Then rerun the implementation agent with the review feedback and transition back to for_review.

Worktree Expectations

The host returns the workspace path. The provider is responsible for ensuring the path exists and is usable for the agent process before spawning an agent. Do not treat the returned string as proof that a worktree already exists.

State mutation commands should not be run from a protected main branch when they need to commit activity-log updates. Use a mission lane/worktree branch for provider-owned mutation calls.

Error Codes

Current machine-readable error codes (the authoritative list is allowed_error_codes in src/specify_cli/core/upstream_contract.json). The list between the markers is the human enumeration, and tests/contract/test_orchestrator_api.py::TestProseErrorCodeEnumerations compares it with that file: a registered code missing here, a code listed here that is not registered, and a code listed twice each fail the contract suite, so a new code is documented in the same change that registers it.

  • USAGE_ERROR
  • POLICY_METADATA_REQUIRED
  • POLICY_VALIDATION_FAILED
  • INVALID_MISSION — --mission is not a safe path segment (.., a path separator, a leading dot, non-ASCII), refused before any path join, with data.reason carrying the guard’s message
  • MISSION_NOT_FOUND
  • STATUS_READ_PATH_NOT_FOUND
  • WP_NOT_FOUND
  • TRANSITION_REJECTED
  • BOOKKEEPING_FAILED — start-implementation, start-review, transition: the transactional status write refused; data.bookkeeping_error_code carries the refusal’s own code (BOOKKEEPING_LOCK_TIMEOUT retryable, BOOKKEEPING_POLICY_REFUSED, BOOKKEEPING_WORKTREE_MISSING, BOOKKEEPING_COMMIT_FAILED, BOOKKEEPING_DOUBLE_EVENT_ID, BOOKKEEPING_LEGACY_RESOLUTION_FAILED, COORD_STATUS_SURFACE_DIVERGED, COORD_STATUS_SURFACE_UNREADABLE). On start-implementation this is a different lock from STATUS_LOCK_HELD: STATUS_LOCK_HELD means the single_branch write-checkout claim lock stayed held, while BOOKKEEPING_FAILED with BOOKKEEPING_LOCK_TIMEOUT means the status-write lock did. Both are retryable.
  • WP_ALREADY_CLAIMED (for start-implementation on an in_progress WP after a reviewer’s rework verdict, the WP’s implementer of record is admitted as a no_op resume rather than refused; an unrelated actor is still refused)
  • MISSION_NOT_READY (on accept-mission, data.preflight_error_code can refine it with an origin freshness code; see below)
  • WORKFLOW_EVIDENCE_REQUIRED — a terminal transition’s required structured workflow evidence is missing; the current host derives those facts instead of returning this code, but the contract registers it
  • PREFLIGHT_FAILED (on consolidate-mission, data.preflight_error_code or data.teardown_error_code can refine it; see below)
  • CONTRACT_VERSION_MISMATCH
  • UNSUPPORTED_STRATEGY
  • HISTORY_COMMIT_FAILED
  • DEPENDENCIES_NOT_SATISFIED
  • LANE_ALLOCATION_FAILED
  • ANCESTRY_NOT_ESTABLISHED
  • STATUS_LOCK_HELD (start-implementation: the single_branch write-checkout claim lock stayed held past its bound; retry)
  • 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_DIRECTORY_ARGUMENT (a requested path is a directory; safe_commit commits an exact file set, so a directory pathspec is refused before anything is written — nothing was committed, and data.offending_path names the path)
  • SAFE_COMMIT_PATH_LOOP
  • SAFE_COMMIT_INDEX_DELETION_CONFLICT
  • SAFE_COMMIT_INDEX_RESIDUE (the commit DID land; commit_sha names it; a SAFE_COMMIT_RECOVERY_FAILED refinement)
  • SAFE_COMMIT_RECOVERY_FAILED
  • SAFE_COMMIT_STAGED_TREE_UNCHANGED — append-history: the staged tree scoped to the requested paths matches HEAD, so the safe commit has nothing to record
  • SAFE_COMMIT_UNREQUESTED_PATHS (a pre-commit hook swept unrequested tracked paths into the commit, which DID land; commit_sha names it; the real index is re-synced for those paths; a SAFE_COMMIT_RECOVERY_FAILED refinement, contract 1.15.0)
  • MISSION_ALREADY_EXISTS — specify
  • MISSION_CREATE_FAILED — specify
  • PLAN_SETUP_FAILED — plan
  • TASKS_FINALIZE_FAILED — tasks
  • PLACEMENT_RESOLUTION_REQUIRED — record-analysis
  • CHECK_PREREQUISITES_FAILED — check-prerequisites
  • RECORD_ANALYSIS_EMPTY_BODY — record-analysis
  • RECORD_ANALYSIS_INPUT_FILE_NOT_FOUND — record-analysis
  • RECORD_ANALYSIS_MALFORMED_CARRIER — record-analysis
  • RECORD_ANALYSIS_WRITE_NOT_CONFIRMED — record-analysis
  • RECORD_ANALYSIS_VERDICT_UNRELIABLE — record-analysis
  • DIRTY_WORKTREE — record-analysis
  • INVALID_ORIGIN_FLOW — open-decision
  • DECISION_MISSING_STEP_OR_SLOT — open-decision, defer-decision, cancel-decision
  • DECISION_ALREADY_CLOSED — open-decision
  • DECISION_NOT_FOUND — resolve-decision, defer-decision, cancel-decision
  • DECISION_TERMINAL_CONFLICT — resolve-decision, defer-decision, cancel-decision
  • DECISION_EVENT_REPAIR_FAILED — open-decision, resolve-decision, defer-decision, cancel-decision
  • DECISION_LOCK_TIMEOUT — resolve-decision, defer-decision, cancel-decision
  • DECISION_OPERATION_FAILED — open-decision, resolve-decision, defer-decision, cancel-decision (fallback when a decision-ledger operation fails for a reason without a more specific registered code)
  • DESIGN_STATUS_EVENT_LOG_UNREADABLE — design-status, open-decision, resolve-decision, defer-decision, cancel-decision, plan, artifact-submit
  • RESULT_REQUIRED — answer-decision
  • INVALID_RESULT — answer-decision
  • NO_PENDING_DECISION — answer-decision
  • AMBIGUOUS_PENDING_DECISION — answer-decision
  • DECISION_NOT_PENDING — answer-decision
  • DESIGN_ARTIFACT_UNSUPPORTED — artifact-read, artifact-submit: the configured artifact name is invalid, the Mission type does not declare it, or the kind is not an authoring capability
  • DESIGN_BOUNDS_EXCEEDED — artifact-read, artifact-submit, design-validate: an artifact, request or batch exceeds the documented byte bound
  • DESIGN_COMMIT_FAILED — artifact-submit: the content materialized but the host commit did not complete; inspect the reported effect state and commit outcome before retrying
  • DESIGN_CONTEXT_FAILED — design-context, interview-record, artifact-submit, design-validate: the resolved design context cannot be built — an undeclared design stage, host content over the inline byte limit, or an activated Mission with no template mapping
  • DESIGN_CONTEXT_STALE — artifact-submit, design-validate, tasks: the resolved template or governance context changed since the content was authored; re-read design-context and resubmit
  • DESIGN_FINALIZED — plan, artifact-submit: an API-authored Mission whose native task board is finalized refuses plan scaffolding and design writes; native reconciliation applies instead
  • DESIGN_INTERVIEW_FAILED — design-context, interview-record, artifact-submit, design-validate: the interview ledger could not be read, or a requested answer could not be recorded; the failure carries the decision IDs already applied, if any, and asks for reconciliation before retrying
  • DESIGN_INTERVIEW_INCOMPLETE — artifact-submit, design-validate, tasks: required interview answers are still pending, deferred or canceled; interview-record reports that state as data.interview.complete: false rather than refusing
  • DESIGN_INTERVIEW_INVALID — interview-record: the answers are not bounded UTF-8 JSON, the mapping is empty, or the actor identity is missing
  • DESIGN_IO_FAILED — artifact-read, artifact-submit, design-validate: the host could not read or persist design content
  • DESIGN_LOCK_TIMEOUT — artifact-read, artifact-submit, tasks: the Mission authoring lock stayed busy past its bound; nothing was written, retry
  • DESIGN_PARENT_STALE — artifact-submit, design-validate, tasks: an accepted parent artifact is missing or changed, or accepted content changed outside its authoring receipt
  • DESIGN_PATH_REFUSED — artifact-read, artifact-submit: an artifact identifier or location is not a single safe basename or a declared destination
  • DESIGN_PREREQUISITES_FAILED — artifact-read, artifact-submit, design-validate, tasks: canonical prerequisites are unmet — open decisions, missing accepted provenance, an invalid outline, or an invalid bounded package graph
  • DESIGN_RECEIPT_UNREADABLE — artifact-submit, design-validate: API authoring provenance is missing or corrupt while the API-enabled marker stands, or a post-commit receipt write failed; reconcile the effects
  • DESIGN_REQUEST_INVALID — artifact-read, artifact-submit, design-validate: the request is not bounded UTF-8 JSON, carries unknown fields, supplies runtime or status authority, names an unknown stage, or selects an identifier the kind does not take
  • DESIGN_REVISION_CONFLICT — artifact-submit: the artifact revision changed since its expected_sha256 was read; re-read and resubmit
  • RUNTIME_BLOCKED — next: the native runtime reported a blocked outcome; the typed payload explains why and the exit code is nonzero
  • RUNTIME_NEXT_FAILED — next: the native step, prompt or request was refused; the exit code is nonzero
  • UNSUPPORTED_CAPABILITY — contract-version --require-capability: the Python delivery profile does not register the requested capability; data.capability names it

Contract 1.4.0 (#3837) added the design-phase, analysis and decision verbs and their codes; 1.12.0 added governed authoring and native next and their DESIGN_*, RUNTIME_* and UNSUPPORTED_CAPABILITY codes; the version-history bullets above name the later additions. The data.preflight_error_code, data.teardown_error_code and origin-freshness codes in the subsections below are a different namespace: they ride inside data, they are not allowed_error_codes entries, and this enumeration does not cover them.

consolidate-mission: data.preflight_error_code

consolidate-mission merges the code lanes directly, with no reconciliation claim behind it, so it checks every approved lane against the commit review approved before it merges the first one. A lane that fails keeps the PREFLIGHT_FAILED envelope code, puts the message in data.errors, and carries a stable code in data.preflight_error_code. No branch was moved.

data.preflight_error_codeMeaningWhat to do
LANE_MOVED_AFTER_APPROVALThe lane holds a content commit made after review approved it.Move the work package back for review, approve it again, re-run.
APPROVAL_STAMP_MISSINGAn approved work package records no lane head, so what review approved cannot be determined.Move it back for review and approve it again, or attest the approval with spec-kitty consolidate --attest-approved-reviewed (the host command only).
APPROVAL_STAMP_NOT_ON_LANEThe approval names a commit that is not on the lane: the lane was rewritten after review.Move the work package back for review, approve it again, re-run.
IMPLEMENTATION_MISSING(1.21.0) An approved work package’s evidence window holds no change to its owned_files (Mission files the CLI writes itself, such as tasks/, lanes.json or acceptance-matrix.json, never count).Commit the work package’s change to its owned files and have it reviewed and approved again, or record spec-kitty accept / spec-kitty consolidate --attest-no-implementation <WP> --attest-reason "<why>" (host commands only) when it owes none.
REVIEW_NOT_INDEPENDENT(1.21.0) The approver is not provably another identity than the implementer of record: the same tool with no model or profile recorded on both sides that differs, or an identity that is not recorded (a placeholder such as user included).Have a reviewer with another identity review and approve it (--agent <tool>:<model>:<profile>). No attestation lifts it.
IMPLEMENTATION_UNREADABLE(1.21.0) The evidence window cannot be diffed, for example the lane branch or the recorded planning commit is gone. A lane branch that is truly absent is reported as absent, with its own cause.Restore or fetch actual recorded lane history and the planning commit where they existed. Local refs, including sibling presence, do not prove the missing lane ever existed; never manufacture its window from target-branch work. No local lane refs is also consistent with target-branch execution, pruning or an incomplete fetch. The verified PR-merge route (accept --mode pr --merge-commit <sha>) stays available under its existing checks. Without that landing or a lane window to restore, escalate #7120 instead of retrying that window.
EVIDENCE_WINDOW_UNCOMPUTABLE(1.21.0) lanes.json records no planning commit, or the work package is in no lane.Re-run spec-kitty agent mission finalize-tasks, re-run.
OWNERSHIP_UNRESOLVED(1.23.0) The work package’s owned_files cannot be read: its task file, or the whole tasks/ directory, is missing or unreadable, so there is no declaration to judge the evidence against. An authored empty list is not this case.Restore or commit the task file with its owned_files, or run from the checkout that owns the Mission, re-run. No attestation lifts it.
SINGLE_BRANCH_OWNERSHIP_UNRESOLVED(1.23.0, #7149) The single_branch alias of OWNERSHIP_UNRESOLVED.As for OWNERSHIP_UNRESOLVED.
SINGLE_BRANCH_IMPLEMENTATION_MISSING, SINGLE_BRANCH_REVIEW_NOT_INDEPENDENT, SINGLE_BRANCH_EVIDENCE_WINDOW_UNCOMPUTABLE(#5939) The same three meanings on a single_branch Mission, which keeps emitting these aliases.As for the neutral code.
TARGET_OVERRIDE_RECORDED_TARGET_UNWRITABLE(1.28.0, #5783) --target names a branch other than the Mission’s recorded target, and the recorded target’s bookkeeping (the done transitions on a Mission without a coordination branch, the coordination flatten) cannot be committed in this run: the checkout it commits in is on the --target branch.Drop --target and consolidate into the recorded target from a checkout of it, or correct target_branch in the Mission’s meta.json, commit it, and re-run without --target.
RETARGET_RESUME_MISMATCH(#7692) The Mission’s merge record holds a retarget that an interrupted spec-kitty consolidate --target <b> --retarget persisted. This command has no --retarget and no rollback, so it neither finishes that retarget nor lands on any other target while it is recorded. Before #7692 such a record could not exist; no contract bump.Finish the retarget with spec-kitty consolidate --mission <slug> --resume, or drop it with spec-kitty consolidate --mission <slug> --abort, then re-run.
CHECKOUT_SKIP_WORKTREE_ENTRIES(1.29.0, #7692) A checkout holding the target or the Mission branch marks a file this run writes (under the Mission directory, or a path the Mission and lane branches change) as skip-worktree, so git would leave the write out of the run’s commits and could not resync the checkout.Clear the bit with the git update-index --no-skip-worktree <paths> command the message names, then re-run.
SINGLE_BRANCH_EVIDENCE_UNREADABLE(#5939) The single_branch alias of IMPLEMENTATION_UNREADABLE, as consolidate-mission, accept-mission, accept and consolidate emit it. (move-task emits the other alias, SINGLE_BRANCH_IMPLEMENTATION_UNREADABLE, for the same meaning.)As for IMPLEMENTATION_UNREADABLE.

data.preflight_error_code is the first code the message names. data.preflight_error_codes is a list of every distinct code the message names, in the order they appear, so a mission whose lanes refuse for different reasons reports all of them. Both keys are absent on every other failure. The host command spec-kitty consolidate reports the same codes in its message and exits 1. When a mixed-lane refusal also applies, it prints that refusal first and the approval-bound codes after This Mission also has:; consolidate-mission never raises the mixed-lane refusal, so its list holds only the approval-bound and evidence codes above.

accept-mission and consolidate-mission: origin freshness

Before either command reads evidence or moves a branch, it asks the remote of each branch it is about to trust (one contact per remote, never prompts). The listing is bounded at 5 seconds and the fetch that follows, skipped when the listing shows nothing new, at 15 seconds more, so a check takes at most 20 seconds. With no remote, or a branch that was never pushed, nothing is contacted and nothing changes. A refusal keeps the envelope code the command already used, MISSION_NOT_READY for accept-mission and PREFLIGHT_FAILED for consolidate-mission, puts the message in data.errors, and adds these keys. No branch was moved.

data.preflight_error_codeMeaningWhat to do
ORIGIN_STATUS_STALEThe remote’s status evidence branch has commits that change this Mission’s status.events.jsonl and that your clone lacks (or the branch is diverged).Run the git pull command the message names in the evidence checkout, then re-run. With a merge record present, abort first, as the message says.
ORIGIN_LANE_STALE (state behind)consolidate-mission only: an approved lane’s remote tip is ahead of the local lane, which has nothing origin lacks.git fetch <remote> <lane>, then git -C <lane worktree> merge --ff-only <remote>/<lane> (or git branch -f <lane> <remote>/<lane> when no checkout holds the lane), then re-run.
ORIGIN_LANE_STALE (state local_missing)The approved lane exists on the remote but not locally.git branch <lane> <remote>/<lane>, then re-run.
ORIGIN_LANE_STALE (state diverged)The lane has commits origin lacks and origin has commits the lane lacks.Merge origin’s lane in (git -C <lane worktree> merge <remote>/<lane>), or, if the local lane is the truth, merge or rebase it onto <remote>/<lane> first, then push. Never git branch -f: it drops the local commits. Then re-run.
ORIGIN_UNREACHABLEA remote resolved but could not be reached in this invocation: it timed out (5 s listing, 15 s fetch) or the transport failed.A timeout may only be slowness: retry. Otherwise restore connectivity, or re-run with --origin-check warn (or set SPEC_KITTY_ORIGIN_CHECK=warn).
ORIGIN_REMOTE_AMBIGUOUSThe repository has remotes but none owns the branch: no branch.<name>.remote, not exactly one remote, and no origin. data.origin_freshness[].detail lists the remotes.Run git config branch.<name>.remote <remote> for the branch, then re-run, or re-run with --origin-check warn.
ORIGIN_COMPARE_FAILEDThe remote answered, but git could not compare the local branch with its fetched tip (a shallow-clone boundary or a damaged ref). data.origin_freshness[].detail carries the git error text.Run git fetch --unshallow <remote> (or repair the ref), then re-run, or re-run with --origin-check warn.

data.preflight_error_code is the first code the message names and data.preflight_error_codes lists every distinct code, as for the codes above.

data.origin_freshness is a list with one row per branch that failed the check:

{
"branch": "kitty/mission-my-mission-01ABCDEF",
"remote": "origin",
"state": "behind",
"behind": 2,
"ahead": 0,
"scope": "kitty-specs/my-mission/status.events.jsonl",
"detail": null
}

state is one of up_to_date, behind, ahead, diverged, local_missing, remote_missing, unreachable, no_remote, remote_ambiguous or compare_failed. A remote_missing row is never a refusal; its detail is set when this clone once saw the branch on the remote and the remote no longer lists it (the branch may have been deleted there), and the same text is a warning. scope names the status log the status evidence row was judged on and is null for a lane. detail says why a remote was unreachable or could not be compared (the git error text), lists the remotes of a remote_ambiguous branch, or notes that a no_remote clone still holds remote-tracking refs (its remote was removed; a warning, never a refusal), and is null otherwise. A consolidate-mission origin refusal also carries data.target_branch, like every other PREFLIGHT_FAILED of that command. With --origin-check warn, or SPEC_KITTY_ORIGIN_CHECK=warn, the command does not refuse: it continues, writes each warning to stderr, and a successful envelope carries them in data.origin_warnings (a list of strings). A coordination Mission whose coordination branch exists only on the remote is not judged here; the existing COORDINATION_WORKTREE_UNMATERIALIZED refusal applies.

--origin-check also accepts off (and so does SPEC_KITTY_ORIGIN_CHECK=off). The command then contacts no remote, never refuses on freshness, and carries one warning in data.origin_warnings and on stderr saying that origin was not checked and stale evidence is accepted. Use it only where you cannot reach the remote and accept that a teammate’s newer status events or lane commits go unseen: a rejection pushed to origin can then land as done.

consolidate-mission: data.lane_cleanup

(contract >= 1.25.0) On success, data.lane_cleanup lists every code lane of the Mission in lanes.json order. Cleanup runs after the landing, mission branch first, then the lanes; it never fails the envelope.

KeyMeaning
lane_idThe lane, e.g. lane-a.
branchThe lane branch (kitty/mission-<slug>-<lane>).
worktreeThe lane worktree, relative to the repository root (.worktrees/<slug>-<lane>).
outcomeremoved, kept (the cleanup could not prove the removal safe) or retained_by_policy (retain_worktrees / retain_branches in meta.json).
codeWhen kept: the refusal code, e.g. MERGE_UNSAFE_WORKTREE_DIRTY, BRANCH_HAS_UNIQUE_COMMITS, WORKTREE_REMOVE_REFUSED_BY_GIT, PROCESS_IN_WORKTREE, PROCESS_PROOF_UNAVAILABLE (running processes cannot be checked on this platform). null otherwise.
remedyWhen kept: what to do first.
commandWhen kept: the command to run afterwards, spec-kitty doctor workspaces --prune.
recreateWhen removed and a branch was deleted: git branch <branch> <sha> restores it.

spec-kitty consolidate prints the same outcomes in its “Lane cleanup” block and exits 0 after a verified landing whatever they are.

consolidate-mission: data.teardown_error_code

A consolidate-mission failure keeps the PREFLIGHT_FAILED envelope code and puts the message in data.errors. When the landing succeeded and only the cleanup after it refused, data also carries teardown_error_code, a stable code to key on instead of the prose. A PREFLIGHT_FAILED without a teardown_error_code is raised before any lane/target mutation; a refusal leaves refs untouched.

data.teardown_error_codeMeaningWhat to do
COORD_MOVED_AFTER_LANDINGThe mission branch moved after the landing was verified. The branch was kept, the late commit is intact and the landed target stands.Review the commit(s) with the git log command in the message, land any that belong on the target, then delete the branch.

The key is absent on every other failure. The message in data.errors ends with Error code: COORD_MOVED_AFTER_LANDING. The host command spec-kitty consolidate reports the same condition with exit code 75.

consolidate-mission does not run the host command’s reconciliation gate, so the gate’s verdict codes (APPROVED_CONTENT_MISSING, CANCELED_REACHABLE_VIA_DEPENDENCY and the others in the status model) are never reported here, and --resume and --attest-canceled-superseded exist only on spec-kitty consolidate. The full list of that command’s exit codes and codes is in the CLI reference.

Provider Rules

  • Call contract-version once before mutating state.
  • Use only orchestrator-api for lane changes.
  • Keep retry decisions based on error_code, not prose.
  • Preserve review_ref values in logs and issue/PR links.
  • Treat mission-state as authoritative after every recovery.
  • Keep agent stdout/stderr in provider logs; do not stuff full logs into WP history entries.

Migration Notes

  • The human-facing CLI still supports hidden deprecated aliases during the migration window.
  • The orchestrator API does not. It is canonical-only on --mission and mission_* payload fields.

See also:

Governed planning delivery (Python profile)

Contract 1.12.0 adds six verbs to Stijn’s existing concern-module registry. It implements the Mission discovery, interview, authored specification/plan, task authoring and native lifecycle slice of spec-kitty.orchestrator/2. The transport remains the existing Python JSON envelope. It is a translation profile, with full_go_conformance: false; clients must not infer Go transport or transaction guarantees from the semantic family name. The corresponding Go contract amendment defines the lifecycle coverage.

contract-version now returns data.delivery_profile, including supported commands, translated operations, limits and unavailable capabilities. contract-version --require-capability artifact-submit probes a required capability without changing a Mission. Unknown or unavailable names return UNSUPPORTED_CAPABILITY. The provider-version handshake still applies.

Semantic operationPython command or authority
Discover Mission types and resolved planning contextdesign-context
Create a Missionspecify and native creation service
Record specification/planning interviewsinterview-record and native decision service
Read or submit governed planning contentartifact-read, artifact-submit
Check design prerequisitesdesign-validate and canonical validators
Issue/complete runtime actionsnext and native lifecycle authority
Finalize task graph and seed ready worktasks and native finalizer
Read work progressExisting mission-state, list-ready, design-status

Unavailable guarantees include GapDB atomic journals, runtime leases/fences, immutable Go WorkRevision generations, native asynchronous operations, watches, durable operation replay and remote serving. These verbs execute in the local host. Tracker publication remains a separate integration.

design-context

Read-only, with --stage specify|plan|tasks. Before creation, omit --mission and explicitly select an activated --mission-type. For an existing Mission, its recorded Mission type governs context; an incompatible override is refused.

Terminal window
spec-kitty orchestrator-api design-context --mission-type software-dev --stage specify
spec-kitty orchestrator-api design-context --mission "$MISSION" --stage plan

Data contains mission_slug (null before creation), mission_type, activated mission_types, resolved templates, canonical questions, interview status, action-scoped governance, context_sha256 and published limits. Template keys retain the resolved template-set vocabulary (spec and plan for software-dev); artifact submission uses the separate closed kind vocabulary below. Each template includes bounded UTF-8 content and a SHA-256 revision. The context digest covers semantic template/governance inputs rather than session metadata or local absolute paths. Reading it does not mark doctrine as loaded or complete a workflow phase.

interview-record

Mutation requires --mission, --stage specify|plan, --answers (a JSON mapping of canonical question IDs to nonempty answers), --actor and --policy. Discover the IDs with design-context; submit answers incrementally. The native decision ledger owns their identities and terminal states.

Terminal window
spec-kitty orchestrator-api interview-record --mission "$MISSION" --stage specify \
--answers '{"problem_statement":"Describe the actual problem"}' --actor client --policy "$POLICY"

Only resolved nonempty answers satisfy a required slot. Pending, deferred and canceled decisions remain incomplete. Retrying an identical resolved answer is idempotent; conflicting terminal answers refuse. data.interview contains complete, incomplete, answers, questions and decision_ids. If a native batch fails after earlier answers were applied, the failure reports those decision IDs and reconciliation_required; callers must reconcile that outcome before retrying. It does not claim transaction rollback.

artifact-read

Read-only, with --mission, --kind and optional --artifact-id. Closed kinds:

KindCanonical content
specificationspec.md
planplan.md
researchresearch.md
data_modeldata-model.md
quickstartquickstart.md
contractRegistered contract basename under contracts/
outlinewps.yaml
work_packagePrompt for a package declared in the outline

Contracts and work packages require a safe --artifact-id. Raw caller paths and undeclared packages are refused. Data includes kind, artifact_id, content and exact-byte sha256. Missing content is explicit: null content, revision absent. Reads use host-resolved artifact placement.

artifact-submit

Mutation requires --mission, --request-json, --actor and --policy. The request is a closed object: unknown fields refuse. Use --request-json - to send bounded UTF-8 JSON on stdin; external CLI clients should use this form so content size does not depend on OS argument limits. Literal JSON remains supported for small requests.

{
"artifacts": [{
"kind": "plan",
"content": "Authored substantive plan text",
"expected_sha256": "absent"
}],
"parents": {"specification": "<current 64-character SHA-256>"},
"context_sha256": "<current design-context digest for plan>"
}

Use artifact-read for each expected target revision and required parent, and design-context for the stage digest. A plan pins its specification; an outline pins specification and plan; a package also pins its outline. Supporting plan artifacts use plan context. Early research uses specification context and can precede the first specification without a specification parent. Resolved required interview slots and substantive committed parent content are checked before writes. The complete bounded batch is validated before effects.

Host-owned accepted lineage is checked again at validation/finalization: passing a new current parent digest cannot make an already stale plan or prompt current. Once the native task board is finalized, API design edits and plan scaffolding refuse with DESIGN_FINALIZED. This surface does not reopen work.

Data contains accepted artifact identities/revisions and the actual host commit outcome, without echoing content. A cooperative host lock serializes API writers. It does not lock every existing CLI/manual writer. Files and Git commit effects precede receipt persistence; partial failures report materialized/committed effects or reconciliation_required. Inspect that outcome before retrying. Receipts live in the Git common directory, are shared between linked worktrees, and are not portable between clones. Missing/corrupt receipts while the separate persistent API-enabled marker remains present fail closed. The marker and receipts are trusted host metadata; deleting both or using another clone does not preserve the host’s API provenance history.

Bounds: 256 KiB per artifact, 1 MiB per batch, at most 64 artifacts. Context responses are at most 1 MiB; interview answers at most 16 KiB each and interview actor identity at most 1 KiB. Artifact submission actor identity is at most 256 bytes. Artifact request JSON is at most 2 MiB (including JSON escaping and structure). Limits count UTF-8 bytes.

design-validate

Read-only, with --mission and --stage specify|plan|tasks. Checks substantive, committed, current content, required resolved decisions and canonical stage requirements. Task checks include the declared graph, package prompts and requirement references. It does not mark a runtime action complete or finalize packages. tasks remains the finalization command and native next remains the completion authority. Legacy manual planning without API receipts retains its existing workflow.

next

next --mission "$MISSION" queries the native runtime without starting a run or advancing an action, even when --agent is provided. Advancement requires --agent, --result success|failed|blocked and --policy. Optional --answer and --decision-id follow the native pending-decision rules.

Terminal window
spec-kitty orchestrator-api next --mission "$MISSION"
spec-kitty orchestrator-api next --mission "$MISSION" --agent client \
--result success --policy "$POLICY"

The first advancement issues an action; later paired results complete the actually issued native action. For API-authored content, successful completion of specify/plan/tasks revalidates that stage under the authoring lock. An initial preview is not an issued action. Native lifecycle pairing, charter preflight, run index and decisions remain authoritative.

Typed native query/step/decision-required/terminal data is preserved. Issued steps include bounded prompt: {content, sha256, bytes}; host absolute prompt_file is not exposed. Native errors return RUNTIME_NEXT_FAILED; blocked outcomes return RUNTIME_BLOCKED, both with nonzero exit. A decision-required state is a successful typed response requiring client action.

API-only planning sequence

Discover context → specify → record specification interview → submit and validate specification → plan scaffold → record plan interview → submit and validate substantive plan → submit outline → submit declared prompts → validate tasks → tasks finalize → list-ready. Supporting artifacts may be submitted through the same governed seam. Clients that drive native actions also query and submit paired results through next; scaffolding alone never completes a design phase.

Status API and Go progress mapping

Go already has a ProgressService with bounded Mission/list/get/watch projections and explicit authority, observation and freshness distinctions. Jeroen’s Mission UI consumes a pinned display contract; its separate Java REST/SSE service is unfinished. Future orchestrator/UI readers should share the planned native status port (#5532, topology integration #5631). This PR preserves current native readers and adds no Java dependency or competing status reducer. Display artifact presence and provisional English nextAction must not become orchestrator completion authority. Go projection-revision cursors and UI JSONL offset/hash cursors require explicit versioned translation. See the application seam ADR.