<?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-13-1-acceptance-scenarios-link-to-promises-by-identifier-only/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-10-13-1-acceptance-scenarios-link-to-promises-by-identifier-only/</id>
  <title>ADR: acceptance scenarios link to product promises by identifier only; core checks the scenario contract per pull request and hands on versioned evidence</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-13-1-acceptance-scenarios-link-to-promises-by-identifier-only/"/>
  <summary>Scenarios cite promises only by @promise identifier; a JDK-free per-PR check validates feature files, tags and step bindings; nightly legs upload versioned evidence.</summary>
  <content type="html">&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted, accepted by the owner on 2026-10-13. Amended 2026-10-15, see &lt;a href=&quot;#amendment-2026-10-15-authored-files-in-fixture-builders&quot;&gt;Amendment&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-10-13&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (owner), with the spec-kitty-qa maintainers for the evidence contract.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; follows &lt;a href=&quot;/adr/4.x/2026-10-11-3-acceptance-testing-and-bdd-support/&quot;&gt;ADR 2026-10-11-3&lt;/a&gt; and its 2026-10-11 amendment. The QA half is spec-kitty-qa ADR-0001 and ADR-0002. Design: &lt;a href=&quot;/architecture/acceptance-scenario-contract/&quot;&gt;the acceptance scenario contract&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Reader:&lt;/strong&gt; a maintainer deciding what this repository owns about acceptance scenarios, and what it hands to spec-kitty-qa.&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;ADR 2026-10-11-3 put Gherkin scenarios in &lt;code dir=&quot;auto&quot;&gt;tests/scenarios/&lt;/code&gt; and a Cucumber-JVM nightly in
