<?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-09-24-2-coord-read-fail-closed/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-09-24-2-coord-read-fail-closed/</id>
  <title>ADR: the placement read seam raises on an unmaterialized coordination worktree</title>
  <updated>2026-10-02T00: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-09-24-2-coord-read-fail-closed/"/>
  <summary>A coord-partition read on CoordState.UNMATERIALIZED now raises CoordinationWorktreeUnmaterialized instead of silently substituting an empty PRIMARY path.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;mission_runtime.resolution._classify_artifact_surface&lt;/code&gt; is the single classifier that
turns a mission’s four-state coordination probe (&lt;code dir=&quot;auto&quot;&gt;specify_cli.missions._read_path_resolver .CoordState&lt;/code&gt;) into a read decision for a coord-partition artifact kind (&lt;code dir=&quot;auto&quot;&gt;STATUS_STATE&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;ISSUE_MATRIX&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;ACCEPTANCE_MATRIX&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;DECISION_LOG&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;TRACER_FILE&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;REVIEW_CYCLE&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;DECISION_LEDGER&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;DECISION_LEDGER&lt;/code&gt; was reclassified to the PRIMARY partition on
2026-10-01, see &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; and
&lt;a href=&quot;/adr/4.x/2026-10-01-3-decision-ledger-primary-partition/&quot;&gt;the 4.x ADR&lt;/a&gt;). Before this ADR, the classifier’s tail read:&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;python&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:#C792EA;--1:#8844AE&quot;&gt;if&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; coord_state &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;is&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; CoordState.&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;DELETED&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:#C792EA;--1:#8844AE&quot;&gt;raise&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; CoordinationBranchDeleted.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;for_mission&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;...&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:#C792EA;--1:#8844AE&quot;&gt;if&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; coord_state &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;is&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; CoordState.&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;MATERIALIZED&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:#C792EA;--1:#8844AE&quot;&gt;return&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; TopologySurface.&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;COORD&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;, &lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;coord_feature_dir&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;...&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:#919F9F;--1:#5F636F&quot;&gt;# EMPTY / UNMATERIALIZED / NONE -&gt; primary + PRIMARY stamp&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:#C792EA;--1:#8844AE&quot;&gt;return&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; TopologySurface.&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;PRIMARY&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;None&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;CoordState.UNMATERIALIZED&lt;/code&gt; names the state where &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; declares a
&lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; that still exists in git, but the coordination worktree itself has
never been created on disk — the fresh-clone / CI-runner / removed-worktree window between
&lt;code dir=&quot;auto&quot;&gt;mission create&lt;/code&gt; and the mission’s first coordination-branch write. In that state the
classifier fell through to the same &lt;code dir=&quot;auto&quot;&gt;TopologySurface.PRIMARY, None&lt;/code&gt; answer as the
genuinely-benign &lt;code dir=&quot;auto&quot;&gt;EMPTY&lt;/code&gt; (coord root present, mission dir absent) and &lt;code dir=&quot;auto&quot;&gt;NONE&lt;/code&gt; (no
coordination topology at all) states — an &lt;strong&gt;empty-PRIMARY substitution&lt;/strong&gt;: a coord-partition
read resolves to the primary checkout, which typically has no copy of the coord-owned
artifact, so the read comes back empty.&lt;/p&gt;
&lt;p&gt;A caller with no special handling treats that empty result as “this document has never been
written” rather than “the authoritative surface for this document could not be reached
right now.” The consequence is not merely a &lt;code dir=&quot;auto&quot;&gt;None&lt;/code&gt;/empty return silently absorbed
somewhere: &lt;code dir=&quot;auto&quot;&gt;retrospective.tracer_writer._read_current_coord_content&lt;/code&gt; catches the resulting
&lt;code dir=&quot;auto&quot;&gt;StatusReadPathNotFound&lt;/code&gt;-family exceptions (via &lt;code dir=&quot;auto&quot;&gt;_NO_EXISTING_CONTENT_EXCEPTIONS&lt;/code&gt;), maps
them to &lt;code dir=&quot;auto&quot;&gt;&quot;&quot;&lt;/code&gt;, and the tracer writer then &lt;strong&gt;clobbers&lt;/strong&gt; a real coord-side trace file’s header
from that empty baseline the next time it writes — a destructive read-then-write, not
merely a stale read. Roughly two dozen other coord &lt;code dir=&quot;auto&quot;&gt;STATUS_STATE&lt;/code&gt; readers with no catch of
their own would, after this fix, propagate the new raise instead of quietly reading empty;
each of those is the intended “desired fail-loud” outcome this ADR names (see Consequences).&lt;/p&gt;
&lt;p&gt;The sibling &lt;code dir=&quot;auto&quot;&gt;CoordState.DELETED&lt;/code&gt; state already fails closed (&lt;code dir=&quot;auto&quot;&gt;CoordinationBranchDeleted&lt;/code&gt;,
#4403/#1848) precisely because a deleted coord branch carrying unmerged status is data
loss. &lt;code dir=&quot;auto&quot;&gt;UNMATERIALIZED&lt;/code&gt; is a different failure shape — the branch is not lost, only not yet
checked out — but it shares the same defect class as &lt;code dir=&quot;auto&quot;&gt;DELETED&lt;/code&gt; once compared against what
&lt;code dir=&quot;auto&quot;&gt;EMPTY&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;NONE&lt;/code&gt; actually mean: &lt;code dir=&quot;auto&quot;&gt;EMPTY&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;NONE&lt;/code&gt; are declared, expected steady states (a
mission that never took the coordination branch, or one whose coord worktree the operator
legitimately flattened); &lt;code dir=&quot;auto&quot;&gt;UNMATERIALIZED&lt;/code&gt; is a &lt;strong&gt;transitional&lt;/strong&gt; window where the
authoritative surface unambiguously exists but is not yet reachable from this checkout, and
substituting empty-PRIMARY silently discards that distinction.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;The placement read seam raises a new typed error, &lt;code dir=&quot;auto&quot;&gt;CoordinationWorktreeUnmaterialized&lt;/code&gt;,
for a coord-partition read on &lt;code dir=&quot;auto&quot;&gt;CoordState.UNMATERIALIZED&lt;/code&gt;, instead of returning the
empty-PRIMARY substitution.&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;CoordinationWorktreeUnmaterialized&lt;/code&gt; is added to
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/coordination/surface_resolver.py&lt;/code&gt;, as a &lt;code dir=&quot;auto&quot;&gt;StatusReadPathNotFound&lt;/code&gt;
subclass sitting beside the existing &lt;code dir=&quot;auto&quot;&gt;CoordinationBranchDeleted&lt;/code&gt; — mirroring its shape
(&lt;code dir=&quot;auto&quot;&gt;error_code&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;next_step&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;for_mission(...)&lt;/code&gt; factory) so every existing
&lt;code dir=&quot;auto&quot;&gt;except StatusReadPathNotFound&lt;/code&gt; handler (the sanctioned read-only degraders in
&lt;code dir=&quot;auto&quot;&gt;mission_runtime.read_dir_degrade&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;review.cycle&lt;/code&gt;, plus every other absorbing
catcher) keeps catching it unchanged.&lt;/li&gt;
&lt;li&gt;Its &lt;code dir=&quot;auto&quot;&gt;error_code&lt;/code&gt; is &lt;code dir=&quot;auto&quot;&gt;COORDINATION_WORKTREE_UNMATERIALIZED&lt;/code&gt; (distinct from
&lt;code dir=&quot;auto&quot;&gt;COORDINATION_BRANCH_DELETED&lt;/code&gt;) and its &lt;code dir=&quot;auto&quot;&gt;next_step&lt;/code&gt; names the truthful recovery —
&lt;strong&gt;materialize&lt;/strong&gt; the coordination worktree (it self-materializes on the mission’s first
coordination-branch write, or an operator can force it via
&lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor workspaces --fix&lt;/code&gt;) — and explicitly does &lt;strong&gt;not&lt;/strong&gt; suggest flattening
the mission, which would be a false and destructive recovery for a branch that still
exists.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;mission_runtime.resolution._classify_artifact_surface&lt;/code&gt; gains one new branch:
&lt;code dir=&quot;auto&quot;&gt;if coord_state is CoordState.UNMATERIALIZED: raise CoordinationWorktreeUnmaterialized.for_mission(...)&lt;/code&gt;, inserted between the existing
&lt;code dir=&quot;auto&quot;&gt;DELETED&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;MATERIALIZED&lt;/code&gt;/fall-through arms. &lt;code dir=&quot;auto&quot;&gt;DELETED&lt;/code&gt; -&gt; &lt;code dir=&quot;auto&quot;&gt;CoordinationBranchDeleted&lt;/code&gt;
and &lt;code dir=&quot;auto&quot;&gt;MATERIALIZED&lt;/code&gt; -&gt; &lt;code dir=&quot;auto&quot;&gt;TopologySurface.COORD&lt;/code&gt; are unchanged.&lt;/li&gt;
&lt;li&gt;The scope is &lt;strong&gt;coord-partition reads only&lt;/strong&gt;. A PRIMARY-partition kind (for example
&lt;code dir=&quot;auto&quot;&gt;PRIMARY_METADATA&lt;/code&gt;) short-circuits to &lt;code dir=&quot;auto&quot;&gt;TopologySurface.PRIMARY&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;declared_read_surface&lt;/code&gt;
before any coordination probe runs, so this change is structurally invisible to it — no
new raise, no behavior change, for every non-coord-routing topology and every
PRIMARY-partition artifact.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;EMPTY&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;NONE&lt;/code&gt; are explicitly &lt;strong&gt;out of scope&lt;/strong&gt; and keep returning the declared
&lt;code dir=&quot;auto&quot;&gt;PRIMARY&lt;/code&gt; surface unchanged. They are not the reported defect (#4959): &lt;code dir=&quot;auto&quot;&gt;NONE&lt;/code&gt; is a
coord-less mission that never had a coordination branch to fail to reach, and &lt;code dir=&quot;auto&quot;&gt;EMPTY&lt;/code&gt; is
a materialized-but-vacant coord root the project already treats as an operator-decided,
loud-warned degrade (&lt;code dir=&quot;auto&quot;&gt;docs/adr/3.x/2026-06-19-1-coord-empty-surface-fallback.md&lt;/code&gt;).
Folding either into this raise would widen the mission beyond the audited blast radius.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Coord readers now fail loud on the transitional window.&lt;/strong&gt; Any coord-partition
&lt;code dir=&quot;auto&quot;&gt;read_dir&lt;/code&gt; (via &lt;code dir=&quot;auto&quot;&gt;mission_runtime.PlacementSeam.read_dir&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;resolve_artifact_surface&lt;/code&gt;) issued while the coordination worktree has not yet been
materialized now raises &lt;code dir=&quot;auto&quot;&gt;CoordinationWorktreeUnmaterialized&lt;/code&gt; instead of silently handing
back an empty PRIMARY path. Callers that already catch &lt;code dir=&quot;auto&quot;&gt;StatusReadPathNotFound&lt;/code&gt; (or its
known subclasses) absorb this unchanged; the roughly two dozen coord &lt;code dir=&quot;auto&quot;&gt;STATUS_STATE&lt;/code&gt;
readers with no catch of their own now propagate the raise to a caller boundary, which is
the intended fail-loud outcome — each was audited (research.md) to land at a sane
boundary rather than a raw traceback.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Sanctioned read-only degraders keep degrading.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;mission_runtime.read_dir_degrade&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;review.cycle&lt;/code&gt;’s existing &lt;code dir=&quot;auto&quot;&gt;except StatusReadPathNotFound&lt;/code&gt; blocks absorb the new sibling
exception exactly as they already absorb &lt;code dir=&quot;auto&quot;&gt;CoordinationBranchDeleted&lt;/code&gt; — no regression for
non-destructive reads (NFR-002).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The tracer-writer clobber this mission set out to close is a separate, dependent fix.&lt;/strong&gt;
&lt;code dir=&quot;auto&quot;&gt;retrospective.tracer_writer._read_current_coord_content&lt;/code&gt;’s narrowed catch (so a
coord-topology unresolved/unmaterialized read propagates instead of degrading to &lt;code dir=&quot;auto&quot;&gt;&quot;&quot;&lt;/code&gt;) is
scoped to a later work package in this mission, not this ADR’s change alone — this ADR
only makes the underlying seam raise; the writer must still choose to let that raise
through rather than catch-and-clobber.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;_coord_branch_exists&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;surface_resolver.py&lt;/code&gt;) is untouched.&lt;/strong&gt; The new exception class
is a pure addition beside &lt;code dir=&quot;auto&quot;&gt;CoordinationBranchDeleted&lt;/code&gt;; no existing function in
&lt;code dir=&quot;auto&quot;&gt;surface_resolver.py&lt;/code&gt;, including the &lt;code dir=&quot;auto&quot;&gt;#4979&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;#4950&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;_coord_branch_exists&lt;/code&gt; surface, was
modified.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The write side is governed separately (amended 2026-10-01).&lt;/strong&gt; The raise above is
unchanged and applies to reads. Writes of a coordination-routed Mission take their
location from &lt;code dir=&quot;auto&quot;&gt;PlacementSeam.write_dir&lt;/code&gt;, which materializes a locally-present
coordination branch and refuses a remote-only one with
&lt;code dir=&quot;auto&quot;&gt;COORDINATION_WORKTREE_UNMATERIALIZED&lt;/code&gt;, and never substitutes the PRIMARY partition or the
repository root checkout. See the 2026-10-01 amendment in
&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;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A future contributor extending the UNMATERIALIZED raise to &lt;code dir=&quot;auto&quot;&gt;EMPTY&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;NONE&lt;/code&gt;&lt;/strong&gt; must revisit
the coord-empty loud-fallback ADR (&lt;code dir=&quot;auto&quot;&gt;2026-06-19-1&lt;/code&gt;) first — those states carry their own,
separately adjudicated policy and are not silently absorbed into this decision.&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;Reuse &lt;code dir=&quot;auto&quot;&gt;CoordinationBranchDeleted&lt;/code&gt; for &lt;code dir=&quot;auto&quot;&gt;UNMATERIALIZED&lt;/code&gt;.&lt;/strong&gt; Rejected — its &lt;code dir=&quot;auto&quot;&gt;next_step&lt;/code&gt;
recommends flattening the mission, which is false and destructive when the coordination
branch is fully intact and merely not yet checked out.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fix at the reader level only (e.g. only &lt;code dir=&quot;auto&quot;&gt;tracer_writer&lt;/code&gt;).&lt;/strong&gt; Rejected by operator
decision (DM-01M38VWD) — a reader-local fix closes one symptom but leaves every other
coord-partition reader silently substituting empty-PRIMARY on the same transitional
window, reopening the same defect class the next time a new reader is added.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Widen the raise to cover &lt;code dir=&quot;auto&quot;&gt;EMPTY&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;NONE&lt;/code&gt; as well.&lt;/strong&gt; Rejected as out of scope — both
are declared, expected steady states with their own existing policy; treating them as
errors would regress the coord-empty loud-fallback decision and the coord-less topology
path for no reported defect.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;references&quot;&gt;References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Mission &lt;code dir=&quot;auto&quot;&gt;kitty-specs/coord-read-fail-closed-01M38VVH/&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;research.md&lt;/code&gt; (Finding A),
&lt;code dir=&quot;auto&quot;&gt;contracts/seam-fail-closed-contract.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;data-model.md&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/resolution.py::_classify_artifact_surface&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;declared_read_surface&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;resolve_artifact_surface&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;PlacementSeam.read_dir&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/coordination/surface_resolver.py::CoordinationBranchDeleted&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;CoordinationWorktreeUnmaterialized&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/missions/_read_path_resolver.py::CoordState&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;probe_coord_state&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Sibling ADR: &lt;code dir=&quot;auto&quot;&gt;docs/adr/3.x/2026-06-19-1-coord-empty-surface-fallback.md&lt;/code&gt; (the &lt;code dir=&quot;auto&quot;&gt;EMPTY&lt;/code&gt;
policy this ADR leaves unchanged).&lt;/li&gt;
&lt;li&gt;Prior fail-closed precedent: &lt;code dir=&quot;auto&quot;&gt;#4403&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;#1848&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;CoordinationBranchDeleted&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;DELETED&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;This mission: &lt;code dir=&quot;auto&quot;&gt;#4959&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Regression coverage: &lt;code dir=&quot;auto&quot;&gt;tests/mission_runtime/test_coord_read_seam.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;tests/mission_runtime/test_resolution_typed_errors.py&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
