@@ -57,6 +57,9 @@ jobs:
           curl -sSL https://github.com/cozystack/cozyvalues-gen/releases/download/v1.7.0/cozyvalues-gen-linux-amd64.tar.gz | tar -xzvf- -C /usr/local/bin/ cozyvalues-gen
 
       - name: Run pre-commit hooks
+        # The complete Bats pass is a manual local hook and is therefore outside
+        # this changed-file lint run. pull-requests.yaml's checks job runs the
+        # full unit path for code and the Bats contracts for docs-only changes.
         run: |
           git fetch origin main || git fetch origin master
           base_commit=$(git rev-parse --verify origin/main || git rev-parse --verify origin/master || echo "")
 
@@ -75,7 +75,6 @@ jobs:
       statuses: write
     outputs:
       code: ${{ steps.p.outputs.code }}
-      trigger_map: ${{ steps.p.outputs.trigger_map }}
       matrix: ${{ steps.p.outputs.matrix }}
       any: ${{ steps.p.outputs.any }}
       touched: ${{ steps.p.outputs.touched }}
@@ -163,23 +162,6 @@ jobs:
           else
             echo "code=false" >> "$GITHUB_OUTPUT"
           fi
-          # docs/agents/contributing.md carries the downstream trigger map, which
-          # hack/downstream-trigger-map.bats asserts against: every path the map
-          # cites still exists, and its repository list still matches the PR
-          # template. Editing the map alone is a docs-only PR, which would skip the
-          # unit tests and exempt the map from its own guard. This flag lets the
-          # unit-test job opt back in, and only that job: it deliberately does not
-          # feed `code`, so a docs PR still builds nothing.
-          #
-          # Detect the map by its old path too, which is why this reads the
-          # rename-blind list above: a PR that moves the map would otherwise skip
-          # the very test that pins the literal below to it, and break for
-          # whoever pushes next.
-          if grep -qxF 'docs/agents/contributing.md' /tmp/changed_norenames.txt; then
-            echo "trigger_map=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "trigger_map=false" >> "$GITHUB_OUTPUT"
-          fi
           matrix="$(hack/build-matrix.sh /tmp/changed.txt)"
           echo "Build matrix: $matrix"
           echo "matrix=$matrix" >> "$GITHUB_OUTPUT"
@@ -301,12 +283,12 @@ jobs:
     permissions:
       contents: read
     needs: ["plan"]
-    # trigger_map opts a docs-only PR back in when it edits the downstream trigger
-    # map, so hack/downstream-trigger-map.bats still guards it. No other job reads
-    # that flag: a docs PR runs the unit tests and nothing heavier.
+    # Unit contracts read both code and documentation. Run this job for every
+    # non-release PR: code changes take the complete unit path, while docs-only
+    # changes run the Bats lane that owns those cross-tree contracts. Builds and
+    # E2E remain gated on `code` below.
     if: |
-      (needs.plan.outputs.code == 'true' || needs.plan.outputs.trigger_map == 'true')
-      && !contains(github.event.pull_request.labels.*.name, 'release')
+      !contains(github.event.pull_request.labels.*.name, 'release')
     steps:
       - name: Checkout code
         uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
@@ -315,22 +297,45 @@ jobs:
       # Ephemeral runners don't carry the helm-unittest plugin the persistent
       # self-hosted runner accreted. Install if absent (idempotent).
       - name: Set up test toolchain
+        env:
+          CODE_CHANGED: ${{ needs.plan.outputs.code }}
+          BATS_VERSION: "1.14.0"
+          BATS_COMMIT: eb7f42f8d608ac693d7a4b67474f6714ea68cfc5
         run: |
-          helm plugin list 2>/dev/null | grep -q unittest \
-            || helm plugin install https://github.com/helm-unittest/helm-unittest
-      # The make processes share one four-slot jobserver. Each BATS file is a
-      # separate target, so the long tail no longer runs as one nine-minute shell
-      # loop; Helm and Go targets share the same bounded pool. Output stays
-      # grouped by target instead of four test logs interleaving.
-      #
+          set -euo pipefail
+          if [ "$CODE_CHANGED" = true ]; then
+            helm plugin list 2>/dev/null | grep -q unittest \
+              || helm plugin install https://github.com/helm-unittest/helm-unittest
+          fi
+          # Source archive bytes can change; verify the tag's commit before install.
+          if ! bats --version 2>/dev/null | grep -qx "Bats $BATS_VERSION"; then
+            bats_parent=$(mktemp -d "$RUNNER_TEMP/bats-core.XXXXXX")
+            bats_source="$bats_parent/source"
+            git clone --quiet --depth=1 --branch "v$BATS_VERSION" \
+              https://github.com/bats-core/bats-core.git "$bats_source"
+            test "$(git -C "$bats_source" rev-parse HEAD)" = "$BATS_COMMIT"
+            sudo "$bats_source/install.sh" /usr/local
+          fi
+          bats --version | grep -qx "Bats $BATS_VERSION"
       # -k is required, not cosmetic: unit-tests and test-controllers are two
       # independent goals on the same command line, and without -k make stops
       # handing out new work the moment any unit-tests prerequisite fails —
       # test-controllers then never starts and reports nothing, so a red BATS
       # file hides the entire Go controller suite. -k lets already-schedulable
       # goals keep running; the job still fails overall on any red target.
       - name: Run unit and controller tests
