Skip to content

Context: Orchestration

Who is this for (2)

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.

Repository

DefinitionThe local git repository that a Project is initialized from and executes within.
ContextOrchestration
Statuscanonical
Applicable to3.x
NoteUse this term when the repository boundary itself matters, especially for repository-scoped identity.
Related termsProject, Build

Project

DefinitionEntire repository initialized for Spec Kitty workflow execution.
ContextOrchestration
Statuscanonical
Applicable to1.x, 2.x

Mission Type

DefinitionReusable workflow blueprint that configures the mission’s steps (actions), their templates, and guardrails.
ContextOrchestration
Statuscanonical
Applicable to1.x, 2.x

Build

DefinitionOne checkout or worktree execution context inside a Repository, identified by machine and build-scoped runtime identity.
ContextOrchestration
Statuscanonical
Applicable to3.x
NoteUse this term when distinguishing per-worktree or per-machine runtime context from the repository boundary itself.
Related termsRepository, Mission Run

Mission

DefinitionA 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.
ContextOrchestration
Statuscanonical
Applicable to1.x, 2.x, 3.x
NoteThis is the generic tracked-item noun across software, research, planning, and documentation work.
Do NOT use whenThe concept is the reusable workflow blueprint the Mission is an instance of — use Mission Type. The concept is one runtime execution of the Mission’s step loop — use Mission Run. Never use the retired alias “Feature” for the Mission domain object (Terminology Canon).

Mission Run

DefinitionOne runtime execution of a Mission’s step loop, keyed by run_id.
ContextOrchestration
Statuscanonical
Applicable to1.x, 2.x, 3.x
Scoping ruleRuntime events should be scoped by the run’s run_id where available
Do NOT use whenThe concept is the tracked unit of work itself — use Mission. Avoid “mission session”.

Feature

DefinitionRetired alias for a Mission whose mission type is software-dev.
ContextOrchestration
Statusdeprecated
Applicable to1.x, 2.x (historical)
NoteProhibited for the Mission domain object in active surfaces (Terminology Canon). Use 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

DefinitionExecutable slice of work inside a mission plan, typically represented as WPxx tasks.
ContextOrchestration
Statuscanonical
Applicable to1.x, 2.x

Mission Action

DefinitionOuter lifecycle action for a mission, such as specify, plan, implement, review, or accept.
ContextOrchestration
Statuscanonical
Applicable to1.x, 2.x
Related termsMission Type, step contract, Procedure

step contract

DefinitionStructured contract for one mission action, including step sequencing, guard evaluation, prompt binding, and delegation hooks.
ContextOrchestration
Statuscanonical
Applicable to1.x, 2.x
Related termsMission Action, Mission-Runtime YAML, Procedure

Workflow

DefinitionUmbrella prose term for the overall flow of work.
ContextOrchestration
Statuscanonical (generic prose only)
Applicable to1.x, 2.x
RuleUse Mission Type, Mission Action, step contract, or Procedure when precision matters.

WorkPackage (Alias)

DefinitionLegacy lexical variant of work package.
ContextOrchestration
Statuscanonical
Applicable to1.x, 2.x
Canonical entrywork package

Lane

DefinitionStatus 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.
ContextOrchestration
Statuscanonical
Applicable to1.x, 2.x
Other senseExecution 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, normally the repository root checkout. Defined in Context: Topology (code lane, repo-root lane).
Do NOT use whenNever 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

DefinitionConfiguration file (mission-runtime.yaml) that defines a mission type’s step graph, action ordering, dependencies, and prompt-template bindings.
ContextOrchestration
Statuscanonical
Applicable to1.x, 2.x
Related termsMission Type, Step Dependency, step contract, Command Template

Step Dependency

DefinitionA declared relationship saying “this step cannot start until that step finishes.” Defined in mission-runtime YAML to enforce ordering.
ContextOrchestration
Statuscanonical
Applicable to1.x, 2.x
Related termsMission-Runtime YAML, Step Sequence

Step Sequence

DefinitionThe order in which mission steps execute, determined by the step list and dependency graph in mission-runtime YAML.
ContextOrchestration
Statuscanonical
Applicable to1.x, 2.x
Related termsStep Dependency, Mission-Runtime YAML

Command Template

DefinitionA 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.
ContextOrchestration
Statuscanonical
Applicable to1.x, 2.x
Related termsTemplate Resolution, Mission-Runtime YAML

Template Resolution

DefinitionThe 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.
ContextOrchestration
Statuscanonical
Applicable to1.x, 2.x
Related termsCommand Template

