<?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-1-execution-state-domain-model/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-06-03-1-execution-state-domain-model/</id>
  <title>ADR 2026-06-03-1: Execution-State Domain Model</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-1-execution-state-domain-model/"/>
  <summary>Splits the CLI into four bounded modules — Governance, Mission Management, Execution/Runtime, Shared Kernel — giving execution state one domain owner.</summary>
  <content type="html">&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;The spec-kitty runtime has accumulated approximately 40 command surfaces that
independently re-derive execution context (workspace path, feature directory,
branch name). This independent re-derivation is the root cause documented in
issue #1619: the same command produces divergent output depending on whether it is
invoked from the main checkout root or from a lane worktree, because each
surface reconstructs its own view of “where we are” rather than reading from a
single resolved context.&lt;/p&gt;
&lt;p&gt;Prior symptom fixes (#1615, #1616, #1617, #1618, #1627) treated individual
surfaces without installing a domain owner. The root cause is architectural:
there is no single module that owns the execution-state domain, so each surface
re-derives context ad hoc.&lt;/p&gt;
&lt;p&gt;The doc-01–doc-17 design analysis ratified in #1666 provides the authoritative
domain model for this mission. This ADR locks in the top-level bounded-module
decomposition and the status/kanban ownership decision before any implementation
begins (DIRECTIVE_032, C-001).&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;h3 id=&quot;four-bounded-modules&quot;&gt;Four Bounded Modules&lt;/h3&gt;
&lt;p&gt;The spec-kitty CLI is organized into four bounded modules with explicit
domain ownership:&lt;/p&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Module&lt;/th&gt;&lt;th&gt;Domain responsibility&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Governance&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Charter and Doctrine artifacts — what the project is allowed to do and how&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Mission Management&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Mission lifecycle, WP status/kanban, status events, planning artifacts&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Execution / Runtime&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Workspace resolution, branch state, mission run lifecycle, CWD-invariant context&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Shared Kernel&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Value types, identifiers, and utilities shared across modules — no domain logic&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Modules communicate via Open Host Service (OHS) facades only. Direct
cross-module imports of internal submodules are prohibited by architectural
tests.&lt;/p&gt;
&lt;h3 id=&quot;status-and-kanban-are-owned-exclusively-by-mission-management&quot;&gt;Status and Kanban Are Owned Exclusively by Mission Management&lt;/h3&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;status/&lt;/code&gt; package (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/status/&lt;/code&gt;) is the OHS facade for all
status reads and writes. No module outside Mission Management may import
&lt;code dir=&quot;auto&quot;&gt;specify_cli.status.&amp;#x3C;submodule&gt;&lt;/code&gt; directly. External callers use only
&lt;code dir=&quot;auto&quot;&gt;from specify_cli.status import &amp;#x3C;symbol&gt;&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;coordination/status_transition.py&lt;/code&gt; is internal Mission Management plumbing; it
may import &lt;code dir=&quot;auto&quot;&gt;status/&lt;/code&gt; internals directly and is explicitly exempt from the
boundary rule.&lt;/p&gt;
&lt;h3 id=&quot;context-is-per-domain&quot;&gt;Context Is Per-Domain&lt;/h3&gt;
&lt;p&gt;Each bounded module owns a context type that represents its resolved inputs for
a single operation:&lt;/p&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Context type&lt;/th&gt;&lt;th&gt;Owner&lt;/th&gt;&lt;th&gt;Resolved from&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;GovernanceContext&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Governance module&lt;/td&gt;&lt;td&gt;Charter and Doctrine artifacts active for this project&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;MissionExecutionContext&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Execution module (&lt;code dir=&quot;auto&quot;&gt;core/execution_context.py&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;Workspace root, branch, feature directory, WP identity&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;InfraContext&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Execution module&lt;/td&gt;&lt;td&gt;Git remote, CI endpoints, infrastructure credentials&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Context types are resolved once per operation and passed down. They are never
re-derived from CWD mid-operation.&lt;/p&gt;
&lt;h3 id=&quot;keeper-invariants&quot;&gt;Keeper Invariants&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;Mission&lt;/code&gt; is not &lt;code dir=&quot;auto&quot;&gt;MissionRun&lt;/code&gt;. A Mission (tracked item in &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;slug&gt;/&lt;/code&gt;)
has a 1-to-many relationship with Mission Runs (runtime session instances in
&lt;code dir=&quot;auto&quot;&gt;.kittify/runtime/&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;MissionType&lt;/code&gt; belongs to the Governance module. A Mission Type is a reusable
workflow blueprint; it is not a tracked item. This distinction follows ADR
&lt;code dir=&quot;auto&quot;&gt;2026-04-04-2-mission-type-mission-and-mission-run-terminology-boundary.md&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&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;All implementation WPs in this mission (#1663, #1664, #1667, #1673) build on
this boundary model. None may merge before this ADR is committed (C-001).&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;status/&lt;/code&gt; module boundary is enforced by an architectural test (WP03).
Existing bypass imports (~245 at issue-filing time) must be resolved before
that test can be added.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;MissionStatus&lt;/code&gt; aggregate (WP04) becomes the authoritative status read/write
entry point for Mission Management.&lt;/li&gt;
&lt;li&gt;All ~40 residue surfaces that re-derive execution context must route through
&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; (WP06).&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;The &lt;code dir=&quot;auto&quot;&gt;status/&lt;/code&gt; public API (&lt;code dir=&quot;auto&quot;&gt;from specify_cli.status import ...&lt;/code&gt;) is unchanged;
only the boundary rule is made explicit and enforced.&lt;/li&gt;
&lt;li&gt;Legacy missions (pre-coordination-topology) continue to work without
modification (NFR-001).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;coordination/transaction.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;BookkeepingTransaction&lt;/code&gt;) is unchanged
(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;Status and kanban ownership is named: Mission Management, not ad hoc per-surface.&lt;/li&gt;
&lt;li&gt;Cross-module communication is constrained to OHS facades.&lt;/li&gt;
&lt;li&gt;Context derivation happens once per operation, not per surface.&lt;/li&gt;
&lt;li&gt;The Mission ≠ MissionRun keeper invariant is a named architectural constraint.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;glossary-additions&quot;&gt;Glossary Additions&lt;/h2&gt;
&lt;p&gt;This ADR introduces the following terms (full entries in project glossary):
&lt;code dir=&quot;auto&quot;&gt;GovernanceContext&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;MissionExecutionContext&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;InfraContext&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Effector&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;communication artefact&lt;/code&gt;.&lt;/p&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: root-cause analysis and Strangler Fig sequence&lt;/li&gt;
&lt;li&gt;Issue #1674: ADR gate requirement&lt;/li&gt;
&lt;li&gt;Issue #1666: doc-01–doc-17 design analysis (authoritative design basis)&lt;/li&gt;
&lt;li&gt;ADR &lt;a href=&quot;/adr/3.x/2026-04-04-2-mission-type-mission-and-mission-run-terminology-boundary/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-04-04-2-mission-type-mission-and-mission-run-terminology-boundary.md&lt;/code&gt;&lt;/a&gt;: keeper invariants on Mission vs MissionType&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;: OHS facade pattern reference&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
