aatuh · aatuh · Aug 22, 2026 · Aug 22, 2026
@@ -17,6 +17,7 @@ permissions:
 
 jobs:
   pr-title:
+    name: pr-title
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
     steps:
@@ -26,6 +27,7 @@ jobs:
           PR_TITLE: ${{ github.event.pull_request.title }}
         run: make pr-title-check
   test:
+    name: test (${{ matrix.go-version }})
     runs-on: ubuntu-latest
     env:
       GOTOOLCHAIN: local
@@ -136,6 +138,7 @@ jobs:
           GOWORK: off
         run: go build ./...
   postgres-contract:
+    name: postgres-contract
     runs-on: ubuntu-latest
     env:
       API_TOOLKIT_TEST_POSTGRES: "1"
@@ -164,6 +167,7 @@ jobs:
       - name: Real PostgreSQL harness
         run: make test-postgres
   redis-contract:
+    name: redis-contract
     runs-on: ubuntu-latest
     env:
       API_TOOLKIT_TEST_REDIS: "1"
@@ -190,6 +194,7 @@ jobs:
           make test-redis
           make supported-adapter-check
   lint:
+    name: lint
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # actions/checkout v7.0.0
@@ -200,6 +205,7 @@ jobs:
       - name: Lint
         run: make lint
   governance:
+    name: governance
     runs-on: ubuntu-latest
     env:
       GOTOOLCHAIN: local
@@ -229,6 +235,7 @@ jobs:
           API_BASE_REF: origin/${{ github.base_ref }}
         run: make contrib-api-drift-report
   api-check:
+    name: api-check (${{ matrix.go-version }})
     runs-on: ubuntu-latest
     env:
       GOTOOLCHAIN: local
@@ -274,6 +281,7 @@ jobs:
           UPGRADE_SMOKE_BASE_REF: v3.1.2
         run: make upgrade-smoke-check
   fuzz:
+    name: fuzz
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # actions/checkout v7.0.0
@@ -300,6 +308,7 @@ jobs:
           if-no-files-found: warn
           retention-days: 7
   mutation:
+    name: mutation
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # actions/checkout v7.0.0

@@ -17,6 +17,7 @@ jobs:
       actions: read
       contents: read
       security-events: write
+    name: analyze
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # actions/checkout v7.0.0

@@ -9,6 +9,7 @@ permissions:
 
 jobs:
   dependency-review:
+    name: dependency-review
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository

@@ -68,6 +68,7 @@ jobs:
       attestations: write
       contents: write
       id-token: write
+    name: release-preflight
     needs: [toolchain-compatibility, redis-contract]
     env:
       TOOLCHAIN_MATRIX_RESULT: passed

@@ -44,7 +44,7 @@ export
 endif
 GITHUB_AUTH_TOKEN ?= $(GITHUB_TOKEN) # GitHub PAT.
 
-.PHONY: help tools api-check release-api-check api-check-contract api-inventory api-inventory-check api-additions-check api-additions-check-contract docs-site docs-site-check dead-code-todo-check dead-code-todo-contract contrib-api-drift-report contrib-release-notes-check dependency-report dependency-boundary-check full-profile-scaffold-check generated-integration-check generated-integration-check-minio generated-integration-contract generated-soak-check generated-soak-contract generated-failure-check generated-failure-contract generated-upgrade-compat-check generated-upgrade-compat-contract upgrade-smoke-check upgrade-smoke-contract reference-service-check reference-service-coverage reference-service-load reference-service-load-contract reference-service-evidence reference-service-evidence-contract test-postgres test-redis supported-adapter-check v3-readiness-check contrib-review-contract actions-audit actions-audit-contract sbom-license-report-contract release-artifact-verify-contract release-evidence-parser-contract release-tag-consistency-check release-tag-consistency-contract release-quality-baseline-contract version-consistency-check version-consistency-contract pr-title-check pr-title-check-contract docs-check fmt lint vuln gosec tidy test example-compile-check coverage coverage-check coverage-trend-record coverage-trend-check benchmark-baseline-check fast-check test-race timeout-determinism-check fuzz fuzz-contract mutation-smoke benchmark-smoke clean finalize audit-check reviewer-gate release-check release-evidence release-review-summary release-artifact-verify release-artifact-verify-fixture ci-build-smoke codeql-local .codeql-local-build scorecard-local sbom-local github-governance-check
+.PHONY: help tools api-check release-api-check api-check-contract api-inventory api-inventory-check api-additions-check api-additions-check-contract docs-site docs-site-check dead-code-todo-check dead-code-todo-contract contrib-api-drift-report contrib-release-notes-check dependency-report dependency-boundary-check full-profile-scaffold-check generated-integration-check generated-integration-check-minio generated-integration-contract generated-soak-check generated-soak-contract generated-failure-check generated-failure-contract generated-upgrade-compat-check generated-upgrade-compat-contract upgrade-smoke-check upgrade-smoke-contract reference-service-check reference-service-coverage reference-service-load reference-service-load-contract reference-service-evidence reference-service-evidence-contract test-postgres test-redis supported-adapter-check v3-readiness-check contrib-review-contract actions-audit actions-audit-contract sbom-license-report-contract release-artifact-verify-contract release-evidence-parser-contract release-tag-consistency-check release-tag-consistency-contract release-quality-baseline-contract version-consistency-check version-consistency-contract pr-title-check pr-title-check-contract required-checks-verify required-checks-verify-contract docs-check fmt lint vuln gosec tidy test example-compile-check coverage coverage-check coverage-trend-record coverage-trend-check benchmark-baseline-check fast-check test-race timeout-determinism-check fuzz fuzz-contract mutation-smoke mutation-check benchmark-smoke clean finalize audit-check reviewer-gate release-check release-evidence release-review-summary release-artifact-verify release-artifact-verify-fixture ci-build-smoke codeql-local .codeql-local-build scorecard-local sbom-local github-governance-check
 
 help: ## Show help
 	@awk 'BEGIN {FS=":.*## "}; \
@@ -177,6 +177,12 @@ supported-adapter-check: ## Verify supported PostgreSQL and Redis real-service e
 github-governance-check: ## Optional authenticated GitHub branch/tag protection verification
 	@scripts/github_governance_check.sh
 
