<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/api/finalize-tasks-internals/">
  <id>https://docs.spec-kitty.ai/api/finalize-tasks-internals/</id>
  <title>finalize-tasks internals reference</title>
  <updated>2026-10-13T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/api/finalize-tasks-internals/"/>
  <summary>finalize-tasks internals: empty owned_files, lane-depth cycle safety, the planning-pin refresh (override and automatic), and the LANE_MEMBERSHIP_FROZEN refusal.</summary>
  <content type="html">&lt;span id=&quot;finalize-tasks-internals-reference&quot;&gt;&lt;/span&gt;
&lt;p&gt;Six non-obvious behaviours an operator may encounter when running
&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent mission finalize-tasks&lt;/code&gt;. All have regression tests
under &lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/cli/commands/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/lanes/&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;1-explicit-empty-owned_files&quot;&gt;1. Explicit empty &lt;code dir=&quot;auto&quot;&gt;owned_files&lt;/code&gt;&lt;/h2&gt;
&lt;p&gt;The finalize-tasks linter normally infers &lt;code dir=&quot;auto&quot;&gt;owned_files&lt;/code&gt; from path-like
strings in the WP body. This is helpful when the author never set the
field. It surprises an operator who EXPLICITLY set &lt;code dir=&quot;auto&quot;&gt;owned_files: []&lt;/code&gt;
because the WP is a triage / planning-artifact / acceptance task that
owns no source or test files.&lt;/p&gt;
&lt;p&gt;The fix at commit &lt;code dir=&quot;auto&quot;&gt;0f4e1a383&lt;/code&gt; adds a pre-check: when the frontmatter
contains the literal pattern &lt;code dir=&quot;auto&quot;&gt;^owned_files:\s*\[\s*\]\s*$&lt;/code&gt;, inference
is skipped for that field. Authors who legitimately own no files write:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;yaml&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;---&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;work_package_id&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;WP01&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;execution_mode&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;planning_artifact&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;owned_files&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: []&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;authoritative_surface&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;docs/triage/&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;---&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;The ownership validator still rejects this if the WP is marked
&lt;code dir=&quot;auto&quot;&gt;execution_mode: code_change&lt;/code&gt; (a code-change WP that owns no files is
suspicious by definition).&lt;/p&gt;
&lt;h2 id=&quot;2-lane-depth-cycle-safety&quot;&gt;2. Lane-depth cycle safety&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;_compute_lane_depths&lt;/code&gt; walks the lane-dependency DAG and assigns each
lane a depth (parallel group). The original implementation recursed
without cycle detection: any self-loop or cycle in &lt;code dir=&quot;auto&quot;&gt;lane_deps&lt;/code&gt; blew the
recursion stack with &lt;code dir=&quot;auto&quot;&gt;maximum recursion depth exceeded&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;The fix at commit &lt;code dir=&quot;auto&quot;&gt;72ff0d723&lt;/code&gt; adds an &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt; guard and a
self-reference filter. Cycle detection is best-effort:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;A lane currently being computed is treated as depth-0 when
re-encountered (breakpoint).&lt;/li&gt;
&lt;li&gt;Self-references in &lt;code dir=&quot;auto&quot;&gt;lane_deps&lt;/code&gt; are filtered before the recursion.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;For a clean DAG (the common case) output is unchanged. For a cyclic
graph, the function returns a dict with each lane present and an
integer depth — but the depth value may not reflect graph reality. The
proper fix for a cyclic lane graph is to validate the inputs upstream
(in the WP-dependency parser), not to “solve” the cycle in the depth
function.&lt;/p&gt;
&lt;p&gt;Both fixes are locked by tests in:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/cli/commands/test_finalize_tasks_explicit_empty_owned_files.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/lanes/test_compute_lane_depths_cycle_safety.py&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Removing those tests, or weakening their assertions to permit recursion,
is a regression.&lt;/p&gt;
&lt;h2 id=&quot;3-refreshing-the-recorded-planning-commit-after-an-amendment-4141&quot;&gt;3. Refreshing the recorded planning commit after an amendment (#4141)&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; freezes &lt;code dir=&quot;auto&quot;&gt;planning_commit_sha&lt;/code&gt; into &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; at first
run. Once execution has begun (any WP past &lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt;), a re-finalize
PRESERVES that recorded SHA (#3311) — correct for an ownership-only
amendment, which must not silently clobber established planning provenance.
But preserve-only left no sanctioned way to advance the SHA after a
legitimate planning amendment (a WP dependency-field fix, an &lt;code dir=&quot;auto&quot;&gt;/spec-kitty .analyze&lt;/code&gt; remediation) landed mid-execution: every subsequently allocated
lane kept merging the stale planning snapshot, the &lt;code dir=&quot;auto&quot;&gt;move-task&lt;/code&gt; gates
(branch-currency / &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; contamination / uncommitted-changes) fired
on the resulting drift, and the only in-tool path was &lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt; on every
transition.&lt;/p&gt;
&lt;p&gt;The fix adds an explicit, advance-only override:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;mission&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;finalize-tasks&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--mission&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;slug&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--refresh-planning-commit&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;With execution begun, the recorded SHA is re-pointed to the current
target-branch tip, so lanes merge the amended planning state at their next
allocation/reuse.&lt;/li&gt;
&lt;li&gt;The override is refused (exit 1, &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; untouched) when the recorded
SHA is not an &lt;em&gt;ancestor&lt;/em&gt; of the tip — a history rewrite or a foreign
provenance SHA, not an amendment. Resolve the divergence manually instead.&lt;/li&gt;
&lt;li&gt;Without the flag, the #3311 preserve behavior is unchanged, but a
re-finalize that detects drift (recorded SHA ≠ branch tip) now warns on
the console and names the flag; the &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; success payload carries the
decision structurally under &lt;code dir=&quot;auto&quot;&gt;planning_commit&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;action&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;sha&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;previous_sha&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;branch_tip&lt;/code&gt;).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Locked by tests in:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/cli/commands/agent/test_issue_4141_refresh_planning_commit.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/cli/commands/agent/test_mission_finalize_phases.py&lt;/code&gt; (the
&lt;code dir=&quot;auto&quot;&gt;_preserve_or_capture_planning_commit_sha&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;_report_planning_sha_decision&lt;/code&gt;
branch tests)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Weakening the ancestor refusal, or making the refresh the default (no flag),
is a regression.&lt;/p&gt;
&lt;h2 id=&quot;4-automatic-planning-pin-refresh-and-planning_commit_refresh&quot;&gt;4. Automatic planning-pin refresh and &lt;code dir=&quot;auto&quot;&gt;planning_commit_refresh&lt;/code&gt;&lt;/h2&gt;
&lt;p&gt;Without &lt;code dir=&quot;auto&quot;&gt;--refresh-planning-commit&lt;/code&gt;, a re-finalize after execution has begun no longer only
preserves the recorded pin. It classifies the recorded &lt;code dir=&quot;auto&quot;&gt;planning_commit_sha&lt;/code&gt; against the
target-branch tip (&lt;code dir=&quot;auto&quot;&gt;PinClass&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/lanes/planning_commit_classify.py&lt;/code&gt;) and
acts on the class:&lt;/p&gt;






























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Pin class&lt;/th&gt;&lt;th&gt;Meaning&lt;/th&gt;&lt;th&gt;Result (exit code)&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;ADVANCED&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The recorded object is present and an ancestor of the tip&lt;/td&gt;&lt;td&gt;Refreshed to the tip &lt;strong&gt;only when&lt;/strong&gt; a PRIMARY planning file changed since the pin for a reason other than finalize’s own earlier bookkeeping commits; otherwise preserved (0)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;ORPHANED&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Present but not an ancestor (a mid-Mission rebase, #4827)&lt;/td&gt;&lt;td&gt;Fails closed before any write; &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; untouched; use &lt;code dir=&quot;auto&quot;&gt;--refresh-planning-commit --allow-orphaned&lt;/code&gt; (1)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;FOREIGN&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The recorded object is absent from this repository&lt;/td&gt;&lt;td&gt;Kept, with a visible warning when the tip has advanced (0)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;INDETERMINATE&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Nothing can be inspected (tip not capturable, or no recorded SHA)&lt;/td&gt;&lt;td&gt;With no recorded SHA and a capturable tip: derived from git, the target-branch commit before the Mission’s &lt;code dir=&quot;auto&quot;&gt;tasks/WP*.md&lt;/code&gt; first appeared on its first-parent line, reported as &lt;code dir=&quot;auto&quot;&gt;derived&lt;/code&gt; (#7210). Otherwise kept, with a visible warning and reason &lt;code dir=&quot;auto&quot;&gt;indeterminate_tip_uncapturable&lt;/code&gt;; never a silent preserve (0)&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; success payload carries the automatic decision in an additive field:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;json&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;planning_commit_refresh&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: {&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;status&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;refreshed&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;recorded&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;&amp;#x3C;previous sha&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;candidate&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;&amp;#x3C;branch tip&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;pin_class&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;advanced&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;reason&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#FF6A83;--1:#A24848&quot;&gt;null&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;}&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;status&lt;/code&gt; is &lt;code dir=&quot;auto&quot;&gt;preserved&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;refreshed&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;derived&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;kept_with_warning&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;reason&lt;/code&gt; is set only for
&lt;code dir=&quot;auto&quot;&gt;kept_with_warning&lt;/code&gt;. The field is &lt;code dir=&quot;auto&quot;&gt;null&lt;/code&gt; before execution begins and for an explicit
&lt;code dir=&quot;auto&quot;&gt;--refresh-planning-commit&lt;/code&gt; run, which keeps reporting through &lt;code dir=&quot;auto&quot;&gt;planning_commit&lt;/code&gt; (section 3).
The explicit flag and its refusals are unchanged. Code: &lt;code dir=&quot;auto&quot;&gt;PlanningCommitResolution&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;_planning_commit_refresh_payload&lt;/code&gt; in
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/agent/mission_finalize_planning_pin.py&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;5-started-work-packages-keep-their-lane-lane_membership_frozen&quot;&gt;5. Started work packages keep their lane (&lt;code dir=&quot;auto&quot;&gt;LANE_MEMBERSHIP_FROZEN&lt;/code&gt;)&lt;/h2&gt;
&lt;p&gt;A re-finalize (any run on a Mission that already has a &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;) keeps every
&lt;a href=&quot;/context/topology/#started-work-package&quot;&gt;started work package&lt;/a&gt; on its recorded
lane, or refuses before its first status write (#5573). Design and rationale: 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;;
the lane-id rule is explained in
&lt;a href=&quot;/architecture/execution-lanes/#re-finalizing-an-active-mission&quot;&gt;Execution Lanes&lt;/a&gt;.&lt;/p&gt;
&lt;h3 id=&quot;where-the-check-runs&quot;&gt;Where the check runs&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;_preflight_frozen_lane_membership&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;mission_finalize_lanes.py&lt;/code&gt;) runs in
&lt;code dir=&quot;auto&quot;&gt;finalize_tasks&lt;/code&gt; after the ownership gates (&lt;code dir=&quot;auto&quot;&gt;_run_finalize_ownership_gates&lt;/code&gt;) and
before the first status write (&lt;code dir=&quot;auto&quot;&gt;_emit_tasks_started&lt;/code&gt;). It is read-only: it builds
the frozen membership and dry-runs &lt;code dir=&quot;auto&quot;&gt;compute_lanes&lt;/code&gt; with it against the previous
&lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;A first finalize (no &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;) reads nothing and constrains nothing.&lt;/li&gt;
&lt;li&gt;A &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt; Mission skips the check: its one repo-root lane has nothing to move.&lt;/li&gt;
&lt;li&gt;A &lt;code dir=&quot;auto&quot;&gt;--refresh-planning-commit&lt;/code&gt; run skips the check: it never recomputes lane membership.&lt;/li&gt;
&lt;li&gt;A lane dependency cycle (&lt;code dir=&quot;auto&quot;&gt;LaneDependencyCycleError&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;LANE_DEPENDENCY_CYCLE&lt;/code&gt;) is
raised here too, with its existing envelope: keeping started lane-mates together can
close a lane cycle that the unfrozen inputs would not have, and the real lane write
would raise it only after the status writes.&lt;/li&gt;
&lt;li&gt;Any other lane-computation failure is left to the real lane write, which reports it
with its existing text.&lt;/li&gt;
&lt;li&gt;The lane writer (&lt;code dir=&quot;auto&quot;&gt;compute_and_write_lanes&lt;/code&gt;) re-checks the invariant with
&lt;code dir=&quot;auto&quot;&gt;assert_frozen_membership_honoured&lt;/code&gt; before it writes &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;. It also raises
&lt;code dir=&quot;auto&quot;&gt;LaneComputationError&lt;/code&gt; when it is asked to recompute over a manifest that has code
lanes with &lt;code dir=&quot;auto&quot;&gt;frozen=None&lt;/code&gt; (no evidence gathered). A caller that means “nothing has
started” passes &lt;code dir=&quot;auto&quot;&gt;FrozenLaneMembership.empty()&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt; and a first finalize
are exempt.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;evidence&quot;&gt;Evidence&lt;/h3&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Evidence&lt;/th&gt;&lt;th&gt;Source&lt;/th&gt;&lt;th&gt;Notes&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Started work packages&lt;/td&gt;&lt;td&gt;The status event log, read from the resolved status surface (&lt;code dir=&quot;auto&quot;&gt;_resolve_status_read_dir&lt;/code&gt;: the placement seam for an owned checkout, otherwise the coordination-aware status surface)&lt;/td&gt;&lt;td&gt;History-based (&lt;code dir=&quot;auto&quot;&gt;started_wp_ids&lt;/code&gt;): any event into &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;. A status directory that exists but holds no event log means nothing started. When the status directory does not exist because the coordination worktree is not materialized (&lt;code dir=&quot;auto&quot;&gt;CoordinationWorktreeUnmaterialized&lt;/code&gt;), the log committed on the local coordination branch is read instead (&lt;code dir=&quot;auto&quot;&gt;_started_on_coordination_branch&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;git ls-tree&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;git cat-file&lt;/code&gt; on &lt;code dir=&quot;auto&quot;&gt;refs/heads/&amp;#x3C;coordination branch&gt;&lt;/code&gt;, parsed with &lt;code dir=&quot;auto&quot;&gt;read_events_from_text&lt;/code&gt;). That read refuses (&lt;code dir=&quot;auto&quot;&gt;status_unreadable&lt;/code&gt;) when the branch is not a local head, carries no committed log, or the log is malformed. Any other missing status directory refuses: an absent surface is not an absent log. Never calls &lt;code dir=&quot;auto&quot;&gt;materialize()&lt;/code&gt; and never materializes the worktree. The read uses the local coordination branch only and never fetches, so a WP started in another clone whose coordination commits were not fetched can look unstarted; the lane-work-tip fallback still freezes a lane with recorded work in this clone. This is an accepted, documented limit.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Lane work tips (fallback)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;recorded_tip_branches&lt;/code&gt;: one &lt;code dir=&quot;auto&quot;&gt;git for-each-ref refs/spec-kitty/lane-tip/&lt;/code&gt; call&lt;/td&gt;&lt;td&gt;Read on every re-finalize. A prior code lane with no history-started member and a recorded tip counts as wholly started. Every lane id of this Mission whose lane branch has a recorded tip stays reserved, including a lane that &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; no longer lists. A listing git cannot produce (&lt;code dir=&quot;auto&quot;&gt;LaneTipListingError&lt;/code&gt;) refuses with &lt;code dir=&quot;auto&quot;&gt;status_unreadable&lt;/code&gt;; it is never read as “no tips”. &lt;code dir=&quot;auto&quot;&gt;lane-planning&lt;/code&gt; is never tip-frozen.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Retired work packages&lt;/td&gt;&lt;td&gt;The cancellation projection (present work packages minus lane inputs)&lt;/td&gt;&lt;td&gt;A missing started work package that was retired is leaving, not moving: no conflict. Its lane id stays reserved for that run through its binding, and on later runs for as long as its lane branch has a recorded tip.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3 id=&quot;--validate-only&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;--validate-only&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;The preflight runs before the validate-only report, so &lt;code dir=&quot;auto&quot;&gt;--validate-only&lt;/code&gt; refuses
in exactly the cases a real run refuses. Its lane preview now passes the previous
&lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; and the frozen membership to &lt;code dir=&quot;auto&quot;&gt;compute_lanes&lt;/code&gt;, so the previewed
&lt;code dir=&quot;auto&quot;&gt;lane_ids&lt;/code&gt; match what a real run writes. Before #5573 the preview minted lane ids
positionally.&lt;/p&gt;
&lt;h3 id=&quot;refusal-envelope&quot;&gt;Refusal envelope&lt;/h3&gt;
&lt;p&gt;Exit code &lt;code dir=&quot;auto&quot;&gt;1&lt;/code&gt;. No status event, no &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; and no commit is written. The ownership
gates run before the preflight and may already have edited work package files and
&lt;code dir=&quot;auto&quot;&gt;tasks.md&lt;/code&gt;; finalize’s write-scope restore puts those and &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; back byte-identical. With &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt;:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;json&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;{&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;error&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;Cannot re-finalize: started work packages would change lane. WP01 (lane-a) and WP02 (lane-b) would be merged into one lane.&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;error_code&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;LANE_MEMBERSHIP_FROZEN&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;reason&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;started_lanes_collapsed&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;conflicts&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: [&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;{&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;      &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;reason&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;started_lanes_collapsed&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;      &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;wp_ids&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: [&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;WP01&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;, &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;WP02&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;],&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;      &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;recorded_lanes&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: [&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;lane-a&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;, &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;lane-b&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;],&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;      &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;remedy&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;Remove the overlap that forces WP01 and WP02 into one lane (for example, move the shared path into a new work package that depends on them, or drop it from one of them), then re-run finalize-tasks.&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;}&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;],&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;next_step&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;Remove the overlap that forces WP01 and WP02 into one lane (...), then re-run finalize-tasks.&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;spec_kitty_version&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;...&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;}&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;Always present: &lt;code dir=&quot;auto&quot;&gt;error&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;error_code&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;reason&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;conflicts&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;next_step&lt;/code&gt;,
plus the standard &lt;code dir=&quot;auto&quot;&gt;spec_kitty_version&lt;/code&gt;. Finalize’s existing extra keys may also
appear when they apply: &lt;code dir=&quot;auto&quot;&gt;target_branch_override_revert_error&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;status_commits_not_undone&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;stale_repository_root_copy&lt;/code&gt; (owned checkouts).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;conflicts&lt;/code&gt; lists every conflict found. Each has &lt;code dir=&quot;auto&quot;&gt;reason&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;wp_ids&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;recorded_lanes&lt;/code&gt; (both sorted) and &lt;code dir=&quot;auto&quot;&gt;remedy&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;reason&lt;/code&gt; is the first conflict reason in the order &lt;code dir=&quot;auto&quot;&gt;started_lanes_collapsed&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;started_wp_removed&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;started_wp_kind_changed&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;status_unreadable&lt;/code&gt;.
&lt;code dir=&quot;auto&quot;&gt;next_step&lt;/code&gt; lists the distinct remedies, one per line, in the same order.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Without &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; the console prints the error, then one line per conflict and its
remedy:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;text&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;Error: Cannot re-finalize: started work packages would change lane. WP01 (lane-a) and WP02 (lane-b) would be merged into one lane.&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;started_lanes_collapsed: WP01 (lane-a), WP02 (lane-b)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;Remedy: Remove the overlap that forces WP01 and WP02 into one lane (...), then re-run finalize-tasks.&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;reasons-and-remedies&quot;&gt;Reasons and remedies&lt;/h3&gt;
&lt;p&gt;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;); conflicts and
remedy texts: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/lanes/frozen_membership.py&lt;/code&gt;.&lt;/p&gt;



































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;&lt;code dir=&quot;auto&quot;&gt;reason&lt;/code&gt;&lt;/th&gt;&lt;th&gt;Trigger&lt;/th&gt;&lt;th&gt;Remedy (as printed)&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;started_lanes_collapsed&lt;/code&gt;&lt;/td&gt;&lt;td&gt;One computed group holds started work packages recorded in two or more lanes&lt;/td&gt;&lt;td&gt;Remove the overlap that forces {WPs} into one lane (for example, move the shared path into a new work package that depends on them, or drop it from one of them), then re-run finalize-tasks.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;started_wp_removed&lt;/code&gt;&lt;/td&gt;&lt;td&gt;A started work package is missing from the plan, and the cancellation projection did not retire it&lt;/td&gt;&lt;td&gt;Restore the task file of {WPs}. To retire a started work package instead, cancel it with &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent tasks move-task &amp;#x3C;WP&gt; --to canceled --mission &amp;#x3C;handle&gt;&lt;/code&gt; without clearing its owned files, then re-run finalize-tasks.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;started_wp_kind_changed&lt;/code&gt;&lt;/td&gt;&lt;td&gt;A started work package’s &lt;code dir=&quot;auto&quot;&gt;execution_mode&lt;/code&gt; now puts it on the other side of &lt;code dir=&quot;auto&quot;&gt;lane-planning&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Restore the &lt;code dir=&quot;auto&quot;&gt;execution_mode&lt;/code&gt; of {WPs}, put the new kind of work in a new work package, then re-run finalize-tasks.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;status_unreadable&lt;/code&gt;&lt;/td&gt;&lt;td&gt;A &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; exists, the coordination worktree of a &lt;code dir=&quot;auto&quot;&gt;lanes_with_coord&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;coord&lt;/code&gt; Mission is not materialized (&lt;code dir=&quot;auto&quot;&gt;CoordinationWorktreeUnmaterialized&lt;/code&gt;), and its committed status log cannot be read because the coordination branch is not a local head (for example it exists only on a remote)&lt;/td&gt;&lt;td&gt;Materialize the coordination worktree, then re-run finalize-tasks. {next step} — the canonical &lt;code dir=&quot;auto&quot;&gt;CoordinationWorktreeUnmaterialized&lt;/code&gt; guidance: run &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor coordination --mission &amp;#x3C;slug&gt; --fix&lt;/code&gt; (if that command cannot, materialize it manually with &lt;code dir=&quot;auto&quot;&gt;git -C &amp;#x3C;repo&gt; worktree add &amp;#x3C;coordination worktree&gt; &amp;#x3C;coordination branch&gt;&lt;/code&gt;); when the coordination branch exists only on a remote, it first says to run &lt;code dir=&quot;auto&quot;&gt;git fetch origin &amp;#x3C;coordination branch&gt;&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;status_unreadable&lt;/code&gt;&lt;/td&gt;&lt;td&gt;A &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; exists, but the preflight cannot resolve the status surface, the status directory is missing for another reason, the local coordination branch carries no committed status log, or the event log cannot be read&lt;/td&gt;&lt;td&gt;Repair the status log (&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent status validate --mission &amp;#x3C;handle&gt;&lt;/code&gt; reports the problem; &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent status doctor&lt;/code&gt; checks status hygiene), then re-run finalize-tasks. Cause: {the error’s message, plus its next step when the message does not already carry it}&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;No remedy suggests deleting &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;, a force flag, &lt;code dir=&quot;auto&quot;&gt;git reset&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;git restore&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;git checkout -- .&lt;/code&gt;, or removing worktrees or branches.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;status_unreadable&lt;/code&gt; in practice: a malformed line in the status log that finalize’s
work-package read already uses (&lt;code dir=&quot;auto&quot;&gt;read_wp_frontmatter&lt;/code&gt;) is refused earlier, by that read,
with its existing store error (&lt;code dir=&quot;auto&quot;&gt;Invalid JSON on line N: ...&lt;/code&gt;). The preflight’s own
&lt;code dir=&quot;auto&quot;&gt;status_unreadable&lt;/code&gt; appears when its separate read fails: the coordination status
surface of a coordination Mission cannot be resolved (for example a deleted
coordination branch), the coordination worktree is not materialized and its branch is
not a local head, the committed log is missing or malformed, or the log cannot be
read. Each &lt;code dir=&quot;auto&quot;&gt;status_unreadable&lt;/code&gt; remedy carries its cause: the remote-only case leads
with materializing the worktree (after fetching the branch), an unreadable lane-tip
listing leads with fixing the git error, and every other case appends &lt;code dir=&quot;auto&quot;&gt;Cause:&lt;/code&gt; and
the underlying message. Its message reads &lt;code dir=&quot;auto&quot;&gt;Cannot re-finalize: the status log or the recorded lane work tips cannot be read, so started work cannot be determined.&lt;/code&gt;: it
does not claim that a lane would change. Code: &lt;code dir=&quot;auto&quot;&gt;_read_started_wp_ids&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;_started_on_coordination_branch&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;_status_unreadable_error&lt;/code&gt; in
&lt;code dir=&quot;auto&quot;&gt;mission_finalize_lanes.py&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;not-the-planning-pin-probe&quot;&gt;Not the planning-pin probe&lt;/h3&gt;
&lt;p&gt;The planning-pin preservation (section 3, #3311) asks “has execution begun?” through
&lt;code dir=&quot;auto&quot;&gt;_execution_has_begun&lt;/code&gt;: it is true when any work package’s &lt;em&gt;current&lt;/em&gt; lane is not
&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), and it degrades to “not begun” when the
status surface or log cannot be read. The started-work-package predicate asks which
work packages have &lt;em&gt;ever&lt;/em&gt; entered a working lane, and fails closed. The two answer
different questions and can disagree: a work package reset to &lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt; is still
started, while a work package moved 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; makes
execution “begun” for the pin without being started. Moving the pin probe onto the
history-based predicate is Follow-up: #5702.&lt;/p&gt;
&lt;p&gt;Locked by tests in:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/lanes/test_frozen_lane_membership.py&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;tests/lanes/test_frozen_lane_membership_sweep.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/cli/commands/agent/test_finalize_frozen_lane_preflight.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/integration/test_refinalize_keeps_started_lanes.py&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;tests/integration/test_refinalize_frozen_lane_refusals.py&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;6-stale-api-authored-content-is-refused&quot;&gt;6. Stale API-authored content is refused&lt;/h2&gt;
&lt;p&gt;A Mission authored through &lt;code dir=&quot;auto&quot;&gt;spec-kitty orchestrator-api&lt;/code&gt; carries an API-authoring
marker. For such a Mission, &lt;code dir=&quot;auto&quot;&gt;agent mission finalize-tasks&lt;/code&gt; first checks that the
specification, plan and work-package content is current and complete, exactly as
the orchestrator-api &lt;code dir=&quot;auto&quot;&gt;tasks&lt;/code&gt; verb does. Stale or unfinished content refuses with a
&lt;code dir=&quot;auto&quot;&gt;DESIGN_*&lt;/code&gt; code (for example &lt;code dir=&quot;auto&quot;&gt;DESIGN_PARENT_STALE&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;DESIGN_PREREQUISITES_FAILED&lt;/code&gt;)
before anything is written, and a successful finalize records the generated
work-package files as current, so native &lt;code dir=&quot;auto&quot;&gt;spec-kitty next --result success&lt;/code&gt; at
&lt;code dir=&quot;auto&quot;&gt;tasks&lt;/code&gt; then advances. &lt;code dir=&quot;auto&quot;&gt;--validate-only&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;--refresh-planning-commit&lt;/code&gt; skip the
check, an already-finalized Mission is not re-checked, and a Mission without the
marker behaves as before. &lt;code dir=&quot;auto&quot;&gt;agent tasks finalize-tasks&lt;/code&gt; does not run the check.&lt;/p&gt;
&lt;h2 id=&quot;module-map&quot;&gt;Module map&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; is split across sibling modules in
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/agent/&lt;/code&gt; (#5627). &lt;code dir=&quot;auto&quot;&gt;mission_finalize.py&lt;/code&gt; is the
facade: it keeps the command, and every other phase lives in its own module:&lt;/p&gt;









































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Module&lt;/th&gt;&lt;th&gt;Owns&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;mission_finalize.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The &lt;code dir=&quot;auto&quot;&gt;finalize_tasks&lt;/code&gt; command, its context (&lt;code dir=&quot;auto&quot;&gt;_resolve_finalize_context&lt;/code&gt;), the branch-setup phase (&lt;code dir=&quot;auto&quot;&gt;_run_finalize_branch_setup&lt;/code&gt;), the validation-gate and ownership-gate runners, and the helpers &lt;code dir=&quot;auto&quot;&gt;_meta_json_delta_is_finalize_attributable&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;_collect_finalize_artifacts&lt;/code&gt;; re-exports every name below&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;mission_finalize_seams.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Constants, the owned-envelope &lt;code dir=&quot;auto&quot;&gt;ContextVar&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_emit_json&lt;/code&gt; and the &lt;code dir=&quot;auto&quot;&gt;mission&lt;/code&gt;-routed patch seams&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;mission_finalize_branch_contract.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Target-branch resolution, branch-contract persistence, the &lt;code dir=&quot;auto&quot;&gt;--target-branch&lt;/code&gt; override&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;mission_finalize_validation.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Requirement-ID, dependency, requirement-mapping and issue-matrix gates&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;mission_finalize_bootstrap.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The per-WP frontmatter bootstrap loop, ownership gates, lane-input projection, the &lt;code dir=&quot;auto&quot;&gt;--validate-only&lt;/code&gt; report, local canonical status events&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;mission_finalize_planning_pin.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The planning-commit pin: preserve-or-capture, &lt;code dir=&quot;auto&quot;&gt;--refresh-planning-commit&lt;/code&gt; and the automatic refresh&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;mission_finalize_lanes.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Lane computation, the frozen-lane preflight (&lt;code dir=&quot;auto&quot;&gt;_preflight_frozen_lane_membership&lt;/code&gt;, section 5) and the acceptance-matrix scaffold&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;mission_finalize_commit.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The commit pipeline, the success report and the refusal-time rollback guards; wraps the status-surface guard with &lt;code dir=&quot;auto&quot;&gt;_capture_status_surface&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_restore_status_surface&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_restore_mission_write_scope_beside_status&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;_report_status_surface_leftover&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;finalize_status_surface.py&lt;/code&gt; is not a phase module. It owns &lt;code dir=&quot;auto&quot;&gt;StatusSurfaceGuard&lt;/code&gt;
and &lt;code dir=&quot;auto&quot;&gt;StatusSurfaceLeftover&lt;/code&gt;, which &lt;code dir=&quot;auto&quot;&gt;mission_finalize_commit.py&lt;/code&gt; wraps.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;mission_finalize&lt;/code&gt; re-exports every name the phase modules define, so
&lt;code dir=&quot;auto&quot;&gt;mission_finalize.&amp;#x3C;name&gt;&lt;/code&gt; stays importable. How a phase module reaches a name
decides whether a patch on &lt;code dir=&quot;auto&quot;&gt;mission_finalize.&amp;#x3C;name&gt;&lt;/code&gt; intercepts the call. The
module goes through &lt;code dir=&quot;auto&quot;&gt;mission_finalize&lt;/code&gt; at call time with a lazy in-function
import (&lt;code dir=&quot;auto&quot;&gt;_mf.&amp;#x3C;name&gt;&lt;/code&gt;), under three rules:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;A call to a function another finalize module owns always goes through &lt;code dir=&quot;auto&quot;&gt;_mf&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;A call to a name that tests patch on &lt;code dir=&quot;auto&quot;&gt;mission_finalize&lt;/code&gt; goes through &lt;code dir=&quot;auto&quot;&gt;_mf&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Any other call inside a phase module is direct. To intercept it, patch the
phase module that makes the call, not &lt;code dir=&quot;auto&quot;&gt;mission_finalize&lt;/code&gt;.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/cli/commands/agent/test_mission_finalize_phase_modules.py&lt;/code&gt;
pins the re-exports, the lazy import, and both routing rules (patched names and
cross-module functions are never referenced bare in a phase module). When a test
starts patching another name on &lt;code dir=&quot;auto&quot;&gt;mission_finalize&lt;/code&gt;, add it to &lt;code dir=&quot;auto&quot;&gt;_ROUTED_NAMES&lt;/code&gt;
there: the gate does not read the tests, so a newly patched name that a phase
module calls directly would not be intercepted and nothing would fail. Structural pins that read the source use &lt;code dir=&quot;auto&quot;&gt;tests/_support/finalize_source.py&lt;/code&gt;,
which reads the whole module family.&lt;/p&gt;</content>
</entry>
