From 33eb0f6bf03845929030858b197e892e6c54f986 Mon Sep 17 00:00:00 2001
From: Peter Lawrey <peter.lawrey@chronicle.software>
Date: Wed, 4 Nov 2026 22:51:15 +0000
Subject: [PATCH] FIX-292: Add opt-in 1 x 8 PR test policy

---
 pom.xml                       | 53 +++++++++++++++++++++++++++++++++++
 src/main/docs/managed-ci.adoc | 27 ++++++++++++++++++
 2 files changed, 80 insertions(+)
 create mode 100644 src/main/docs/managed-ci.adoc

diff --git a/pom.xml b/pom.xml
index 39608fd..8554f1a 100644
--- a/pom.xml
+++ b/pom.xml
@@ -145,6 +145,59 @@
     </build>
 
     <profiles>
+        <profile>
+            <id>chronicle-ci-policy</id>
+            <activation>
+                <property>
+                    <name>chronicle.ci.mode</name>
+                </property>
+            </activation>
+            <properties>
+                <chronicle.ci.forks.max8>8</chronicle.ci.forks.max8>
+            </properties>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>org.apache.maven.plugins</groupId>
+                        <artifactId>maven-surefire-plugin</artifactId>
+                        <executions>
+                            <execution>
+                                <id>default-test</id>
+                                <phase>test</phase>
+                                <goals>
+                                    <goal>test</goal>
+                                </goals>
+                                <configuration>
+                                    <forkCount>${chronicle.ci.forks.max8}</forkCount>
+                                    <rerunFailingTestsCount>0</rerunFailingTestsCount>
+                                    <runOrder>alphabetical</runOrder>
+                                    <reportsDirectory>${project.build.directory}/ci-reports/surefire/default-test</reportsDirectory>
+                                </configuration>
+                            </execution>
+                        </executions>
+                        <configuration>
+                            <forkCount>${chronicle.ci.forks.max8}</forkCount>
+                            <rerunFailingTestsCount>0</rerunFailingTestsCount>
+                            <runOrder>alphabetical</runOrder>
+                            <reportsDirectory>${project.build.directory}/ci-reports/surefire/default-cli</reportsDirectory>
+                        </configuration>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
+        <profile>
+            <id>chronicle-ci-build-all-budget</id>
+            <activation>
+                <property>
+                    <name>chronicle.ci.mode</name>
+                    <value>build-all</value>
+                </property>
+            </activation>
+            <properties>
+                <chronicle.ci.forks.max8>2</chronicle.ci.forks.max8>
+            </properties>
+        </profile>
+
         <profile>
             <id>prejava17</id>
             <activation>
diff --git a/src/main/docs/managed-ci.adoc b/src/main/docs/managed-ci.adoc
new file mode 100644
index 0000000..1833672
--- /dev/null
+++ b/src/main/docs/managed-ci.adoc
@@ -0,0 +1,27 @@
+= Managed CI qualification
+:sectnums:
+:lang: en-GB
+:source-highlighter: rouge
+
+== FIX-292 execution contract
+
+The opt-in PR route uses 1 reactor threads and up to 8 ordinary forks per active module, within an eight-test-JVM budget. This is the selected local observation, not a production performance guarantee. Existing protected executions remain one fork with a fresh JVM. A one-worker preference is retained where measured; it is independent of the safety exceptions.
+
+[source,shell]
+----
+mvn -B -ntp -T1 -Dbuild-all=true -Drun-mapping-tests -Dchronicle.ci.mode=pr -Dchronicle.ci.stage=main clean verify
+----
+
+== Adoption and evidence
+
+The current Build-All remains unchanged. These profiles require an explicit `chronicle.ci.mode`; existing lifecycle and bare Surefire invocations keep their configuration. Individual managed PR checks must opt in explicitly. Existing Snapshot statuses alone do not prove this route executed.
+
+A separate Build-All Eight project can select `chronicle.ci.mode=build-all`, initially with one shared `-T4` reactor and per-module ordinary caps of at most two. Repository caps of one remain one. Do not nest this repository's PR reactor inside that aggregate. The alternative project must validate source dependency alignment and complete inventories before replacing the current Build-All.
+
+Surefire reports are separated under each module's `target/ci-reports/surefire/<execution>`. Import all executions and compare full testcase multisets including module, execution/mode, class, parameter identity, outcome and skip identity. A green Maven exit or equal total alone is not a completeness certificate. Keep package/artifact checks and intentional mode repetitions.
+
+The selected allocation was measured on native Linux with Java 21 and unchanged declared dependencies. Other JDKs, operating systems, explicit Snapshot profiles, targeted `-Dtest` and `test-serial` routes need their own qualification before activation. Use the complete command above for this trial. No retries are introduced.
+
+== Retiring protected exceptions
+
+Fix demonstrated shared-state/resource hazards one test at a time; qualify never-tested exceptions without presuming a defect. Move only the proved-safe class into the ordinary batch, preserve assertions and full inventories, and require repeated concurrent PR and aggregate evidence. Global isolation can be removed only after cross-module interference is resolved.