chore: add conformance evidence tooling and release gates

.github/workflows/ci.yml

@@ -4,6 +4,9 @@ on:
   push:
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   test:
     runs-on: ubuntu-latest
@@ -29,6 +32,38 @@ jobs:
         run: |
           pytest -q
 
+  conformance:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev,image,pdf]"
+
+      - name: Generate conformance evidence
+        run: |
+          python scripts/conformance_report.py \
+            --report conformance_report.md \
+            --json conformance_report.json \
+            --matrix-report compat_matrix_report.md
+
+      - name: Upload conformance artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: conformance-evidence
+          path: |
+            conformance_report.md
+            conformance_report.json
+            compat_matrix_report.md
+
   quality:
     runs-on: ubuntu-latest
     needs: test
@@ -55,7 +90,7 @@ jobs:
 
   build:
     runs-on: ubuntu-latest
-    needs: quality
+    needs: [quality, conformance]
     steps:
       - uses: actions/checkout@v4
 

.github/workflows/release-gate.yml

@@ -0,0 +1,55 @@
+name: release-gate
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published, prereleased]
+
+permissions:
+  contents: read
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev,image,pdf]"
+          python -m pip install build twine
+
+      - name: Quality gates
+        run: |
+          pytest -q
+          ruff check .
+          mypy --strict aztec_py
+
+      - name: Conformance evidence
+        run: |
+          python scripts/conformance_report.py \
+            --report conformance_report.md \
+            --json conformance_report.json \
+            --matrix-report compat_matrix_report.md
+
+      - name: Build and verify artifacts
+        run: |
+          python -m build
+          twine check dist/*
+
+      - name: Upload release gate artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-gate-evidence
+          path: |
+            conformance_report.md
+            conformance_report.json
+            compat_matrix_report.md
+            dist/*

.gitignore

@@ -40,6 +40,9 @@ htmlcov/
 .coverage
 .coverage.*
 .cache
+compat_matrix_report.md
+conformance_report.md
+conformance_report.json
 nosetests.xml
 coverage.xml
 *,cover

MANIFEST.in

@@ -3,3 +3,4 @@ include requirements.txt
 include LICENSE
 include LICENSE.upstream
 include CONTRIBUTORS.md
+include docs/ISO_IEC_24778_TRACEABILITY.md

PRODUCTION_CHECKLIST.md

@@ -9,7 +9,9 @@ Use this checklist before shipping a new `aztec-py` version to production.
 - [ ] `python -m mypy --strict aztec_py`
 - [ ] `python -m build`
 - [ ] `python scripts/decoder_matrix.py --report compat_matrix_report.md`
+- [ ] `python scripts/conformance_report.py --report conformance_report.md --json conformance_report.json --matrix-report compat_matrix_report.md`
 - [ ] If decode runtime is available in CI: `python scripts/decoder_matrix.py --strict-decode`
+- [ ] `docs/ISO_IEC_24778_TRACEABILITY.md` reviewed and current
 
 ## 2. Runtime Optional Dependencies
 
@@ -42,5 +44,6 @@ Use this checklist before shipping a new `aztec-py` version to production.
 ## 6. Incident Guardrails
 
 - [ ] Keep compatibility fixture failures as release blockers.
+- [ ] Keep conformance report failures as release blockers.
 - [ ] Log scanner model/runtime for each production decode issue.
 - [ ] Add a regression fixture for every production bug before patching.

README.md

@@ -79,7 +79,17 @@ Use strict mode when decode checks are mandatory in CI:
 python scripts/decoder_matrix.py --strict-decode
 ```
 
+Generate full conformance evidence (markdown + JSON + compatibility matrix):
+
+```bash
+python scripts/conformance_report.py \
+  --report conformance_report.md \
+  --json conformance_report.json \
+  --matrix-report compat_matrix_report.md
+```
+
 Fixture source: `tests/compat/fixtures.json`
+Traceability matrix: `docs/ISO_IEC_24778_TRACEABILITY.md`
 Release checklist: `PRODUCTION_CHECKLIST.md`
 
 ## CLI

docs/ISO_IEC_24778_TRACEABILITY.md

@@ -0,0 +1,41 @@
+# ISO/IEC 24778 Traceability Matrix
+
+This document provides implementation traceability evidence for `aztec-py`.
+It is intended for audit support and release validation workflows.
+
+This matrix does not replace independent certification.
+
+## Scope
+
+- Encoder implementation: `aztec_py/core.py`
+- Symbol rendering: `aztec_py/renderers/*`
+- Validation fixtures and regression checks: `tests/*`, `tests/compat/fixtures.json`
+
+## Traceability Table
+
+| Requirement Area | Implementation Evidence | Automated Verification |
+|---|---|---|
+| Symbol layer/size selection and capacity fit checks | `aztec_py/core.py` (`find_suitable_matrix_size`, `_required_capacity_bits`) | `tests/test_core.py`, `tests/test_validation.py` |
+| Reed-Solomon error correction generation | `aztec_py/core.py` (`reed_solomon`) | `tests/test_core.py::Test::test_reed_solomon` |
+| Character mode/latch/shift sequencing | `aztec_py/core.py` (`find_optimal_sequence`, `optimal_sequence_to_bits`) | `tests/test_core.py::Test::test_find_optimal_sequence_*`, `tests/test_core.py::Test::test_optimal_sequence_to_bits` |
+| Bit stuffing and codeword construction | `aztec_py/core.py` (`get_data_codewords`) | `tests/test_core.py::Test::test_get_data_codewords` |
+| CRLF handling regression | `aztec_py/core.py` + fixture/test coverage | `tests/test_core.py::Test::test_crlf_encoding`, `tests/test_core.py::Test::test_crlf_roundtrip` |
+| Error-correction capacity regression (worst-case bytes) | `aztec_py/core.py` capacity calculations | `tests/test_core.py::Test::test_ec_worst_case_ff_bytes`, `tests/test_core.py::Test::test_ec_worst_case_null_bytes` |
+| GS1 payload composition and separators | `aztec_py/gs1.py` | `tests/test_gs1.py` |
+| Rendering determinism (PNG/SVG/PDF) | `aztec_py/core.py`, `aztec_py/renderers/image.py`, `aztec_py/renderers/svg.py` | `tests/test_renderers.py`, `tests/test_api_behaviour.py` |
+| CLI behavior and output contract | `aztec_py/__main__.py` | `tests/test_cli.py` |
+| Compatibility fixture corpus and decode matrix | `scripts/decoder_matrix.py`, `tests/compat/fixtures.json` | `tests/test_compat_matrix.py`, `scripts/conformance_report.py` |
+
+## Release Evidence Artifacts
+
+The following artifacts are generated and retained by CI/release gates:
+
+- `compat_matrix_report.md`
+- `conformance_report.md`
+- `conformance_report.json`
+
+## Audit Notes
+
+- Decode checks are runtime-dependent (`python-zxing` + Java).
+- Non-strict mode allows skip-safe evidence generation when decode backend is unavailable.
+- Strict mode can be enabled for environments where decode runtime is mandatory.