Mission Discovery

DefinitionHow the runtime finds and loads mission-type definition files (mission.yaml, mission-runtime.yaml) from configured mission-pack roots at startup.
ContextOrchestration
Statuscanonical
Applicable to1.x, 2.x
Related termsMission Type, Mission-Runtime YAML

Command Envelope

DefinitionStandard 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).
ContextOrchestration
Statuscanonical
Applicable to1.x, 2.x
Related termsOrchestrator API, Contract Version, JSON

Contract Version

DefinitionVersion number on the orchestrator API that tells consumers whether the API has changed in a breaking way.
ContextOrchestration
Statuscanonical
Applicable to1.x, 2.x
Related termsOrchestrator API, Command Envelope

Orchestrator API

DefinitionJSON-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 instead of human-facing output.
ContextOrchestration
Statuscanonical
Applicable to1.x, 2.x
Related termsCommand Envelope, API

Decision

DefinitionA 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.
ContextOrchestration
Statuscanonical
Applicable to1.x, 2.x, 3.x
LifecycleIn event-backed runtimes, opened by Decision Input Request; closed by Decision Input Answer.
Former SaaS projectionBefore 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 withSaaS 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 termsDecision Kind, Decision Input Request, Decision Input Answer, Human-in-Charge (HiC)

Decision Kind

DefinitionThe 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.
ContextOrchestration
Statuscanonical
Applicable to1.x, 2.x, 3.x
Related termsDecision, Decision Input Request

Decision Input Request

DefinitionThe 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”.
ContextOrchestration
Statuscanonical
Applicable to2.x, 3.x
Event typeDecisionInputRequested (in spec-kitty-events)
Former SaaS effectBefore #6164, created a DecisionInboxItem row with state=pending in the hosted product. Open-core no longer sends it there.
Related termsDecision, Decision Input Answer, Mission Run

Decision Input Answer

DefinitionThe 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.
ContextOrchestration
Statuscanonical
Applicable to2.x, 3.x
Event typeDecisionInputAnswered (in spec-kitty-events)
Former SaaS effectBefore #6164, updated the matching DecisionInboxItem to state=answered in the hosted product. Open-core no longer sends it there.
Related termsDecision, Decision Input Request

Runtime Bridge

DefinitionThe 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.
ContextOrchestration
Statuscanonical
Applicable to1.x, 2.x
Related termsDecision, Human-in-Charge (HiC)

Mission State Derivation

DefinitionThe 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.
ContextOrchestration
Statuscanonical
Applicable to1.x, 2.x
Related termsMission Run, Decision

base branch

DefinitionOverloaded 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.
ContextOrchestration
Statuscanonical
Applicable to3.x
Related termstarget branch, Planning base branch, Lane

branch strategy gate

DefinitionThe 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.
ContextOrchestration
Statuscanonical
Applicable to3.x
Related termspr-bound mission, primary branch, feature branch, start branch

current branch

DefinitionThe 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.
ContextOrchestration
Statuscanonical
Applicable to3.x
Related termstarget branch, base branch

topic branch

DefinitionA short-lived branch carrying one change to a pull request.
ContextOrchestration
Statuscanonical
Applicable to3.x, 4.x
Do NOT use whenThe concept is the repository’s default integration branch — use primary branch. The concept is the ref a mission’s code must ultimately land on — use target branch. Avoid the aliases “feature branch” and “PR branch”.
Related termsfeature branch, primary branch, target branch, pr-bound mission

feature branch

DefinitionAlias of topic branch: a short-lived branch carrying one change to a pull request. Prefer “topic branch” in canonical and operator-facing language.
ContextOrchestration
Statusdeprecated
Applicable to3.x, 4.x
Do NOT use whenPrefer the canonical 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 termstopic branch, pr-bound mission, primary branch, start branch, target branch

gate binding

DefinitionA 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.
ContextOrchestration
Statuscanonical
Applicable to3.x
Related termsgate handler, transition gate, branch strategy gate

gate handler

DefinitionA 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.
ContextOrchestration
Statuscanonical
Applicable to3.x
Related termsgate binding, transition gate, branch strategy gate

Merge target branch

DefinitionThe 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 sense), not lane consolidation. JSON key: merge_target_branch.
ContextOrchestration
Statuscanonical
Applicable to3.x
Related termstarget branch, Planning base branch, work package

Planning base branch

DefinitionThe 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.
ContextOrchestration
Statuscanonical
Applicable to3.x
Related termstarget branch, Merge target branch, Lane, work package

