<?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-03-2-executioncontext-owner-and-committarget/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-06-03-2-executioncontext-owner-and-committarget/</id>
  <title>ADR 2026-06-03-2: ExecutionContext Owner and CommitTarget Atomicity</title>
  <updated>2026-06-03T00: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-03-2-executioncontext-owner-and-committarget/"/>
  <summary>Names `resolve_action_context` the single canonical ExecutionContext resolver, and adopts CommitTarget as ergonomic hardening rather than a correctness fix.</summary>
  <content type="html">&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;Two related structural decisions are needed before implementation WPs can begin:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Problem 1 — ExecutionContext ownership&lt;/strong&gt;: Approximately 40 command surfaces
independently resolve workspace root, branch name, and feature directory from
CWD. This produces divergent behavior when the same command is invoked from
different directories (main checkout vs. lane worktree). A single canonical
resolver is required.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Problem 2 — CommitTarget safety&lt;/strong&gt;: The &lt;code dir=&quot;auto&quot;&gt;safe_commit&lt;/code&gt; function in the
execution domain accepts a worktree root and a destination ref as separate
parameters. A forensic pass of the &lt;code dir=&quot;auto&quot;&gt;safe_commit&lt;/code&gt; call graph (7 direct call
sites, all examined) confirmed the invariant &lt;code dir=&quot;auto&quot;&gt;(worktree_root, destination_ref)&lt;/code&gt;
is always structurally enforced by &lt;code dir=&quot;auto&quot;&gt;safe_commit&lt;/code&gt; itself. Introducing
&lt;code dir=&quot;auto&quot;&gt;CommitTarget&lt;/code&gt; as a named value type is ergonomic hardening of already-clean
code, not a correctness fix.&lt;/p&gt;
&lt;p&gt;The design analysis in doc-06 of #1666 evaluated three options for the
ExecutionContext resolver (A: full rewrite, B: new canonical resolver,
C: Strangler Fig via existing OHS). This ADR records the chosen option.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;h3 id=&quot;decision-1-resolve_action_context-is-the-canonical-ohs-entry-point&quot;&gt;Decision 1: &lt;code dir=&quot;auto&quot;&gt;resolve_action_context&lt;/code&gt; Is the Canonical OHS Entry Point&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;resolve_action_context&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/execution_context.py&lt;/code&gt; is the
single canonical resolver for &lt;code dir=&quot;auto&quot;&gt;ExecutionContext&lt;/code&gt;. It fuses planning context
(mission slug, WP identity read from mission artifacts) with execution context
(workspace path, branch) and returns a fully resolved &lt;code dir=&quot;auto&quot;&gt;ExecutionContext&lt;/code&gt; object.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Rules:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Execution context is resolved once per operation by calling
&lt;code dir=&quot;auto&quot;&gt;resolve_action_context&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The resolved context is passed down to all callees as a value object.&lt;/li&gt;
&lt;li&gt;No callee may independently re-derive workspace path, branch, or feature
directory from CWD after context has been resolved.&lt;/li&gt;
&lt;li&gt;New surfaces must call &lt;code dir=&quot;auto&quot;&gt;resolve_action_context&lt;/code&gt; first; they must not
construct &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;slug&gt;&lt;/code&gt; paths directly (FR-031).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Migration strategy — Strangler Fig Option C → B&lt;/strong&gt;:&lt;/p&gt;
&lt;p&gt;The implementation uses the Strangler Fig pattern:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;resolve_action_context&lt;/code&gt; already exists as an OHS entry point (Option C).&lt;/li&gt;
&lt;li&gt;The migration routes each residue surface through the existing entry point
one at a time, without a big-bang rewrite (Option B execution).&lt;/li&gt;
&lt;li&gt;Once all residue surfaces are routed through &lt;code dir=&quot;auto&quot;&gt;resolve_action_context&lt;/code&gt;,
duplicated path-builder functions that become unreachable are deleted
(FR-034).&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;This approach was chosen over Option A (full rewrite) because the existing OHS
entry point is structurally correct; it needs consumers, not replacement.&lt;/p&gt;
&lt;h3 id=&quot;decision-2-committarget-is-a-planned-value-type--strangler-step-7&quot;&gt;Decision 2: &lt;code dir=&quot;auto&quot;&gt;CommitTarget&lt;/code&gt; Is a Planned Value Type — Strangler Step 7&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;CommitTarget&lt;/code&gt; is a self-validating value type pairing &lt;code dir=&quot;auto&quot;&gt;(worktree_root: Path, destination_ref: str)&lt;/code&gt;. It will replace the two-argument calling convention of
&lt;code dir=&quot;auto&quot;&gt;safe_commit&lt;/code&gt; with a single atomic argument.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Key facts confirmed by the forensic pass:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;safe_commit&lt;/code&gt; has 7 direct call sites in the codebase.&lt;/li&gt;
&lt;li&gt;All 7 call sites supply consistent, correct &lt;code dir=&quot;auto&quot;&gt;(worktree_root, destination_ref)&lt;/code&gt;
pairs; the invariant is already structurally enforced by &lt;code dir=&quot;auto&quot;&gt;safe_commit&lt;/code&gt; itself.&lt;/li&gt;
&lt;li&gt;There is no active correctness defect in the call graph.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Status&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;CommitTarget&lt;/code&gt; is Strangler step 7 (the final step). It is
ergonomic hardening, not a correctness fix. It carries no design risk to steps
1–6 and must not block them. The type will be introduced after steps 1–6 are
complete.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;what-changes-downstream&quot;&gt;What changes downstream&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;WP06 (ExecutionContext hardening) routes &lt;code dir=&quot;auto&quot;&gt;runtime_bridge&lt;/code&gt; query-mode and
&lt;code dir=&quot;auto&quot;&gt;workflow.py&lt;/code&gt; fix-mode through &lt;code dir=&quot;auto&quot;&gt;resolve_action_context&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;All residue surfaces that construct &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;slug&gt;&lt;/code&gt; paths directly are
removed and replaced with &lt;code dir=&quot;auto&quot;&gt;resolve_action_context&lt;/code&gt; calls.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;CommitTarget&lt;/code&gt; is introduced as the final hardening step after the other
surfaces are routed.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;what-stays-the-same&quot;&gt;What stays the same&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;resolve_action_context&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;core/execution_context.py&lt;/code&gt; is unchanged; this
ADR names it as canonical rather than replacing it.&lt;/li&gt;
&lt;li&gt;All 7 existing &lt;code dir=&quot;auto&quot;&gt;safe_commit&lt;/code&gt; call sites are correct; they need no functional
change before &lt;code dir=&quot;auto&quot;&gt;CommitTarget&lt;/code&gt; is introduced.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;BookkeepingTransaction&lt;/code&gt; internals are not modified (NFR-003, C-004).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;what-is-now-explicit&quot;&gt;What is now explicit&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;resolve_action_context&lt;/code&gt; is the named OHS entry point for &lt;code dir=&quot;auto&quot;&gt;ExecutionContext&lt;/code&gt;.
This is no longer implicit.&lt;/li&gt;
&lt;li&gt;The Strangler Fig migration order is declared: route surfaces → delete dead
code → introduce &lt;code dir=&quot;auto&quot;&gt;CommitTarget&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;CommitTarget&lt;/code&gt; introduction is explicitly deferred to step 7 to unblock steps
1–6.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;references&quot;&gt;References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Mission spec: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/execution-state-domain-remediation-01KT6HVH/spec.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Issue #1619: Strangler Fig sequence&lt;/li&gt;
&lt;li&gt;Issue #1673: ExecutionContext hardening implementation&lt;/li&gt;
&lt;li&gt;Issue #1666 doc-06: ExecutionContext resolver options A/B/C analysis&lt;/li&gt;
&lt;li&gt;ADR &lt;a href=&quot;/adr/3.x/2026-06-03-1-execution-state-domain-model/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-06-03-1-execution-state-domain-model.md&lt;/code&gt;&lt;/a&gt;: domain model gate&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/execution_context.py&lt;/code&gt;: canonical OHS entry point file&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;addendum-2026-06-10--missions-01ktpkst--01ktrc04&quot;&gt;Addendum (2026-06-10 — missions 01KTPKST + 01KTRC04)&lt;/h2&gt;
&lt;p&gt;This addendum records what was actually delivered against this ADR’s sketch. It
is an append-only record of canonical drift — the body above is preserved as the
original decision; this section is the binding correction.&lt;/p&gt;
&lt;h3 id=&quot;a-resolve_action_contexts-actual-home&quot;&gt;(a) &lt;code dir=&quot;auto&quot;&gt;resolve_action_context&lt;/code&gt;’s actual home&lt;/h3&gt;
&lt;p&gt;The ADR body names &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/execution_context.py&lt;/code&gt; as the canonical
OHS entry point for &lt;code dir=&quot;auto&quot;&gt;resolve_action_context&lt;/code&gt;. That path is now &lt;strong&gt;retired&lt;/strong&gt;. Post
shared-package-boundary (ADR &lt;code dir=&quot;auto&quot;&gt;2026-04-25-1-shared-package-boundary.md&lt;/code&gt;), the
runtime context surface moved into the shared package: &lt;code dir=&quot;auto&quot;&gt;resolve_action_context&lt;/code&gt;
lives in &lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/resolution.py&lt;/code&gt;&lt;/strong&gt; (with &lt;code dir=&quot;auto&quot;&gt;CommitTarget&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;ExecutionContext&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/context.py&lt;/code&gt;). References above to the
&lt;code dir=&quot;auto&quot;&gt;specify_cli/core/execution_context.py&lt;/code&gt; path are historical.&lt;/p&gt;
&lt;h3 id=&quot;b-delivered-committarget-shape--deliberate-canonical-drift&quot;&gt;(b) Delivered &lt;code dir=&quot;auto&quot;&gt;CommitTarget&lt;/code&gt; shape — deliberate, canonical drift&lt;/h3&gt;
&lt;p&gt;The ADR sketched &lt;code dir=&quot;auto&quot;&gt;CommitTarget&lt;/code&gt; as &lt;code dir=&quot;auto&quot;&gt;(worktree_root, destination_ref)&lt;/code&gt;. The
delivered, now-canonical shape is:&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:#B2CCD6;--1:#096E72&quot;&gt;CommitTarget&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--1:#3B61B0&quot;&gt;&lt;span style=&quot;--0:#82AAFF&quot;&gt;ref: &lt;/span&gt;&lt;span style=&quot;--0:#C5E478&quot;&gt;str&lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;,&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt; kind: CommitTargetKind&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;)   &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# kind ∈ {PRIMARY, COORDINATION, FLATTENED}&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;ref&lt;/code&gt; is the single destination authority (the short branch name); &lt;code dir=&quot;auto&quot;&gt;kind&lt;/code&gt;
classifies the topology. This is a &lt;strong&gt;deliberate drift&lt;/strong&gt;, not an oversight:
&lt;code dir=&quot;auto&quot;&gt;worktree_root&lt;/code&gt; did not vanish — it enters the guard via &lt;code dir=&quot;auto&quot;&gt;ProtectionState&lt;/code&gt;
(the pure value object the &lt;code dir=&quot;auto&quot;&gt;git.commit_helpers&lt;/code&gt; facade probes from the repo and
hands to &lt;code dir=&quot;auto&quot;&gt;core.commit_guard.evaluate&lt;/code&gt;), keeping &lt;code dir=&quot;auto&quot;&gt;CommitTarget&lt;/code&gt; an I/O-free value
and &lt;code dir=&quot;auto&quot;&gt;evaluate&lt;/code&gt; free of git/env/filesystem calls. The &lt;code dir=&quot;auto&quot;&gt;(ref, kind)&lt;/code&gt; shape is the
canonical contract going forward.&lt;/p&gt;
&lt;h3 id=&quot;c-step-7-delivered&quot;&gt;(c) Step 7 delivered&lt;/h3&gt;
&lt;p&gt;The ADR deferred &lt;code dir=&quot;auto&quot;&gt;CommitTarget&lt;/code&gt; introduction to “step 7” of the Strangler Fig
sequence to unblock steps 1–6. Step 7 is now &lt;strong&gt;delivered&lt;/strong&gt; across two missions:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;01KTPKST&lt;/strong&gt; built &lt;code dir=&quot;auto&quot;&gt;CommitTarget&lt;/code&gt; (the &lt;code dir=&quot;auto&quot;&gt;(ref, kind)&lt;/code&gt; value object in
&lt;code dir=&quot;auto&quot;&gt;mission_runtime&lt;/code&gt;) and the resolver path that produces it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;01KTRC04&lt;/strong&gt; made &lt;code dir=&quot;auto&quot;&gt;safe_commit&lt;/code&gt; &lt;em&gt;consume&lt;/em&gt; &lt;code dir=&quot;auto&quot;&gt;CommitTarget&lt;/code&gt; (the
&lt;code dir=&quot;auto&quot;&gt;git.commit_helpers&lt;/code&gt; facade is the single C-GUARD-1 entry point), &lt;strong&gt;folded the
five legacy privilege channels&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;_is_protected_branch_exception&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;allow_protected_branch_in_test_mode&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;allow_completed_op_on_protected_branch&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_is_completed_op_record_exception&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;_test_mode_allows_protected_branch&lt;/code&gt; — into the asserted-at-the-surface
&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;GuardCapability&lt;/code&gt;&lt;/strong&gt; (authorization is now an explicit caller argument, never
derived from message text, file content, env, or op records), and &lt;strong&gt;extracted
the SK policy module &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/commit_guard.py&lt;/code&gt;&lt;/strong&gt; whose
&lt;code dir=&quot;auto&quot;&gt;evaluate()&lt;/code&gt; is the ONE protected-branch decision.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The single-authority + capability model is permanently ratcheted by
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_safe_commit_import_boundary.py&lt;/code&gt; (#1355): &lt;code dir=&quot;auto&quot;&gt;evaluate&lt;/code&gt; has
exactly two blessed importers (the facade + &lt;code dir=&quot;auto&quot;&gt;coordination.policy&lt;/code&gt;), the five
deleted channels must have zero references in &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt;, and the residual two-arg
&lt;code dir=&quot;auto&quot;&gt;safe_commit(destination_ref=...)&lt;/code&gt; compat shim is allowlisted to its single
remaining call site so it cannot regrow a userbase before retirement.&lt;/p&gt;
&lt;h3 id=&quot;addendum-references&quot;&gt;Addendum references&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Mission spec: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/tooling-stability-guard-coherence-01KTRC04/spec.md&lt;/code&gt; (FR-008, FR-009, NFR-004)&lt;/li&gt;
&lt;li&gt;Contracts: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/tooling-stability-guard-coherence-01KTRC04/contracts/&lt;/code&gt; (C-GUARD-1, C-GUARD-2)&lt;/li&gt;
&lt;li&gt;ADR &lt;a href=&quot;/adr/3.x/2026-04-25-1-shared-package-boundary/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-04-25-1-shared-package-boundary.md&lt;/code&gt;&lt;/a&gt;: the boundary that retired the &lt;code dir=&quot;auto&quot;&gt;specify_cli/core/execution_context.py&lt;/code&gt; path&lt;/li&gt;
&lt;li&gt;Issue #1355: import-boundary ratchet&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/resolution.py&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/context.py&lt;/code&gt;: canonical &lt;code dir=&quot;auto&quot;&gt;resolve_action_context&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;CommitTarget&lt;/code&gt; home&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/commit_guard.py&lt;/code&gt;: the extracted SK policy module (single &lt;code dir=&quot;auto&quot;&gt;evaluate&lt;/code&gt; decision)&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