+required-checks-verify: ## Verify the required-check manifest against stable workflow job identities
+	@scripts/required_checks_verify.sh
+
+required-checks-verify-contract: ## Exercise required-check manifest and branch-protection failure modes
+	@bash scripts/required_checks_verify_contract_test.sh
+
 v3-readiness-check: ## Run compatibility-sensitive v3 readiness guardrails
 	@$(GO) test ./docscheck -count=1 -run 'TestCompatibilitySensitivePortsManifestIsCurrent|TestContribPackageClassificationAndCompatibilityPolicy|TestCompatibilityShimLifecycleRoadmap|TestIdempotencyCompatibilityMetricDocsStayBounded|TestResponseWriterInventoryMatchesCurrentImports|TestPublicExamplesDoNotTeachLegacyCompatibilitySurfaces|TestV3RemovalMatrixHasExecutableEvidence|TestV3DebtChecklistRowsStayExecutable|TestCompatibilityRoadmapCoversDocumentedSensitiveSurfaces|TestCompatibilitySensitivePortsGovernanceDocs|TestCompatibilitySensitivePackageDocsPointToReplacements|TestExamplesAndGuidesPreferCompatibilityReplacements|TestReleaseNotesIncludeStableSurfaceChecklist|TestDeprecatedBillingPortsPointToCompatPackage|TestDeprecatedBillingPortsStayInCompatibilitySource|TestDatabaseStatsStayInCompatibilityOrAdapterSource|TestAdapterLegacyRecoveryTelemetryRedactsKeysByDefault|TestIdempotencyCaptureDoesNotUseLegacyResponseWriter'
 
@@ -194,6 +200,8 @@ sbom-license-report-contract: ## Run SPDX dependency license report contract tes
 
 docs-check: ## Run documentation contract checks
 	@$(GO) test ./docscheck -count=1
+	@$(MAKE) required-checks-verify
+	@$(MAKE) required-checks-verify-contract
 	@$(MAKE) version-consistency-check
 	@$(MAKE) version-consistency-contract
 	@$(MAKE) coverage-trend-check
@@ -363,6 +371,7 @@ release-check: ## Run release readiness checks; requires explicit API_BASE_REF
 	$(MAKE) vuln
 	$(MAKE) gosec
 	$(MAKE) ci-build-smoke
+	$(MAKE) required-checks-verify
 	$(MAKE) release-api-check
 	$(MAKE) contrib-api-drift-report
 	$(MAKE) contrib-release-notes-check
@@ -376,6 +385,7 @@ release-check: ## Run release readiness checks; requires explicit API_BASE_REF
 	$(MAKE) test
 	$(MAKE) test-race
 	$(MAKE) fuzz
+	$(MAKE) mutation-check
 	$(MAKE) clean
 
 release-evidence: ## Run release readiness and write release-check-summary.json

@@ -203,6 +203,7 @@ identifies the installed generator and contract tool.
 | [Reproducible build status](reproducible-builds.md) | Release consumers and maintainers | Distinguish unsupported binary reproducibility from the checksums, signatures, and provenance verified for release assets. |
 | [Release review checklist](release-review.md) | Release reviewers | Short path through summary fields, manifests, dirty-tree decisions, artifacts, and release notes. |
 | [Governance](governance.md) | Maintainers | Branch protection, CODEOWNERS, tag protection, required checks, and release approval expectations. |
