<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/4.x/2026-10-07-1-upgrade-never-runs-mission-state-repair/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-10-07-1-upgrade-never-runs-mission-state-repair/</id>
  <title>ADR: upgrade never runs the mission-state repair</title>
  <updated>2026-10-14T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/4.x/2026-10-07-1-upgrade-never-runs-mission-state-repair/"/>
  <summary>spec-kitty upgrade, including --yes, only reports TeamSpace mission-state blockers (and only when hosted drain is on); doctor mission-state --fix is the sole repair consent path.</summary>
  <content type="html">&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-10-07&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (repository owner).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; #5811 (an up-to-date &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade --yes&lt;/code&gt; rewrote historical Mission state); this record reverses the #4775 decision that &lt;code dir=&quot;auto&quot;&gt;--yes&lt;/code&gt; consents to the repair. Related: #3653.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Reader:&lt;/strong&gt; a maintainer changing the upgrade finalizer, the TeamSpace mission-state gate, or the mission-state repair.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; ends with a finalizer step that used to offer the mission-state repair (&lt;code dir=&quot;auto&quot;&gt;doctor mission-state --fix&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;repair_repo&lt;/code&gt;), a mutating rewrite of &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt;. Mission &lt;code dir=&quot;auto&quot;&gt;upgrade-command-hardening&lt;/code&gt; (#3653) made that repair a separately-consented, default-deny gate. #4775 then reconciled “&lt;code dir=&quot;auto&quot;&gt;--yes&lt;/code&gt; is fully non-interactive” with that gate by passing the &lt;code dir=&quot;auto&quot;&gt;--yes&lt;/code&gt; value as the gate’s own opt-in, so &lt;code dir=&quot;auto&quot;&gt;upgrade --yes&lt;/code&gt; ran the repair.&lt;/p&gt;
&lt;p&gt;#5811 showed the cost: a project that was already up to date had its historical Mission state rewritten by a routine &lt;code dir=&quot;auto&quot;&gt;upgrade --yes&lt;/code&gt;, with no operator decision about the repair, in a repository whose hosted (Team Kitty) features are off and unsupported (&lt;a href=&quot;/adr/4.x/2026-10-06-1-team-kitty-surfaces-are-hidden-unless-drain-is-on/&quot;&gt;ADR 2026-10-06-1&lt;/a&gt;). The repair exists to prepare history for a TeamSpace import, which only matters when hosted drain is on.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;upgrade&lt;/code&gt; is report-only.&lt;/strong&gt; The finalizer step calls &lt;code dir=&quot;auto&quot;&gt;report_teamspace_mission_state_blockers&lt;/code&gt;, which never calls &lt;code dir=&quot;auto&quot;&gt;repair_repo&lt;/code&gt;, never prompts, and never raises &lt;code dir=&quot;auto&quot;&gt;typer.Exit&lt;/code&gt;. The upgrade exit code is unchanged by a reported blocker.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Drain-gated.&lt;/strong&gt; With hosted drain off (the default) readiness is not evaluated and nothing is printed. With drain on, the gate prints the blocker count, the finding codes and &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor mission-state --fix&lt;/code&gt;. The posture is read through the &lt;code dir=&quot;auto&quot;&gt;hosted_posture.drain_posture&lt;/code&gt; module attribute.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;One consent path.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor mission-state --fix&lt;/code&gt; is the only caller of &lt;code dir=&quot;auto&quot;&gt;repair_repo&lt;/code&gt;. It names every errored Mission and exits non-zero when any errored, and never prints a “cleared” claim in that case. &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_mission_state_repair_sole_caller.py&lt;/code&gt; pins the sole caller with an empty allowlist.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Residue is reported, never repaired (#5812).&lt;/strong&gt; A &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; child that is not a Mission (no &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; and no git-tracked &lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;, for example a gitignored &lt;code dir=&quot;auto&quot;&gt;*.lock&lt;/code&gt; leftover) is reported as INFO &lt;code dir=&quot;auto&quot;&gt;RESIDUE_DIRECTORY&lt;/code&gt; and never repaired. The predicate is &lt;code dir=&quot;auto&quot;&gt;is_mission_dir&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/context/mission_resolver.py&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The consent plumbing is deleted.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;_should_run_repair&lt;/code&gt;, the &lt;code dir=&quot;auto&quot;&gt;repair_opt_in&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;assume_yes&lt;/code&gt; repair parameters, and the &lt;code dir=&quot;auto&quot;&gt;declined&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;ran&lt;/code&gt; outcome states have no remaining meaning and are removed.&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;&lt;strong&gt;Report-only, drain-gated (chosen).&lt;/strong&gt; Keeps the operator informed where the repair matters and writes nothing.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Keep the &lt;code dir=&quot;auto&quot;&gt;--yes&lt;/code&gt;-carries-consent wiring and add a no-op guard.&lt;/strong&gt; Rejected: the repair still runs from a command whose name and flags do not announce it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Restore the default-deny prompt of #3653.&lt;/strong&gt; Rejected: an interactive prompt inside &lt;code dir=&quot;auto&quot;&gt;upgrade&lt;/code&gt; for an unsupported hosted feature is noise, and the explicit command already exists.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Remove the report as well.&lt;/strong&gt; Rejected: with drain on, the blocker count is the signal that tells the operator to run the doctor.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;--yes&lt;/code&gt; stays fully non-interactive (FR-017 of #4775 still holds); it no longer carries a repair consent.&lt;/li&gt;
&lt;li&gt;Already-damaged history is not restored by this change.&lt;/li&gt;
&lt;li&gt;Upgrade output with drain off no longer mentions mission-state at all.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;enforce_teamspace_mission_state_ready&lt;/code&gt;, the blocking gate for hosted operations, is unchanged.&lt;/li&gt;
&lt;li&gt;Reversible only by an explicit, new decision; the sole-caller gate fails on any other &lt;code dir=&quot;auto&quot;&gt;repair_repo&lt;/code&gt; caller until its allowlist is amended in the same change.&lt;/li&gt;
&lt;li&gt;Known limitation: &lt;code dir=&quot;auto&quot;&gt;upgrade --json&lt;/code&gt; does not report mission-state blockers. Deferred; it needs an operator ruling on the JSON contract.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-10-14&quot;&gt;Amendment 2026-10-14&lt;/h2&gt;
&lt;p&gt;Amendment 2026-10-14: the hosted surfaces this ADR fences were removed from open-core by #6164; the code is preserved in spec-kitty/event-router.&lt;/p&gt;</content>
</entry>
