<?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-05-1-merge-publish-layer-boundary/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-06-05-1-merge-publish-layer-boundary/</id>
  <title>ADR: Merge Publish-Layer Boundary</title>
  <updated>2026-06-05T00: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-05-1-merge-publish-layer-boundary/"/>
  <summary>Remote-state inspection moves to the publish layer, so local lane consolidation stays network-free and the `git fetch` preflight runs only under `--push`.</summary>
  <content type="html">&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty merge&lt;/code&gt; is a local operation: it sequences WP branches onto a
target branch using the local git graph only. No push is implied by the
core merge operation unless the caller explicitly requests &lt;code dir=&quot;auto&quot;&gt;--push&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;Prior to this ADR, &lt;code dir=&quot;auto&quot;&gt;merge.py&lt;/code&gt; called &lt;code dir=&quot;auto&quot;&gt;_enforce_target_branch_sync_preflight&lt;/code&gt;
unconditionally before any local mutation. That function performed a live
&lt;code dir=&quot;auto&quot;&gt;git fetch origin&lt;/code&gt; against the remote and raised &lt;code dir=&quot;auto&quot;&gt;MergeError&lt;/code&gt; when the local
target branch was ahead of, behind, or diverged from &lt;code dir=&quot;auto&quot;&gt;origin&lt;/code&gt;. This blocked
issue &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1706&quot;&gt;#1706&lt;/a&gt;: a
repository where the local &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; was legitimately ahead of &lt;code dir=&quot;auto&quot;&gt;origin/main&lt;/code&gt;
(e.g., post-merge with unsynced remote) could not run &lt;code dir=&quot;auto&quot;&gt;spec-kitty merge&lt;/code&gt; at
all, even when no push was intended.&lt;/p&gt;
&lt;p&gt;The root cause is a layer violation: push-safety is a publish concern and
belongs in the publish layer, not in the domain merge layer. The domain layer
should operate on the local git graph and remain entirely network-free.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;All remote-state inspection lives in &lt;code dir=&quot;auto&quot;&gt;push_preflight.py&lt;/code&gt;&lt;/strong&gt; (publish layer).
This module owns the &lt;code dir=&quot;auto&quot;&gt;git fetch&lt;/code&gt; call, the tracking-branch comparison, and
the &lt;code dir=&quot;auto&quot;&gt;is_safe_to_push&lt;/code&gt; predicate.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;preflight.py&lt;/code&gt; is domain-only&lt;/strong&gt; — local git graph checks (worktree
cleanliness, branch existence, conflict detection) with no network I/O.
Legacy remote-state re-export names are exposed lazily for transition
compatibility; importing &lt;code dir=&quot;auto&quot;&gt;preflight.py&lt;/code&gt; must not import &lt;code dir=&quot;auto&quot;&gt;push_preflight.py&lt;/code&gt;
at runtime.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;merge.py&lt;/code&gt; imports &lt;code dir=&quot;auto&quot;&gt;push_preflight&lt;/code&gt; conditionally&lt;/strong&gt;, only inside
&lt;code dir=&quot;auto&quot;&gt;if push:&lt;/code&gt; branches. The local merge path never touches &lt;code dir=&quot;auto&quot;&gt;push_preflight&lt;/code&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;is_safe_to_push&lt;/code&gt;&lt;/strong&gt; is the correct predicate for push-safety decisions.
It returns &lt;code dir=&quot;auto&quot;&gt;False&lt;/code&gt; for &lt;code dir=&quot;auto&quot;&gt;&quot;behind&quot;&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;&quot;diverged&quot;&lt;/code&gt; states. Both indicate
that remote commits are missing locally, so &lt;code dir=&quot;auto&quot;&gt;merge --push&lt;/code&gt; would perform
local merge/bookkeeping mutations before a known non-fast-forward push
rejection. The states &lt;code dir=&quot;auto&quot;&gt;&quot;ahead&quot;&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;&quot;in_sync&quot;&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;&quot;no_tracking_branch&quot;&lt;/code&gt;
are safe-to-push: ahead means the push will advance the remote normally;
no tracking branch means there is no remote to conflict with.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;is_safe&lt;/code&gt;&lt;/strong&gt; is a deprecated alias on &lt;code dir=&quot;auto&quot;&gt;TargetBranchSyncStatus&lt;/code&gt; that
always returns &lt;code dir=&quot;auto&quot;&gt;True&lt;/code&gt;. It existed to gate local merge operations on remote
state, which was incorrect — local merges do not require remote sync.
Callers making push decisions must migrate to &lt;code dir=&quot;auto&quot;&gt;is_safe_to_push&lt;/code&gt;.
&lt;em&gt;(Amended 2026-09-30: the alias had no remaining callers and was removed
in the 2026-09-30 dead-code sweep.)&lt;/em&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Domain layer is network-free.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;spec-kitty merge&lt;/code&gt; without &lt;code dir=&quot;auto&quot;&gt;--push&lt;/code&gt;
performs no &lt;code dir=&quot;auto&quot;&gt;git fetch&lt;/code&gt; and does not block when the local target is ahead
of or behind the remote.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Push-safety fires only when push is requested.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;check_push_safety()&lt;/code&gt;
in &lt;code dir=&quot;auto&quot;&gt;push_preflight.py&lt;/code&gt; is called only when &lt;code dir=&quot;auto&quot;&gt;merge.py&lt;/code&gt; is about to push to
the remote.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Issue #1706 is resolved.&lt;/strong&gt; A repository with a local &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; ahead of
&lt;code dir=&quot;auto&quot;&gt;origin/main&lt;/code&gt; can run &lt;code dir=&quot;auto&quot;&gt;spec-kitty merge&lt;/code&gt; without &lt;code dir=&quot;auto&quot;&gt;--push&lt;/code&gt; without error.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The &lt;code dir=&quot;auto&quot;&gt;is_safe&lt;/code&gt; predicate is deprecated.&lt;/strong&gt; It always returns &lt;code dir=&quot;auto&quot;&gt;True&lt;/code&gt; to
unblock callers during the transition; callers making push decisions must
switch to &lt;code dir=&quot;auto&quot;&gt;is_safe_to_push&lt;/code&gt;. &lt;em&gt;(Amended 2026-09-30: removed.)&lt;/em&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;rejected-alternatives&quot;&gt;Rejected Alternatives&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Add &lt;code dir=&quot;auto&quot;&gt;&quot;ahead&quot;&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;&quot;behind&quot;&lt;/code&gt; to the &lt;code dir=&quot;auto&quot;&gt;is_safe&lt;/code&gt; whitelist in
&lt;code dir=&quot;auto&quot;&gt;preflight.py&lt;/code&gt;&lt;/strong&gt;: bandaid. This would suppress the specific error in
#1706 but leaves the network call (&lt;code dir=&quot;auto&quot;&gt;git fetch&lt;/code&gt;) in the domain layer on
every local merge invocation, regardless of whether push is intended.
The coupling between local-merge and remote-state is the root cause; a
whitelist change does not remove it.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Guard the &lt;code dir=&quot;auto&quot;&gt;_enforce_target_branch_sync_preflight&lt;/code&gt; call with
&lt;code dir=&quot;auto&quot;&gt;if push:&lt;/code&gt;&lt;/strong&gt; in &lt;code dir=&quot;auto&quot;&gt;merge.py&lt;/code&gt;, without relocating the module**: this corrects
the call-site behavior but does not enforce the architectural boundary.
The fetch logic remains importable from &lt;code dir=&quot;auto&quot;&gt;preflight.py&lt;/code&gt;, making it easy
for future contributors to re-introduce the coupling accidentally.
Relocating to &lt;code dir=&quot;auto&quot;&gt;push_preflight.py&lt;/code&gt; makes the boundary structural and
enforced by the module’s import identity.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;references&quot;&gt;References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Issue: &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1706&quot;&gt;#1706&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Publish-layer module: &lt;a href=&quot;../../../src/specify_cli/consolidation/push_preflight.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/consolidation/push_preflight.py&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Domain-layer preflight: &lt;a href=&quot;../../../src/specify_cli/consolidation/preflight.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/consolidation/preflight.py&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Publish preflight tests: &lt;a href=&quot;../../../tests/consolidation/test_push_preflight.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;tests/consolidation/test_push_preflight.py&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
