<?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-08-13-1-built-in-mission-subtree-stays-nested-retire-legacy-step-contracts/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-08-13-1-built-in-mission-subtree-stays-nested-retire-legacy-step-contracts/</id>
  <title>ADR: The built-in mission subtree stays nested and self-contained; retire the legacy step-contract surface</title>
  <updated>2026-08-13T00: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-08-13-1-built-in-mission-subtree-stays-nested-retire-legacy-step-contracts/"/>
  <summary>Keeps the nested per-type packs/built-in/missions/ bundle canonical (no flattening) and retires built_in_step_contracts in favour of the unified MissionStep model.</summary>
  <content type="html">&lt;h2 id=&quot;the-built-in-mission-subtree-stays-nested-and-self-contained-retire-the-legacy-step-contract-surface&quot;&gt;The built-in mission subtree stays nested and self-contained; retire the legacy step-contract surface&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Filename:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;2026-08-13-1-built-in-mission-subtree-stays-nested-retire-legacy-step-contracts.md&lt;/code&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-08-13&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Operator (ATDD)&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; Discharges the nested-vs-flat mission-type layout decision that
&lt;a href=&quot;/adr/3.x/2026-08-05-1-mission-type-availability-before-kind-promotion/&quot;&gt;ADR 2026-08-05-1&lt;/a&gt; (§“a
short decision record of its own”) explicitly reserved. Completes the FR-011 unified-step
migration begun in mission &lt;code dir=&quot;auto&quot;&gt;charter-doctrine-mission-type-configuration-01KSWJVX&lt;/code&gt;.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;packs/built-in/missions/&lt;/code&gt; is a &lt;strong&gt;nested subtree&lt;/strong&gt;, unlike the flat &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;plural&gt;/&lt;/code&gt; content
dirs the other doctrine kinds use. It holds, per grounding research
(&lt;code dir=&quot;auto&quot;&gt;work/doctrine-pack-restructure-research/01-current-structure-and-loaders.md&lt;/code&gt;):&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;mission_types/*.yaml&lt;/code&gt; — the mission-type &lt;strong&gt;identity registry&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;id&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;display_name&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;mission-steps/&amp;#x3C;type&gt;/&amp;#x3C;step&gt;/{step.yaml,prompt.md,guidelines.md}&lt;/code&gt; — the &lt;strong&gt;unified
&lt;code dir=&quot;auto&quot;&gt;MissionStep&lt;/code&gt;&lt;/strong&gt; model (FR-011), the canonical per-step authority.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;built_in_step_contracts/*.step-contract.yaml&lt;/code&gt; — the &lt;strong&gt;legacy &lt;code dir=&quot;auto&quot;&gt;MissionStepContract&lt;/code&gt;&lt;/strong&gt;
shape, explicitly “retained as a compatibility surface … until later WPs migrate those
callers to the unified model” (&lt;code dir=&quot;auto&quot;&gt;src/doctrine/missions/step_contracts.py:1-17&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;Per-type &lt;strong&gt;self-contained bundles&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;type&gt;/&lt;/code&gt; — &lt;code dir=&quot;auto&quot;&gt;mission.yaml&lt;/code&gt; (state machine),
&lt;code dir=&quot;auto&quot;&gt;actions/&amp;#x3C;action&gt;/index.yaml&lt;/code&gt; (delegation map), &lt;code dir=&quot;auto&quot;&gt;templates/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;mission-runtime.yaml&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;expected-artifacts.yaml&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;governance-profile.yaml&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;A restructure was proposed to &lt;strong&gt;flatten&lt;/strong&gt; the subtree into two top-level dirs
(&lt;code dir=&quot;auto&quot;&gt;packs/built-in/mission-types/&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;packs/built-in/step-contracts/&lt;/code&gt;, deprecating
&lt;code dir=&quot;auto&quot;&gt;missions/&lt;/code&gt;) so built-in would look like a “normal” pack. Grounding showed this flatten
is expensive and fights existing invariants: it does not account for the unified
&lt;code dir=&quot;auto&quot;&gt;mission-steps/&lt;/code&gt; surface or the per-type runtime bundles (the two-dir target names neither);
it would red the Accepted layout gate in
&lt;a href=&quot;/adr/3.x/2026-07-26-2-doctrine-artefact-pack-layout-convention/&quot;&gt;ADR 2026-07-26-2&lt;/a&gt; that pins step-contracts
at &lt;code dir=&quot;auto&quot;&gt;missions/built_in_step_contracts/&lt;/code&gt;; it collides with kernel-floor path constants; and it
pulls built-in toward a DRG layout that still conflicts with the org-pack &lt;code dir=&quot;auto&quot;&gt;drg/fragment.yaml&lt;/code&gt;
convention (so “one canonical structure” would not actually be achieved). Meanwhile the
nested per-type organisation is already clean: each mission type is a self-contained
directory that offers its own identity, steps, state machine, actions, templates, and
governance.&lt;/p&gt;
&lt;p&gt;Two things are therefore in tension and need a recorded decision: &lt;strong&gt;(1)&lt;/strong&gt; whether to flatten,
and &lt;strong&gt;(2)&lt;/strong&gt; what to do about the two coexisting step surfaces (&lt;code dir=&quot;auto&quot;&gt;built_in_step_contracts/&lt;/code&gt;
legacy vs &lt;code dir=&quot;auto&quot;&gt;mission-steps/&lt;/code&gt; unified), which are a live drift hazard.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Single canonical authority&lt;/strong&gt; — two step surfaces (&lt;code dir=&quot;auto&quot;&gt;MissionStepContract&lt;/code&gt; vs &lt;code dir=&quot;auto&quot;&gt;MissionStep&lt;/code&gt;)
for “a mission’s steps” violate it and must collapse to one.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Self-containment / legibility&lt;/strong&gt; — a per-mission-type directory that carries everything
that type needs is easier to reason about, override, and extend than a flat collapse.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Do not break Accepted ADRs or kernel-floor invariants without cause.&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Avoid speculative convergence&lt;/strong&gt; — matching the org-pack shape is only worthwhile if it is
actually reached; a half-flatten that still differs from org packs buys nothing.&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;Option A — Flatten&lt;/strong&gt; to top-level &lt;code dir=&quot;auto&quot;&gt;mission-types/&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;step-contracts/&lt;/code&gt;, deprecate
&lt;code dir=&quot;auto&quot;&gt;missions/&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option B — Keep the nested subtree canonical; retire the legacy step-contract surface&lt;/strong&gt;
so the remaining structure is unambiguous.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option C — Keep everything as-is&lt;/strong&gt;, including both step surfaces (status quo).&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: “Option B”.&lt;/strong&gt; The nested &lt;code dir=&quot;auto&quot;&gt;packs/built-in/missions/&lt;/code&gt; subtree is the canonical
built-in mission layout. It is &lt;strong&gt;not&lt;/strong&gt; flattened. The legacy step-contract surface is
&lt;strong&gt;retired in its entirety&lt;/strong&gt;.&lt;/p&gt;
&lt;h3 id=&quot;canonical-structure-fixed-by-this-adr&quot;&gt;Canonical structure (fixed by this ADR)&lt;/h3&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;plaintext&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:#d6deeb;--1:#403f53&quot;&gt;packs/built-in/missions/&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;├── mission_types/&amp;#x3C;type&gt;.yaml                     # identity registry (id + display_name)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;├── mission-steps/&amp;#x3C;type&gt;/&amp;#x3C;step&gt;/                  # UNIFIED MissionStep (sole step authority)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│   ├── step.yaml&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│   ├── prompt.md&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│   └── guidelines.md&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;└── &amp;#x3C;type&gt;/                                        # self-contained per-type bundle&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;├── mission.yaml                               # state machine&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;├── mission-runtime.yaml                       # runtime DAG&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;├── expected-artifacts.yaml                    # dossier manifest&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;├── governance-profile.yaml                    # type-grain governance&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;├── actions/&amp;#x3C;action&gt;/index.yaml                # action-grain delegation map&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;└── templates/                                 # content scaffolds&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Each mission type is a &lt;strong&gt;self-contained directory&lt;/strong&gt;; two flat registries (&lt;code dir=&quot;auto&quot;&gt;mission_types/&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;mission-steps/&lt;/code&gt;) index identity and steps across types. This is the intended shape and
should not be flattened toward the org-pack &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;plural&gt;/&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;drg/fragment.yaml&lt;/code&gt; convention.
Built-in remaining structurally distinct from org packs is &lt;strong&gt;accepted and intentional&lt;/strong&gt; — it
is the positionally-anchored base layer, not a registered path-resolved pack.&lt;/p&gt;
&lt;h3 id=&quot;the-legacy-step-contract-surface-is-removed&quot;&gt;The legacy step-contract surface is removed&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;built_in_step_contracts/&lt;/code&gt; (the on-disk &lt;code dir=&quot;auto&quot;&gt;*.step-contract.yaml&lt;/code&gt; files, 17 today), the
&lt;code dir=&quot;auto&quot;&gt;MissionStepContract&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;MissionStepContractStep&lt;/code&gt; models and repository/loader
(&lt;code dir=&quot;auto&quot;&gt;src/doctrine/missions/step_contracts.py&lt;/code&gt;), the &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/mission_step_contracts/&lt;/code&gt;
package, the &lt;code dir=&quot;auto&quot;&gt;mission_step_contract&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;ArtifactKind&lt;/code&gt; and its DRG fragment
(&lt;code dir=&quot;auto&quot;&gt;packs/built-in/mission_step_contract.graph.yaml&lt;/code&gt;, 34 nodes), and every remaining caller of
that surface are migrated onto the unified &lt;code dir=&quot;auto&quot;&gt;MissionStep&lt;/code&gt; model and then deleted. This
completes FR-011.&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;One step model (&lt;code dir=&quot;auto&quot;&gt;MissionStep&lt;/code&gt;), one step surface (&lt;code dir=&quot;auto&quot;&gt;mission-steps/&lt;/code&gt;) — the drift hazard is
gone.&lt;/li&gt;
&lt;li&gt;The per-type bundle stays legible and self-contained; overrides and new mission types have
an obvious home.&lt;/li&gt;
&lt;li&gt;No churn against the kernel-floor &lt;code dir=&quot;auto&quot;&gt;missions&lt;/code&gt; leaf, the missions-root authority, or the
~23 &lt;code dir=&quot;auto&quot;&gt;default_missions_root()&lt;/code&gt; consumers (nothing moves).&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Removing the legacy surface is a &lt;strong&gt;large, cross-cutting migration&lt;/strong&gt; (~45 src files + ~40
test files reference it; the runtime contract registry, contract synthesis, and review
gate bindings must move to &lt;code dir=&quot;auto&quot;&gt;MissionStep&lt;/code&gt; first). It is breaking and must land behind the
unified model being feature-complete for gates.&lt;/li&gt;
&lt;li&gt;Deleting the &lt;code dir=&quot;auto&quot;&gt;mission_step_contract&lt;/code&gt; DRG fragment changes the built-in graph identity
(node/edge cardinality drops by 34 nodes); the parity fixture/golden must be re-baselined
in the same change, not silently.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Built-in stays asymmetric to org packs by design; the separate pack-meta / README /
built-in-validator work (see the pack-restructure research) is orthogonal and unaffected.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;Enforced, not aspirational: after migration, no &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; symbol imports
&lt;code dir=&quot;auto&quot;&gt;MissionStepContract*&lt;/code&gt; and no &lt;code dir=&quot;auto&quot;&gt;*.step-contract.yaml&lt;/code&gt; remains under &lt;code dir=&quot;auto&quot;&gt;packs/built-in/&lt;/code&gt;
(architectural guard); the unified &lt;code dir=&quot;auto&quot;&gt;MissionStep&lt;/code&gt; resolver carries the gate semantics the
contracts previously held (behavioural test); the built-in DRG parity fixture is
re-baselined to the post-removal cardinality; &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor doctrine --json&lt;/code&gt; reports
healthy.&lt;/p&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Grounding research: &lt;code dir=&quot;auto&quot;&gt;work/doctrine-pack-restructure-research/&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;01&lt;/code&gt;–&lt;code dir=&quot;auto&quot;&gt;05&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;99-SYNTHESIS.md&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;Supersedes point 5 of &lt;a href=&quot;/adr/3.x/2026-07-26-2-doctrine-artefact-pack-layout-convention/&quot;&gt;ADR 2026-07-26-2&lt;/a&gt;
(which pins step-contracts at &lt;code dir=&quot;auto&quot;&gt;missions/built_in_step_contracts/&lt;/code&gt;) — that path is removed.&lt;/li&gt;
&lt;li&gt;Does not contradict &lt;a href=&quot;/adr/3.x/2026-05-16-1-doctrine-layer-merge-semantics/&quot;&gt;ADR 2026-05-16-1&lt;/a&gt;
(merge semantics) or the shared-package-boundary ADR (packaging).&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
