<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/api/mission-creation-internals/">
  <id>https://docs.spec-kitty.ai/api/mission-creation-internals/</id>
  <title>mission-creation internals reference</title>
  <updated>2026-10-05T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/api/mission-creation-internals/"/>
  <summary>mission-creation internals: the mission_creation module family, the patch-routing rule, and where to add a create-time decision.</summary>
  <content type="html">&lt;h2 id=&quot;mission_creation-internals-reference&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;mission_creation&lt;/code&gt; internals reference&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent mission create&lt;/code&gt; and the orchestrator-api &lt;code dir=&quot;auto&quot;&gt;specify&lt;/code&gt; verb both
call &lt;code dir=&quot;auto&quot;&gt;create_mission_core()&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/mission_creation.py&lt;/code&gt;. That
module used to hold all of mission creation in about 2,360 lines. Since #5634 it
is a façade over a family of sibling modules. This page is for a maintainer who
changes create-time behaviour.&lt;/p&gt;
&lt;h2 id=&quot;module-map&quot;&gt;Module map&lt;/h2&gt;
&lt;p&gt;The façade keeps &lt;code dir=&quot;auto&quot;&gt;create_mission_core&lt;/code&gt; (the public entry point), which
delegates to &lt;code dir=&quot;auto&quot;&gt;_create_mission_core_failure_atomic&lt;/code&gt; (the failure-atomic wrapper,
which also takes the private identity inputs &lt;code dir=&quot;auto&quot;&gt;_mission_id&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;_created_at&lt;/code&gt;),
&lt;code dir=&quot;auto&quot;&gt;_create_mission_core_impl&lt;/code&gt; (the orchestration) and the historical import
surface. Every other definition moved into one sibling, and the façade
re-exports it with &lt;code dir=&quot;auto&quot;&gt;from ... import x as x&lt;/code&gt;. The bodies moved verbatim; the
decision-core and seam cleanups then reshaped several leaves (the protected
mint’s &lt;code dir=&quot;auto&quot;&gt;_ProtectionProbe&lt;/code&gt; and gather ladder, the rollback’s
&lt;code dir=&quot;auto&quot;&gt;CreateRollbackJournal&lt;/code&gt;, the meta build/write split). &lt;code dir=&quot;auto&quot;&gt;logger&lt;/code&gt; is the same logger
object as before: the leaves that log pin its name, and the façade re-exports it.&lt;/p&gt;

































































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Module&lt;/th&gt;&lt;th&gt;Responsibility&lt;/th&gt;&lt;th&gt;Key names&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;mission_creation_errors&lt;/code&gt;&lt;/td&gt;&lt;td&gt;errors, the result type, the bootstrap commit-skip set&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;MissionCreationError&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;MissionAlreadyExistsError&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;MissionBranchExistsError&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;MissionCreationResult&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;mission_creation_identity&lt;/code&gt;&lt;/td&gt;&lt;td&gt;slug, friendly name and purpose inputs&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;_mint_mission_id&lt;/code&gt; (the identity seam), &lt;code dir=&quot;auto&quot;&gt;KEBAB_CASE_PATTERN&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_validate_create_inputs&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_resolve_purpose&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;mission_creation_roots&lt;/code&gt;&lt;/td&gt;&lt;td&gt;repository root, write root and current branch&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;_CreateRoots&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_resolve_create_roots&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;mission_creation_duplicates&lt;/code&gt;&lt;/td&gt;&lt;td&gt;live-duplicate detection over &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;_list_mission_scaffolds&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_find_live_duplicate_mission&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_refuse_live_duplicate&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;mission_creation_protected_mint&lt;/code&gt;&lt;/td&gt;&lt;td&gt;the protected-target mission-branch mint for &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;_ProtectionProbe&lt;/code&gt; (the per-create protection decision), &lt;code dir=&quot;auto&quot;&gt;_refuse_protected_recreate&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_mint_protected_branch_for_topology&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;mission_creation_scaffold&lt;/code&gt;&lt;/td&gt;&lt;td&gt;the mission directory scaffold, tasks README and create-time governance&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;render_tasks_readme_content&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_resolve_create_governance&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_scaffold_mission_dir&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;mission_creation_meta&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; assembly, the coordination-branch mint, and the &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; write&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;_MetaBuild&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_build_create_meta&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_write_create_meta&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;mission_creation_events&lt;/code&gt;&lt;/td&gt;&lt;td&gt;creation events and the coordination status seed&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;_emit_create_events&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_commit_coord_create_events&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_seed_coord_surface_for_create&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;mission_creation_commit&lt;/code&gt;&lt;/td&gt;&lt;td&gt;the scaffold commit, origin binding and the result&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;_commit_feature_file&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_commit_create_scaffold&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_build_create_result&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;mission_creation_rollback&lt;/code&gt;&lt;/td&gt;&lt;td&gt;failure-atomic rollback of a failed create&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;CreateRollbackJournal&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_CoordCreateRollbackContext&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_restore_git_state_after_failed_create&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;mission_creation_decisions&lt;/code&gt;&lt;/td&gt;&lt;td&gt;pure decision cores: no git, filesystem, clock or ULID&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;decide_protected_mint&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;coord_rollback_action&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;mission_creation.&amp;#x3C;name&gt;&lt;/code&gt; stays importable for every name the module exposed
before the split; &lt;code dir=&quot;auto&quot;&gt;tests/core/test_mission_creation_family.py&lt;/code&gt; pins that list.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;_create_mission_core_impl&lt;/code&gt; runs the create steps in this order: scaffold,
&lt;code dir=&quot;auto&quot;&gt;_build_create_meta&lt;/code&gt; (which mints the coordination branch), the protected-target
mint &lt;code dir=&quot;auto&quot;&gt;_mint_protected_branch_for_topology&lt;/code&gt;, then &lt;code dir=&quot;auto&quot;&gt;_write_create_meta&lt;/code&gt;. The mint
is called from the orchestration, not from the meta builder, and it runs before
the write because it can set &lt;code dir=&quot;auto&quot;&gt;meta[&quot;mission_branch&quot;]&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;the-patch-routing-rule&quot;&gt;The patch-routing rule&lt;/h2&gt;
&lt;p&gt;Tests patch names on the façade, for example
&lt;code dir=&quot;auto&quot;&gt;monkeypatch.setattr(mission_creation, &quot;build_mission_created_payload&quot;, ...)&lt;/code&gt;. A leaf that
called such a name directly would ignore the patch. Today the patch-routed set (patched
names a leaf reads) is &lt;code dir=&quot;auto&quot;&gt;{build_mission_created_payload}&lt;/code&gt;; the other &lt;code dir=&quot;auto&quot;&gt;_mc.&lt;/code&gt; calls in
the leaves are cross-leaf calls. So:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;A leaf calls a name tests patch on &lt;code dir=&quot;auto&quot;&gt;mission_creation&lt;/code&gt;, or a function another
&lt;code dir=&quot;auto&quot;&gt;mission_creation*&lt;/code&gt; module owns, as &lt;code dir=&quot;auto&quot;&gt;_mc.&amp;#x3C;name&gt;(...)&lt;/code&gt;, after a function-local
&lt;code dir=&quot;auto&quot;&gt;from specify_cli.core import mission_creation as _mc&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Every other call in a leaf is direct, and patching the leaf intercepts it.&lt;/li&gt;
&lt;li&gt;No leaf imports the façade at module scope, and the decisions module never
imports it. Leaves import classes and constants of other leaves directly.&lt;/li&gt;
&lt;li&gt;Leaves that log use &lt;code dir=&quot;auto&quot;&gt;logging.getLogger(&quot;specify_cli.core.mission_creation&quot;)&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;tests/core/test_mission_creation_family.py&lt;/code&gt; computes the routed set from the
patch census (&lt;code dir=&quot;auto&quot;&gt;tests/_support/patch_census.py&lt;/code&gt;) and fails on a bare reference to
a routed name, on a foreign function used bare, and on an &lt;code dir=&quot;auto&quot;&gt;_mc.&lt;/code&gt; reference to a
name nobody patches. It reads an import alias as the name it imports, and it
also fails on &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;module alias&gt;.&amp;#x3C;routed name&gt;&lt;/code&gt; (for example
&lt;code dir=&quot;auto&quot;&gt;import specify_cli.core.git_ops as g; g.get_current_branch()&lt;/code&gt;), on an import
of a patched name or of another family module’s function under any alias, and
on &lt;code dir=&quot;auto&quot;&gt;sys.modules[...]&lt;/code&gt; in a leaf. When a test starts patching a new façade name that a leaf
reads, route that read in the same change.&lt;/p&gt;
&lt;h2 id=&quot;fixing-a-creates-identity&quot;&gt;Fixing a create’s identity&lt;/h2&gt;
&lt;p&gt;A create mints its &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;mission_creation_identity._mint_mission_id()&lt;/code&gt;
and reads the clock for &lt;code dir=&quot;auto&quot;&gt;created_at&lt;/code&gt; in the meta leaf. A test or caller that
needs a fixed identity (a resume into the same directory, a branch name known in
advance) passes &lt;code dir=&quot;auto&quot;&gt;_mission_id=&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;_created_at=&lt;/code&gt; to
&lt;code dir=&quot;auto&quot;&gt;mission_creation._create_mission_core_failure_atomic&lt;/code&gt;, the failure-atomic body
&lt;code dir=&quot;auto&quot;&gt;create_mission_core&lt;/code&gt; delegates to, instead of patching &lt;code dir=&quot;auto&quot;&gt;ULID&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;now_utc_iso&lt;/code&gt;.
The public signature of &lt;code dir=&quot;auto&quot;&gt;create_mission_core&lt;/code&gt; does not carry them.&lt;/p&gt;
&lt;h2 id=&quot;where-to-add-a-create-time-decision&quot;&gt;Where to add a create-time decision&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Put the rule in &lt;code dir=&quot;auto&quot;&gt;mission_creation_decisions.py&lt;/code&gt; as a pure function over plain
values. It may not do I/O; &lt;code dir=&quot;auto&quot;&gt;tests/core/test_mission_creation_purity.py&lt;/code&gt;
checks that with an import allow-list and a ban on file and process calls.&lt;/li&gt;
&lt;li&gt;Unit-test every branch in &lt;code dir=&quot;auto&quot;&gt;tests/core/test_mission_creation_decisions.py&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Gather the facts in the leaf that owns the step (the adapter) and pass them
in. Keep the order in which facts are probed, so an error still raises at the
same point.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Behaviour of the whole create path is pinned by the golden matrix in
&lt;code dir=&quot;auto&quot;&gt;tests/core/test_mission_creation_golden_*.py&lt;/code&gt; and the CLI golden in
&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/cli/commands/agent/test_mission_create_golden_cli.py&lt;/code&gt;.&lt;/p&gt;</content>
</entry>
