ci(gates): protect main with quality gates

.github/quality-gates.json

@@ -0,0 +1,45 @@
+{
+  "schema_version": 1,
+  "policy": {
+    "baseline_policy": "explicit-waiver-required",
+    "require_signed_commits": true,
+    "branch_protection": {
+      "protected_branches": [
+        "main"
+      ],
+      "require_pull_request": true,
+      "disallow_direct_pushes": true
+    },
+    "review_policy": {
+      "mode": "conditional-required",
+      "required_approvals": 1,
+      "exempt_repository_owner": true,
+      "exempt_author_permissions": [
+        "admin",
+        "maintain"
+      ],
+      "allowed_reviewer_permissions": [
+        "write",
+        "maintain",
+        "admin"
+      ],
+      "enforcement": {
+        "mode": "github-native",
+        "bypass_mode": "pull-request-only"
+      }
+    }
+  },
+  "required_checks": [
+    "Build"
+  ],
+  "informational_checks": [],
+  "waivers": [],
+  "expected_pr_workflows": [
+    {
+      "workflow": "Build",
+      "jobs": [
+        "Build"
+      ]
+    }
+  ]
+}

.github/workflows/build.yml

@@ -5,24 +5,26 @@ on:
     branches: [ "main" ]
   pull_request:
     branches: [ "main" ]
+  merge_group:
 
 env:
   CARGO_TERM_COLOR: always
 
 jobs:
   build:
+    name: Build
 
     runs-on: ubuntu-latest
 
     steps:
     - uses: actions/checkout@v3
-    - name: Build
+    - name: Build default features
       run: cargo build --verbose
     - name: Check documentation examples
       run: |
         # Check that documentation examples compile correctly
         # Skip actual doc tests due to embedded target configuration
         echo "Checking documentation examples compilation..."
         cargo check --verbose
-    - name: Build
-      run: cargo build --verbose --features async
+    - name: Build async feature
+      run: cargo build --verbose --features async

.github/workflows/release.yml

@@ -4,30 +4,40 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        description: "major/minor/patch or semver"
+        description: "Expected Cargo.toml version"
         required: false
-        default: "patch"
 
 concurrency: release-crate
 
+permissions:
+  contents: write
+
 jobs:
   publish:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-      - name: Set git credentials
+      - name: Verify requested version
+        id: crate
+        env:
+          EXPECTED_VERSION: ${{ github.event.inputs.version }}
         run: |
-          git config user.name github-actions
-          git config user.email github-actions@github.com
-      - name: Crates publish
-        uses: kaleidawave/crates-release-gh-action@main
-        id: release
-        with:
-          version: ${{ github.event.inputs.version }}
-          crates-token: ${{ secrets.CARGO_REGISTRY_TOKEN }}
-      - name: Push updated Cargo.toml
+          actual="$(
+            cargo metadata --no-deps --format-version 1 \
+              | python3 -c 'import json,sys; print(json.load(sys.stdin)["packages"][0]["version"])'
+          )"
+          if [ -n "${EXPECTED_VERSION}" ] && [ "${EXPECTED_VERSION}" != "${actual}" ]; then
+            echo "Expected version ${EXPECTED_VERSION}, but Cargo.toml declares ${actual}." >&2
+            exit 1
+          fi
+          echo "version=${actual}" >> "${GITHUB_OUTPUT}"
+      - name: Publish crate
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+        run: cargo publish --locked
+      - name: Push release tag
+        env:
+          version: ${{ steps.crate.outputs.version }}
         run: |
-          git add .
-          git commit -m "Release: ${{ steps.release.outputs.new-versions-description }}"
-          git tag "release/${{ steps.release.outputs.new-version }}"
-          git push --tags origin main
+          git tag "release/${version}"
+          git push origin "release/${version}"

README.md

@@ -221,6 +221,10 @@ where I2C::Error: core::fmt::Debug
 - `async`: Enables async/await support for non-blocking operations
 - `defmt`: Enables structured logging with defmt
 
