Epic/0.7.1 control plane authority

.github/AGENTS.md

@@ -24,6 +24,7 @@ and related GitHub configuration.
 | CI step | Local command |
 |---------|---------------|
 | Run tests | `./gradlew test` |
+| Run tests (guarded, same guards as CI) | `bash .github/scripts/test-watchdog.sh` |
 | Verify maintainability baseline | `./gradlew verifyMaintainabilityBaseline` |
 | Full maintainability verification | `./gradlew verifyFullMaintainabilityBaseline` |
 | Change policy check | `./gradlew verifyChangePolicy` |

.github/scripts/test-watchdog.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+#
+# Guarded test runner for the CI `tests` job.
+#
+# A hanging suite and a merely slow suite need different treatment, so this carries two independent
+# guards:
+#
+#   inactivity  no observable progress for WATCHDOG_INACTIVITY_SECONDS -> a real stall, abort now
+#   ceiling     wall-clock WATCHDOG_CEILING_SECONDS -> a growth margin, abort regardless of progress
+#
+# Progress is read from Gradle's own test-result tree, which advances as each test executes. Both
+# guards dump worker threads first, so the uploaded artifact shows where the run stopped.
+#
+# Calibration consequence: the ceiling must sit comfortably above the suite's real runtime. If the
+# suite grows into the ceiling, the guard silently becomes an assertion about suite duration rather
+# than a hang detector, and healthy runs get aborted at random.
+set -uo pipefail
+
+CEILING_SECONDS="${WATCHDOG_CEILING_SECONDS:-1200}"
+INACTIVITY_SECONDS="${WATCHDOG_INACTIVITY_SECONDS:-270}"
+POLL_SECONDS="${WATCHDOG_POLL_SECONDS:-30}"
+DUMP_DIR="${WATCHDOG_DUMP_DIR:-/tmp/threaddumps}"
+RESULTS_ROOT="${WATCHDOG_RESULTS_ROOT:-.}"
+COMMAND="${WATCHDOG_COMMAND:-./gradlew test}"
+
+mkdir -p "$DUMP_DIR"
+
+progress_fingerprint() {
+  find "$RESULTS_ROOT" -path '*/build/test-results/*' -type f -printf '%p %s %T@\n' 2>/dev/null |
+    sort | md5sum | cut -d' ' -f1
+}
+
+abort() {
+  echo "::error::$1"
+  for P in $(jps -l 2>/dev/null | grep -iE 'GradleWorkerMain|GradleDaemon' | awk '{print $1}'); do
+    jstack "$P" >"$DUMP_DIR/worker-$P-$(date +%H%M%S).txt" 2>&1 || true
+  done
+  kill "$CHILD_PID" 2>/dev/null || true
+  wait "$CHILD_PID" 2>/dev/null || true
+  exit 1
+}
+
+echo "watchdog: ceiling=${CEILING_SECONDS}s inactivity=${INACTIVITY_SECONDS}s poll=${POLL_SECONDS}s results=${RESULTS_ROOT}"
+
+bash -c "exec ${COMMAND}" &
+CHILD_PID=$!
+
+started=$(date +%s)
+last_progress=$started
+fingerprint=$(progress_fingerprint)
+
+while kill -0 "$CHILD_PID" 2>/dev/null; do
+  sleep "$POLL_SECONDS"
+  now=$(date +%s)
+  current=$(progress_fingerprint)
+  if [ "$current" != "$fingerprint" ]; then
+    fingerprint="$current"
+    last_progress="$now"
+  fi
+  idle=$((now - last_progress))
+  elapsed=$((now - started))
+  if [ "$idle" -ge "$INACTIVITY_SECONDS" ]; then
+    abort "Run tests made no progress for ${idle}s (limit ${INACTIVITY_SECONDS}s) — dumping threads and aborting"
+  fi
+  if [ "$elapsed" -ge "$CEILING_SECONDS" ]; then
+    abort "Run tests reached the ${CEILING_SECONDS}s wall-clock ceiling — dumping threads and aborting"
+  fi
+done
+
+wait "$CHILD_PID"
+exit $?