+| `docs/required-checks.json` | Maintainers and automation | Canonical check names, workflow/job identities, GitHub App bindings, owners, and PR/release classifications for protected quality gates. |
 | [Changelog](../CHANGELOG.md) | Release consumers | Concise user-facing history for published releases. |
 | [Release notes](release-notes.md) | Release consumers and maintainers | Dated behavior changes, upgrade notes, and package-tied contrib drift acknowledgements. |
 | [Release manifests](release-manifests.md) | Release reviewers and maintainers | Human guide for package classification, contrib drift, contrib dispositions, and vulnerability dispositions. |

@@ -19,24 +19,26 @@ and `docs/stable-core.md`.
   eligible maintainer is added.
 - Require the CodeQL `code_scanning` ruleset on `master` with Errors and
   Warnings plus High-or-higher security alerts blocking merges.
-- Require the CI jobs that apply to the change:
-  - `ci / test`, including `make coverage-check`, `make test-race`, and
-    `make vuln`.
-  - `ci / lint`, including `make lint`.
-  - `ci / governance`, including `make docs-check`,
-    `make v3-readiness-check`, and pull-request contrib drift/release-note
-    checks.
-  - `ci / api-check`, including `make release-api-check` against the pull
-    request base or push predecessor.
-  - `ci / fuzz`, including `make fuzz` and a failure-only upload of minimized
-    synthetic fuzz corpus files.
-  - `ci / mutation`, including `make mutation-check` with its documented
-    assertion-based kill-rate threshold.
-  - `dependency-review / dependency-review`, which fails pull requests that
-    introduce high or critical vulnerable dependencies or dependencies outside
-    the configured license policy.
-  - `codeql` and `scorecard` workflow results when those workflows are enabled
-    for the repository.
+- Require every pull-request identity in `docs/required-checks.json`, with the
+  exact check name and GitHub App binding recorded there. The manifest groups
+  the stable gates as follows:
+  - `test (1.25.x)` and `test (1.26.x)` cover unit tests,
+    `make coverage-check`, `make test-race`, `make vuln`, builds, examples, and
+    dependency-footprint evidence.
+  - The four `platform-core (...)` identities cover Linux amd64, native Linux
+    arm64, macOS arm64, and Windows amd64 portability.
+  - `lint`, `governance`, both `api-check (...)` identities, `fuzz`, and
+    `mutation` run `make lint`, `make docs-check`, `make v3-readiness-check`,
+    `make release-api-check`, `make fuzz`, and `make mutation-check` across
+    static quality, documentation and dependency boundaries, API compatibility,
+    malformed-input smoke, and assertion-sensitive testing.
+  - `postgres-contract` and `redis-contract` cover supported real-service
+    integration contracts.
+  - `analyze`, `CodeQL`, and `dependency-review` cover workflow analysis,
+    code-scanning publication, and dependency policy. `dependency-review`
+    rejects high or critical vulnerable dependencies and dependencies outside
+    the configured license policy. `pr-title` enforces the one-ticket
+    Conventional Commit identity at review time.
 - Enable GitHub Secret Scanning and push protection for supported secret
   patterns. Treat them as required merge-prevention controls, not as a
   replacement for review or safe configuration design.
@@ -58,13 +60,22 @@ state. Maintainers should verify them with the GitHub UI or
 `make github-governance-check` before publication review, and attach the output
 when repository settings are accessible.
 
+`make required-checks-verify` validates the manifest schema, canonical workflow
+paths, explicit workflow job names, owners, release classification, and unique
+check identities. It runs through `docs-check` and `release-check`; changing a
+required job ID or displayed job name therefore requires a matching manifest
+change. Release evidence records the verifier and required mutation gate as
+ordinary release-check results.
+
 Maintainers can run the optional authenticated verifier with
 `make github-governance-check`. The command uses `gh api` when available to
-check branch protection, required status checks, the sole-maintainer PR and
-no-bypass rulesets, CodeQL merge protection, force-push/deletion protection,
-and tag rulesets for both `refs/tags/v*` and `refs/tags/contrib/v*`. It skips
-cleanly when `gh` is not installed or authenticated, and it is not part of `finalize`
-or required PR CI.
+compare the manifest with the exact strict, app-bound branch-protection set and
+to check the sole-maintainer PR and no-bypass rulesets, CodeQL merge protection,
+force-push/deletion protection, and tag rulesets for both `refs/tags/v*` and
+`refs/tags/contrib/v*`. It skips cleanly only when `gh` is absent or
+unauthenticated; an authenticated API failure, malformed response, missing
+check, stale check, or wrong App binding fails closed. The authenticated command
+is not part of `finalize` or required PR CI.
 
 ## PR Review Discipline
 

