docs: add phase-1 quantization hardening gate

Author: t81dev

README.md

@@ -207,6 +207,7 @@ See [docs/api-overview.md](docs/api-overview.md) for the full surface described
 - [docs/python-api.md](docs/python-api.md) & [docs/python-cookbook.md](docs/python-cookbook.md) — Python recipes.
 - [docs/torch.md](docs/torch.md) — PyTorch integration, `t81.torch`, and `t81.nn`.
 - [docs/references/cli-usage.md](docs/references/cli-usage.md) — CLI workflows for convert/gguf/qat.
+- [docs/quantization-hardening.md](docs/quantization-hardening.md) — Phase 1 hardening checklist and reproducible validation lanes.
 
 ### Specs & design
 

docs/index.md

@@ -68,6 +68,7 @@ From here: `t8.nn.Linear` for drop-in layers, `t8.convert`/`t8.gguf` for scripte
 - **GPU backends** — [`docs/gpu.md`](gpu.md) explains the CUDA/ROCm build flags and tensor metadata routing.
 - **API overview** — [`docs/api-overview.md`](api-overview.md) summarizes the numeric containers and helpers exposed via `<t81/t81lib.hpp>`.
 - **Tests & benchmarks** — [`tests/`](../tests/) documents the unit/property coverage while [`bench/`](../bench/) shows throughput patterns.
+- **Phase 1 hardening checklist** — [`docs/quantization-hardening.md`](quantization-hardening.md) defines the arithmetic/quantization stabilization gates and reproducible validation flow.
 - **Docs sitemap** — the [`docs/diagrams/docs-sitemap.mermaid.md`](diagrams/docs-sitemap.mermaid.md) mind map visualizes the content hierarchy referenced on this page.
 
 ## Stay aligned

docs/quantization-hardening.md

@@ -0,0 +1,49 @@
+# Quantization and Arithmetic Hardening
+
+Roadmap linkage:
+- `t81-roadmap#2`
+- `t81-roadmap/PHASE1_STABILIZATION_MATRIX.md` (`P1-S2`)
+
+This document is the Phase 1 hardening checklist for `t81lib`.
+
+## Hardening Checklist
+
+- [x] Define a reproducible core arithmetic validation lane (C++ build + unit tests).
+- [x] Define a reproducible quantization validation lane (Python tests with explicit deps).
+- [x] Add one command entry point that runs both lanes in a consistent order.
+- [x] Require changed quantization claims to include benchmark artifact references.
+- [x] Route contract-impacting changes back to roadmap tracking.
+
+## Reproducible Validation Paths
+
+### Lane A: Core arithmetic (required)
+
+Runs deterministic C++ checks through CMake/CTest:
+
+```bash
+scripts/validate_quantization_hardening.sh
+```
+
+### Lane B: Python quantization surface (optional but required for Python/API changes)
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install ".[torch]"
+scripts/validate_quantization_hardening.sh --with-python
+```
+
+## Benchmark Artifact Rule
+
+If a change alters quantization behavior or performance claims, include:
+
+1. Command used (for example `scripts/ternary_quantization_benchmark.py` args).
+2. Output artifact path (`benchmarks/*.csv` or `benchmarks/*.json`).
+3. Before/after summary in PR or issue notes.
+
+## Contract/Governance Rule
+
+When quantization behavior changes impact cross-repo assumptions, open or update linked tracking in:
+
+1. `t81-roadmap` (Phase 1 tracker),
+2. downstream contract consumers as needed (`t81-python`, `t81-lang`).

scripts/validate_quantization_hardening.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+BUILD_DIR="${BUILD_DIR:-build-hardening}"
+WITH_PYTHON=0
+FULL=0
+
+usage() {
+  cat <<'EOF'
+Usage: scripts/validate_quantization_hardening.sh [--with-python] [--full]
+
+Runs the Phase 1 hardening validation lanes for t81lib:
+  1) C++ arithmetic/core lane (required)
+  2) Python quantization lane (optional, enabled with --with-python)
+Default C++ lane excludes the long-running fuzz target (`bigint_bitops_fuzz`).
+Use --full to include it.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --with-python)
+      WITH_PYTHON=1
+      shift
+      ;;
+    --full)
+      FULL=1
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+echo "[hardening] lane A: C++ core arithmetic/tests"
+cmake -S "$ROOT_DIR" -B "$ROOT_DIR/$BUILD_DIR" -DT81LIB_BUILD_TESTS=ON
+cmake --build "$ROOT_DIR/$BUILD_DIR" --parallel
+if [[ "$FULL" -eq 1 ]]; then
+  ctest --test-dir "$ROOT_DIR/$BUILD_DIR" --output-on-failure
+else
+  ctest --test-dir "$ROOT_DIR/$BUILD_DIR" -E "bigint_bitops_fuzz" --output-on-failure
+fi
+
+if [[ "$WITH_PYTHON" -eq 1 ]]; then
+  echo "[hardening] lane B: Python quantization/tests"
+  if ! python3 -c "import numpy" >/dev/null 2>&1; then
+    echo "Missing numpy. Install Python deps first (for example: pip install \".[torch]\")." >&2
+    exit 1
+  fi
+  if ! python3 -c "import t81lib" >/dev/null 2>&1; then
+    echo "Missing importable t81lib module. Install package first (for example: pip install \".[torch]\")." >&2
+    exit 1
+  fi
+  (cd "$ROOT_DIR" && PYTHONPATH="$ROOT_DIR/python:$ROOT_DIR/src:${PYTHONPATH:-}" pytest -q tests/python/test_bindings.py tests/python/test_torch_ternary.py)
+fi
+
+echo "[hardening] all selected lanes passed"