<?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-04-3-upgrade-reports-one-outcome/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-10-04-3-upgrade-reports-one-outcome/</id>
  <title>ADR: a completed upgrade run reports one outcome</title>
  <updated>2026-10-13T00: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-04-3-upgrade-reports-one-outcome/"/>
  <summary>The upgrade outcome owns the kind, reasons, messages, JSON status, closing line and exit code of a run; presentation code reads them and cannot build its own.</summary>
  <content type="html">&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted, except the exit-code rule for unresolved drift, which is the current contract and is &lt;strong&gt;pending operator confirmation&lt;/strong&gt; in &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5745&quot;&gt;#5745&lt;/a&gt; (see &lt;a href=&quot;#open-decision-exit-code-for-unresolved-drift&quot;&gt;Open decision&lt;/a&gt;).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-10-04&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; &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/4925&quot;&gt;#4925&lt;/a&gt;, Mission &lt;code dir=&quot;auto&quot;&gt;upgrade-outcome-single-rendering-01M444Q6&lt;/code&gt;. The misleading “drift in 0 file(s)” message is the first part of &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/4893&quot;&gt;#4893&lt;/a&gt;; the ordering defect in that issue is not addressed here.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Reader:&lt;/strong&gt; a maintainer changing &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; or its tests.&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; already decided its exit code in one place, a &lt;code dir=&quot;auto&quot;&gt;derive_exit_code&lt;/code&gt; method on &lt;code dir=&quot;auto&quot;&gt;UpgradeOutcome&lt;/code&gt;, after the exit-honesty fixes (#3392, #5575). The text the operator reads was not decided there. Each presentation path built its own error list, and the path taken when no migrations are pending printed &lt;code dir=&quot;auto&quot;&gt;Project is already up to date!&lt;/code&gt; without asking the outcome anything.&lt;/p&gt;
