Contracts
mission-run-cli.md
Contract: spec-kitty mission run CLI
Command shape
spec-kitty mission run <mission-key> --mission <mission-slug> [--json]| Argument / option | Type | Required | Notes |
|---|---|---|---|
<mission-key> | positional, str | yes | The reusable identifier for a custom mission definition. Resolved through internal-runtime discovery precedence. |
--mission <mission-slug> | option, str | yes | The identifier of the tracked mission run under kitty-specs/<mission-slug>/. The resolver disambiguates by mission_id and returns a structured MISSION_AMBIGUOUS_SELECTOR error on ambiguity. |
--json / --no-json | option, bool | no, default false | Emit machine-readable envelope on stdout. Without --json, a rich.panel.Panel is rendered. |
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success — runtime started or already running for the requested mission. |
| 1 | Infrastructure failure — filesystem error, repository corruption, etc. Not the operator's fault. |
| 2 | Validation error — the custom mission definition or selector is unfit. Operator-fixable. |
Stdout envelopes
Success envelope (--json)
{
"result": "success",
"mission_key": "erp-integration",
"mission_slug": "erp-q3-rollout-01KQ…",
"mission_id": "01KQ…",
"feature_dir": "/abs/path/kitty-specs/erp-q3-rollout-01KQ…",
"run_dir": "/abs/path/.kittify/runtime/runs/<run-id>",
"warnings": []
}warnings is a list of {code, message, details} objects. Possible warning codes are documented in validation-errors.md.
Error envelope (--json)
{
"result": "error",
"error_code": "MISSION_RETROSPECTIVE_MISSING",
"message": "Custom mission 'erp-integration' has no retrospective marker step.",
"details": {
"file": "/abs/path/.kittify/missions/erp-integration/mission.yaml",
"mission_key": "erp-integration",
"expected": "steps[-1].id == 'retrospective'",
"actual": "write-report"
},
"warnings": []
}Human envelope (no --json)
A rich.panel.Panel is rendered with the same fields. The panel's title is the error code (or "Mission Run Started" on success). The body is the message followed by indented details (in success: feature_dir, run_dir).
Discoverability
spec-kitty mission --help lists run alongside the existing subcommands (list, current, info, create). spec-kitty mission run --help shows the args + options table above plus a one-paragraph description: Start (or attach to) a runtime for a project-authored custom mission definition.
Error code stability
The full closed enum is documented in validation-errors.md. New codes MAY be added in future tranches; existing codes MUST NOT change wire spelling.
Locked invariants
- The CLI never invokes a model (charter / C-006). It only routes; the runtime composition path drives the host harness.
- Validation errors do NOT start a run. The
kitty-specs/<slug>/directory is not created on validation failure. - Success envelope's
feature_diris the absolute path; downstream tooling cancdto it without recomputation.
validation-errors.md
Contract: Loader Validation Errors and Warnings
This is the closed enumeration of error and warning codes emitted by mission_loader. Wire spellings are stable: removal or rename is a breaking change requiring a deprecation cycle. Additions are non-breaking.
Errors (exit code 2)
| Code | When | Required details keys |
|---|---|---|
MISSION_YAML_MALFORMED | Discovery scanned a file but failed to parse it as YAML, OR MissionTemplate.model_validate raised ValidationError. | file, parse_error |
MISSION_REQUIRED_FIELD_MISSING | Top-level mission.key, mission.name, mission.version, or steps[] missing. (A specific subset of MISSION_YAML_MALFORMED surfaced separately for operator clarity.) | file, mission_key (best-effort), field |
MISSION_KEY_UNKNOWN | The user invoked spec-kitty mission run <key> but no discovery tier produced a definition with that key. | mission_key, tiers_searched (list[str]) |
MISSION_KEY_AMBIGUOUS | Two or more tiers produced the same key AND the resolver could not pick a single selected entry (extreme edge case; default precedence picks one). Reserved for future use. | mission_key, paths (list[str]) |
MISSION_KEY_RESERVED | A non-builtin tier produced a definition whose mission.key is in RESERVED_BUILTIN_KEYS. | mission_key, file, tier, reserved_keys |
MISSION_RETROSPECTIVE_MISSING | Validator R-001: the last step's id is not "retrospective". | file, mission_key, actual_last_step_id, expected: "retrospective" |
MISSION_STEP_NO_PROFILE_BINDING | Validator FR-008: a step with empty requires_inputs declares neither agent_profile nor contract_ref. | file, mission_key, step_id |
MISSION_STEP_AMBIGUOUS_BINDING | Validator: a step declares both agent_profile AND contract_ref. | file, mission_key, step_id |
MISSION_CONTRACT_REF_UNRESOLVED | A step's contract_ref does not resolve in the on-disk MissionStepContractRepository. | file, mission_key, step_id, contract_ref |
Warnings (exit code unaffected; included in envelope)
| Code | When | Required details keys |
|---|---|---|
MISSION_KEY_SHADOWED | A definition was discovered in multiple tiers; the higher-precedence tier wins. Emitted for non-built-in keys (built-in shadow is an error per MISSION_KEY_RESERVED). | mission_key, selected_path, selected_tier, shadowed_paths |
MISSION_PACK_LOAD_FAILED | A mission-pack manifest pointed at a mission.yaml that failed to load. | pack_root, failed_path, parse_error |
Detail key conventions
- All paths are absolute strings.
mission_keyis the value oftemplate.mission.keyonce known;nullwhen unknown.tier∈{"explicit", "env", "project_override", "project_legacy", "user_global", "project_config", "builtin"}.step_idis thePromptStep.idvalue.
Stability guarantees
1. The result field of the JSON envelope is exactly "success" or "error". No third value. 2. error_code ∈ the codes above. Tooling MAY rely on string equality. 3. details is always an object. It MAY have additional keys beyond those required (forward-compatible). Tooling MUST NOT fail on unknown keys. 4. Warnings flow on success and on error envelopes. Tooling MUST surface them.