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
| |
|---|
| Definition | The 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. |
| Context | Topology |
| Status | canonical |
| Applicable to | 3.x |
| Do NOT use when | The 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 terms | write checkout, code lane, Topology Surface, Lane |
Size default
| |
|---|
| Definition | The 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. |
| Context | Topology |
| Status | canonical |
| Applicable to | 4.x |
| Do NOT use when | The 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 terms | topic branch, Topology, mission branch |
Topic branch
| |
|---|
| Definition | The 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. |
| Context | Topology |
| Status | canonical |
| Applicable to | 4.x |
| Do NOT use when | The Mission has an explicit topology — say mission branch or coordination branch. The concept is the branch the work lands on — use target branch. |
| Related terms | size default, mission branch, PRIMARY partition |
Write checkout
| |
|---|
| Definition | The 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. |
| Context | Topology |
| Status | canonical |
| Applicable to | 3.x |
| Do NOT use when | The 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 terms | repo-root lane, repository root checkout, mission branch, Topology |
Repo-root lane
| |
|---|
| Definition | The 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. |
| Context | Topology |
| Status | canonical |
| Applicable to | 3.x |
| Do NOT use when | The lane resolves to a .worktrees/ lane worktree — use code lane. Never call a single_branch lane “lane-a”. |
| Related terms | write checkout, code lane, Lane |
Code lane
| |
|---|
| Definition | A 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). |
| Context | Topology |
| Status | canonical |
| Applicable to | 3.x |
| Do NOT use when | The lane is the lane-planning bookkeeping lane — use repo-root lane. The concept is lane consolidation into the mission branch — use Lane Consolidation. |
| Related terms | repo-root lane, lane work tip, Lane, Topology |
Protected target
| |
|---|
| Definition | A 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). |
| Context | Topology |
| Status | canonical |
| Applicable to | 3.x |
| Do NOT use when | The 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 terms | mission branch, primary branch, target branch |
Mission branch
| |
|---|
| Definition | kitty/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. |
| Context | Topology |
| Status | canonical |
| Applicable to | 3.x |
| Do NOT use when | The 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 terms | topic branch, protected target, write checkout, Lane Consolidation, target branch |
Lane work tip
| |
|---|
| Definition | The 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. |
| Context | Topology |
| Status | canonical |
| Applicable to | 3.x |
| Do NOT use when | The 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 terms | absorbed lane, code lane, Lane |
Absorbed lane
| |
|---|
| Definition | A 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. |
| Context | Topology |
| Status | canonical |
| Applicable to | 3.x |
| Do NOT use when | The 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 terms | lane work tip, Lane Consolidation |
Execution-mode stamp
| |
|---|
| Definition | The 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. |
| Context | Topology |
| Status | canonical |
| Applicable to | 3.x |
| Do NOT use when | The 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 terms | write checkout, work package |
Started work package
| |
|---|
| Definition | A 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. |
| Context | Topology |
| Status | canonical |
| Applicable to | 4.x |
| Do NOT use when | The 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 terms | LANE_MEMBERSHIP_FROZEN, lane work tip, code lane, work package |
LANE_MEMBERSHIP_FROZEN
| |
|---|
| Definition | The 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. |
| Context | Topology |
| Status | canonical |
| Applicable to | 4.x |
| Do NOT use when | The 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 terms | started work package, code lane, repo-root lane |