<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/architecture/acceptance-scenario-contract/">
  <id>https://docs.spec-kitty.ai/architecture/acceptance-scenario-contract/</id>
  <title>The acceptance scenario contract</title>
  <updated>2026-10-15T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/architecture/acceptance-scenario-contract/"/>
  <summary>How CLI acceptance scenarios link to product promises by identifier only, what a pull request checks about them, and what evidence each nightly run hands on.</summary>
  <content type="html">&lt;span id=&quot;the-acceptance-scenario-contract&quot;&gt;&lt;/span&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Status: design of record, mostly shipped.&lt;/strong&gt; The scenario tree, the Cucumber-JVM runner and
the nightly job exist (&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;).
This page designs the four additions in
&lt;a href=&quot;/adr/4.x/2026-10-13-1-acceptance-scenarios-link-to-promises-by-identifier-only/&quot;&gt;ADR 2026-10-13-1&lt;/a&gt;:
the scenario contract (A), the per-pull-request check (B), the evidence bundle (C) and the
fixture builders (D) are built. Ownership and the absorption of engineering tests are in
&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;.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;&lt;strong&gt;Reader:&lt;/strong&gt; a maintainer or contributor who writes, reviews or generates scenarios under
&lt;code dir=&quot;auto&quot;&gt;tests/scenarios/&lt;/code&gt;, or who changes the &lt;code dir=&quot;auto&quot;&gt;acceptance-jvm/&lt;/code&gt; runner or the nightly job.&lt;/p&gt;
&lt;h2 id=&quot;two-layers-one-link&quot;&gt;Two layers, one link&lt;/h2&gt;
&lt;p&gt;Verification has two layers with different owners, formats and tooling.&lt;/p&gt;





























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Layer&lt;/th&gt;&lt;th&gt;What it holds&lt;/th&gt;&lt;th&gt;Where it lives&lt;/th&gt;&lt;th&gt;Format&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Product promises&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;What a user can rely on, at product level, with its owner, status and history&lt;/td&gt;&lt;td&gt;spec-kitty-qa (outside this repository)&lt;/td&gt;&lt;td&gt;Markdown pages with structured front matter&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Acceptance scenarios&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Executable examples that check the CLI does what a promise says&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;tests/scenarios/&amp;#x3C;area&gt;/*.feature&lt;/code&gt; in this repository&lt;/td&gt;&lt;td&gt;Gherkin, run by Cucumber-JVM&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Engineering tests&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Unit, integration, acceptance-gate and e2e tests&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;tests/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;pytest&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;The promise layer and the scenario layer are deliberately &lt;strong&gt;not&lt;/strong&gt; one format. Each repository
picks the scenario tooling that suits its stack, and promise pages stay readable by people who
never open a repository. Nothing in this repository reads, parses or copies promise pages.&lt;/p&gt;
&lt;p&gt;The &lt;strong&gt;only&lt;/strong&gt; link between the layers is the promise identifier, carried as a tag:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;gherkin&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;@promise:PR-CLI-INIT-001&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;Scenario&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt; Re-running init keeps the project&apos;s files&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;The identifier is opaque here. This repository checks that the tag is well formed and nothing
else: it does not know whether the identifier exists, what it says, or whether it is ratified.
spec-kitty-qa resolves identifiers, computes coverage and reports gaps. The identifier is the
persistent one, never the human-readable slug, so renaming a promise page never touches a
scenario.&lt;/p&gt;
&lt;p&gt;This keeps the open-core repository free of product-planning content: a scenario says what the
CLI does, and an identifier is meaningless without the promise store.&lt;/p&gt;
&lt;figure class=&quot;dk-diagram&quot; role=&quot;group&quot;&gt;&lt;svg xmlns=&quot;http://www.w3.org/2000/svg&quot; id=&quot;m09104300759772088-0&quot; width=&quot;100%&quot; aria-roledescription=&quot;flowchart-v2&quot; class=&quot;flowchart&quot; style=&quot;font-family:arial,sans-serif;font-size:16px;fill:var(--dk-diagram-node-text);max-width:2133.546875px&quot; viewBox=&quot;0 0 2133.547 525&quot;&gt;&lt;marker id=&quot;m09104300759772088-0_flowchart-v2-pointEnd&quot; class=&quot;marker flowchart-v2&quot; markerHeight=&quot;8&quot; markerUnits=&quot;userSpaceOnUse&quot; markerWidth=&quot;8&quot; orient=&quot;auto&quot; refX=&quot;5&quot; refY=&quot;5&quot; viewBox=&quot;0 0 10 10&quot;&gt;&lt;path d=&quot;m0 0 10 5-10 5z&quot; class=&quot;arrowMarkerPath&quot; style=&quot;stroke-width:1;stroke-dasharray:1,0&quot;&gt;&lt;/path&gt;&lt;/marker&gt;&lt;marker id=&quot;m09104300759772088-0_flowchart-v2-pointStart&quot; class=&quot;marker flowchart-v2&quot; markerHeight=&quot;8&quot; markerUnits=&quot;userSpaceOnUse&quot; markerWidth=&quot;8&quot; orient=&quot;auto&quot; refX=&quot;4.5&quot; refY=&quot;5&quot; viewBox=&quot;0 0 10 10&quot;&gt;&lt;path d=&quot;m0 5 10 5V0z&quot; class=&quot;arrowMarkerPath&quot; style=&quot;stroke-width:1;stroke-dasharray:1,0&quot;&gt;&lt;/path&gt;&lt;/marker&gt;&lt;marker id=&quot;m09104300759772088-0_flowchart-v2-pointEnd-margin&quot; class=&quot;marker flowchart-v2&quot; markerHeight=&quot;14&quot; markerUnits=&quot;userSpaceOnUse&quot; markerWidth=&quot;10.5&quot; orient=&quot;auto&quot; refX=&quot;11.5&quot; refY=&quot;7&quot; viewBox=&quot;0 0 11.5 14&quot;&gt;&lt;path d=&quot;m0 0 11.5 7L0 14z&quot; class=&quot;arrowMarkerPath&quot; style=&quot;stroke-width:0;stroke-dasharray:1,0&quot;&gt;&lt;/path&gt;&lt;/marker&gt;&lt;marker id=&quot;m09104300759772088-0_flowchart-v2-pointStart-margin&quot; class=&quot;marker flowchart-v2&quot; markerHeight=&quot;14&quot; markerUnits=&quot;userSpaceOnUse&quot; markerWidth=&quot;11.5&quot; orient=&quot;auto&quot; refX=&quot;1&quot; refY=&quot;7&quot; viewBox=&quot;0 0 11.5 14&quot;&gt;&lt;polygon points=&quot;0,7 11.5,14 11.5,0&quot; class=&quot;arrowMarkerPath&quot; style=&quot;stroke-width:0;stroke-dasharray:1,0&quot;&gt;&lt;/polygon&gt;&lt;/marker&gt;&lt;marker id=&quot;m09104300759772088-0_flowchart-v2-circleEnd&quot; class=&quot;marker flowchart-v2&quot; markerHeight=&quot;11&quot; markerUnits=&quot;userSpaceOnUse&quot; markerWidth=&quot;11&quot; orient=&quot;auto&quot; refX=&quot;11&quot; refY=&quot;5&quot; viewBox=&quot;0 0 10 10&quot;&gt;&lt;circle cx=&quot;5&quot; cy=&quot;5&quot; r=&quot;5&quot; class=&quot;arrowMarkerPath&quot; style=&quot;stroke-width:1;stroke-dasharray:1,0&quot;&gt;&lt;/circle&gt;&lt;/marker&gt;&lt;marker id=&quot;m09104300759772088-0_flowchart-v2-circleStart&quot; class=&quot;marker flowchart-v2&quot; markerHeight=&quot;11&quot; markerUnits=&quot;userSpaceOnUse&quot; markerWidth=&quot;11&quot; orient=&quot;auto&quot; refX=&quot;-1&quot; refY=&quot;5&quot; viewBox=&quot;0 0 10 10&quot;&gt;&lt;circle cx=&quot;5&quot; cy=&quot;5&quot; r=&quot;5&quot; class=&quot;arrowMarkerPath&quot; style=&quot;stroke-width:1;stroke-dasharray:1,0&quot;&gt;&lt;/circle&gt;&lt;/marker&gt;&lt;marker id=&quot;m09104300759772088-0_flowchart-v2-circleEnd-margin&quot; class=&quot;marker flowchart-v2&quot; markerHeight=&quot;14&quot; markerUnits=&quot;userSpaceOnUse&quot; markerWidth=&quot;14&quot; orient=&quot;auto&quot; refX=&quot;12.25&quot; refY=&quot;5&quot; viewBox=&quot;0 0 10 10&quot;&gt;&lt;circle cx=&quot;5&quot; cy=&quot;5&quot; r=&quot;5&quot; class=&quot;arrowMarkerPath&quot; style=&quot;stroke-width:0;stroke-dasharray:1,0&quot;&gt;&lt;/circle&gt;&lt;/marker&gt;&lt;marker id=&quot;m09104300759772088-0_flowchart-v2-circleStart-margin&quot; class=&quot;marker flowchart-v2&quot; markerHeight=&quot;14&quot; markerUnits=&quot;userSpaceOnUse&quot; markerWidth=&quot;14&quot; orient=&quot;auto&quot; refX=&quot;-2&quot; refY=&quot;5&quot; viewBox=&quot;0 0 10 10&quot;&gt;&lt;circle cx=&quot;5&quot; cy=&quot;5&quot; r=&quot;5&quot; class=&quot;arrowMarkerPath&quot; style=&quot;stroke-width:0;stroke-dasharray:1,0&quot;&gt;&lt;/circle&gt;&lt;/marker&gt;&lt;marker id=&quot;m09104300759772088-0_flowchart-v2-crossEnd&quot; class=&quot;marker cross flowchart-v2&quot; markerHeight=&quot;11&quot; markerUnits=&quot;userSpaceOnUse&quot; markerWidth=&quot;11&quot; orient=&quot;auto&quot; refX=&quot;12&quot; refY=&quot;5.2&quot; viewBox=&quot;0 0 11 11&quot;&gt;&lt;path d=&quot;m1 1 9 9m0-9-9 9&quot; class=&quot;arrowMarkerPath&quot; style=&quot;stroke-width:2;stroke-dasharray:1,0&quot;&gt;&lt;/path&gt;&lt;/marker&gt;&lt;marker id=&quot;m09104300759772088-0_flowchart-v2-crossStart&quot; class=&quot;marker cross flowchart-v2&quot; markerHeight=&quot;11&quot; markerUnits=&quot;userSpaceOnUse&quot; markerWidth=&quot;11&quot; orient=&quot;auto&quot; refX=&quot;-1&quot; refY=&quot;5.2&quot; viewBox=&quot;0 0 11 11&quot;&gt;&lt;path d=&quot;m1 1 9 9m0-9-9 9&quot; class=&quot;arrowMarkerPath&quot; style=&quot;stroke-width:2;stroke-dasharray:1,0&quot;&gt;&lt;/path&gt;&lt;/marker&gt;&lt;marker id=&quot;m09104300759772088-0_flowchart-v2-crossEnd-margin&quot; class=&quot;marker cross flowchart-v2&quot; markerHeight=&quot;12&quot; markerUnits=&quot;userSpaceOnUse&quot; markerWidth=&quot;12&quot; orient=&quot;auto&quot; refX=&quot;17.7&quot; refY=&quot;7.5&quot; viewBox=&quot;0 0 15 15&quot;&gt;&lt;path d=&quot;m1 1 13 13M1 14 14 1&quot; class=&quot;arrowMarkerPath&quot; style=&quot;stroke-width:2.5&quot;&gt;&lt;/path&gt;&lt;/marker&gt;&lt;marker id=&quot;m09104300759772088-0_flowchart-v2-crossStart-margin&quot; class=&quot;marker cross flowchart-v2&quot; markerHeight=&quot;12&quot; markerUnits=&quot;userSpaceOnUse&quot; markerWidth=&quot;12&quot; orient=&quot;auto&quot; refX=&quot;-3.5&quot; refY=&quot;7.5&quot; viewBox=&quot;0 0 15 15&quot;&gt;&lt;path d=&quot;m1 1 13 13M1 14 14 1&quot; class=&quot;arrowMarkerPath&quot; style=&quot;stroke-width:2.5;stroke-dasharray:1,0&quot;&gt;&lt;/path&gt;&lt;/marker&gt;&lt;g class=&quot;root&quot;&gt;&lt;g class=&quot;clusters&quot;&gt;&lt;g id=&quot;m09104300759772088-0-Core&quot; class=&quot;cluster&quot; data-look=&quot;classic&quot;&gt;&lt;rect width=&quot;925.906&quot; height=&quot;276&quot; x=&quot;773.969&quot; y=&quot;8&quot;&gt;&lt;/rect&gt;&lt;foreignObject width=&quot;182.266&quot; height=&quot;24&quot; class=&quot;cluster-label&quot; transform=&quot;translate(1145.79 8)&quot;&gt;&lt;div xmlns=&quot;http://www.w3.org/1999/xhtml&quot; style=&quot;display:table-cell;white-space:nowrap;line-height:1.5&quot;&gt;&lt;span class=&quot;nodeLabel&quot;&gt;&lt;p&gt;spec-kitty (this repository)&lt;/p&gt;&lt;/span&gt;&lt;/div&gt;&lt;/foreignObject&gt;&lt;/g&gt;&lt;g id=&quot;m09104300759772088-0-QA&quot; class=&quot;cluster&quot; data-look=&quot;classic&quot;&gt;&lt;rect width=&quot;2117.547&quot; height=&quot;213&quot; x=&quot;8&quot; y=&quot;304&quot;&gt;&lt;/rect&gt;&lt;foreignObject width=&quot;90.703&quot; height=&quot;24&quot; class=&quot;cluster-label&quot; transform=&quot;translate(1021.422 304)&quot;&gt;&lt;div xmlns=&quot;http://www.w3.org/1999/xhtml&quot; style=&quot;display:table-cell;white-space:nowrap;line-height:1.5&quot;&gt;&lt;span class=&quot;nodeLabel&quot;&gt;&lt;p&gt;spec-kitty-qa&lt;/p&gt;&lt;/span&gt;&lt;/div&gt;&lt;/foreignObject&gt;&lt;/g&gt;&lt;/g&gt;&lt;g class=&quot;edgePaths&quot;&gt;&lt;path id=&quot;m09104300759772088-0-L_P_G_0&quot; marker-end=&quot;url(#m09104300759772088-0_flowchart-v2-pointEnd)&quot; d=&quot;m293 389.968 4.167-.995c4.166-.995 12.5-2.984 20.166-3.978S332 384 335.5 384h3.5&quot; class=&quot;edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link&quot; data-edge=&quot;true&quot; data-et=&quot;edge&quot; data-id=&quot;L_P_G_0&quot; data-look=&quot;classic&quot; data-points=&quot;W3sieCI6MjkzLCJ5IjozODkuOTY3NzQxOTM1NDgzOX0seyJ4IjozMTgsInkiOjM4NH0seyJ4IjozNDMsInkiOjM4NH1d&quot;&gt;&lt;/path&gt;&lt;path id=&quot;m09104300759772088-0-L_G_S_0&quot; marker-end=&quot;url(#m09104300759772088-0_flowchart-v2-pointEnd)&quot; d=&quot;M523.969 384h125c41.666 0 83.333 0 123.88-32.596s79.974-97.789 99.687-130.385l19.714-32.596&quot; class=&quot;edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link&quot; data-edge=&quot;true&quot; data-et=&quot;edge&quot; data-id=&quot;L_G_S_0&quot; data-look=&quot;classic&quot; data-points=&quot;W3sieCI6NTIzLjk2ODc1LCJ5IjozODR9LHsieCI6NjQ4Ljk2ODc1LCJ5IjozODR9LHsieCI6NzczLjk2ODc1LCJ5IjozODR9LHsieCI6ODk0LjMxOTg1Mjk0MTE3NjUsInkiOjE4NX1d&quot;&gt;&lt;/path&gt;&lt;path id=&quot;m09104300759772088-0-L_S_C_0&quot; marker-end=&quot;url(#m09104300759772088-0_flowchart-v2-pointEnd)&quot; d=&quot;m1036.844 109.785 15.208-4.631c15.208-4.631 45.625-13.892 75.675-18.523S1187.458 82 1202.299 82h14.842&quot; class=&quot;edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link&quot; data-edge=&quot;true&quot; data-et=&quot;edge&quot; data-id=&quot;L_S_C_0&quot; data-look=&quot;classic&quot; data-points=&quot;W3sieCI6MTAzNi44NDM3NSwieSI6MTA5Ljc4NDcxNjAyNzM1NjUyfSx7IngiOjExMjguMDkzNzUsInkiOjgyfSx7IngiOjEyMjEuMTQwNjI1LCJ5Ijo4Mn1d&quot;&gt;&lt;/path&gt;&lt;path id=&quot;m09104300759772088-0-L_S_N_0&quot; marker-end=&quot;url(#m09104300759772088-0_flowchart-v2-pointEnd)&quot; d=&quot;m1036.844 182.215 15.208 4.631c15.208 4.631 45.625 13.892 75.375 18.523S1186.26 210 1200.802 210h14.542&quot; class=&quot;edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link&quot; data-edge=&quot;true&quot; data-et=&quot;edge&quot; data-id=&quot;L_S_N_0&quot; data-look=&quot;classic&quot; data-points=&quot;W3sieCI6MTAzNi44NDM3NSwieSI6MTgyLjIxNTI4Mzk3MjY0MzQ4fSx7IngiOjExMjguMDkzNzUsInkiOjIxMH0seyJ4IjoxMjE5LjM0Mzc1LCJ5IjoyMTB9XQ==&quot;&gt;&lt;/path&gt;&lt;path id=&quot;m09104300759772088-0-L_N_E_0&quot; marker-end=&quot;url(#m09104300759772088-0_flowchart-v2-pointEnd)&quot; d=&quot;M1446.563 210h46&quot; class=&quot;edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link&quot; data-edge=&quot;true&quot; data-et=&quot;edge&quot; data-id=&quot;L_N_E_0&quot; data-look=&quot;classic&quot; data-points=&quot;W3sieCI6MTQ0Ni41NjI1LCJ5IjoyMTB9LHsieCI6MTQ3MS41NjI1LCJ5IjoyMTB9LHsieCI6MTQ5Ni41NjI1LCJ5IjoyMTB9XQ==&quot;&gt;&lt;/path&gt;&lt;path id=&quot;m09104300759772088-0-L_E_R_0&quot; marker-end=&quot;url(#m09104300759772088-0_flowchart-v2-pointEnd)&quot; d=&quot;M1674.875 210h4.167c4.166 0 12.5 0 30.914 29s46.909 87 78.362 120.981c31.453 33.982 65.864 43.944 83.07 48.925l17.205 4.982&quot; class=&quot;edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link&quot; data-edge=&quot;true&quot; data-et=&quot;edge&quot; data-id=&quot;L_E_R_0&quot; data-look=&quot;classic&quot; data-points=&quot;W3sieCI6MTY3NC44NzUsInkiOjIxMH0seyJ4IjoxNjk5Ljg3NSwieSI6MjEwfSx7IngiOjE3ODUuMzU5Mzc1LCJ5IjozODR9LHsieCI6MTg5Mi40MzU0Nzk1MjU4NjIsInkiOjQxNX1d&quot;&gt;&lt;/path&gt;&lt;path id=&quot;m09104300759772088-0-L_R_P_0&quot; marker-end=&quot;url(#m09104300759772088-0_flowchart-v2-pointEnd)&quot; d=&quot;m1870.844 451.173-14.248 1.138c-14.247 1.137-42.742 3.413-71.237 4.551S1728.37 458 1695.096 458H450.151c-55.161 0-93.656 0-116.422-.84s-29.802-2.519-33.32-3.359l-3.518-.84&quot; class=&quot;edge-thickness-normal edge-pattern-solid flowchart-link&quot; data-edge=&quot;true&quot; data-et=&quot;edge&quot; data-id=&quot;L_R_P_0&quot; data-look=&quot;classic&quot; data-points=&quot;W3sieCI6MTg3MC44NDM3NSwieSI6NDUxLjE3MjcxNzcwMDczNzA1fSx7IngiOjE3ODUuMzU5Mzc1LCJ5Ijo0NTh9LHsieCI6MTY5OS44NzUsInkiOjQ1OH0seyJ4IjoxNTg1LjcxODc1LCJ5Ijo0NTh9LHsieCI6MTQ3MS41NjI1LCJ5Ijo0NTh9LHsieCI6MTMzMi45NTMxMjUsInkiOjQ1OH0seyJ4IjoxMTI4LjA5Mzc1LCJ5Ijo0NTh9LHsieCI6OTE3LjkwNjI1LCJ5Ijo0NTh9LHsieCI6NzczLjk2ODc1LCJ5Ijo0NTh9LHsieCI6NjQ4Ljk2ODc1LCJ5Ijo0NTh9LHsieCI6NDMzLjQ4NDM3NSwieSI6NDU4fSx7IngiOjMxOCwieSI6NDU4fSx7IngiOjI5MywieSI6NDUyLjAzMjI1ODA2NDUxNjF9XQ==&quot; style=&quot;stroke-dasharray:2&quot;&gt;&lt;/path&gt;&lt;/g&gt;&lt;g class=&quot;edgeLabels&quot;&gt;&lt;g class=&quot;edgeLabel&quot;&gt;&lt;foreignObject width=&quot;0&quot; height=&quot;0&quot; class=&quot;label&quot; data-id=&quot;L_P_G_0&quot;&gt;&lt;div xmlns=&quot;http://www.w3.org/1999/xhtml&quot; class=&quot;labelBkg&quot; style=&quot;display:table-cell;white-space:nowrap;line-height:1.5;max-width:200px;text-align:center&quot;&gt;&lt;span class=&quot;edgeLabel&quot;&gt;&lt;/span&gt;&lt;/div&gt;&lt;/foreignObject&gt;&lt;/g&gt;&lt;g class=&quot;edgeLabel&quot;&gt;&lt;foreignObject width=&quot;200&quot; height=&quot;48&quot; class=&quot;label&quot; data-id=&quot;L_G_S_0&quot; transform=&quot;translate(548.969 360)&quot;&gt;&lt;div xmlns=&quot;http://www.w3.org/1999/xhtml&quot; class=&quot;labelBkg&quot; style=&quot;display:table;white-space:break-spaces;line-height:1.5;max-width:200px;text-align:center;width:200px&quot;&gt;&lt;span class=&quot;edgeLabel&quot;&gt;&lt;p&gt;pull request: @wip scenarios&lt;/p&gt;&lt;/span&gt;&lt;/div&gt;&lt;/foreignObject&gt;&lt;/g&gt;&lt;g class=&quot;edgeLabel&quot;&gt;&lt;foreignObject width=&quot;0&quot; height=&quot;0&quot; class=&quot;label&quot; data-id=&quot;L_S_C_0&quot;&gt;&lt;div xmlns=&quot;http://www.w3.org/1999/xhtml&quot; class=&quot;labelBkg&quot; style=&quot;display:table-cell;white-space:nowrap;line-height:1.5;max-width:200px;text-align:center&quot;&gt;&lt;span class=&quot;edgeLabel&quot;&gt;&lt;/span&gt;&lt;/div&gt;&lt;/foreignObject&gt;&lt;/g&gt;&lt;g class=&quot;edgeLabel&quot;&gt;&lt;foreignObject width=&quot;0&quot; height=&quot;0&quot; class=&quot;label&quot; data-id=&quot;L_S_N_0&quot;&gt;&lt;div xmlns=&quot;http://www.w3.org/1999/xhtml&quot; class=&quot;labelBkg&quot; style=&quot;display:table-cell;white-space:nowrap;line-height:1.5;max-width:200px;text-align:center&quot;&gt;&lt;span class=&quot;edgeLabel&quot;&gt;&lt;/span&gt;&lt;/div&gt;&lt;/foreignObject&gt;&lt;/g&gt;&lt;g class=&quot;edgeLabel&quot;&gt;&lt;foreignObject width=&quot;0&quot; height=&quot;0&quot; class=&quot;label&quot; data-id=&quot;L_N_E_0&quot;&gt;&lt;div xmlns=&quot;http://www.w3.org/1999/xhtml&quot; class=&quot;labelBkg&quot; style=&quot;display:table-cell;white-space:nowrap;line-height:1.5;max-width:200px;text-align:center&quot;&gt;&lt;span class=&quot;edgeLabel&quot;&gt;&lt;/span&gt;&lt;/div&gt;&lt;/foreignObject&gt;&lt;/g&gt;&lt;g class=&quot;edgeLabel&quot;&gt;&lt;foreignObject width=&quot;120.969&quot; height=&quot;24&quot; class=&quot;label&quot; data-id=&quot;L_E_R_0&quot; transform=&quot;translate(1701.198 323.806)&quot;&gt;&lt;div xmlns=&quot;http://www.w3.org/1999/xhtml&quot; class=&quot;labelBkg&quot; style=&quot;display:table-cell;white-space:nowrap;line-height:1.5;max-width:200px;text-align:center&quot;&gt;&lt;span class=&quot;edgeLabel&quot;&gt;&lt;p&gt;artifact download&lt;/p&gt;&lt;/span&gt;&lt;/div&gt;&lt;/foreignObject&gt;&lt;/g&gt;&lt;g class=&quot;edgeLabel&quot;&gt;&lt;foreignObject width=&quot;132.5&quot; height=&quot;24&quot; class=&quot;label&quot; data-id=&quot;L_R_P_0&quot; transform=&quot;translate(1061.844 446)&quot;&gt;&lt;div xmlns=&quot;http://www.w3.org/1999/xhtml&quot; class=&quot;labelBkg&quot; style=&quot;display:table-cell;white-space:nowrap;line-height:1.5;max-width:200px;text-align:center&quot;&gt;&lt;span class=&quot;edgeLabel&quot;&gt;&lt;p&gt;resolves identifiers&lt;/p&gt;&lt;/span&gt;&lt;/div&gt;&lt;/foreignObject&gt;&lt;/g&gt;&lt;/g&gt;&lt;g class=&quot;nodes&quot;&gt;&lt;g id=&quot;m09104300759772088-0-flowchart-P-0&quot; class=&quot;node default&quot; data-look=&quot;classic&quot; transform=&quot;translate(163 421)&quot;&gt;&lt;rect width=&quot;260&quot; height=&quot;102&quot; x=&quot;-130&quot; y=&quot;-51&quot; class=&quot;basic label-container&quot;&gt;&lt;/rect&gt;&lt;g class=&quot;label&quot; transform=&quot;translate(-100 -36)&quot;&gt;&lt;rect&gt;&lt;/rect&gt;&lt;foreignObject width=&quot;200&quot; height=&quot;72&quot;&gt;&lt;div xmlns=&quot;http://www.w3.org/1999/xhtml&quot; style=&quot;display:table;white-space:break-spaces;line-height:1.5;max-width:200px;text-align:center;width:200px&quot;&gt;&lt;span class=&quot;nodeLabel&quot;&gt;&lt;p&gt;Promise pages&lt;br&gt;(identifier, slug, owner, status)&lt;/p&gt;&lt;/span&gt;&lt;/div&gt;&lt;/foreignObject&gt;&lt;/g&gt;&lt;/g&gt;&lt;g id=&quot;m09104300759772088-0-flowchart-G-1&quot; class=&quot;node default&quot; data-look=&quot;classic&quot; transform=&quot;translate(433.484 384)&quot;&gt;&lt;rect width=&quot;180.969&quot; height=&quot;78&quot; x=&quot;-90.484&quot; y=&quot;-39&quot; class=&quot;basic label-container&quot;&gt;&lt;/rect&gt;&lt;g class=&quot;label&quot; transform=&quot;translate(-60.484 -24)&quot;&gt;&lt;rect&gt;&lt;/rect&gt;&lt;foreignObject width=&quot;120.969&quot; height=&quot;48&quot;&gt;&lt;div xmlns=&quot;http://www.w3.org/1999/xhtml&quot; style=&quot;display:table-cell;white-space:nowrap;line-height:1.5;max-width:200px;text-align:center&quot;&gt;&lt;span class=&quot;nodeLabel&quot;&gt;&lt;p&gt;Scenario drafting&lt;br&gt;(operator-driven)&lt;/p&gt;&lt;/span&gt;&lt;/div&gt;&lt;/foreignObject&gt;&lt;/g&gt;&lt;/g&gt;&lt;g id=&quot;m09104300759772088-0-flowchart-R-2&quot; class=&quot;node default&quot; data-look=&quot;classic&quot; transform=&quot;translate(1985.695 442)&quot;&gt;&lt;rect width=&quot;229.703&quot; height=&quot;54&quot; x=&quot;-114.852&quot; y=&quot;-27&quot; class=&quot;basic label-container&quot;&gt;&lt;/rect&gt;&lt;g class=&quot;label&quot; transform=&quot;translate(-84.852 -12)&quot;&gt;&lt;rect&gt;&lt;/rect&gt;&lt;foreignObject width=&quot;169.703&quot; height=&quot;24&quot;&gt;&lt;div xmlns=&quot;http://www.w3.org/1999/xhtml&quot; style=&quot;display:table-cell;white-space:nowrap;line-height:1.5;max-width:200px;text-align:center&quot;&gt;&lt;span class=&quot;nodeLabel&quot;&gt;&lt;p&gt;Trace lint + Allure report&lt;/p&gt;&lt;/span&gt;&lt;/div&gt;&lt;/foreignObject&gt;&lt;/g&gt;&lt;/g&gt;&lt;g id=&quot;m09104300759772088-0-flowchart-S-3&quot; class=&quot;node default&quot; data-look=&quot;classic&quot; transform=&quot;translate(917.906 146)&quot;&gt;&lt;rect width=&quot;237.875&quot; height=&quot;78&quot; x=&quot;-118.938&quot; y=&quot;-39&quot; class=&quot;basic label-container&quot;&gt;&lt;/rect&gt;&lt;g class=&quot;label&quot; transform=&quot;translate(-88.938 -24)&quot;&gt;&lt;rect&gt;&lt;/rect&gt;&lt;foreignObject width=&quot;177.875&quot; height=&quot;48&quot;&gt;&lt;div xmlns=&quot;http://www.w3.org/1999/xhtml&quot; style=&quot;display:table-cell;white-space:nowrap;line-height:1.5;max-width:200px;text-align:center&quot;&gt;&lt;span class=&quot;nodeLabel&quot;&gt;&lt;p&gt;tests/scenarios/**.feature&lt;br&gt;@promise:&amp;#x3C;id&gt;&lt;/p&gt;&lt;/span&gt;&lt;/div&gt;&lt;/foreignObject&gt;&lt;/g&gt;&lt;/g&gt;&lt;g id=&quot;m09104300759772088-0-flowchart-C-4&quot; class=&quot;node default&quot; data-look=&quot;classic&quot; transform=&quot;translate(1332.953 82)&quot;&gt;&lt;rect width=&quot;223.625&quot; height=&quot;78&quot; x=&quot;-111.813&quot; y=&quot;-39&quot; class=&quot;basic label-container&quot;&gt;&lt;/rect&gt;&lt;g class=&quot;label&quot; transform=&quot;translate(-81.813 -24)&quot;&gt;&lt;rect&gt;&lt;/rect&gt;&lt;foreignObject width=&quot;163.625&quot; height=&quot;48&quot;&gt;&lt;div xmlns=&quot;http://www.w3.org/1999/xhtml&quot; style=&quot;display:table-cell;white-space:nowrap;line-height:1.5;max-width:200px;text-align:center&quot;&gt;&lt;span class=&quot;nodeLabel&quot;&gt;&lt;p&gt;Per-PR scenario check&lt;br&gt;(Python, no JVM)&lt;/p&gt;&lt;/span&gt;&lt;/div&gt;&lt;/foreignObject&gt;&lt;/g&gt;&lt;/g&gt;&lt;g id=&quot;m09104300759772088-0-flowchart-N-5&quot; class=&quot;node default&quot; data-look=&quot;classic&quot; transform=&quot;translate(1332.953 210)&quot;&gt;&lt;rect width=&quot;227.219&quot; height=&quot;78&quot; x=&quot;-113.609&quot; y=&quot;-39&quot; class=&quot;basic label-container&quot;&gt;&lt;/rect&gt;&lt;g class=&quot;label&quot; transform=&quot;translate(-83.61 -24)&quot;&gt;&lt;rect&gt;&lt;/rect&gt;&lt;foreignObject width=&quot;167.219&quot; height=&quot;48&quot;&gt;&lt;div xmlns=&quot;http://www.w3.org/1999/xhtml&quot; style=&quot;display:table-cell;white-space:nowrap;line-height:1.5;max-width:200px;text-align:center&quot;&gt;&lt;span class=&quot;nodeLabel&quot;&gt;&lt;p&gt;Nightly acceptance-bdd&lt;br&gt;(Cucumber-JVM, 3 OS)&lt;/p&gt;&lt;/span&gt;&lt;/div&gt;&lt;/foreignObject&gt;&lt;/g&gt;&lt;/g&gt;&lt;g id=&quot;m09104300759772088-0-flowchart-E-6&quot; class=&quot;node default&quot; data-look=&quot;classic&quot; transform=&quot;translate(1585.719 210)&quot;&gt;&lt;rect width=&quot;178.313&quot; height=&quot;78&quot; x=&quot;-89.156&quot; y=&quot;-39&quot; class=&quot;basic label-container&quot;&gt;&lt;/rect&gt;&lt;g class=&quot;label&quot; transform=&quot;translate(-59.156 -24)&quot;&gt;&lt;rect&gt;&lt;/rect&gt;&lt;foreignObject width=&quot;118.313&quot; height=&quot;48&quot;&gt;&lt;div xmlns=&quot;http://www.w3.org/1999/xhtml&quot; style=&quot;display:table-cell;white-space:nowrap;line-height:1.5;max-width:200px;text-align:center&quot;&gt;&lt;span class=&quot;nodeLabel&quot;&gt;&lt;p&gt;Evidence bundle&lt;br&gt;per OS&lt;/p&gt;&lt;/span&gt;&lt;/div&gt;&lt;/foreignObject&gt;&lt;/g&gt;&lt;/g&gt;&lt;/g&gt;&lt;/g&gt;&lt;defs&gt;&lt;filter id=&quot;m09104300759772088-0-drop-shadow&quot; width=&quot;130%&quot; height=&quot;130%&quot;&gt;&lt;feDropShadow dx=&quot;4&quot; dy=&quot;4&quot; flood-color=&quot;#000&quot; flood-opacity=&quot;.06&quot; stdDeviation=&quot;0&quot;&gt;&lt;/feDropShadow&gt;&lt;/filter&gt;&lt;/defs&gt;&lt;defs&gt;&lt;filter id=&quot;m09104300759772088-0-drop-shadow-small&quot; width=&quot;150%&quot; height=&quot;150%&quot;&gt;&lt;feDropShadow dx=&quot;2&quot; dy=&quot;2&quot; flood-color=&quot;#000&quot; flood-opacity=&quot;.06&quot; stdDeviation=&quot;0&quot;&gt;&lt;/feDropShadow&gt;&lt;/filter&gt;&lt;/defs&gt;&lt;linearGradient id=&quot;m09104300759772088-0-gradient&quot; x1=&quot;0%&quot; x2=&quot;100%&quot; y1=&quot;0%&quot; y2=&quot;0%&quot; gradientUnits=&quot;objectBoundingBox&quot;&gt;&lt;stop offset=&quot;0%&quot; stop-color=&quot;var(--dk-diagram-node-border)&quot;&gt;&lt;/stop&gt;&lt;stop offset=&quot;100%&quot; stop-color=&quot;hsl(-40.8510638298, 21.038961039%, 74.9019607843%)&quot;&gt;&lt;/stop&gt;&lt;/linearGradient&gt;&lt;/svg&gt;&lt;/figure&gt;
&lt;p&gt;&lt;em&gt;Figure: promise pages stay in spec-kitty-qa; scenarios, the per-PR check, the nightly and its
evidence live here; spec-kitty-qa reads the evidence back and resolves the identifiers.&lt;/em&gt;&lt;/p&gt;
&lt;h2 id=&quot;a-the-scenario-contract&quot;&gt;A. The scenario contract&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Layout (built).&lt;/strong&gt; One folder per CLI area under &lt;code dir=&quot;auto&quot;&gt;tests/scenarios/&lt;/code&gt;, one or more &lt;code dir=&quot;auto&quot;&gt;.feature&lt;/code&gt;
files per folder. The runner reads them in place.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Tag vocabulary.&lt;/strong&gt; Tags are the whole interface between a scenario and everything outside it.&lt;/p&gt;








































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Tag&lt;/th&gt;&lt;th&gt;Meaning in this repository&lt;/th&gt;&lt;th&gt;Rule the check enforces&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;@promise:&amp;#x3C;id&gt;&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Links the scenario to a promise. Inert at run time.&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;id&gt;&lt;/code&gt; matches &lt;code dir=&quot;auto&quot;&gt;[A-Za-z0-9][A-Za-z0-9._-]*&lt;/code&gt;; no tag repeats on one scenario.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;@wip&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Steps are not bound yet, or the scenario is not trusted yet. Runs in the non-gating pass.&lt;/td&gt;&lt;td&gt;Needs &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;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;@manual&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Never runs automatically (heavy or on-demand).&lt;/td&gt;&lt;td&gt;None.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;@defect:&amp;#x3C;issue&gt;&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Reproduces a tracked bug.&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;issue&gt;&lt;/code&gt; is a positive integer.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;@qa:&amp;#x3C;ref&gt;&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Traceability to a QA-corpus scenario it was converted from.&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;ref&gt;&lt;/code&gt; uses the identifier character set.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;@&amp;#x3C;area&gt;&lt;/code&gt; and other bare tags&lt;/td&gt;&lt;td&gt;Free-form selection tags.&lt;/td&gt;&lt;td&gt;None.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Untagged and &lt;code dir=&quot;auto&quot;&gt;@promise&lt;/code&gt;-only scenarios gate the nightly, as today. How old a &lt;code dir=&quot;auto&quot;&gt;@wip&lt;/code&gt; scenario may
be is a reporting rule for spec-kitty-qa’s trace lint, not a check here: the per-PR check only
requires the date to be present and valid.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Drafted scenarios.&lt;/strong&gt; A scenario drafted from a promise, by hand or with AI help, lands as
&lt;code dir=&quot;auto&quot;&gt;@wip&lt;/code&gt; with the promise tag, an owner and a date. It may use step text that has no binding yet.
An engineer binds or rewords the steps, adds the positive control
(&lt;a href=&quot;/development/testing/acceptance-scenarios/&quot;&gt;acceptance scenarios guide&lt;/a&gt;) and removes
&lt;code dir=&quot;auto&quot;&gt;@wip&lt;/code&gt;. The tag is added by a person; tooling never invents a promise identifier.&lt;/p&gt;
&lt;h2 id=&quot;b-the-per-pull-request-scenario-check-built&quot;&gt;B. The per-pull-request scenario check (built)&lt;/h2&gt;
&lt;p&gt;Without it, the nightly would be the only thing that reads scenarios, so a malformed feature file
or a typo’d step would be found the next morning. The check finds it on the pull request, without
a JDK.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Where:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_scenario_contract.py&lt;/code&gt;, Python standard library plus first-party
&lt;code dir=&quot;auto&quot;&gt;kernel.clock&lt;/code&gt; (no third-party dependency), with
a small Gherkin reader for the subset the scenarios use (&lt;code dir=&quot;auto&quot;&gt;Feature&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Background&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Scenario&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;Scenario Outline&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Examples&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Rule&lt;/code&gt;, tags, steps, doc strings and data tables). No new
dependency.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;What it asserts:&lt;/strong&gt;
&lt;ol&gt;
&lt;li&gt;Every &lt;code dir=&quot;auto&quot;&gt;.feature&lt;/code&gt; file parses and holds at least one scenario (&lt;code dir=&quot;auto&quot;&gt;NO_SCENARIOS&lt;/code&gt; otherwise,
which catches a misspelt &lt;code dir=&quot;auto&quot;&gt;Scenario:&lt;/code&gt; keyword), and every scenario has at least one step.&lt;/li&gt;
&lt;li&gt;Every tag follows the vocabulary table above.&lt;/li&gt;
&lt;li&gt;Every step of a scenario &lt;strong&gt;without&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;@wip&lt;/code&gt; matches exactly one step definition. Step
definitions are read from the &lt;code dir=&quot;auto&quot;&gt;@Given&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;@When&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;@Then&lt;/code&gt; annotations in
&lt;code dir=&quot;auto&quot;&gt;acceptance-jvm/src/test/java/**/steps/*.java&lt;/code&gt;; the Cucumber expression parameters in use
(&lt;code dir=&quot;auto&quot;&gt;{string}&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;{int}&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;{word}&lt;/code&gt;) become regular expressions. An unsupported parameter type
fails the check, so the reader cannot silently fall behind the runner.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;@wip&lt;/code&gt; scenarios may use unmatched steps; the check lists them as information.&lt;/li&gt;
&lt;/ol&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Oracles:&lt;/strong&gt; one broken fixture per rule under &lt;code dir=&quot;auto&quot;&gt;tests/architectural/fixtures/scenarios/&lt;/code&gt;, and a
guard that the real tree is not empty.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Routing:&lt;/strong&gt; the &lt;code dir=&quot;auto&quot;&gt;scenarios&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;tests/scenarios/**&lt;/code&gt;) and &lt;code dir=&quot;auto&quot;&gt;acceptance_jvm&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;acceptance-jvm/**&lt;/code&gt;)
groups in &lt;code dir=&quot;auto&quot;&gt;ci-router.yml&lt;/code&gt; start gating the job that runs this file. Contributors still need no
JDK.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;c-the-evidence-bundle-built&quot;&gt;C. The evidence bundle (built)&lt;/h2&gt;
&lt;p&gt;Each nightly leg hands its results to spec-kitty-qa. A result is only useful there if it says
which CLI build, on which OS, in which pass produced it. The current upload does not.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Problems it fixed&lt;/strong&gt; (the job had these before the bundle was built):&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The gating pass and the &lt;code dir=&quot;auto&quot;&gt;@wip&lt;/code&gt; pass write into the same &lt;code dir=&quot;auto&quot;&gt;build/&lt;/code&gt; folders, and the second pass
runs with &lt;code dir=&quot;auto&quot;&gt;--rerun-tasks&lt;/code&gt;, so it &lt;strong&gt;overwrites the gating pass’s Cucumber JSON and JUnit XML&lt;/strong&gt;
and mixes both passes’ Allure results before the upload.&lt;/li&gt;
&lt;li&gt;The Allure results folder is not set, so the upload lists two possible folders and only warns
if both are empty.&lt;/li&gt;
&lt;li&gt;Nothing records the CLI version, the commit, the OS or the pass.&lt;/li&gt;
&lt;li&gt;The artifact has no explicit retention.&lt;/li&gt;
&lt;li&gt;The job’s &lt;code dir=&quot;auto&quot;&gt;if:&lt;/code&gt; mentions &lt;code dir=&quot;auto&quot;&gt;pull_request&lt;/code&gt;, an event &lt;code dir=&quot;auto&quot;&gt;ci-nightly.yml&lt;/code&gt; never receives.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Design:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Each pass writes to its own folder, &lt;code dir=&quot;auto&quot;&gt;acceptance-jvm/build/acceptance/&amp;#x3C;pass&gt;/&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;pass&gt;&lt;/code&gt; set
to &lt;code dir=&quot;auto&quot;&gt;gating&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;wip&lt;/code&gt;, holding &lt;code dir=&quot;auto&quot;&gt;allure-results/&lt;/code&gt; (set through &lt;code dir=&quot;auto&quot;&gt;allure.results.directory&lt;/code&gt;),
&lt;code dir=&quot;auto&quot;&gt;cucumber.json&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;junit/&lt;/code&gt;. A Gradle property selects the pass, and the tag filter comes from
the pass, so CI cannot pair a pass name with the wrong filter.&lt;/li&gt;
&lt;li&gt;Before the scenarios run, the runner writes:
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;allure-results/environment.properties&lt;/code&gt;: CLI version (from the wheel it built), commit SHA,
OS, JDK version, pass;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;allure-results/executor.json&lt;/code&gt;: the CI run URL and run number, when present.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;After both passes, the job writes &lt;code dir=&quot;auto&quot;&gt;acceptance-jvm/build/acceptance/evidence.json&lt;/code&gt;:
&lt;code dir=&quot;auto&quot;&gt;schema_version&lt;/code&gt;, commit SHA, CLI version, OS, the run URL, and per pass the outcome, scenario
counts and the result paths. spec-kitty-qa reads this file first; a field it does not know
never breaks it, and a &lt;code dir=&quot;auto&quot;&gt;schema_version&lt;/code&gt; it does not know makes it refuse.&lt;/li&gt;
&lt;li&gt;The upload keeps the name &lt;code dir=&quot;auto&quot;&gt;acceptance-bdd-results-&amp;#x3C;os&gt;&lt;/code&gt; (since the #7492 follow-up below:
&lt;code dir=&quot;auto&quot;&gt;acceptance-bdd-results-&amp;#x3C;os&gt;-shard-&amp;#x3C;k&gt;&lt;/code&gt;, one per shard), uploads only
&lt;code dir=&quot;auto&quot;&gt;acceptance-jvm/build/acceptance/&lt;/code&gt;, fails when the gating results are missing
(&lt;code dir=&quot;auto&quot;&gt;if-no-files-found: error&lt;/code&gt;), and sets &lt;code dir=&quot;auto&quot;&gt;retention-days: 30&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The job’s &lt;code dir=&quot;auto&quot;&gt;if:&lt;/code&gt; drops the &lt;code dir=&quot;auto&quot;&gt;pull_request&lt;/code&gt; clause.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Amendment (#7492, 2026-11-10).&lt;/strong&gt; The &lt;code dir=&quot;auto&quot;&gt;@wip&lt;/code&gt; pass moved to its own non-gating job,
&lt;code dir=&quot;auto&quot;&gt;acceptance-bdd-wip&lt;/code&gt;: on Windows the gating pass and the &lt;code dir=&quot;auto&quot;&gt;@wip&lt;/code&gt; pass together ran into the
leg’s 60-minute cap, and the canceled leg escalated a P0 with no failing test. Each job now
writes its own &lt;code dir=&quot;auto&quot;&gt;evidence.json&lt;/code&gt; (schema version 1 unchanged: both passes are present, the one
the job did not run is &lt;code dir=&quot;auto&quot;&gt;missing&lt;/code&gt;, and the additive &lt;code dir=&quot;auto&quot;&gt;passes_run&lt;/code&gt; field names the one it ran).
The gating bundle stays in &lt;code dir=&quot;auto&quot;&gt;acceptance-bdd-results-&amp;#x3C;os&gt;-shard-&amp;#x3C;k&gt;&lt;/code&gt;; the &lt;code dir=&quot;auto&quot;&gt;@wip&lt;/code&gt; bundle is uploaded as
&lt;code dir=&quot;auto&quot;&gt;acceptance-bdd-wip-results-&amp;#x3C;os&gt;&lt;/code&gt;. spec-kitty-qa reads the &lt;code dir=&quot;auto&quot;&gt;@wip&lt;/code&gt; results from that artifact.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Amendment (#7492 follow-up, 2026-11-10).&lt;/strong&gt; The gating pass runs in shards, three on Windows,
two on macOS and one on Linux (&lt;code dir=&quot;auto&quot;&gt;-Pacceptance.shard=K/N&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;kitty.acceptance.sharding.ShardFilter&lt;/code&gt;), to cut the Windows leg’s
~47-minute critical path. Each shard uploads &lt;code dir=&quot;auto&quot;&gt;acceptance-bdd-results-&amp;#x3C;os&gt;-shard-&amp;#x3C;k&gt;&lt;/code&gt;, and its
&lt;code dir=&quot;auto&quot;&gt;evidence.json&lt;/code&gt; adds &lt;code dir=&quot;auto&quot;&gt;shard: &quot;K/N&quot;&lt;/code&gt; (additive; &lt;code dir=&quot;auto&quot;&gt;null&lt;/code&gt; when unsharded). A consumer reads every
shard artifact of an OS to see the whole gating pass. Every shard still lists the tag-skipped
(&lt;code dir=&quot;auto&quot;&gt;@wip&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;@manual&lt;/code&gt;) scenarios as skipped, so a consumer merging the shards dedupes them. This
changes the artifact name FR-011 and ADR &lt;code dir=&quot;auto&quot;&gt;2026-10-13-1&lt;/code&gt; kept; spec-kitty-qa follows it.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;d-fixture-builders-built&quot;&gt;D. Fixture builders (built)&lt;/h2&gt;
&lt;p&gt;Today’s Arrange steps can set up an initialised project and a git repository with history. The
promises that matter next (mission creation, the status lane walk, review and consolidation)
need a project with a mission in a known state.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Builders stay black-box.&lt;/strong&gt; A builder in &lt;code dir=&quot;auto&quot;&gt;kitty.acceptance.environment&lt;/code&gt; reaches a state only by
running the CLI through the driver (&lt;code dir=&quot;auto&quot;&gt;init&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;agent mission create&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;agent mission finalize-tasks&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;move-task&lt;/code&gt;, …). It never writes CLI-managed state, so a builder breaks when
the CLI’s own path breaks, which is the point. It may write what an agent or a user authors (see
“What a builder may write” below).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Steps on top:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;Given a project with a mission &quot;&amp;#x3C;slug&gt;&quot;&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Given the work package &quot;&amp;#x3C;wp&gt;&quot; of mission &quot;&amp;#x3C;slug&gt;&quot; is in lane &quot;&amp;#x3C;lane&gt;&quot;&lt;/code&gt;, and assert steps on &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent tasks status --json&lt;/code&gt; output.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;First scenarios:&lt;/strong&gt; a small mission-lifecycle area that proves the builders, each with a
positive control.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Built:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;MissionFixture&lt;/code&gt; (a project with a Mission, through &lt;code dir=&quot;auto&quot;&gt;init&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;agent mission create&lt;/code&gt;),
&lt;code dir=&quot;auto&quot;&gt;MissionLifecycle&lt;/code&gt; (a Mission planned on the topic branch &lt;code dir=&quot;auto&quot;&gt;work&lt;/code&gt; up to finalized work packages, a
&lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt; Mission on the topic branch or minted from protected &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;, and a work package
walked through &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt;, or rejected with
feedback), and &lt;code dir=&quot;auto&quot;&gt;GitStates&lt;/code&gt; (sparse-checkout state, linked worktrees, an in-progress merge).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;What a builder may write (amended 2026-10-15, ADR 2026-10-15-1 decision 6):&lt;/strong&gt; the planning files
an agent authors (&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, review
feedback outside the repository and plain files a user edits in git. Never 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 or anything under &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;what-this-design-does-not-cover&quot;&gt;What this design does not cover&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Where promise pages live, their format, who ratifies them, and how they are versioned.&lt;/li&gt;
&lt;li&gt;Drafting scenarios from promises, and the QA docs site.&lt;/li&gt;
&lt;li&gt;Building the Allure report, keeping its history, and the trace lint.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;All of these belong to spec-kitty-qa. This repository’s side of that boundary is the tag
vocabulary in section A and the evidence bundle in section C.&lt;/p&gt;</content>
</entry>