+## Maintainer Quality Gates
+
+Changes to `main` must go through a pull request with the `Build` GitHub check passing. The repository-local quality gate contract is recorded in `.github/quality-gates.json`; GitHub branch protection should require the same `Build` check and block direct pushes to `main`, including release version updates.
+
 ## Hardware Support
 
 This driver is designed for the SW2303 USB PD controller. The SW2303 is a USB PD controller that supports:

docs/specs/README.md

@@ -0,0 +1,5 @@
+# Specs
+
+| ID | Topic | Status | Spec | Summary |
+| --- | --- | --- | --- | --- |
+| b7k2m | Repository quality gates | Active | [b7k2m-repo-quality-gates/SPEC.md](b7k2m-repo-quality-gates/SPEC.md) | Protect `main` with PR-only `Build` gate and signed commits. |

docs/specs/b7k2m-repo-quality-gates/HISTORY.md

@@ -0,0 +1,9 @@
+# History
+
+## Origin
+
+PR #1 merged while `main` had no GitHub branch protection and no repository rulesets. The repository needed a repo-local declaration plus GitHub-native enforcement so future merges cannot depend on operator memory.
+
+## Decision
+
+Use a single required check named `Build`, require pull requests for `main`, block direct pushes, and require signed commits. Keep `.github/quality-gates.json` as the source of truth and treat GitHub protection drift as a reportable failure.

docs/specs/b7k2m-repo-quality-gates/IMPLEMENTATION.md

@@ -0,0 +1,18 @@
+# Implementation
+
+## Current Shape
+
+- `.github/quality-gates.json` declares the repo-local gate contract for `main`.
+- `.github/workflows/build.yml` exposes a stable required check named `Build`.
+- `.github/workflows/release.yml` publishes the signed version already present on `main` and pushes only the release tag.
+- `README.md` documents the maintainer-facing quality gate.
+- GitHub branch protection is aligned to the declaration after the required check exists on the pull request.
+
+## Validation
+
+- Parse `.github/quality-gates.json` as JSON.
+- Run the style-playbook quality gate checker against the local declaration.
+- Run `cargo fmt -- --check`.
+- Run `cargo clippy --all-targets --all-features -- -D warnings`.
+- Run `cargo test`.
+- Verify GitHub protection state through `gh api` after remote alignment.

docs/specs/b7k2m-repo-quality-gates/SPEC.md

@@ -0,0 +1,32 @@
+# Repository Quality Gates
+
+Spec ID: b7k2m
+
+## Problem
+
+The default branch accepted PR #1 because GitHub reported no branch protection for `main` and no repository rulesets. The only completed status check was `build`, so GitHub had no required review, signed-commit, direct-push, or required-check policy to enforce.
+
+## Requirements
+
+- `main` is the protected default branch.
+- All changes to `main` enter through pull requests.
+- Direct pushes to `main` are blocked.
+- Signed commits are required for protected-branch changes.
+- The required GitHub status check is `Build`, declared repo-locally in `.github/quality-gates.json`.
+- The `Build` workflow supports `pull_request`, `push` to `main`, and `merge_group` events so branch protection and merge queue style checks can consume the same required context.
+- Native GitHub branch protection or rulesets enforce the declared policy. Workflow-only checks or README text do not count as enforcement.
+- Release automation must not push version metadata directly to `main`; protected-branch version updates enter through signed maintainer PRs before publishing.
+- Any intentional divergence between `.github/quality-gates.json` and GitHub protection state must be recorded as a waiver or reported as drift.
+
+## Non-Goals
+
+- This crate does not use PR label release intent. No `Label Gate` check is required until release intent is driven by PR labels.
+- This spec does not change Rust driver behavior or public API.
+
+## Acceptance
+
+- `.github/quality-gates.json` validates with the style-playbook quality gate checker.
+- GitHub branch protection for `main` requires PRs, blocks direct pushes, requires signed commits, and requires the `Build` check.
+- A PR changing the repository must show `Build` passing before merge.
+- The README points maintainers to the repo-local quality gate contract.
+- The release workflow publishes from the signed version already present on `main` and does not create protected-branch commits.