<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/2.x/2026-02-25-3-mission-audit-primitive-hardening-and-2x-policy/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-02-25-3-mission-audit-primitive-hardening-and-2x-policy/</id>
  <title>Mission Audit Primitive Hardening and 2.x-Only Policy</title>
  <updated>2026-02-25T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/2.x/2026-02-25-3-mission-audit-primitive-hardening-and-2x-policy/"/>
  <summary>Implements auditing as a declarable Mission primitive behind compatibility gates, keeping built-in and custom Missions portable across local and hosted projections.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Spec Kitty 2.x treats Mission as the central control entity, but primitive hardening is uneven:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Built-in missions are not uniformly runtime-template compatible.&lt;/li&gt;
&lt;li&gt;Primitive context mutability and bridge wiring are functional but not yet uniformly constrained by compatibility gates.&lt;/li&gt;
&lt;li&gt;New post-merge audit behavior must be mission-declarable, deterministic, and portable across local + SaaS projections.&lt;/li&gt;
&lt;li&gt;Current built-in mission template baseline is mixed (for example, some missions still rely on legacy &lt;code dir=&quot;auto&quot;&gt;mission.yaml&lt;/code&gt; state-machine shape while others have runtime sidecars).&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;At the same time, product policy requires no new feature work on 1.x.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Make mission primitives reliable enough to be the primary abstraction for future growth.&lt;/li&gt;
&lt;li&gt;Ensure audit behavior is mission-controlled, not ad hoc command logic.&lt;/li&gt;
&lt;li&gt;Prevent branch-policy ambiguity between 1.x and 2.x.&lt;/li&gt;
&lt;li&gt;Enforce fail-fast behavior on invalid mission contracts.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Implement post-merge audit as CLI-only logic outside mission primitive system.&lt;/li&gt;
&lt;li&gt;Implement audit as mission primitive with hardening gates and 2.x-only policy (chosen).&lt;/li&gt;
&lt;li&gt;Delay primitive hardening and ship ad hoc audit now.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; “Implement audit as mission primitive with hardening gates and 2.x-only policy”, because this preserves architectural coherence and makes mission primitives a defensible long-term foundation.&lt;/p&gt;
&lt;h3 id=&quot;hardening-contract&quot;&gt;Hardening Contract&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;Audit is a mission primitive declared in mission runtime configuration.&lt;/li&gt;
&lt;li&gt;Runtime compatibility checks are required for built-in missions used in 2.x rollout.&lt;/li&gt;
&lt;li&gt;Invalid/partial mission config results in explicit fail-fast behavior.&lt;/li&gt;
&lt;li&gt;Primitive output schema for audit is typed and deterministic.&lt;/li&gt;
&lt;li&gt;Mission audit checkpoint decisions integrate with existing decision-required flow.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;branch-policy&quot;&gt;Branch Policy&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;All audit primitive and verify repurpose work is 2.x only.&lt;/li&gt;
&lt;li&gt;1.x receives no new feature implementation for this initiative.&lt;/li&gt;
&lt;li&gt;Any compatibility shims in shared code must avoid introducing new 1.x product capability.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Mission primitives become stronger as a reusable abstraction for future capabilities.&lt;/li&gt;
&lt;li&gt;Audit behavior stays composable and policy-driven per mission.&lt;/li&gt;
&lt;li&gt;Rollout discipline improves through explicit 2.x/1.x separation.&lt;/li&gt;
&lt;/ol&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Upfront migration effort for mission runtime templates and tests.&lt;/li&gt;
&lt;li&gt;Potential short-term blocked states while mission compatibility gaps are closed.&lt;/li&gt;
&lt;/ol&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Some built-in missions may remain temporarily unsupported until compatibility gates pass.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;This decision is validated when:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Built-in mission templates targeted for 2.0 pass runtime compatibility checks.&lt;/li&gt;
&lt;li&gt;Audit primitive behavior is deterministic across repeated runs.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt;/decision flow can process audit checkpoints end-to-end.&lt;/li&gt;
&lt;li&gt;No new 1.x feature scope appears in release changelogs for this initiative.&lt;/li&gt;
&lt;/ol&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;option-1-cli-only-audit-no-mission-primitive&quot;&gt;Option 1: CLI-only audit, no mission primitive&lt;/h3&gt;
&lt;p&gt;Attach audit behavior directly to commands.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Fastest path to initial feature.&lt;/li&gt;
&lt;li&gt;Low immediate runtime dependency.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Weakens mission as central control abstraction.&lt;/li&gt;
&lt;li&gt;Harder to compose, test, and extend reliably.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;option-2-mission-declared-audit-primitive-with-hardening-gates&quot;&gt;Option 2: Mission-declared audit primitive with hardening gates&lt;/h3&gt;
&lt;p&gt;Extend runtime contract and enforce compatibility.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Strong architecture alignment and composability.&lt;/li&gt;
&lt;li&gt;Better long-term maintainability.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Requires template/schema and testing investment.&lt;/li&gt;
&lt;li&gt;Requires cross-repo sequencing discipline.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;option-3-delay-hardening-and-ship-ad-hoc-audit-first&quot;&gt;Option 3: Delay hardening and ship ad hoc audit first&lt;/h3&gt;
&lt;p&gt;Ship quickly, refactor later.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Short-term delivery speed.&lt;/li&gt;
&lt;li&gt;Defers hard compatibility work.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;High refactor risk and technical debt.&lt;/li&gt;
&lt;li&gt;Increases probability of contract drift across repos.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;PRD reference:
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;spec-kitty-planning-repo&gt;/product-ideas/mission-collaboration-platform-ddd/prd-mission-post-merge-audit-and-verify-repurpose-v1.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Existing primitive context model:
&lt;code dir=&quot;auto&quot;&gt;src/doctrine/missions/primitives.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Runtime bridge integration point:
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/next/runtime_bridge.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Built-in mission runtime templates:
&lt;code dir=&quot;auto&quot;&gt;src/doctrine/missions/*/mission-runtime.yaml&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;src/doctrine/missions/*/mission.yaml&lt;/code&gt;&lt;/li&gt;
&lt;/ol&gt;</content>
</entry>
