<?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-04-27-1-retrospective-gate-shared-module/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-27-1-retrospective-gate-shared-module/</id>
  <title>ADR: Retrospective Gate as Shared Module</title>
  <updated>2026-04-27T00: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-04-27-1-retrospective-gate-shared-module/"/>
  <summary>One shared completion-gate function owns retrospective enforcement, so the runtime hook and status-transition surfaces cannot drift into rival implementations.</summary>
  <content type="html">&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;The retrospective learning loop (FR-011 through FR-016) requires a lifecycle gate
that decides, for a given mission, whether the transition to &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; is permitted
given the mission’s current retrospective state and resolved governance mode
(&lt;code dir=&quot;auto&quot;&gt;autonomous&lt;/code&gt; vs. &lt;code dir=&quot;auto&quot;&gt;human_in_command&lt;/code&gt;).&lt;/p&gt;
&lt;p&gt;The gate must be consulted from two independent surfaces:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;specify_cli.next&lt;/code&gt;&lt;/strong&gt; — the canonical control loop. Every mission completion
path runs through this surface. When the last domain step succeeds, &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt;
must check the gate before signaling mission completion.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Any future status-transition surface&lt;/strong&gt; that refuses mission-level completion
(e.g., a direct API caller that asks to move the mission to &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt;). These
surfaces need to apply the same mission-level mode policy without knowing the
internals of the &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; runtime.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Three placement options were evaluated:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;(A)&lt;/strong&gt; Place the gate inside &lt;code dir=&quot;auto&quot;&gt;specify_cli.status.transitions&lt;/code&gt;, alongside the
existing per-WP transition matrix.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;(B)&lt;/strong&gt; Bury the gate inside &lt;code dir=&quot;auto&quot;&gt;specify_cli.next&lt;/code&gt; (the control-loop internals).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;(C)&lt;/strong&gt; Place the gate in a new dedicated module &lt;code dir=&quot;auto&quot;&gt;specify_cli.retrospective.gate&lt;/code&gt;
and have both callers invoke it through a published typed API.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;The lifecycle gate lives in &lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/retrospective/gate.py&lt;/code&gt;&lt;/strong&gt; as a
single source of truth (option C). It exposes one public function:&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:#C792EA;--1:#8844AE&quot;&gt;def&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;is_completion_allowed&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&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&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;mission_id&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: MissionId,&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&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;*&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&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;feature_dir&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: Path,&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&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;repo_root&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: Path,&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&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;mode_override&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: Mode &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;|&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#FF6A83;--1:#A24848&quot;&gt;None&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#FF6A83;--1:#A24848&quot;&gt;None&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 style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;)&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; -&gt; GateDecision: &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&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;Both callers stay thin:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;specify_cli.next._internal_runtime.retrospective_hook&lt;/code&gt; calls
&lt;code dir=&quot;auto&quot;&gt;gate.is_completion_allowed(...)&lt;/code&gt; immediately before signaling mission
completion; it does not re-implement any gate logic.&lt;/li&gt;
&lt;li&gt;Any status-transition surface that intends to complete a mission calls the same
function; &lt;code dir=&quot;auto&quot;&gt;specify_cli.status.transitions&lt;/code&gt; is not modified.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The gate itself resolves mode through &lt;code dir=&quot;auto&quot;&gt;specify_cli.retrospective.mode.detect()&lt;/code&gt;
(charter override &gt; explicit flag &gt; environment &gt; parent process; FR-016, C-013)
and consults the mission event log to find the latest retrospective event.
The decision is deterministic: the same event log and mode signals always produce
the same &lt;code dir=&quot;auto&quot;&gt;GateDecision&lt;/code&gt; (NFR-008).&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;No logic duplication&lt;/strong&gt;: both &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; and any status-transition surface call
one function; changes to gate logic land in one file and are immediately
visible to all callers.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Isolated testability&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;retrospective.gate&lt;/code&gt; has no dependency on &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt;
internals or on &lt;code dir=&quot;auto&quot;&gt;status.transitions&lt;/code&gt;. It can be unit-tested by replaying event
log fixtures and charter fixtures without spinning up a full runtime.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Explicit cross-package dependency&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;specify_cli.next&lt;/code&gt; and any
status-transition surface depend on the &lt;code dir=&quot;auto&quot;&gt;retrospective&lt;/code&gt; package. This is an
intentional layering: the retrospective package owns mission-level governance
policy; &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;status&lt;/code&gt; are callers of that policy, not its authors.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;WP-level transitions are unchanged&lt;/strong&gt;: per-WP transition guards in
&lt;code dir=&quot;auto&quot;&gt;specify_cli.status.transitions&lt;/code&gt; remain governed by the existing per-WP
transition matrix. Mission-level mode policy does not bleed into that module.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Performance&lt;/strong&gt;: when &lt;code dir=&quot;auto&quot;&gt;retrospective.completed&lt;/code&gt; is already present, the gate
reads at most &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;, the mission event log filtered to retrospective
events, and (optionally) the retrospective YAML for hash verification — all
constant-bounded reads. NFR-007 (&amp;#x3C; 500 ms on completion) is achievable.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;alternatives-considered&quot;&gt;Alternatives considered&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option A — gate in &lt;code dir=&quot;auto&quot;&gt;specify_cli.status.transitions&lt;/code&gt;&lt;/strong&gt;: rejected. The
&lt;code dir=&quot;auto&quot;&gt;status.transitions&lt;/code&gt; module encodes per-WP lifecycle guards; inserting
mission-mode policy there conflates two orthogonal concerns (WP-level state
machine vs. mission-level governance). The module would need to load charter
overrides and parse retrospective events, which are not its responsibilities.
Future readers would be surprised to find retrospective mode-detection logic
inside the WP transition matrix.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option B — gate buried in &lt;code dir=&quot;auto&quot;&gt;specify_cli.next&lt;/code&gt;&lt;/strong&gt;: rejected. &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; is the
canonical control loop, but it is not the only path from which a mission
&lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; transition can be initiated. A status-transition surface that needs
to refuse completion would have to reach into &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; internals — violating
the architectural boundary that &lt;code dir=&quot;auto&quot;&gt;_internal_runtime&lt;/code&gt; is next-private. The gate
would then be duplicated, or the status surface would take on a hard dependency
on &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt;’s internal module, which is worse.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;references&quot;&gt;References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;AD-001 in mission plan: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/mission-retrospective-learning-loop-01KQ6YEG/plan.md&lt;/code&gt; (§Architecture Decisions, AD-001)&lt;/li&gt;
&lt;li&gt;Gate API contract: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/mission-retrospective-learning-loop-01KQ6YEG/contracts/gate_api.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Mission spec FR-011–FR-016, NFR-007, NFR-008, C-013: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/mission-retrospective-learning-loop-01KQ6YEG/spec.md&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
