Implement M44: Auditability and documentation hardening

1. Fix documentation count drift: single source-of-truth test-counts.json
   (Go 399, Python 718, total 1117), CI test-count-check job that fails if
   documented counts drift below actual, updated test-matrix.md and README
   with exact counts.

2. CI evidence easier to verify: Verification & Audit section in README
   with direct links to CI/build/release workflows, M5 control matrix,
   supply-chain provenance doc; GitHub Actions CI and Build badges.

3. M4/M5 terminology disambiguation: renamed all roadmap entries from
   "M0..M43" to "Milestone 0..Milestone 43", created glossary.md
   distinguishing project milestones vs M5 security assurance level vs
   acceptance criteria.

4. M5 evidence chain explicit: added "Operator Verification" column to
   all 26 controls in m5-control-matrix.md, created audit-quick-path.md
   (run tests, inspect logs, verify artifacts, confirm system states).

5. Recovery path proven: created recovery-runbook.md with degradation
   triggers, containment latch behavior, acknowledgment/re-attestation
   procedures, return-to-trusted ceremony, forensic export, severity
   escalation reference (all with concrete curl commands).

6. Supply-chain verification tightened: created verify-release.sh auditor
   script (cosign verify, SBOM attestation, SLSA provenance, checksums),
   created sample-release-bundle.md documenting release artifact structure.

7. Status page restructured: split security-status.md into "Security
   Assurance Controls (M5 Complete)" and "Product Feature Roadmap",
   clarified Agent Mode Phase 2/3 are not M5 blockers.

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

Author: SecAI-Hub