.github/workflows/architecture-authority.yml

@@ -0,0 +1,84 @@
+name: Architecture Authority
+
+# The API architecture authority (verify060Architecture) aggregates Contract-1 (committed dump vs
+# source), Contract-2 (base-branch compatibility + stability policy) and the migration-registry
+# hygiene rule. It ran in NO workflow at all, and in no verifyPr lane either, so release-line drift
+# in the API/migration policy stayed invisible until someone ran it by hand — twice (0.7.1c and
+# 0.7.1d), the second time as a permanent red that no PR could clear without deleting release
+# history.
+#
+# It lives in its own workflow rather than in ci.yml because ci.yml is the JDK 25 production matrix
+# (.github/AGENTS.md rule 6), while this gate is a build-logic authority documented against JDK 21.
+# It lives outside maintainability-baseline.yml because that workflow triggers only for PRs against
+# master, which would leave every epic-targeted slice — where this drift actually happens —
+# unguarded.
+#
+# It invokes the single gate and its own base resolution; it does not re-implement the constituent
+# checks.
+
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+
+permissions:
+  contents: read
+
+jobs:
+  api-architecture:
+    name: api-architecture (verify060Architecture)
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # Contract-2 and the registry chain walk compare against base-branch dumps, so the base
+          # SHA must be resolvable from history.
+          fetch-depth: 0
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'temurin'
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v4
+        with:
+          # The gate consumes -PchangePolicyBase, which is configuration-time and untracked as a
+          # task input, so a cached result could belong to a different base SHA.
+          cache-read-only: true
+
+      - name: Resolve comparison base
+        id: base
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            BASE="${{ github.event.pull_request.base.sha }}"
+          else
+            BASE="${{ github.event.before }}"
+          fi
+          # A new branch push reports an all-zero (or empty) before-SHA; fall back to the pushed
+          # commit's parent so the gate still compares against something real.
+          case "$BASE" in
+            ""|0000000000000000000000000000000000000000)
+              BASE="$(git rev-parse HEAD~1 2>/dev/null || git rev-parse HEAD)"
+              ;;
+          esac
+          echo "sha=$BASE" >> "$GITHUB_OUTPUT"
+          echo "Comparing against base $BASE"
+
+      - name: Verify API architecture authority
+        run: |
+          ./gradlew verify060Architecture --no-daemon \
+            -PchangePolicyBase="${{ steps.base.outputs.sha }}"
+
+      - name: Upload architecture report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: api-architecture-report
+          path: build/reports/tramai/architecture/
+          retention-days: 30

.github/workflows/ci.yml

@@ -22,6 +22,8 @@ jobs:
             gates: spotlessCheck verifyStaticAnalysis verifyStaticSafetyGuards
           - name: hygiene
             gates: verifyDependencyHygiene
+          - name: junit-test-signatures
+            gates: verifyJUnitTestSignatures
 
     steps:
       - name: Checkout
@@ -101,6 +103,16 @@ jobs:
           - name: static-analysis
             test-filter: "--tests 'dev.tramai.build.quality.StaticAnalysis*Test'"
             expected: 25
+          # 0.7.1e: the API compatibility / migration-policy suites lived only in
+          # maintainability-baseline.yml, which triggers for PRs against master — so on every
+          # epic-targeted slice (where this policy actually drifts) they never ran. They are pure
+          # dump/policy logic, so they belong in this JDK 25 matrix like the other partitions.
+          - name: ci-wiring
+            test-filter: "--tests 'dev.tramai.build.quality.TestsWatchdogWiringTest'"
+            expected: 6
+          - name: api-compatibility
+            test-filter: "--tests 'dev.tramai.build.quality.ApiCompatibilityMutationTest' --tests 'dev.tramai.build.quality.ApiBaselineVerifierTest' --tests 'dev.tramai.build.quality.ApiStabilityPolicyTest'"
+            expected: 67
 
     steps:
       - name: Checkout