&lt;code dir=&quot;auto&quot;&gt;acceptance-jvm/&lt;/code&gt;. Its amendment moved the promise index, the per-PR promise-tag check and the
index sync to spec-kitty-qa, which left &lt;code dir=&quot;auto&quot;&gt;@promise&lt;/code&gt; inert here and the &lt;code dir=&quot;auto&quot;&gt;scenarios&lt;/code&gt; router group
gating nothing.&lt;/p&gt;
&lt;p&gt;Four problems remain:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;No stated boundary.&lt;/strong&gt; Nothing says what a scenario may carry about a promise. Scenarios are
about to be drafted from promise pages, with AI help, so wording, rationale or status could
leak into this public repository.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No per-PR check at all.&lt;/strong&gt; A malformed feature file, a bad tag or a step with no binding is
found only by the next nightly.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Evidence cannot be traced to a build.&lt;/strong&gt; The &lt;code dir=&quot;auto&quot;&gt;@wip&lt;/code&gt; pass runs after the gating pass with
&lt;code dir=&quot;auto&quot;&gt;--rerun-tasks&lt;/code&gt; into the same folders, so it overwrites the gating Cucumber JSON and JUnit XML,
and mixes both passes’ Allure results, before the upload.
No result records the CLI version, commit, OS or pass, the Allure folder is not set, and the
artifact has no explicit retention.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fixtures stop at &lt;code dir=&quot;auto&quot;&gt;init&lt;/code&gt;.&lt;/strong&gt; Arrange steps cannot reach a project with a mission in it, so the
next promises cannot be checked.&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;Promise content stays out of the open-core repository.&lt;/li&gt;
&lt;li&gt;Each repository keeps the scenario tooling that suits its stack; no shared format is forced
across the promise and scenario layers.&lt;/li&gt;
&lt;li&gt;A contributor gets scenario feedback on the pull request, without a JDK.&lt;/li&gt;
&lt;li&gt;Every result names the exact build, OS and pass it came from.&lt;/li&gt;
&lt;li&gt;Scenarios stay black-box: steps drive the CLI as a process.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Identifier-only link, syntax checked here, evidence bundle per leg&lt;/strong&gt; (chosen).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Sync a public promise index into core and check identifiers against it.&lt;/strong&gt; This was ADR
2026-10-11-3’s original plan. Rejected by its amendment, and still rejected: it couples core to
the promise store’s lifecycle, and needs a cross-repository token.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Carry the promise slug or title in the tag.&lt;/strong&gt; Rejected: slugs are renamed, and titles leak
promise wording.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Run the JVM suite per pull request.&lt;/strong&gt; Rejected: every contributor would pay for a JDK and a
wheel build on every change, while the per-PR question is only “does this parse, and is every
step bound?”.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Leave evidence as it is, and let spec-kitty-qa infer context from the run.&lt;/strong&gt; Rejected: the
gating results are overwritten before the upload, and the run alone does not say which CLI
version was built.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; option 1.&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;The link is the persistent promise identifier.&lt;/strong&gt; A scenario cites a promise only as
&lt;code dir=&quot;auto&quot;&gt;@promise:&amp;#x3C;id&gt;&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;id&gt;&lt;/code&gt; is opaque here and matches &lt;code dir=&quot;auto&quot;&gt;[A-Za-z0-9][A-Za-z0-9._-]*&lt;/code&gt;. No promise
wording, slug, status or rationale goes into this repository. Resolving identifiers, computing
coverage and reporting gaps stay in spec-kitty-qa.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Tag vocabulary.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;@promise:&amp;#x3C;id&gt;&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;@wip&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;@wip-owner:&amp;#x3C;handle&gt;&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;@wip-since:&amp;#x3C;YYYY-MM-DD&gt;&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;@manual&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;@defect:&amp;#x3C;issue&gt;&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;@qa:&amp;#x3C;ref&gt;&lt;/code&gt;; free-form bare tags. A
drafted scenario lands as &lt;code dir=&quot;auto&quot;&gt;@wip&lt;/code&gt;. Only a person adds a &lt;code dir=&quot;auto&quot;&gt;@promise&lt;/code&gt; tag.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Per-PR scenario check.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_scenario_contract.py&lt;/code&gt;, standard library
plus first-party &lt;code dir=&quot;auto&quot;&gt;kernel.clock&lt;/code&gt; (no third-party dependency), checks that every feature file parses, every tag follows the vocabulary, and every step
of a scenario without &lt;code dir=&quot;auto&quot;&gt;@wip&lt;/code&gt; matches exactly one step definition read from the
&lt;code dir=&quot;auto&quot;&gt;acceptance-jvm&lt;/code&gt; step annotations. It has one broken fixture per rule. The &lt;code dir=&quot;auto&quot;&gt;scenarios&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;acceptance_jvm&lt;/code&gt; router groups gate the job that runs it. This narrows the 2026-10-11-3
amendment’s “the &lt;code dir=&quot;auto&quot;&gt;scenarios&lt;/code&gt; group gates no per-PR job”; it does not bring back the promise
index.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Evidence bundle.&lt;/strong&gt; Each pass (gating, &lt;code dir=&quot;auto&quot;&gt;@wip&lt;/code&gt;) writes its own folder under
&lt;code dir=&quot;auto&quot;&gt;acceptance-jvm/build/acceptance/&amp;#x3C;pass&gt;/&lt;/code&gt;, with the Allure results folder set explicitly. The
runner writes Allure &lt;code dir=&quot;auto&quot;&gt;environment.properties&lt;/code&gt; (CLI version, commit, OS, JDK, pass) and
&lt;code dir=&quot;auto&quot;&gt;executor.json&lt;/code&gt;. The job writes &lt;code dir=&quot;auto&quot;&gt;evidence.json&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;schema_version&lt;/code&gt; 1) per leg. The upload keeps
the name &lt;code dir=&quot;auto&quot;&gt;acceptance-bdd-results-&amp;#x3C;os&gt;&lt;/code&gt;, fails when the gating results are missing, and keeps
them for 30 days. The job’s dead &lt;code dir=&quot;auto&quot;&gt;pull_request&lt;/code&gt; condition is removed.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Black-box fixture builders.&lt;/strong&gt; Builders that reach a mission state do so only by running the
CLI through the driver, never by writing project files directly.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Scenarios can be drafted from promises and published without exposing promise content.&lt;/li&gt;
&lt;li&gt;Broken scenarios and unbound steps are caught on the pull request.&lt;/li&gt;
&lt;li&gt;spec-kitty-qa can attribute every result to a build, an OS and a pass, and the gating evidence
is no longer overwritten.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;A second, partial Gherkin reader and Cucumber expression matcher exist beside the JVM runner.
They must follow the runner: an unsupported parameter type fails the check rather than passing.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;scenarios&lt;/code&gt; router group now runs a job on scenario-only pull requests.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;@promise&lt;/code&gt; identifiers are still not checked for existence here; a typo’d identifier is found by
spec-kitty-qa’s trace lint, not on the pull request.&lt;/li&gt;
&lt;li&gt;The Allure report, its history and the trace lint stay in spec-kitty-qa.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_scenario_contract.py&lt;/code&gt; passes on the real tree, and each broken fixture
fails its rule.&lt;/li&gt;
&lt;li&gt;A nightly leg’s artifact holds &lt;code dir=&quot;auto&quot;&gt;gating/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;wip/&lt;/code&gt; folders, an &lt;code dir=&quot;auto&quot;&gt;evidence.json&lt;/code&gt; with the commit
and CLI version, and Allure results with &lt;code dir=&quot;auto&quot;&gt;environment.properties&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;grep -r &quot;promise&quot; tests/scenarios&lt;/code&gt; finds only &lt;code dir=&quot;auto&quot;&gt;@promise:&amp;#x3C;id&gt;&lt;/code&gt; tags and guide text, no promise
wording.&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;&lt;a href=&quot;/architecture/acceptance-scenario-contract/&quot;&gt;The acceptance scenario contract&lt;/a&gt;: the
design, including the fixture builders.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/development/testing/acceptance-scenarios/&quot;&gt;CLI acceptance scenarios&lt;/a&gt;: how to write and
run scenarios today.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-10-15-authored-files-in-fixture-builders&quot;&gt;Amendment (2026-10-15): authored files in fixture builders&lt;/h2&gt;
&lt;p&gt;Decision 6 of &lt;a href=&quot;/adr/4.x/2026-10-15-1-qa-and-core-share-the-acceptance-scenarios-and-absorb-engineering-tests-through-a-ledger/&quot;&gt;ADR 2026-10-15-1&lt;/a&gt;
(operator ruling) narrows decision 5 above. A fixture builder may write the files an agent or a user
authors: the planning files of &lt;code dir=&quot;auto&quot;&gt;specify&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;plan&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;tasks&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;plan.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tasks.md&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;tasks/WP*.md&lt;/code&gt;), a work package’s code in its checkout, review feedback outside the repository, and
plain files a user edits in git. It still reaches every state through the CLI and never writes
CLI-managed state (&lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;, the status log, &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;, review-cycle records, &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt;).&lt;/p&gt;</content>
</entry>
