work package state position in the canonical lifecycle FSM. Canonical lanes: planned, claimed, in_progress, for_review, done, blocked, canceled. Alias: doing -> in_progress.
Context
Orchestration
Status
canonical
Applicable to
1.x, 2.x
Mission-Runtime YAML
Definition
Configuration file (mission-runtime.yaml) that defines a mission type's step graph, action ordering, dependencies, and prompt-template bindings.
A markdown file that provides the prompt for a specific mission action. Located in the mission type's template directory and loaded at runtime based on mission type and agent configuration.
The process of finding and loading the correct command template for a given mission action, considering which mission type is active and which agent is running.
JSON-based interface that lets external orchestration tools interact with spec-kitty CLI operations programmatically, without going through the human-facing CLI.
A structured choice presented to the Human-in-Charge (HiC) or their delegated agent during the next-command loop. Each decision describes what needs to happen next and offers options to advance the mission. In event-backed runtimes, a pending Decision is tracked until answered, then closed.
Materialised as a DecisionInboxItem (pending → answered) in the TeamSpace.
Not to be confused with
SaaS Decision (an immutable recorded past collaboration choice); SaaS DecisionPoint (a first-class team-consultation entity that can be widened, deferred, or resolved independently of the loop). See the SaaS domain glossary at architecture/domain-glossary.md.
The type of choice being presented — for example, selecting which step to run next, resolving a conflict, or assigning a work package to an agent. In the spec-kitty next --json contract this is carried as the top-level kind field; DecisionInputRequested events are emitted only for decision_required choices and do not repeat that field.
The event emitted by the runtime when it opens a Decision and requires a response from the HiC or a delegated agent. Carries the question text, candidate options, step context, and a unique decision_id. Opening a Decision Input Request is what makes a Decision "pending".
Context
Orchestration
Status
canonical
Applicable to
2.x, 3.x
Event type
DecisionInputRequested (in spec-kitty-events)
SaaS effect
Creates a DecisionInboxItem row with state=pending.
The event emitted when the HiC or a delegated agent answers a pending Decision. Carries the chosen answer, the actor identity, and the originating decision_id. Answering closes the Decision; the loop continues.
Context
Orchestration
Status
canonical
Applicable to
2.x, 3.x
Event type
DecisionInputAnswered (in spec-kitty-events)
SaaS effect
Updates the matching DecisionInboxItem to state=answered.
The adapter that connects the CLI's decision loop to the mission execution engine. It translates internal runtime decisions into the format the HiC or agent sees while keeping mission identity separate from mission-run identity.
The process of figuring out where a mission currently stands by reading filesystem artifacts and event logs, so the system can determine what mission actions are available next.
Overloaded key with two distinct scopes. (1) At the mission level (branch-context JSON output): alias for target_branch — the branch the mission is rooted in; base_branch and target_branch carry the same value in branch-context output. (2) At the worktree/WP level (WP prompt frontmatter): the specific git branch from which the individual lane worktree was created; this may be a lane branch (e.g. kitty/mission-010-feature-lane-a) rather than the target branch itself. JSON key: base_branch.
The mission-create guard for PR-bound missions that requires an explicit operator or agent decision before planning artifacts are written on a primary branch. Interactive callers may confirm at the prompt; non-interactive callers record the already-made decision with --branch-strategy already-confirmed. When the recommended feature-branch path is chosen, pass --start-branch so the CLI switches before scaffold writes.
The git branch checked out in the main repository at the moment a workflow command is invoked. Read ephemerally from the working tree; never persisted in any mission artifact. Exposed as current_branch / CURRENT_BRANCH in branch-context JSON output. Since WP07 (FR-012), spec-kitty does not use current_branch to derive the mission target — it reads target_branch from meta.json instead, so the branch contract is stable regardless of which branch the operator is on.
A dedicated git branch for pr-bound mission planning and implementation work, typically named feat/<slug> for feature work or fix/<slug> for bug-fix work. It is distinct from the primary branch and is the recommended start point when a mission is expected to become a pull request.
A versioned doctrine declaration attaching a named gate handler to a status-transition edge ({on_transition, handler, handler_kind, schema_version, fail_open, provenance}), authored on the review MissionStepContract. A binding is a field/relationship, not a standalone artefact. Do NOT confuse with the five pre-existing *gate* senses (branch strategy gate / diff compliance gate / dependency gate / merge dependency gate / sonar quality gate) — those are unrelated one-off guards, not doctrine-resolved lane-edge checks.
A named, dispatchable check registered in GATE_REGISTRY; the Spec-Kitty pre-review engine is the first handler, keyed to the for_review edge. Registry membership is the callable source; activation decides whether it runs. Do NOT confuse with the five pre-existing *gate* senses (branch strategy gate / diff compliance gate / dependency gate / merge dependency gate / sonar quality gate) — those are unrelated one-off guards, not doctrine-resolved dispatch callables.
The branch where completed work-package code must ultimately land. Stored in every WP prompt's frontmatter (alongside planning_base_branch) to give implementing agents an explicit merge destination. In meta.json: legacy alias for target_branch, read as a fallback by resolve_planning_branch_from_meta() for pre-WP03 missions. In 3.x all three — target_branch, planning_base_branch, and merge_target_branch — carry the same value; the separation makes intent explicit in agent-facing prompts and prevents the "prep branch leak" (pre-WP07 pattern). JSON key: merge_target_branch.
The branch active in the repository root checkout when WP prompts were generated (at finalize-tasks time). Stored in every WP prompt's frontmatter and in lanes.json to root lane-worktree allocation correctly regardless of which branch the operator is on when running finalize-tasks. In 3.x equals target_branch. Introduced alongside merge_target_branch to close the "prep branch leak" bug (pre-WP07): when finalize-tasks ran from a temporary prep/... branch, that branch leaked into WP frontmatter and crashed lane allocation once the prep branch was deleted. JSON key: planning_base_branch.
The repository's default integration branch, normally resolved from origin/HEAD and commonly named main, master, or develop. The specify branch-context output exposes this value as primary_branch only for branch-strategy recommendation; it is not automatically the mission's target_branch once target_branch has been persisted in meta.json. This is primarySense B — the canonical term is "primary branch" (kept per operator decision D1); the wire keys primary_branch / current_is_primary are unchanged.
A mission expected to land through a pull request rather than direct work on the primary branch. During mission create, --pr-bound activates the branch strategy gate so the branch choice is explicit before planning artifacts are written.
The branch passed to mission create with --start-branch. The CLI creates or switches to this branch before writing mission scaffolding, and it must match --target-branch when both options are supplied so mission metadata and the checked-out branch describe the same planning branch.
The git branch on which a mission's code, planning artifacts, and status events must ultimately land. Persisted in meta.json under the key target_branch at mission create time and never overwritten. Read by resolve_planning_branch_from_meta() as the canonical key; merge_target_branch is its legacy alias in older meta.json fixtures. Since WP07 (FR-012), all downstream commands — finalize-tasks, implement, review, merge — derive the branch contract from this stored value, not from current_branch at invocation time. In branch-context JSON output, target_branch and base_branch carry the same value at the mission level.
A check that must pass before a work-package status-transition edge (e.g. in_progress->for_review) is allowed. Resolved from the repo's active doctrine and dispatched through the inverted move-task hook (_mt_run_transition_gates); the flagship handler is the scoped pre-review regression check. Do NOT confuse with the five pre-existing *gate* senses (branch strategy gate / diff compliance gate / dependency gate / merge dependency gate / sonar quality gate) — those are unrelated one-off guards, not doctrine-resolved lane-edge checks.
The artifact-kind partition that holds stable planning artifacts — spec, plan, work-package outlines, and meta.json — as distinct from the COORD partition that holds the lifecycle artifacts (status events, notes, trace, issue-matrix, acceptance-matrix, review cycles, move-task). A partition is an artifact-kind routing concept: it decides which topology surface an artifact kind is written to. It is not a git branch. Missions with no coordination topology (SINGLE_BRANCH / LANES) route every artifact kind to PRIMARY. This is primarySense A.
Context
Orchestration
Status
canonical
Applicable to
3.x
Do NOT use when
The concept is the repository's default integration branch — use primary branch. The concept is the repository-root working copy versus a lane worktree — use repository root checkout. The concept is the ref that planning artifacts commit to — use Target Ref / Commit Target. The concept is the physical tree the routed artifact lands in — use Topology Surface. Never write bare "primary" for the partition; always say "PRIMARY partition".
The git ref that a mission's planning artifacts and status events are committed against — the "commit target" the resolver writes to. In current code this resolves to the mission's target_branch. It is distinct from the artifact-kind partition (which decides which surface an artifact is written to) and from the repository's default integration branch. This is primarySense D; the retired alias phrases "primary target" and "primary ref" describe this sense.
Context
Orchestration
Status
canonical
Applicable to
3.x
Do NOT use when
The concept is the artifact-kind partition — use PRIMARY partition. The concept is the repository's default integration branch — use primary branch. The concept is the branch the mission's code must ultimately land on — use target branch. Avoid the bare aliases "primary target" and "primary ref".
The spec-kitty merge operation: LOCAL consolidation of completed lane branches into the mission branch, with no push to any remote. Realized by the internal helper consolidate_lane_into_mission. This is mergeSense 1 — the first of three distinct "merge" operations. It stops at local main; it never publishes.
Context
Orchestration
Status
canonical
Applicable to
3.x
Canonical term (2026-07-30)
consolidate / consolidation is the canonical word for this sense (ADR 2026-07-30-1, #3080 foundation). The bare word "merge" for lane consolidation is now a legacy alias: existing occurrences are grandfathered (not rewritten by this ADR), but NEW code, new symbols, and touched prose must say "consolidate" / "consolidation" for this sense (boyscouting, C-012). Existing public symbols (spec-kitty merge, MergeState, baseline_merge_commit, consolidate_lane_into_mission's own name) are renamed only by the full #3080 rename, not by this entry.
Do NOT use when
The concept is the git merge that integrates the mission branch into its target branch — use Branch Integration / Git Merge. The concept is publishing merged work to origin/main — use Publish to origin/main. Never write bare "merge"; name the operation. In NEW code or prose, prefer "consolidate" / "consolidation" over "merge" for this sense — see Canonical term above; a CI drift-ratchet guard (tests/architectural/test_no_legacy_terminology.py, _LANE_CONSOLIDATION_FORBIDDEN_PHRASES) blocks the specific legacy lane-plus-merge-verb phrasings from growing beyond their grandfathered baseline (FR-016).
The git merge operation that integrates the mission branch into its target branch. Realized by the internal helper integrate_mission_into_target. This is mergeSense 2 — branch-to-branch integration, distinct from local lane consolidation and from publishing to origin. The MergeStrategy literals (merge / squash / rebase) select how this integration is performed and are unchanged serialized contracts.
Context
Orchestration
Status
canonical
Applicable to
3.x
Do NOT use when
The concept is spec-kitty merge's local lane consolidation — use Lane Consolidation. The concept is publishing merged work to origin/main — use Publish to origin/main.
The operator-only act of publishing merged mission work to origin/main, always through a pull request — never a direct push. Represented in the merge flow by push_requested. spec-kitty merge deliberately does not perform this step; it stops at LOCAL consolidation. This is mergeSense 3 — the publish operation, sometimes called "operator merge".
The artifact-kind partition that holds a mission's lifecycle/coordination artifacts — status events, notes, trace, issue-matrix, acceptance-matrix, review cycles, move-task — as distinct from the PRIMARY partition that holds stable planning artifacts. Like PRIMARY it is an artifact-kind routing concept, not a git branch and not a directory: it decides which surface a kind is written to. Only missions whose stored topology routes through coordination (COORD / LANES_WITH_COORD) have a materialised COORD surface; SINGLE_BRANCH / LANES missions route every kind to PRIMARY. Realized in code as the _PLACEMENT_ARTIFACT_KINDS frozenset in mission_runtime/artifacts.py, whose partition-invariant P-1 (disjoint and jointly exhaustive with _PRIMARY_ARTIFACT_KINDS) is asserted at the placement seam.
Context
Orchestration
Status
canonical
Applicable to
3.x
Do NOT use when
The concept is the physical tree an artifact resolves to — use Topology Surface. The concept is a coordination branch or worktree — say "coord branch" / "coord worktree" explicitly. Never write bare "coord" for the partition; always say "COORD partition".
The physical tree (working copy / checkout location) that a mission artifact resolves to for reading and writing. This is surfaceSense 2 — the mission-topology sense. Modelled by the TopologySurface enum in src/mission_runtime/artifacts.py, carried on MissionArtifactHome as read_surface / write_surface, and returned by artifact_home_for. Live members today: PRIMARY — the repository-root planning tree; COORD — the mission's coordination tree. Planned members, landing together with the surface→filesystem translation seam that makes each resolvable: LANE — a per-work-package lane worktree under .worktrees/; CONSOLIDATED — the tree after lane branches have been consolidated into the mission branch; TEMP — an ephemeral scratch tree with no durable home. The three planned members are deliberately not declared ahead of that seam: a member no caller can translate to a location is a phantom, and the seam's totality test exists precisely to catch that. Renamed from Surface (whose members were PRIMARY | PLACEMENT, with a str mixin and an ArtifactSurface back-compat alias, both retired) per ADR 2026-07-23-1.
Context
Orchestration
Status
canonical
Applicable to
3.x
Note
A topology surface is a location; a partition is a routing rule over artifact kinds. The two vocabularies coincide only on the PRIMARY and COORD values — the PRIMARY partition routes its kinds to the PRIMARY topology surface and the COORD partition to the COORD topology surface. LANE, CONSOLIDATED, and TEMP are locations with no partition of their own. Prose also uses "surface" as an ungoverned generic modifier ("command surface", "API surface", "doc surface") meaning "the outward face of X"; that usage is not governed here, but it must always carry its modifier — bare "surface" always means one of the two governed senses.
Note (naming vs conditioning)
Naming a surface COORD does not violate the rule against conditioning behaviour on topology. Naming a real surface is correct; branching on it — if surface is COORD: ... in place of a resolved read/write path — is what is forbidden. The prior member name PLACEMENT avoided the word while keeping the concept; explicitness is preferred.
Note (CONSOLIDATED, not MERGED)
The post-consolidation surface is named CONSOLIDATED because merge is itself a three-sense overloaded term in this codebase — Lane Consolidation, Branch Integration / Git Merge, and Publish to origin/main. A member named MERGED would not say which of the three had happened. CONSOLIDATED names exactly one: the surface that exists after Lane Consolidation. This is the same disambiguation discipline already applied to primary / main / base.
Do NOT use when
The concept is a tool-visible artifact or configuration entry Spec Kitty installs for a concrete execution tool — use Tool Surface (surfaceSense 1). The concept is the artifact-kind routing rule rather than the location — use PRIMARY partition or COORD partition. The concept is the repository-root working copy versus a lane worktree as an operator-facing checkout — use repository root checkout. Never write bare "surface" in governed prose; name the sense ("topology surface" / "tool surface").
"Routing" has no single meaning in this codebase — it is an umbrella word covering at least six live governed decisions, one retired governed sense retained here as a named referent, plus several infrastructural ones that are explicitly out of scope here. This entry extends, not restates, PRIMARY partition / COORD partition / Topology Surface above, which already frame the placement sense; naming an exclusion is disambiguation, silence is not.
Context
Orchestration
Status
canonical
Applicable to
3.x
Governed senses
Placement routing — mapping a MissionArtifactKind + mission topology to a Topology Surface. Owning module: mission_runtime/resolution.py (PlacementSeam, placement_seam). Full explanation: The Artifact Placement Seam. Do NOT use when the question is which git branch a commit lands on — that is branch-target routing, below. — Branch-target routing — which git branch (lane / coordination / target) a category of change commits to. Owning doc: Branch-Target Routing. Do NOT use when the question is which physical tree an artifact kind resolves to — that is placement routing, above. — Commit routing — the git-commit mechanics inside coordination/commit_router.py::commit_for_mission: given an already-resolved placement, whether the coordination worktree must be materialised before staging and committing. Do NOT use when the question is which surface a kind resolves to (placement routing) or which branch a category lands on (branch-target routing) — commit routing consumes both answers, it does not compute either. — Dispatch/profile routing — matching an ad-hoc natural-language request to an agent profile + action. Owning module: specify_cli/invocation/router.py (ActionRouter). Do NOT use when the subject is mission artifact placement or git branches. — Model/task routing — assigning a model or delegation target to a unit of work; the highest-collision sense in agent-authored prose because "route this to the right agent" reads as dispatch/profile routing but is a distinct decision. Owning surface: src/doctrine/model_task_routing/. Do NOT use when the subject is profile selection for an ad-hoc request (dispatch/profile routing) or mission artifact placement. — Scope routing — resolving which configuration/auth/sync scope (repo-level vs global) an operation applies at. Owning module: specify_cli/auth/transport.py. Do NOT use when the subject is artifact placement, branches, or model/agent assignment.
Retired governed sense
Sync fan-out routing — per-checkout opt-in/opt-out for SaaS sync delivery. Was owned by specify_cli/sync/routing.py (resolve_checkout_sync_routing); the entire specify_cli/sync/ tree was deleted with the sync transport (issue #115) and this is no longer a live governed decision. Retained here as a named referent, not as a live sense, so historical prose ("sync routing decides only whether a checkout participates in sync fan-out, never where anything is stored") still resolves.
Explicitly out of scope (infrastructural senses, named not silenced)
Event routing — dispatching an emitted event to its handler(s) inside the event/runtime-bridge machinery. HTTP request routing — mapping an inbound request path to a handler in a web-serving layer. Significance routing bands — make_routing_bands in runtime/next/_internal_runtime/significance.py, which buckets a decision's scored significance into a band; a scoring concept, not a placement or dispatch decision. None of these three is governed by this entry; if a caller needs one disambiguated further, name it explicitly in prose rather than writing bare "routing".
Do NOT use when
Never write bare "routing" in governed prose without naming which of the senses above (or an explicitly out-of-scope one) is meant.
"The drain" is retired historical terminology on this line. It previously named three distinct flows — the dispatch-selection drain (delivery/selection.py), the body drain (sync/background.py), and the queue-backed event drain (sync/batch.py, removed upstream by #3167) — all of which were deleted with the sync / delivery / event_journal subsystems (spec-kitty#5 / PR #114). The entry is retained as a named referent so historical prose, commit messages and issue threads that say "the drain" stay resolvable. Bare use is not resolvable from context; in new prose, name the concrete current operation instead.
| Context | Orchestration |
| Status | canonical |
| Applicable to | 3.x |
| Governed senses | All three senses are historical on this line: the dispatch-selection drain (formerly specify_cli/delivery/selection.py, feeding delivery/dispatcher.py), the body drain (formerly specify_cli/sync/background.py backed by sync/body_queue.py), and the queue-backed event drain (formerly specify_cli/sync/batch.py, removed upstream by #3167 before the subsystem deletion). None has a successor mechanism: mission status is ephemeral via Zeitgeist, and dossier artifacts render server-side from git. A reader resolving a historical "the drain" mention consults this entry, not current code. |
| Note (why this entry exists) | The overload was load-bearing, not cosmetic. #3167's own first-draft specification asserted that a true docstring was false — it read sync/runtime.py's claim that "the drain" walks the per-project consent chain as referring to sync/batch.py (which walked a different chain) instead of to delivery/selection.py (which does walk it). The proposed correction would have rewritten correct documentation and, in the natural rewrite, claimed consent coverage for a module that had no production caller — manufacturing exactly the false-pointer class that mission existed to remove. A false pointer is how an auditor concludes a gate exists. |
| Do NOT use when | Never write bare "the drain" in governed prose or in src/ docstrings. Write "the dispatch-selection drain", "the body drain", or "the retired queue-backed drain" — or link this entry. Also do not use "the drain" for the Lane Consolidation or status-event flush paths; those are not drains and have their own terms. |
| Related terms | Routing (the retired sync fan-out sense decided whether a checkout participates, never what "the drain" means), Lane Consolidation, Mission |