@@ -149,29 +161,14 @@ jobs:
         uses: gradle/actions/setup-gradle@v4
 
       - name: Run tests
-        timeout-minutes: 15
-        run: |
-          ./gradlew test &
-          GRADLE_PID=$!
-          DUMP_DIR=/tmp/threaddumps
-          mkdir -p "$DUMP_DIR"
-          # Containment watchdog: if tests exceed ~12 min, dump worker threads and
-          # fail fast instead of letting a concurrency flake hold the pipeline
-          # hostage for the full timeout.
-          for i in $(seq 1 18); do
-            if ! kill -0 "$GRADLE_PID" 2>/dev/null; then break; fi
-            sleep 40
-          done
-          if kill -0 "$GRADLE_PID" 2>/dev/null; then
-            echo "::error::Run tests exceeded 12 minutes — dumping threads and aborting"
-            for P in $(jps -l 2>/dev/null | grep -iE 'GradleWorkerMain|GradleDaemon' | awk '{print $1}'); do
-              jstack "$P" > "$DUMP_DIR/worker-$P-$(date +%H%M%S).txt" 2>&1 || true
-            done
-            kill "$GRADLE_PID" 2>/dev/null || true
-            wait "$GRADLE_PID" 2>/dev/null || true
-            exit 1
-          fi
-          wait "$GRADLE_PID"
+        timeout-minutes: 25
+        env:
+          # Wall-clock ceiling: growth margin, not a hang signal. Healthy runs measure ~13-14 min,
+          # so 20 min absorbs suite growth while the inactivity guard below catches real stalls.
+          WATCHDOG_CEILING_SECONDS: "1200"
+          # No test-result progress for 4.5 min means the run is stalled, not slow.
+          WATCHDOG_INACTIVITY_SECONDS: "270"
+        run: bash ./.github/scripts/test-watchdog.sh
 
       - name: Upload test hang thread dumps
         if: always()
@@ -220,13 +217,28 @@ jobs:
         run: |
           ./gradlew verifyMutationRatchet \
             --no-daemon \
+            -PtramaiMutationEvolution=${{ contains(github.event.pull_request.labels.*.name, 'mutation-population-evolution') && 'recorded-evolution' || 'forbid' }} \
             -PtramaiMutationBaseSha="${{ github.event.pull_request.base.sha }}"
 
       - name: Verify mutation ratchet against previous master
         if: github.event_name == 'push' && github.event.before != '0000000000000000000000000000000000000000'
+        # Evolution authority follows the transition, not the branch. A merge into master carries a
+        # mutation-population evolution only if it changed BOTH the committed population and the
+        # evolution records; anything else stays FORBID (fast, no PIT) so an ordinary push can never
+        # enter a ~50 minute campaign, and a removal without its records fails closed in FORBID.
+        # A legitimate evolution still has to survive the exact record-set check, which rejects
+        # records that do not match the identities disappearing in this transition.
         run: |
+          CHANGED=$(git diff --name-only "${{ github.event.before }}" "${{ github.sha }}")
+          EVOLUTION="forbid"
+          if echo "$CHANGED" | grep -qx 'config/quality/mutation-baseline.json' && \
+             echo "$CHANGED" | grep -qx 'config/quality/mutation-evolution.yml'; then
+            EVOLUTION="recorded-evolution"
+          fi
+          echo "mutation evolution mode: $EVOLUTION"
           ./gradlew verifyMutationRatchet \
             --no-daemon \
+            -PtramaiMutationEvolution="$EVOLUTION" \
             -PtramaiMutationBaseSha="${{ github.event.before }}"
 
   consumer-smoke:

.github/workflows/maintainability-baseline.yml

@@ -104,7 +104,25 @@ jobs:
   # MutationRatchetAuthorityTest (7) = 257 -> 302.
   # 10.3d: W4 mutation ratchet wiring discriminator + W5 CI workflow wiring discriminators in CoverageWiringTest = 248 -> 253.
   # 12.3b (R12-003): Gradle 9 strict task dependency validation tests (+1 in policy-maintainability, +1 in scanners-coverage) = 302 -> 303, 253 -> 254.
