test: expand script coverage and add dev setup bootstrap

.bats-version

@@ -0,0 +1 @@
+1.11.0

.github/workflows/ci.yml

@@ -63,12 +63,10 @@ jobs:
       - uses: actions/setup-go@v5
         with:
           go-version-file: go.mod
-      - name: Install benchmark quality tools
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y hyperfine
-          go install golang.org/x/perf/cmd/benchstat@latest
-          echo "$(go env GOPATH)/bin" >> "$GITHUB_PATH"
+      - name: Install script toolchain
+        run: make setup-dev-env-ci-scripts
+      - name: Run non-network script unit tests
+        run: make test-scripts
       - name: Run benchmark script smoke
         run: bash scripts/run-all.sh
       - name: Generate report from raw results

.gitignore

@@ -10,6 +10,7 @@ coverage.out
 # Python cache/bytecode
 **/__pycache__/
 *.py[cod]
+.venv/
 
 # Local worktrees
 .worktrees/

CONTRIBUTING.md

@@ -16,6 +16,27 @@ This repository validates API parity and runs framework benchmarks. Keep changes
 - Go 1.25.7+
 - Docker + Docker Compose (for local service runs)
 - GNU Make
+- Python 3
+- `pytest` and `pytest-cov`
+- `bats` (bats-core)
+- `jsonschema` Python package
+
+Bootstrap local dependencies:
+
+```bash
+bash scripts/setup-dev-env.sh
+```
+
+Optional targeted setup modes:
+
+```bash
+# CI-friendly install flow
+bash scripts/setup-dev-env.sh --ci --subset core,python-test,shell-test,benchmark-tools
+
+# Makefile wrappers
+make setup-dev-env
+make setup-dev-env-ci-scripts
+```
 
 ## Local validation
 
@@ -24,6 +45,7 @@ Run these before opening a PR:
 ```bash
 go test ./...
 make test-coverage
+make test-scripts
 TARGET=http://localhost:3001 bash scripts/parity-check.sh
 ```
 
@@ -43,6 +65,7 @@ If you changed benchmark artifacts or report generation, also run schema validat
 
 ```bash
 make benchmark-schema-validate
+make ci-benchmark-quality-check
 ```
 
 ## Pull request process

METHODOLOGY.md

@@ -22,7 +22,7 @@
 - shell scripts in `scripts/` for orchestration
 - `hyperfine` benchmark engine (optional via `BENCH_ENGINE=hyperfine`)
 - `benchstat` statistical comparison for quality gates
-- policy file: `stats-policy.yaml`
+- policy file: `stats-policy.json` (`stats-policy.yaml` accepted for backward compatibility)
 - Python 3 report and normalization tooling in `scripts/`
 
 ## Baseline benchmark profile
@@ -33,7 +33,7 @@
 
 ## Quality policy
 
-- thresholds and required metrics are defined in `stats-policy.yaml`
+- thresholds and required metrics are defined in `stats-policy.json`
 - `make ci-benchmark-quality-check` enforces policy locally and in CI
 - benchstat comparisons are evaluated against policy baseline framework (`baseline` by default)
 - manual CI benchmark runs use bounded workflow inputs (`frameworks` subset, `runs` 1..10, `benchmark_requests` 50..1000)

Makefile

@@ -1,11 +1,22 @@
 SHELL := /bin/sh
 PYTHON ?= python3
 GO ?= go
+PYTEST ?= pytest
+BATS ?= bats
+
+ifneq ("$(wildcard .venv/bin/python)","")
+PYTHON := .venv/bin/python
+endif
+
+ifneq ("$(wildcard .venv/bin/pytest)","")
+PYTEST := .venv/bin/pytest
+endif
+
 GOPATH ?= $(shell $(GO) env GOPATH)
 GO_PATCH_COVER ?= $(GOPATH)/bin/go-patch-cover
 MODULES = $(shell find . -type f -name "go.mod" -not -path "*/.*/*" -not -path "*/vendor/*" -exec dirname {} \;)
 
-.PHONY: benchmark benchmark-modkit benchmark-nestjs benchmark-baseline benchmark-wire benchmark-fx benchmark-do report test test-coverage test-patch-coverage tools parity-check parity-check-modkit parity-check-nestjs benchmark-fingerprint-check benchmark-limits-check benchmark-manifest-check benchmark-raw-schema-check benchmark-summary-schema-check benchmark-schema-validate benchmark-stats-check benchmark-variance-check benchmark-benchstat-check ci-benchmark-quality-check workflow-concurrency-check workflow-budget-check workflow-inputs-check report-disclaimer-check methodology-changelog-check publication-sync-check
+.PHONY: benchmark benchmark-modkit benchmark-nestjs benchmark-baseline benchmark-wire benchmark-fx benchmark-do report test test-go test-python test-shell test-scripts test-coverage test-coverage-go test-coverage-python test-patch-coverage tools setup-dev-env setup-dev-env-ci setup-dev-env-ci-scripts parity-check parity-check-modkit parity-check-nestjs benchmark-fingerprint-check benchmark-limits-check benchmark-manifest-check benchmark-raw-schema-check benchmark-summary-schema-check benchmark-schema-validate benchmark-stats-check benchmark-variance-check benchmark-benchstat-check ci-benchmark-quality-check workflow-concurrency-check workflow-budget-check workflow-inputs-check report-disclaimer-check methodology-changelog-check publication-sync-check
 
 benchmark:
 	bash scripts/run-all.sh
