<?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-03-3-feature-acceptance-runs-on-the-integrated-mission-branch/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-03-3-feature-acceptance-runs-on-the-integrated-mission-branch/</id>
  <title>Feature Acceptance Runs on the Integrated Mission Branch</title>
  <updated>2026-04-03T00: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-03-3-feature-acceptance-runs-on-the-integrated-mission-branch/"/>
  <summary>Mission acceptance and QA must run on the integrated mission branch, mapping every critical requirement to an automated test or a manual evidence item.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;WP review can prove that a branch diff is coherent. It cannot prove that the
integrated feature behaves correctly once multiple lanes are merged together.&lt;/p&gt;
&lt;p&gt;Feature &lt;code dir=&quot;auto&quot;&gt;028-saas-active-projects-shell&lt;/code&gt; demonstrated the gap:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;route cleanup was treated as evidence that the old mission page was gone,&lt;/li&gt;
&lt;li&gt;the old fallback mission page still existed behind the new canonical route,&lt;/li&gt;
&lt;li&gt;the integrated user journey was therefore broken even though WP review had
passed.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;This is not a planner or merge-topology problem alone. It is an acceptance
problem. Feature completion must be evaluated against the integrated mission
branch and against the actual user journey, including forbidden fallback paths.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Product truth over branch folklore&lt;/strong&gt; — acceptance must validate what the
user can actually do.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Integrated QA&lt;/strong&gt; — QA must run against the real integrated mission branch.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Negative invariant enforcement&lt;/strong&gt; — removed surfaces must be proven absent,
not merely hidden from primary navigation.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Evidence discipline&lt;/strong&gt; — manual QA must leave durable proof, not just a
checkbox.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Representative data&lt;/strong&gt; — acceptance must exercise realistic data paths, not
only fixture-backed happy paths.&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; Accept a feature by aggregating WP approvals&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2:&lt;/strong&gt; Allow QA and acceptance to run on any convenient branch&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3:&lt;/strong&gt; Require feature-level acceptance on the integrated mission branch with explicit evidence&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;, because acceptance must judge the integrated
product, not isolated implementation slices.&lt;/p&gt;
&lt;h3 id=&quot;core-decision&quot;&gt;Core Decision&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;WP review may happen on a lane branch.&lt;/li&gt;
&lt;li&gt;Feature QA and &lt;code dir=&quot;auto&quot;&gt;accept&lt;/code&gt; MUST happen on the mission integration branch.&lt;/li&gt;
&lt;li&gt;A feature is not acceptable until its critical user journeys are validated on
that integrated branch.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;acceptance-contract&quot;&gt;Acceptance Contract&lt;/h3&gt;
&lt;p&gt;For each feature, acceptance MUST map every critical requirement to one of:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;an automated test, or&lt;/li&gt;
&lt;li&gt;a manual QA evidence item.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;If neither exists for a requirement, acceptance is blocked.&lt;/p&gt;
&lt;h3 id=&quot;negative-invariant-rule&quot;&gt;Negative Invariant Rule&lt;/h3&gt;
&lt;p&gt;When a spec says a legacy or unwanted surface is “gone”, acceptance MUST verify
all relevant dimensions, not only one.&lt;/p&gt;
&lt;p&gt;At minimum, the following must be checked where applicable:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;no primary route remains,&lt;/li&gt;
&lt;li&gt;no navigation entry remains,&lt;/li&gt;
&lt;li&gt;no compatibility redirect lands on the removed surface itself,&lt;/li&gt;
&lt;li&gt;no fallback code path or secondary entrypoint can still render the removed
surface.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;negative-invariant-verifier-model&quot;&gt;Negative Invariant Verifier Model&lt;/h3&gt;
&lt;p&gt;Negative invariant evidence MUST distinguish absence from verifier failure.
&lt;code dir=&quot;auto&quot;&gt;grep_absence&lt;/code&gt; remains a cheap textual fallback, but only &lt;code dir=&quot;auto&quot;&gt;grep&lt;/code&gt; exit code 1
proves absence. Exit code 0 means the forbidden surface is still present. Exit
codes greater than 1 mean verifier failure and MUST produce a blocking
&lt;code dir=&quot;auto&quot;&gt;verification_error&lt;/code&gt;, not &lt;code dir=&quot;auto&quot;&gt;confirmed_absent&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;Structured surfaces SHOULD use typed verifiers instead of grep:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;command registry inspection for command absence,&lt;/li&gt;
&lt;li&gt;route table inspection for route absence,&lt;/li&gt;
&lt;li&gt;AST or import graph checks for code-level bans,&lt;/li&gt;
&lt;li&gt;parsed config or manifest inspection for configuration invariants,&lt;/li&gt;
&lt;li&gt;orchestrator/state APIs for workflow-state invariants.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Every verifier SHOULD declare the checked surface, absence semantics, evidence
shape, and blocking behavior. Its tests MUST prove both positive detection
(&lt;code dir=&quot;auto&quot;&gt;still_present&lt;/code&gt;) and negative absence (&lt;code dir=&quot;auto&quot;&gt;confirmed_absent&lt;/code&gt;), and SHOULD include
a verifier-failure case (&lt;code dir=&quot;auto&quot;&gt;verification_error&lt;/code&gt;) where the verifier depends on
parsing, external commands, or structured inputs.&lt;/p&gt;
&lt;h3 id=&quot;manual-qa-evidence-rule&quot;&gt;Manual QA Evidence Rule&lt;/h3&gt;
&lt;p&gt;Manual QA evidence MUST include, at minimum:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;the exact URL or command exercised,&lt;/li&gt;
&lt;li&gt;the scenario/data precondition,&lt;/li&gt;
&lt;li&gt;the observed outcome,&lt;/li&gt;
&lt;li&gt;a screenshot, DOM snapshot, or equivalent durable artifact.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;representative-data-rule&quot;&gt;Representative Data Rule&lt;/h3&gt;
&lt;p&gt;For UI features, acceptance MUST cover representative cases that reflect real
product risk, not only ideal fixtures. At minimum:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;the expected happy path,&lt;/li&gt;
&lt;li&gt;a missing-data or degraded-data path,&lt;/li&gt;
&lt;li&gt;one identity/uniqueness edge case if the feature depends on keyed lookups or
routing,&lt;/li&gt;
&lt;li&gt;real dev/staging data when such data exists and is materially different from
fixtures.&lt;/li&gt;
&lt;/ol&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;Acceptance now evaluates the product the user actually sees.&lt;/li&gt;
&lt;li&gt;Hidden fallback paths become explicit acceptance targets.&lt;/li&gt;
&lt;li&gt;QA artifacts become durable evidence rather than unverifiable statements.&lt;/li&gt;
&lt;li&gt;Features like 028 can fail acceptance for the correct reason before merge.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative&quot;&gt;Negative&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Acceptance is more demanding and may take longer.&lt;/li&gt;
&lt;li&gt;Manual QA requires disciplined evidence capture.&lt;/li&gt;
&lt;li&gt;Some features will need better staging/dev datasets to be meaningfully tested.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;neutral&quot;&gt;Neutral&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;WP-level review remains valuable, but it is no longer treated as sufficient
proof of integrated correctness.&lt;/li&gt;
&lt;li&gt;Compatibility redirects may still exist, but they must be validated against
the negative invariant rule.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;This decision is validated when:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;acceptance artifacts consistently reference the mission integration branch,&lt;/li&gt;
&lt;li&gt;critical user journeys are provably exercised before a feature is merged,&lt;/li&gt;
&lt;li&gt;removed legacy surfaces cannot survive through fallback code paths without
failing acceptance,&lt;/li&gt;
&lt;li&gt;QA evidence is attached for any requirement not covered by automation.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;option-1-aggregate-wp-approvals&quot;&gt;Option 1: Aggregate WP approvals&lt;/h3&gt;
&lt;p&gt;Treat the feature as done when all WPs are approved.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Simple accounting model.&lt;/li&gt;
&lt;li&gt;Minimal extra process after WP review.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Misses integrated failures and overlap regressions.&lt;/li&gt;
&lt;li&gt;Cannot prove that deleted surfaces are truly unreachable.&lt;/li&gt;
&lt;li&gt;Encourages “all boxes green” without validating the user journey.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-2-allow-qa-on-any-convenient-branch&quot;&gt;Option 2: Allow QA on any convenient branch&lt;/h3&gt;
&lt;p&gt;Run QA on whichever branch is easiest to access.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Flexible and cheap in the short term.&lt;/li&gt;
&lt;li&gt;Easy to parallelize.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Results are not authoritative for the final integrated product.&lt;/li&gt;
&lt;li&gt;Makes acceptance outcomes branch-dependent and non-reproducible.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-3-require-integrated-mission-branch-acceptance&quot;&gt;Option 3: Require integrated mission-branch acceptance&lt;/h3&gt;
&lt;p&gt;Run feature QA and acceptance only on the mission integration branch.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Acceptance measures the real assembled feature.&lt;/li&gt;
&lt;li&gt;Negative invariants become enforceable.&lt;/li&gt;
&lt;li&gt;QA evidence becomes reviewable and reproducible.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Requires stronger orchestration and evidence capture.&lt;/li&gt;
&lt;li&gt;Exposes more failures late unless teams integrate lanes continuously.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Related ADRs:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;2026-04-03-1-execution-lanes-own-worktrees-and-mission-branches.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;2026-04-03-2-review-approval-and-integration-completion-are-distinct.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;2026-02-17-1-canonical-next-command-runtime-loop.md&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Related Product Document:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Companion planning artifact: &lt;code dir=&quot;auto&quot;&gt;prd-lane-based-execution-and-feature-acceptance-gates-v1.md&lt;/code&gt; in the planning repo&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