-  # Counts: 8 + 71 + 75 + 25 (quality) + 174 + 303 + 254 = 910.
+  # 0.7.1e: ApiStabilityPolicyTest (24) enrolled in scanners-coverage = 254 -> 278. The suite was
+  # in no CI lane at all, so the release-line API-policy discriminators never ran in CI.
+  # Docs/version-surface repair: the example-selection guard derives the promoted release from
+  # CHANGELOG.md, so ExampleGuideReleaseAssertionTest (+3) enters release-sovereign = 174 -> 179.
+  # The same measurement certifies accumulated policy-maintainability drift = 303 -> 305
+  # (both reproduced with the exact filters below; 0 failures).
+  # 0.7.1g1F follow-up (split out of the ceremony PR by review, scope hygiene): the pin is corrected to
+  # a MEASURED value. Measured through this lane's own 13 filters (extracted from the matrix below, not
+  # approximated): 333 on the epic line before the ceremony suite, 364 with it (0 failures both times;
+  # 333 + 31 = 364 cross-checks the two runs). The pin had been stale at 305 for the whole epic line
+  # because this workflow only triggers for pull requests targeting master, so epic-targeted PRs never
+  # exercised it.
+  # NOTE: the other lanes' pins in this matrix were NOT re-measured and may carry the same epic-line
+  # drift. Re-derive them before this workflow next runs against master.
+  # #426: sibling-catch cancellation recognition adds 8 scanner tests, and the 83-line
+  # context-equivalence case is split into three single-scenario tests (1 removed, 3 added).
+  # MERGED: master's 264 scanner tests + the epic's ApiStabilityPolicyTest (24) and nine other
+  # lane additions = 297, measured through this lane's own 20 filters after merging master in.
+  # Counts: 8 + 71 + 75 + 25 (quality) + 179 + 364 + 297 = 1019.
   build-logic-tests:
     name: build-logic (${{ matrix.name }})
     runs-on: ubuntu-latest
@@ -139,7 +157,7 @@ jobs:
               --tests 'dev.tramai.build.publishing.*'
               --tests 'dev.tramai.build.docs.*'
               --tests 'dev.tramai.build.conventions.*'
-            expected: 174
+            expected: 179
           - name: policy-maintainability
             test-filter: >-
               --tests 'dev.tramai.build.quality.ChangePolicy*Test'
@@ -155,12 +173,13 @@ jobs:
               --tests 'dev.tramai.build.quality.DetektBaselineGrowthDriftTest'
               --tests 'dev.tramai.build.quality.DependencyBaselineVerifierTest'
               --tests 'dev.tramai.build.quality.DependencyEdgeNormalizerTest'
-            expected: 303
+            expected: 364
           - name: scanners-coverage
             test-filter: >-
               --tests 'dev.tramai.build.quality.KotlinCancellationCatchScannerTest'
               --tests 'dev.tramai.build.quality.ApiCompatibilityMutationTest'
               --tests 'dev.tramai.build.quality.ApiBaselineVerifierTest'
+              --tests 'dev.tramai.build.quality.ApiStabilityPolicyTest'
               --tests 'dev.tramai.build.quality.JUnitTestSignatureVerifierTest'
               --tests 'dev.tramai.build.quality.CancellationDeltaComparatorTest'
               --tests 'dev.tramai.build.quality.CoveragePolicyDeltaVerifierTest'
@@ -177,7 +196,7 @@ jobs:
               --tests 'dev.tramai.build.quality.TestPerformanceVerifierTest'
               --tests 'dev.tramai.build.quality.TestPerformanceAggregatorTest'
               --tests 'dev.tramai.build.quality.ResolvedDependencyAggregateTest'
-            expected: 254
+            expected: 297
 
     steps:
       - name: Checkout
@@ -228,4 +247,4 @@ jobs:
           name: build-logic-${{ matrix.name }}-test-reports
           path: |
             build-logic/build/test-results/test/
-            build-logic/build/reports/tests/test/
+            build-logic/build/reports/tests/test/