<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/architecture/artifact-placement-seam/">
  <id>https://docs.spec-kitty.ai/architecture/artifact-placement-seam/</id>
  <title>The Artifact Placement Seam</title>
  <updated>2026-10-17T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/architecture/artifact-placement-seam/"/>
  <summary>How a mission artifact&apos;s kind and topology resolve to a physical tree, the two composition roots, and where callers still bypass the seam.</summary>
  <content type="html">&lt;span id=&quot;the-artifact-placement-seam&quot;&gt;&lt;/span&gt;
&lt;p&gt;This page explains the layering that decides &lt;strong&gt;where a mission artifact physically lives&lt;/strong&gt;
— which directory a read resolves to, which branch a write commits against — and names the
places a caller can still bypass that decision. It exists because three missions in a row
spent their discovery budget re-deriving facts this page now states once: &lt;code dir=&quot;auto&quot;&gt;#3014&lt;/code&gt; was filed
on a false premise about the layering, and this mission (&lt;code dir=&quot;auto&quot;&gt;read-side-seam-primary-primitive- closure-01KYKMMT&lt;/code&gt;) was re-scoped twice before the layering itself was pinned down correctly.&lt;/p&gt;
&lt;p&gt;This page is &lt;strong&gt;explanatory, not normative&lt;/strong&gt;. The binding placement rules live in
&lt;a href=&quot;/adr/3.x/2026-06-24-1-kind-and-topology-aware-artifact-placement/&quot;&gt;ADR 2026-06-24-1&lt;/a&gt; and
&lt;a href=&quot;/adr/3.x/2026-07-23-1-surface-vocabulary-two-domains-and-topology-surface-rename/&quot;&gt;ADR 2026-07-23-1&lt;/a&gt;
(see &lt;a href=&quot;#citations&quot;&gt;Citations&lt;/a&gt;); this page does not restate their rules, only shows how the code
that implements them is layered. Every code-shape claim below carries a &lt;code dir=&quot;auto&quot;&gt;module:symbol&lt;/code&gt;
citation so a future rename shows up as a broken reference rather than silent drift.&lt;/p&gt;
&lt;h2 id=&quot;what-routing-means-here&quot;&gt;What “routing” means here&lt;/h2&gt;
&lt;p&gt;“Routing” on this page means exactly one thing: **mapping a mission artifact’s &lt;em&gt;kind&lt;/em&gt; — a
&lt;code dir=&quot;auto&quot;&gt;MissionArtifactKind&lt;/code&gt; member such as &lt;code dir=&quot;auto&quot;&gt;SPEC&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;STATUS_STATE&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/artifacts.py:63&lt;/code&gt;) — together with the mission’s &lt;em&gt;topology&lt;/em&gt;, to a
&lt;code dir=&quot;auto&quot;&gt;TopologySurface&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/artifacts.py:23&lt;/code&gt;): the physical tree the artifact
resolves to for reading or writing. This is the &lt;strong&gt;placement sense&lt;/strong&gt; of “routing.”&lt;/p&gt;
&lt;p&gt;“Routing” is heavily overloaded elsewhere in this codebase — branch selection, git-commit
targets, dispatch/profile matching, sync fan-out, model/task assignment, and more all use the
same word for unrelated decisions. Do not infer any of those senses from this page. The full
disambiguation, with a “do NOT use when” guard for every governed sense, lives in the
&lt;code dir=&quot;auto&quot;&gt;Routing&lt;/code&gt; entry of &lt;a href=&quot;/context/orchestration/#routing&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/context/orchestration.md&lt;/code&gt;&lt;/a&gt; —
consult it rather than guessing from context.&lt;/p&gt;
&lt;h2 id=&quot;the-layer-table&quot;&gt;The layer table&lt;/h2&gt;
&lt;p&gt;The question “where does this artifact live?” passes through five layers before it reaches a
filesystem path. Each layer has exactly one owner; a caller that reaches past its own layer
(picking a surface, or assembling a path, itself) is the semi-compliance shape &lt;a href=&quot;#the-compliance-taxonomy&quot;&gt;§4&lt;/a&gt;
names.&lt;/p&gt;















































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Layer&lt;/th&gt;&lt;th&gt;Question answered&lt;/th&gt;&lt;th&gt;Owning module:symbol&lt;/th&gt;&lt;th&gt;Aware of&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;L0 — entry&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;em&gt;What&lt;/em&gt; artifact am I reading or writing?&lt;/td&gt;&lt;td&gt;The caller names a &lt;code dir=&quot;auto&quot;&gt;MissionArtifactKind&lt;/code&gt; and asks a &lt;code dir=&quot;auto&quot;&gt;PlacementSeam&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/resolution.py:2302&lt;/code&gt;) for &lt;code dir=&quot;auto&quot;&gt;read_dir&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;write_target&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;write_dir&lt;/code&gt;&lt;/td&gt;&lt;td&gt;kind only — nothing about &lt;em&gt;where&lt;/em&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;L1 — partition classification&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Which partition does this kind belong to — PRIMARY or COORD?&lt;/td&gt;&lt;td&gt;The &lt;code dir=&quot;auto&quot;&gt;_PRIMARY_ARTIFACT_KINDS&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;_PLACEMENT_ARTIFACT_KINDS&lt;/code&gt; frozensets and &lt;code dir=&quot;auto&quot;&gt;assert_partition_invariant&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/artifacts.py:165&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;:207&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;:353&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;kind only — &lt;strong&gt;topology-blind&lt;/strong&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;L2a — declared decision&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Where does this fact &lt;em&gt;architecturally&lt;/em&gt; live, independent of what is materialized on disk right now?&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;declared_read_surface&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/resolution.py:2630&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;kind + topology; &lt;strong&gt;materialization-BLIND&lt;/strong&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;L2b — affirmative decision&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Where does this read resolve &lt;em&gt;right now&lt;/em&gt;, given what is actually materialized?&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;_classify_artifact_surface&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/resolution.py:2679&lt;/code&gt;), consuming &lt;code dir=&quot;auto&quot;&gt;probe_coord_state&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/missions/_read_path_resolver.py:287&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;kind + topology + &lt;strong&gt;materialization&lt;/strong&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;L3 — candidate discovery / assembly&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Which concrete directories exist for this handle, and how is the final path assembled?&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;resolve_planning_read_dir&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/missions/_read_path_resolver.py:1429&lt;/code&gt;) and the module-private leaf &lt;code dir=&quot;auto&quot;&gt;_compose_primary_feature_dir&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/missions/_read_path_resolver.py:1320&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;filesystem + handle form — this is where paths are &lt;strong&gt;built&lt;/strong&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;L4 — translation&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Given a chosen surface, &lt;em&gt;which&lt;/em&gt; already-discovered location is it?&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;translate_surface&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/resolution.py:2588&lt;/code&gt;) over a &lt;code dir=&quot;auto&quot;&gt;SurfaceLocations&lt;/code&gt; record (&lt;code dir=&quot;auto&quot;&gt;:2556&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;neither kind nor topology — it &lt;strong&gt;selects&lt;/strong&gt; a field off an already-populated record, and &lt;strong&gt;refuses&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;ValueError&lt;/code&gt;) when that field is absent&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;strong&gt;L2 is two functions, not one, and the split is deliberate.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;declared_read_surface&lt;/code&gt; is
materialization-&lt;em&gt;blind&lt;/em&gt; precisely so it can disagree with an already-resolved surface stamp —
that disagreement is what lets &lt;code dir=&quot;auto&quot;&gt;GateExecutionContext.surface_cannot_hold&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/acceptance/execution_context.py:196&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;#2885&lt;/code&gt;) refuse rather than silently
pass an empty surface. Describing L2 as “one decision module” erases the reason that guard can
fire at all. &lt;code dir=&quot;auto&quot;&gt;_classify_artifact_surface&lt;/code&gt;’s own docstring names this: it defers to
&lt;code dir=&quot;auto&quot;&gt;declared_read_surface&lt;/code&gt; first and only consults the materialization-aware &lt;code dir=&quot;auto&quot;&gt;CoordState&lt;/code&gt;
classifier when the declared answer is &lt;code dir=&quot;auto&quot;&gt;COORD&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;L4 selects; it does not assemble.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;translate_surface&lt;/code&gt; reads a field off a &lt;code dir=&quot;auto&quot;&gt;SurfaceLocations&lt;/code&gt;
record that L3 already populated and raises when the field is &lt;code dir=&quot;auto&quot;&gt;None&lt;/code&gt; — it never touches the
filesystem or builds a path from parts. Treating L4 as the place to “fix” a placement bug
teaches the exact misappropriation this page exists to prevent: re-adding discovery logic at a
call site instead of routing through L0–L3.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;A third &lt;code dir=&quot;auto&quot;&gt;read_dir&lt;/code&gt; route, not shown as a table row.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;PlacementSeam.read_dir&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/resolution.py:2359&lt;/code&gt;) short-circuits exactly one kind —
&lt;code dir=&quot;auto&quot;&gt;MissionArtifactKind.RETROSPECTIVE&lt;/code&gt; — to &lt;code dir=&quot;auto&quot;&gt;resolve_retrospective_home&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/retrospective/writer.py:37&lt;/code&gt;) at &lt;code dir=&quot;auto&quot;&gt;resolution.py:2403&lt;/code&gt;, &lt;strong&gt;before&lt;/strong&gt; any of L2’s
classification runs. See &lt;a href=&quot;#honest-bounds&quot;&gt;Honest bounds&lt;/a&gt; for why this is load-bearing rather
than a footnote.&lt;/p&gt;
&lt;h2 id=&quot;both-composition-roots&quot;&gt;Both composition roots&lt;/h2&gt;
&lt;p&gt;There are two composition roots, not one, and both are reached through the same seam object:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;The read root&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;resolve_artifact_surface&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/resolution.py:2826&lt;/code&gt;),
projected by &lt;code dir=&quot;auto&quot;&gt;PlacementSeam.read_dir&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The write root&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;resolve_placement_only&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/resolution.py:1864&lt;/code&gt;),
projected by &lt;code dir=&quot;auto&quot;&gt;PlacementSeam.write_target&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;:2345&lt;/code&gt;).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Both are constructed via one entry point, &lt;code dir=&quot;auto&quot;&gt;placement_seam(repo_root, mission_slug)&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/resolution.py:3020&lt;/code&gt;), which also asserts the L1 partition invariant
before returning — “two roots, one seam.”&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;This is the intent, not a landed invariant with zero exceptions&lt;/strong&gt; — see
&lt;a href=&quot;#honest-bounds&quot;&gt;Honest bounds&lt;/a&gt; for the measured count of direct callers that reach either root
without going through &lt;code dir=&quot;auto&quot;&gt;PlacementSeam&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;the-write-location-write_dir&quot;&gt;The write location (write_dir)&lt;/h3&gt;
&lt;p&gt;The write root answers &lt;em&gt;which ref&lt;/em&gt; a commit lands on; it has no opinion on &lt;em&gt;which directory&lt;/em&gt;
the bytes are written into. That second question belongs to &lt;code dir=&quot;auto&quot;&gt;PlacementSeam.write_dir(kind)&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/resolution.py:2426&lt;/code&gt;), added by mission
&lt;code dir=&quot;auto&quot;&gt;coord-artifact-single-home-01M3V4BE&lt;/code&gt; (Mission contract
&lt;code dir=&quot;auto&quot;&gt;contracts/write-location-accessor.md&lt;/code&gt;; decision record: the 2026-10-01 amendment of
&lt;a href=&quot;/adr/3.x/2026-06-19-1-coord-empty-surface-fallback/&quot;&gt;ADR 2026-06-19-1&lt;/a&gt;). It returns a
&lt;code dir=&quot;auto&quot;&gt;WriteLocation&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/write_location.py:77&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;path&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;surface_root&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;surface&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;coord_state_before&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;establishment&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;seed&lt;/code&gt;).&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;write_dir&lt;/code&gt; is &lt;strong&gt;not a third composition root&lt;/strong&gt;: it consults the same materialization-blind
&lt;code dir=&quot;auto&quot;&gt;declared_read_surface&lt;/code&gt; decision (L2a) that &lt;code dir=&quot;auto&quot;&gt;read_dir&lt;/code&gt; does, then branches:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;declared PRIMARY (a PRIMARY-partition kind, or any kind on &lt;code dir=&quot;auto&quot;&gt;lanes&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt;) →
&lt;code dir=&quot;auto&quot;&gt;_declared_primary_write_dir&lt;/code&gt;, identical to &lt;code dir=&quot;auto&quot;&gt;read_dir&lt;/code&gt; with no side effects;&lt;/li&gt;
&lt;li&gt;a published Mission’s E2-eligible COORD kind, or &lt;code dir=&quot;auto&quot;&gt;STATUS_STATE&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;_published_e2_write_dir&lt;/code&gt;,
the PRIMARY Mission dir with no coordination probe, so a coordination branch that
consolidation has already torn down cannot raise here;&lt;/li&gt;
&lt;li&gt;every other COORD kind of a coordination-routed Mission →
&lt;code dir=&quot;auto&quot;&gt;specify_cli.coordination.coord_seed.establish_coord_write_location&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/coordination/coord_seed.py:1107&lt;/code&gt;), the one place that &lt;strong&gt;materializes,
seeds, restores or refuses&lt;/strong&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The difference from &lt;code dir=&quot;auto&quot;&gt;read_dir&lt;/code&gt; is the whole point: a reader may fall back to the PRIMARY
partition on an &lt;code dir=&quot;auto&quot;&gt;EMPTY&lt;/code&gt; coordination surface (the loud fallback of ADR 2026-06-19-1, which
reads keep); a writer never does, so a COORD record cannot land on the repository root
checkout. The per-state behaviour table lives in the ADR amendment and is not repeated here.&lt;/p&gt;
&lt;h2 id=&quot;the-compliance-taxonomy&quot;&gt;The compliance taxonomy&lt;/h2&gt;
&lt;p&gt;A call site’s relationship to the seam falls into one of four shapes:&lt;/p&gt;






























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Shape&lt;/th&gt;&lt;th&gt;What the caller does&lt;/th&gt;&lt;th&gt;Verdict&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Compliant (tier-1)&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Names a &lt;code dir=&quot;auto&quot;&gt;MissionArtifactKind&lt;/code&gt;, asks &lt;code dir=&quot;auto&quot;&gt;placement_seam(...).read_dir(kind)&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;.write_target(kind)&lt;/code&gt;, and fails loud on an unresolved surface&lt;/td&gt;&lt;td&gt;Target state&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Delegating-but-lenient&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Names a kind, delegates the surface decision to the seam, but the surrounding code never supplies the fail-closed input the leaf needs (e.g. a missing &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;Censused as a bypass on the &lt;em&gt;leniency&lt;/em&gt; axis, not the &lt;em&gt;routing&lt;/em&gt; axis&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Semi-compliant&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Passes an already-canonical mission handle, but picks its own surface/resolver directly instead of asking the seam for the kind’s home&lt;/td&gt;&lt;td&gt;&lt;strong&gt;This page’s headline concept&lt;/strong&gt; — see below&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Non-compliant&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Uses a raw or unrecognized handle, or hand-assembles a path from parts&lt;/td&gt;&lt;td&gt;Should red the read-side bypass census; one currently-permanent exception is named in &lt;a href=&quot;#honest-bounds&quot;&gt;Honest bounds&lt;/a&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;strong&gt;Semi-compliance is the headline shape, and it is invisible to a handle-hygiene gate.&lt;/strong&gt; A call
site can canonicalize its mission handle perfectly — passing every check the canonicalizer
authority gate (formerly &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_resolution_authority_gates.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;CANONICALIZER_PRIMITIVE_NAMES&lt;/code&gt;; that file has been deleted) ran — and still choose its own surface by calling a
kind-blind resolver (&lt;code dir=&quot;auto&quot;&gt;resolve_feature_dir_for_mission&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/missions/_read_path_resolver.py:1695&lt;/code&gt;) directly, instead of asking
&lt;code dir=&quot;auto&quot;&gt;placement_seam(...).read_dir(&amp;#x3C;kind&gt;)&lt;/code&gt; to make the decision. The handle is canonical; the
&lt;em&gt;routing&lt;/em&gt; is not. A gate that only checks handle canonicalization form (def-use canonicality)
cannot see this, because canonicality and routing-compliance are orthogonal axes.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Which gate catches it, and which does not (US7.4):&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Does NOT catch it:&lt;/strong&gt; the (now-deleted) canonicalizer authority gate
(formerly &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_resolution_authority_gates.py&lt;/code&gt;) — it verified the &lt;em&gt;handle argument&lt;/em&gt;
passed to a small allow-listed set of primitives is already canonical; it has no opinion on
which primitive or surface the caller chose.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Does catch it:&lt;/strong&gt; the read-side bypass census
(&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_no_read_side_bypass.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;test_no_read_side_bypass_outside_sanctioned_and_allow_listed&lt;/code&gt;) — it scans for calls to the
kind-blind primitives by name (&lt;code dir=&quot;auto&quot;&gt;primary_feature_dir_for_mission&lt;/code&gt; while it existed;
&lt;code dir=&quot;auto&quot;&gt;resolve_feature_dir_for_mission&lt;/code&gt; today) anywhere outside a named sanction, independent of
whether the handle passed to them is canonical.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;unclassified-kinds-none-have-one-meaning-5697&quot;&gt;Unclassified kinds (&lt;code dir=&quot;auto&quot;&gt;None&lt;/code&gt;) have one meaning (#5697)&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;kind_for_mission_file(path)&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/artifacts.py&lt;/code&gt;) returns a
&lt;code dir=&quot;auto&quot;&gt;MissionArtifactKind&lt;/code&gt; for a recognized mission file, or &lt;code dir=&quot;auto&quot;&gt;None&lt;/code&gt; for a path it does not
recognize. &lt;code dir=&quot;auto&quot;&gt;None&lt;/code&gt; means exactly one thing to every consumer: &lt;strong&gt;“not a coordination
record.”&lt;/strong&gt; An unclassified path is primary-bound on write and is &lt;strong&gt;never&lt;/strong&gt; projected by the
squash projection (&lt;code dir=&quot;auto&quot;&gt;consolidation/bookkeeping_projection.py:_post_checkpoint_mission_paths&lt;/code&gt;)
as coordination bookkeeping. Both the projection and the workflow commit partition
(&lt;code dir=&quot;auto&quot;&gt;cli/commands/agent/workflow.py:_partition_paths_by_primary_kind&lt;/code&gt;) decide this through the
single authority &lt;code dir=&quot;auto&quot;&gt;coordination/coherence.py:is_coordination_kind_file&lt;/code&gt; (which returns &lt;code dir=&quot;auto&quot;&gt;False&lt;/code&gt;
for &lt;code dir=&quot;auto&quot;&gt;None&lt;/code&gt;) — the same authority the write side (&lt;code dir=&quot;auto&quot;&gt;commit_router&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;is_coord_residue_churn&lt;/code&gt;)
already used. Before #5697 those two consumers each re-derived the opposite answer locally
(&lt;code dir=&quot;auto&quot;&gt;None&lt;/code&gt; → coordination bookkeeping), which let a byte-identical planning/research file be
primary on write yet projected-and-refused by a squash &lt;code dir=&quot;auto&quot;&gt;consolidate&lt;/code&gt; (the #5552 class).&lt;/p&gt;
&lt;p&gt;The same unified rule routes a &lt;strong&gt;non-mission path&lt;/strong&gt; — a repo-root &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; or config file a
caller stages that never classifies — to primary-bound on the workflow commit partition. That
is deliberate alignment with the write-side authority (#2533: an unrecognized path routes
PRIMARY unconditionally), not a regression.&lt;/p&gt;
&lt;p&gt;#5697 also classified the Mission files that previously fell through to &lt;code dir=&quot;auto&quot;&gt;None&lt;/code&gt;, all in the
PRIMARY partition: &lt;code dir=&quot;auto&quot;&gt;research/**&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;RESEARCH&lt;/code&gt; (directory-anchored); &lt;code dir=&quot;auto&quot;&gt;findings.md&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;report.md&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;methodology.md&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;synthesis.md&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;literature-review.md&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;RESEARCH_OUTPUT&lt;/code&gt;;
&lt;code dir=&quot;auto&quot;&gt;gap-analysis.md&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;audit-report.md&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;ANALYSIS_REPORT&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;occurrence_map.yaml&lt;/code&gt; →
&lt;code dir=&quot;auto&quot;&gt;OCCURRENCE_MAP&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;goals.md&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;MISSION_GOALS&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;release.md&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;RELEASE_RECORD&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;
→ &lt;code dir=&quot;auto&quot;&gt;PRIMARY_METADATA&lt;/code&gt;. Four paths stay deliberately unclassified because they are not
&lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;slug&gt;/&lt;/code&gt; Mission artifacts: &lt;code dir=&quot;auto&quot;&gt;lint-report.json&lt;/code&gt; (under &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt;), &lt;code dir=&quot;auto&quot;&gt;docs/**&lt;/code&gt;
(project-root repo content), &lt;code dir=&quot;auto&quot;&gt;answers.yaml&lt;/code&gt; (under &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/interview/&lt;/code&gt;), and
&lt;code dir=&quot;auto&quot;&gt;mission-events.jsonl&lt;/code&gt; (deliberately not a kind, #5669 — keep-local, must stay real dirt).&lt;/p&gt;
&lt;h2 id=&quot;honest-bounds&quot;&gt;Honest bounds&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Surface members with no production producer.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;TopologySurface&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/ artifacts.py:23&lt;/code&gt;) has five members — &lt;code dir=&quot;auto&quot;&gt;PRIMARY&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;COORD&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;LANE&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;CONSOLIDATED&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;TEMP&lt;/code&gt; — all
declared together so &lt;code dir=&quot;auto&quot;&gt;translate_surface&lt;/code&gt;’s totality assertion (&lt;code dir=&quot;auto&quot;&gt;assert_surface_totality&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/artifacts.py:384&lt;/code&gt;) has no phantom member to skip. Only &lt;code dir=&quot;auto&quot;&gt;PRIMARY&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;COORD&lt;/code&gt; are wired to a production caller today; &lt;code dir=&quot;auto&quot;&gt;LANE&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;CONSOLIDATED&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;TEMP&lt;/code&gt; are declared
with the seam but have &lt;strong&gt;no production producer yet&lt;/strong&gt; — the enum’s own docstring
(&lt;code dir=&quot;auto&quot;&gt;artifacts.py:42-49&lt;/code&gt;) says so directly. Do not read their presence in the enum as evidence a
caller resolves them today.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The residual &lt;code dir=&quot;auto&quot;&gt;PLACEMENT&lt;/code&gt; rename debt.&lt;/strong&gt; ADR &lt;code dir=&quot;auto&quot;&gt;2026-07-23-1&lt;/code&gt; renamed the &lt;code dir=&quot;auto&quot;&gt;TopologySurface&lt;/code&gt;
member &lt;code dir=&quot;auto&quot;&gt;PLACEMENT&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;COORD&lt;/code&gt;. The frozenset that decides &lt;em&gt;which artifact kinds&lt;/em&gt; route to that
surface, however, is still named &lt;code dir=&quot;auto&quot;&gt;_PLACEMENT_ARTIFACT_KINDS&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/ artifacts.py:207&lt;/code&gt;) — the rename reached the enum member but not this frozenset’s name. This is
named here, not laundered: a future cleanup can rename the frozenset without changing any
behavior, since membership (not the Python identifier) is what every consumer reads.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The &lt;code dir=&quot;auto&quot;&gt;RETROSPECTIVE&lt;/code&gt; short-circuit is a foundation site, not a footnote.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;PlacementSeam. read_dir&lt;/code&gt; routes &lt;code dir=&quot;auto&quot;&gt;MissionArtifactKind.RETROSPECTIVE&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;resolve_retrospective_home&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/retrospective/writer.py:37&lt;/code&gt;) before &lt;code dir=&quot;auto&quot;&gt;resolve_artifact_surface&lt;/code&gt; ever runs —
because a second RETROSPECTIVE-home computation would duplicate the single authority that
function already is. &lt;code dir=&quot;auto&quot;&gt;resolve_retrospective_home&lt;/code&gt; itself calls the module-private leaf
&lt;code dir=&quot;auto&quot;&gt;_compose_primary_feature_dir&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/missions/_read_path_resolver.py:1320&lt;/code&gt;)
directly, never &lt;code dir=&quot;auto&quot;&gt;read_dir&lt;/code&gt; again. This mission proved the short-circuit is load-bearing, not
cosmetic: an intermediate draft that routed the wrapper &lt;em&gt;through&lt;/em&gt; &lt;code dir=&quot;auto&quot;&gt;read_dir(RETROSPECTIVE)&lt;/code&gt;
produced a &lt;strong&gt;real recursion cycle&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;resolve_retrospective_home → read_dir(RETROSPECTIVE) → resolve_retrospective_home → …&lt;/code&gt;), caught only by call-graph tracing, not by a &lt;code dir=&quot;auto&quot;&gt;RecursionError&lt;/code&gt;
at runtime (the cycle’s other legs terminate, so nothing crashed). The standing rule this
leaves behind: &lt;strong&gt;any site beneath this short-circuit is a foundation site&lt;/strong&gt; — it must call the
leaf directly and permanently, never route back through &lt;code dir=&quot;auto&quot;&gt;read_dir&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Two composition roots, measured bypass count (not a zero-exception invariant).&lt;/strong&gt; Re-derived
directly from the tree by AST-matching &lt;code dir=&quot;auto&quot;&gt;Call&lt;/code&gt; nodes (&lt;code dir=&quot;auto&quot;&gt;ast.walk&lt;/code&gt; over &lt;code dir=&quot;auto&quot;&gt;src/**/*.py&lt;/code&gt;, this
page’s own re-derive-don’t-copy discipline). &lt;strong&gt;Re-measured 2026-10-02 on the tip of the
mission’s last stacked lane (&lt;code dir=&quot;auto&quot;&gt;1404842433&lt;/code&gt;), because the earlier 12 + 6 figures predate the
&lt;code dir=&quot;auto&quot;&gt;merge&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;consolidation&lt;/code&gt; module renames and this mission’s write-side work.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;PlacementSeam. write_dir&lt;/code&gt; adds no &lt;code dir=&quot;auto&quot;&gt;resolve_placement_only&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;resolve_artifact_surface&lt;/code&gt; caller of its own.&lt;/p&gt;























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Root&lt;/th&gt;&lt;th&gt;Total call expressions&lt;/th&gt;&lt;th&gt;Reached via &lt;code dir=&quot;auto&quot;&gt;placement_seam(...)&lt;/code&gt; or in-module projections&lt;/th&gt;&lt;th&gt;Direct callers outside &lt;code dir=&quot;auto&quot;&gt;resolution.py&lt;/code&gt;&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;resolve_placement_only&lt;/code&gt; (write)&lt;/td&gt;&lt;td&gt;16&lt;/td&gt;&lt;td&gt;2 in &lt;code dir=&quot;auto&quot;&gt;resolution.py&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;PlacementSeam.write_target&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;resolution.py:2352&lt;/code&gt;) and the issue-matrix projection &lt;code dir=&quot;auto&quot;&gt;_issue_matrix_ref&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;:2104&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;&lt;strong&gt;14&lt;/strong&gt;, across 8 modules (&lt;code dir=&quot;auto&quot;&gt;coordination/commit_router.py&lt;/code&gt; ×6, &lt;code dir=&quot;auto&quot;&gt;coordination/status_transition.py&lt;/code&gt; ×2, &lt;code dir=&quot;auto&quot;&gt;consolidation/run_state.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;consolidation/done_bookkeeping.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;lanes/for_review_gate.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;cli/commands/safe_commit_cmd.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;cli/commands/agent/tasks_shared.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;mission_runtime/write_target_degrade.py&lt;/code&gt;)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;resolve_artifact_surface&lt;/code&gt; (read)&lt;/td&gt;&lt;td&gt;11&lt;/td&gt;&lt;td&gt;2 in &lt;code dir=&quot;auto&quot;&gt;resolution.py&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;PlacementSeam.read_dir&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;:2419&lt;/code&gt;) and the thin projection &lt;code dir=&quot;auto&quot;&gt;coord_read_dir_for&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;:2992&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;&lt;strong&gt;9&lt;/strong&gt;, across 7 modules (&lt;code dir=&quot;auto&quot;&gt;consolidation/forecast.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;policy/merge_gates.py&lt;/code&gt; ×2, &lt;code dir=&quot;auto&quot;&gt;cli/commands/accept.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;migration/runtime_state_cutover.py&lt;/code&gt; ×2, &lt;code dir=&quot;auto&quot;&gt;acceptance/execution_context.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;missions/_read_path_resolver.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;:1772&lt;/code&gt;), &lt;code dir=&quot;auto&quot;&gt;mission_runtime/issue_matrix_partition.py&lt;/code&gt;)&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;None of these 23 direct callers is a defect by itself — several are the composition root’s own
adjacent infrastructure (e.g. &lt;code dir=&quot;auto&quot;&gt;GateExecutionContext&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;acceptance/execution_context.py&lt;/code&gt;
legitimately consumes &lt;code dir=&quot;auto&quot;&gt;resolve_artifact_surface&lt;/code&gt; directly, since it &lt;em&gt;is&lt;/em&gt; the gate-facing
consumer of that authority, not a bypass of it). The count exists so “one seam object” is never
read as a landed zero-exception invariant — it is the destination, measured against the
current tree, not a claim about it. The count went &lt;strong&gt;up&lt;/strong&gt; (18 → 23) between measurements
because the tree grew, not because callers were added to bypass the seam; the figure is a
snapshot, not a ratchet.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The write-side rederivation gate has a blind spot, and its cap is zero.&lt;/strong&gt;
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_no_write_side_rederivation.py&lt;/code&gt; guards the COORD write location in
two ways: a census of COORD writer functions must not obtain their directory from a read
resolver (&lt;code dir=&quot;auto&quot;&gt;read_dir(&amp;#x3C;COORD kind&gt;)&lt;/code&gt; and the other read resolvers), and must not compose a
&lt;code dir=&quot;auto&quot;&gt;KITTY_SPECS_DIR&lt;/code&gt; path onto a worktree-named operand. Both scans cover &lt;strong&gt;only the bodies of
the census functions&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;_COORD_WRITER_CENSUS&lt;/code&gt;). A future caller that builds the Mission dir
through &lt;code dir=&quot;auto&quot;&gt;specify_cli.coordination.legacy_resolution._checkout_mission_dir&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/coordination/legacy_resolution.py:56&lt;/code&gt;, documented for non-coordination
checkouts only) is outside that scan, and so is a writer that is not in the census. The live
allowlist is empty and the cap is 0 (&lt;code dir=&quot;auto&quot;&gt;tests/architectural/_baselines.yaml&lt;/code&gt;:
&lt;code dir=&quot;auto&quot;&gt;test_no_write_side_rederivation: coord_writer_allowlist: 0&lt;/code&gt;). The honest statement is “the gate
proves the census writers do not re-derive”, not “no writer re-derives”; the gate is not
weakened to hide that.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;#3055&lt;/code&gt; — one deliberately-deferred edge (historical; now routed).&lt;/strong&gt; At the time of the audit,
&lt;code dir=&quot;auto&quot;&gt;decisions/emit.py:71&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/decisions/emit.py&lt;/code&gt;) still called &lt;code dir=&quot;auto&quot;&gt;resolve_feature_dir_for_mission&lt;/code&gt; directly
rather than routing through the seam. It was allow-listed, not routed, because the
coord-authority gate (formerly &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_resolution_authority_gates.py&lt;/code&gt;, since
deleted) independently sanctioned this exact call as a permanent legitimate coord-owned write bypass, keyed on the
literal primitive name — the gate must learn the seam idiom (recognize a kind-aware
&lt;code dir=&quot;auto&quot;&gt;read_dir(&amp;#x3C;COORD kind&gt;)&lt;/code&gt; call as the same sanctioned bypass) before this site can route without
breaking that gate. &lt;code dir=&quot;auto&quot;&gt;#3055&lt;/code&gt; tracked the follow-up. (Superseded: the site was routed onto
&lt;code dir=&quot;auto&quot;&gt;read_dir(STATUS_STATE)&lt;/code&gt; in write-side-seam-matrix-tracer WP02, and the sanctioning gate was deleted
in #3285; see the &lt;code dir=&quot;auto&quot;&gt;decisions/emit.py:71&lt;/code&gt; row in
&lt;a href=&quot;/development/reference/read-side-seam-classification/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;read-side-seam-classification.md&lt;/code&gt;&lt;/a&gt;.) This is the one edge &lt;em&gt;this mission audited&lt;/em&gt;
as directory-identical-routable and deliberately deferred. It is not the only unrouted
sanctioned &lt;code dir=&quot;auto&quot;&gt;resolve_feature_dir_for_mission&lt;/code&gt; coord-write: &lt;code dir=&quot;auto&quot;&gt;widen/state.py:63&lt;/code&gt; (removed
with the widen package, #6164), &lt;code dir=&quot;auto&quot;&gt;agent_tasks_ports.py:322&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;lanes/recovery.py:765&lt;/code&gt; carried
the same coord-authority sanction — they were simply not re-audited for the directory-identical-routing property this mission established
for &lt;code dir=&quot;auto&quot;&gt;emit.py:71&lt;/code&gt;. So the honest statement is “the one edge adjudicated and deferred,” not “the
one call site in tension.”&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Current state (2026-10-02).&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;decisions/emit.py:_mission_dir&lt;/code&gt; no longer calls
&lt;code dir=&quot;auto&quot;&gt;resolve_feature_dir_for_mission&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;read_dir&lt;/code&gt; at all: it resolves the decision-event write
location through &lt;code dir=&quot;auto&quot;&gt;placement_seam(...).write_dir(STATUS_STATE).path&lt;/code&gt;, because a decision event is a
COORD record and &lt;code dir=&quot;auto&quot;&gt;read_dir&lt;/code&gt; would degrade an &lt;code dir=&quot;auto&quot;&gt;EMPTY&lt;/code&gt; coordination surface to the repository root
checkout. Of the three sibling sanctions, &lt;code dir=&quot;auto&quot;&gt;agent_tasks_ports.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;RealCoordCommitRouter. feature_write_dir&lt;/code&gt;) and &lt;code dir=&quot;auto&quot;&gt;lanes/recovery.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;reconcile_status&lt;/code&gt;) now also take &lt;code dir=&quot;auto&quot;&gt;write_dir&lt;/code&gt;;
&lt;code dir=&quot;auto&quot;&gt;widen/state.py:63&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;WidenPendingStore.__init__&lt;/code&gt;) was removed with the widen package (#6164).&lt;/p&gt;
&lt;h2 id=&quot;partition-move-audit-checklist&quot;&gt;Partition-Move Audit Checklist&lt;/h2&gt;
&lt;p&gt;&lt;a href=&quot;/adr/3.x/2026-06-24-1-kind-and-topology-aware-artifact-placement/&quot;&gt;ADR 2026-06-24-1&lt;/a&gt;
establishes read/write symmetry as the governing rule for the L1 partition:
a kind’s read side and write side must resolve to the &lt;em&gt;same&lt;/em&gt; partition
(PRIMARY or COORD). That symmetry is a property of the &lt;strong&gt;kind
classification&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;_PRIMARY_ARTIFACT_KINDS&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;_PLACEMENT_ARTIFACT_KINDS&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/artifacts.py&lt;/code&gt;), not of any single call site — so moving
a kind between partitions is a whole-symmetry operation. Reclassify the
write side without correcting every reader and you get a documented, real
production regression, not a theoretical one:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The PR #3437 (issue #3371) case.&lt;/strong&gt; A prior mission correctly reclassified &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;LANE_STATE&lt;/code&gt;) as PRIMARY and moved its &lt;strong&gt;write&lt;/strong&gt; target accordingly — but
one reader, &lt;code dir=&quot;auto&quot;&gt;implement._resolve_lanes_dir&lt;/code&gt;, still read it via the coord
STATUS surface. Coord-topology &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt; then couldn’t find its own lane
state and refused. Every unit suite stayed green, because none of them
exercised the coord read path end-to-end; the only test that caught the
break was &lt;code dir=&quot;auto&quot;&gt;tests/e2e/test_cli_smoke.py::test_full_workflow_sequence&lt;/code&gt;, a
coord-topology full-workflow smoke test — pass on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;, fail on the
branch. &lt;strong&gt;This is the standing lesson: an e2e test, not a unit test, is
what catches a partition-move straggler&lt;/strong&gt;, because unit tests exercise a
resolver function directly with an already-correct &lt;code dir=&quot;auto&quot;&gt;feature_dir&lt;/code&gt;, while the
break lives in &lt;em&gt;which&lt;/em&gt; &lt;code dir=&quot;auto&quot;&gt;feature_dir&lt;/code&gt; an out-of-loop caller hands that
function.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The checklist&lt;/strong&gt;, next time a kind’s partition classification moves:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Grep every reader&lt;/strong&gt; of the moved kind — every call to
&lt;code dir=&quot;auto&quot;&gt;read_lanes_json&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;require_lanes_json&lt;/code&gt; / a kind-specific &lt;code dir=&quot;auto&quot;&gt;resolve_*_dir&lt;/code&gt;
helper, not just calls through &lt;code dir=&quot;auto&quot;&gt;placement_seam(...).read_dir(&amp;#x3C;kind&gt;)&lt;/code&gt;.
The seam is the compliant path; the point of this step is finding the
ones that &lt;em&gt;aren’t&lt;/em&gt; on it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Classify each reader&lt;/strong&gt; into one of three buckets:
&lt;ul&gt;
&lt;li&gt;Uses the seam (&lt;code dir=&quot;auto&quot;&gt;placement_seam(repo_root, slug).read_dir(&amp;#x3C;kind&gt;)&lt;/code&gt;) —
compliant; moves automatically with the kind’s classification.&lt;/li&gt;
&lt;li&gt;Receives its directory from an &lt;strong&gt;out-of-loop coord-resolving caller&lt;/strong&gt;
(a caller that independently resolves a coord/status surface and hands
the result down) — trace that caller too; it is invisible to a grep
scoped to the moved kind’s own helper names.&lt;/li&gt;
&lt;li&gt;Resolves the coord surface directly, bypassing the seam — broken by
construction; this was &lt;code dir=&quot;auto&quot;&gt;implement._resolve_lanes_dir&lt;/code&gt;’s shape in the
PR #3437 case.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Watch for graceful-degradation callers especially.&lt;/strong&gt; Some out-of-loop
coord-resolving callers (merge ordering, &lt;code dir=&quot;auto&quot;&gt;policy/merge_gates&lt;/code&gt;, the
bulk-edit diff-base fallback) don’t crash on a stale surface — they
silently &lt;code dir=&quot;auto&quot;&gt;SKIP&lt;/code&gt; a gate or fall back to an empty graph. A caller that
degrades gracefully on the wrong surface hides the break instead of
surfacing it, which is worse than a crash for audit purposes: nothing
in the test output points at the mismatch. (This is the same
fail-open-hides-a-break shape the charter’s C-009 class names elsewhere.)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Prove it with an e2e test, not just unit reads.&lt;/strong&gt; A unit test that
calls the resolver directly with a hand-built &lt;code dir=&quot;auto&quot;&gt;feature_dir&lt;/code&gt; cannot catch
a caller that resolves the &lt;em&gt;wrong&lt;/em&gt; &lt;code dir=&quot;auto&quot;&gt;feature_dir&lt;/code&gt; upstream — by
construction, it never gives the caller the chance to go wrong. Run (or
add) a full-workflow / topology-level test that exercises the reader
through its real call chain, for both PRIMARY-only and coord topologies.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;worked-example-decision_ledger-moved-coord-to-primary-2026-10-01&quot;&gt;Worked example: &lt;code dir=&quot;auto&quot;&gt;DECISION_LEDGER&lt;/code&gt; moved COORD to PRIMARY (2026-10-01)&lt;/h3&gt;
&lt;p&gt;Mission &lt;code dir=&quot;auto&quot;&gt;coord-artifact-single-home-01M3V4BE&lt;/code&gt; moved &lt;code dir=&quot;auto&quot;&gt;MissionArtifactKind.DECISION_LEDGER&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;decisions/index.json&lt;/code&gt; and the &lt;code dir=&quot;auto&quot;&gt;DM-*.md&lt;/code&gt; files) from &lt;code dir=&quot;auto&quot;&gt;_PLACEMENT_ARTIFACT_KINDS&lt;/code&gt; to
&lt;code dir=&quot;auto&quot;&gt;_PRIMARY_ARTIFACT_KINDS&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/artifacts.py:165&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;:207&lt;/code&gt;; the kind sits in the
PRIMARY frozenset at &lt;code dir=&quot;auto&quot;&gt;:197&lt;/code&gt;). The decision and its reasoning are in
&lt;a href=&quot;/adr/4.x/2026-10-01-3-decision-ledger-primary-partition/&quot;&gt;ADR 2026-10-01-3&lt;/a&gt;. This is the
checklist above applied, step by step:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Grep every reader.&lt;/strong&gt; The reader blast radius was enumerated up front (the Mission’s
research record, D12) instead of being found by symptom, and every reader that flips has a
focused test of its post-flip answer
(&lt;code dir=&quot;auto&quot;&gt;tests/mission_runtime/test_decision_ledger_reader_flips.py&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Classify each reader.&lt;/strong&gt; Seam readers moved with the classification automatically. The
shared predicates (&lt;code dir=&quot;auto&quot;&gt;kind_is_coordination_residue&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;is_coord_residue_churn&lt;/code&gt; in
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/coordination/coherence.py&lt;/code&gt;) changed their verdict for the ledger at every
caller, including the topology-less ones that project COORD by default. The writer
(&lt;code dir=&quot;auto&quot;&gt;decisions/emit.py&lt;/code&gt; and the store) was already PRIMARY since #4966, so the &lt;em&gt;taxonomy&lt;/em&gt; was
the straggler of that earlier intent, not a reader.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Graceful-degradation callers.&lt;/strong&gt; The consolidation planning-recency pass is the case the
checklist warns about: it can silently overwrite a merged file. It now excludes any path
covered by a registered merge driver
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/consolidation/planning_recency.py&lt;/code&gt;), so the
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-decision-index&lt;/code&gt; driver (&lt;code dir=&quot;auto&quot;&gt;union_decision_index&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;run_decision_index_driver&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/consolidation/drivers.py:1236&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;:1280&lt;/code&gt;) owns reconciling &lt;code dir=&quot;auto&quot;&gt;index.json&lt;/code&gt;
instead of a target-favouring restore dropping a lane-added decision entry.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Prove it end to end.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;tests/integration/test_coord_single_home_workflow.py&lt;/code&gt; runs the
ledger through create, &lt;code dir=&quot;auto&quot;&gt;spec-commit&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;accept&lt;/code&gt;, consolidate and a fresh clone, for the
coordination topologies, not only unit reads.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;One consequence is specific to this move: the &lt;em&gt;events&lt;/em&gt; about decisions
(&lt;code dir=&quot;auto&quot;&gt;decisions.events.jsonl&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;DECISION_LOG&lt;/code&gt;) did &lt;strong&gt;not&lt;/strong&gt; move; they stay COORD, so a Mission can
have a PRIMARY ledger whose events live on the coordination branch. A divergence between the
two is a recorded finding (&lt;code dir=&quot;auto&quot;&gt;DECISION_LEDGER_ONLY_ON_COORDINATION&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;DECISION_LOG_FORKED&lt;/code&gt;;
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/decisions/fork.py:407&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;:442&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;:514&lt;/code&gt;), repaired by &lt;code dir=&quot;auto&quot;&gt;doctor decisions --repair&lt;/code&gt;, and teardown refuses with &lt;code dir=&quot;auto&quot;&gt;COORDINATION_LEDGER_UNREPAIRED&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/coordination/teardown.py:151&lt;/code&gt;) rather than dropping an unreconciled ledger.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Coordination residue note.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;_COORD_RESIDUE_DIRS&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/artifacts.py:303&lt;/code&gt;)
maps a Mission-relative directory name to the kind it holds, which
&lt;code dir=&quot;auto&quot;&gt;kind_is_coordination_residue&lt;/code&gt; then judges by the kind’s partition. Its &lt;code dir=&quot;auto&quot;&gt;decisions&lt;/code&gt;
entry maps to &lt;code dir=&quot;auto&quot;&gt;DECISION_LEDGER&lt;/code&gt;; since the move, &lt;code dir=&quot;auto&quot;&gt;decisions/&lt;/code&gt; is a &lt;strong&gt;PRIMARY-partition kind and
is never reset as residue&lt;/strong&gt;: the directory still maps to the same kind, and only the kind’s
partition membership changed.&lt;/p&gt;
&lt;h2 id=&quot;two-axis-resolver-site-classification&quot;&gt;Two-Axis Resolver-Site Classification&lt;/h2&gt;
&lt;p&gt;Auditing a resolver call site for correctness (not just for seam
compliance) means answering two independent questions, not one:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Axis A — raise or degrade.&lt;/strong&gt; When the target cannot be resolved, does the
call site raise (fail-closed — e.g. &lt;code dir=&quot;auto&quot;&gt;require_lanes_json&lt;/code&gt; raising
&lt;code dir=&quot;auto&quot;&gt;MissingLanesError&lt;/code&gt;, or &lt;code dir=&quot;auto&quot;&gt;resolve_write_target_or_degrade&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/write_target_degrade.py&lt;/code&gt;) called with
&lt;code dir=&quot;auto&quot;&gt;degrade_ref=None&lt;/code&gt;), or does it silently degrade to a fallback ref or an
empty/skipped result (fail-open — e.g. the same helper called with a
caller-supplied &lt;code dir=&quot;auto&quot;&gt;degrade_ref&lt;/code&gt;, or the graceful-degradation callers named
above)? Both arms are legitimate in the right place; the audit question is
whether the &lt;em&gt;caller&lt;/em&gt; chose the arm deliberately for its own correctness
requirements, or inherited it by accident from a shared helper’s default.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Axis B — anchor-root.&lt;/strong&gt; Does the call site route its &lt;code dir=&quot;auto&quot;&gt;repo_root&lt;/code&gt; through
&lt;code dir=&quot;auto&quot;&gt;get_main_repo_root()&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/paths.py&lt;/code&gt;) before resolving —
anchoring at the primary checkout regardless of which worktree the process
is physically running from — or does it resolve directly off whatever
&lt;code dir=&quot;auto&quot;&gt;repo_root&lt;/code&gt; (or cwd) it was handed, which may itself be a lane worktree? An
unanchored call site invoked from inside a lane worktree silently resolves
against that worktree’s own tree instead of the primary checkout, producing
a worktree-local answer for a question that has exactly one correct answer
mission-wide.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The two axes are orthogonal — classify both, not just one.&lt;/strong&gt; A call site
that raises loudly (Axis A) but is unanchored (Axis B) fails safe against
the &lt;em&gt;wrong&lt;/em&gt; root — a clean exception that still doesn’t prove the right
directory was ever examined. A call site that degrades quietly (Axis A) but
is correctly anchored (Axis B) at least looks in the right place, but can
still mask a real gap behind a plausible-looking fallback. Neither
combination is “obviously fine because it raises” or “obviously broken
because it degrades” — record both axes for a call site before signing off
on it.&lt;/p&gt;
&lt;h2 id=&quot;citations&quot;&gt;Citations&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&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 — One Partition, Read/Write
Symmetry&lt;/a&gt; — the
governing decision for the L1 partition (&lt;code dir=&quot;auto&quot;&gt;_PRIMARY_ARTIFACT_KINDS&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;_PLACEMENT_ARTIFACT_KINDS&lt;/code&gt;) and for read/write symmetry across the two composition roots.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-07-23-1-surface-vocabulary-two-domains-and-topology-surface-rename/&quot;&gt;ADR 2026-07-23-1: &lt;code dir=&quot;auto&quot;&gt;surface&lt;/code&gt; names two unrelated domains — split the vocabulary, rename to
&lt;code dir=&quot;auto&quot;&gt;ToolSurfaceKind&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;TopologySurface&lt;/code&gt;&lt;/a&gt;
— the governing decision for the &lt;code dir=&quot;auto&quot;&gt;TopologySurface&lt;/code&gt; vocabulary (including the
&lt;code dir=&quot;auto&quot;&gt;PRIMARY&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;COORD&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;LANE&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;CONSOLIDATED&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;TEMP&lt;/code&gt; members) and the forbidden-conditioning rule
(naming a surface is not licence to branch behavior on it).&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-06-19-1-coord-empty-surface-fallback/&quot;&gt;ADR 2026-06-19-1: coordination-worktree-empty surface policy&lt;/a&gt;
— the 2026-10-01 amendment governs &lt;code dir=&quot;auto&quot;&gt;PlacementSeam.write_dir&lt;/code&gt; and the per-state write behaviour; the
2026-06-21 amendment still governs the read-side loud fallback.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/4.x/2026-10-01-3-decision-ledger-primary-partition/&quot;&gt;ADR 2026-10-01-3: the decision ledger is a PRIMARY-partition kind&lt;/a&gt;
— the partition move in the worked example above.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;See also the &lt;code dir=&quot;auto&quot;&gt;Routing&lt;/code&gt; disambiguation in
&lt;a href=&quot;/context/orchestration/#routing&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/context/orchestration.md&lt;/code&gt;&lt;/a&gt; for every other sense of
“routing” this page deliberately does not cover, and
&lt;a href=&quot;/architecture/branch-target-routing/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;branch-target-routing.md&lt;/code&gt;&lt;/a&gt; for the &lt;strong&gt;branch&lt;/strong&gt; sense — which git
branch a commit lands on, a related but distinct question from the placement question this page
answers.&lt;/p&gt;</content>
</entry>
