<?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-21-1-protected-branch-config-boundary-resolved-value/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-06-21-1-protected-branch-config-boundary-resolved-value/</id>
  <title>Protected-branch configuration is a standalone boundary-resolved value, not a nested context sub-object</title>
  <updated>2026-06-21T00: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-21-1-protected-branch-config-boundary-resolved-value/"/>
  <summary>Protected-branch configuration resolves once into a standalone value object with `is_protected(ref)`, because the `safe-commit` deadlock site holds no mission context.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;The set of branches Spec Kitty refuses direct commits to (“protected branches”) is
hardcoded to &lt;code dir=&quot;auto&quot;&gt;{main, master}&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;git/commit_helpers.py:420&lt;/code&gt;), decided by &lt;strong&gt;branch name
only&lt;/strong&gt;, and re-read independently at ~8 callsites that each call
&lt;code dir=&quot;auto&quot;&gt;protected_branches(repo_root)&lt;/code&gt; (and re-shell &lt;code dir=&quot;auto&quot;&gt;git remote show origin&lt;/code&gt;). Two consequences:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Owners cannot configure it.&lt;/strong&gt; Any repo whose primary is named &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;master&lt;/code&gt;
deadlocks the sanctioned &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.specify&lt;/code&gt; flow (the #1619 P0); owners have no way
to declare intent.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The protection authority is scattered.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;coordination/policy.py&lt;/code&gt; even documents
itself as “the single chokepoint for protected-branch refusal” yet still re-reads the
set at &lt;code dir=&quot;auto&quot;&gt;:214&lt;/code&gt; — a live #1868 “authority in name only” instance.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The mission must make the protected set &lt;strong&gt;owner-configurable&lt;/strong&gt; (declared in &lt;code dir=&quot;auto&quot;&gt;.kittify&lt;/code&gt;
config, default unchanged), &lt;strong&gt;resolved once at the outermost boundary&lt;/strong&gt;, and &lt;strong&gt;propagated
inward&lt;/strong&gt; so core logic stops touching git/filesystem for the protection decision (the
mission’s pillar C, FR-007/008/009/010).&lt;/p&gt;
&lt;p&gt;The architectural question this ADR settles: &lt;strong&gt;what object carries the resolved
protected-branch set, and how does it reach the decision callsites?&lt;/strong&gt; The initial proposal
was to introduce a new &lt;code dir=&quot;auto&quot;&gt;EnvironmentContext&lt;/code&gt; and &lt;strong&gt;nest it as a sub-object on an existing
context&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;ExecutionContext&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;WorkspaceContext&lt;/code&gt;) for reuse and propagation.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;The boundary must be reachable from &lt;strong&gt;every&lt;/strong&gt; protection callsite — above all the
deadlock site, the standalone &lt;code dir=&quot;auto&quot;&gt;spec-kitty safe-commit&lt;/code&gt; process.&lt;/li&gt;
&lt;li&gt;“Resolve once at the boundary, propagate inward; no core git/fs reads after” (FR-007/
NFR-003).&lt;/li&gt;
&lt;li&gt;Single authority + an enforceable regression guard (FR-010 / #1868).&lt;/li&gt;
&lt;li&gt;Minimal coupling and no premature abstraction; the change must not balloon into a
config-loader unification refactor.&lt;/li&gt;
&lt;li&gt;Reuse what already exists rather than reinventing decision machinery.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;A — Standalone boundary-resolved value object&lt;/strong&gt;, one &lt;code dir=&quot;auto&quot;&gt;resolve(repo_root)&lt;/code&gt; resolver,
passed explicitly, feeding the existing &lt;code dir=&quot;auto&quot;&gt;commit_guard.evaluate(ProtectionState)&lt;/code&gt; seam.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;B — &lt;code dir=&quot;auto&quot;&gt;EnvironmentContext&lt;/code&gt; nested as a sub-object on &lt;code dir=&quot;auto&quot;&gt;ExecutionContext&lt;/code&gt;&lt;/strong&gt; (the original
proposal) as the primary carrier.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;C — Nested on &lt;code dir=&quot;auto&quot;&gt;WorkspaceContext&lt;/code&gt;&lt;/strong&gt; (the per-WP, JSON-persisted context).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;D — No new object&lt;/strong&gt;: make &lt;code dir=&quot;auto&quot;&gt;protected_branches()&lt;/code&gt; read &lt;code dir=&quot;auto&quot;&gt;.kittify&lt;/code&gt; config (memoized) and
keep calling it at each site.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option: “A — standalone boundary-resolved value object”, with cohesive scope&lt;/strong&gt;
(carries &lt;code dir=&quot;auto&quot;&gt;protected_branches&lt;/code&gt;, the resolved &lt;code dir=&quot;auto&quot;&gt;operator_hatch_active&lt;/code&gt; hatch state, and an
&lt;code dir=&quot;auto&quot;&gt;is_protected(ref)&lt;/code&gt; method), because it is the only shape that reaches the deadlock callsite
and it adopts — rather than duplicates — the decision seam that already exists.&lt;/p&gt;
&lt;p&gt;The decisive fact, reached independently by four of the five squad agents (and conceded by
the fifth): &lt;strong&gt;no protection callsite holds a built &lt;code dir=&quot;auto&quot;&gt;ExecutionContext&lt;/code&gt; at the decision
point.&lt;/strong&gt; The deadlock site — &lt;code dir=&quot;auto&quot;&gt;spec-kitty safe-commit&lt;/code&gt; — is a standalone process with no
mission identity, and the only &lt;code dir=&quot;auto&quot;&gt;ExecutionContext&lt;/code&gt; factory (&lt;code dir=&quot;auto&quot;&gt;resolve_action_context&lt;/code&gt;) &lt;em&gt;requires&lt;/em&gt;
action+mission+wp and &lt;strong&gt;fails closed with no fallback&lt;/strong&gt;. A context-nested carrier (Options
B/C) therefore &lt;strong&gt;cannot reach the very callsite the mission exists to fix&lt;/strong&gt; without
fabricating a mission context that does not (and during the create→first-write window,
cannot) exist. Option C additionally serialises owner config into per-WP JSON snapshots —
a stale-config leak.&lt;/p&gt;
&lt;p&gt;The boundary-resolved &lt;em&gt;decision&lt;/em&gt; already exists: &lt;code dir=&quot;auto&quot;&gt;core/commit_guard.py&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;evaluate(target, ProtectionState(is_protected), capability)&lt;/code&gt; is pure/IO-free and takes a
&lt;code dir=&quot;auto&quot;&gt;ProtectionState&lt;/code&gt; computed at the boundary. The scattered part is only the &lt;strong&gt;input&lt;/strong&gt;. So
the mission lifts the input to a single resolver and routes the ~8 callsites through it —
no new decision machinery.&lt;/p&gt;
&lt;p&gt;The operator’s composition instinct is preserved but demoted: the value object &lt;strong&gt;may&lt;/strong&gt;
later be attached as an &lt;code dir=&quot;auto&quot;&gt;ExecutionContext&lt;/code&gt; fragment for the in-loop callers
(implement/tasks/accept) as a coherence improvement — explicitly &lt;strong&gt;not&lt;/strong&gt; the primary carrier
and not on this mission’s critical path.&lt;/p&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The deadlock callsite (&lt;code dir=&quot;auto&quot;&gt;safe_commit_cmd.py&lt;/code&gt;) resolves the policy at its own boundary
(where &lt;code dir=&quot;auto&quot;&gt;repo_root&lt;/code&gt; is known) and works without any mission context.&lt;/li&gt;
&lt;li&gt;One sanctioned resolver makes the FR-010 guard a clean grep boundary; &lt;code dir=&quot;auto&quot;&gt;coordination/policy.py&lt;/code&gt;
becomes a &lt;em&gt;real&lt;/em&gt; chokepoint instead of a named-only one.&lt;/li&gt;
&lt;li&gt;Reuses the existing &lt;code dir=&quot;auto&quot;&gt;ProtectionState&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;commit_guard.evaluate&lt;/code&gt; seam — pillar C shrinks to
“lift input + route callsites”, de-risking the mission.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;is_protected()&lt;/code&gt; method folds the duplicated &lt;code dir=&quot;auto&quot;&gt;not hatch and ref in protected&lt;/code&gt; idiom
(3 sites) and makes the hatch boundary-resolved too.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Explicit threading: each command must resolve the value at its entry and pass it down
(shallow, at the boundary each already owns — strictly less than nesting would require).&lt;/li&gt;
&lt;li&gt;Risk of a forgotten resolve falling back to a direct &lt;code dir=&quot;auto&quot;&gt;protected_branches()&lt;/code&gt; call — mitigated
by the FR-010 architectural guard.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;A future second repository/environment setting can promote the value into a richer
&lt;code dir=&quot;auto&quot;&gt;RepositoryConfig&lt;/code&gt; object; deferred until a real second field arrives (YAGNI).&lt;/li&gt;
&lt;li&gt;Consolidating the four scattered &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt; loaders is explicitly out of scope
here (a separate strangler).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;The decision is validated when: the #1619 repro completes on a &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;-primary repo using only
sanctioned commands (SC-001); the protection decision performs zero post-resolution git/fs
reads (NFR-003); the FR-010 guard is green and bans direct &lt;code dir=&quot;auto&quot;&gt;protected_branches(repo_root)&lt;/code&gt; /
hardcoded-set decisions outside the single resolver; and default-config repos behave
byte-identically (NFR-004). Confidence: high — the carrier shape was stress-tested by an
adversarial dialectic and the input/decision split is already present in the code.&lt;/p&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;a--standalone-boundary-resolved-value&quot;&gt;A — Standalone boundary-resolved value&lt;/h3&gt;
&lt;p&gt;A frozen value with one &lt;code dir=&quot;auto&quot;&gt;resolve(repo_root)&lt;/code&gt; resolver, passed explicitly, feeding
&lt;code dir=&quot;auto&quot;&gt;commit_guard.evaluate(ProtectionState)&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; reaches every callsite incl. the parentless deadlock site; minimal coupling;
cleanest single-authority guard; reuses the existing decision seam.
&lt;strong&gt;Cons:&lt;/strong&gt; explicit (shallow) threading at ~8 sites; needs the guard to prevent drift.&lt;/p&gt;
&lt;h3 id=&quot;b--environmentcontext-nested-on-executioncontext&quot;&gt;B — &lt;code dir=&quot;auto&quot;&gt;EnvironmentContext&lt;/code&gt; nested on &lt;code dir=&quot;auto&quot;&gt;ExecutionContext&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;Carry the set as a sub-object/fragment on the per-action context.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; idiomatic with the existing fragment family; free for in-loop callers.
&lt;strong&gt;Cons:&lt;/strong&gt; &lt;strong&gt;cannot reach the deadlock site&lt;/strong&gt; (no &lt;code dir=&quot;auto&quot;&gt;ExecutionContext&lt;/code&gt; there; factory fails
closed); couples a repo-scoped fact to a per-action composite; “EnvironmentContext” name
collides with &lt;code dir=&quot;auto&quot;&gt;os.environ&lt;/code&gt; and the existing “environment = worktree-vs-code” usage.&lt;/p&gt;
&lt;h3 id=&quot;c--nested-on-workspacecontext&quot;&gt;C — Nested on &lt;code dir=&quot;auto&quot;&gt;WorkspaceContext&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;Carry it on the per-WP, JSON-persisted workspace context.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; none material here.
&lt;strong&gt;Cons:&lt;/strong&gt; scope inversion (repo-scoped vs per-WP); &lt;strong&gt;serialises owner config into stale
JSON snapshots&lt;/strong&gt;, breaking “owner edits config and observes the change”; still absent at the
deadlock site.&lt;/p&gt;
&lt;h3 id=&quot;d--no-new-object-config-aware-protected_branches&quot;&gt;D — No new object (config-aware &lt;code dir=&quot;auto&quot;&gt;protected_branches()&lt;/code&gt;)&lt;/h3&gt;
&lt;p&gt;Make the existing free function read &lt;code dir=&quot;auto&quot;&gt;.kittify&lt;/code&gt; config, keep calling it everywhere.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; smallest diff; fixes the deadlock + configurability.
&lt;strong&gt;Cons:&lt;/strong&gt; fails pillar C — the read stays &lt;em&gt;at the callsite&lt;/em&gt; (FR-007/NFR-003) and FR-010 can’t
ban the very function it would have to allow; the #1868 scatter persists.&lt;/p&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Mission spec + decision record: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/specify-protected-primary-coherence-01KVMBD6/spec.md&lt;/code&gt;
(FR-007/008/009/010) and &lt;code dir=&quot;auto&quot;&gt;…/research/protected-branch-carrier-decision.md&lt;/code&gt; (full squad synthesis,
callsite matrix, boundary seams).&lt;/li&gt;
&lt;li&gt;Decision seam reused: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/commit_guard.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;evaluate&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;ProtectionState&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;Input lifted to the resolver: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/git/commit_helpers.py:420,485-531,1017-1031&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Why nesting fails at the deadlock site: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/safe_commit_cmd.py&lt;/code&gt;
(no mission context) and &lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/resolution.py:855&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;resolve_action_context&lt;/code&gt;,
no-fallback).&lt;/li&gt;
&lt;li&gt;Related: ADR &lt;code dir=&quot;auto&quot;&gt;2026-06-03-2-executioncontext-owner-and-committarget.md&lt;/code&gt;,
ADR &lt;code dir=&quot;auto&quot;&gt;2026-06-19-1-coord-empty-surface-fallback.md&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