&lt;p&gt;The result on an up-to-date project with one hand-edited managed file:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;the text output said the project was up to date and gave no reason;&lt;/li&gt;
&lt;li&gt;the exit code was 1;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; said &lt;code dir=&quot;auto&quot;&gt;status: failed&lt;/code&gt; with the drift error.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Automation that gates on the exit code, and an operator reading the screen, got contradictory answers. A second problem sat next to it: one boolean stood for three different conditions (unresolved drift, a repair that was not applied, an incomplete dry-run preview), so a repair failure was worded &lt;code dir=&quot;auto&quot;&gt;Unresolved tool-surface drift in 0 file(s)&lt;/code&gt; and sent the operator to review drift that did not exist.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;UpgradeOutcome&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/outcome.py&lt;/code&gt;) is the only object that says what an upgrade run amounted to. It owns:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;the &lt;strong&gt;kind&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;applied&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;no_op&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;drift_unresolved&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;failed&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;the &lt;strong&gt;reasons&lt;/strong&gt; a run is not a success (&lt;code dir=&quot;auto&quot;&gt;UpgradeFailureReason&lt;/code&gt;), in declaration order;&lt;/li&gt;
&lt;li&gt;the ordered, de-duplicated list of &lt;strong&gt;errors&lt;/strong&gt; and the &lt;strong&gt;warnings&lt;/strong&gt;. The step that fails still words its own diagnostic; the outcome owns the order, the de-duplication and the fallback lines;&lt;/li&gt;
&lt;li&gt;the JSON &lt;strong&gt;status&lt;/strong&gt; word (&lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;up_to_date&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;failed&lt;/code&gt;);&lt;/li&gt;
&lt;li&gt;the &lt;strong&gt;closing line&lt;/strong&gt; of the text output;&lt;/li&gt;
&lt;li&gt;the &lt;strong&gt;exit code&lt;/strong&gt;, a read-only property of the kind (&lt;code dir=&quot;auto&quot;&gt;0&lt;/code&gt; for &lt;code dir=&quot;auto&quot;&gt;applied&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;no_op&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;1&lt;/code&gt; otherwise). It is not stored, so it cannot disagree with the kind, the status or the closing line.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Precedence: any reason other than drift makes the kind &lt;code dir=&quot;auto&quot;&gt;failed&lt;/code&gt;. Drift alone makes it &lt;code dir=&quot;auto&quot;&gt;drift_unresolved&lt;/code&gt;. With no reason, the kind is &lt;code dir=&quot;auto&quot;&gt;applied&lt;/code&gt; if migrations ran, otherwise &lt;code dir=&quot;auto&quot;&gt;no_op&lt;/code&gt;. Every reason is still listed in &lt;code dir=&quot;auto&quot;&gt;failure_reasons&lt;/code&gt;, and every message in &lt;code dir=&quot;auto&quot;&gt;errors&lt;/code&gt;.&lt;/p&gt;








































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Kind&lt;/th&gt;&lt;th&gt;Exit&lt;/th&gt;&lt;th&gt;JSON &lt;code dir=&quot;auto&quot;&gt;status&lt;/code&gt;&lt;/th&gt;&lt;th&gt;JSON &lt;code dir=&quot;auto&quot;&gt;outcome&lt;/code&gt;&lt;/th&gt;&lt;th&gt;Text closing line&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;applied&lt;/td&gt;&lt;td&gt;0&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;applied&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;Upgrade complete! &amp;#x3C;from&gt; -&gt; &amp;#x3C;to&gt;&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;no-op&lt;/td&gt;&lt;td&gt;0&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;up_to_date&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;no_op&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;Project is already up to date!&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;drift-unresolved&lt;/td&gt;&lt;td&gt;1&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;failed&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;drift_unresolved&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;Upgrade finished, but N managed file(s) with local edits were not updated.&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;failed&lt;/td&gt;&lt;td&gt;1&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;failed&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;failed&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;Upgrade failed.&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;no_op&lt;/code&gt; means no migration ran. It does not mean nothing changed: a run with no pending migration can still create missing managed files and commit them, and it then closes with the no-op line followed by the auto-commit line.&lt;/p&gt;
&lt;p&gt;The reasons, as they appear in JSON &lt;code dir=&quot;auto&quot;&gt;failure_reasons&lt;/code&gt;:&lt;/p&gt;









































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Reason&lt;/th&gt;&lt;th&gt;Holds when&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;migration_failed&lt;/code&gt;&lt;/td&gt;&lt;td&gt;a migration did not complete&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;activation_error&lt;/code&gt;&lt;/td&gt;&lt;td&gt;provisioning the Mission-type activations failed&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;worktree_failure&lt;/code&gt;&lt;/td&gt;&lt;td&gt;a worktree could not be upgraded&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;commit_recovery_failed&lt;/code&gt;&lt;/td&gt;&lt;td&gt;the upgrade’s auto-commit could not be completed or cleanly recovered&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;repair_preparation_failed&lt;/code&gt;&lt;/td&gt;&lt;td&gt;the tool-surface repair could not be prepared or its preflight failed (an unreadable agent config, a broken &lt;code dir=&quot;auto&quot;&gt;charter:&lt;/code&gt; pointer, two tools claiming one path)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;surface_repair_failed&lt;/code&gt;&lt;/td&gt;&lt;td&gt;a prepared tool-surface repair was not applied&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;preview_incomplete&lt;/code&gt;&lt;/td&gt;&lt;td&gt;a dry-run preview could not be completed&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;surface_drift&lt;/code&gt;&lt;/td&gt;&lt;td&gt;managed files with local edits were kept and not updated (&lt;a href=&quot;/context/execution/#tool-surface-drift&quot;&gt;tool-surface drift&lt;/a&gt;)&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Rules that follow:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Text and JSON exit codes are equal for the same project state.&lt;/li&gt;
&lt;li&gt;A non-zero exit prints every entry of JSON &lt;code dir=&quot;auto&quot;&gt;errors&lt;/code&gt; and never a success closing line, and it always has at least one error. A surface-repair or preview reason that recorded no message of its own always gets a generic line; a migration or commit-recovery reason gets one only when the list would otherwise be empty.&lt;/li&gt;
&lt;li&gt;A completed dry run exits 0 and, on the migrations path, ends on &lt;code dir=&quot;auto&quot;&gt;Dry run complete — no changes applied. (&amp;#x3C;from&gt; -&gt; &amp;#x3C;to&gt; previewed)&lt;/code&gt;. An incomplete preview is &lt;code dir=&quot;auto&quot;&gt;failed&lt;/code&gt;, and its notice is printed once. A dry run does not predict the drift exit: on a project with edited managed files it prints &lt;code dir=&quot;auto&quot;&gt;Would preserve N paths requiring separate consent&lt;/code&gt; and exits 0, while the real run exits 1.&lt;/li&gt;
&lt;li&gt;A mission-state repair (the separately consented step) never changes the kind or the exit code. A failure of it that the repair gate did not already show is listed as a warning.&lt;/li&gt;
&lt;li&gt;Drift is reported per file, in plain words. Each kept file gets one line, &lt;code dir=&quot;auto&quot;&gt;Not updated, your local edit was kept: &amp;#x3C;path relative to the project&gt; (&amp;#x3C;reason&gt;)&lt;/code&gt;, for at most 20 files and then &lt;code dir=&quot;auto&quot;&gt;... and N more&lt;/code&gt;. One guidance line follows: &lt;code dir=&quot;auto&quot;&gt;To take the current version of a file, delete it and run &apos;spec-kitty upgrade&apos; again. To keep your edit, leave the file as it is. &apos;spec-kitty doctor tool-surfaces&apos; shows each file&apos;s state.&lt;/code&gt; The guidance never recommends an option that overwrites the operator’s edit (#5677); in particular it does not mention &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor tool-surfaces --fix&lt;/code&gt;, which replaces an edited file with the generated version.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Presentation code (&lt;code dir=&quot;auto&quot;&gt;_display*&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_render*&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_build_*&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_print*&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;cli/commands/upgrade.py&lt;/code&gt;) may not build any of these itself. It asks the outcome: &lt;code dir=&quot;auto&quot;&gt;outcome.errors()&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;outcome.warnings()&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;outcome.status&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;outcome.closing_line()&lt;/code&gt;. The exit code is raised once, as &lt;code dir=&quot;auto&quot;&gt;typer.Exit(outcome.exit_code)&lt;/code&gt;, after the finalizer has run.&lt;/p&gt;
&lt;p&gt;The contract applies to every run that reaches the finalizer, on both the migrations path and the no-migrations path. The JSON keys &lt;code dir=&quot;auto&quot;&gt;outcome&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;failure_reasons&lt;/code&gt; are present only on those runs. Outside the contract, each with its own output:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;the planner and compatibility paths (&lt;code dir=&quot;auto&quot;&gt;--cli&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;--plan-json&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;--project&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;--dry-run&lt;/code&gt;, the agent-check flags), which keep their own exit vocabulary;&lt;/li&gt;
&lt;li&gt;a refused downgrade target, which emits &lt;code dir=&quot;auto&quot;&gt;status: &quot;failed&quot;&lt;/code&gt; with exit 1 and no &lt;code dir=&quot;auto&quot;&gt;outcome&lt;/code&gt; key;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;--project&lt;/code&gt; outside a project, which emits &lt;code dir=&quot;auto&quot;&gt;{&quot;error&quot;: …}&lt;/code&gt; with exit 1;&lt;/li&gt;
&lt;li&gt;a declined or unanswerable confirmation prompt, which prints &lt;code dir=&quot;auto&quot;&gt;Upgrade cancelled.&lt;/code&gt; and exits 0 with nothing applied, also under &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; without &lt;code dir=&quot;auto&quot;&gt;--yes&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;open-decision-exit-code-for-unresolved-drift&quot;&gt;Open decision: exit code for unresolved drift&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pending operator confirmation, tracked in &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5745&quot;&gt;#5745&lt;/a&gt;.&lt;/strong&gt; The current contract is that unresolved tool-surface drift exits 1, on both paths. That keeps the behaviour earlier missions and tests pinned (#3392, #5575, and &lt;code dir=&quot;auto&quot;&gt;agent-profile-projection-plugin-production-01KV3NGS&lt;/code&gt;).&lt;/p&gt;
&lt;p&gt;The alternative is exit 0 with a warning on a run that applied nothing. It is not chosen here. The known cost of keeping the current rule: until the drift classification issue (&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/702&quot;&gt;#702&lt;/a&gt;) is fixed, untouched generated files can be classified as drift, so an unattended upgrade can exit 1 without any real edit. Because the kind is a value, reversing the rule later is a one-line change to &lt;code dir=&quot;auto&quot;&gt;SUCCESS_KINDS&lt;/code&gt; and to the table above; no presentation code changes.&lt;/p&gt;
&lt;p&gt;Two facts the decision should weigh. An operator has no way to accept an edit and stop the flag: &lt;code dir=&quot;auto&quot;&gt;upgrade&lt;/code&gt; has no accept or overwrite option, so a project with one customised managed file gets exit 1 from every later upgrade. And the run has already applied and committed its migrations when it exits 1.&lt;/p&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Fix only the no-migrations path.&lt;/strong&gt; Rejected. It would add a third place that builds an error list and leave the next path to diverge the same way.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Exit 0 with a warning on drift.&lt;/strong&gt; Not chosen; see the open decision above.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The outcome owns kind, reasons, messages, status, closing line and exit code, and a gate keeps presentation from rebuilding them (chosen).&lt;/strong&gt;&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;JSON gains two keys, &lt;code dir=&quot;auto&quot;&gt;outcome&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;failure_reasons&lt;/code&gt;. No existing key is removed or renamed.&lt;/li&gt;
&lt;li&gt;A run with pending migrations and unresolved drift now closes with the drift closing line, as the no-migrations path does. It used to close with &lt;code dir=&quot;auto&quot;&gt;Upgrade failed.&lt;/code&gt;. The exit code is unchanged.&lt;/li&gt;
&lt;li&gt;After a failed commit recovery, the optional mission-state repair is not offered. A commit that could not be recovered is a failure reason (&lt;code dir=&quot;auto&quot;&gt;commit_recovery_failed&lt;/code&gt;) and the run should not go on to ask for another consent.&lt;/li&gt;
&lt;li&gt;A surface-repair or preview reason that recorded no message gets its own generic error line, even when other messages exist, so no reason is silent.&lt;/li&gt;
&lt;li&gt;A broken charter pack config (for example a &lt;code dir=&quot;auto&quot;&gt;charter:&lt;/code&gt; pointer to a missing file) is reported as an upgrade error with its remediation, in text and JSON. It used to end in a traceback with no JSON.&lt;/li&gt;
&lt;li&gt;When the auto-commit landed but its recovery step failed, JSON &lt;code dir=&quot;auto&quot;&gt;auto_committed&lt;/code&gt; is true and the text still says the commit landed.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Residual, not fixed here:&lt;/strong&gt; a worktree migration that could not be detected or applied is recorded as an error line but not as a failure reason, so that run still exits 0 with a success closing line above an &lt;code dir=&quot;auto&quot;&gt;Errors:&lt;/code&gt; section (&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5746&quot;&gt;#5746&lt;/a&gt;).&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;drift in 0 file(s)&lt;/code&gt; wording is gone: a repair that was not applied is reported as a repair failure. &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/4893&quot;&gt;#4893&lt;/a&gt; stays open for its other defect, the ordering that makes a first run fail on some old projects. That is now reported honestly and is not fixed.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;upgrade&lt;/code&gt; help text and the exit-code docstring now describe the dry-run exit codes as they are.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;UpgradeResult.worktree_failures&lt;/code&gt; stays a list of strings; the sibling work on &lt;code dir=&quot;auto&quot;&gt;runner.py&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;assessment.py&lt;/code&gt; is untouched.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;enforcement&quot;&gt;Enforcement&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_upgrade_outcome_single_rendering.py&lt;/code&gt; fails when:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;closing-line text appears in &lt;code dir=&quot;auto&quot;&gt;cli/commands/upgrade.py&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;a JSON builder takes &lt;code dir=&quot;auto&quot;&gt;status&lt;/code&gt; from anything but &lt;code dir=&quot;auto&quot;&gt;outcome.status&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;errors&lt;/code&gt; from anything but the call &lt;code dir=&quot;auto&quot;&gt;outcome.errors()&lt;/code&gt;, or &lt;code dir=&quot;auto&quot;&gt;warnings&lt;/code&gt; from anything but the call &lt;code dir=&quot;auto&quot;&gt;outcome.warnings()&lt;/code&gt;, omits one of the three, or assigns one of them by subscript after the dict literal;&lt;/li&gt;
&lt;li&gt;the tail renderer never reaches a &lt;code dir=&quot;auto&quot;&gt;closing_line()&lt;/code&gt; call;&lt;/li&gt;
&lt;li&gt;a presentation function reads message state directly, fetches it with &lt;code dir=&quot;auto&quot;&gt;getattr(&amp;#x3C;x&gt;, &quot;&amp;#x3C;name&gt;&quot;)&lt;/code&gt;, or takes an &lt;code dir=&quot;auto&quot;&gt;errors&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;effective_success&lt;/code&gt; parameter. A presentation function is one named &lt;code dir=&quot;auto&quot;&gt;_display*&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_render*&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_build_*&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;_print*&lt;/code&gt;, or any function with an &lt;code dir=&quot;auto&quot;&gt;outcome&lt;/code&gt; parameter that calls &lt;code dir=&quot;auto&quot;&gt;console.print&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;print&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;a function that must not exit does so (&lt;code dir=&quot;auto&quot;&gt;typer.Exit&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;raise SystemExit&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;sys.exit&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;os._exit&lt;/code&gt;). That covers every presentation function, every function that takes an &lt;code dir=&quot;auto&quot;&gt;outcome&lt;/code&gt;, every &lt;code dir=&quot;auto&quot;&gt;_finalizer_step*&lt;/code&gt; function, every function reachable from the tail of &lt;code dir=&quot;auto&quot;&gt;upgrade()&lt;/code&gt; after the finalizer call, and every function in &lt;code dir=&quot;auto&quot;&gt;upgrade/finalize.py&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;upgrade/outcome.py&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;anything but &lt;code dir=&quot;auto&quot;&gt;raise typer.Exit(outcome.exit_code)&lt;/code&gt; exits after the finalizer call in &lt;code dir=&quot;auto&quot;&gt;upgrade()&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The kind-to-exit mapping needs no shape rule: the exit code is a property, and the truth table in &lt;code dir=&quot;auto&quot;&gt;tests/upgrade/test_upgrade_outcome_kind.py&lt;/code&gt; pins it for every reachable combination of reasons.&lt;/p&gt;
&lt;p&gt;It has no allowlist. Floor assertions name the real renderers, builders and exit sites, and synthetic violations prove every check can fail.&lt;/p&gt;
&lt;h3 id=&quot;follow-ups-not-in-scope&quot;&gt;Follow-ups, not in scope&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The planner and compatibility paths use a different exit-code vocabulary (2, 4, 5, 6). Folding them under one outcome is a separate decision.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;repair_stale_manifest&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;remove_unsafe_symlinks&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/skills/manifest_store.py&lt;/code&gt; had no production caller since the unreachable legacy branch of the surface-repair helper was removed. They were deleted as dead code; the repairs they performed are tracked in issue 5710.&lt;/li&gt;
&lt;li&gt;The exit code for unresolved drift, and a way for an operator to accept an edit: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5745&quot;&gt;#5745&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;A worktree migration failure that still exits 0, a confirmation prompt under &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt;, and files left behind by a failed auto-commit: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5746&quot;&gt;#5746&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;The reason shown for each kept file comes from the tool-surface provider and still uses internal wording such as “requires exact-path consent”.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-10-13-the-shared-command-skill-projection-is-regenerated-not-kept-702&quot;&gt;Amendment 2026-10-13: the shared command-skill projection is regenerated, not kept (#702)&lt;/h2&gt;
&lt;p&gt;Decision 5 no longer applies to the shared command-skill projection, &lt;code dir=&quot;auto&quot;&gt;.agents/skills/spec-kitty.&amp;#x3C;command&gt;/SKILL.md&lt;/code&gt; (Codex, Mistral Vibe, Pi, Letta). The state contract declares that surface &lt;code dir=&quot;auto&quot;&gt;DERIVED&lt;/code&gt; and git-&lt;code dir=&quot;auto&quot;&gt;IGNORED&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;shared_skills_projection&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/state/contract.py&lt;/code&gt;). Across two checkouts of one project, the command-skill manifest and the ignored bytes legitimately disagree, so the installer cannot tell a hand edit from generated output that another checkout’s upgrade left behind. Operator direction (2026-10-05, P1) is to regenerate: &lt;code dir=&quot;auto&quot;&gt;init&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;upgrade&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent config sync&lt;/code&gt; rewrite a manifest-owned projection whose bytes match neither the recorded hash nor the current render, without consent and without a &lt;code dir=&quot;auto&quot;&gt;Not updated, your local edit was kept&lt;/code&gt; line.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;Naming superseded: command skills are now &lt;code dir=&quot;auto&quot;&gt;spec-kitty-&amp;#x3C;cmd&gt;&lt;/code&gt;, see ADR 2026-10-20-1.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;Consequences:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;A hand edit to a &lt;code dir=&quot;auto&quot;&gt;spec-kitty.*&lt;/code&gt; command skill is replaced on the next reconcile. Customizations belong in a skill of the project’s own, which is never touched.&lt;/li&gt;
&lt;li&gt;The premise depends on &lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt; being git-ignored, which migration &lt;code dir=&quot;auto&quot;&gt;m_3_2_5_agents_skills_gitignore_backfill&lt;/code&gt; ensures. A project that removes that rule and commits the tree can still recover an overwritten edit from git.&lt;/li&gt;
&lt;li&gt;Every other managed surface (slash-command files, managed skills, agent profiles, plugin-bundle components) keeps Decision 5 unchanged, and so does removing a retired command’s drifted projection, which is still kept as &lt;code dir=&quot;auto&quot;&gt;consent_required&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The exit code for unresolved drift (#5745) is unaffected; this surface simply no longer produces drift.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;follow-up-2026-10-13-the-regenerate-is-named-gated-and-prunes-retired-drift-6155-6160&quot;&gt;Follow-up 2026-10-13: the regenerate is named, gated and prunes retired drift (#6155, #6160)&lt;/h3&gt;
&lt;p&gt;Three statements above no longer match the code. This note records what changed; the amendment text stays as written.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;A regenerated projection is named.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;init&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;upgrade&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent config sync&lt;/code&gt; print one line per regenerated path, &lt;code dir=&quot;auto&quot;&gt;Regenerated a generated command skill that differed from the current version: &amp;#x3C;path&gt;&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;upgrade --json&lt;/code&gt; lists the paths under &lt;code dir=&quot;auto&quot;&gt;surface_repair.regenerated&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent config sync --json&lt;/code&gt; lists them under &lt;code dir=&quot;auto&quot;&gt;regenerated&lt;/code&gt; without printing the line. A regenerated path counts as installed in the &lt;code dir=&quot;auto&quot;&gt;N command skills installed&lt;/code&gt; count. The exit code and the upgrade outcome kind are unchanged. “Without a &lt;code dir=&quot;auto&quot;&gt;Not updated, your local edit was kept&lt;/code&gt; line” still holds: the line is a notice, not a kept-drift report.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The regenerate checks the state contract when it runs.&lt;/strong&gt; The installer reads &lt;code dir=&quot;auto&quot;&gt;shared_skills_projection&lt;/code&gt; from &lt;code dir=&quot;auto&quot;&gt;STATE_SURFACES&lt;/code&gt; and regenerates only while that surface is &lt;code dir=&quot;auto&quot;&gt;DERIVED&lt;/code&gt; and git-&lt;code dir=&quot;auto&quot;&gt;IGNORED&lt;/code&gt;. Otherwise, including when the surface is missing from &lt;code dir=&quot;auto&quot;&gt;STATE_SURFACES&lt;/code&gt;, it fails closed to the exact-path consent path: a drifted projection is kept as &lt;code dir=&quot;auto&quot;&gt;consent_required&lt;/code&gt; unless the operator named it for overwrite.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A retired command’s drifted projection is pruned.&lt;/strong&gt; Under the same check, removing a retired command now deletes its drifted manifest-owned projection and its manifest entry, so the earlier consequence that it “is still kept as &lt;code dir=&quot;auto&quot;&gt;consent_required&lt;/code&gt;” no longer applies. A directory at the projection path is still refused, a path the manifest does not own is never touched, and an entry that other agents still own is narrowed to those owners while the file is left alone. Removing an agent (&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent config remove&lt;/code&gt;) still refuses a drifted projection.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
