<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/context/topology/">
  <id>https://docs.spec-kitty.ai/context/topology/</id>
  <title>Context: Topology</title>
  <updated>2026-11-13T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/context/topology/"/>
  <summary>Topology glossary: the four topologies, size default, topic branch, write checkout, repo-root and code lanes, mission branch, lane work tip, started work package.</summary>
  <content type="html">&lt;h2 id=&quot;context-topology&quot;&gt;Context: Topology&lt;/h2&gt;
&lt;p&gt;Terms describing the shape a mission is given at creation and where its work runs. Introduced by mission &lt;code dir=&quot;auto&quot;&gt;single-branch-topology-honesty-01M3M22V&lt;/code&gt; (#5100). Related placement vocabulary — &lt;a href=&quot;/context/orchestration/#primary-partition&quot;&gt;PRIMARY partition&lt;/a&gt;, &lt;a href=&quot;/context/orchestration/#coord-partition&quot;&gt;COORD partition&lt;/a&gt;, &lt;a href=&quot;/context/orchestration/#topology-surface&quot;&gt;Topology Surface&lt;/a&gt; — lives in &lt;a href=&quot;/context/orchestration/&quot;&gt;Context: Orchestration&lt;/a&gt;.&lt;/p&gt;
&lt;h3 id=&quot;topology&quot;&gt;Topology&lt;/h3&gt;

































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

































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;&lt;/th&gt;&lt;th&gt;&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Definition&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;The topology a Mission gets when &lt;code dir=&quot;auto&quot;&gt;agent mission create&lt;/code&gt; runs without &lt;code dir=&quot;auto&quot;&gt;--topology&lt;/code&gt; (ADR &lt;a href=&quot;/adr/4.x/2026-11-06-3-topology-is-settled-once-at-first-finalize/&quot;&gt;4.x &lt;code dir=&quot;auto&quot;&gt;2026-11-06-3&lt;/code&gt;&lt;/a&gt;, #7282). Create mints exactly one &lt;a href=&quot;#topic-branch&quot;&gt;topic branch&lt;/a&gt; on every target and no worktree, and records &lt;code dir=&quot;auto&quot;&gt;topology: single_branch&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;topology_source: default&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;topology_settled: false&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;create_return_branch&lt;/code&gt; (the branch the repository root checkout was on). Because create switches the checkout, it refuses with &lt;code dir=&quot;auto&quot;&gt;WRITE_CHECKOUT_DIRTY&lt;/code&gt; when the checkout has changes outside the new Mission’s own scaffold, including the uncommitted &lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt; 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 &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; settles the topology once, by size (&lt;code dir=&quot;auto&quot;&gt;lanes/topology_settlement.py&lt;/code&gt;): at most two non-canceled work packages, or at most one code lane, stays &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt; (a Mission that meets either limit stays, so a tie stays &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt;); anything larger becomes &lt;code dir=&quot;auto&quot;&gt;lanes_with_coord&lt;/code&gt;, on protected and unprotected targets alike, with the topic branch as its coordination branch. Settlement then records &lt;code dir=&quot;auto&quot;&gt;topology_settled: true&lt;/code&gt;; a settled Mission, and every Mission created with an explicit topology, is never re-decided. &lt;code dir=&quot;auto&quot;&gt;finalize-tasks --validate-only&lt;/code&gt; only previews the decision. A &lt;code dir=&quot;auto&quot;&gt;lanes_with_coord&lt;/code&gt; settlement commits the Mission directory on the topic branch, moves the repository root checkout back to &lt;code dir=&quot;auto&quot;&gt;create_return_branch&lt;/code&gt;, materializes the coordination worktree on the topic branch, re-stamps &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; there and writes &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;; any failure undoes every step, leaves the Mission provisional and refuses with &lt;code dir=&quot;auto&quot;&gt;TOPOLOGY_SETTLEMENT_REFUSED&lt;/code&gt; (or &lt;code dir=&quot;auto&quot;&gt;WRITE_CHECKOUT_OCCUPIED&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;WRITE_CHECKOUT_DIRTY&lt;/code&gt;). A later failure of the same &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; run also undoes the settlement.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Context&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Topology&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Status&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;canonical&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Applicable to&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;4.x&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Do NOT use when&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;The Mission was created with &lt;code dir=&quot;auto&quot;&gt;--topology&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;--owned-checkout&lt;/code&gt; — its topology is explicit. Never call the default “explicit-only” and never say it is decided at create.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Related terms&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;a href=&quot;#topic-branch&quot;&gt;topic branch&lt;/a&gt;, &lt;a href=&quot;#topology&quot;&gt;Topology&lt;/a&gt;, &lt;a href=&quot;#mission-branch&quot;&gt;mission branch&lt;/a&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;hr&gt;
&lt;h3 id=&quot;topic-branch&quot;&gt;Topic branch&lt;/h3&gt;

































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;&lt;/th&gt;&lt;th&gt;&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Definition&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;The one branch a default Mission’s create mints, &lt;code dir=&quot;auto&quot;&gt;kitty/mission-&amp;#x3C;slug&gt;-&amp;#x3C;mid8&gt;&lt;/code&gt;, recorded as &lt;code dir=&quot;auto&quot;&gt;mission_branch&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; and checked out in the write checkout. Before the landing it holds the Mission’s &lt;a href=&quot;/context/orchestration/#primary-partition&quot;&gt;PRIMARY partition&lt;/a&gt; artifacts (spec, plan, work package outlines): the placement seam resolves the PRIMARY partition to &lt;code dir=&quot;auto&quot;&gt;meta.mission_branch&lt;/code&gt; until &lt;code dir=&quot;auto&quot;&gt;consolidate&lt;/code&gt; records the landing, and to &lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt; after it. A Mission that stays &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt; lands it like any &lt;a href=&quot;#mission-branch&quot;&gt;mission branch&lt;/a&gt;. A Mission settled to &lt;code dir=&quot;auto&quot;&gt;lanes_with_coord&lt;/code&gt; 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 &lt;code dir=&quot;auto&quot;&gt;git diff &amp;#x3C;target&gt; &amp;#x3C;branch&gt;&lt;/code&gt;, land them on the target, then run &lt;code dir=&quot;auto&quot;&gt;spec-kitty consolidate --resume&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Context&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Topology&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Status&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;canonical&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Applicable to&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;4.x&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Do NOT use when&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;The Mission has an explicit topology — say &lt;a href=&quot;#mission-branch&quot;&gt;mission branch&lt;/a&gt; or coordination branch. The concept is the branch the work lands on — use &lt;a href=&quot;/context/orchestration/#target-branch&quot;&gt;target branch&lt;/a&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Related terms&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;a href=&quot;#size-default&quot;&gt;size default&lt;/a&gt;, &lt;a href=&quot;#mission-branch&quot;&gt;mission branch&lt;/a&gt;, &lt;a href=&quot;/context/orchestration/#primary-partition&quot;&gt;PRIMARY partition&lt;/a&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;hr&gt;
&lt;h3 id=&quot;write-checkout&quot;&gt;Write checkout&lt;/h3&gt;

































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;&lt;/th&gt;&lt;th&gt;&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Definition&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;The one checkout a &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt; mission writes code and status into: either the &lt;a href=&quot;/context/execution/#repository-root-checkout&quot;&gt;repository root checkout&lt;/a&gt; or a validated owned checkout (ADR 2026-09-03-1). Work packages run in it one at a time, stamped &lt;code dir=&quot;auto&quot;&gt;execution_mode: direct_repo&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt; refuses with &lt;code dir=&quot;auto&quot;&gt;WRITE_CHECKOUT_WRONG_BRANCH&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;WRITE_CHECKOUT_OCCUPIED&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;WRITE_CHECKOUT_DIRTY&lt;/code&gt; (a resume is exempt from the dirty check; the claimed Mission’s own status files and event log, and spec-kitty’s runtime directories &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.spec-kitty/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;kitty-ops/&lt;/code&gt;, never count as dirty). &lt;code dir=&quot;auto&quot;&gt;WRITE_CHECKOUT_OCCUPIED&lt;/code&gt; counts an &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt; 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 &lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; 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 &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt; is caught only by the dirty-checkout refusal.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Context&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Topology&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Status&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;canonical&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Applicable to&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;3.x&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Do NOT use when&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;The mission has code lanes — its work runs in a lane worktree, not a write checkout; use &lt;a href=&quot;#code-lane&quot;&gt;code lane&lt;/a&gt;. The concept is only the operator’s repository-root working copy as opposed to a lane worktree — use &lt;a href=&quot;/context/execution/#repository-root-checkout&quot;&gt;repository root checkout&lt;/a&gt;. Never write “main repo” or “main repository”.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Related terms&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;a href=&quot;#repo-root-lane&quot;&gt;repo-root lane&lt;/a&gt;, &lt;a href=&quot;/context/execution/#repository-root-checkout&quot;&gt;repository root checkout&lt;/a&gt;, &lt;a href=&quot;#mission-branch&quot;&gt;mission branch&lt;/a&gt;, &lt;a href=&quot;#topology&quot;&gt;Topology&lt;/a&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;hr&gt;
&lt;h3 id=&quot;repo-root-lane&quot;&gt;Repo-root lane&lt;/h3&gt;

































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;&lt;/th&gt;&lt;th&gt;&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Definition&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;The single bookkeeping lane of a &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt; mission, keeping the existing lane id &lt;code dir=&quot;auto&quot;&gt;lane-planning&lt;/code&gt;. It always resolves to the &lt;a href=&quot;#write-checkout&quot;&gt;write checkout&lt;/a&gt;, never to a &lt;code dir=&quot;auto&quot;&gt;.worktrees/&lt;/code&gt; path, and has no lane branch. It generalizes the planning lane that every topology already carries for &lt;code dir=&quot;auto&quot;&gt;planning_artifact&lt;/code&gt; work packages.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Context&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Topology&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Status&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;canonical&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Applicable to&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;3.x&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Do NOT use when&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;The lane resolves to a &lt;code dir=&quot;auto&quot;&gt;.worktrees/&lt;/code&gt; lane worktree — use &lt;a href=&quot;#code-lane&quot;&gt;code lane&lt;/a&gt;. Never call a &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt; lane “lane-a”.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Related terms&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;a href=&quot;#write-checkout&quot;&gt;write checkout&lt;/a&gt;, &lt;a href=&quot;#code-lane&quot;&gt;code lane&lt;/a&gt;, &lt;a href=&quot;/context/orchestration/#lane&quot;&gt;Lane&lt;/a&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;hr&gt;
&lt;h3 id=&quot;code-lane&quot;&gt;Code lane&lt;/h3&gt;

































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;&lt;/th&gt;&lt;th&gt;&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Definition&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;A lane that resolves to a &lt;code dir=&quot;auto&quot;&gt;.worktrees/&lt;/code&gt; lane worktree and a lane branch. Only &lt;code dir=&quot;auto&quot;&gt;lanes&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;lanes_with_coord&lt;/code&gt; missions have code lanes. A &lt;a href=&quot;#repo-root-lane&quot;&gt;repo-root lane&lt;/a&gt; is never a code lane. A &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt; mission whose &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; holds a code lane is unmigrated and fails closed with &lt;code dir=&quot;auto&quot;&gt;SINGLE_BRANCH_CODE_LANES_UNMIGRATED&lt;/code&gt;; the remedy is &lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate backfill-topology --restamp-single-branch&lt;/code&gt; (always works), or &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; (its re-stamp migration can be a no-op where it is already recorded).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Context&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Topology&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Status&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;canonical&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Applicable to&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;3.x&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Do NOT use when&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;The lane is the &lt;code dir=&quot;auto&quot;&gt;lane-planning&lt;/code&gt; bookkeeping lane — use &lt;a href=&quot;#repo-root-lane&quot;&gt;repo-root lane&lt;/a&gt;. The concept is lane consolidation into the mission branch — use &lt;a href=&quot;/context/orchestration/#lane-consolidation&quot;&gt;Lane Consolidation&lt;/a&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Related terms&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;a href=&quot;#repo-root-lane&quot;&gt;repo-root lane&lt;/a&gt;, &lt;a href=&quot;#lane-work-tip&quot;&gt;lane work tip&lt;/a&gt;, &lt;a href=&quot;/context/orchestration/#lane&quot;&gt;Lane&lt;/a&gt;, &lt;a href=&quot;#topology&quot;&gt;Topology&lt;/a&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;hr&gt;
&lt;h3 id=&quot;protected-target&quot;&gt;Protected target&lt;/h3&gt;

































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;&lt;/th&gt;&lt;th&gt;&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Definition&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;A target branch that is the repository’s &lt;a href=&quot;/context/orchestration/#primary-branch&quot;&gt;primary branch&lt;/a&gt;, or one that &lt;code dir=&quot;auto&quot;&gt;ProtectionPolicy&lt;/code&gt; reports as protected. Both cases are answered by one query, &lt;code dir=&quot;auto&quot;&gt;ProtectionPolicy.is_protected_target&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/git/protection_policy.py&lt;/code&gt;); no forge API is consulted. A &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt; mission targeting a protected target gets a &lt;a href=&quot;#mission-branch&quot;&gt;mission branch&lt;/a&gt; at create time unless &lt;code dir=&quot;auto&quot;&gt;--commit-to-target&lt;/code&gt; is passed; that flag (persisted in &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;, decided in &lt;code dir=&quot;auto&quot;&gt;ProtectionPolicy&lt;/code&gt;) un-protects only that mission’s own target for its own writes. An explicit &lt;code dir=&quot;auto&quot;&gt;lanes&lt;/code&gt; create (no Mission or coordination branch) on a target the status-write guard protects (&lt;code dir=&quot;auto&quot;&gt;ProtectionPolicy.is_protected&lt;/code&gt;) is refused before any write with &lt;code dir=&quot;auto&quot;&gt;LANES_PROTECTED_TARGET_REFUSED&lt;/code&gt;; use an unprotected target or &lt;code dir=&quot;auto&quot;&gt;--topology lanes_with_coord&lt;/code&gt; (#7632).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Context&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Topology&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Status&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;canonical&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Applicable to&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;3.x&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Do NOT use when&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;The concept is only the repository’s default integration branch — use &lt;a href=&quot;/context/orchestration/#primary-branch&quot;&gt;primary branch&lt;/a&gt;. The concept is the branch a mission’s code must land on regardless of protection — use &lt;a href=&quot;/context/orchestration/#target-branch&quot;&gt;target branch&lt;/a&gt;. Never use &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; as a generic name for a protected target.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Related terms&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;a href=&quot;#mission-branch&quot;&gt;mission branch&lt;/a&gt;, &lt;a href=&quot;/context/orchestration/#primary-branch&quot;&gt;primary branch&lt;/a&gt;, &lt;a href=&quot;/context/orchestration/#target-branch&quot;&gt;target branch&lt;/a&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;hr&gt;
&lt;h3 id=&quot;mission-branch&quot;&gt;Mission branch&lt;/h3&gt;

































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;&lt;/th&gt;&lt;th&gt;&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Definition&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;kitty/mission-&amp;#x3C;slug&gt;-&amp;#x3C;mid8&gt;&lt;/code&gt;. For a &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt; mission it is minted and checked out in the &lt;a href=&quot;#write-checkout&quot;&gt;write checkout&lt;/a&gt;, and recorded as &lt;code dir=&quot;auto&quot;&gt;mission_branch&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;, only when the mission targets a &lt;a href=&quot;#protected-target&quot;&gt;protected target&lt;/a&gt; without &lt;code dir=&quot;auto&quot;&gt;--commit-to-target&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;spec-kitty consolidate&lt;/code&gt; 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 (&lt;code dir=&quot;auto&quot;&gt;mission_branch_name&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;coordination_branch_name&lt;/code&gt; give one name). A default Mission’s mission branch is its &lt;a href=&quot;#topic-branch&quot;&gt;topic branch&lt;/a&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Context&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Topology&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Status&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;canonical&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Applicable to&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;3.x&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Do NOT use when&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;The concept is the branch a mission’s code must ultimately land on — use &lt;a href=&quot;/context/orchestration/#target-branch&quot;&gt;target branch&lt;/a&gt;. The concept is the coordination branch — say “coord branch”. The concept is a single lane’s branch — use &lt;a href=&quot;#code-lane&quot;&gt;code lane&lt;/a&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Related terms&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;a href=&quot;#topic-branch&quot;&gt;topic branch&lt;/a&gt;, &lt;a href=&quot;#protected-target&quot;&gt;protected target&lt;/a&gt;, &lt;a href=&quot;#write-checkout&quot;&gt;write checkout&lt;/a&gt;, &lt;a href=&quot;/context/orchestration/#lane-consolidation&quot;&gt;Lane Consolidation&lt;/a&gt;, &lt;a href=&quot;/context/orchestration/#target-branch&quot;&gt;target branch&lt;/a&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;hr&gt;
&lt;h3 id=&quot;lane-work-tip&quot;&gt;Lane work tip&lt;/h3&gt;

































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;&lt;/th&gt;&lt;th&gt;&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Definition&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;The last commit made on a lane branch, recorded when the commit happens, independent of any spec-kitty command. It is stored in &lt;code dir=&quot;auto&quot;&gt;refs/spec-kitty/lane-tip/&amp;#x3C;branch&gt;&lt;/code&gt;, written by a POSIX &lt;code dir=&quot;auto&quot;&gt;post-commit&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;post-rewrite&lt;/code&gt; hook when the recorder is installed (migration &lt;code dir=&quot;auto&quot;&gt;4_0_0rc5_install_lane_tip_recorder&lt;/code&gt;; a foreign hook is left untouched; the hooks are skipped with a warning when &lt;code dir=&quot;auto&quot;&gt;core.hooksPath&lt;/code&gt; comes from global or system git config, is &lt;code dir=&quot;auto&quot;&gt;/dev/null&lt;/code&gt;, missing, or inside the working tree), plus spec-kitty’s own record points (&lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; transitions, crash recovery, auto-rebase; &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/lanes/lane_tip.py&lt;/code&gt;). It is distinct from the lane’s creation base. A destroyed lane with unabsorbed work is refused with &lt;code dir=&quot;auto&quot;&gt;DESTROYED_LANE&lt;/code&gt;, which names the SHA and the restore command &lt;code dir=&quot;auto&quot;&gt;git branch &amp;#x3C;b&gt; refs/spec-kitty/lane-tip/&amp;#x3C;b&gt;&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;LANE_WORK_TIP_UNKNOWN&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;LaneWorkTipUnknownError&lt;/code&gt;) fires when a lane’s branch was deleted before any work tip was recorded, or after its &lt;code dir=&quot;auto&quot;&gt;refs/spec-kitty/lane-tip/&amp;#x3C;branch&gt;&lt;/code&gt; 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 (&lt;code dir=&quot;auto&quot;&gt;git reflog &amp;#x3C;branch&gt;&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;git fsck --lost-found&lt;/code&gt;); if you find one, record it with &lt;code dir=&quot;auto&quot;&gt;git update-ref refs/spec-kitty/lane-tip/&amp;#x3C;branch&gt; &amp;#x3C;sha&gt;&lt;/code&gt; and re-run &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt;; if you are sure no work was ever committed, run &lt;code dir=&quot;auto&quot;&gt;spec-kitty context cleanup&lt;/code&gt; to clear the stale workspace record and retry. Abandoning a destroyed lane (&lt;code dir=&quot;auto&quot;&gt;DESTROYED_LANE&lt;/code&gt;) is two steps today: &lt;code dir=&quot;auto&quot;&gt;git update-ref -d refs/spec-kitty/lane-tip/&amp;#x3C;branch&gt;&lt;/code&gt;, then &lt;code dir=&quot;auto&quot;&gt;spec-kitty context cleanup&lt;/code&gt;. Squash-absorption detection needs git &gt;= 2.38 (&lt;code dir=&quot;auto&quot;&gt;git merge-tree --write-tree&lt;/code&gt;); on older git the guard fails closed and refuses even a genuinely squash-merged lane.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Context&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Topology&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Status&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;canonical&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Applicable to&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;3.x&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Do NOT use when&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;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.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Related terms&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;a href=&quot;#absorbed-lane&quot;&gt;absorbed lane&lt;/a&gt;, &lt;a href=&quot;#code-lane&quot;&gt;code lane&lt;/a&gt;, &lt;a href=&quot;/context/orchestration/#lane&quot;&gt;Lane&lt;/a&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;hr&gt;
&lt;h3 id=&quot;absorbed-lane&quot;&gt;Absorbed lane&lt;/h3&gt;

































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;&lt;/th&gt;&lt;th&gt;&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Definition&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;A lane whose &lt;a href=&quot;#lane-work-tip&quot;&gt;work tip&lt;/a&gt; is an ancestor of the target, equals the lane’s base (&lt;code dir=&quot;auto&quot;&gt;tip == base&lt;/code&gt;, 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 &gt;= 2.38; if git cannot evaluate absorption (including any older git) the check fails closed and the lane is not treated as absorbed.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Context&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Topology&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Status&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;canonical&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Applicable to&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;3.x&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Do NOT use when&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;The concept is one of the three “merge” operations — use &lt;a href=&quot;/context/orchestration/#lane-consolidation&quot;&gt;Lane Consolidation&lt;/a&gt;, &lt;a href=&quot;/context/orchestration/#branch-integration--git-merge&quot;&gt;Branch Integration / Git Merge&lt;/a&gt; or &lt;a href=&quot;/context/orchestration/#publish-to-originmain&quot;&gt;Publish to origin/main&lt;/a&gt;. Never write bare “merged” for an absorbed lane.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Related terms&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;a href=&quot;#lane-work-tip&quot;&gt;lane work tip&lt;/a&gt;, &lt;a href=&quot;/context/orchestration/#lane-consolidation&quot;&gt;Lane Consolidation&lt;/a&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;hr&gt;
&lt;h3 id=&quot;execution-mode-stamp&quot;&gt;Execution-mode stamp&lt;/h3&gt;

































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;&lt;/th&gt;&lt;th&gt;&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Definition&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;The &lt;code dir=&quot;auto&quot;&gt;execution_mode&lt;/code&gt; recorded on status events: &lt;code dir=&quot;auto&quot;&gt;worktree&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;direct_repo&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;direct_repo&lt;/code&gt; is stamped for every work package that runs in a &lt;a href=&quot;#write-checkout&quot;&gt;write checkout&lt;/a&gt;, and also for &lt;code dir=&quot;auto&quot;&gt;planning_artifact&lt;/code&gt; work packages of every topology, because they resolve to the repo-root lane. It is &lt;strong&gt;not&lt;/strong&gt; the work-product kind (&lt;code dir=&quot;auto&quot;&gt;code_change&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;planning_artifact&lt;/code&gt;), which older code and work-package frontmatter also call &lt;code dir=&quot;auto&quot;&gt;execution_mode&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Context&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Topology&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Status&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;canonical&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Applicable to&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;3.x&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Do NOT use when&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;The concept is whether a work package produces code or planning artifacts — say “work-product kind” (&lt;code dir=&quot;auto&quot;&gt;code_change&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;planning_artifact&lt;/code&gt;). Never write bare “execution_mode” when the kind is meant.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Related terms&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;a href=&quot;#write-checkout&quot;&gt;write checkout&lt;/a&gt;, &lt;a href=&quot;/context/orchestration/#work-package&quot;&gt;work package&lt;/a&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;hr&gt;
&lt;h3 id=&quot;started-work-package&quot;&gt;Started work package&lt;/h3&gt;

































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;&lt;/th&gt;&lt;th&gt;&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Definition&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;A work package whose status history has ever recorded a move into a working status lane: &lt;code dir=&quot;auto&quot;&gt;claimed&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt;, including forced moves and &lt;code dir=&quot;auto&quot;&gt;blocked → in_progress&lt;/code&gt; moves that skip &lt;code dir=&quot;auto&quot;&gt;claimed&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;started_wp_ids&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/lanes/frozen_membership.py&lt;/code&gt;). Being reset to &lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt;, or canceled, afterwards does not make it unstarted. A move from &lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt; straight to &lt;code dir=&quot;auto&quot;&gt;blocked&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;canceled&lt;/code&gt; does not start it. On a re-finalize, a prior &lt;a href=&quot;#code-lane&quot;&gt;code lane&lt;/a&gt; with no such work package but a recorded &lt;a href=&quot;#lane-work-tip&quot;&gt;lane work tip&lt;/a&gt; counts as wholly started. A started work package keeps its recorded execution lane when &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; is re-run; see &lt;a href=&quot;/architecture/execution-lanes/#re-finalizing-an-active-mission&quot;&gt;Execution Lanes&lt;/a&gt; and ADR &lt;a href=&quot;/adr/4.x/2026-10-04-2-started-work-package-lane-membership-is-frozen/&quot;&gt;4.x &lt;code dir=&quot;auto&quot;&gt;2026-10-04-2&lt;/code&gt;&lt;/a&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Context&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Topology&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Status&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;canonical&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Applicable to&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;4.x&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Do NOT use when&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;The concept is the work package’s current status lane — name the lane (&lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt;, …). “Started” is not a synonym of &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt;: a &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt;, canceled or reset work package can be started. The concept is the planning-pin question “has execution begun?” (any work package currently past &lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;blocked&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;canceled&lt;/code&gt; included) — that is a different predicate. Avoid “active WP” or “in-flight WP”, which are ambiguous about resets.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Related terms&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;a href=&quot;#lane_membership_frozen&quot;&gt;LANE_MEMBERSHIP_FROZEN&lt;/a&gt;, &lt;a href=&quot;#lane-work-tip&quot;&gt;lane work tip&lt;/a&gt;, &lt;a href=&quot;#code-lane&quot;&gt;code lane&lt;/a&gt;, &lt;a href=&quot;/context/orchestration/#work-package&quot;&gt;work package&lt;/a&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;hr&gt;
&lt;h3 id=&quot;lane_membership_frozen&quot;&gt;LANE_MEMBERSHIP_FROZEN&lt;/h3&gt;

































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;&lt;/th&gt;&lt;th&gt;&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Definition&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;The error code (&lt;code dir=&quot;auto&quot;&gt;LaneMembershipFrozenError&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/lanes/compute.py&lt;/code&gt;) with which &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent mission finalize-tasks&lt;/code&gt; refuses a re-finalize that cannot keep every &lt;a href=&quot;#started-work-package&quot;&gt;started work package&lt;/a&gt; on its recorded execution lane. Its &lt;code dir=&quot;auto&quot;&gt;reason&lt;/code&gt; is one of &lt;code dir=&quot;auto&quot;&gt;started_lanes_collapsed&lt;/code&gt; (started work packages from two execution lanes would share one), &lt;code dir=&quot;auto&quot;&gt;started_wp_removed&lt;/code&gt; (a started work package’s task file was removed without canceling it), &lt;code dir=&quot;auto&quot;&gt;started_wp_kind_changed&lt;/code&gt; (its &lt;code dir=&quot;auto&quot;&gt;execution_mode&lt;/code&gt; would move it across &lt;code dir=&quot;auto&quot;&gt;lane-planning&lt;/code&gt;) or &lt;code dir=&quot;auto&quot;&gt;status_unreadable&lt;/code&gt; (a &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; exists but the status surface or log cannot be read). It is raised by a read-only preflight before the first status write, &lt;code dir=&quot;auto&quot;&gt;--validate-only&lt;/code&gt; included, and exits 1 with no status event, &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; 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 &lt;a href=&quot;/api/finalize-tasks-internals/#5-started-work-packages-keep-their-lane-lane_membership_frozen&quot;&gt;finalize-tasks internals §5&lt;/a&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Context&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Topology&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Status&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;canonical&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Applicable to&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;4.x&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Do NOT use when&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;The failure is &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt; refusing a lane whose branch or work tip is gone — use &lt;code dir=&quot;auto&quot;&gt;LANE_WORK_TIP_UNKNOWN&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;DESTROYED_LANE&lt;/code&gt; (&lt;a href=&quot;#lane-work-tip&quot;&gt;lane work tip&lt;/a&gt;). The failure is a cyclic lane graph — that is &lt;code dir=&quot;auto&quot;&gt;LANE_DEPENDENCY_CYCLE&lt;/code&gt;. Never answer it by deleting &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;, forcing, or resetting git; the remedies keep the recorded lanes.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Related terms&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;a href=&quot;#started-work-package&quot;&gt;started work package&lt;/a&gt;, &lt;a href=&quot;#code-lane&quot;&gt;code lane&lt;/a&gt;, &lt;a href=&quot;#repo-root-lane&quot;&gt;repo-root lane&lt;/a&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;</content>
</entry>