@@ -81,6 +81,17 @@ source of truth is `docs/release-runbook.md`.
   policy does not claim macOS amd64 or Windows arm64 without matching required
   workflow evidence.
 
+### Stable required quality-gate identities
+
+- `docs/required-checks.json` now records every protected pull-request check,
+  its GitHub App binding, workflow/job identity, owner, and PR/release role.
+- Workflow jobs have explicit displayed names, and local documentation plus
+  release gates fail when a job identity drifts from the manifest.
+- The authenticated governance audit compares branch protection with the exact
+  manifest set and fails on missing, stale, unbound, or wrong-App checks.
+- Release evidence now records required-check manifest verification and the
+  blocking mutation gate as named results.
+
 ### Real Redis contract foundation
 
 - `make test-redis` now provides an isolated Redis 7 harness and real-service

@@ -134,7 +134,8 @@ after the final stable `vX.Y.0` release is published.
 | `GOTOOLCHAIN=local make reference-service-coverage` | Optional checked-in reference service coverage diagnostic. | Writes `.ci-result/coverage/reference-service.func` and `.ci-result/coverage/reference-service-summary.md` without folding generated app code into root/contrib aggregate coverage thresholds. Not part of `finalize`. |
 | `GOTOOLCHAIN=local make reference-service-load` | Optional checked-in reference service load-smoke baseline. | Runs the reference-service router in-process, writes `.ci-result/reference-service-load/status`, `summary.json`, `summary.md`, and `load-smoke.log`, and records latency, throughput, memory, allocations, and expected missing-API-key failure behavior. Not part of `finalize`. |
 | `GOTOOLCHAIN=local make reference-service-evidence` | Optional recorded reference service evidence. | Runs `reference-service-check`, writes `.ci-result/reference-service/status`, `.ci-result/reference-service/summary.json`, and logs. Set `REFERENCE_SERVICE_DOCKER=1` to also run the service-owned Docker `integration-check`; set `REFERENCE_SERVICE_MINIO=1` only when object-storage integration evidence is in scope. Not part of `finalize`. |
-| `make github-governance-check` | Optional authenticated GitHub repository settings verification. | Uses `gh api` to verify branch protection, required checks, the sole-maintainer PR/no-bypass rulesets, CodeQL merge protection, force-push/deletion protection, and root `v*` plus contrib `contrib/v*` tag rulesets when `gh` is installed and authenticated; skips cleanly otherwise. |
+| `make required-checks-verify` | Local required-check identity contract. | Validates `docs/required-checks.json` against explicit workflow job IDs and names. It is part of `docs-check` and `release-check`, so release evidence records its result. |
+| `make github-governance-check` | Optional authenticated GitHub repository settings verification. | Uses `gh api` to compare the manifest with the exact strict, app-bound branch-protection set and verify the sole-maintainer PR/no-bypass rulesets, CodeQL merge protection, force-push/deletion protection, and root `v*` plus contrib `contrib/v*` tag rulesets. It skips when `gh` is absent or unauthenticated and fails closed after authentication. |
 | `RELEASE_TAG=vX.Y.Z GOTOOLCHAIN=local make release-tag-consistency-check` | Paired root/contrib release identity gate. | Fails if matching root/contrib tags, branch ancestry, module-major paths, changelog, release notes, support policy, or the release-workflow baseline are incoherent. |
 | `RELEASE_TAG=vX.Y.Z API_BASE_REF=v4.0.1 GOTOOLCHAIN=local make release-evidence` | Clean-tree tag-binding preflight. | Requires the supported tag to point at `HEAD` and records tag/commit/tree/default-branch/module identity in `release-check-summary.json` schema v2, plus checks and retained logs. Local evidence is useful preflight only; the tag-driven GitHub workflow is the trusted publication producer. |
 | `ALLOW_DIRTY_RELEASE_EVIDENCE=1 API_BASE_REF=v4.0.1 GOTOOLCHAIN=local make release-evidence` | Local dirty-tree audit evidence. | Writes the same evidence files but records `publication_eligible=false` and `provenance_policy.mode=local_audit`; not acceptable before publishing. |
@@ -242,6 +243,9 @@ Local release evidence is the developer/auditor tier. It contains:
 
 - `release-check-summary.json` schema v2.
 - One check record per `make release-check` subtarget.
+- Required-check manifest verification and the blocking mutation result are
+  retained as named check records, so release reviewers can see whether stable
+  workflow identities and the assertion-sensitive gate passed.
 - Command lines, exit codes, durations, log availability, log paths, tool
   versions, commit, branch or detached state, dirty flag, staged/unstaged/
   untracked/deleted counts, and `API_BASE_REF`.