Contracts

merge-ship-preflight.yaml

contract: merge-ship-preflight version: 1 mission: release-320-workflow-reliability-01KQKV85 branch_preflight: required_inputs:

blocking_conditions:

remediation: required: true statement: Provide a deterministic focused PR branch synthesis path based on mission-owned files or commits. review_artifact_consistency: required_inputs:

blocking_conditions:

allowed_outcomes:

test_fixtures:

diagnostics: required_fields:

  • local_target_branch
  • remote_tracking_branch
  • merge_target_branch
  • mission_owned_refs_or_files
  • local_target_branch_diverged_from_remote_tracking_branch
  • work_package_id
  • canonical_lane
  • latest_review_cycle_path
  • latest_review_cycle_verdict
  • canonical_lane_in_approved_or_done_and_latest_verdict_rejected
  • fail_before_signoff
  • warn_hard_before_signoff_with_required_resolution
  • local_main_diverged_from_origin_main
  • approved_wp_latest_review_rejected
  • done_wp_latest_review_rejected
  • diagnostic_code
  • branch_or_work_package
  • violated_invariant
  • remediation

review-prompt-metadata.yaml

contract: review-prompt-metadata version: 1 mission: release-320-workflow-reliability-01KQKV85 prompt_identity: required_fields:

path_requirements: uniqueness_components:

validation:

statement: Dispatcher compares requested repo_root, mission, work_package_id, and worktree with prompt metadata before review launch.

statement: Any metadata mismatch fails closed and prevents reviewer dispatch.

statement: Diff commands use base_ref, mission_branch, and lane_branch from canonical state, not slug reconstruction. test_fixtures:

failure_diagnostics: required_fields:

  • invocation_id
  • repo_root
  • mission_id
  • mission_slug
  • work_package_id
  • lane_worktree
  • mission_branch
  • lane_branch
  • base_ref
  • prompt_path
  • created_at
  • repo_root_hash_or_safe_identifier
  • mission_id_or_slug
  • work_package_id
  • invocation_id
  • id: RPM-001
  • id: RPM-002
  • id: RPM-003
  • concurrent_prompts_two_repos
  • concurrent_prompts_two_missions
  • mission_slug_prefixed_with_mission
  • diagnostic_code
  • requested_context
  • prompt_context
  • prompt_path

status-transition-atomicity.yaml

contract: status-transition-atomicity version: 1 mission: release-320-workflow-reliability-01KQKV85 scope: commands:

invariants:

statement: A command that reports transition success must append the expected event to status.events.jsonl.

statement: The command must read back the appended event before reporting success.

statement: If event append or readback fails, the command exits non-zero with a diagnostic naming mission, work_package_id, requested lane, and event path when known.

statement: Interrupted, backgrounded, or slow implement/review paths must not leave a work package stranded in claimed without a recoverable transition or diagnostic. test_fixtures:

observable_outputs: success: requires:

failure: requires:

  • spec-kitty agent tasks move-task
  • spec-kitty agent action implement
  • spec-kitty agent action review
  • spec-kitty agent status emit
  • id: STA-001
  • id: STA-002
  • id: STA-003
  • id: STA-004
  • subagent_worktree_move_task_approval_event
  • interrupted_action_claimed_recovery
  • missing_event_readback_failure
  • event_id
  • work_package_id
  • to_lane
  • status_events_path
  • diagnostic_code
  • violated_invariant
  • remediation

sync-diagnostics-output.yaml

contract: sync-diagnostics-output version: 1 mission: release-320-workflow-reliability-01KQKV85 local_success_rule: statement: After a local state mutation is durable, non-fatal final-sync failure must not convert the local command result into a red command failure. stdout_rules: text_commands: statement: Human stdout may describe local success; non-fatal sync diagnostics render on stderr. json_commands: statement: stdout must remain valid JSON parseable by a standard JSON parser. allowed_diagnostic_locations:

diagnostic_shape: required_fields:

dedupe: scope: per_invocation key_fields:

test_fixtures:

environment_rule: local_machine: Commands that exercise SaaS, tracker, hosted auth, or sync behavior use SPEC_KITTY_ENABLE_SAAS_SYNC=1.

  • stderr
  • explicit_json_field
  • severity
  • diagnostic_code
  • message
  • fatal
  • sync_phase
  • diagnostic_code
  • sync_phase
  • normalized_message
  • final_sync_failure_after_local_success
  • strict_json_stdout_with_sync_warning
  • duplicate_sync_lock_shutdown_messages