<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/migrations/verdict-provenance-backfill/">
  <id>https://docs.spec-kitty.ai/migrations/verdict-provenance-backfill/</id>
  <title>Migration: Verdict-Provenance Backfill</title>
  <updated>2026-08-06T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/migrations/verdict-provenance-backfill/"/>
  <summary>Upgrade-time backfill (FR-012/SC-008) reducing each mission&apos;s terminal review-cycle .md verdict into the event log, completing event authority after the verdict-reader collapse.</summary>
  <content type="html">&lt;blockquote&gt;
&lt;p&gt;Migration note: This page documents a migration path or historical transition. It is not the current 3.2 happy path.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;span id=&quot;migration-verdict-provenance-backfill&quot;&gt;&lt;/span&gt;
&lt;p&gt;&lt;strong&gt;Status&lt;/strong&gt;: Shipped with mission &lt;code dir=&quot;auto&quot;&gt;verdict-seam-write-unification-01KZ9Q35&lt;/code&gt;.
&lt;strong&gt;Migration id&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;verdict_provenance_backfill&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/m_zz_verdict_provenance_backfill.py&lt;/code&gt;).
&lt;strong&gt;Audience&lt;/strong&gt;: Operators upgrading existing Spec Kitty projects across the
verdict single-authority cutover.&lt;/p&gt;
&lt;h2 id=&quot;why-this-matters&quot;&gt;Why This Matters&lt;/h2&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;verdict-seam-write-unification-01KZ9Q35&lt;/code&gt; mission made the append-only
event log (&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;) the &lt;strong&gt;sole&lt;/strong&gt; authority for a work package’s
review verdict. Every verdict reader was collapsed onto the event-sourced
&lt;code dir=&quot;auto&quot;&gt;review_result&lt;/code&gt; slot, and the &lt;code dir=&quot;auto&quot;&gt;review-cycle-N.md&lt;/code&gt; frontmatter readers were
&lt;strong&gt;deleted&lt;/strong&gt; — the irreversible half of single-authority.&lt;/p&gt;
&lt;p&gt;That deletion is only safe if the event log already carries every verdict a
mission ever recorded. A mission created before the cutover can carry a
&lt;strong&gt;terminal &lt;code dir=&quot;auto&quot;&gt;.md&lt;/code&gt; verdict with no &lt;code dir=&quot;auto&quot;&gt;review_result&lt;/code&gt; event slot&lt;/strong&gt; — a &lt;em&gt;stranded&lt;/em&gt;
verdict. Once the frontmatter readers are gone, a consumer reading the event
authority mid-upgrade would simply not see that historical rejection.&lt;/p&gt;
&lt;p&gt;This migration closes that gap (FR-012 / SC-008): it recovers each stranded
&lt;code dir=&quot;auto&quot;&gt;.md&lt;/code&gt; verdict into the event log so the authority is complete before anyone
reads it.&lt;/p&gt;
&lt;h2 id=&quot;what-it-does&quot;&gt;What It Does&lt;/h2&gt;
&lt;p&gt;On &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt;, for &lt;strong&gt;every&lt;/strong&gt; mission under &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt;:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Find each WP with a terminal &lt;code dir=&quot;auto&quot;&gt;review-cycle-N.md&lt;/code&gt; verdict but no event
&lt;code dir=&quot;auto&quot;&gt;review_result&lt;/code&gt; slot (the &lt;code dir=&quot;auto&quot;&gt;stranded_verdict_findings&lt;/code&gt; predicate).&lt;/li&gt;
&lt;li&gt;Reduce that historical verdict into a &lt;strong&gt;hand-constructed&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;review_result&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;StatusEvent&lt;/code&gt; appended to &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;backfill_verdict_provenance&lt;/code&gt;). The event’s timestamp is the artifact’s
own historical &lt;code dir=&quot;auto&quot;&gt;reviewed_at&lt;/code&gt; — never &lt;code dir=&quot;auto&quot;&gt;now()&lt;/code&gt; — so it sorts correctly in the
reducer’s &lt;code dir=&quot;auto&quot;&gt;(at, event_id)&lt;/code&gt; fold and never resurrects over a later approval.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The backfill spine is unchanged; this migration only adds the corpus walk.&lt;/p&gt;
&lt;h2 id=&quot;when-it-runs&quot;&gt;When It Runs&lt;/h2&gt;
&lt;p&gt;Automatically, as an auto-discovered upgrade migration
(&lt;code dir=&quot;auto&quot;&gt;@MigrationRegistry.register&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;pkgutil.iter_modules&lt;/code&gt;), during
&lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt;. It targets the current package version and runs after the
charter-fold migrations at the same version (the &lt;code dir=&quot;auto&quot;&gt;m_zz_&lt;/code&gt; filename encodes that
ordering). No operator action beyond running &lt;code dir=&quot;auto&quot;&gt;upgrade&lt;/code&gt; is required.&lt;/p&gt;
&lt;h2 id=&quot;idempotency&quot;&gt;Idempotency&lt;/h2&gt;
&lt;p&gt;The backfill is keyed on a &lt;strong&gt;deterministic ULID&lt;/strong&gt; over
&lt;code dir=&quot;auto&quot;&gt;(mission_id, wp_id, verdict, cycle)&lt;/code&gt; and skips any WP that already carries a
&lt;code dir=&quot;auto&quot;&gt;review_result&lt;/code&gt; event slot. Re-running &lt;code dir=&quot;auto&quot;&gt;upgrade&lt;/code&gt; over an already-migrated
corpus therefore seeds nothing:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; returns &lt;code dir=&quot;auto&quot;&gt;False&lt;/code&gt; once every mission is converged.&lt;/li&gt;
&lt;li&gt;A live &lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt; appends zero events; a &lt;code dir=&quot;auto&quot;&gt;--dry-run&lt;/code&gt; reports a would-seed
count of &lt;code dir=&quot;auto&quot;&gt;0&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Running it more than once is safe.&lt;/p&gt;
&lt;h2 id=&quot;verifying&quot;&gt;Verifying&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty accept&lt;/code&gt; carries a &lt;strong&gt;non-blocking&lt;/strong&gt; diagnostic that reports any
remaining stranded verdict for the mission under acceptance (naming the WPs and
pointing at &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt;). A clean upgrade leaves it silent. The
diagnostic is advisory only — it never blocks acceptance and never raises.&lt;/p&gt;
&lt;h2 id=&quot;rationale--references&quot;&gt;Rationale / References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Requirement: FR-012 (backfill) / SC-008 (safe reader collapse).&lt;/li&gt;
&lt;li&gt;Backfill library: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/migration/verdict_provenance_backfill.py&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Follow-up: &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/3236&quot;&gt;#3236&lt;/a&gt;
now tracks only the function-level census-exclusion narrowing for
&lt;code dir=&quot;auto&quot;&gt;_legacy_frontmatter_verdict&lt;/code&gt;, not the wiring — which this migration closes.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
