M53: Harder CI gates for production branches — release-gate job, CVE-ID govulncheck, docs consistency

Add release-branch-only hardened gate (zero-tolerance bandit, CVE-ID-level
govulncheck waivers, M5 acceptance re-verification), release preflight check
in release.yml, docs consistency checks (milestone count cross-check,
m5-control-matrix test reference verification, test-counts staleness warning),
container pin wiring, and branch protection documentation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: SecAI-Hub

.github/branch-protection.md

@@ -0,0 +1,118 @@
+# Branch Protection Rules
+
+Required branch protection settings for SecAI OS release infrastructure.
+Configure these in GitHub Settings > Branches > Add branch protection rule,
+or use the setup script below.
+
+Last updated: 2026-03-14
+
+---
+
+## `release/*` branches
+
+| Setting | Value |
+|---------|-------|
+| Require pull request before merging | Yes |
+| Required approvals | 1 |
+| Dismiss stale reviews | Yes |
+| Require status checks to pass | Yes |
+| Required status checks | See list below |
+| Require branches to be up to date | Yes |
+| Require signed commits | Recommended |
+| Allow force pushes | No |
+| Allow deletions | No |
+
+### Required status checks for `release/*`
+
+All 7 of these must pass before a PR can merge into a release branch:
+
+1. **Go Build & Test** (`go-build-and-test`) — Builds and tests all 9 Go services with race detector
+2. **Python Test & Lint** (`python-test`) — Ruff, bandit, mypy, unit/integration tests, adversarial + M5 acceptance
+3. **Security Regression Tests** (`security-regression`) — Adversarial tests (Python + Go MCP/policy/incident-recorder)
+4. **Dependency Vulnerability Audit** (`dependency-audit`) — govulncheck + pip-audit with waiver mechanism
+5. **Test Count Drift Check** (`test-count-check`) — Ensures test counts don't drop below documented floor
+6. **Documentation Validation** (`docs-validation`) — Broken links, required docs, milestone count consistency, test references
+7. **Release Branch Hardened Gate** (`release-gate`) — Zero-tolerance bandit, CVE-ID govulncheck waivers, M5 acceptance re-run
+
+The `release-gate` job has `needs:` on all of the above, so configuring it as the sole required check is sufficient.
+However, listing all 7 makes failure diagnosis easier in the GitHub UI.
+
+---
+
+## `stable` branch
+
+Same settings as `release/*`, plus:
+
+| Setting | Value |
+|---------|-------|
+| Restrict who can push | Maintainers only |
+| Require conversation resolution | Yes |
+
+---
+
+## What the release-gate adds over dev CI
+
+| Check | Dev CI (`main` / PRs) | Release branches |
+|-------|----------------------|------------------|
+| Bandit severity gate | HIGH severity + HIGH confidence | HIGH severity at **any** confidence |
+| Go vuln waiver matching | Count-based subtraction | CVE-ID matching (per-vulnerability) |
+| M5 acceptance suite | Runs in `python-test` | Re-runs in dedicated `release-gate` step |
+| Container pin check | Checked (since M53) | Same |
+| Docs consistency | Milestone counts + test refs (since M53) | Same |
+
+---
+
+## Setup Script
+
+Run from a machine with the `gh` CLI authenticated as a repository admin.
+
+**Note:** The GitHub API endpoint for branch protection rules with wildcard
+patterns (`release/*`) requires using rulesets. The script below uses the
+branch protection API for `stable` (exact name) and documents the UI steps
+for wildcard patterns.
+
+### For `stable` branch (exact match — API supported)
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+OWNER="SecAI-Hub"
+REPO="SecAI_OS"
+
+gh api -X PUT "repos/${OWNER}/${REPO}/branches/stable/protection" \
+  --input - <<'EOF'
+{
+  "required_status_checks": {
+    "strict": true,
+    "contexts": [],
+    "checks": [
+      {"context": "Go Build & Test"},
+      {"context": "Python Test & Lint"},
+      {"context": "Security Regression Tests"},
+      {"context": "Dependency Vulnerability Audit"},
+      {"context": "Test Count Drift Check"},
+      {"context": "Documentation Validation"},
+      {"context": "Release Branch Hardened Gate"}
+    ]
+  },
+  "enforce_admins": true,
+  "required_pull_request_reviews": {
+    "required_approving_review_count": 1,
+    "dismiss_stale_reviews": true
+  },
+  "restrictions": null,
+  "allow_force_pushes": false,
+  "allow_deletions": false
+}
+EOF
+echo "OK: Branch protection set for stable"
+```
+
+### For `release/*` branches (wildcard — use GitHub UI)
+
+1. Go to **Settings > Branches > Add branch protection rule**
+2. Branch name pattern: `release/*`
+3. Enable all settings listed in the table above
+4. Under "Require status checks to pass", add all 7 check names listed above
+5. Save changes

.github/scripts/govulncheck-strict.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# govulncheck-strict.sh — Release-branch govulncheck with CVE-ID-level waivers.
+#
+# Unlike the regular dependency-audit job (which subtracts waiver counts),
+# this matches by specific CVE ID — same approach as the Python pip-audit gate.
+# Only used by the release-gate job on release/* and stable branches.
+#
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+WAIVERS="${REPO_ROOT}/.github/vuln-waivers.json"
+GO_SERVICES="airlock registry tool-firewall gpu-integrity-watch mcp-firewall policy-engine runtime-attestor integrity-monitor incident-recorder"
+
+# Collect all vulnerability IDs across services
+FINDINGS_FILE=$(mktemp)
+trap 'rm -f "$FINDINGS_FILE"' EXIT
+
+for svc in ${GO_SERVICES}; do
+    echo "--- govulncheck: ${svc} ---"
+    OUTPUT_FILE=$(mktemp)
+    (cd "${REPO_ROOT}/services/${svc}" && govulncheck -json ./... > "$OUTPUT_FILE" 2>&1) || true
+
+    # Extract OSV/CVE IDs from govulncheck JSON stream
+    python3 -c "
+import json, sys
+ids = set()
+for line in open('${OUTPUT_FILE}'):
+    line = line.strip()
+    if not line:
+        continue
+    try:
+        obj = json.loads(line)
+    except json.JSONDecodeError:
+        continue
+    osv = obj.get('osv', {})
+    if osv:
+        vid = osv.get('id', '')
+        if vid:
+            ids.add(vid)
+        for a in osv.get('aliases', []):
+            ids.add(a)
+    finding = obj.get('finding', {})
+    if finding and finding.get('osv'):
+        ids.add(finding['osv'])
+for vid in sorted(ids):
+    print('${svc}:' + vid)
+" >> "$FINDINGS_FILE" 2>/dev/null || true
+
+    rm -f "$OUTPUT_FILE"
+done
+
+# Compare findings against waivers
+python3 -c "
+import json, sys, datetime
+
+with open('${WAIVERS}') as f:
+    waivers = json.load(f)
+today = datetime.date.today().isoformat()
+waived_ids = {w['id'] for w in waivers.get('go', []) if w.get('expires', '') >= today}
+
+unwaived = []
+with open('${FINDINGS_FILE}') as f:
+    for line in f:
+        line = line.strip()
+        if not line:
+            continue
+        svc, vid = line.split(':', 1)
+        if vid in waived_ids:
+            print(f'WAIVED: {svc} {vid}')
+        else:
+            print(f'::error::{svc}: {vid} — unwaived vulnerability')
+            unwaived.append(f'{svc}:{vid}')
+
+# Deduplicate (same CVE in multiple services)
+unique = set(v.split(':', 1)[1] for v in unwaived)
+if unique:
+    print(f'RELEASE GATE FAIL: {len(unique)} unwaived Go CVE(s) across {len(unwaived)} service finding(s)')
+    print('To waive, add CVE IDs to .github/vuln-waivers.json with reason + expiry.')
+    sys.exit(1)
+print(f'OK: Go strict vuln check passed ({len(waived_ids)} waiver(s) active)')
+"