feat: add benchmark quality and gate why mode

Author: a-a-k

.github/workflows/release-dry-run.yml

@@ -53,4 +53,5 @@ jobs:
             release-manifest.json
             charts/sheaft/**
             .tmp/smoke-examples/**
+            .tmp/benchmark-slice/**
           if-no-files-found: error

.github/workflows/release.yml

@@ -51,6 +51,9 @@ jobs:
       - name: Package default config pack
         run: make default-config-pack APP_VERSION=${APP_VERSION#v}
 
+      - name: Run fixed benchmark slice
+        run: make benchmark-slice BENCHMARK_OUT_DIR=dist/benchmark-slice
+
       - name: Publish OCI image
         run: |
           OWNER_LC="$(printf '%s' "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')"
@@ -114,6 +117,9 @@ jobs:
               find dist/charts -maxdepth 1 -type f -name 'sheaft-*.tgz'
             } | sort
           )
+          if [ -f dist/benchmark-slice/quality-report.json ]; then
+            files+=("dist/benchmark-slice/quality-report.json")
+          fi
           files+=("compatibility-manifest.json")
           files+=("release-manifest.json")
           gh release upload "${TAG}" "${files[@]}" --clobber

CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## v0.2.4 - 2026-05-31
+
+Technical-preview feature release focused on trustable gate evidence, benchmark packaging, and explainable gate decisions for the `v0.2.x` line.
+
+Included in this release:
+
+- added a fixed Sheaft-on-Bering benchmark slice with `make benchmark-slice` and a versioned manifest under `benchmarks/fixed-slice`
+- added benchmark quality reporting with repeatability, confidence, advanced-metric availability, baseline-diff, contract, and cross-profile checks
+- added machine-readable gate decision reasons in `report.json` and a Why section in `summary.md`
+- added `sheaft gate --why` and `sheaft run --why` for human-readable gate explanations
+- added the benchmark manifest to the default config pack and the benchmark slice to release dry-run validation
+- refreshed roadmap, release tracking, and assumptions documentation after closing R4.1, R4.2, R4.3, and R9.1
+
+Stable within the `v0.2.4` preview:
+
+- the same strict `1.0.0` and `1.1.0` Bering contract acceptance introduced in `v0.2.0`
+- deterministic batch analysis, baseline comparison, and CI gate behavior from the `v0.2.0` line
+- release validation now includes the fixed benchmark slice and quality-report generation
+- gate decisions now carry threshold, aggregate, and assertion causes for release review
+
+Still experimental in `v0.2.4`:
+
+- long-running `serve` / `watch` service mode remains technical-preview surface
+- local `discover` helper
+- broader operator-facing packaging and operational conventions around image/chart deployment
+- benchmark scale and external quality datasets remain outside this repository
+
 ## v0.2.3 - 2026-05-01
 
 Technical-preview patch release focused on Kubernetes handoff reliability for the `v0.2.x` line.

Makefile

@@ -30,8 +30,9 @@ BUILD_DATE ?= $(shell git log -1 --format=%cI 2>/dev/null || date -u +"%Y-%m-%dT
 endif
 DIST_DIR ?= dist
 PLATFORMS ?= linux/amd64,linux/arm64
+BENCHMARK_OUT_DIR ?= .tmp/benchmark-slice
 
-.PHONY: help build test lint smoke-examples docker-build docker-run-sample sample compatibility-manifest validate-compatibility-manifest validate-chart default-config-pack release-tools release-build image-dry-run image-local chart-package chart-publish-local release-manifest validate-release-manifest validate-release-assets release-dry-run release-local clean clean-dist
+.PHONY: help build test lint smoke-examples benchmark-slice docker-build docker-run-sample sample compatibility-manifest validate-compatibility-manifest validate-chart default-config-pack release-tools release-build image-dry-run image-local chart-package chart-publish-local release-manifest validate-release-manifest validate-release-assets release-dry-run release-local clean clean-dist
 
 ifeq ($(OS),Windows_NT)
 define MKDIR_P
@@ -57,6 +58,7 @@ help:
 	@echo "  test                       Run Go tests"
 	@echo "  lint                       Run go vet"
 	@echo "  smoke-examples             Build the CLI and smoke checked-in examples"
+	@echo "  benchmark-slice            Run the fixed Sheaft-on-Bering benchmark slice"
 	@echo "  docker-build               Build the local container image"
 	@echo "  docker-run-sample          Run sample pipeline in the container image"
 	@echo "  compatibility-manifest     Generate compatibility-manifest.json from strict contract pins"
@@ -85,6 +87,9 @@ else
 	"$(POSIX_SH)" scripts/ci/smoke-examples.sh .tmp/smoke-examples ./bin/sheaft$(EXEEXT)
 endif
 
+benchmark-slice:
+	go run ./cmd/releasectl benchmark-slice --manifest benchmarks/fixed-slice/manifest.json --out-dir $(BENCHMARK_OUT_DIR)
+
 docker-build:
 	docker build -f build/Dockerfile -t $(IMAGE) .
 
@@ -156,7 +161,7 @@ validate-release-manifest:
 
 validate-release-assets: validate-compatibility-manifest validate-chart validate-release-manifest
 
-release-dry-run: compatibility-manifest test smoke-examples release-build default-config-pack image-dry-run chart-package release-manifest validate-release-assets
+release-dry-run: compatibility-manifest test smoke-examples benchmark-slice release-build default-config-pack image-dry-run chart-package release-manifest validate-release-assets
 
 release-local: compatibility-manifest test smoke-examples release-build
 ifeq ($(OS),Windows_NT)

README.md

@@ -5,7 +5,7 @@
 [![ci-template-smoke](https://img.shields.io/github/actions/workflow/status/MB3R-Lab/Sheaft/ci-template-smoke.yml?branch=main&label=ci-template-smoke)](https://github.com/MB3R-Lab/Sheaft/actions/workflows/ci-template-smoke.yml)
 [![schema-contract](https://img.shields.io/github/actions/workflow/status/MB3R-Lab/Sheaft/schema-contract.yml?branch=main&label=schema-contract)](https://github.com/MB3R-Lab/Sheaft/actions/workflows/schema-contract.yml)
 [![Go version](https://img.shields.io/github/go-mod/go-version/MB3R-Lab/Sheaft)](https://github.com/MB3R-Lab/Sheaft/blob/main/go.mod)
-[![Technical preview](https://img.shields.io/badge/preview-v0.2.3-orange)](https://github.com/MB3R-Lab/Sheaft/releases/tag/v0.2.3)
+[![Technical preview](https://img.shields.io/badge/preview-v0.2.4-orange)](https://github.com/MB3R-Lab/Sheaft/releases/tag/v0.2.4)
 [![Bering support](https://img.shields.io/badge/Bering-1.0%20%7C%201.1-blue)](https://github.com/MB3R-Lab/Sheaft/blob/main/docs/compatibility-matrix.md)
 
 Sheaft is a downstream resilience posture engine and CI/CD gate for model artifacts produced by Bering or another compatible upstream producer.
@@ -21,16 +21,18 @@ It stays downstream of topology discovery. The public surface in this repository
 
 ## Stability / Release Status
 
-The current public release is `v0.2.3`. The `v0.2.x` line is an experimental public release and should be treated as a technical preview, not a stable GA release.
+The current public release is `v0.2.4`. The `v0.2.x` line is an experimental public release and should be treated as a technical preview, not a stable GA release.
 
-Stable within the `v0.2.3` technical preview:
+Stable within the `v0.2.4` technical preview:
 
 - strict acceptance of the baseline Bering contract line: `io.mb3r.bering.model@1.0.0` and `io.mb3r.bering.snapshot@1.0.0`
 - strict acceptance of the advanced Bering contract line: `io.mb3r.bering.model@1.1.0` and `io.mb3r.bering.snapshot@1.1.0`
 - batch CLI command names and core flow: `simulate`, `gate`, `run`
 - deterministic batch execution for a fixed seed and config
 - cross-line baseline comparison through `analysis.baselines`
 - additive advanced analysis when `1.1.0` metadata exists
+- gate decision reasons in `report.json`, `summary.md`, and `sheaft gate/run --why`
+- fixed benchmark slice and release-quality `quality-report.json` generation
 - release archives for Linux and macOS on `amd64` and `arm64`
 
 Experimental in `v0.2.x`:
@@ -181,6 +183,7 @@ Sheaft is intentionally downstream of Bering artifacts and schemas.
 - `serve` and its watch loop are suitable for technical-preview evaluation, not yet for a stable long-term operational contract.
 - The richer analysis surface is available, but its configuration ergonomics and operational conventions may still change in later `0.x` releases.
 - Release automation is designed around GitHub Releases, release manifests, OCI image publication, and an OCI Helm chart; Windows release archives can be built, but they are not the primary tested surface in this preview.
+- Before using a Sheaft report as blocking release evidence, review the do-not-trust signal catalogue in [Assumptions and Limitations](docs/assumptions-and-limitations.md).
 
 ## Development
 
@@ -191,6 +194,7 @@ make build
 make test
 make lint
 make smoke-examples
+make benchmark-slice
 ```
 
 Direct command equivalents:
@@ -211,6 +215,7 @@ go vet ./...
 - [Methodology](docs/methodology.md)
 - [Configuration and Schemas](docs/configuration.md)
 - [CI Gate](docs/ci-gate.md)
+- [Fixed Benchmark Slice](docs/benchmark-slice.md)
 - [Consumer Semantics v1](docs/consumer-semantics-v1.md)
 - [Consumer Semantics v2](docs/consumer-semantics-v2.md)
 - [Versioning](VERSIONING.md)

RELEASING.md

@@ -45,6 +45,7 @@ A successful tagged release publishes:
 - `compatibility-manifest.json`
 - `release-manifest.json`
 - default config pack archive
+- fixed benchmark quality report
 - versioned GitHub release notes from `release/<tag>.md`, when present
 
 ## Local Validation
@@ -82,12 +83,13 @@ On tag push it:
 
 1. runs tests;
 2. runs smoke checks against checked-in examples;
-3. builds release archives with GoReleaser;
-4. publishes the OCI image;
-5. publishes the OCI Helm chart;
-6. generates `release-manifest.json`;
-7. creates or updates the GitHub Release using `release/<tag>.md` when available;
-8. uploads the canonical payload to the GitHub Release.
+3. runs the fixed benchmark slice;
+4. builds release archives with GoReleaser;
+5. publishes the OCI image;
+6. publishes the OCI Helm chart;
+7. generates `release-manifest.json`;
+8. creates or updates the GitHub Release using `release/<tag>.md` when available;
+9. uploads the canonical payload to the GitHub Release.
 
 ## Generic CI Reuse
 

api/schema/benchmark-quality.schema.json

@@ -0,0 +1,149 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/MB3R-Lab/Sheaft/api/schema/benchmark-quality.schema.json",
+  "title": "SheaftBenchmarkQualityReport",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "benchmark_name",
+    "status",
+    "generated_at",
+    "inputs",
+    "outputs",
+    "metrics",
+    "checks"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string"
+    },
+    "benchmark_name": {
+      "type": "string"
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "pass",
+        "fail"
+      ]
+    },
+    "generated_at": {
+      "type": "string"
+    },
+    "inputs": {
+      "type": "object",
+      "required": [
+        "artifact",
+        "analysis"
+      ],
+      "properties": {
+        "artifact": {
+          "type": "string"
+        },
+        "analysis": {
+          "type": "string"
+        }
+      }
+    },
+    "outputs": {
+      "type": "object",
+      "required": [
+        "model",
+        "report",
+        "summary",
+        "quality_report"
+      ],
+      "properties": {
+        "model": {
+          "type": "string"
+        },
+        "report": {
+          "type": "string"
+        },
+        "summary": {
+          "type": "string"
+        },
+        "quality_report": {
+          "type": "string"
+        }
+      }
+    },
+    "metrics": {
+      "type": "object",
+      "required": [
+        "decision",
+        "profile_count",
+        "confidence",
+        "cross_profile_weighted_availability",
+        "risk_score",
+        "unavailable_advanced_metrics",
+        "baseline_diff_count",
+        "stable_report_sha256",
+        "repeat_stable_report_sha256"
+      ],
+      "properties": {
+        "decision": {
+          "type": "string"
+        },
+        "profile_count": {
+          "type": "integer"
+        },
+        "confidence": {
+          "type": "number"
+        },
+        "cross_profile_weighted_availability": {
+          "type": "number"
+        },
+        "risk_score": {
+          "type": "number"
+        },
+        "unavailable_advanced_metrics": {
+          "type": "integer"
+        },
+        "baseline_diff_count": {
+          "type": "integer"
+        },
+        "stable_report_sha256": {
+          "type": "string"
+        },
+        "repeat_stable_report_sha256": {
+          "type": "string"
+        }
+      }
+    },
+    "checks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "status",
+          "expected",
+          "actual",
+          "message"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "pass",
+              "fail"
+            ]
+          },
+          "expected": {
+            "type": "string"
+          },
+          "actual": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}