<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-06-22-1-mission-topology-ssot/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-06-22-1-mission-topology-ssot/</id>
  <title>ADR: MissionTopology SSOT — Store the Mission Shape, Resolve It Once</title>
  <updated>2026-06-22T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-06-22-1-mission-topology-ssot/"/>
  <summary>Stores the coordination-by-lanes mission shape as a `MissionTopology` value minted at creation instead of re-inferring it from disk; `flattened` stays a provenance flag.</summary>
  <content type="html">&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;src/runtime/next/runtime_bridge.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/mission_creation.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/missions/_read_path_resolver.py&lt;/code&gt;
&lt;strong&gt;Design driver&lt;/strong&gt;: &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2069&quot;&gt;#2069&lt;/a&gt;
&lt;strong&gt;Predecessor&lt;/strong&gt;: &lt;a href=&quot;/adr/3.x/2026-06-03-2-executioncontext-owner-and-committarget/&quot;&gt;ADR 2026-06-03-2 — ExecutionContext Owner and CommitTarget&lt;/a&gt;,
&lt;a href=&quot;/adr/3.x/2026-06-19-1-coord-empty-surface-fallback/&quot;&gt;ADR 2026-06-19-1 — Coord-Empty Surface Policy&lt;/a&gt;&lt;/p&gt;
&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;A Spec Kitty mission can take one of four shapes across the orthogonal
&lt;strong&gt;coordination × lanes&lt;/strong&gt; grid: no-coord/no-lanes, no-coord/lanes,
coord/no-lanes, coord/lanes. That shape decides &lt;em&gt;where&lt;/em&gt; a mission’s planning
artifacts and status surface live — the &lt;strong&gt;primary checkout&lt;/strong&gt;
(&lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;slug&gt;[-mid8]/&lt;/code&gt;) versus the &lt;strong&gt;coordination worktree&lt;/strong&gt;
(&lt;code dir=&quot;auto&quot;&gt;.worktrees/&amp;#x3C;slug&gt;-&amp;#x3C;mid8&gt;-coord/...&lt;/code&gt;).&lt;/p&gt;
&lt;p&gt;Today &lt;strong&gt;no shape is a first-class stored value.&lt;/strong&gt; Each consumer re-infers a
slice of it, ad-hoc, from scattered on-disk and git signals:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;CommitTargetKind&lt;/code&gt; is classified &lt;strong&gt;per ref&lt;/strong&gt; at construction time, never read
back as a mission shape.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;coordination_branch is None ⇒ FLATTENED&lt;/code&gt; derivation is hand-rolled in
&lt;strong&gt;two independent places&lt;/strong&gt;: behind the canonical construction door at
&lt;a href=&quot;../../../src/mission_runtime/resolution.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;resolution.py:705-718&lt;/code&gt;&lt;/a&gt;
(&lt;code dir=&quot;auto&quot;&gt;_resolve_coordination_branch&lt;/code&gt;), &lt;strong&gt;and&lt;/strong&gt; a second, parallel disk-&lt;code dir=&quot;auto&quot;&gt;stat&lt;/code&gt;
ladder at &lt;a href=&quot;../../../src/runtime/next/runtime_bridge.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;runtime_bridge.py:144-211&lt;/code&gt;&lt;/a&gt;
(&lt;code dir=&quot;auto&quot;&gt;_mission_declares_coordination_branch&lt;/code&gt; plus a &lt;code dir=&quot;auto&quot;&gt;_coord_path.exists() ⇒ COORDINATION&lt;/code&gt; branch).&lt;/li&gt;
&lt;li&gt;The read path keys on &lt;code dir=&quot;auto&quot;&gt;CoordState.MATERIALIZED&lt;/code&gt; — a disk &lt;code dir=&quot;auto&quot;&gt;stat&lt;/code&gt; of the
&lt;code dir=&quot;auto&quot;&gt;-coord&lt;/code&gt; worktree — in &lt;code dir=&quot;auto&quot;&gt;_read_path_resolver._resolve_existing_for_slug&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;read_lanes_json(...)&lt;/code&gt; re-derives the lanes axis independently.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Because the shape is re-inferred at every seam, the slices &lt;strong&gt;drift&lt;/strong&gt;: an
artifact written through one inference is read back through another. That drift
&lt;strong&gt;is&lt;/strong&gt; the coord/primary read/write desync class —
&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2062&quot;&gt;#2062&lt;/a&gt; (a flattened
mission with a stale &lt;code dir=&quot;auto&quot;&gt;-coord&lt;/code&gt; husk reads the husk and mis-reports a &lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt;
lane), &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2063&quot;&gt;#2063&lt;/a&gt;
(&lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt;/tasks written to one surface, read from another →
“not found” divergence), and
&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2064&quot;&gt;#2064&lt;/a&gt;
(&lt;code dir=&quot;auto&quot;&gt;map-requirements&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; disagree about where WP
&lt;code dir=&quot;auto&quot;&gt;requirement_refs&lt;/code&gt; live).&lt;/p&gt;
&lt;p&gt;Prior fixes in this family were &lt;strong&gt;symptomatic&lt;/strong&gt;: they band-aided one read leg
(e.g. threading a &lt;code dir=&quot;auto&quot;&gt;declares_coordination&lt;/code&gt; signal into the disk-&lt;code dir=&quot;auto&quot;&gt;stat&lt;/code&gt;
heuristic) while leaving the parallel inferences alive. The operator’s binding
principle for this mission: &lt;em&gt;“if storing topology re-opens #2062, that proves
our prior #2062 fix was non-structural.”&lt;/em&gt;&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;Land the &lt;strong&gt;#2069 structural design&lt;/strong&gt;: name the mission shape, &lt;strong&gt;store&lt;/strong&gt; it, and
resolve it once through a pure projection over the single existing construction
door.&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Name the shape.&lt;/strong&gt; Add a mission-level enum
&lt;code dir=&quot;auto&quot;&gt;MissionTopology {SINGLE_BRANCH, LANES, COORD, LANES_WITH_COORD}&lt;/code&gt; in
&lt;code dir=&quot;auto&quot;&gt;mission_runtime/context.py&lt;/code&gt;, naming the coordination × lanes 2×2 grid as one
value. &lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;FLATTENED&lt;/code&gt; is NOT an enum member&lt;/strong&gt; — it is a separate
historical/metadata &lt;em&gt;provenance flag&lt;/em&gt;. A mission that &lt;em&gt;was&lt;/em&gt; coord and had its
&lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; dropped is now &lt;code dir=&quot;auto&quot;&gt;SINGLE_BRANCH&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;LANES&lt;/code&gt; carrying a
&lt;code dir=&quot;auto&quot;&gt;flattened&lt;/code&gt; mark; the shape value never encodes history. This is the single
place the lanes-vs-coord cross-product is named.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Store it, do not guess it.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;topology&lt;/code&gt; is minted into &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; at
&lt;code dir=&quot;auto&quot;&gt;mission create&lt;/code&gt; and &lt;strong&gt;read&lt;/strong&gt; thereafter — never re-inferred from disk or
from &lt;code dir=&quot;auto&quot;&gt;coordination_branch is None&lt;/code&gt; at resolve time. Legacy missions are
backfilled &lt;strong&gt;once&lt;/strong&gt; via &lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate backfill-topology&lt;/code&gt; (mirroring the
&lt;code dir=&quot;auto&quot;&gt;backfill-identity&lt;/code&gt; precedent), with a &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor topology --json&lt;/code&gt;
audit. Until a mission is backfilled, the imperative shell falls back to the
legacy derivation exactly once — to &lt;strong&gt;compute and persist&lt;/strong&gt; the topology —
then reads the stored value.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;One resolver, pure.&lt;/strong&gt; Add
&lt;code dir=&quot;auto&quot;&gt;resolve_context_for_mission(mission_id: str, topology: MissionTopology) -&gt; MissionExecutionContext&lt;/code&gt; as a &lt;strong&gt;pure projection&lt;/strong&gt; over the existing single
construction door &lt;code dir=&quot;auto&quot;&gt;build_execution_context&lt;/code&gt; (functional core / imperative
shell). It performs &lt;strong&gt;no filesystem or git I/O&lt;/strong&gt;; the shell parses/persists
&lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; and passes &lt;code dir=&quot;auto&quot;&gt;id + topology&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;topology&lt;/code&gt; is an authoritative input
(optional input-assertion: fail-closed on a supplied-vs-resolved mismatch).
This is a second projection of the same door — “one authority, two
projections”, the way &lt;code dir=&quot;auto&quot;&gt;resolve_placement_only&lt;/code&gt; already is — &lt;strong&gt;not&lt;/strong&gt; a new
parallel resolver (C-003).&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Retire BOTH live derivations.&lt;/strong&gt; The &lt;code dir=&quot;auto&quot;&gt;coordination_branch is None ⇒ FLATTENED&lt;/code&gt; inference is removed from &lt;strong&gt;both&lt;/strong&gt; sites: (a) &lt;code dir=&quot;auto&quot;&gt;resolution.py:705-718&lt;/code&gt;
behind the door, &lt;strong&gt;and&lt;/strong&gt; (b) the independent &lt;code dir=&quot;auto&quot;&gt;runtime_bridge.py:144-211&lt;/code&gt;
disk-&lt;code dir=&quot;auto&quot;&gt;stat&lt;/code&gt; ladder. Leaving either alive is the parallel-inference
death-spiral; both route through the stored topology under the same live
convergence proof.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;CommitTargetKind&lt;/code&gt; becomes a topology-derived predicate.&lt;/strong&gt; Introduce a
&lt;code dir=&quot;auto&quot;&gt;MissionTopology&lt;/code&gt;-derived per-ref predicate &lt;code dir=&quot;auto&quot;&gt;routes_through_coordination(target)&lt;/code&gt;
and re-express the &lt;strong&gt;9&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;.kind is COORDINATION&lt;/code&gt; branch-decision sites
against it, so no site re-infers the per-ref topology. The
&lt;code dir=&quot;auto&quot;&gt;CommitTargetKind&lt;/code&gt; &lt;strong&gt;type itself is NOT deleted here&lt;/strong&gt; — its ~143
value-literal references (≈63 constructions + ≈24 imports + ≈56 test refs
across 41 files) are behavior-neutral and &lt;strong&gt;carved to Mission B&lt;/strong&gt;
(&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2070&quot;&gt;#2070&lt;/a&gt;). This
mission stops &lt;em&gt;reading&lt;/em&gt; &lt;code dir=&quot;auto&quot;&gt;.kind&lt;/code&gt; for decisions; the constructor field stays
vestigial until Mission B eradicates the type.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Adopt structurally on the read and write paths.&lt;/strong&gt; The read path
(&lt;code dir=&quot;auto&quot;&gt;_read_path_resolver._resolve_existing_for_slug&lt;/code&gt; and the legs it feeds)
resolves the surface from the &lt;strong&gt;stored&lt;/strong&gt; topology, so &lt;code dir=&quot;auto&quot;&gt;CoordState.MATERIALIZED&lt;/code&gt;
(a disk &lt;code dir=&quot;auto&quot;&gt;stat&lt;/code&gt;) is no longer the deciding signal (FR-006). The write path —
every planning-phase commit and every &lt;code dir=&quot;auto&quot;&gt;status.emit.emit_status_transition&lt;/code&gt;
call site — resolves its destination through the seam, not from the current
&lt;code dir=&quot;auto&quot;&gt;HEAD&lt;/code&gt; branch (FR-007/FR-009). &lt;code dir=&quot;auto&quot;&gt;safe-commit&lt;/code&gt;’s two responsibilities are
&lt;strong&gt;separated&lt;/strong&gt;: mission-aware planning commits resolve via the seam; generic
operator-file commits keep their existing behavior (NFR-002).&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;binding-principle--structural-not-symptomatic-c-004&quot;&gt;Binding principle — structural, not symptomatic (C-004)&lt;/h3&gt;
&lt;p&gt;The fix is structural: &lt;strong&gt;the read path consults the STORED topology, never
re-inferring the shape from on-disk worktree existence.&lt;/strong&gt; A flattened mission
resolves PRIMARY because its &lt;em&gt;stored&lt;/em&gt; topology says so — not because a band-aid
out-voted an on-disk husk. By construction, the orphaned &lt;code dir=&quot;auto&quot;&gt;-coord&lt;/code&gt; husk is never
consulted, so #2062/#2063/#2064 cannot re-open. If storing the topology &lt;em&gt;could&lt;/em&gt;
re-open #2062, that would prove the prior fix was a symptom patch; the
resolution is to stop the read path inferring from disk, never to re-add a
band-aid.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;positive&quot;&gt;Positive&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;The mission shape is one named, stored, authoritative value.&lt;/strong&gt; It is
parseable after an interruption or an agent tool-switch — no caller has to
recompute it from &lt;code dir=&quot;auto&quot;&gt;coordination_branch is None&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; presence, or a
worktree &lt;code dir=&quot;auto&quot;&gt;stat&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The resolver is pure and isolated-testable&lt;/strong&gt; (NFR-005): feed
&lt;code dir=&quot;auto&quot;&gt;(mission_id, topology)&lt;/code&gt;, assert the returned &lt;code dir=&quot;auto&quot;&gt;MissionExecutionContext&lt;/code&gt; surface
fields — zero filesystem/git fixtures. All FS/git access lives in the
imperative shell.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Both hand-rolled derivations are dead&lt;/strong&gt; (SC-001): a &lt;code dir=&quot;auto&quot;&gt;grep&lt;/code&gt; for the
&lt;code dir=&quot;auto&quot;&gt;coordination_branch is None&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;_coord_path.exists()&lt;/code&gt; inference pattern finds
zero live decision sites.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The #2062/#2063/#2064 desync class is closed at the root&lt;/strong&gt; — structurally,
not by close-on-static (witnessed live per NFR-001).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative--risks&quot;&gt;Negative / risks&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Backfill sequencing is a dogfooding landmine.&lt;/strong&gt; This mission’s &lt;em&gt;own&lt;/em&gt;
&lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; must be topology-backfilled &lt;strong&gt;before&lt;/strong&gt; any caller reads the stored
field (FR-003); flatten/coord friction is expected during implement, carried
under the live-evidence rule.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Transient on-disk×git states are NOT subsumed by the enum&lt;/strong&gt; (C-006). The
create→first-write window (&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1718&quot;&gt;#1718&lt;/a&gt;:
topology = COORD but the worktree is not yet materialized) and the
coord-deleted state (&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1848&quot;&gt;#1848&lt;/a&gt;:
declared branch deleted from git → &lt;code dir=&quot;auto&quot;&gt;CoordinationBranchDeleted&lt;/code&gt; data-loss
carve-out) are orthogonal to the four enum cells and &lt;strong&gt;stay discriminated by
&lt;code dir=&quot;auto&quot;&gt;probe_coord_state&lt;/code&gt;&lt;/strong&gt; (with the branch signal). A &lt;code dir=&quot;auto&quot;&gt;LANES_WITH_COORD&lt;/code&gt; mission
can be MATERIALIZED/EMPTY/UNMATERIALIZED/DELETED at any instant; the stored
topology does not encode that and must not try to.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The &lt;code dir=&quot;auto&quot;&gt;CommitTargetKind&lt;/code&gt; type lives vestigially&lt;/strong&gt; until Mission B (#2070). The
9 decision sites no longer read it, but the constructor field and its ~143
value-literal references remain until the behavior-neutral eradication lands.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;alternatives-considered&quot;&gt;Alternatives considered&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Derive-and-carry per call&lt;/strong&gt; (the #2069 ticket’s original lean). Rejected:
recomputing the shape per call is itself the drift vector this mission exists
to remove — every recomputation is another place the slices can diverge.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A new unified parallel resolver.&lt;/strong&gt; Rejected (C-003): &lt;code dir=&quot;auto&quot;&gt;build_execution_context&lt;/code&gt;
is already the single, verified construction door (per missions &lt;code dir=&quot;auto&quot;&gt;01KVGCE8&lt;/code&gt;/
&lt;code dir=&quot;auto&quot;&gt;01KVN754&lt;/code&gt;). &lt;code dir=&quot;auto&quot;&gt;resolve_context_for_mission&lt;/code&gt; &lt;em&gt;projects&lt;/em&gt; it; introducing a second
resolver that re-reads &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;/git independently would
re-create the very split-brain under repair.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The original adopt-&lt;code dir=&quot;auto&quot;&gt;resolve_placement_only&lt;/code&gt; + band-aid-the-read-path plan.&lt;/strong&gt;
Superseded as symptomatic (D-2/C-004): threading a &lt;code dir=&quot;auto&quot;&gt;declares_coordination&lt;/code&gt;
signal into the disk-&lt;code dir=&quot;auto&quot;&gt;stat&lt;/code&gt; heuristic treats the symptom; it leaves the disk
&lt;code dir=&quot;auto&quot;&gt;stat&lt;/code&gt; as a topology signal and is re-openable.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Delete the whole &lt;code dir=&quot;auto&quot;&gt;CommitTargetKind&lt;/code&gt; type in-mission.&lt;/strong&gt; Rejected: 41-file
churn balloons a focused seam mission with zero correctness gain. Carved to
Mission B (#2070) as principled cleanup over an already-correct door — the
#2065 read-side strangler pattern.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;references&quot;&gt;References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Mission spec: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/single-planning-surface-authority-01KVPR00/spec.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Phase-0 decisions (D-1..D-8): &lt;code dir=&quot;auto&quot;&gt;kitty-specs/single-planning-surface-authority-01KVPR00/research.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Design driver: &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2069&quot;&gt;#2069&lt;/a&gt; (MissionTopology SSOT seam)&lt;/li&gt;
&lt;li&gt;Closed structurally: &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2062&quot;&gt;#2062&lt;/a&gt;, &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2063&quot;&gt;#2063&lt;/a&gt;, &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2064&quot;&gt;#2064&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Mission B (behavior-neutral follow-on, blocked-by this mission): &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2070&quot;&gt;#2070&lt;/a&gt; — &lt;code dir=&quot;auto&quot;&gt;CommitTargetKind&lt;/code&gt; type eradication + richer-API adoption at the 14 &lt;code dir=&quot;auto&quot;&gt;resolve_placement_only&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;resolve_action_context&lt;/code&gt; call sites&lt;/li&gt;
&lt;li&gt;Write-side twin (kind-aware placement over the stored topology): &lt;a href=&quot;/adr/3.x/2026-06-24-1-kind-and-topology-aware-artifact-placement/&quot;&gt;ADR 2026-06-24-1 — Kind- and topology-aware artifact placement&lt;/a&gt; (&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2090&quot;&gt;#2090&lt;/a&gt; / &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2101&quot;&gt;#2101&lt;/a&gt;)&lt;/li&gt;
&lt;li&gt;Epics: &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1716&quot;&gt;#1716&lt;/a&gt; (single surface authority), &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2007&quot;&gt;#2007&lt;/a&gt;, &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1619&quot;&gt;#1619&lt;/a&gt; (execution-context)&lt;/li&gt;
&lt;li&gt;Transient-state carve-outs preserved: &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1718&quot;&gt;#1718&lt;/a&gt; (create-window), &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1848&quot;&gt;#1848&lt;/a&gt; (coord-deleted)&lt;/li&gt;
&lt;li&gt;Canonical seams: &lt;a href=&quot;../../../src/mission_runtime/context.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/context.py&lt;/code&gt;&lt;/a&gt; (&lt;code dir=&quot;auto&quot;&gt;MissionExecutionContext&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;CommitTargetKind&lt;/code&gt;), &lt;a href=&quot;../../../src/mission_runtime/resolution.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/resolution.py&lt;/code&gt;&lt;/a&gt; (&lt;code dir=&quot;auto&quot;&gt;build_execution_context&lt;/code&gt;, retired derivation), &lt;a href=&quot;../../../src/runtime/next/runtime_bridge.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/runtime/next/runtime_bridge.py&lt;/code&gt;&lt;/a&gt; (retired second derivation)&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-11-06-topology-stored-at-create-settled-once-at-the-first-finalize&quot;&gt;Amendment 2026-11-06: topology stored at create, settled once at the first finalize&lt;/h2&gt;
&lt;p&gt;Decision 2 now reads: &lt;strong&gt;the topology is stored at create, settled once at the first finalize, and read thereafter.&lt;/strong&gt; &lt;a href=&quot;/adr/4.x/2026-11-06-3-topology-is-settled-once-at-first-finalize/&quot;&gt;ADR 2026-11-06-3&lt;/a&gt; records the change (&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/7282&quot;&gt;#7282&lt;/a&gt;); the text above is kept as history.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;A Mission created without &lt;code dir=&quot;auto&quot;&gt;--topology&lt;/code&gt; stores a provisional value: &lt;code dir=&quot;auto&quot;&gt;topology: single_branch&lt;/code&gt; on a minted topic branch, with &lt;code dir=&quot;auto&quot;&gt;topology_source: default&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;topology_settled: false&lt;/code&gt;. The first &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; settles it by size, once, to &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;lanes_with_coord&lt;/code&gt;, before any work package is claimed, and writes &lt;code dir=&quot;auto&quot;&gt;topology_decision&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;--topology&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;--owned-checkout&lt;/code&gt; record &lt;code dir=&quot;auto&quot;&gt;topology_source: explicit&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;owned_checkout&lt;/code&gt; and are settled at create, as before.&lt;/li&gt;
&lt;li&gt;A Mission with no &lt;code dir=&quot;auto&quot;&gt;topology_source&lt;/code&gt; (every Mission created before this change) is settled. It is never re-decided, and &lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate backfill-topology&lt;/code&gt; is unchanged.&lt;/li&gt;
&lt;li&gt;The rest of this record holds: settlement writes the stored value through the shell and nothing re-infers the topology from disk. Re-finalize, the legacy &lt;code dir=&quot;auto&quot;&gt;tasks-finalize&lt;/code&gt; repair path and doctor rebuilds read the stored value and never re-decide.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
