Spec Kitty

Contracts

next-query-response.schema.json

{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://spec-kitty.dev/contracts/078/next-query-response.schema.json", "title": "SpecKittyNextQueryResponse", "type": "object", "required": [ "kind", "agent", "mission_slug", "mission", "mission_state", "timestamp", "is_query" ], "properties": { "kind": { "const": "query" }, "agent": { "type": [ "string", "null" ] }, "mission_slug": { "type": "string", "minLength": 1 }, "mission": { "type": "string", "minLength": 1 }, "mission_state": { "type": "string", "minLength": 1, "description": "Fresh runs use 'not_started'. Started runs use the issued step id." }, "preview_step": { "type": [ "string", "null" ] }, "timestamp": { "type": "string", "format": "date-time" }, "action": { "type": [ "string", "null" ] }, "wp_id": { "type": [ "string", "null" ] }, "workspace_path": { "type": [ "string", "null" ] }, "prompt_file": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "guard_failures": { "type": "array", "items": { "type": "string" } }, "progress": { "type": [ "object", "null" ] }, "origin": { "type": "object" }, "run_id": { "type": [ "string", "null" ] }, "step_id": { "type": [ "string", "null" ] }, "decision_id": { "type": [ "string", "null" ] }, "input_key": { "type": [ "string", "null" ] }, "question": { "type": [ "string", "null" ] }, "options": { "type": [ "array", "null" ], "items": { "type": "string" } }, "is_query": { "const": true } }, "allOf": [ { "if": { "properties": { "mission_state": { "const": "not_started" } }, "required": [ "mission_state" ] }, "then": { "required": [ "preview_step" ], "properties": { "preview_step": { "type": "string", "minLength": 1 } } } } ], "additionalProperties": false }

planning-artifact-lifecycle.md

Contract: Planning-Artifact Lifecycle

Mission: 078-planning-artifact-and-query-consistency

Purpose

Define what lifecycle status lanes mean for planning-artifact work packages that execute in repository root instead of a lane worktree.

Status Meanings

Lane	Meaning for planning-artifact WPs
planned	The planning artifact work has not started
in_progress	The agent is actively editing repository-root planning artifacts
for_review	The repository-root artifacts are ready for review
approved	Review passed and downstream dependents may start
done	The artifacts have been accepted as complete

Required Rules

1. Planning-artifact WPs use the same lifecycle status lanes as other valid WPs. 2. approved remains meaningful; it is not skipped or renamed. 3. done must not depend on lane merge or worktree merge. 4. Review success must not require synthetic branch state for planning-artifact WPs. 5. Human-readable status output must not imply that planning-artifact completion is blocked on lane merge. 6. spec-kitty agent tasks move-task <wp-id> --to done must bypass merge-ancestry enforcement for planning-artifact WPs while leaving the ancestry guard intact for code_change WPs.

Explicit Non-Rules

• Planning-artifact WPs do not need execution-lane membership to reach for_review, approved, or done.
• Planning-artifact WPs do not need a workspace context file to participate in lifecycle transitions.

References

• ../spec.md
• ../data-model.md

stale-status.schema.json

{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://spec-kitty.dev/contracts/078/stale-status.schema.json", "title": "SpecKittyStaleStatus", "type": "object", "required": [ "status", "reason", "minutes_since_commit", "last_commit_time" ], "properties": { "status": { "type": "string", "enum": [ "fresh", "stale", "not_applicable" ] }, "reason": { "type": [ "string", "null" ] }, "minutes_since_commit": { "type": [ "number", "null" ] }, "last_commit_time": { "type": [ "string", "null" ], "format": "date-time" } }, "allOf": [ { "if": { "properties": { "status": { "const": "not_applicable" } }, "required": [ "status" ] }, "then": { "properties": { "reason": { "const": "planning_artifact_repo_root_shared_workspace" }, "minutes_since_commit": { "const": null }, "last_commit_time": { "const": null } } } } ], "additionalProperties": false }

workspace-resolution.md

Contract: Workspace Resolution

Mission: 078-planning-artifact-and-query-consistency

Purpose

Define the single runtime contract for determining where a work package runs.

This contract replaces the current split between:

• lane-only runtime lookup in src/specify_cli/workspace_context.py
• existing but unwired execution-mode-aware routing in src/specify_cli/core/worktree.py

Resolution Flow

1. Load and normalize WP metadata once per mission per command/session. 2. Ensure every target WP has a non-null execution_mode before any caller asks for a workspace. 3. Route by execution_mode, not by lane membership alone. 4. Return one ResolvedWorkspace object that all callers consume.

Resolution Matrix

execution_mode	lane membership required	workspace path	branch name	lane id	context file
code_change	yes	.worktrees/<mission>-<lane>	required	required	allowed
planning_artifact	no	<repo_root>	null	null	none

Compatibility Classification

When execution_mode is missing for a supported historical mission:

1. Infer it once from existing WP content. 2. Record mode_source = "inferred_legacy" for diagnostics. 3. Reuse the inferred value for the rest of the command/session.

If classification is impossible, fail once with an actionable compatibility error before any downstream command path runs.

Caller Obligations

The following callers must treat this resolver as authoritative and must not re-discover workspace rules themselves:

• src/specify_cli/cli/commands/implement.py
• src/specify_cli/cli/commands/agent/workflow.py
• src/specify_cli/cli/commands/agent/tasks.py
• src/specify_cli/core/execution_context.py
• src/specify_cli/core/stale_detection.py
• src/specify_cli/core/worktree_topology.py
• src/specify_cli/next/prompt_builder.py

Topology Obligation

Informational topology rendering must respect the canonical resolver too.

• A planning-artifact WP must not cause topology materialization to fail solely because it is outside lanes.json.
• Topology may represent planning-artifact entries as repo-root entries with nullable lane/branch fields.
• Topology must not silently drop all mixed-mission data because one planning-artifact WP lacks lane membership.

Non-Goals

• No synthetic lanes for planning-artifact WPs
• No planning-artifact workspace context files
• No mandatory rewrite of historical WP frontmatter on disk

References

• ../spec.md
• ../plan.md
• ../data-model.md