---
type: "Context"
title: "Context: Topology"
description: "Topology glossary: the four topologies, size default, topic branch, write checkout, repo-root and code lanes, mission branch, lane work tip, started work package."
status: "stable"
generated:
  by: "process:dockitty-export"
  at: "2026-11-13T00:00:00Z"
---

## 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](/context/orchestration.md#primary-partition), [COORD partition](/context/orchestration.md#coord-partition), [Topology Surface](/context/orchestration.md#topology-surface) — lives in [Context: Orchestration](/context/orchestration.md).

### 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](#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](#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](/context/orchestration.md#primary-partition) or [COORD partition](/context/orchestration.md#coord-partition). The concept is the physical tree an artifact resolves to — use [Topology Surface](/context/orchestration.md#topology-surface). Never write "mode" or "layout" for a topology. |
| **Related terms** | [write checkout](#write-checkout), [code lane](#code-lane), [Topology Surface](/context/orchestration.md#topology-surface), [Lane](/context/orchestration.md#lane) |

---

### Size default

| | |
|---|---|
| **Definition** | The topology a Mission gets when `agent mission create` runs without `--topology` (ADR [4.x `2026-11-06-3`](/adr/4.x/2026-11-06-3-topology-is-settled-once-at-first-finalize.md), #7282). Create mints exactly one [topic branch](#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](#topic-branch), [Topology](#topology), [mission branch](#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](/context/orchestration.md#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](#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](#mission-branch) or coordination branch. The concept is the branch the work lands on — use [target branch](/context/orchestration.md#target-branch). |
| **Related terms** | [size default](#size-default), [mission branch](#mission-branch), [PRIMARY partition](/context/orchestration.md#primary-partition) |

---

### Write checkout

| | |
|---|---|
| **Definition** | The one checkout a `single_branch` mission writes code and status into: either the [repository root checkout](/context/execution.md#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](#code-lane). The concept is only the operator's repository-root working copy as opposed to a lane worktree — use [repository root checkout](/context/execution.md#repository-root-checkout). Never write "main repo" or "main repository". |
| **Related terms** | [repo-root lane](#repo-root-lane), [repository root checkout](/context/execution.md#repository-root-checkout), [mission branch](#mission-branch), [Topology](#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](#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](#code-lane). Never call a `single_branch` lane "lane-a". |
| **Related terms** | [write checkout](#write-checkout), [code lane](#code-lane), [Lane](/context/orchestration.md#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](#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](#repo-root-lane). The concept is lane consolidation into the mission branch — use [Lane Consolidation](/context/orchestration.md#lane-consolidation). |
| **Related terms** | [repo-root lane](#repo-root-lane), [lane work tip](#lane-work-tip), [Lane](/context/orchestration.md#lane), [Topology](#topology) |

---

### Protected target

| | |
|---|---|
| **Definition** | A target branch that is the repository's [primary branch](/context/orchestration.md#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](#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](/context/orchestration.md#primary-branch). The concept is the branch a mission's code must land on regardless of protection — use [target branch](/context/orchestration.md#target-branch). Never use `main` as a generic name for a protected target. |
| **Related terms** | [mission branch](#mission-branch), [primary branch](/context/orchestration.md#primary-branch), [target branch](/context/orchestration.md#target-branch) |

---

### Mission branch

| | |
|---|---|
| **Definition** | `kitty/mission-<slug>-<mid8>`. For a `single_branch` mission it is minted and checked out in the [write checkout](#write-checkout), and recorded as `mission_branch` in `meta.json`, only when the mission targets a [protected target](#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](#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](/context/orchestration.md#target-branch). The concept is the coordination branch — say "coord branch". The concept is a single lane's branch — use [code lane](#code-lane). |
| **Related terms** | [topic branch](#topic-branch), [protected target](#protected-target), [write checkout](#write-checkout), [Lane Consolidation](/context/orchestration.md#lane-consolidation), [target branch](/context/orchestration.md#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](#absorbed-lane), [code lane](#code-lane), [Lane](/context/orchestration.md#lane) |

---

### Absorbed lane

| | |
|---|---|
| **Definition** | A lane whose [work tip](#lane-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](/context/orchestration.md#lane-consolidation), [Branch Integration / Git Merge](/context/orchestration.md#branch-integration--git-merge) or [Publish to origin/main](/context/orchestration.md#publish-to-originmain). Never write bare "merged" for an absorbed lane. |
| **Related terms** | [lane work tip](#lane-work-tip), [Lane Consolidation](/context/orchestration.md#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](#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](#write-checkout), [work package](/context/orchestration.md#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](#code-lane) with no such work package but a recorded [lane work tip](#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](/architecture/execution-lanes.md#re-finalizing-an-active-mission) and ADR [4.x `2026-10-04-2`](/adr/4.x/2026-10-04-2-started-work-package-lane-membership-is-frozen.md). |
| **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_membership_frozen), [lane work tip](#lane-work-tip), [code lane](#code-lane), [work package](/context/orchestration.md#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](#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](/api/finalize-tasks-internals.md#5-started-work-packages-keep-their-lane-lane_membership_frozen). |
| **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](#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](#started-work-package), [code lane](#code-lane), [repo-root lane](#repo-root-lane) |

## Related

- [Execution Lanes](/architecture/execution-lanes.md)
- [Context: Execution](/context/execution.md)
- [Context: Orchestration](/context/orchestration.md)

## Audience

- [Stakeholder Persona: AI Collaboration Agent](/context/audience/internal/ai-collaboration-agent.md) - Use these terms to tell which checkout and branch a work package writes to, and to read the topology refusal codes correctly.
- [Stakeholder Persona: Lead Developer](/context/audience/internal/lead-developer.md) - Use this when you create, finalize or consolidate a Mission and need to know what its topology implies.
