Contracts
event-schema.json
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "StatusEvent", "description": "Canonical status transition event for spec-kitty work packages", "type": "object", "required": [ "event_id", "feature_slug", "wp_id", "from_lane", "to_lane", "at", "actor", "force", "execution_mode" ], "properties": { "event_id": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "description": "ULID: globally unique, lexicographically sortable" }, "feature_slug": { "type": "string", "pattern": "^\\d{3}-[a-z0-9-]+$", "description": "Feature identifier (e.g., 034-feature-name)" }, "wp_id": { "type": "string", "pattern": "^WP\\d{2}$", "description": "Work package identifier (e.g., WP01)" }, "from_lane": { "$ref": "#/$defs/Lane" }, "to_lane": { "$ref": "#/$defs/Lane" }, "at": { "type": "string", "format": "date-time", "description": "UTC ISO 8601 timestamp" }, "actor": { "type": "string", "minLength": 1, "description": "Who initiated the transition" }, "force": { "type": "boolean", "description": "Whether transition was forced (bypassing guards)" }, "reason": { "type": ["string", "null"], "description": "Required when force=true" }, "execution_mode": { "type": "string", "enum": ["worktree", "direct_repo"] }, "review_ref": { "type": ["string", "null"], "description": "Required for for_review → in_progress transitions" }, "evidence": { "oneOf": [ { "$ref": "#/$defs/DoneEvidence" }, { "type": "null" } ], "description": "Required when to_lane=done (unless forced)" } }, "allOf": [ { "if": { "properties": { "force": { "const": true } } }, "then": { "required": ["reason"], "properties": { "reason": { "type": "string", "minLength": 1 } } } }, { "if": { "properties": { "from_lane": { "const": "for_review" }, "to_lane": { "const": "in_progress" } } }, "then": { "required": ["review_ref"], "properties": { "review_ref": { "type": "string", "minLength": 1 } } } } ], "$defs": { "Lane": { "type": "string", "enum": [ "planned", "claimed", "in_progress", "for_review", "done", "blocked", "canceled" ] }, "DoneEvidence": { "type": "object", "required": ["review"], "properties": { "repos": { "type": "array", "items": { "type": "object", "required": ["repo", "branch", "commit"], "properties": { "repo": { "type": "string" }, "branch": { "type": "string" }, "commit": { "type": "string", "pattern": "^[0-9a-f]{7,40}$" }, "files_touched": { "type": "array", "items": { "type": "string" } } } } }, "verification": { "type": "array", "items": { "type": "object", "required": ["command", "result", "summary"], "properties": { "command": { "type": "string" }, "result": { "type": "string", "enum": ["pass", "fail", "skip"] }, "summary": { "type": "string" } } } }, "review": { "type": "object", "required": ["reviewer", "verdict", "reference"], "properties": { "reviewer": { "type": "string" }, "verdict": { "type": "string", "enum": ["approved", "changes_requested"] }, "reference": { "type": "string" } } } } } } }
snapshot-schema.json
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "StatusSnapshot", "description": "Materialized current state of all WPs in a feature (status.json)", "type": "object", "required": [ "feature_slug", "materialized_at", "event_count", "last_event_id", "work_packages", "summary" ], "properties": { "feature_slug": { "type": "string", "pattern": "^\\d{3}-[a-z0-9-]+$" }, "materialized_at": { "type": "string", "format": "date-time" }, "event_count": { "type": "integer", "minimum": 0 }, "last_event_id": { "type": ["string", "null"], "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "work_packages": { "type": "object", "patternProperties": { "^WP\\d{2}$": { "$ref": "#/$defs/WPState" } }, "additionalProperties": false }, "summary": { "$ref": "#/$defs/LaneSummary" } }, "$defs": { "WPState": { "type": "object", "required": ["lane", "actor", "last_transition_at", "last_event_id", "force_count"], "properties": { "lane": { "type": "string", "enum": ["planned", "claimed", "in_progress", "for_review", "done", "blocked", "canceled"] }, "actor": { "type": ["string", "null"] }, "last_transition_at": { "type": "string", "format": "date-time" }, "last_event_id": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "force_count": { "type": "integer", "minimum": 0 } } }, "LaneSummary": { "type": "object", "required": ["planned", "claimed", "in_progress", "for_review", "done", "blocked", "canceled"], "properties": { "planned": { "type": "integer", "minimum": 0 }, "claimed": { "type": "integer", "minimum": 0 }, "in_progress": { "type": "integer", "minimum": 0 }, "for_review": { "type": "integer", "minimum": 0 }, "done": { "type": "integer", "minimum": 0 }, "blocked": { "type": "integer", "minimum": 0 }, "canceled": { "type": "integer", "minimum": 0 } } } } }
transition-matrix.json
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "TransitionMatrix", "description": "Legal lane transitions and guard conditions for the 7-lane state machine", "canonical_lanes": [ "planned", "claimed", "in_progress", "for_review", "done", "blocked", "canceled" ], "aliases": { "doing": "in_progress" }, "terminal_lanes": ["done", "canceled"], "transitions": [ { "from": "planned", "to": "claimed", "guard": "actor_set_no_conflicting_claim", "description": "Claim a planned WP for work" }, { "from": "claimed", "to": "in_progress", "guard": "workspace_context_established", "description": "Begin active implementation" }, { "from": "in_progress", "to": "for_review", "guard": "subtasks_complete_or_force", "description": "Submit for review" }, { "from": "for_review", "to": "done", "guard": "reviewer_approval_evidence", "description": "Accept reviewed work" }, { "from": "for_review", "to": "in_progress", "guard": "review_ref_required", "description": "Changes requested by reviewer" }, { "from": "in_progress", "to": "planned", "guard": "reason_required", "description": "Abandon or reassign work" }, { "from": "planned", "to": "blocked", "guard": "none", "description": "Block planned work" }, { "from": "claimed", "to": "blocked", "guard": "none", "description": "Block claimed work" }, { "from": "in_progress", "to": "blocked", "guard": "none", "description": "Block in-progress work" }, { "from": "for_review", "to": "blocked", "guard": "none", "description": "Block work under review" }, { "from": "blocked", "to": "in_progress", "guard": "none", "description": "Unblock and resume work" }, { "from": "planned", "to": "canceled", "guard": "none", "description": "Cancel planned work" }, { "from": "claimed", "to": "canceled", "guard": "none", "description": "Cancel claimed work" }, { "from": "in_progress", "to": "canceled", "guard": "none", "description": "Cancel in-progress work" }, { "from": "for_review", "to": "canceled", "guard": "none", "description": "Cancel work under review" }, { "from": "blocked", "to": "canceled", "guard": "none", "description": "Cancel blocked work" } ], "force_rules": { "description": "Any transition can be forced with force=true + actor + reason", "done_exit_requires_force": true, "audit_fields_required": ["actor", "reason"] }, "conflict_resolution": { "strategy": "rollback_aware", "description": "Reviewer rollback (for_review → in_progress with review_ref) beats concurrent forward progression", "fallback": "timestamp_ordering" } }