primary branch

DefinitionThe 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.
ContextOrchestration
Statuscanonical
Applicable to3.x
Do NOT use whenThe concept is the artifact-kind partition — use PRIMARY partition. The concept is the repository-root working copy versus a lane worktree — use repository root checkout. The concept is the ref planning artifacts commit to — use Target Ref / Commit Target.
Related termscurrent branch, target branch, feature branch, branch strategy gate, PRIMARY partition, repository root checkout, Target Ref / Commit Target

pr-bound mission

DefinitionA 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.
ContextOrchestration
Statuscanonical
Applicable to3.x
Related termsbranch strategy gate, feature branch, primary branch

start branch

DefinitionThe 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.
ContextOrchestration
Statuscanonical
Applicable to3.x
Related termsfeature branch, target branch, branch strategy gate

target branch

DefinitionThe 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.
ContextOrchestration
Statuscanonical
Applicable to2.x, 3.x
Related termsbase branch, Planning base branch, Merge target branch, current branch, Mission

transition gate

DefinitionA 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.
ContextOrchestration
Statuscanonical
Applicable to3.x
Related termsgate handler, gate binding, branch strategy gate

Tracker Connector

DefinitionOutbound integration boundary that projects host lifecycle state to external tracker systems without transferring lifecycle authority.
ContextOrchestration
Statuscanonical
Applicable to1.x, 2.x
Related termstarget branch, Orchestrator API, WPStatusChanged

Tracker Connector Boundary (Alias)

DefinitionArchitecture-facing alias for Tracker Connector.
ContextOrchestration
Statuscanonical
Applicable to1.x, 2.x
Canonical entryTracker Connector

PRIMARY partition

DefinitionThe 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 placement 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 primary Sense A.
ContextOrchestration
Statuscanonical
Applicable to3.x
Do NOT use whenThe 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”.
Related termsprimary branch, COORD partition, Topology Surface, repository root checkout, Target Ref / Commit Target, target branch

Target Ref / Commit Target

DefinitionThe 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.
ContextOrchestration
Statuscanonical
Applicable to3.x
Do NOT use whenThe 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”.
Related termstarget branch, Merge target branch, base branch, current branch, PRIMARY partition

Lane Consolidation

DefinitionThe 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 locally (integrate_mission_into_target), and publishes only when the operator passes --push (see Publish to origin/main).
ContextOrchestration
Statuscanonical
Applicable to3.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). 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 whenThe concept is the git merge that integrates the mission branch into its target branch — use Branch Integration / Git Merge. The concept is publishing the landed 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).
Related termsBranch Integration / Git Merge, Publish to origin/main, Merge target branch, Lane, Topology Surface

Branch Integration / Git Merge

DefinitionThe 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.
ContextOrchestration
Statuscanonical
Applicable to3.x
Do NOT use whenThe concept is spec-kitty consolidate’s local lane consolidation — use Lane Consolidation. The concept is publishing the landed work to origin/main — use Publish to origin/main.
Related termsLane Consolidation, Publish to origin/main, target branch, Merge target branch

Publish to origin/main

DefinitionThe 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”.
ContextOrchestration
Statuscanonical
Applicable to3.x
Do NOT use whenThe concept is spec-kitty consolidate’s local lane consolidation — use Lane Consolidation. The concept is the git merge branch-integration step — use Branch Integration / Git Merge.
Related termsLane Consolidation, Branch Integration / Git Merge, primary branch

Branch-relative provenance

DefinitionThe 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.
ContextOrchestration
Statuscanonical
Applicable to4.x
Do NOT use whenThe 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 termsPublish to origin/main, Lane Consolidation, Evidence gate

Work-package window

DefinitionThe span of lane history one approved work package is accountable for: from its window-open SHA (exclusive) to its newest approval stamp (inclusive). A work package with a window gap gets a degraded window from the claim base to its approval stamp. ADR 2026-11-08-2.
ContextOrchestration
Statuscandidate
Applicable to4.x
Do NOT use whenThe concept is the canceled-content implementation and review windows of a mixed lane (WorkWindow): that is a named window variant, never “work-package window”. Do not write “work window” or “WP range” for this sense.
Related termsWindow-open SHA, Window opener, Window gap, Exemption anchor, Named window variant

Window-open SHA

DefinitionThe 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. It is branch-relative provenance, valid for one consolidation attempt. ADR 2026-11-08-2.
ContextOrchestration
Statuscandidate
Applicable to4.x
Do NOT use whenThe 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 termsWork-package window, Window opener, Window gap, Branch-relative provenance

