<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/migrations/retrospective-events-upstream/">
  <id>https://docs.spec-kitty.ai/migrations/retrospective-events-upstream/</id>
  <title>Cutover Runbook: Retrospective Events — Local to Upstream</title>
  <updated>2026-06-03T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/migrations/retrospective-events-upstream/"/>
  <summary>Cutover runbook for moving retrospective events from local emission to the upstream spec_kitty_events package, pending its release: the steps and the relevant ADR.</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;cutover-runbook-retrospective-events--local-to-upstream&quot;&gt;&lt;/span&gt;
&lt;p&gt;&lt;strong&gt;Status&lt;/strong&gt;: Pending upstream release of &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events&lt;/code&gt; with retrospective events.
&lt;strong&gt;Relevant ADR&lt;/strong&gt;: AD-004 in &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/mission-retrospective-learning-loop-01KQ6YEG/plan.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/mission-retrospective-learning-loop-01KQ6YEG/plan.md&lt;/code&gt;&lt;/a&gt;
&lt;strong&gt;Events contract&lt;/strong&gt;: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/mission-retrospective-learning-loop-01KQ6YEG/contracts/retrospective_events_v1.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/mission-retrospective-learning-loop-01KQ6YEG/contracts/retrospective_events_v1.md&lt;/code&gt;&lt;/a&gt;&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;background&quot;&gt;Background&lt;/h2&gt;
&lt;p&gt;This tranche introduces eight retrospective lifecycle events (FR-017). They are
defined &lt;em&gt;locally&lt;/em&gt; in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/retrospective/events.py&lt;/code&gt; so the tranche
stays self-contained and does not block on an external release. In parallel, an
upstream PR has been opened (or will be opened — see T065 note below) against
the &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events&lt;/code&gt; PyPI package to add the same eight events with the same
names and payload shapes.&lt;/p&gt;
&lt;p&gt;Once the upstream release lands, this runbook takes the CLI from the local
module to the shared package surface. The cutover is mechanical: verify shapes,
bump the version pin, swap imports, delete the local module, and unskip the
boundary test.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;t065--upstream-issue-placeholder&quot;&gt;T065 — Upstream issue placeholder&lt;/h2&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Note&lt;/strong&gt;: WP03 (which creates &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/retrospective/events.py&lt;/code&gt;)
may not have landed when WP12 (this runbook) is merged. The real upstream
&lt;code dir=&quot;auto&quot;&gt;spec_kitty_events&lt;/code&gt; issue URL will be recorded in &lt;code dir=&quot;auto&quot;&gt;events.py&lt;/code&gt; and the
boundary test after WP03 lands. See the placeholder pattern below.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;&lt;strong&gt;Placeholder URL pattern&lt;/strong&gt; (to be replaced by a follow-up patch after WP03
lands):&lt;/p&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;https://github.com/spec-kitty/spec-kitty/issues/&amp;#x3C;ISSUE_NUMBER&gt;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;The follow-up patch must:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Open the actual GitHub issue against &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events&lt;/code&gt; with title:
“Add retrospective lifecycle events (8) to public surface.” Body should
link to
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/mission-retrospective-learning-loop-01KQ6YEG/plan.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/mission-retrospective-learning-loop-01KQ6YEG/plan.md&lt;/code&gt;&lt;/a&gt;
and
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/mission-retrospective-learning-loop-01KQ6YEG/contracts/retrospective_events_v1.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/mission-retrospective-learning-loop-01KQ6YEG/contracts/retrospective_events_v1.md&lt;/code&gt;&lt;/a&gt;,
and paste the eight event names and their payload field minimums from the
contract.&lt;/li&gt;
&lt;li&gt;Replace the &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;TODO: WP12&gt;&lt;/code&gt; marker in
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/retrospective/events.py&lt;/code&gt; with the real issue URL.&lt;/li&gt;
&lt;li&gt;Replace the &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;TODO: WP12&gt;&lt;/code&gt; marker in
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_retrospective_events_boundary.py&lt;/code&gt; with the real
issue URL.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;This keeps WP12 mergeable independently of WP03’s timing.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;cutover-steps&quot;&gt;Cutover steps&lt;/h2&gt;
&lt;h3 id=&quot;step-1--verify-upstream-shapes-match-the-contract&quot;&gt;Step 1 — Verify upstream shapes match the contract&lt;/h3&gt;
&lt;p&gt;Before bumping the pin, confirm that the upstream release exports the correct
names and payload fields. Run this against a scratch venv:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&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:#82AAFF;--1:#3B61B0&quot;&gt;pip&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;install&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;spec_kitty_events&gt;=&amp;#x3C;TARGET_VERSION&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&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:#82AAFF;--1:#3B61B0&quot;&gt;python&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&amp;#x3C;&amp;#x3C;&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&apos;EOF&apos;&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:#ECC48D;--1:#984E4D&quot;&gt;from spec_kitty_events.retrospective import (&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:#ECC48D;--1:#984E4D&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;Requested, Started, Completed, Skipped, Failed,&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:#ECC48D;--1:#984E4D&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;ProposalGenerated, ProposalApplied, ProposalRejected,&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:#ECC48D;--1:#984E4D&quot;&gt;)&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:#ECC48D;--1:#984E4D&quot;&gt;# Spot-check required payload fields from the contract&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:#ECC48D;--1:#984E4D&quot;&gt;assert hasattr(Requested, &apos;model_fields&apos;) and &apos;mode&apos; in Requested.model_fields&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:#ECC48D;--1:#984E4D&quot;&gt;assert hasattr(Completed, &apos;model_fields&apos;) and &apos;record_hash&apos; in Completed.model_fields&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:#ECC48D;--1:#984E4D&quot;&gt;assert hasattr(Skipped, &apos;model_fields&apos;) and &apos;skip_reason&apos; in Skipped.model_fields&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:#ECC48D;--1:#984E4D&quot;&gt;assert hasattr(ProposalGenerated, &apos;model_fields&apos;) and &apos;proposal_id&apos; in ProposalGenerated.model_fields&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:#ECC48D;--1:#984E4D&quot;&gt;print(&quot;Shape check passed.&quot;)&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:#D9F5DD;--1:#111111&quot;&gt;EOF&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Cross-check each field against
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/mission-retrospective-learning-loop-01KQ6YEG/contracts/retrospective_events_v1.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;contracts/retrospective_events_v1.md&lt;/code&gt;&lt;/a&gt;.
If any field is missing or renamed, open a follow-up issue against
&lt;code dir=&quot;auto&quot;&gt;spec_kitty_events&lt;/code&gt; before proceeding — do not paper over the mismatch with an
adapter.&lt;/p&gt;
&lt;h3 id=&quot;step-2--bump-the-version-pin-in-pyprojecttoml&quot;&gt;Step 2 — Bump the version pin in &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;Open &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt; and update the &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; compatibility range to
include the new release:&lt;/p&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;toml&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:#919F9F;--1:#5F636F&quot;&gt;# Before (example):&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:#FFFFFF;--1:#984E4D&quot;&gt;&quot;spec-kitty-events&gt;=4.0.0,&amp;#x3C;5.0.0&quot;&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;/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:#919F9F;--1:#5F636F&quot;&gt;# After (example — adjust to the actual released version):&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:#FFFFFF;--1:#984E4D&quot;&gt;&quot;spec-kitty-events&gt;=4.1.0,&amp;#x3C;5.0.0&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Exact pins live only in &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt; (per ADR &lt;code dir=&quot;auto&quot;&gt;2026-04-25-1-shared-package-boundary.md&lt;/code&gt;).
Regenerate the lock file:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&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:#82AAFF;--1:#3B61B0&quot;&gt;uv&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;lock&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;step-3--swap-the-imports-in-eventspy&quot;&gt;Step 3 — Swap the imports in &lt;code dir=&quot;auto&quot;&gt;events.py&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;Open &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/retrospective/events.py&lt;/code&gt;. Replace the local Pydantic model
definitions with upstream imports:&lt;/p&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;python&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:#919F9F;--1:#5F636F&quot;&gt;# Before:&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:#C792EA;--1:#8844AE&quot;&gt;from&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; pydantic &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;import&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; BaseModel&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:#919F9F;--1:#5F636F&quot;&gt;# ... local definitions ...&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;/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:#919F9F;--1:#5F636F&quot;&gt;# After:&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:#C792EA;--1:#8844AE&quot;&gt;from&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; spec_kitty_events.retrospective &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;import&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; (&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;Requested,&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;Started,&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;Completed,&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;Skipped,&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;Failed,&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;ProposalGenerated,&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;ProposalApplied,&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;ProposalRejected,&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;)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Record the upstream issue URL in the module docstring (replacing &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;TODO: WP12&gt;&lt;/code&gt;
added in the WP03 follow-up patch):&lt;/p&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;python&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:#D9F5DD;--1:#111111&quot;&gt;&quot;&quot;&quot;&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:#ECC48D;--1:#984E4D&quot;&gt;Retrospective lifecycle event models.&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;/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:#ECC48D;--1:#984E4D&quot;&gt;Post-cutover: these names are re-exported from `spec_kitty_events.retrospective`.&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:#ECC48D;--1:#984E4D&quot;&gt;Upstream issue: https://github.com/spec-kitty/spec-kitty/issues/&amp;#x3C;ISSUE_NUMBER&gt;&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:#D9F5DD;--1:#111111&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;step-4--delete-the-local-pydantic-model-definitions&quot;&gt;Step 4 — Delete the local Pydantic model definitions&lt;/h3&gt;
&lt;p&gt;After the import swap in Step 3, remove the local &lt;code dir=&quot;auto&quot;&gt;class *Event(BaseModel):&lt;/code&gt;
definitions from &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/retrospective/events.py&lt;/code&gt;. The file should
contain only the upstream re-exports and the module docstring.&lt;/p&gt;
&lt;p&gt;Confirm nothing else imports the old local class names directly:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&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:#82AAFF;--1:#3B61B0&quot;&gt;grep&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-r&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;from specify_cli.retrospective.events import&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;src/&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;tests/&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;All usages should resolve to the same upstream names after the swap.&lt;/p&gt;
&lt;h3 id=&quot;step-5--unskip-the-boundary-test&quot;&gt;Step 5 — Unskip the boundary test&lt;/h3&gt;
&lt;p&gt;Open &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_retrospective_events_boundary.py&lt;/code&gt;. Find the
&lt;code dir=&quot;auto&quot;&gt;@pytest.mark.skip(reason=&quot;pending upstream release ...&quot;)&lt;/code&gt; decorator and remove
it. The test asserts that no Pydantic model for retrospective events lives
outside &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events.*&lt;/code&gt; in the production source tree.&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&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:#919F9F;--1:#5F636F&quot;&gt;# Run the boundary test to confirm it passes:&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:#82AAFF;--1:#3B61B0&quot;&gt;pytest&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;tests/architectural/test_retrospective_events_boundary.py&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-v&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;hr&gt;
&lt;h2 id=&quot;verification-checklist&quot;&gt;Verification checklist&lt;/h2&gt;
&lt;p&gt;Run through these checks in order before merging the cutover PR:&lt;/p&gt;
&lt;ul class=&quot;contains-task-list&quot;&gt;
&lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; &lt;code dir=&quot;auto&quot;&gt;pip install &quot;spec_kitty_events&gt;=&amp;#x3C;X&gt;&quot;&lt;/code&gt; resolves without dependency
conflicts.&lt;/li&gt;
&lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; &lt;code dir=&quot;auto&quot;&gt;python -c &quot;from spec_kitty_events import retrospective&quot;&lt;/code&gt; succeeds.&lt;/li&gt;
&lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; All eight names import cleanly:
&lt;code dir=&quot;auto&quot;&gt;Requested, Started, Completed, Skipped, Failed,&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;ProposalGenerated, ProposalApplied, ProposalRejected&lt;/code&gt;.&lt;/li&gt;
&lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; Payload field spot-checks pass (see Step 1 script above).&lt;/li&gt;
&lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; &lt;code dir=&quot;auto&quot;&gt;uv lock&lt;/code&gt; completes without error; &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt; is committed.&lt;/li&gt;
&lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; Existing tests still pass after the import swap:
&lt;code dir=&quot;auto&quot;&gt;bash     pytest tests/retrospective/ -v     pytest tests/integration/retrospective/ -v     &lt;/code&gt;&lt;/li&gt;
&lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; The boundary test in
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_retrospective_events_boundary.py&lt;/code&gt; is unskipped
and passes:
&lt;code dir=&quot;auto&quot;&gt;bash     pytest tests/architectural/test_retrospective_events_boundary.py -v     &lt;/code&gt;&lt;/li&gt;
&lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; No &lt;code dir=&quot;auto&quot;&gt;class *Event(BaseModel)&lt;/code&gt; definitions remain under
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/retrospective/&lt;/code&gt;:
&lt;code dir=&quot;auto&quot;&gt;bash     grep -rn &quot;class.*Event.*BaseModel&quot; src/specify_cli/retrospective/     # Expected: no output     &lt;/code&gt;&lt;/li&gt;
&lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; The upstream issue URL is recorded in the module docstring of
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/retrospective/events.py&lt;/code&gt; and in the boundary test skip
comment (replaced the &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;TODO: WP12&gt;&lt;/code&gt; marker).&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;h2 id=&quot;rollback&quot;&gt;Rollback&lt;/h2&gt;
&lt;p&gt;If the upstream shapes do not match, or if the boundary test reveals an
unexpected import, do not merge the cutover PR. The local module in
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/retrospective/events.py&lt;/code&gt; continues to work unmodified. This
tranche’s acceptance does not require the upstream release to land (AD-004).&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;see-also&quot;&gt;See also&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Events contract: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/mission-retrospective-learning-loop-01KQ6YEG/contracts/retrospective_events_v1.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/mission-retrospective-learning-loop-01KQ6YEG/contracts/retrospective_events_v1.md&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Shared package boundary ADR: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/docs/adr/3.x/2026-04-25-1-shared-package-boundary.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/adr/3.x/2026-04-25-1-shared-package-boundary.md&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Boundary test: &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_retrospective_events_boundary.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Operator overview: &lt;a href=&quot;/architecture/retrospective-learning-loop/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/architecture/retrospective-learning-loop.md&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