+        if: needs.plan.outputs.code == 'true'
         run: make unit-tests test-controllers -j4 -k --output-sync=target
+      - name: Run Bats unit tests for docs-only changes
+        if: needs.plan.outputs.code == 'false'
+        run: make bats-unit-tests
+      - name: Upload unit test report
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: bats-unit-report
+          path: _out/test-reports/
+          if-no-files-found: ignore
 
   # One image (package) per job, fanned out across the ephemeral pool. Each job
   # gets its own buildx (docker-container driver) so the shared-buildkit
 
@@ -21,6 +21,17 @@ repos:
         '
       language: system
       files: ^.*$
+    # The complete hack/*.bats and POSIX-compatibility pass is intentionally a
+    # manual local hook because it requires bats-core and has substantial wall
+    # time even with GNU parallel. Run it before pushing with:
+    # pre-commit run bats-unit-tests --hook-stage manual --all-files
+    # Pull-request CI remains the unconditional gate.
+    - id: bats-unit-tests
+      name: Run hack/*.bats unit tests
+      entry: make bats-unit-tests bats-posix-compat-tests
+      language: system
+      stages: [manual]
+      pass_filenames: false
 # Lints changed GitHub Actions workflows for unpinned actions and excessive token
 # permissions (audit scope is set in .github/zizmor.yml). Runs offline so it needs
 # no GitHub token locally. The same gate runs tree-wide in .github/workflows/zizmor.yml.
 
@@ -1,9 +1,4 @@
-.PHONY: manifests assets prepare-env prepare-env-container unit-tests helm-unit-tests bats-unit-tests bats-unit-files-check rd-presets-check migrations-target-check test test-controllers preflight
-
-# Before any include, the last file make has read is this one: MAKEFILES and
-# -f files given before it are earlier in the list, -f files after it are not
-# read yet.
-ROOT_MAKEFILE := $(lastword $(MAKEFILE_LIST))
+.PHONY: manifests assets prepare-env prepare-env-container unit-tests helm-unit-tests bats-unit-tests bats-unit-files-check bats-posix-compat-tests print-bats-unit-files print-bats-posix-compat-files print-bats-jobs rd-presets-check migrations-target-check test test-controllers preflight
 
 include hack/common-envs.mk
 
@@ -122,7 +117,7 @@ test:
 	make -C packages/core/testing apply
 	make -C packages/core/testing e2e
 
-unit-tests: helm-unit-tests bats-unit-tests go-unit-tests go-module-tests rd-presets-check test-check-readiness migrations-target-check
+unit-tests: helm-unit-tests bats-unit-tests bats-posix-compat-tests go-unit-tests go-module-tests rd-presets-check test-check-readiness migrations-target-check
 
 helm-unit-tests:
 	hack/helm-unit-tests.sh
@@ -174,52 +169,91 @@ test-controllers:
 test-check-readiness:
 	go test ./test/check-readiness/ -count=1
 
-# Discover every hack/*.bats file that is NOT an e2e test and run it
-# through cozytest.sh. This glob is one level deep: live-cluster suites under
-# hack/e2e-* or in subdirectories need an invocation in packages/core/testing.
-# hack/bats-runner-coverage.bats reports files that neither runner selects.
-# Park a suite with the .bats.disabled suffix to exclude it from the audit.
+# Unit discovery is one level deep. Live-cluster files need an invocation in
+# packages/core/testing; hack/bats-runner-coverage.bats checks that boundary.
+# Bats supplies TAP and JUnit output; the live-cluster runner keeps its tracing.
 #
 # Caveat: $(wildcard ...) returns space-separated names, so a filename
 # containing a literal space would split into multiple tokens here. All
 # current bats files use hyphen-separated names; if the project ever
 # introduces whitespace-bearing filenames this recipe must be rewritten
 # (e.g. to use `find ... -print0 | xargs -0`).
 BATS_UNIT_FILES := $(filter-out hack/e2e-%.bats,$(wildcard hack/*.bats))
-BATS_UNIT_TARGETS := $(patsubst hack/%.bats,bats-unit-%,$(BATS_UNIT_FILES))
-
-# Quiet by default: cozytest.sh streams every test's xtrace live, which over
-# this many suites buried the one failing assertion under ~240k lines of
-# trace in CI. COZYTEST_TRACE=0 keeps the per-test start/end lines and still dumps
-# the full trace of whichever test FAILS -- but not of one that is killed
-# instead, a hang reaped by the job timeout among them, since the dump runs
-# after the test returns. See the COZYTEST_TRACE comment in hack/cozytest.sh.
-# Override to watch a run line by
-# line: `COZYTEST_TRACE=1 make bats-unit-tests`, or invoke the runner
-# directly (`hack/cozytest.sh hack/foo.bats [pattern]`), which stays verbose.
-# The e2e call sites in packages/core/testing/Makefile are untouched and keep
-# the live stream -- see the COZYTEST_TRACE comment in hack/cozytest.sh.
-COZYTEST_TRACE ?= 0
 
-# A sub-make with --keep-going, so one red file does not stop make from
-# scheduling the files after it; the sub-make still exits non-zero if any
-# file failed (hack/bats-unit-keep-going.bats covers both). It shares the
-# caller's -j slots and --output-sync through MAKEFLAGS.
-bats-unit-tests: bats-unit-files-check
-	@$(MAKE) --file=$(ROOT_MAKEFILE) --no-print-directory --keep-going $(BATS_UNIT_TARGETS)
+# The same list, one file per line, for hack/bats-strict-setup.bats. Every unit
+# file has to load hack/test_helper.bash to get `set -u` back, and that audit is
+# only worth anything if the set it walks is the set that actually runs -- so it
+# asks here rather than keeping a second copy of the filter above.
+print-bats-unit-files:
+	@printf '%s\n' $(BATS_UNIT_FILES)
+
+# `bats -j` needs GNU parallel and exits non-zero rather than degrading when it
+# is missing. moreutils also ships a command named parallel, so identify the GNU
+# implementation from its version output before enabling concurrency. Resolve
+# the probe once per make process; `?=` would keep the `$(shell ...)` recursive
+# and rerun it at every expansion.
+ifndef BATS_JOBS
+BATS_JOBS := $(shell parallel --version 2>/dev/null | grep -q '^GNU parallel ' && nproc 2>/dev/null || echo 1)
+endif
+
+print-bats-jobs:
+	@printf '%s\n' "$(BATS_JOBS)"
+
+# JUnit XML is preserved as a CI artifact for inspection. _out is gitignored.
+BATS_REPORT_DIR ?= _out/test-reports
 
 bats-unit-files-check:
 	@if [ -z "$(BATS_UNIT_FILES)" ]; then \
 		echo "ERROR: no hack/*.bats unit test files found"; \
 		exit 1; \
 	fi
+bats-unit-tests: bats-unit-files-check
+	@command -v bats >/dev/null 2>&1 || { \
+		echo "ERROR: bats not found. Install bats-core >= 1.5 — https://bats-core.readthedocs.io"; \
+		exit 1; \
+	}
+	@mkdir -p "$(BATS_REPORT_DIR)"
+	bats -j $(BATS_JOBS) --report-formatter junit -o "$(BATS_REPORT_DIR)" $(BATS_UNIT_FILES)
+
+# Real Bats is authoritative. Unit files that source production code whose
+# contract is POSIX sh retain a compatibility pass through cozytest.sh's
+# /bin/sh translator. Discover literal .sh dependencies wherever they live,
+# including hack/lib and package migration helpers, so a new non-Chainsaw
+# helper test cannot run only under Bash. The explicit entries retain reviewed
+# shell-facing tests, including files whose production path is held in a
+# variable and therefore cannot be identified from the source line alone.
+BATS_SOURCED_SH_FILES := $(shell grep -El '^[[:space:]]*(\.|source)[[:space:]]+.*\.sh' $(BATS_UNIT_FILES))
+BATS_POSIX_COMPAT_FILES := $(sort \
+	$(BATS_SOURCED_SH_FILES) \
+	hack/capture-dataplane.bats \
+	hack/capture-previous-logs.bats \
+	hack/cilium-leak-healer_test.bats \
+	hack/container-lane-capacity_test.bats \
+	hack/cozyreport-talos.bats \
+	hack/cozyreport.bats \
+	hack/cozystack-version-stamp.bats \
+	hack/nightly-mirror_test.bats \
+	hack/pod-label-census_test.bats \
+	hack/promote-rewrite-tags_test.bats \
+	hack/runner-identity.bats \
+	hack/seaweedfs-naming-audit.bats \
+)
+
+# CI's /bin/sh is dash. Keep the interpreter overridable so contributors can
+# run the same compatibility lane explicitly on hosts whose /bin/sh differs.
+BATS_POSIX_SHELL ?= /bin/sh
+COZYTEST_TRACE ?= 0
+
+print-bats-posix-compat-files:
+	@printf '%s\n' $(BATS_POSIX_COMPAT_FILES)
 
-# Each file is its own target of the sub-make so `make -jN` can schedule them,
-# and the trace switch rides along per target.
-.PHONY: $(BATS_UNIT_TARGETS)
-$(BATS_UNIT_TARGETS): bats-unit-%: hack/%.bats
-	@echo "--- running $< ---"
-	@COZYTEST_TRACE=$(COZYTEST_TRACE) hack/cozytest.sh "$<"
+bats-posix-compat-tests:
+	@status=0; \
+	for f in $(BATS_POSIX_COMPAT_FILES); do \
+		echo "--- running POSIX compatibility: $$f ---"; \
+		COZYTEST_TRACE=$(COZYTEST_TRACE) "$(BATS_POSIX_SHELL)" hack/cozytest.sh "$$f" || status=1; \
+	done; \
+	exit $$status
 
 # Operator-facing host preflight check. Warns about a standalone
 # containerd.service or docker.service running alongside the embedded