docs: add ABI contract validation gate

Author: t81dev

README.md

@@ -234,6 +234,7 @@ See `examples/` for demo programs covering basic usage, calculator-style logic,
 - `SPECIFICATION.md` documents the helper ABI, ISA mnemonics, and execution model.
 - `ROADMAP.md` sketches future work (CI, ABI stability, runtime verification).
 - `ENCODING.md` details the tryte-level encoding for the ISA.
+- `docs/abi-contract-validation.md` defines ABI drift policy and the reproducible validation command.
 - Run `./make_release.sh` to build a tarball release with headers and plugin artifacts.
 
 ## Contributing

docs/README.md

@@ -8,3 +8,4 @@ The repository README now lives at [`../README.md`](../README.md) so that visito
 - [docs/MASTER_ISA.md](MASTER_ISA.md)
 - [docs/ENCODING.md](ENCODING.md)
 - [`docs/examples.md`](examples.md) (guided sample programs + instructions to run `tools/quickstart.sh`)
+- [`docs/abi-contract-validation.md`](abi-contract-validation.md) (ABI drift policy + reproducible validation flow)

docs/abi-contract-validation.md

@@ -0,0 +1,45 @@
+# ABI Contract Validation
+
+Roadmap linkage:
+- `t81-roadmap#2`
+- `t81-roadmap/PHASE1_STABILIZATION_MATRIX.md` (`P1-S3`)
+
+This document defines the ABI contract validation path for `ternary_gcc_plugin`.
+
+## Contract Scope
+
+The ABI contract is the union of:
+
+1. exported helper declarations in `include/ternary_runtime.h`,
+2. helper implementation coverage in `runtime/ternary_runtime.c`,
+3. helper symbol documentation in `README.md` and `docs/SPECIFICATION.md`.
+
+## Drift Policy
+
+Any change to helper declarations (add/remove/rename/signature change) must include:
+
+1. header updates (`include/ternary_runtime.h` and related helper headers),
+2. runtime implementation updates,
+3. documentation updates (`README.md`, `docs/SPECIFICATION.md`, and this page if process changes),
+4. successful ABI validation run via `scripts/validate_abi_contract.sh`.
+
+## Reproducible Validation
+
+Run:
+
+```bash
+scripts/validate_abi_contract.sh
+```
+
+This command performs:
+
+1. helper-doc parity check (`tools/check_helper_docs.py`),
+2. compile/link smoke checks against runtime ABI (`tests/test_abi.c`, `tests/test_varargs.c`),
+3. execution of those ABI smoke binaries.
+
+## Escalation Rule
+
+If ABI drift impacts downstream ecosystem contracts, link follow-up work in:
+
+1. `t81-roadmap` Phase 1 tracker,
+2. downstream consumers (`t81-lang`, `t81-python`) when relevant.

scripts/validate_abi_contract.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+BUILD_DIR="${BUILD_DIR:-$ROOT_DIR/build/abi-contract}"
+CC_BIN="${CC:-cc}"
+
+mkdir -p "$BUILD_DIR"
+
+echo "[abi] helper documentation parity"
+python3 "$ROOT_DIR/tools/check_helper_docs.py"
+
+echo "[abi] compiling runtime and smoke tests with ${CC_BIN}"
+"$CC_BIN" -std=c11 -I"$ROOT_DIR/include" -c "$ROOT_DIR/runtime/ternary_runtime.c" -o "$BUILD_DIR/ternary_runtime.o"
+"$CC_BIN" -std=c11 -I"$ROOT_DIR/include" "$ROOT_DIR/tests/test_abi.c" "$BUILD_DIR/ternary_runtime.o" -o "$BUILD_DIR/test_abi"
+"$CC_BIN" -std=c11 -I"$ROOT_DIR/include" "$ROOT_DIR/tests/test_varargs.c" "$BUILD_DIR/ternary_runtime.o" -o "$BUILD_DIR/test_varargs"
+
+echo "[abi] running smoke binaries"
+"$BUILD_DIR/test_abi"
+"$BUILD_DIR/test_varargs"
+
+echo "[abi] validation passed"