<?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-26-3-e2e-hard-gate/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-26-3-e2e-hard-gate/</id>
  <title>ADR: Cross-Repo E2E as a Hard Mission-Review Gate</title>
  <updated>2026-04-26T00: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-26-3-e2e-hard-gate/"/>
  <summary>Cross-repo end-to-end scenarios become a hard pass/fail mission-review gate, escapable only through an explicit operator-authored exception artifact.</summary>
  <content type="html">&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;architecture/2.x/adr/2026-04-25-1-shared-package-boundary.md&lt;/code&gt;
(the shared package boundary that this gate defends downstream of)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;architecture/2.x/adr/2026-04-26-1-contract-pinning-resolved-version.md&lt;/code&gt;
(paired with this gate for the in-repo contract layer)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;architecture/2.x/adr/2026-04-26-2-auth-transport-boundary.md&lt;/code&gt;
(a downstream consumer of this gate’s protection)&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;Spec Kitty is a multi-repo product. The CLI (&lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt;) imports
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;spec-kitty-tracker&lt;/code&gt; as external PyPI
dependencies. The SaaS surface (&lt;code dir=&quot;auto&quot;&gt;spec-kitty-saas&lt;/code&gt;) consumes the same
contracts. The end-to-end repo (&lt;code dir=&quot;auto&quot;&gt;spec-kitty-end-to-end-testing&lt;/code&gt;) is the
only place where a real cross-repo workflow runs against the resolved
package versions in a clean venv.&lt;/p&gt;
&lt;p&gt;Pre-mission, the release gating model was:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Each package has its own CI suite (&lt;code dir=&quot;auto&quot;&gt;pytest&lt;/code&gt; + lint + types).&lt;/li&gt;
&lt;li&gt;The CLI has &lt;code dir=&quot;auto&quot;&gt;tests/contract/&lt;/code&gt; that asserts the &lt;em&gt;expected&lt;/em&gt; shape of
events/tracker payloads.&lt;/li&gt;
&lt;li&gt;There is no required check that the resolved package versions in the
CLI’s lockfile actually behave the way &lt;code dir=&quot;auto&quot;&gt;tests/contract/&lt;/code&gt; claims they
do, end to end, against a real downstream consumer.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;This produced two recurring failures the maintainers paid for:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Silent contract drift.&lt;/strong&gt; A &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; minor bump changed
envelope semantics (omitted a previously-required field, widened a
type). Package-local CI passed because the contract was never
cross-checked. The CLI shipped with the new version pinned in
&lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt;. Downstream consumers (&lt;code dir=&quot;auto&quot;&gt;spec-kitty-saas&lt;/code&gt; ingestion, the
e2e harness) failed in production with a missing-field exception.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Uninitialized-repo regressions.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;spec-kitty specify&lt;/code&gt; (and friends)
silently fell back to a sibling initialized repo when invoked in a
non-Spec-Kitty directory, writing artifacts into the wrong tree. The
bug was real but only reproduced cleanly in a multi-directory layout
the CLI’s own tests did not exercise.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Package-local CI cannot catch either class. They are
&lt;strong&gt;cross-repo, real-process, real-filesystem&lt;/strong&gt; failure modes. The
end-to-end repo exists precisely to catch them, but it was treated as an
optional integration check. Two recent missions
(&lt;code dir=&quot;auto&quot;&gt;shared-package-boundary-cutover-01KQ22DS&lt;/code&gt; and the present
&lt;code dir=&quot;auto&quot;&gt;stability-and-hygiene-hardening&lt;/code&gt; mission) paid for that softness in
rework.&lt;/p&gt;
&lt;p&gt;The mission spec (FR-038, FR-039, FR-040, FR-041) and the constraint
C-010 require that the e2e suite be a &lt;strong&gt;hard&lt;/strong&gt; gate at mission review,
with a documented operator-exception path for cases where the dev
SaaS endpoint is unreachable on the reviewer’s machine. This ADR locks
that gate.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;The cross-repo end-to-end suite at
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-end-to-end-testing/scenarios/&lt;/code&gt; is a &lt;strong&gt;hard&lt;/strong&gt; pass/fail gate
during &lt;code dir=&quot;auto&quot;&gt;spec-kitty-mission-review&lt;/code&gt;, alongside &lt;code dir=&quot;auto&quot;&gt;tests/contract/&lt;/code&gt; in the
CLI repo and the populated traceability matrix at
&lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;slug&gt;/issue-matrix.md&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;Three concrete obligations:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;The mission-review skill MUST run, in order:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;pytest spec-kitty/tests/contract/ -v&lt;/code&gt; — non-zero exit ⇒ FAIL&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;pytest spec-kitty/tests/architectural/ -v&lt;/code&gt; — non-zero exit ⇒ FAIL&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;pytest spec-kitty-end-to-end-testing/scenarios/ -v&lt;/code&gt; — non-zero
exit ⇒ FAIL &lt;strong&gt;unless&lt;/strong&gt; an operator exception artifact exists at
&lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;slug&gt;/mission-exception.md&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Read &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;slug&gt;/issue-matrix.md&lt;/code&gt; and assert every row has
a non-empty verdict that is one of &lt;code dir=&quot;auto&quot;&gt;fixed&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;verified-already-fixed&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;deferred-with-followup&lt;/code&gt;. Any other
value, including the literal &lt;code dir=&quot;auto&quot;&gt;unknown&lt;/code&gt; or an empty cell, is FAIL.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;The exception artifact has a fixed shape.&lt;/strong&gt; A
&lt;code dir=&quot;auto&quot;&gt;mission-exception.md&lt;/code&gt; file under &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;slug&gt;/&lt;/code&gt; MUST:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;name the operator who granted the exception;&lt;/li&gt;
&lt;li&gt;identify the failing scenario by file path and assertion;&lt;/li&gt;
&lt;li&gt;explain why the failure is environmental (e.g., dev SaaS endpoint
unreachable on reviewer’s machine) and not a code defect;&lt;/li&gt;
&lt;li&gt;record the command the operator ran to reproduce the failure;&lt;/li&gt;
&lt;li&gt;include a follow-up issue link or a written commitment to retry
the scenario in a documented future window.
The mission-review skill rejects an exception artifact that is
missing any of those fields.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;The exception path is bounded.&lt;/strong&gt; An operator exception covers a
&lt;em&gt;specific scenario&lt;/em&gt;, not the whole e2e suite. A mission whose e2e
suite has more than one failing scenario MUST get a separate
exception entry per scenario. A mission cannot ship with a blanket
“e2e is unreachable, skip the whole suite” waiver.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The four scenarios this mission ships are the floor, not the ceiling.
Future missions touching cross-repo behavior MUST add scenarios that
prove their behavior:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;dependent_wp_planning_lane.py&lt;/code&gt; — FR-001 + FR-005 + FR-038&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;uninitialized_repo_fail_loud.py&lt;/code&gt; — FR-032 + FR-039&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;saas_sync_enabled.py&lt;/code&gt; — FR-040&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;contract_drift_caught.py&lt;/code&gt; — FR-041&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Positive:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;A &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; candidate cannot be promoted to stable while
the e2e harness fails on a real consumer. The four stability and
contract failure modes that drove this mission can no longer ship
past mission review without a documented operator exception.&lt;/li&gt;
&lt;li&gt;The exception path is explicit and audited. “The maintainer
decided” without a &lt;code dir=&quot;auto&quot;&gt;mission-exception.md&lt;/code&gt; artifact is no longer
sufficient.&lt;/li&gt;
&lt;li&gt;The contract layer and the e2e layer are mutually reinforcing:
contract tests pin the &lt;em&gt;expected&lt;/em&gt; shape against the resolved
version, e2e tests pin the &lt;em&gt;actual&lt;/em&gt; shape against a running
downstream consumer, the matrix pins issue-level closure to a
specific test or commit.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Negative / costs:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Mission review is slower. The e2e suite has a wall-clock floor of
several minutes against a real dev SaaS endpoint. NFR-006 caps this
at 20 minutes.&lt;/li&gt;
&lt;li&gt;The dev SaaS endpoint becomes a hard dependency for full mission
acceptance. When the endpoint is unreachable on a reviewer’s
machine, the operator must produce an exception artifact instead
of silently approving. This is documented in
&lt;code dir=&quot;auto&quot;&gt;docs/migrations/cross-repo-e2e-gate.md&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The e2e repo is now a release-blocking dependency for the CLI and
the SaaS. Its own maintenance burden goes up; it cannot bit-rot
without breaking unrelated mission reviews.&lt;/li&gt;
&lt;li&gt;Cross-repo workflow: implementers and reviewers must commit to two
repos for missions that touch cross-repo behavior. The
cross-repo-e2e-gate migration doc walks operators through the
workflow.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Operational consequences:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;spec-kitty-mission-review&lt;/code&gt; skill (source at
&lt;code dir=&quot;auto&quot;&gt;src/doctrine/skills/spec-kitty-mission-review/SKILL.md&lt;/code&gt;) is
updated by T050 to enforce the gate.&lt;/li&gt;
&lt;li&gt;The migration doc at
&lt;code dir=&quot;auto&quot;&gt;docs/migrations/cross-repo-e2e-gate.md&lt;/code&gt; is the operator runbook.&lt;/li&gt;
&lt;li&gt;The four shipped e2e scenarios live in the e2e repo’s
&lt;code dir=&quot;auto&quot;&gt;scenarios/&lt;/code&gt; directory and are committed there as a separate
commit.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;alternatives-considered&quot;&gt;Alternatives Considered&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Alternative 1: Keep e2e as advisory, lean harder on
&lt;code dir=&quot;auto&quot;&gt;tests/contract/&lt;/code&gt;.&lt;/strong&gt; Rejected. Contract tests pin the expected shape
against an in-repo fixture. They do not run the resolved package’s
real code path against a real downstream consumer in a real venv.
The two failure modes that drove this mission both passed contract
tests and failed in real usage.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Alternative 2: Run e2e in CI on every PR, not at mission review.&lt;/strong&gt;
Considered. Worth doing; not a substitute for the mission-review
gate. A PR-level e2e run does not catch a multi-WP mission that
introduces cross-WP contract drift, because the drift only appears
when all WPs land together. The mission-review gate is the
post-merge “all WPs landed” check the per-PR check cannot do.
We will likely add per-PR e2e in a future ops-CI mission, on top of
this gate, not instead of it.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Alternative 3: A single combined “mission acceptance” pytest
suite that runs contract + architectural + e2e in one command.&lt;/strong&gt;
Rejected for now. The three suites have different dependency
profiles (contract is fast, architectural is fast, e2e needs a dev
SaaS endpoint). Treating them uniformly would cargo-cult e2e’s slow
external dependency onto every contract run. The mission-review
skill orchestrates the three calls separately and reports them
separately.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Alternative 4: Allow a blanket e2e waiver under
&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_E2E_OPTIONAL=1&lt;/code&gt;.&lt;/strong&gt; Rejected. C-010 explicitly forbids
this: “the mission MUST NOT be marked complete without either
executed e2e evidence or an explicit operator-approved exception.”
A blanket env-var override would re-introduce the silent-skip mode
the gate exists to prevent.&lt;/p&gt;
&lt;h2 id=&quot;references&quot;&gt;References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Spec: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/stability-and-hygiene-hardening-2026-04-01KQ4ARB/spec.md&lt;/code&gt;
(FR-038, FR-039, FR-040, FR-041, NFR-006, C-010)&lt;/li&gt;
&lt;li&gt;Research: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/stability-and-hygiene-hardening-2026-04-01KQ4ARB/research.md&lt;/code&gt;
(D1 issue traceability shape; this ADR formalizes the gate that
reads D1’s matrix)&lt;/li&gt;
&lt;li&gt;Migration: &lt;code dir=&quot;auto&quot;&gt;docs/migrations/cross-repo-e2e-gate.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Skill source: &lt;code dir=&quot;auto&quot;&gt;src/doctrine/skills/spec-kitty-mission-review/SKILL.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Issue matrix: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/stability-and-hygiene-hardening-2026-04-01KQ4ARB/issue-matrix.md&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
