<?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-07-23-2-post-consolidation-deferral-and-external-enforcement/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-07-23-2-post-consolidation-deferral-and-external-enforcement/</id>
  <title>Post-Consolidation Deferral and External Enforcement of Negative Invariants</title>
  <updated>2026-07-23T00: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-07-23-2-post-consolidation-deferral-and-external-enforcement/"/>
  <summary>Negative invariants are verified externally at a named `post-consolidation` phase on the `CONSOLIDATED` surface, never at a step whose integrated tree does not yet exist.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;ADR &lt;a href=&quot;/adr/3.x/2026-04-03-3-feature-acceptance-runs-on-the-integrated-mission-branch/&quot;&gt;2026-04-03-3&lt;/a&gt;
decided that &lt;em&gt;“Feature QA and &lt;code dir=&quot;auto&quot;&gt;accept&lt;/code&gt; MUST happen on the mission integration branch”&lt;/em&gt;, and
specified the negative-invariant verifier model down to its result vocabulary.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;That decision was never enforced in code, and this ADR does not enforce it literally either —
it addresses the narrower failure the gap produces.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;spec-kitty accept&lt;/code&gt; executes each negative
invariant’s &lt;code dir=&quot;auto&quot;&gt;verification_command&lt;/code&gt; from the pre-merge &lt;strong&gt;primary repository root&lt;/strong&gt;
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/acceptance/gates_core.py:298&lt;/code&gt;, passing a bare &lt;code dir=&quot;auto&quot;&gt;repo_root&lt;/code&gt;). Pre-merge, the
primary tree cannot contain the mission’s changes — they live on unmerged lane branches. An
honest invariant whose subject is something the mission &lt;em&gt;adds&lt;/em&gt; therefore evaluates against a tree
where it structurally cannot be true, is recorded &lt;code dir=&quot;auto&quot;&gt;still_present&lt;/code&gt;, and blocks acceptance
(issue #1834).&lt;/p&gt;
&lt;p&gt;The operator-visible consequence is documented and measurable:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The workaround is to declare no invariants at all. The flagship mission merged immediately
before this one (&lt;code dir=&quot;auto&quot;&gt;coord-commit-integrity-01KY5JS8&lt;/code&gt;) ships &lt;code dir=&quot;auto&quot;&gt;negative_invariants: []&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Across the repository: &lt;strong&gt;153 acceptance matrices, 40 non-&lt;code dir=&quot;auto&quot;&gt;pending&lt;/code&gt; negative invariants in 14
missions, zero carrying any record of which surface established them.&lt;/strong&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;A partial fix landed in &lt;code dir=&quot;auto&quot;&gt;b918e66df&lt;/code&gt;: a &lt;em&gt;recorded&lt;/em&gt; non-&lt;code dir=&quot;auto&quot;&gt;pending&lt;/code&gt; result is preserved rather than
re-judged. But &lt;code dir=&quot;auto&quot;&gt;pending&lt;/code&gt; is the scaffolded default, so an invariant nobody hand-recorded during
review still executes against the wrong tree. The failure was renamed, not removed.&lt;/p&gt;
&lt;p&gt;Two further problems block a naive fix:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;There is no pre-merge integrated tree to run against.&lt;/strong&gt; For a multi-lane mission, lanes are
independent branches; integration materialises only at lane consolidation. Making the
verification &lt;code dir=&quot;auto&quot;&gt;cwd&lt;/code&gt; “workspace-aware” would require designating one lane’s worktree as the
integrated tree — fabricating exactly the authority this class of defect is about.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;merge&lt;/code&gt; is a three-sense overloaded term here&lt;/strong&gt; (lane consolidation / branch integration /
publish to origin), so “defer it to merge” does not say which event is being waited on.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Honour the existing ADR&lt;/strong&gt; — 2026-04-03-3 is Accepted; the gap is enforcement, not intent.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Never fabricate an evaluation surface&lt;/strong&gt; — a gate must judge a real tree or refuse.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Do not add abort paths to consolidation&lt;/strong&gt; — the merge executor’s compensating-transaction
machinery is being consolidated concurrently; a new abort trigger inside it is unsafe.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Terminology precision&lt;/strong&gt; — the name must state which event is awaited.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Honest enforcement&lt;/strong&gt; — an enforcer that cannot fire is worse than an admitted gap, because it
reads as a guarantee.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Downstream truthfulness&lt;/strong&gt; — Spec Kitty runs in repositories that do not share this project’s
CI.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option 1:&lt;/strong&gt; Workspace-aware verification &lt;code dir=&quot;auto&quot;&gt;cwd&lt;/code&gt; — resolve an integrated tree pre-merge.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2:&lt;/strong&gt; Never overwrite a recorded result (the &lt;code dir=&quot;auto&quot;&gt;b918e66df&lt;/code&gt; half-fix), and stop there.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3:&lt;/strong&gt; Defer unjudgeable invariants to a &lt;strong&gt;post-consolidation&lt;/strong&gt; phase, verified on the
consolidated mission tree, enforced externally in CI and disclosed at assignment time.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option: Option 3.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;Option 1 is rejected as a fiction: the tree it depends on does not exist pre-merge for a
multi-lane mission. Option 2 is already landed and demonstrably insufficient — it protects only
invariants a reviewer remembered to record by hand, and a design that requires a discipline
reminder to enforce a constraint is structurally incomplete.&lt;/p&gt;
&lt;h3 id=&quot;core-decision&quot;&gt;Core Decision&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;post-consolidation&lt;/code&gt; is the canonical name&lt;/strong&gt; for the phase, the surface (&lt;code dir=&quot;auto&quot;&gt;CONSOLIDATED&lt;/code&gt;), and
the verification that runs there. The bare word &lt;em&gt;merge&lt;/em&gt; is never used for it. This is the same
disambiguation discipline already applied to &lt;code dir=&quot;auto&quot;&gt;primary&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;base&lt;/code&gt;, and is why the
surface member is &lt;code dir=&quot;auto&quot;&gt;CONSOLIDATED&lt;/code&gt; rather than &lt;code dir=&quot;auto&quot;&gt;MERGED&lt;/code&gt; (see ADR
&lt;a href=&quot;/adr/3.x/2026-07-23-1-surface-vocabulary-two-domains-and-topology-surface-rename/&quot;&gt;2026-07-23-1&lt;/a&gt;).&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;A &lt;code dir=&quot;auto&quot;&gt;pending&lt;/code&gt; invariant whose subject cannot exist in the current surface is recorded
&lt;code dir=&quot;auto&quot;&gt;deferred_to_consolidation&lt;/code&gt;&lt;/strong&gt; with a stated reason — never &lt;code dir=&quot;auto&quot;&gt;still_present&lt;/code&gt;. Deferral is a
scheduled follow-up, not an absence of information.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Every recorded judgement carries provenance&lt;/strong&gt; — the ref and the &lt;code dir=&quot;auto&quot;&gt;TopologySurface&lt;/code&gt; it was
established against. A judgement without provenance is a validation error. This operationalises
2026-04-03-3’s requirement that evidence &lt;em&gt;“distinguish absence from verifier failure”&lt;/em&gt;: it also
distinguishes absence-here from absence-anywhere.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;overall_verdict&lt;/code&gt; gains a fourth value, &lt;code dir=&quot;auto&quot;&gt;pass_pending_consolidation&lt;/code&gt;.&lt;/strong&gt; The existing three
have no assignment satisfying both “must not block acceptance” and “must not silently pass”:
allowing the deferred value yields &lt;code dir=&quot;auto&quot;&gt;pass&lt;/code&gt;, disallowing it yields &lt;code dir=&quot;auto&quot;&gt;fail&lt;/code&gt;, and grouping it with
&lt;code dir=&quot;auto&quot;&gt;pending&lt;/code&gt; reproduces the block being removed.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Verification runs after consolidation completes, as an ordinary governed Op&lt;/strong&gt;, and a violation
fails &lt;strong&gt;that Op&lt;/strong&gt; — not the consolidation. No new CLI verb: it is dispatched through the
canonical surface (&lt;code dir=&quot;auto&quot;&gt;spec-kitty dispatch&lt;/code&gt;, closed via &lt;code dir=&quot;auto&quot;&gt;profile-invocation complete&lt;/code&gt;), single-agent
or squad-based like any other. What distinguishes it is when it runs and what it checks.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Enforcement is EXTERNAL to the mission loop.&lt;/strong&gt; A CI consistency check, at the front of the
quality run, fails any pull request still carrying a dangling &lt;code dir=&quot;auto&quot;&gt;deferred_to_consolidation&lt;/code&gt;
element.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;The deferral discloses its own contract at assignment time.&lt;/strong&gt; When Spec Kitty assigns
&lt;code dir=&quot;auto&quot;&gt;deferred_to_consolidation&lt;/code&gt; it must state that the mission loop will not verify it and name the
gate the operator needs.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;why-enforcement-cannot-live-in-the-loop--measured&quot;&gt;Why enforcement cannot live in the loop — measured&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;overall_verdict&lt;/code&gt; has exactly &lt;strong&gt;one&lt;/strong&gt; consumer in &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;acceptance/gates_core.py:311&lt;/code&gt;), inside
the accept gate. &lt;code dir=&quot;auto&quot;&gt;read_acceptance_matrix&lt;/code&gt; is consumed only by &lt;code dir=&quot;auto&quot;&gt;acceptance/gates_core.py&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;acceptance/summary_core.py&lt;/code&gt;. Both run &lt;strong&gt;pre-consolidation&lt;/strong&gt;. Nothing reads the acceptance matrix
after &lt;code dir=&quot;auto&quot;&gt;spec-kitty merge&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;An earlier candidate enforcer — &lt;em&gt;“the matrix cannot reach a terminal verdict while deferrals
remain”&lt;/em&gt; — is therefore &lt;strong&gt;circular&lt;/strong&gt;: it blocks at the only gate that reads the artifact, which is
the gate that created the deferral and which by design must not block on it. It is withdrawn and
recorded here so it is not re-proposed.&lt;/p&gt;
&lt;p&gt;The pull request is the first point at which the consolidated tree and the acceptance artifact are
both present and something automated reads them. That is where the gate belongs.&lt;/p&gt;
&lt;h3 id=&quot;why-disclosure-is-a-requirement-not-a-courtesy&quot;&gt;Why disclosure is a requirement, not a courtesy&lt;/h3&gt;
&lt;p&gt;Spec Kitty ships into other people’s repositories, where this project’s CI check does not exist.
An enforcement model that works only upstream, applied silently, would export the exact failure
this ADR removes: a gate that looks authoritative and verifies nothing. The tool must therefore
state the contract at the moment it assigns the status.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;positive&quot;&gt;Positive&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;ADR 2026-04-03-3’s intent is finally enforceable: acceptance judges the integrated product,
because unjudgeable invariants wait for the integrated tree instead of failing against the wrong
one.&lt;/li&gt;
&lt;li&gt;Command-verified negative invariants become usable, removing the incentive to ship
&lt;code dir=&quot;auto&quot;&gt;negative_invariants: []&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Consolidation gains no new abort path, so the concurrent consolidation of the merge executor’s
two compensating transactions is unaffected.&lt;/li&gt;
&lt;li&gt;Every judgement states its surface, so a reader can tell whether it is still meaningful.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative--accepted-trade-offs&quot;&gt;Negative / accepted trade-offs&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Between assignment and the PR check, a deferred invariant is genuinely unverified&lt;/strong&gt;, and a
repository that never adds the gate never verifies it. This is accepted as honest and visible,
in preference to a constraint no code can express.&lt;/li&gt;
&lt;li&gt;Feedback arrives later than acceptance. Late-but-honest is preferred to early-but-wrong; the
blast radius is bounded because the consolidated tree is the mission/PR branch, not the primary
branch.&lt;/li&gt;
&lt;li&gt;A fourth verdict value and five new invariant fields require a one-time backfill migration
across 153 existing matrices, plus an archive path for missions whose recorded state cannot
migrate honestly — a migration that invented provenance for unknowable surfaces would itself be
fabricating evidence.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;neutral&quot;&gt;Neutral&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;deferred_to_consolidation&lt;/code&gt; is not in older readers’ &lt;code dir=&quot;auto&quot;&gt;NEGATIVE_INVARIANT_RESULTS&lt;/code&gt;, so an older
Spec Kitty reading a new matrix computes &lt;code dir=&quot;auto&quot;&gt;fail&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;pass_pending_consolidation&lt;/code&gt; does &lt;strong&gt;not&lt;/strong&gt; have
this problem — &lt;code dir=&quot;auto&quot;&gt;overall_verdict&lt;/code&gt; is excluded from deserialisation and recomputed.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Supersedes nothing, and does &lt;strong&gt;not&lt;/strong&gt; implement 2026-04-03-3 literally. That ADR’s instruction
is to relocate the whole &lt;code dir=&quot;auto&quot;&gt;accept&lt;/code&gt; step onto the mission integration branch; this ADR keeps
&lt;code dir=&quot;auto&quot;&gt;accept&lt;/code&gt; where it is and defers only the &lt;strong&gt;subset of judgements that cannot be true&lt;/strong&gt; on the
pre-consolidation surface. It therefore realises 2026-04-03-3’s &lt;em&gt;intent&lt;/em&gt; — that acceptance
judges the integrated product rather than an isolated slice — by a narrower mechanism, and
leaves the relocation question open. Relationship: &lt;strong&gt;inherits the intent of&lt;/strong&gt; ADR
&lt;a href=&quot;/adr/3.x/2026-04-03-3-feature-acceptance-runs-on-the-integrated-mission-branch/&quot;&gt;2026-04-03-3&lt;/a&gt;; does
not discharge it.&lt;/li&gt;
&lt;li&gt;Surface vocabulary: ADR
&lt;a href=&quot;/adr/3.x/2026-07-23-1-surface-vocabulary-two-domains-and-topology-surface-rename/&quot;&gt;2026-07-23-1&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;Issues: #1834 (the live leg), #2885, #2795, #2882.&lt;/li&gt;
&lt;li&gt;Mission: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/lifecycle-gate-execution-context-01KY72GQ/&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;User-facing guide: &lt;a href=&quot;/guides/how-to/missions/accept-and-merge/&quot;&gt;accept-and-merge&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-09-22&quot;&gt;Amendment (2026-09-22)&lt;/h2&gt;
&lt;p&gt;The &lt;strong&gt;“do not add abort paths to consolidation”&lt;/strong&gt; principle — stated as a Decision Driver
(“Do not add abort paths to consolidation”, Decision Drivers, above) and reaffirmed under
Consequences (“Consolidation gains no new abort path”, Positive Consequences, above) — is
&lt;strong&gt;qualified, not reversed, for gate/verdict artifacts&lt;/strong&gt;. It continues to govern the general
consolidation path unchanged.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/write-side-seam-matrix-tracer-01KYP3MH/contracts/merge-driver-algorithm.md&lt;/code&gt;
originally cited this ADR to justify a “structured conflict result (fail-closed, no
consolidation abort)” behavior for the row-aware matrix merge driver: a both-sides-diverged
field on a keyed row (e.g. &lt;code dir=&quot;auto&quot;&gt;pass_fail&lt;/code&gt;) was embedded as a git-style conflict-marker string
&lt;em&gt;inside the field value itself&lt;/em&gt;, and the merge proceeded. For a &lt;strong&gt;gate/verdict artifact&lt;/strong&gt;
(the acceptance matrix, the issue matrix) this reading was unsafe: an embedded marker string
in &lt;code dir=&quot;auto&quot;&gt;pass_fail&lt;/code&gt; is not human prose to review later, it is a value the artifact’s own
verdict-computation logic reads — and it recomputed &lt;code dir=&quot;auto&quot;&gt;overall_verdict&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;fail&lt;/code&gt;, silently
corrupting an already-accepted mission’s recorded state. That defect and its fix are tracked
under #4880.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Amended rule:&lt;/strong&gt; for a gate/verdict artifact only, a both-sides-diverged keyed-row field is
unresolvable by machine and &lt;strong&gt;fails closed&lt;/strong&gt; — the driver raises, the CLI invocation exits
non-zero, and &lt;code dir=&quot;auto&quot;&gt;git merge&lt;/code&gt; is left for a human to resolve (&lt;code dir=&quot;auto&quot;&gt;git merge --abort&lt;/code&gt; is available to
the operator; the mission integration path does not silently advance past it). Conflict
markers are never embedded as field values in a gate/verdict artifact.&lt;/p&gt;
&lt;p&gt;This qualification is scoped narrowly: it does &lt;strong&gt;not&lt;/strong&gt; apply to non-authoritative prose
artifacts (e.g. the review-cycle &lt;code dir=&quot;auto&quot;&gt;.md&lt;/code&gt;, whose verdict authority lives elsewhere), which keep
the original best-effort, no-abort behavior this ADR describes. It also does not reopen or
weaken any Core Decision item (1–7, including item 3’s provenance requirement, which is
untouched by this amendment) or the general “no new abort path in the merge executor’s
compensating-transaction machinery” principle for any surface other than gate/verdict
artifacts.&lt;/p&gt;
&lt;p&gt;The originating contract and unit-gate mission
(&lt;code dir=&quot;auto&quot;&gt;kitty-specs/write-side-seam-matrix-tracer-01KYP3MH/...&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;kitty-specs/gate-artifact-merge-driver-unit-gate-01KZPG7V/spec.md&lt;/code&gt; FR-004) are &lt;strong&gt;immutable
archived snapshots&lt;/strong&gt; and are deliberately NOT edited here — their original wording is
preserved as history. This amendment (a living governance record) is the authoritative
supersession of that “no consolidation abort” reading for gate/verdict artifacts; the new
behavior and the FR-004 supersession are recorded in the #4880 mission’s own living
contract: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/acceptance-matrix-merge-fail-closed-01M34HG8/contracts/merge-driver-algorithm-amendment.md&lt;/code&gt;.&lt;/p&gt;</content>
</entry>
