<?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-19-1-coord-empty-surface-fallback/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-06-19-1-coord-empty-surface-fallback/</id>
  <title>ADR: Coordination-Worktree-Empty Surface Policy — Loud Primary Fallback (amended)</title>
  <updated>2026-10-01T00: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-19-1-coord-empty-surface-fallback/"/>
  <summary>Reads of an empty coordination worktree fall back loudly to the repository-root checkout; writes establish the coordination surface (amended 2026-10-01).</summary>
  <content type="html">&lt;p&gt;&lt;strong&gt;loud primary fallback&lt;/strong&gt; decision in the Amendment section below.
&lt;strong&gt;Mission&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;single-mission-surface-resolver-01KVGCE8&lt;/code&gt; (WP06, original) ·
&lt;code dir=&quot;auto&quot;&gt;mission-surface-resolver-safety-net-01KVN754&lt;/code&gt; (amendment)
&lt;strong&gt;Requirement&lt;/strong&gt;: FR-006 (&lt;code dir=&quot;auto&quot;&gt;#1716&lt;/code&gt;), bound to FR-001/FR-007 (single resolver)
&lt;strong&gt;Module&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/coordination/surface_resolver.py&lt;/code&gt;
&lt;strong&gt;Tracker&lt;/strong&gt;: &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1716&quot;&gt;#1716&lt;/a&gt;&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;amendment-2026-11-06-superseded-by-the-one-status-read-contract&quot;&gt;Amendment 2026-11-06: superseded by the one status read contract&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Newest amendment first, as in this file; the amendments below are unchanged history.&lt;/strong&gt;
Mission &lt;code dir=&quot;auto&quot;&gt;lane-worktree-model-hardening-01M6QY1M&lt;/code&gt; (S1, #7277), Proposed until the operator accepts
&lt;a href=&quot;/adr/4.x/2026-11-06-2-one-status-read-contract/&quot;&gt;ADR 2026-11-06-2&lt;/a&gt;.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Read side superseded for status reads.&lt;/strong&gt; An empty or unmaterialized coordination worktree no
longer falls back to the repository root checkout, loudly or otherwise. The one status read door
reads the committed coordination branch (&lt;code dir=&quot;auto&quot;&gt;COORD_BRANCH_REF&lt;/code&gt;); a missing or unreadable ref raises
&lt;code dir=&quot;auto&quot;&gt;StatusSurfaceRefUnreadable&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Reversed requirements.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;coord-artifact-single-home-01M3V4BE#C-002&lt;/code&gt; (keep the read-side fallback)
and the “retained read-side fallback” part of &lt;code dir=&quot;auto&quot;&gt;#FR-017&lt;/code&gt; are reversed by ADR 2026-11-06-2.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Unchanged.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;CoordinationBranchDeleted&lt;/code&gt; for a deleted coordination branch, and the write side of
the 2026-10-01 amendment (single home, &lt;code dir=&quot;auto&quot;&gt;write_dir&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;Do not implement the read-side fallback from the amendments below.&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;h2 id=&quot;amendment-2026-10-01--mission-coord-artifact-single-home-01m3v4be&quot;&gt;Amendment (2026-10-01 — mission &lt;code dir=&quot;auto&quot;&gt;coord-artifact-single-home-01M3V4BE&lt;/code&gt;)&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Newest amendment first; the 2026-06-21 amendment below is unchanged history.&lt;/strong&gt;&lt;/p&gt;
&lt;h3 id=&quot;status-of-this-amendment&quot;&gt;Status of this amendment&lt;/h3&gt;
&lt;p&gt;This amendment &lt;strong&gt;binds despite the frontmatter &lt;code dir=&quot;auto&quot;&gt;status: Superseded&lt;/code&gt;&lt;/strong&gt;. That status marks
the &lt;em&gt;original&lt;/em&gt; 2026-06-19 hard-fail decision as superseded by the 2026-06-21 amendment in
this same file; it does not retire either amendment. The read-side policy of the
2026-06-21 amendment is current, and so is this one. The read-side raise on
&lt;code dir=&quot;auto&quot;&gt;UNMATERIALIZED&lt;/code&gt; is recorded separately in
&lt;a href=&quot;/adr/3.x/2026-09-24-2-coord-read-fail-closed/&quot;&gt;ADR 2026-09-24-2&lt;/a&gt;, and the decision-ledger
reclassification in
&lt;a href=&quot;/adr/4.x/2026-10-01-3-decision-ledger-primary-partition/&quot;&gt;ADR 2026-10-01-3 (4.x)&lt;/a&gt;.
Do not implement from the original “Decision” section further down.&lt;/p&gt;
&lt;h3 id=&quot;amended-decision-writes-never-substitute-the-repository-root-checkout&quot;&gt;Amended decision: writes never substitute the repository root checkout&lt;/h3&gt;
&lt;p&gt;The 2026-06-21 loud fallback was written as a &lt;em&gt;read&lt;/em&gt; policy but behaved as a read-and-write
one: a writer that asked the read resolver for a COORD-partition directory and got the
declared PRIMARY-partition fallback wrote a Mission’s coordination record into the
repository root checkout, where the coordination branch never saw it. This amendment splits
the policy.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Single-home rule.&lt;/strong&gt; Every COORD-partition artifact of a coordination-routed Mission
(topology &lt;code dir=&quot;auto&quot;&gt;coord&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;lanes_with_coord&lt;/code&gt;, owned checkouts included) has exactly one
writable home: the coordination worktree on the coordination branch. A write obtains its
location only from &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&lt;/code&gt;),
the one sanctioned extension of the placement seam. For a COORD kind it delegates to
&lt;code dir=&quot;auto&quot;&gt;specify_cli.coordination.coord_seed.establish_coord_write_location&lt;/code&gt;, which owns
&lt;strong&gt;materialize, seed and refuse&lt;/strong&gt;. A writer never substitutes the repository root checkout
for the coordination surface, and &lt;code dir=&quot;auto&quot;&gt;read_dir&lt;/code&gt; is never a write location for a COORD kind.&lt;/p&gt;
&lt;h3 id=&quot;per-state-write-behaviour&quot;&gt;Per-state write behaviour&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;write_dir&lt;/code&gt; is placement routing (kind plus topology to a directory), not branch-target
routing; the commit ref still comes from &lt;code dir=&quot;auto&quot;&gt;write_target&lt;/code&gt;, and the two agree by construction.
The state is the four-way coordination probe plus the seed marker (the commit trailer
&lt;code dir=&quot;auto&quot;&gt;Spec-Kitty-Coordination-Seed: &amp;#x3C;mission_id&gt;&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;coord_seed.COORD_SEED_TRAILER&lt;/code&gt;).&lt;/p&gt;









































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Coordination state of the Mission&lt;/th&gt;&lt;th&gt;&lt;code dir=&quot;auto&quot;&gt;write_dir&lt;/code&gt; result&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;No coordination topology (&lt;code dir=&quot;auto&quot;&gt;lanes&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt;), or a PRIMARY-partition kind&lt;/td&gt;&lt;td&gt;The declared PRIMARY dir, byte-identical to &lt;code dir=&quot;auto&quot;&gt;read_dir&lt;/code&gt;. No side effects (C-008).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Published Mission, an E2-eligible COORD kind (&lt;code dir=&quot;auto&quot;&gt;REVIEW_CYCLE&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;TRACER_FILE&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;) or &lt;code dir=&quot;auto&quot;&gt;STATUS_STATE&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The PRIMARY Mission dir, checked before any coordination probe, so a torn-down coordination branch never raises here.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;MATERIALIZED&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The coordination Mission dir. No side effect unless a refused seed commit is pending, in which case the next write re-commits it.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;UNMATERIALIZED&lt;/code&gt;, branch present locally&lt;/td&gt;&lt;td&gt;Materialize the worktree first (once), then the &lt;code dir=&quot;auto&quot;&gt;MATERIALIZED&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;EMPTY&lt;/code&gt; row applies.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;UNMATERIALIZED&lt;/code&gt;, branch only on a remote&lt;/td&gt;&lt;td&gt;Refuse with &lt;code dir=&quot;auto&quot;&gt;COORDINATION_WORKTREE_UNMATERIALIZED&lt;/code&gt; and a recovery hint (parity with #4970). Nothing is written.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;EMPTY&lt;/code&gt;, no seed marker (Mission created before this fix)&lt;/td&gt;&lt;td&gt;Seed once under the status lock: one seed commit on the coordination branch, records restored from the repository root checkout by the prefix rule. A true fork refuses with &lt;code dir=&quot;auto&quot;&gt;COORD_SEED_FORK_REFUSED&lt;/code&gt;; a lock timeout refuses with &lt;code dir=&quot;auto&quot;&gt;STATUS_LOCK_HELD&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;EMPTY&lt;/code&gt;, seed marker present (a Mission created after this fix: a regression)&lt;/td&gt;&lt;td&gt;Loud &lt;code dir=&quot;auto&quot;&gt;WARNING&lt;/code&gt;, restore the COORD-kind paths from the coordination branch tip (never PRIMARY files), then write.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;DELETED&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;CoordinationBranchDeleted&lt;/code&gt;, unchanged.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3 id=&quot;read-side-unchanged-c-002&quot;&gt;Read side (unchanged, C-002)&lt;/h3&gt;
&lt;p&gt;Reads keep the loud declared PRIMARY fallback for &lt;code dir=&quot;auto&quot;&gt;EMPTY&lt;/code&gt; exactly as the 2026-06-21
amendment states, and &lt;code dir=&quot;auto&quot;&gt;UNMATERIALIZED&lt;/code&gt; keeps the ADR 2026-09-24-2 raise. The one read-side
change: the &lt;code dir=&quot;auto&quot;&gt;EMPTY&lt;/code&gt; warning now fires for post-fix Missions in &lt;strong&gt;both&lt;/strong&gt; coordination
topologies, because “post-fix” is discriminated by the seed-marker trailer rather than by
topology. Retiring the read fallback is a follow-up, not part of this amendment.&lt;/p&gt;
&lt;h3 id=&quot;create&quot;&gt;Create&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;mission create&lt;/code&gt; for a coordination-routed Mission materializes and seeds the coordination
worktree eagerly and commits the creation records on the coordination branch, so the target
branch never receives a COORD record. The expected divergence between the coordination
branch and the target branch is one shared predicate,
&lt;code dir=&quot;auto&quot;&gt;specify_cli.missions._create.is_expected_coordination_divergence&lt;/code&gt;, used by create and by
&lt;code dir=&quot;auto&quot;&gt;doctor coordination&lt;/code&gt;. Residual, named rather than fixed: an &lt;code dir=&quot;auto&quot;&gt;--owned-checkout&lt;/code&gt; create keeps
its status log in the owned checkout’s own PRIMARY dir exactly as before (INV-COORD-HOME).&lt;/p&gt;
&lt;h3 id=&quot;other-writers&quot;&gt;Other writers&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty consolidate&lt;/code&gt;.&lt;/strong&gt; A real run resolves its status directory through
&lt;code dir=&quot;auto&quot;&gt;write_dir(STATUS_STATE)&lt;/code&gt; before it takes the merge lock, so it materializes an
&lt;code dir=&quot;auto&quot;&gt;UNMATERIALIZED&lt;/code&gt; coordination surface (local branch) and proceeds, and seeds a pre-fix
&lt;code dir=&quot;auto&quot;&gt;EMPTY&lt;/code&gt; one. A remote-only branch, a fork, a deleted branch and a held status lock each
abort before any state change. &lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;--dry-run&lt;/code&gt; stays fail-closed and does not
materialize&lt;/strong&gt;: it keeps reading through the read seam and stops on
&lt;code dir=&quot;auto&quot;&gt;CoordinationBranchDeleted&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;CoordinationWorktreeUnmaterialized&lt;/code&gt;. The asymmetry is
deliberate; a preview must not create a worktree.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty materialize&lt;/code&gt;.&lt;/strong&gt; Regenerates derived views; for a coordination-routed Mission
it resolves the status directory through &lt;code dir=&quot;auto&quot;&gt;write_dir(STATUS_STATE)&lt;/code&gt;, so it creates the
coordination worktree (once) and seeds a pre-fix &lt;code dir=&quot;auto&quot;&gt;EMPTY&lt;/code&gt; one. A remote-only branch or a
forked log is reported in the error summary and the remaining Missions are still processed.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Commit routing.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;spec-commit&lt;/code&gt; and the other &lt;code dir=&quot;auto&quot;&gt;commit_for_mission&lt;/code&gt; consumers report one
outcome per surface and exit non-zero when any surface is refused
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/coordination/commit_outcome.py&lt;/code&gt;).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;enforcement&quot;&gt;Enforcement&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_no_write_side_rederivation.py&lt;/code&gt; carries a COORD-writer grammar:
a census of COORD writer functions must not compose a &lt;code dir=&quot;auto&quot;&gt;KITTY_SPECS_DIR&lt;/code&gt; path onto a
worktree-named operand, and must not derive a write location from a read resolver. The
allowlist is empty and its cap in &lt;code dir=&quot;auto&quot;&gt;tests/architectural/_baselines.yaml&lt;/code&gt; is 0.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Honest bound of that gate.&lt;/strong&gt; It scans only the bodies of the census functions, and it
flags a &lt;code dir=&quot;auto&quot;&gt;KITTY_SPECS_DIR&lt;/code&gt; join with a worktree-named operand. 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;
is outside that scan. That helper is documented for non-coordination checkouts only, so
the gate cannot see a misuse of it. The gate is not weakened for this; the bound is
recorded so a reviewer knows what the gate does not prove.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/integration/test_coord_single_home_workflow.py&lt;/code&gt; is the end-to-end invariant: one
status log, no COORD record on the target branch before consolidation, and the ledger
committed at its commit points.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;decision-ledger&quot;&gt;Decision ledger&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;DECISION_LEDGER&lt;/code&gt; moved from the COORD to the PRIMARY partition in the same Mission. That
reversal of the #3928 intent has its own record:
&lt;a href=&quot;/adr/4.x/2026-10-01-3-decision-ledger-primary-partition/&quot;&gt;ADR 2026-10-01-3 (4.x)&lt;/a&gt;. It is
linked, not restated, here. The consequence for this ADR is that &lt;code dir=&quot;auto&quot;&gt;decisions/&lt;/code&gt; is never
coordination residue and is never reset as such.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;amendment-2026-06-21--mission-mission-surface-resolver-safety-net-01kvn754&quot;&gt;Amendment (2026-06-21 — mission &lt;code dir=&quot;auto&quot;&gt;mission-surface-resolver-safety-net-01KVN754&lt;/code&gt;)&lt;/h2&gt;
&lt;h3 id=&quot;amended-decision-coord-empty--loud-primary-fallback-not-hard-fail&quot;&gt;Amended decision: coord-empty → &lt;strong&gt;loud primary fallback&lt;/strong&gt; (not hard-fail)&lt;/h3&gt;
&lt;p&gt;A &lt;strong&gt;materialized-but-empty coordination worktree NO LONGER hard-fails.&lt;/strong&gt; The
canonical resolver (&lt;code dir=&quot;auto&quot;&gt;resolve_status_surface_with_anchor&lt;/code&gt;) &lt;strong&gt;falls back to the
primary checkout surface and proceeds&lt;/strong&gt;, but emits a &lt;strong&gt;clear, structured,
operator-visible warning&lt;/strong&gt; at the fallback point. The read keeps working
(liveness); the staleness risk is made &lt;strong&gt;loud and observable&lt;/strong&gt; so a human
operator or an orchestrating agent can intervene (flatten or repair) if desired.&lt;/p&gt;
&lt;h3 id=&quot;why-the-reversal&quot;&gt;Why the reversal&lt;/h3&gt;
&lt;p&gt;The original decision (hard-fail, below) rejected primary fallback because it was
&lt;strong&gt;silent&lt;/strong&gt; — a silent stale read is the &lt;code dir=&quot;auto&quot;&gt;#1589&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;#1821&lt;/code&gt; split-brain bug. That
rejection rationale is sound &lt;em&gt;for a silent fallback&lt;/em&gt;. This amendment keeps the
fallback but &lt;strong&gt;removes the silence&lt;/strong&gt;: the operator-visible warning names the
stale-surface risk and &lt;strong&gt;both&lt;/strong&gt; recovery commands (collapse/flatten &lt;strong&gt;or&lt;/strong&gt;
&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent worktree repair --mission &amp;#x3C;slug&gt;&lt;/code&gt;). The split-brain hazard the
original feared is a &lt;em&gt;silent&lt;/em&gt; divergence; a &lt;em&gt;logged&lt;/em&gt; divergence the operator can
see and act on is a different, acceptable trade.&lt;/p&gt;
&lt;p&gt;Decisive field evidence: under the strict hard-fail, mission &lt;code dir=&quot;auto&quot;&gt;01KVFTFV&lt;/code&gt; was
forced to &lt;strong&gt;flatten&lt;/strong&gt; (drop &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt;) just to make progress — i.e.
the ADR’s own recovery path (a) became the routine workaround. A policy whose
escape hatch is the normal path is too strict for the operational reality;
liveness-with-observability is the better default.&lt;/p&gt;
&lt;h3 id=&quot;scope-of-the-amendment-binding&quot;&gt;Scope of the amendment (binding)&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Applies to the coord-empty state only&lt;/strong&gt;, at the canonical resolver seam.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Unchanged — still resolve primary (benign):&lt;/strong&gt; the create→first-write window
and the no-coord topology (these were never hard-fails).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Unchanged — still HARD-FAIL (do not soften):&lt;/strong&gt; the &lt;strong&gt;coord-deleted&lt;/strong&gt; state
(&lt;code dir=&quot;auto&quot;&gt;CoordinationBranchDeleted&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;#1848&lt;/code&gt;). A declared-but-deleted coord branch
carrying unmerged status is &lt;strong&gt;data loss&lt;/strong&gt;, categorically worse than staleness;
it must keep failing closed. Loud fallback is for &lt;em&gt;empty&lt;/em&gt;, never for &lt;em&gt;deleted&lt;/em&gt;.&lt;/li&gt;
&lt;li&gt;The warning is &lt;strong&gt;non-silent and load-bearing&lt;/strong&gt;: a test asserts it fires on the
coord-empty path (the fallback must be observable, not best-effort).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;consequence-for-the-typed-error-surface&quot;&gt;Consequence for the typed-error surface&lt;/h3&gt;
&lt;p&gt;Coord-empty stops raising &lt;code dir=&quot;auto&quot;&gt;CoordinationWorktreeEmpty&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;STATUS_READ_PATH_NOT_FOUND&lt;/code&gt;
and instead returns the primary dir + warning. Callers that previously caught the
coord-empty hard-fail now receive a successful (warned) read. The genuinely
unresolvable / ambiguous cases still raise their typed errors (this mission’s
typed-error-pass-through requirement is unaffected — coord-empty simply leaves
the error class).&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;The original 2026-06-19 decision and its alternatives are retained below as
historical record. Where they say “hard-fail on coord-empty”, read “superseded
by the loud primary fallback above”.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h3 id=&quot;stale-reference-correction-2026-06-21&quot;&gt;Stale reference correction (2026-06-21)&lt;/h3&gt;
&lt;p&gt;The original “Read-CLI residual (#2046)” consequence below is &lt;strong&gt;stale&lt;/strong&gt;: #2046 is
&lt;strong&gt;closed and fixed&lt;/strong&gt;. The operator read CLIs (&lt;code dir=&quot;auto&quot;&gt;agent tasks status&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;agent context&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;agent mission&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;decision&lt;/code&gt;) now route through the unified
&lt;code dir=&quot;auto&quot;&gt;missions/_read_path_resolver.resolve_handle_to_read_path&lt;/code&gt;, which consumes the
&lt;code dir=&quot;auto&quot;&gt;resolve_declared_mid8&lt;/code&gt; cascade — so a bare-slug handle against a coord-topology
mission resolves its mid8 instead of silently reading primary. (&lt;code dir=&quot;auto&quot;&gt;acceptance&lt;/code&gt;
deliberately retains the lower &lt;code dir=&quot;auto&quot;&gt;resolve_mission_read_path&lt;/code&gt; with an explicit mid8
— the lenient acceptance-lane carve-out, blessed by the FR-010 selection guard.)
Mission &lt;code dir=&quot;auto&quot;&gt;mission-surface-resolver-safety-net-01KVN754&lt;/code&gt; does not re-do that work;
its differential characterization test &lt;strong&gt;verifies and regression-guards&lt;/strong&gt; the
fix (the four &lt;code dir=&quot;auto&quot;&gt;coord-*/bare&lt;/code&gt; cells).&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;A Spec Kitty mission’s status surface (&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt;) lives in exactly one of two places, decided by topology:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&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; — for missions with no
coordination branch (and during the create→first-write window).&lt;/li&gt;
&lt;li&gt;&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/kitty-specs/&amp;#x3C;slug&gt;-&amp;#x3C;mid8&gt;/&lt;/code&gt;
— for coord-topology missions, where lane processes write through
&lt;code dir=&quot;auto&quot;&gt;BookkeepingTransaction&lt;/code&gt; and lanes sparse-exclude the status files.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;There is a hazardous intermediate topology state — &lt;strong&gt;coord-empty&lt;/strong&gt;: the mission
declares &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; in its primary &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;, the coordination
worktree ROOT has been materialized on disk, but it carries &lt;strong&gt;no mission dir&lt;/strong&gt;
(no status surface yet). This is distinct from two adjacent, benign states:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;create→first-write window&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; declared, coord worktree
root &lt;strong&gt;not&lt;/strong&gt; materialized. The primary checkout legitimately holds the
bootstrap status events; reading primary is correct.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;no-coord&lt;/strong&gt; — no &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; at all. Primary is the sole,
authoritative, non-divergent surface.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Historically the resolver’s coord-empty path either fell back to the primary
checkout (exposing a stale, split-brain status surface — the &lt;code dir=&quot;auto&quot;&gt;#1589&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;#1821&lt;/code&gt;
class) or raised a &lt;em&gt;bare&lt;/em&gt; &lt;code dir=&quot;auto&quot;&gt;StatusReadPathNotFound&lt;/code&gt; with no operator guidance.&lt;/p&gt;
&lt;p&gt;Before this mission the same coord-vs-primary selection was duplicated across
several resolvers (the read-path resolver, the surface resolver, the aggregate,
the mission-runtime boundary, and a 5th path-shape predicate site in
&lt;code dir=&quot;auto&quot;&gt;status_transition.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;#1900&lt;/code&gt;). A policy that lived in only one of those
copies would silently diverge.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;A &lt;strong&gt;materialized-but-empty coordination worktree HARD-FAILS&lt;/strong&gt;. The single
canonical resolver (&lt;code dir=&quot;auto&quot;&gt;coordination.surface_resolver.resolve_status_surface_with_anchor&lt;/code&gt;
— FR-001/FR-007’s sole selection authority) raises &lt;code dir=&quot;auto&quot;&gt;CoordinationWorktreeEmpty&lt;/code&gt;,
a carve-out of &lt;code dir=&quot;auto&quot;&gt;StatusReadPathNotFound&lt;/code&gt; that:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Carries the same &lt;code dir=&quot;auto&quot;&gt;error_code&lt;/code&gt;&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;STATUS_READ_PATH_NOT_FOUND&lt;/code&gt;) so every
existing &lt;code dir=&quot;auto&quot;&gt;except StatusReadPathNotFound&lt;/code&gt; fail-closed handler keeps catching
it and every caller that routes on the stable code keeps working. (This
mirrors the sibling &lt;code dir=&quot;auto&quot;&gt;CoordinationBranchDeleted&lt;/code&gt; carve-out for the
coord-deleted state, &lt;code dir=&quot;auto&quot;&gt;#1848&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;#1889&lt;/code&gt; R3.)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Names BOTH operator recovery paths&lt;/strong&gt; in its message (NFR-004 — errors are
actionable):
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;(a) collapse/flatten&lt;/strong&gt; the mission — remove the &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt;
key from &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; so the primary checkout becomes authoritative; &lt;strong&gt;OR&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;(b) recreate/populate&lt;/strong&gt; the coordination worktree — run
&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent worktree repair --mission &amp;#x3C;slug&gt;&lt;/code&gt; so it carries the
mission status surface.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Never silently falls back to the primary checkout.&lt;/strong&gt; Reading primary here
would expose a stale, split-brain status surface — the exact failure class
the single-resolver mission exists to eliminate (FR-005/FR-006).&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The hard-fail fires for &lt;strong&gt;both&lt;/strong&gt; mission-handle forms — a bare &lt;code dir=&quot;auto&quot;&gt;--mission &amp;#x3C;slug&gt;&lt;/code&gt;
and the canonical &lt;code dir=&quot;auto&quot;&gt;--mission &amp;#x3C;slug&gt;-&amp;#x3C;mid8&gt;&lt;/code&gt; — so the policy is handle-invariant.&lt;/p&gt;
&lt;p&gt;This policy is &lt;strong&gt;bound to the single resolver&lt;/strong&gt;: because FR-001/FR-007 collapsed
selection to &lt;code dir=&quot;auto&quot;&gt;resolve_status_surface_with_anchor&lt;/code&gt; (and the &lt;code dir=&quot;auto&quot;&gt;#1900&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;status_transition.py&lt;/code&gt; predicates were migrated to it, draining the C-002
topology-ratchet allowlist entry), there is exactly one place the coord-empty
decision is made, and no parallel resolver can contradict it.&lt;/p&gt;
&lt;h2 id=&quot;distinctions-preserved-what-does-not-hard-fail&quot;&gt;Distinctions preserved (what does NOT hard-fail)&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;create→first-write window&lt;/strong&gt; (coord declared, worktree NOT materialized) →
the resolver composes the coord path and the aggregate’s create-window gate
keeps the &lt;strong&gt;primary checkout authoritative&lt;/strong&gt; until the worktree exists. A
regression that hard-failed here would break first-write on a freshly created
coord mission. (Mutation-guarded by the equivalence test’s
&lt;code dir=&quot;auto&quot;&gt;test_create_first_write_window_resolves_primary&lt;/code&gt; and the surface-collapse
test’s &lt;code dir=&quot;auto&quot;&gt;test_create_window_unmaterialized_coord_resolves_primary&lt;/code&gt;.)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;no-coord&lt;/strong&gt; → primary is authoritative; no hard-fail.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;coord-deleted&lt;/strong&gt; (branch declared but deleted from git) → the distinct
&lt;code dir=&quot;auto&quot;&gt;CoordinationBranchDeleted&lt;/code&gt; carve-out (&lt;code dir=&quot;auto&quot;&gt;#1848&lt;/code&gt;), not coord-empty.&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;Positive.&lt;/strong&gt; A genuinely broken coordination topology is surfaced &lt;strong&gt;loudly
and actionably&lt;/strong&gt; rather than silently degrading to a stale primary read. The
operator is handed two concrete recovery commands. The policy is single-sourced
on the canonical resolver, so it cannot drift across the (former) duplicate
selection sites.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Bounded backward-compatibility.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;CoordinationWorktreeEmpty&lt;/code&gt; subclasses
&lt;code dir=&quot;auto&quot;&gt;StatusReadPathNotFound&lt;/code&gt; and reuses its &lt;code dir=&quot;auto&quot;&gt;error_code&lt;/code&gt;, so existing fail-closed
handlers and code-based routing are unaffected; only the diagnostic is richer.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Known scope boundary.&lt;/strong&gt; The &lt;code dir=&quot;auto&quot;&gt;MissionStatus&lt;/code&gt; aggregate continues to translate
the resolver’s fail-closed signal to its own single boundary exception
(&lt;code dir=&quot;auto&quot;&gt;CoordAuthorityUnavailable&lt;/code&gt;, WP04/FR-015–FR-023) for every handle form — a
separately-tested public contract used by the &lt;code dir=&quot;auto&quot;&gt;agent status&lt;/code&gt; CLI. Converging
the aggregate’s &lt;em&gt;exception type&lt;/em&gt; with the resolver’s is therefore deferred (it
would regress that boundary), and the corresponding equivalence-matrix cells
remain documented, allowlisted strict-xfails (see
&lt;code dir=&quot;auto&quot;&gt;tests/missions/test_surface_resolution_equivalence.py&lt;/code&gt;). The user-facing
FR-006 two-path message is delivered regardless, at the resolver seam.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Read-CLI residual (#2046).&lt;/strong&gt; The operator read CLIs (&lt;code dir=&quot;auto&quot;&gt;agent tasks status&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;agent context&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;agent mission&lt;/code&gt;) call the lower &lt;code dir=&quot;auto&quot;&gt;resolve_mission_read_path&lt;/code&gt;
primitive directly and are mid8-blind for a &lt;strong&gt;bare slug&lt;/strong&gt;, so a bare-slug
handle against a coord-topology mission still resolves the primary checkout
rather than hard-failing here. Closing this needs the &lt;code dir=&quot;auto&quot;&gt;resolve_declared_mid8&lt;/code&gt;
cascade inside the read path; it is tracked in &lt;strong&gt;#2046&lt;/strong&gt; (the earlier deferral
to the now-closed #1918 was incorrect, found by the post-merge architecture
review). The four &lt;code dir=&quot;auto&quot;&gt;coord-*/bare&lt;/code&gt; equivalence-matrix cells are its acceptance gate.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;alternatives-considered&quot;&gt;Alternatives considered&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Silent primary fallback.&lt;/strong&gt; Rejected: it is the split-brain bug
(&lt;code dir=&quot;auto&quot;&gt;#1589&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;#1821&lt;/code&gt;) this mission exists to kill — a coord-declared mission that
reads a stale primary surface mis-reports WP lane state.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Bare &lt;code dir=&quot;auto&quot;&gt;StatusReadPathNotFound&lt;/code&gt; with no guidance.&lt;/strong&gt; Rejected: dead-ends the
operator (violates NFR-004). The recovery is non-obvious (collapse vs
repair), so the message must spell out both.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Auto-repair (silently recreate/populate the worktree).&lt;/strong&gt; Rejected: the
resolver is a read-side authority; mutating topology as a side effect of a
read would be surprising and could mask a genuine teardown the operator
intended. The repair path is offered as an explicit command instead.&lt;/li&gt;
&lt;/ol&gt;</content>
</entry>