.github/scripts/check-test-counts.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+###############################################################################
+# check-test-counts.sh — Detect test-count drift against docs/test-counts.json
+#
+# Exits non-zero if any per-service count is LOWER than the documented count.
+# Counts that EXCEED the documented value are fine (docs just need updating).
+###############################################################################
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+COUNTS_FILE="${REPO_ROOT}/docs/test-counts.json"
+
+if [[ ! -f "${COUNTS_FILE}" ]]; then
+  echo "FATAL: ${COUNTS_FILE} not found."
+  exit 1
+fi
+
+# JSON helper — Python is already set up in CI.
+read_json() {
+  python3 -c "import json,sys; d=json.load(open('${COUNTS_FILE}')); print(d$1)"
+}
+
+###############################################################################
+# 1. Count Go tests per service
+###############################################################################
+
+GO_SERVICES="airlock registry tool-firewall gpu-integrity-watch mcp-firewall policy-engine runtime-attestor integrity-monitor incident-recorder"
+
+go_total_actual=0
+drift_found=0
+
+echo "=============================================="
+echo "  Test-Count Drift Check"
+echo "=============================================="
+echo ""
+echo "--- Go services ---"
+
+# Store results in temp files (bash 3 compatible, no associative arrays)
+results_dir=$(mktemp -d)
+trap 'rm -rf "${results_dir}"' EXIT
+
+for svc in ${GO_SERVICES}; do
+  svc_dir="${REPO_ROOT}/services/${svc}"
+  if [[ ! -d "${svc_dir}" ]]; then
+    echo "WARNING: services/${svc} directory not found, skipping."
+    echo "0" > "${results_dir}/${svc}.actual"
+  else
+    count=$(cd "${svc_dir}" && go test -v -count=1 ./... 2>&1 | grep -c "^--- PASS" || true)
+    echo "${count}" > "${results_dir}/${svc}.actual"
+    go_total_actual=$((go_total_actual + count))
+  fi
+
+  expected=$(read_json "['go']['${svc}']" 2>/dev/null || echo 0)
+  echo "${expected}" > "${results_dir}/${svc}.expected"
+done
+
+###############################################################################
+# 2. Count Python tests
+###############################################################################
+
+echo "--- Python tests ---"
+
+python_actual=$(cd "${REPO_ROOT}" && \
+  PYTHONPATH=services python3 -m pytest tests/ --co -q 2>&1 | tail -1 | \
+  grep -oE '^[0-9]+' || echo 0)
+
+python_expected=$(read_json "['python_total']" 2>/dev/null || echo 0)
+
+###############################################################################
+# 3. Compute totals
+###############################################################################
+
+go_total_expected=$(read_json "['go_total']" 2>/dev/null || echo 0)
+grand_expected=$(read_json "['grand_total']" 2>/dev/null || echo 0)
+grand_actual=$((go_total_actual + python_actual))
+
+###############################################################################
+# 4. Print summary table
+###############################################################################
+
+echo ""
+echo "=============================================="
+printf "  %-22s %8s %8s %8s\n" "Component" "Expected" "Actual" "Status"
+echo "----------------------------------------------"
+
+for svc in ${GO_SERVICES}; do
+  exp=$(cat "${results_dir}/${svc}.expected")
+  act=$(cat "${results_dir}/${svc}.actual")
+  if [ "${act}" -lt "${exp}" ]; then
+    status="DRIFT!"
+    drift_found=1
+  elif [ "${act}" -gt "${exp}" ]; then
+    status="ABOVE (update docs)"
+  else
+    status="OK"
+  fi
+  printf "  %-22s %8d %8d   %s\n" "go/${svc}" "${exp}" "${act}" "${status}"
+done
+
+# Python row
+if [ "${python_actual}" -lt "${python_expected}" ]; then
+  py_status="DRIFT!"
+  drift_found=1
+elif [ "${python_actual}" -gt "${python_expected}" ]; then
+  py_status="ABOVE (update docs)"
+else
+  py_status="OK"
+fi
+printf "  %-22s %8d %8d   %s\n" "python" "${python_expected}" "${python_actual}" "${py_status}"
+
+echo "----------------------------------------------"
+printf "  %-22s %8d %8d\n" "Go subtotal" "${go_total_expected}" "${go_total_actual}"
+printf "  %-22s %8d %8d\n" "Python subtotal" "${python_expected}" "${python_actual}"
+printf "  %-22s %8d %8d\n" "Grand total" "${grand_expected}" "${grand_actual}"
+echo "=============================================="
+echo ""
+
+###############################################################################
+# 5. Exit with appropriate code
+###############################################################################
+
+if [ "${drift_found}" -eq 1 ]; then
+  echo "FAIL: One or more test counts drifted DOWN from documented values."
+  echo "      This means tests were removed or broken without updating docs/test-counts.json."
+  exit 1
+else
+  echo "PASS: All test counts meet or exceed documented values."
+  if [ "${grand_actual}" -gt "${grand_expected}" ]; then
+    echo "NOTE: Grand total exceeds documented count (${grand_actual} > ${grand_expected})."
+    echo "      Consider updating docs/test-counts.json to reflect the new counts."
+  fi
+  exit 0
+fi

.github/workflows/ci.yml

@@ -236,3 +236,25 @@ jobs:
       - name: Run incident-recorder recovery tests
         working-directory: services/incident-recorder
         run: go test -v -race -run "TestRecovery|TestEscalation|TestForensic|TestLatched" ./...
+
+  test-count-check:
+    name: Test Count Drift Check
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0
+        with:
+          go-version: "1.23"
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Install Python dependencies
+        run: pip install pyyaml flask requests pytest
+
+      - name: Check test counts for drift
+        run: bash .github/scripts/check-test-counts.sh

README.md

@@ -1,6 +1,7 @@
 # SecAI OS
 
 [![CI](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/ci.yml/badge.svg)](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/ci.yml)