@@ -32,9 +43,34 @@ report:
 	$(PYTHON) scripts/generate-report.py
 
 test:
+	$(MAKE) test-go
+	$(MAKE) test-scripts
+
+test-go:
 	$(GO) test ./...
 
+test-python:
+	@if ! command -v $(PYTEST) >/dev/null 2>&1; then \
+		echo "pytest not found; install with: $(PYTHON) -m pip install pytest pytest-cov"; \
+		exit 1; \
+	fi
+	$(PYTEST) tests/unit
+
+test-shell:
+	@if ! command -v $(BATS) >/dev/null 2>&1; then \
+		echo "bats not found; install bats-core before running shell tests"; \
+		exit 1; \
+	fi
+	$(BATS) tests/integration
+
+test-scripts:
+	$(MAKE) test-python
+	$(MAKE) test-shell
+
 test-coverage:
+	$(MAKE) test-coverage-go
+
+test-coverage-go:
 	@mkdir -p .coverage
 	@echo "mode: atomic" > .coverage/coverage.out
 	@for mod in $(MODULES); do \
@@ -44,10 +80,17 @@ test-coverage:
 			tail -n +2 $$mod/profile.out >> .coverage/coverage.out; \
 			rm $$mod/profile.out; \
 		fi; \
-	done
+		done
 	@printf "\nTotal Coverage:\n"
 	@$(GO) tool cover -func=.coverage/coverage.out | grep "total:"
 
+test-coverage-python:
+	@if ! command -v $(PYTEST) >/dev/null 2>&1; then \
+		echo "pytest not found; install with: $(PYTHON) -m pip install pytest pytest-cov"; \
+		exit 1; \
+	fi
+	$(PYTEST) tests/unit --cov=scripts --cov-report=term-missing
+
 test-patch-coverage: tools test-coverage
 	@echo "Comparing against origin/main..."
 	@git diff -U0 --no-color origin/main...HEAD > .coverage/diff.patch
@@ -60,6 +103,15 @@ tools:
 	@$(GO) install github.com/seriousben/go-patch-cover/cmd/go-patch-cover@latest
 	@echo "Done: go-patch-cover installed"
 
+setup-dev-env:
+	bash scripts/setup-dev-env.sh
+
+setup-dev-env-ci:
+	bash scripts/setup-dev-env.sh --ci --subset core,python-test,go-tools
+
+setup-dev-env-ci-scripts:
+	bash scripts/setup-dev-env.sh --ci --subset core,python-test,shell-test,benchmark-tools
+
 parity-check:
 	TARGET="$(PARITY_TARGET)" bash scripts/parity-check.sh
 

README.md

@@ -61,8 +61,16 @@ BENCH_ENGINE=hyperfine make benchmark
 
 ## Tooling prerequisites
 
+- One-command local setup: `bash scripts/setup-dev-env.sh`
+- CI/subset setup examples:
+  - `bash scripts/setup-dev-env.sh --ci --subset core,python-test,shell-test,benchmark-tools`
+  - `make setup-dev-env-ci-scripts`
+
 - Go (for `go test` and `benchstat`)
 - Python 3
+- pytest + pytest-cov (for Python unit tests)
+- bats-core (for shell integration tests)
+- jsonschema (for schema validation checks)
 - hyperfine (optional benchmark engine)
 - benchstat (`go install golang.org/x/perf/cmd/benchstat@latest`)
 - go-patch-cover (`go install github.com/seriousben/go-patch-cover/cmd/go-patch-cover@latest`, for `make test-patch-coverage`)
@@ -108,7 +116,6 @@ benchmarks/
 - `docs/guides/adding-scenarios.md` - how to add parity scenarios
 - `docs/guides/benchmark-workflow.md` - benchmark and reporting flow
 - `docs/guides/benchmark-publication-policy.md` - minimum disclosure for publishable results
-- `docs/guides/repository-metadata.md` - repository metadata and positioning
 
 **Governance:**
 - `MAINTAINERS.md` - maintainership roles and triage expectations