<?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-2-post-merge-audit-artifact-and-event-emission/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-02-25-2-post-merge-audit-artifact-and-event-emission/</id>
  <title>Post-Merge Mission Audit Artifact and Event Emission</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-2-post-merge-audit-artifact-and-event-emission/"/>
  <summary>Emits a canonical audit artifact and lifecycle events once a Mission is integrated, giving a durable, projectable answer to whether delivery matched the spec.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Current merge flow emits WP lifecycle transitions but does not produce a dedicated post-merge audit lifecycle, and does not persist audit status in feature metadata.
At the same time, dossier contracts already exist in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; and SaaS dossier projection exists, but current SaaS ingestion is focused on &lt;code dir=&quot;auto&quot;&gt;MissionDossierArtifactIndexed&lt;/code&gt; dispatch and not a post-merge mission-audit lifecycle.&lt;/p&gt;
&lt;p&gt;As a result:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;There is no canonical “did delivered software match spec/plan/tasks” artifact at merge boundary.&lt;/li&gt;
&lt;li&gt;Event stream consumers cannot reliably project post-merge quality status.&lt;/li&gt;
&lt;li&gt;Dashboard and dossier views cannot consistently show post-merge audit outcomes.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Ensure post-merge quality evaluation is auditable and replayable.&lt;/li&gt;
&lt;li&gt;Keep local-first execution authority while supporting SaaS projection parity.&lt;/li&gt;
&lt;li&gt;Provide deterministic artifact/event links for mission dossier materialization.&lt;/li&gt;
&lt;li&gt;Support human decision checkpoints for low-confidence or ambiguous audit results.&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;Keep audit as manual command only, no merge integration.&lt;/li&gt;
&lt;li&gt;Trigger audit on merge when mission policy enables it; emit canonical events + artifact (chosen).&lt;/li&gt;
&lt;li&gt;Make SaaS perform post-merge audit independently.&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; “Trigger audit on merge when mission policy enables it; emit canonical events + artifact”, because it preserves local authority and gives deterministic post-merge evidence.&lt;/p&gt;
&lt;h3 id=&quot;contract-details&quot;&gt;Contract Details&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;Merge MUST evaluate mission policy for audit trigger mode.&lt;/li&gt;
&lt;li&gt;If policy includes post-merge audit:
&lt;ul&gt;
&lt;li&gt;initiate audit run,&lt;/li&gt;
&lt;li&gt;persist audit metadata in feature state,&lt;/li&gt;
&lt;li&gt;emit canonical mission-audit lifecycle events,&lt;/li&gt;
&lt;li&gt;materialize a dossier-indexed audit artifact.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;If policy does not include post-merge audit:
&lt;ul&gt;
&lt;li&gt;do not run audit,&lt;/li&gt;
&lt;li&gt;emit explicit skip reason where applicable.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;Human clarification checkpoints are first-class decision events and appear in decision inbox projections.&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;Merge boundary gains deterministic quality evidence.&lt;/li&gt;
&lt;li&gt;Dashboard can reliably surface latest post-merge audit state.&lt;/li&gt;
&lt;li&gt;Dossier and event streams stay aligned for replay/debug.&lt;/li&gt;
&lt;/ol&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Merge flow complexity increases.&lt;/li&gt;
&lt;li&gt;Additional contract coordination required across repositories.&lt;/li&gt;
&lt;/ol&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Some missions can remain manual-only audit by policy.&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;Merge-triggered audits produce canonical event sequences and artifact refs.&lt;/li&gt;
&lt;li&gt;Feature metadata reflects latest audit run/verdict deterministically.&lt;/li&gt;
&lt;li&gt;SaaS dashboard and dossier show the same audit result as local state.&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-manual-only-audit&quot;&gt;Option 1: Manual-only audit&lt;/h3&gt;
&lt;p&gt;Post-merge quality checks are user-invoked only.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Simplest implementation.&lt;/li&gt;
&lt;li&gt;No merge-path latency impact.&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;Easy to skip accidentally.&lt;/li&gt;
&lt;li&gt;No reliable merge-boundary evidence.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;option-2-merge-triggered-policy-aware-audit-with-eventsartifact&quot;&gt;Option 2: Merge-triggered policy-aware audit with events/artifact&lt;/h3&gt;
&lt;p&gt;Run audit from merge when mission policy declares post-merge behavior.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Deterministic post-merge quality traceability.&lt;/li&gt;
&lt;li&gt;Strong alignment with mission-driven execution.&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 cross-repo implementation coordination.&lt;/li&gt;
&lt;li&gt;Must handle blocking/advisory behavior carefully.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;option-3-saas-side-independent-audit&quot;&gt;Option 3: SaaS-side independent audit&lt;/h3&gt;
&lt;p&gt;Perform audit in SaaS materialization layer.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Keeps local merge path simpler.&lt;/li&gt;
&lt;li&gt;Centralized compute in cloud layer.&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;Breaks local-first authority model.&lt;/li&gt;
&lt;li&gt;Risks divergence from canonical local artifacts/events.&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;Current merge command:
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/merge.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Existing event emitter contracts:
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/sync/emitter.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Existing dossier event/indexer model:
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/dossier/events.py&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/dossier/indexer.py&lt;/code&gt;&lt;/li&gt;
&lt;/ol&gt;</content>
</entry>
