---
type: "Context"
title: "Context: Orchestration"
description: "Glossary context for orchestration: lifecycle and runtime orchestration semantics, including the repository, project, and mission-run terms."
status: "stable"
generated:
  by: "process:dockitty-export"
  at: "2026-11-13T00:00:00Z"
---

## Context: Orchestration

Terms describing lifecycle and runtime orchestration semantics.

Mission topology terms (the four topologies, write checkout, repo-root lane, code lane, protected target, mission branch, lane work tip, absorbed lane) are defined in [Context: Topology](/context/topology.md).

### Repository

| | |
|---|---|
| **Definition** | The local git repository that a [Project](#project) is initialized from and executes within. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `3.x` |
| **Note** | Use this term when the repository boundary itself matters, especially for repository-scoped identity. |
| **Related terms** | [Project](#project), [Build](#build) |

---

### Project

| | |
|---|---|
| **Definition** | Entire repository initialized for Spec Kitty workflow execution. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |

---

### Mission Type

| | |
|---|---|
| **Definition** | Reusable workflow blueprint that configures the mission's steps (actions), their templates, and guardrails. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |

---

### Build

| | |
|---|---|
| **Definition** | One checkout or worktree execution context inside a [Repository](#repository), identified by machine and build-scoped runtime identity. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `3.x` |
| **Note** | Use this term when distinguishing per-worktree or per-machine runtime context from the repository boundary itself. |
| **Related terms** | [Repository](#repository), [Mission Run](#mission-run) |

---

### Mission

| | |
|---|---|
| **Definition** | A unit of governed delivery: the concrete tracked item, stored under the Mission's own spec directory and linked to exactly one Mission Type, that carries one piece of work from agreed intent to a verified result. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x`, `3.x` |
| **Note** | This is the generic tracked-item noun across software, research, planning, and documentation work. |
| **Do NOT use when** | The concept is the reusable workflow blueprint the Mission is an instance of — use [Mission Type](#mission-type). The concept is one runtime execution of the Mission's step loop — use [Mission Run](#mission-run). Never use the retired alias "Feature" for the Mission domain object (Terminology Canon). |

---

### Mission Run

| | |
|---|---|
| **Definition** | One runtime execution of a Mission's step loop, keyed by `run_id`. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x`, `3.x` |
| **Scoping rule** | Runtime events should be scoped by the run's `run_id` where available |
| **Do NOT use when** | The concept is the tracked unit of work itself — use [Mission](#mission). Avoid "mission session". |

---

### Feature

| | |
|---|---|
| **Definition** | Retired alias for a [Mission](#mission) whose mission type is `software-dev`. |
| **Context** | Orchestration |
| **Status** | deprecated |
| **Applicable to** | `1.x`, `2.x` (historical) |
| **Note** | Prohibited for the Mission domain object in active surfaces (Terminology Canon). Use [Mission](#mission). Generic "feature" in the product-capability sense, and the Gherkin keyword, are unaffected. Legacy machine keys such as `feature_dir` are still emitted alongside the canonical `mission_dir` as legacy output aliases (#5206), not read-only survivors. |

---

### work package

| | |
|---|---|
| **Definition** | Executable slice of work inside a mission plan, typically represented as `WPxx` tasks. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |

---

### Mission Action

| | |
|---|---|
| **Definition** | Outer lifecycle action for a mission, such as `specify`, `plan`, `implement`, `review`, or `accept`. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |
| **Related terms** | [Mission Type](#mission-type), [step contract](#step-contract), [Procedure](/context/charter.md#procedure) |

---

### step contract

| | |
|---|---|
| **Definition** | Structured contract for one mission action, including step sequencing, guard evaluation, prompt binding, and delegation hooks. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |
| **Related terms** | [Mission Action](#mission-action), [Mission-Runtime YAML](#mission-runtime-yaml), [Procedure](/context/charter.md#procedure) |

---

### Workflow

| | |
|---|---|
| **Definition** | Umbrella prose term for the overall flow of work. |
| **Context** | Orchestration |
| **Status** | canonical (generic prose only) |
| **Applicable to** | `1.x`, `2.x` |
| **Rule** | Use [Mission Type](#mission-type), [Mission Action](#mission-action), [step contract](#step-contract), or [Procedure](/context/charter.md#procedure) when precision matters. |

---

### WorkPackage (Alias)

| | |
|---|---|
| **Definition** | Legacy lexical variant of [work package](#work-package). |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |
| **Canonical entry** | [work package](#work-package) |

---

### Lane

| | |
|---|---|
| **Definition** | Status lane: a work package's state position in the canonical lifecycle FSM. The nine canonical lanes are `planned`, `claimed`, `in_progress`, `for_review`, `in_review`, `approved`, `done`, `blocked`, `canceled`. The happy path is `planned` -> `claimed` -> `in_progress` -> `for_review` -> `in_review` -> `approved` -> `done`; `blocked` is reachable from every non-terminal lane and `canceled` from every lane. Alias: `doing` -> `in_progress`. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |
| **Other sense** | **Execution lane**: a group of work packages that `finalize-tasks` computes into `lanes.json`, which runs in one place. A code lane has its own lane branch and `.worktrees/` lane worktree; the `lane-planning` lane has no lane branch and resolves to the [write checkout](/context/topology.md#write-checkout), normally the repository root checkout. Defined in [Context: Topology](/context/topology.md#code-lane) ([code lane](/context/topology.md#code-lane), [repo-root lane](/context/topology.md#repo-root-lane)). |
| **Do NOT use when** | Never write bare "lane" when the sense matters: say "status lane" for the lifecycle position defined here, and "execution lane", "code lane", "lane branch" or "lane worktree" for where work runs. |

---

### Mission-Runtime YAML

| | |
|---|---|
| **Definition** | Configuration file (`mission-runtime.yaml`) that defines a mission type's step graph, action ordering, dependencies, and prompt-template bindings. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |
| **Related terms** | [Mission Type](#mission-type), [Step Dependency](#step-dependency), [step contract](#step-contract), [Command Template](#command-template) |

---

### Step Dependency

| | |
|---|---|
| **Definition** | A declared relationship saying "this step cannot start until that step finishes." Defined in mission-runtime YAML to enforce ordering. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |
| **Related terms** | [Mission-Runtime YAML](#mission-runtime-yaml), [Step Sequence](#step-sequence) |

---

### Step Sequence

| | |
|---|---|
| **Definition** | The order in which mission steps execute, determined by the step list and dependency graph in mission-runtime YAML. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |
| **Related terms** | [Step Dependency](#step-dependency), [Mission-Runtime YAML](#mission-runtime-yaml) |

---

### Command Template

| | |
|---|---|
| **Definition** | 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. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |
| **Related terms** | [Template Resolution](#template-resolution), [Mission-Runtime YAML](#mission-runtime-yaml) |

---

### Template Resolution

| | |
|---|---|
| **Definition** | 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. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |
| **Related terms** | [Command Template](#command-template) |

---

### Mission Discovery

| | |
|---|---|
| **Definition** | How the runtime finds and loads mission-type definition files (`mission.yaml`, `mission-runtime.yaml`) from configured mission-pack roots at startup. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |
| **Related terms** | [Mission Type](#mission-type), [Mission-Runtime YAML](#mission-runtime-yaml) |

---

### Command Envelope

| | |
|---|---|
| **Definition** | Standard JSON wrapper around the output of every `spec-kitty orchestrator-api` command: `contract_version`, `command`, `timestamp`, `correlation_id`, `success`, `error_code` and `data` (`make_envelope`, `src/specify_cli/orchestrator_api/envelope.py`). |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |
| **Related terms** | [Orchestrator API](#orchestrator-api), [Contract Version](#contract-version), [JSON](/context/technology-foundations.md#json) |

---

### Contract Version

| | |
|---|---|
| **Definition** | Version number on the orchestrator API that tells consumers whether the API has changed in a breaking way. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |
| **Related terms** | [Orchestrator API](#orchestrator-api), [Command Envelope](#command-envelope) |

---

### Orchestrator API

| | |
|---|---|
| **Definition** | JSON-based interface that lets external orchestration tools drive Spec Kitty operations programmatically: the `spec-kitty orchestrator-api` command group, whose commands answer in the [Command Envelope](#command-envelope) instead of human-facing output. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |
| **Related terms** | [Command Envelope](#command-envelope), [API](/context/technology-foundations.md#api) |

---

### Decision

| | |
|---|---|
| **Definition** | 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. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x`, `3.x` |
| **Lifecycle** | In event-backed runtimes, opened by [Decision Input Request](#decision-input-request); closed by [Decision Input Answer](#decision-input-answer). |
| **Former SaaS projection** | Before the hosted surfaces were removed from open-core (#6164), the hosted product materialised a Decision as a `DecisionInboxItem` (pending → answered) in the TeamSpace. Open-core no longer sends it there. |
| **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). |
| **Related terms** | [Decision Kind](#decision-kind), [Decision Input Request](#decision-input-request), [Decision Input Answer](#decision-input-answer), [Human-in-Charge (HiC)](/context/identity.md#human-in-charge-hic) |

---

### Decision Kind

| | |
|---|---|
| **Definition** | 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. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x`, `3.x` |
| **Related terms** | [Decision](#decision), [Decision Input Request](#decision-input-request) |

---

### Decision Input Request

| | |
|---|---|
| **Definition** | The event emitted by the runtime when it opens a [Decision](#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`) |
| **Former SaaS effect** | Before #6164, created a `DecisionInboxItem` row with `state=pending` in the hosted product. Open-core no longer sends it there. |
| **Related terms** | [Decision](#decision), [Decision Input Answer](#decision-input-answer), [Mission Run](#mission-run) |

---

### Decision Input Answer

| | |
|---|---|
| **Definition** | The event emitted when the HiC or a delegated agent answers a pending [Decision](#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`) |
| **Former SaaS effect** | Before #6164, updated the matching `DecisionInboxItem` to `state=answered` in the hosted product. Open-core no longer sends it there. |
| **Related terms** | [Decision](#decision), [Decision Input Request](#decision-input-request) |

---

### Runtime Bridge

| | |
|---|---|
| **Definition** | 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. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |
| **Related terms** | [Decision](#decision), [Human-in-Charge (HiC)](/context/identity.md#human-in-charge-hic) |

---

### Mission State Derivation

| | |
|---|---|
| **Definition** | 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. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |
| **Related terms** | [Mission Run](#mission-run), [Decision](#decision) |

---

### base branch

| | |
|---|---|
| **Definition** | 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-<slug>-lane-a`) rather than the target branch itself. JSON key: `base_branch`. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `3.x` |
| **Related terms** | [target branch](#target-branch), [Planning base branch](#planning-base-branch), [Lane](#lane) |

---

### branch strategy gate

| | |
|---|---|
| **Definition** | 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. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `3.x` |
| **Related terms** | [pr-bound mission](#pr-bound-mission), [primary branch](#primary-branch), [feature branch](#feature-branch), [start branch](#start-branch) |

---

### current branch

| | |
|---|---|
| **Definition** | The git branch checked out in the repository root checkout 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. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `3.x` |
| **Related terms** | [target branch](#target-branch), [base branch](#base-branch) |

---

### topic branch

| | |
|---|---|
| **Definition** | A short-lived branch carrying one change to a pull request. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `3.x`, `4.x` |
| **Do NOT use when** | The concept is the repository's default integration branch — use [primary branch](#primary-branch). The concept is the ref a mission's code must ultimately land on — use [target branch](#target-branch). Avoid the aliases "feature branch" and "PR branch". |
| **Related terms** | [feature branch](#feature-branch), [primary branch](#primary-branch), [target branch](#target-branch), [pr-bound mission](#pr-bound-mission) |

---

### feature branch

| | |
|---|---|
| **Definition** | Alias of topic branch: a short-lived branch carrying one change to a pull request. Prefer "topic branch" in canonical and operator-facing language. |
| **Context** | Orchestration |
| **Status** | deprecated |
| **Applicable to** | `3.x`, `4.x` |
| **Do NOT use when** | Prefer the canonical [topic branch](#topic-branch) in new code, prose and operator-facing text. The machine value `feature-branch` (for example the `recommended_strategy` branch-strategy value) is unchanged and is not this alias. |
| **Related terms** | [topic branch](#topic-branch), [pr-bound mission](#pr-bound-mission), [primary branch](#primary-branch), [start branch](#start-branch), [target branch](#target-branch) |

---

### gate binding

| | |
|---|---|
| **Definition** | 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 artifact. 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. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `3.x` |
| **Related terms** | [gate handler](#gate-handler), [transition gate](#transition-gate), [branch strategy gate](#branch-strategy-gate) |

---

### gate handler

| | |
|---|---|
| **Definition** | 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. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `3.x` |
| **Related terms** | [gate binding](#gate-binding), [transition gate](#transition-gate), [branch strategy gate](#branch-strategy-gate) |

---

### Merge target branch

| | |
|---|---|
| **Definition** | 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 landing 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 and 4.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). Here "merge" means landing the work on its target (the [Branch Integration](#branch-integration--git-merge) sense), not lane consolidation. JSON key: `merge_target_branch`. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `3.x` |
| **Related terms** | [target branch](#target-branch), [Planning base branch](#planning-base-branch), [work package](#work-package) |

---

### Planning base branch

| | |
|---|---|
| **Definition** | The branch a work package's planning is rooted on, written into every WP prompt's frontmatter by `finalize-tasks`. `finalize-tasks` sets it to the Mission's resolved planning branch, which is the `target_branch` read from `meta.json` (an owned checkout uses its write branch; the `--target-branch` override is how a legacy PR-bound Mission names its planning branch, #2938), never the branch the operator happens to be on (`src/specify_cli/cli/commands/agent/mission_finalize_bootstrap.py`, `mission_finalize_branch_contract.py`). The branch-context JSON reports the same value (`mission_branch_context.py`). `lanes.json` does not store it: it records `target_branch` and `mission_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-worktree allocation once the prep branch was deleted. JSON key: `planning_base_branch`. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `3.x` |
| **Related terms** | [target branch](#target-branch), [Merge target branch](#merge-target-branch), [Lane](#lane), [work package](#work-package) |

---

### primary branch

| | |
|---|---|
| **Definition** | 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 `primary` **Sense B** — the canonical term is "primary branch" (kept per operator decision D1); the wire keys `primary_branch` / `current_is_primary` are unchanged. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `3.x` |
| **Do NOT use when** | The concept is the artifact-kind partition — use [PRIMARY partition](#primary-partition). The concept is the repository-root working copy versus a lane worktree — use [repository root checkout](/context/execution.md#repository-root-checkout). The concept is the ref planning artifacts commit to — use [Target Ref / Commit Target](#target-ref--commit-target). |
| **Related terms** | [current branch](#current-branch), [target branch](#target-branch), [feature branch](#feature-branch), [branch strategy gate](#branch-strategy-gate), [PRIMARY partition](#primary-partition), [repository root checkout](/context/execution.md#repository-root-checkout), [Target Ref / Commit Target](#target-ref--commit-target) |

---

### pr-bound mission

| | |
|---|---|
| **Definition** | 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. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `3.x` |
| **Related terms** | [branch strategy gate](#branch-strategy-gate), [feature branch](#feature-branch), [primary branch](#primary-branch) |

---

### start branch

| | |
|---|---|
| **Definition** | 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. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `3.x` |
| **Related terms** | [feature branch](#feature-branch), [target branch](#target-branch), [branch strategy gate](#branch-strategy-gate) |

---

### target branch

| | |
|---|---|
| **Definition** | 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`, `consolidate` — 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. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `2.x`, `3.x` |
| **Related terms** | [base branch](#base-branch), [Planning base branch](#planning-base-branch), [Merge target branch](#merge-target-branch), [current branch](#current-branch), [Mission](#mission) |

---

### transition gate

| | |
|---|---|
| **Definition** | 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. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `3.x` |
| **Related terms** | [gate handler](#gate-handler), [gate binding](#gate-binding), [branch strategy gate](#branch-strategy-gate) |

---

### Tracker Connector

| | |
|---|---|
| **Definition** | Outbound integration boundary that projects host lifecycle state to external tracker systems without transferring lifecycle authority. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |
| **Related terms** | [target branch](#target-branch), [Orchestrator API](#orchestrator-api), [WPStatusChanged](/context/system-events.md#wpstatuschanged) |

---

### Tracker Connector Boundary (Alias)

| | |
|---|---|
| **Definition** | Architecture-facing alias for [Tracker Connector](#tracker-connector). |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |
| **Canonical entry** | [Tracker Connector](#tracker-connector) |

---

### PRIMARY partition

| | |
|---|---|
| **Definition** | The artifact-kind partition that holds stable planning artifacts — spec, plan, work-package outlines, and `meta.json` — as distinct from the [COORD partition](#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 *placement routing* concept: it decides which [topology surface](#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 `primary` **Sense 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](#primary-branch). The concept is the repository-root working copy versus a lane worktree — use [repository root checkout](/context/execution.md#repository-root-checkout). The concept is the ref that planning artifacts commit to — use [Target Ref / Commit Target](#target-ref--commit-target). The concept is the physical tree the routed artifact lands in — use [Topology Surface](#topology-surface). Never write bare "primary" for the partition; always say "PRIMARY partition". |
| **Related terms** | [primary branch](#primary-branch), [COORD partition](#coord-partition), [Topology Surface](#topology-surface), [repository root checkout](/context/execution.md#repository-root-checkout), [Target Ref / Commit Target](#target-ref--commit-target), [target branch](#target-branch) |

---

### Target Ref / Commit Target

| | |
|---|---|
| **Definition** | 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 `primary` **Sense 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](#primary-partition). The concept is the repository's default integration branch — use [primary branch](#primary-branch). The concept is the branch the mission's code must ultimately land on — use [target branch](#target-branch). Avoid the bare aliases "primary target" and "primary ref". |
| **Related terms** | [target branch](#target-branch), [Merge target branch](#merge-target-branch), [base branch](#base-branch), [current branch](#current-branch), [PRIMARY partition](#primary-partition) |

---

### Lane Consolidation

| | |
|---|---|
| **Definition** | The lane step of `spec-kitty consolidate` (the command was renamed from the former `merge` command by #3080): 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 `merge` **Sense 1** — the first of three distinct "merge" operations. The step stops at the local mission branch. The same command then performs [Branch Integration](#branch-integration--git-merge) locally (`integrate_mission_into_target`), and publishes only when the operator passes `--push` (see [Publish to origin/main](#publish-to-originmain)). |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `3.x` |
| **Canonical term (2026-07-30, renamed 2026-09 by #3080)** | `consolidate` / `consolidation` is the **canonical word** for this sense (ADR [2026-07-30-1](/adr/3.x/2026-07-30-1-consolidated-write-surface-and-consolidate-terminology.md)). The bare word "merge" for lane consolidation is now a **legacy alias**: pre-#3080 occurrences are grandfathered, but NEW code, new symbols, and touched prose must say "consolidate" / "consolidation" for this sense (boyscouting, C-012). The full #3080 rename has landed: the CLI command is `spec-kitty consolidate` (`merge` now exits with a migration-error stub), the state class is `ConsolidationState`, and the package is `specify_cli.consolidation`. `baseline_merge_commit` (the `meta.json` wire-key) and `consolidate_lane_into_mission`'s own name are unaffected — they were frozen KEEPs, not part of the rename. |
| **Do NOT use when** | The concept is the `git merge` that integrates the mission branch into its target branch — use [Branch Integration / Git Merge](#branch-integration--git-merge). The concept is publishing the landed work to `origin/main` — use [Publish to origin/main](#publish-to-originmain). 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). |
| **Related terms** | [Branch Integration / Git Merge](#branch-integration--git-merge), [Publish to origin/main](#publish-to-originmain), [Merge target branch](#merge-target-branch), [Lane](#lane), [Topology Surface](#topology-surface) |

---

### Branch Integration / Git Merge

| | |
|---|---|
| **Definition** | The `git merge` operation that integrates the mission branch into its target branch. Realized by the internal helper `integrate_mission_into_target`. This is `merge` **Sense 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 consolidate`'s local lane consolidation — use [Lane Consolidation](#lane-consolidation). The concept is publishing the landed work to `origin/main` — use [Publish to origin/main](#publish-to-originmain). |
| **Related terms** | [Lane Consolidation](#lane-consolidation), [Publish to origin/main](#publish-to-originmain), [target branch](#target-branch), [Merge target branch](#merge-target-branch) |

---

### Publish to origin/main

| | |
|---|---|
| **Definition** | The operator-only act of publishing the landed mission work to `origin/main`. In this repository it always goes through a pull request — never a direct push. Represented in the consolidation flow by `push_requested`. By default `spec-kitty consolidate` does **not** perform this step: it stops at the local landing. Its opt-in `--push` flag runs `git push origin <target branch>` after the local integration (`src/specify_cli/consolidation/phase_finalize.py`); this repository's workflow forbids using it for `main`. This is `merge` **Sense 3** — the publish operation, sometimes called "operator merge". |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `3.x` |
| **Do NOT use when** | The concept is `spec-kitty consolidate`'s local lane consolidation — use [Lane Consolidation](#lane-consolidation). The concept is the `git merge` branch-integration step — use [Branch Integration / Git Merge](#branch-integration--git-merge). |
| **Related terms** | [Lane Consolidation](#lane-consolidation), [Branch Integration / Git Merge](#branch-integration--git-merge), [primary branch](#primary-branch) |

---

### Branch-relative provenance

| | |
|---|---|
| **Definition** | The meaning of a commit SHA a Mission dossier records (`merged_commit`, `baseline_merge_commit`, `accept_commit`, `accepted_from_commit`, `lane_head`, `planning_commit_sha`, `base_commit`, and any SHA cited in hand-authored evidence such as `issue-matrix.json` `evidence_ref`): it names a commit on the branch the Mission was built on, as that branch stood when the value was written. After the pull request lands by rebase it may resolve only through the pull request's head ref, or not at all, and it is never repointed. The only exception is a field classified `LANDED` (today `pr_merge_commit`), whose writer verifies the commit is on the target branch. The classification lives in `DOSSIER_SHA_FIELDS` (`tests/architectural/test_dossier_sha_provenance.py`); ADR [2026-11-07-1](/adr/4.x/2026-11-07-1-dossier-commit-shas-are-branch-relative-provenance.md). |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `4.x` |
| **Do NOT use when** | The concept is the commit that landed a Mission on `main`: that is `pr_merge_commit` where it was recorded, or the pull request's landed commit. Do not call an unreachable branch-relative SHA "stale" or "corrupt", and never ask for an archive-freeze exception to correct one. |
| **Related terms** | [Publish to origin/main](#publish-to-originmain), [Lane Consolidation](#lane-consolidation), [Evidence gate](#evidence-gate) |

---

### Work-package window

| | |
|---|---|
| **Definition** | The span of lane history one approved work package is accountable for: from its [window-open SHA](#window-open-sha) (exclusive) to its newest approval stamp (inclusive). A work package with a [window gap](#window-gap) gets a degraded window from the claim base to its approval stamp. ADR [2026-11-08-2](/adr/4.x/2026-11-08-2-work-package-windows-are-recorded-at-the-opening-transition.md). |
| **Context** | Orchestration |
| **Status** | candidate |
| **Applicable to** | `4.x` |
| **Do NOT use when** | The concept is the canceled-content implementation and review windows of a mixed lane (`WorkWindow`): that is a [named window variant](#named-window-variant), never "work-package window". Do not write "work window" or "WP range" for this sense. |
| **Related terms** | [Window-open SHA](#window-open-sha), [Window opener](#window-opener), [Window gap](#window-gap), [Exemption anchor](#exemption-anchor), [Named window variant](#named-window-variant) |

---

### Window-open SHA

| | |
|---|---|
| **Definition** | The lane head recorded under `policy_metadata.wp_window.open_sha` on the status event of a non-migration move into `claimed` or `in_progress`. The window opens at the one recorded on the [window opener](#window-opener). It is [branch-relative provenance](#branch-relative-provenance), valid for one consolidation attempt. ADR [2026-11-08-2](/adr/4.x/2026-11-08-2-work-package-windows-are-recorded-at-the-opening-transition.md). |
| **Context** | Orchestration |
| **Status** | candidate |
| **Applicable to** | `4.x` |
| **Do NOT use when** | The concept is the approval stamp (`lane_head` on the newest approval transition): that is the window's closing edge. Do not write "open stamp", "base SHA" or "fork point" for this sense. |
| **Related terms** | [Work-package window](#work-package-window), [Window opener](#window-opener), [Window gap](#window-gap), [Branch-relative provenance](#branch-relative-provenance) |

---

### Window opener

| | |
|---|---|
| **Definition** | The opening event a work package's window binds to: the first non-migration move into `claimed` or `in_progress` after the work package last returned to `planned` from a non-review status lane (a review rejection does not reset it), skipping leading `lane_branch_missing` openers, with the openers of that cycle ordered by lane topology and by event-log order when their SHAs are unrelated (FR-021). ADR [2026-11-08-2](/adr/4.x/2026-11-08-2-work-package-windows-are-recorded-at-the-opening-transition.md). |
| **Context** | Orchestration |
| **Status** | candidate |
| **Applicable to** | `4.x` |
| **Do NOT use when** | The concept is the closed-world lane anchor, where `blocked` also counts as an opener (`first_governed_open_stamp`): that is a [named window variant](#named-window-variant). Do not write "first claim"; it is no longer exact. |
| **Related terms** | [Window-open SHA](#window-open-sha), [Work-package window](#work-package-window), [Named window variant](#named-window-variant) |

---

### Window gap

| | |
|---|---|
| **Definition** | The explicit, typed absence of a recorded window for a work package: "not recorded" (no value on the opener), "capture failed" (with the recorded cause), "lane branch missing" (every opener of the cycle recorded that the lane branch did not exist yet) or "not on lane" (the SHA is not an ancestor of the lane tip, or does not resolve in this clone). A gap never refuses by itself: the work package is judged by the approval-stamp bound and listed in the [gap report](#gap-report). ADR [2026-11-08-2](/adr/4.x/2026-11-08-2-work-package-windows-are-recorded-at-the-opening-transition.md). |
| **Context** | Orchestration |
| **Status** | candidate |
| **Applicable to** | `4.x` |
| **Do NOT use when** | The concept is a missing approval stamp: that is `APPROVAL_STAMP_MISSING`, a different refusal. Do not write "missing stamp" for a window gap. |
| **Related terms** | [Gap report](#gap-report), [Work-package window](#work-package-window), [Window-open SHA](#window-open-sha) |

---

### Gap report

| | |
|---|---|
| **Definition** | The part of the `consolidate` output (fresh run, resume and forecast; `window_gaps` in the JSON) that lists every work package judged by the fallback approval-stamp bound, with its [window gap](#window-gap) reason. ADR [2026-11-08-2](/adr/4.x/2026-11-08-2-work-package-windows-are-recorded-at-the-opening-transition.md). |
| **Context** | Orchestration |
| **Status** | candidate |
| **Applicable to** | `4.x` |
| **Do NOT use when** | The concept is a refusal or a warning about the work itself: a gap report lists the weaker check a work package got, and refuses nothing. Do not write "warning list". |
| **Related terms** | [Window gap](#window-gap), [Work-package window](#work-package-window) |

---

### Exemption anchor

| | |
|---|---|
| **Definition** | A commit whose reach exempts lane commits from the window refusal: the closed-world anchors (dependency-lane tips of lanes that are not fully canceled, the target's pre-consolidation tip) and the approval stamps of **other** bounded lanes. A lane's own approval stamps are not exemption anchors on the window path. ADR [2026-11-08-2](/adr/4.x/2026-11-08-2-work-package-windows-are-recorded-at-the-opening-transition.md). |
| **Context** | Orchestration |
| **Status** | candidate |
| **Applicable to** | `4.x` |
| **Do NOT use when** | The concept is an approval stamp of the lane under check, which does not exempt on the window path. Do not write "stamp anchor" without naming the lane. |
| **Related terms** | [Work-package window](#work-package-window), [Claim inputs](#claim-inputs), [Lane Consolidation](#lane-consolidation) |

---

### Claim inputs

| | |
|---|---|
| **Definition** | `ClaimInputs`: the one frozen value the consolidation gate's claim is built from, with one constructor and three sources (`LIVE` for the forecast, `LIVE_THEN_SAVED` for a fresh run, `SAVED` for a resume). It holds the target base, the coordination base, the frozen lane tips, the frozen dependency anchors, the dependency pins, the excluded canceled work packages, the strategy and the status directory read. ADR [2026-11-08-2](/adr/4.x/2026-11-08-2-work-package-windows-are-recorded-at-the-opening-transition.md). |
| **Context** | Orchestration |
| **Status** | candidate |
| **Applicable to** | `4.x` |
| **Do NOT use when** | The concept is the target branch's tip before the run mutated anything (the claim base), which is one field of the claim inputs. Do not write "claim args" or "gate params". |
| **Related terms** | [Lane Consolidation](#lane-consolidation), [Exemption anchor](#exemption-anchor), [Work-package window](#work-package-window) |

---

### Named window variant

| | |
|---|---|
| **Definition** | A deliberate difference between window definitions that ADR [2026-11-08-2](/adr/4.x/2026-11-08-2-work-package-windows-are-recorded-at-the-opening-transition.md) records by name instead of unifying: "lane anchor" (`blocked` opens), "canceled-content windows" (`WorkWindow`), "owned-file evidence", and the `single_branch` authorship window. |
| **Context** | Orchestration |
| **Status** | candidate |
| **Applicable to** | `4.x` |
| **Do NOT use when** | The concept is an accident or an unrecorded difference between two checks: a named variant is recorded and has a reason. Do not write "exception" or "special case". |
| **Related terms** | [Work-package window](#work-package-window), [Window opener](#window-opener), [Exemption anchor](#exemption-anchor) |

---

### Evidence gate

| | |
|---|---|
| **Definition** | A command that turns a Mission's local status or code into a durable verdict: review workspace preparation (`agent action review`), `accept`, `consolidate`, and the `orchestrator-api` `accept-mission` and `consolidate-mission` forms. Each one runs the [origin freshness check](#origin-freshness-check) before it trusts a local branch. Enforced by `tests/architectural/test_evidence_gates_check_origin.py`. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `4.x` |
| **Do NOT use when** | The concept is the end of a Mission's life — "terminus" already names that, so never "terminus gate". The concept is the reconciliation gate that verifies a consolidation landed approved content (`MergeOutcomeVerifier`) — that is one step *inside* `consolidate`, not the gate itself. The concept is the comparison against the remote — use [origin freshness check](#origin-freshness-check); never "origin reconciliation" or "sync". |
| **Related terms** | [origin freshness check](#origin-freshness-check), [status evidence branch](#status-evidence-branch), [Lane Consolidation](#lane-consolidation) |

---

### Origin freshness check

| | |
|---|---|
| **Definition** | Refreshing the remote's view of a branch in the current invocation and classifying the local branch against it. The verdict is one of `up_to_date`, `behind`, `ahead`, `diverged`, `local_missing`, `remote_missing`, `unreachable`, `no_remote`, `remote_ambiguous` or `compare_failed`; `not_checked` is recorded when the check is `off` and nothing was contacted (`FreshnessState`, `src/specify_cli/git/origin_freshness.py`). A landing-path gate (`consolidate`, `accept`, the two `orchestrator-api` gates) refuses on `ORIGIN_STATUS_STALE`, `ORIGIN_LANE_STALE`, `ORIGIN_UNREACHABLE`, `ORIGIN_REMOTE_AMBIGUOUS` or `ORIGIN_COMPARE_FAILED` unless the operator passes `--origin-check warn` (default `SPEC_KITTY_ORIGIN_CHECK`); `off` contacts nothing and accepts stale evidence. `ORIGIN_LANE_DIVERGED` is `agent action review` only, which has no flag: only `SPEC_KITTY_ORIGIN_CHECK=warn` lifts it. Owned by `specify_cli.git.origin_freshness`; every remote read (listing, fetch, clone, `remote show`) belongs to `kernel.git.remote`, while push is excluded (FR-015, #5858). See ADR [2026-10-06-3](/adr/4.x/2026-10-06-3-evidence-gates-check-origin-freshness.md). |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `4.x` |
| **Do NOT use when** | The concept is the check that a push will be accepted (`is_safe_to_push` in `push_preflight`) — that is push safety, which this check does not replace. The concept is the consolidation reconciliation gate — use [Evidence gate](#evidence-gate) and name the gate; do not say "origin reconciliation". The retired transport vocabulary ("sync", "in sync") is never used for this: say `up_to_date`. |
| **Related terms** | [Evidence gate](#evidence-gate), [status evidence branch](#status-evidence-branch), [Publish to origin/main](#publish-to-originmain) |

---

### Status evidence branch

| | |
|---|---|
| **Definition** | The branch whose copy of a Mission's `status.events.jsonl` an [evidence gate](#evidence-gate) reads: the coordination branch for a coordination topology, the write branch for `single_branch` (`kitty/mission-...` for a protected target, the target itself with `--commit-to-target`), and the target branch for `lanes`. The origin freshness check judges it only on commits that change this Mission's status log, under every directory alias of the Mission. A gate never moves it; it refuses and names the pull command. |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `4.x` |
| **Do NOT use when** | The concept is the [COORD partition](#coord-partition) (a placement rule over artifact kinds), or "coord" generally: a `lanes` or `single_branch` Mission has no coordination branch but still has a status evidence branch. The concept is a lane's code branch — use [Lane](#lane). |
| **Related terms** | [Evidence gate](#evidence-gate), [origin freshness check](#origin-freshness-check), [COORD partition](#coord-partition), [PRIMARY partition](#primary-partition) |

---

### COORD partition

| | |
|---|---|
| **Definition** | 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](#primary-partition) that holds stable planning artifacts. Like the PRIMARY partition it is an artifact-kind *placement 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](#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". |
| **Related terms** | [PRIMARY partition](#primary-partition), [Topology Surface](#topology-surface), [Lane](#lane), [Mission](#mission) |

---

### Target-owned bookkeeping

| | |
|---|---|
| **Definition** | A tracked file at the project root that Spec Kitty fully generates, marks "do not edit", and that no work package authors, declared `StateSurface.target_owned` in the state contract (`src/specify_cli/state/contract.py`; today only `.kittify/metadata.yaml`). Its authoritative copy is the one on the [Merge target branch](#merge-target-branch). When two branches of one Mission carry different copies, each integration site resolves the conflict to a fixed side without asking: the copy closer to the merge target branch wins, and between two lane branches the receiving lane branch keeps its own until consolidation. The per-site table is in ADR [2026-10-04-4](/adr/4.x/2026-10-04-4-upgrade-writes-project-global-state-once.md). The code identifiers `target_owned`, `is_target_owned_path` and the rule id `R-TARGET-OWNED-BOOKKEEPING` carry this sense. |
| **Context** | Orchestration |
| **Status** | candidate |
| **Applicable to** | `4.x` |
| **Use when** | Describing why `consolidate`, review start, implement resume or a lane sync did not refuse on a conflict in `.kittify/metadata.yaml`, or which copy of it survived. |
| **Do NOT use when** | The file is operator-editable (`.gitattributes`, `.gitignore`, `.kittify/config.yaml`): those are never target-owned, and a conflict on them still refuses. The concept is where a Mission artifact is stored: use [PRIMARY partition](#primary-partition); `.kittify/metadata.yaml` is not a Mission artifact and has no partition. The concept is "the repository root checkout's copy": no site computes that. Do not call it "primary-owned": that earlier name suggested the PRIMARY partition or the [primary branch](#primary-branch), and the merge target branch need not be the primary branch. |
| **Related terms** | [Merge target branch](#merge-target-branch), [Lane consolidation](#lane-consolidation), [PRIMARY partition](#primary-partition), [integrating worktree](/context/execution.md#integrating-worktree), [repository root checkout](/context/execution.md#repository-root-checkout) |

---

### Topology Surface

| | |
|---|---|
| **Definition** | The physical tree (working copy / checkout location) that a mission artifact resolves to for reading and writing. This is `surface` **Sense 2** — the mission-topology sense. Modeled by the `TopologySurface` enum in `src/mission_runtime/artifacts.py`, carried on `MissionArtifactHome` as `read_surface` / `write_surface`, and returned by `artifact_home_for`. Members with production callers today: `PRIMARY` — the repository-root planning tree; `COORD` — the mission's coordination tree. Also declared, together with the surface→filesystem translation seam that makes each resolvable (`translate_surface`, `src/mission_runtime/resolution.py`): `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. These three have no production caller yet, but every member maps to a real location and the seam's totality test (`assert_surface_totality`) exercises each, so none is a phantom. 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](/adr/3.x/2026-07-23-1-surface-vocabulary-two-domains-and-topology-surface-rename.md). |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `3.x` |
| **Note** | A topology surface is a *location*; a partition is a *placement-routing rule over artifact kinds*. The two vocabularies coincide only on the `PRIMARY` and `COORD` values — the [PRIMARY partition](#primary-partition) routes its kinds to the `PRIMARY` topology surface and the [COORD partition](#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 behavior 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](#lane-consolidation), [Branch Integration / Git Merge](#branch-integration--git-merge), and [Publish to origin/main](#publish-to-originmain). A member named `MERGED` would not say which of the three had happened. `CONSOLIDATED` names exactly one: the surface that exists after [Lane Consolidation](#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](/context/execution.md#tool-surface) (`surface` **Sense 1**). The concept is the artifact-kind placement-routing rule rather than the location — use [PRIMARY partition](#primary-partition) or [COORD partition](#coord-partition). The concept is the repository-root working copy versus a lane worktree as an operator-facing checkout — use [repository root checkout](/context/execution.md#repository-root-checkout). Never write bare "surface" in governed prose; name the sense ("topology surface" / "tool surface"). |
| **Related terms** | [Tool Surface](/context/execution.md#tool-surface), [PRIMARY partition](#primary-partition), [COORD partition](#coord-partition), [Lane](#lane), [Lane Consolidation](#lane-consolidation), [repository root checkout](/context/execution.md#repository-root-checkout) |

---

### Routing

| | |
|---|---|
| **Definition** | "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](#primary-partition) / [COORD partition](#coord-partition) / [Topology Surface](#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](#topology-surface). Owning module: `mission_runtime/resolution.py` (`PlacementSeam`, `placement_seam`). Full explanation: [The Artifact Placement Seam](/architecture/artifact-placement-seam.md). *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](/architecture/branch-target-routing.md). *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/charter/offering/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. Its former owning module, the hosted auth transport, was removed with the hosted surfaces in #6164; no current module is named as its owner. *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. It was owned by the sync transport's routing module; the whole sync package 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. |
| **Related terms** | [PRIMARY partition](#primary-partition), [COORD partition](#coord-partition), [Topology Surface](#topology-surface), [target branch](#target-branch) |

---

### The drain

| | |
|---|---|
| **Definition** | "The drain" is retired historical terminology on this line. It previously named three distinct flows — the **dispatch-selection drain** (in the delivery subsystem), the **body drain** (the sync transport's background body-queue sender), and the **queue-backed event drain** (the sync transport's batch sender, 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** (the delivery subsystem's selection step, feeding its dispatcher), **the body drain** (the sync transport's background sender, backed by its body queue), and **the queue-backed event drain** (the sync transport's batch sender, removed upstream by #3167 before the subsystem deletion). None has a successor mechanism in open-core. 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 the sync runtime module's claim that "the drain" walks the per-project consent chain as referring to the batch sender (which walked a different chain) instead of to the dispatch-selection step (which did 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](#lane-consolidation) or status-event flush paths; those are not drains and have their own terms. |
| **Related terms** | [Routing](#routing) (the retired sync fan-out sense decided *whether* a checkout participates, never what "the drain" means), [Lane Consolidation](#lane-consolidation), [Mission](#mission) |

---

### Residue

| | |
|---|---|
| **Definition** | "Residue" names a `kitty-specs/` child directory that is not a Mission — but it has no single rule. Three live code senses each answer "is this folder a Mission?" differently for their own surface, and each is justified in its owning docstring. This entry extends, not restates, [Mission](#mission); naming the senses is disambiguation, silence is not (the same footgun class as [Routing](#routing) above, issue #6759). |
| **Context** | Orchestration |
| **Status** | canonical |
| **Applicable to** | `4.x` |
| **Governed senses** | **Write-seam residue** — whether an upgrade or migration write seam must leave the folder untouched. Owning symbol: `is_kitty_specs_residue` (`src/specify_cli/context/mission_resolver.py`, #6627 / #6668). A `spec.md` on disk keeps a folder out of write-seam residue, so the upgrade sweep can still repair it. *Do NOT use when* the surface reads or audits the folder: a `spec.md`-only folder is never selectable, and the audit engine reports it too until its `spec.md` is tracked — those are the read-side and audit-engine senses below. — **Audit-engine residue** — a directory that fails `is_mission_dir`, reported as one INFO `RESIDUE_DIRECTORY` finding and not classified. Owning symbol: `RESIDUE_DIRECTORY` (`src/specify_cli/audit/models.py`, emitted by `src/specify_cli/audit/engine.py`, #5812). The engine keeps this looser rule deliberately (issue #5875): a tracked `spec.md`, or any marker on a non-git root, still makes a Mission there, so its findings must not disappear. *Do NOT use when* the question is whether Mission selection lists the folder (read-side residue is stricter) or whether a write seam may repair it (write-seam residue is looser). — **Read-side / `doctor identity` residue** — a folder Mission selection never lists: no `meta.json` on disk; a `meta.json` that carries no `mission_id` and that git does not back with a tracked marker (in a git repository); or a `meta.json` that is unreadable or not a JSON object when git tracks no marker (a Mission otherwise, which `doctor identity` then classifies as `orphan` — as read-side residue it carries the `corrupt_meta` reason with the read error). Owning symbol: `not is_selectable_mission_dir` (`src/specify_cli/context/mission_resolver.py`, consumed by `src/specify_cli/status/identity_audit.py`, #5875 operator ruling 2026-10-27). `doctor identity` reports each with its reason and remedy. *Do NOT use when* the question is whether a write seam may touch the folder (a `spec.md`-only folder is read-side residue but never write-seam residue) or what the audit engine reports (audit-engine residue). |
| **Note (why three rules)** | The strictness order is deliberate, not drift: the write seam must not destroy repairable work (so a `spec.md` on disk shields the folder), selection must not offer non-Missions to the operator (so it demands a `meta.json` and identity or a tracked marker), and the audit engine reports rather than classifies (so it keeps the `is_mission_dir` rule its findings were written against). A folder holding only a **tracked** `spec.md` is read-side residue and an audit-engine Mission; untracked, the audit engine reports it as `RESIDUE_DIRECTORY` too — but tracked or not it is never write-seam residue, because a `spec.md` on disk is all the write seam asks. The code is the source of truth for each rule; this entry only names and links them. |
| **Do NOT use when** | Never write bare "residue" in governed prose or in `src/` docstrings when the sense matters; name it ("write-seam residue" / "audit-engine residue" / "read-side residue") or link this entry. Also do not use "residue" for toolchain leftovers outside `kitty-specs/` (for example the status files a rolled-back consolidation may leave in a coordination worktree — "toolchain residue" is a different, ungoverned concept), or for the retired-vocabulary sense of leftover identifiers ([Team Kitty](/context/team-kitty.md)). |
| **Related terms** | [Mission](#mission), [Routing](#routing), [The drain](#the-drain) |

## Related

- [Context: Charter](/context/charter.md)
- [Context: Identity](/context/identity.md)
- [Context: System Events](/context/system-events.md)
- [Context: Technology Foundations](/context/technology-foundations.md)
- [Context: Topology](/context/topology.md)

## Audience

- [Stakeholder Persona: AI Collaboration Agent](/context/audience/internal/ai-collaboration-agent.md) - Resolve which sense of primary, merge, routing, residue or lane a text means before acting on it, and use the lifecycle and branch terms exactly as defined here.
- [Stakeholder Persona: Lead Developer](/context/audience/internal/lead-developer.md) - Use this when you change the Mission lifecycle, branch handling, consolidation or the placement seam.