Window opener

DefinitionThe 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.
ContextOrchestration
Statuscandidate
Applicable to4.x
Do NOT use whenThe concept is the closed-world lane anchor, where blocked also counts as an opener (first_governed_open_stamp): that is a named window variant. Do not write “first claim”; it is no longer exact.
Related termsWindow-open SHA, Work-package window, Named window variant

Window gap

DefinitionThe 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. ADR 2026-11-08-2.
ContextOrchestration
Statuscandidate
Applicable to4.x
Do NOT use whenThe concept is a missing approval stamp: that is APPROVAL_STAMP_MISSING, a different refusal. Do not write “missing stamp” for a window gap.
Related termsGap report, Work-package window, Window-open SHA

Gap report

DefinitionThe 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 reason. ADR 2026-11-08-2.
ContextOrchestration
Statuscandidate
Applicable to4.x
Do NOT use whenThe 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 termsWindow gap, Work-package window

Exemption anchor

DefinitionA 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.
ContextOrchestration
Statuscandidate
Applicable to4.x
Do NOT use whenThe 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 termsWork-package window, Claim inputs, Lane Consolidation

Claim inputs

DefinitionClaimInputs: 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.
ContextOrchestration
Statuscandidate
Applicable to4.x
Do NOT use whenThe 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 termsLane Consolidation, Exemption anchor, Work-package window

Named window variant

DefinitionA deliberate difference between window definitions that ADR 2026-11-08-2 records by name instead of unifying: “lane anchor” (blocked opens), “canceled-content windows” (WorkWindow), “owned-file evidence”, and the single_branch authorship window.
ContextOrchestration
Statuscandidate
Applicable to4.x
Do NOT use whenThe 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 termsWork-package window, Window opener, Exemption anchor

Evidence gate

DefinitionA 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 before it trusts a local branch. Enforced by tests/architectural/test_evidence_gates_check_origin.py.
ContextOrchestration
Statuscanonical
Applicable to4.x
Do NOT use whenThe 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; never “origin reconciliation” or “sync”.
Related termsorigin freshness check, status evidence branch, Lane Consolidation

Origin freshness check

DefinitionRefreshing 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.
ContextOrchestration
Statuscanonical
Applicable to4.x
Do NOT use whenThe 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 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 termsEvidence gate, status evidence branch, Publish to origin/main

Status evidence branch

DefinitionThe branch whose copy of a Mission’s status.events.jsonl an 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.
ContextOrchestration
Statuscanonical
Applicable to4.x
Do NOT use whenThe concept is the 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.
Related termsEvidence gate, origin freshness check, COORD partition, PRIMARY partition

COORD partition

DefinitionThe 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 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.
ContextOrchestration
Statuscanonical
Applicable to3.x
Do NOT use whenThe 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”.
Related termsPRIMARY partition, Topology Surface, Lane, Mission

Target-owned bookkeeping

DefinitionA 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. 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. The code identifiers target_owned, is_target_owned_path and the rule id R-TARGET-OWNED-BOOKKEEPING carry this sense.
ContextOrchestration
Statuscandidate
Applicable to4.x
Use whenDescribing 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 whenThe 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; .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, and the merge target branch need not be the primary branch.
Related termsMerge target branch, Lane consolidation, PRIMARY partition, integrating worktree, repository root checkout

Topology Surface

DefinitionThe 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.
ContextOrchestration
Statuscanonical
Applicable to3.x
NoteA 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 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 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, 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 whenThe concept is a tool-visible artifact or configuration entry Spec Kitty installs for a concrete execution tool — use Tool Surface (surface Sense 1). The concept is the artifact-kind placement-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”).
Related termsTool Surface, PRIMARY partition, COORD partition, Lane, Lane Consolidation, 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 / COORD partition / Topology Surface above, which already frame the placement sense; naming an exclusion is disambiguation, silence is not.
ContextOrchestration
Statuscanonical
Applicable to3.x
Governed sensesPlacement 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/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 senseSync 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 whenNever write bare “routing” in governed prose without naming which of the senses above (or an explicitly out-of-scope one) is meant.
Related termsPRIMARY partition, COORD partition, Topology Surface, 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 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 |


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; naming the senses is disambiguation, silence is not (the same footgun class as Routing above, issue #6759).
ContextOrchestration
Statuscanonical
Applicable to4.x
Governed sensesWrite-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 whenNever 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).
Related termsMission, Routing, The drain