Skip to content

Context: Topology

Who is this for (2)

Context: Topology

Terms describing the shape a mission is given at creation and where its work runs. Introduced by mission single-branch-topology-honesty-01M3M22V (#5100). Related placement vocabulary — PRIMARY partition, COORD partition, Topology Surface — lives in Context: Orchestration.

Topology

DefinitionThe shape a mission is given at creation, stored as topology in meta.json. Exactly four values, the 2x2 product of “has a coordination branch” and “has lanes”: single_branch (no coordination, no lanes: every work package runs in the write checkout), lanes (no coordination, computed code lanes), coord (coordination, no lanes), lanes_with_coord (coordination and code lanes). Realized by the MissionTopology enum in src/mission_runtime/context.py. Create-time default (when --topology is omitted): the size default. lanes and coord come only from an explicit --topology; single_branch also comes from --owned-checkout; an explicit value is settled at create and never re-decided. A mission with no stored topology (created before the field existed) is read as lanes at runtime, whereas spec-kitty migrate backfill-topology writes the derived 2x2 cell, which can be single_branch for a mission with no code lane yet; the write is an explicit operator choice that switches the mission onto the single_branch runtime. doctor coordination --fix does not make that choice for you: after flattening a mission whose coordination branch was never created it stamps the runtime reading (lanes), not a derived single_branch.
ContextTopology
Statuscanonical
Applicable to3.x
Do NOT use whenThe concept is the artifact-kind placement rule (placement routing) — use PRIMARY partition or COORD partition. The concept is the physical tree an artifact resolves to — use Topology Surface. Never write “mode” or “layout” for a topology.
Related termswrite checkout, code lane, Topology Surface, Lane

Size default

DefinitionThe topology a Mission gets when agent mission create runs without --topology (ADR 4.x 2026-11-06-3, #7282). Create mints exactly one topic branch on every target and no worktree, and records topology: single_branch, topology_source: default, topology_settled: false and create_return_branch (the branch the repository root checkout was on). Because create switches the checkout, it refuses with WRITE_CHECKOUT_DIRTY when the checkout has changes outside the new Mission’s own scaffold, including the uncommitted spec.md an earlier default create left behind: git carries untracked files across a branch switch, so that scaffold would otherwise land on the new Mission’s branch. Commit (or discard) the earlier scaffold on its own Mission branch first. The first finalize-tasks settles the topology once, by size (lanes/topology_settlement.py): at most two non-canceled work packages, or at most one code lane, stays single_branch (a Mission that meets either limit stays, so a tie stays single_branch); anything larger becomes lanes_with_coord, on protected and unprotected targets alike, with the topic branch as its coordination branch. Settlement then records topology_settled: true; a settled Mission, and every Mission created with an explicit topology, is never re-decided. finalize-tasks --validate-only only previews the decision. A lanes_with_coord settlement commits the Mission directory on the topic branch, moves the repository root checkout back to create_return_branch, materializes the coordination worktree on the topic branch, re-stamps meta.json there and writes lanes.json; any failure undoes every step, leaves the Mission provisional and refuses with TOPOLOGY_SETTLEMENT_REFUSED (or WRITE_CHECKOUT_OCCUPIED / WRITE_CHECKOUT_DIRTY). A later failure of the same finalize-tasks run also undoes the settlement.
ContextTopology
Statuscanonical
Applicable to4.x
Do NOT use whenThe Mission was created with --topology or --owned-checkout — its topology is explicit. Never call the default “explicit-only” and never say it is decided at create.
Related termstopic branch, Topology, mission branch

Topic branch

DefinitionThe one branch a default Mission’s create mints, kitty/mission-<slug>-<mid8>, recorded as mission_branch in meta.json and checked out in the write checkout. Before the landing it holds the Mission’s PRIMARY partition artifacts (spec, plan, work package outlines): the placement seam resolves the PRIMARY partition to meta.mission_branch until consolidate records the landing, and to target_branch after it. A Mission that stays single_branch lands it like any mission branch. A Mission settled to lanes_with_coord uses it as its coordination branch, which therefore shares the Mission branch’s name, and cuts its code lanes from it. Its consolidation refuses the coordination teardown (exit 1, branch, coordination worktree and marker kept) while the topic branch still holds PRIMARY-partition changes the target does not carry; the message names the paths and says to review them with git diff <target> <branch>, land them on the target, then run spec-kitty consolidate --resume.
ContextTopology
Statuscanonical
Applicable to4.x
Do NOT use whenThe Mission has an explicit topology — say mission branch or coordination branch. The concept is the branch the work lands on — use target branch.
Related termssize default, mission branch, PRIMARY partition

Write checkout

DefinitionThe one checkout a single_branch mission writes code and status into: either the repository root checkout or a validated owned checkout (ADR 2026-09-03-1). Work packages run in it one at a time, stamped execution_mode: direct_repo. implement refuses with WRITE_CHECKOUT_WRONG_BRANCH, WRITE_CHECKOUT_OCCUPIED or WRITE_CHECKOUT_DIRTY (a resume is exempt from the dirty check; the claimed Mission’s own status files and event log, and spec-kitty’s runtime directories .kittify/, .spec-kitty/ and kitty-ops/, never count as dirty). WRITE_CHECKOUT_OCCUPIED counts an in_progress WP only when its mission writes to the branch the checkout is on (#5550); a status copy on another branch does not count, except that a mission whose write branch cannot be determined (no usable target_branch, meta.json and lanes.json disagreeing, or a detached HEAD) still counts on every branch. Occupancy is per branch, not per directory: switching the same checkout to another branch while a WP is in_progress is caught only by the dirty-checkout refusal.
ContextTopology
Statuscanonical
Applicable to3.x
Do NOT use whenThe mission has code lanes — its work runs in a lane worktree, not a write checkout; use code lane. The concept is only the operator’s repository-root working copy as opposed to a lane worktree — use repository root checkout. Never write “main repo” or “main repository”.
Related termsrepo-root lane, repository root checkout, mission branch, Topology

Repo-root lane

DefinitionThe single bookkeeping lane of a single_branch mission, keeping the existing lane id lane-planning. It always resolves to the write checkout, never to a .worktrees/ path, and has no lane branch. It generalizes the planning lane that every topology already carries for planning_artifact work packages.
ContextTopology
Statuscanonical
Applicable to3.x
Do NOT use whenThe lane resolves to a .worktrees/ lane worktree — use code lane. Never call a single_branch lane “lane-a”.
Related termswrite checkout, code lane, Lane

Code lane

DefinitionA lane that resolves to a .worktrees/ lane worktree and a lane branch. Only lanes and lanes_with_coord missions have code lanes. A repo-root lane is never a code lane. A single_branch mission whose lanes.json holds a code lane is unmigrated and fails closed with SINGLE_BRANCH_CODE_LANES_UNMIGRATED; the remedy is spec-kitty migrate backfill-topology --restamp-single-branch (always works), or spec-kitty upgrade (its re-stamp migration can be a no-op where it is already recorded).
ContextTopology
Statuscanonical
Applicable to3.x
Do NOT use whenThe lane is the lane-planning bookkeeping lane — use repo-root lane. The concept is lane consolidation into the mission branch — use Lane Consolidation.
Related termsrepo-root lane, lane work tip, Lane, Topology

Protected target

DefinitionA target branch that is the repository’s primary branch, or one that ProtectionPolicy reports as protected. Both cases are answered by one query, ProtectionPolicy.is_protected_target (src/specify_cli/git/protection_policy.py); no forge API is consulted. A single_branch mission targeting a protected target gets a mission branch at create time unless --commit-to-target is passed; that flag (persisted in meta.json, decided in ProtectionPolicy) un-protects only that mission’s own target for its own writes. An explicit lanes create (no Mission or coordination branch) on a target the status-write guard protects (ProtectionPolicy.is_protected) is refused before any write with LANES_PROTECTED_TARGET_REFUSED; use an unprotected target or --topology lanes_with_coord (#7632).
ContextTopology
Statuscanonical
Applicable to3.x
Do NOT use whenThe concept is only the repository’s default integration branch — use primary branch. The concept is the branch a mission’s code must land on regardless of protection — use target branch. Never use main as a generic name for a protected target.
Related termsmission branch, primary branch, target branch

Mission branch

Definitionkitty/mission-<slug>-<mid8>. For a single_branch mission it is minted and checked out in the write checkout, and recorded as mission_branch in meta.json, only when the mission targets a protected target without --commit-to-target. spec-kitty consolidate then lands the mission branch onto the target. Lane-based missions carry the same branch name as the consolidation base of their code lanes; on a coordination topology the coordination branch is that same branch (mission_branch_name and coordination_branch_name give one name). A default Mission’s mission branch is its topic branch.
ContextTopology
Statuscanonical
Applicable to3.x
Do NOT use whenThe concept is the branch a mission’s code must ultimately land on — use target branch. The concept is the coordination branch — say “coord branch”. The concept is a single lane’s branch — use code lane.
Related termstopic branch, protected target, write checkout, Lane Consolidation, target branch

Lane work tip

DefinitionThe last commit made on a lane branch, recorded when the commit happens, independent of any spec-kitty command. It is stored in refs/spec-kitty/lane-tip/<branch>, written by a POSIX post-commit / post-rewrite hook when the recorder is installed (migration 4_0_0rc5_install_lane_tip_recorder; a foreign hook is left untouched; the hooks are skipped with a warning when core.hooksPath comes from global or system git config, is /dev/null, missing, or inside the working tree), plus spec-kitty’s own record points (implement, for_review transitions, crash recovery, auto-rebase; src/specify_cli/lanes/lane_tip.py). It is distinct from the lane’s creation base. A destroyed lane with unabsorbed work is refused with DESTROYED_LANE, which names the SHA and the restore command git branch <b> refs/spec-kitty/lane-tip/<b>. LANE_WORK_TIP_UNKNOWN (LaneWorkTipUnknownError) fires when a lane’s branch was deleted before any work tip was recorded, or after its refs/spec-kitty/lane-tip/<branch> ref was deleted: nothing is left to classify the lane by, so the guard fails closed. It also fires when the recorder hook is not active and the recorded tip still equals the lane’s creation base: commits never moved the tip, so it cannot tell an empty lane from one with unrecorded work. Its message says to look for stranded commits (git reflog <branch> or git fsck --lost-found); if you find one, record it with git update-ref refs/spec-kitty/lane-tip/<branch> <sha> and re-run implement; if you are sure no work was ever committed, run spec-kitty context cleanup to clear the stale workspace record and retry. Abandoning a destroyed lane (DESTROYED_LANE) is two steps today: git update-ref -d refs/spec-kitty/lane-tip/<branch>, then spec-kitty context cleanup. Squash-absorption detection needs git >= 2.38 (git merge-tree --write-tree); on older git the guard fails closed and refuses even a genuinely squash-merged lane.
ContextTopology
Statuscanonical
Applicable to3.x
Do NOT use whenThe concept is the commit a lane was cut from — say “lane base”. Never write a bare “head” or a bare “tip” for the work tip.
Related termsabsorbed lane, code lane, Lane

Absorbed lane

DefinitionA lane whose work tip is an ancestor of the target, equals the lane’s base (tip == base, nothing was ever committed), or whose integration into the target would change nothing (for example after a squash). The destroyed-lane guard treats an absorbed lane as safe to re-cut; an unabsorbed one is refused. Squash detection needs git >= 2.38; if git cannot evaluate absorption (including any older git) the check fails closed and the lane is not treated as absorbed.
ContextTopology
Statuscanonical
Applicable to3.x
Do NOT use whenThe concept is one of the three “merge” operations — use Lane Consolidation, Branch Integration / Git Merge or Publish to origin/main. Never write bare “merged” for an absorbed lane.
Related termslane work tip, Lane Consolidation

Execution-mode stamp

DefinitionThe execution_mode recorded on status events: worktree or direct_repo. direct_repo is stamped for every work package that runs in a write checkout, and also for planning_artifact work packages of every topology, because they resolve to the repo-root lane. It is not the work-product kind (code_change / planning_artifact), which older code and work-package frontmatter also call execution_mode.
ContextTopology
Statuscanonical
Applicable to3.x
Do NOT use whenThe concept is whether a work package produces code or planning artifacts — say “work-product kind” (code_change / planning_artifact). Never write bare “execution_mode” when the kind is meant.
Related termswrite checkout, work package

Started work package

DefinitionA work package whose status history has ever recorded a move into a working status lane: claimed, in_progress, for_review, in_review, approved or done, including forced moves and blocked → in_progress moves that skip claimed (started_wp_ids, src/specify_cli/lanes/frozen_membership.py). Being reset to planned, or canceled, afterwards does not make it unstarted. A move from planned straight to blocked or canceled does not start it. On a re-finalize, a prior code lane with no such work package but a recorded lane work tip counts as wholly started. A started work package keeps its recorded execution lane when finalize-tasks is re-run; see Execution Lanes and ADR 4.x 2026-10-04-2.
ContextTopology
Statuscanonical
Applicable to4.x
Do NOT use whenThe concept is the work package’s current status lane — name the lane (in_progress, for_review, …). “Started” is not a synonym of in_progress: a done, canceled or reset work package can be started. The concept is the planning-pin question “has execution begun?” (any work package currently past planned, blocked and canceled included) — that is a different predicate. Avoid “active WP” or “in-flight WP”, which are ambiguous about resets.
Related termsLANE_MEMBERSHIP_FROZEN, lane work tip, code lane, work package

LANE_MEMBERSHIP_FROZEN

DefinitionThe error code (LaneMembershipFrozenError, src/specify_cli/lanes/compute.py) with which spec-kitty agent mission finalize-tasks refuses a re-finalize that cannot keep every started work package on its recorded execution lane. Its reason is one of started_lanes_collapsed (started work packages from two execution lanes would share one), started_wp_removed (a started work package’s task file was removed without canceling it), started_wp_kind_changed (its execution_mode would move it across lane-planning) or status_unreadable (a lanes.json exists but the status surface or log cannot be read). It is raised by a read-only preflight before the first status write, --validate-only included, and exits 1 with no status event, lanes.json or commit written; edits finalize made to work package files earlier in the run are restored. The JSON envelope and the non-destructive remedy for each reason are in finalize-tasks internals §5.
ContextTopology
Statuscanonical
Applicable to4.x
Do NOT use whenThe failure is implement refusing a lane whose branch or work tip is gone — use LANE_WORK_TIP_UNKNOWN or DESTROYED_LANE (lane work tip). The failure is a cyclic lane graph — that is LANE_DEPENDENCY_CYCLE. Never answer it by deleting lanes.json, forcing, or resetting git; the remedies keep the recorded lanes.
Related termsstarted work package, code lane, repo-root lane