+[![Build](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/build.yml/badge.svg)](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/build.yml)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 [![Fedora 42](https://img.shields.io/badge/Fedora-42-blue)](https://fedoraproject.org/)
 [![uBlue](https://img.shields.io/badge/Built_on-uBlue-purple)](https://universal-blue.org/)
@@ -150,7 +151,7 @@ Every model passes through the same fully automatic pipeline:
 | **Updates** | Cosign-verified rpm-ostree, staged workflow, greenboot auto-rollback |
 | **Supply Chain** | Per-service CycloneDX SBOMs, SLSA3 provenance attestation, cosign-signed checksums |
 
-See [docs/threat-model.md](docs/threat-model.md) for threat classes, residual risks, and security invariants. See [docs/security-status.md](docs/security-status.md) for implementation status of all 43 milestones.
+See [docs/threat-model.md](docs/threat-model.md) for threat classes, residual risks, and security invariants. See [docs/security-status.md](docs/security-status.md) for implementation status of all 44 milestones.
 
 ### Verify Image Signatures
 
@@ -192,6 +193,34 @@ See [docs/policy-schema.md](docs/policy-schema.md) for full schema reference. Se
 
 ---
 
+## Verification & Audit
+
+### Workflow Files
+
+- [CI Workflow](.github/workflows/ci.yml)
+- [Build Workflow](.github/workflows/build.yml)
+- [Release Workflow](.github/workflows/release.yml)
+
+### Security Documentation
+
+- [M5 Control Matrix](docs/m5-control-matrix.md)
+- [Supply Chain Provenance](docs/supply-chain-provenance.md)
+- [Security Status](docs/security-status.md)
+
+### CI Verification Evidence
+
+Each CI job produces specific security evidence:
+
+| Job | What It Proves |
+|-----|---------------|
+| `security-regression` | Adversarial test suite: prompt injection, policy bypass, containment |
+| `supply-chain-verify` | SBOM generation via Syft, cosign availability, provenance keywords |
+| `go-build-and-test` | 399 Go tests across 9 services with `-race` |
+| `python-test` | 718 Python tests (agent, adversarial, M5 acceptance, UI, pipeline) |
+| `test-count-check` | Prevents documented test counts from drifting below actual |
+
+---
+
 ## Documentation
 
 | Document | Description |
@@ -200,8 +229,8 @@ See [docs/policy-schema.md](docs/policy-schema.md) for full schema reference. Se
 | [Threat Model](docs/threat-model.md) | Threat classes, invariants, residual risks |
 | [API Reference](docs/api.md) | HTTP API for all services |
 | [Policy Schema](docs/policy-schema.md) | Full policy.yaml schema reference |
-| [Security Status](docs/security-status.md) | Implementation status of all 43 milestones |
-| [Test Matrix](docs/test-matrix.md) | Test coverage: 1000+ tests across Go, Python, shell |
+| [Security Status](docs/security-status.md) | Implementation status of all 44 milestones |
+| [Test Matrix](docs/test-matrix.md) | Test coverage: 1,117 tests across Go and Python (see [test-counts.json](docs/test-counts.json)) |
 | [Compatibility Matrix](docs/compatibility-matrix.md) | GPU, VM, and hardware support |
 | [Security Test Matrix](docs/security-test-matrix.md) | Security feature test coverage |
 | [FAQ](docs/faq.md) | Common questions |
@@ -226,6 +255,9 @@ See [docs/policy-schema.md](docs/policy-schema.md) for full schema reference. Se
 | [Incident Recorder](docs/components/incident-recorder.md) | Security event capture and auto-containment |
 | [M5 Control Matrix](docs/m5-control-matrix.md) | M5 acceptance criteria, enforcement paths, operator verification |
 | [Supply Chain Provenance](docs/supply-chain-provenance.md) | Provenance pipeline, SBOM coverage, key material |
+| [Audit Quick Path](docs/audit-quick-path.md) | External auditor step-by-step verification guide |
+| [Recovery Runbook](docs/recovery-runbook.md) | Operator procedures for degradation, containment, and recovery |
+| [Sample Release Bundle](docs/sample-release-bundle.md) | Release artifact structure and verification commands |
 
 ### Install Guides
 
@@ -308,13 +340,13 @@ Privacy: Tor-routed, PII stripped, injection detection, privacy-preserving query
 ## Running Tests
 
 ```bash
-# Go tests (348 total across 9 services)
+# Go tests (399 total across 9 services)
 for svc in airlock registry tool-firewall gpu-integrity-watch mcp-firewall \
            policy-engine runtime-attestor integrity-monitor incident-recorder; do
   (cd services/$svc && go test -v -race ./...)
 done
 
-# Python tests (658 total)
+# Python tests (718 total)
 pip install pytest flask requests pyyaml
 python -m pytest tests/ -v
 
@@ -329,52 +361,53 @@ See [docs/test-matrix.md](docs/test-matrix.md) for full breakdown.
 ## Roadmap
 
 <details>
-<summary>All 43 milestones (click to expand)</summary>
-
-- [x] **M0** -- Threat model, dataflow, invariants, policy files
-- [x] **M1** -- Bootable OS, encrypted vault, GPU drivers
-- [x] **M2** -- Trusted Registry, hash pinning, cosign verification
-- [x] **M3** -- 7-stage quarantine pipeline
-- [x] **M4** -- Tool Firewall, default-deny policy
-- [x] **M5** -- Online Airlock, sanitization
-- [x] **M6** -- Systemd sandboxing, kernel hardening, nftables
-- [x] **M7** -- CI/CD, Go/Python tests, shellcheck
-- [x] **M8** -- Image/video generation, diffusion worker
-- [x] **M9** -- Multi-GPU support (NVIDIA/AMD/Intel/Apple)
-- [x] **M10** -- Tor-routed search, SearXNG, PII stripping
-- [x] **M11** -- VM support, OVA/QCOW2 builds
-- [x] **M12** -- Model integrity monitoring
-- [x] **M13** -- Tamper-evident audit logs
-- [x] **M14** -- Local passphrase auth
-- [x] **M15** -- Vault auto-lock
-- [x] **M16** -- Seccomp-BPF + Landlock process isolation
-- [x] **M17** -- Secure Boot + TPM2 measured boot
-- [x] **M18** -- Memory protection (swap/zswap/core dumps/mlock/TEE)
-- [x] **M19** -- Traffic analysis protection
-- [x] **M20** -- Privacy-preserving query obfuscation for search
-- [x] **M21** -- Clipboard isolation
-- [x] **M22** -- Canary/tripwire system
-- [x] **M23** -- Emergency wipe (3-level panic)
-- [x] **M24** -- Update verification + auto-rollback
-- [x] **M25** -- UI polish + security hardening
-- [x] **M26** -- Fail-closed pipeline, service auth, CSRF, supply chain pinning
-- [x] **M27** -- Enhanced scanners, provenance manifests, fs-verity
-- [x] **M28** -- Weight distribution fingerprinting
-- [x] **M29** -- Garak LLM vulnerability scanner
-- [x] **M30** -- gguf-guard deep GGUF integrity scanner
-- [x] **M31** -- Agent Mode (Phase 1: safe local autopilot)
-- [x] **M32** -- GPU Integrity Watch (continuous GPU runtime verification)
-- [x] **M33** -- MCP Firewall (Model Context Protocol policy gateway)
-- [x] **M34** -- Release provenance + per-service SBOMs (SLSA3, CycloneDX, cosign)
-- [x] **M35** -- Unified policy decision engine (6 domains, OPA/Rego-upgradeable)
-- [x] **M36** -- Runtime attestation + startup gating (TPM2, HMAC state bundles)
-- [x] **M37** -- Continuous integrity monitor (baseline-verified file watcher)
-- [x] **M38** -- Incident recorder + containment automation (9 classes, 4-state lifecycle)
-- [x] **M39** -- GPU integrity deep integration (driver fingerprinting, attestor/incident wiring)
-- [x] **M40** -- Agent verified supervisor hardening (signed tokens, replay protection, two-phase approval)
-- [x] **M41** -- HSM-backed key handling (pluggable keystore: software/TPM2/PKCS#11)
-- [x] **M42** -- Enforcement wiring + CI supply chain verification
-- [x] **M43** -- Stronger isolation: sandbox tightening, adversarial tests, CI security regression, MCP isolation, recovery ceremonies, M5 acceptance suite
+<summary>All 44 project milestones (click to expand)</summary>
+
+- [x] **Milestone 0** -- Threat model, dataflow, invariants, policy files
+- [x] **Milestone 1** -- Bootable OS, encrypted vault, GPU drivers
+- [x] **Milestone 2** -- Trusted Registry, hash pinning, cosign verification
+- [x] **Milestone 3** -- 7-stage quarantine pipeline
+- [x] **Milestone 4** -- Tool Firewall, default-deny policy
+- [x] **Milestone 5** -- Online Airlock, sanitization
+- [x] **Milestone 6** -- Systemd sandboxing, kernel hardening, nftables
+- [x] **Milestone 7** -- CI/CD, Go/Python tests, shellcheck
+- [x] **Milestone 8** -- Image/video generation, diffusion worker
+- [x] **Milestone 9** -- Multi-GPU support (NVIDIA/AMD/Intel/Apple)
+- [x] **Milestone 10** -- Tor-routed search, SearXNG, PII stripping
+- [x] **Milestone 11** -- VM support, OVA/QCOW2 builds
+- [x] **Milestone 12** -- Model integrity monitoring
+- [x] **Milestone 13** -- Tamper-evident audit logs
+- [x] **Milestone 14** -- Local passphrase auth
+- [x] **Milestone 15** -- Vault auto-lock
+- [x] **Milestone 16** -- Seccomp-BPF + Landlock process isolation
+- [x] **Milestone 17** -- Secure Boot + TPM2 measured boot
+- [x] **Milestone 18** -- Memory protection (swap/zswap/core dumps/mlock/TEE)
+- [x] **Milestone 19** -- Traffic analysis protection
+- [x] **Milestone 20** -- Privacy-preserving query obfuscation for search
+- [x] **Milestone 21** -- Clipboard isolation
+- [x] **Milestone 22** -- Canary/tripwire system
+- [x] **Milestone 23** -- Emergency wipe (3-level panic)
+- [x] **Milestone 24** -- Update verification + auto-rollback
+- [x] **Milestone 25** -- UI polish + security hardening
+- [x] **Milestone 26** -- Fail-closed pipeline, service auth, CSRF, supply chain pinning
+- [x] **Milestone 27** -- Enhanced scanners, provenance manifests, fs-verity
+- [x] **Milestone 28** -- Weight distribution fingerprinting
+- [x] **Milestone 29** -- Garak LLM vulnerability scanner
+- [x] **Milestone 30** -- gguf-guard deep GGUF integrity scanner
+- [x] **Milestone 31** -- Agent Mode (Phase 1: safe local autopilot)
+- [x] **Milestone 32** -- GPU Integrity Watch (continuous GPU runtime verification)
+- [x] **Milestone 33** -- MCP Firewall (Model Context Protocol policy gateway)
+- [x] **Milestone 34** -- Release provenance + per-service SBOMs (SLSA3, CycloneDX, cosign)
+- [x] **Milestone 35** -- Unified policy decision engine (6 domains, OPA/Rego-upgradeable)
+- [x] **Milestone 36** -- Runtime attestation + startup gating (TPM2, HMAC state bundles)
+- [x] **Milestone 37** -- Continuous integrity monitor (baseline-verified file watcher)
+- [x] **Milestone 38** -- Incident recorder + containment automation (9 classes, 4-state lifecycle)
+- [x] **Milestone 39** -- GPU integrity deep integration (driver fingerprinting, attestor/incident wiring)
+- [x] **Milestone 40** -- Agent verified supervisor hardening (signed tokens, replay protection, two-phase approval)
+- [x] **Milestone 41** -- HSM-backed key handling (pluggable keystore: software/TPM2/PKCS#11)
+- [x] **Milestone 42** -- Enforcement wiring + CI supply chain verification
+- [x] **Milestone 43** -- Stronger isolation: sandbox tightening, adversarial tests, CI security regression, MCP isolation, recovery ceremonies, M5 acceptance suite
+- [x] **Milestone 44** -- Auditability and documentation hardening: test-count drift CI check, CI evidence links and badges, M4/M5 terminology disambiguation, audit quick-path doc, recovery runbook, verify-release script, security/product roadmap split
 
 </details>
 
@@ -406,7 +439,7 @@ services/
   search-mediator/          Python -- Tor-routed web search (:8485)
   ui/                       Python/Flask -- Web UI (:8480)
   common/                   Python -- Shared utilities (audit, auth, mlock)
-tests/                      658 Python tests, 348 Go tests (~1006 total)
+tests/                      718 Python tests, 399 Go tests (1,117 total)
 docs/                       Architecture, API, threat model, install guides
 schemas/                    OpenAPI spec, JSON Schema for config files
 examples/                   Task-oriented walkthroughs