fix: Gram-consistent D2/D2b symmetrised gaps + 2026-07 audit hardening batch (#73)

* fix: Gram-consistent D2/D2b symmetrised gaps + audit hardening batch (property tests, CodeQL, repo-review fixes)

Physics fixes (2026-07 audit, all anchor-preserving — 21/21 anchors unchanged):
- alicki_adjoint: transpose the Kron rho factors so the pi-weighted adjoint
  is the true GNS-Gram adjoint G^-1 L G (G = rho.T (x) I, anchor B). Off the
  real-diagonal steady-state manifold the old construction returned
  unphysical NEGATIVE gns_gap (repro: Delta_s = -4.4 at Delta = 0.63).
- kms_gap: use the KMS-Gram adjoint (new gram_adjoint helper) instead of
  mixing the GNS adjoint with a KMS similarity transform.
- _real_gap_from_symmetric: deflate exactly one zero mode; additional
  Hermitian-part kernel vectors mean NO certified contraction (Delta_s = 0),
  filtering them over-certified the bound (Delta_s > Delta).
  Contraction bounds 0 <= Delta_s <= Delta verified on 40/40 random GKSL.
- sparse.chi1: remove double square root (certificate was K^(1/4), docs say
  K^(1/2)); pinned against the dense petermann_factors oracle.
- relaxation: failed bootstrap now yields (nan, nan) CI + RuntimeWarning
  instead of a silent zero-width interval (perfect-certainty failure mode).
- Robustness guards: steady_state integer-dtype cast, v4_thermal beta*omega
  guard, seed bool rejection, engineered_target_jumps zero-vector guard.

Quality/infra (best-practice research: SPEC 0/7/8, sp-repo-review, OpenSSF):
- New Hypothesis property-based suite (gap scaling, unitary similarity,
  trace-distance axioms + CPTP contractivity, semigroup law, Choi gate).
- New CodeQL SAST workflow (SHA-pinned, minimal permissions).
- pre-commit config (ruff, zizmor, cffconvert, hygiene hooks).
- pyproject strictness: pytest --strict-config/xfail_strict/filterwarnings=error,
  mypy warn_unreachable + extra error codes, build-requires cleanup.
- CI concurrency auto-cancel; pypi.yml release QA gate (twine check --strict +
  check-wheel-contents); scorecard publish_results for the public repo.

Docs: README layer table now uses the code-backed D-numbering; honest
qualification of the D21-D23 schema slots; manifest/seed claims corrected.

Semantics-changing classifier findings are tracked as issues #68-#72 for
dedicated PRs per AGENTS.md working agreement 3 (anchors are sacred).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XyiBg4VHjKnQ56kqJGFAN6

* fix(ci): allowlist QuTiP's matplotlib-absent import warning under filterwarnings=error

The new fail-loud filterwarnings=["error"] gate turned QuTiP's import-time
"matplotlib not found: Graphics will not work." UserWarning into a hard
error on every CI leg (the matrix installs .[dev,qutip] without the figures
extra; local runs had matplotlib installed, which is why this only surfaced
in CI). Graphics are irrelevant to the cross-checks — ignore exactly this
message, keep everything else erroring.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XyiBg4VHjKnQ56kqJGFAN6

* fix(ci): match ResolventConvergenceWarning by message, not class path

The class-based filterwarnings entry
(ignore::liouscope.numerics.resolvent.ResolventConvergenceWarning) forces
pytest to import liouscope at config time — BEFORE pytest-cov starts
measuring. coverage then reports module-not-measured for the whole package
and the total craters from ~94% to 74.55%, tripping --cov-fail-under=80 on
every matrix leg. Matching the warning by its message prefix needs no
import; verified locally: 403 passed, coverage 94.23%.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XyiBg4VHjKnQ56kqJGFAN6

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: marcohost33-maker

.github/workflows/ci-qutip.yml

@@ -18,6 +18,11 @@ on:
 
 permissions: {}
 
+# Auto-cancel superseded runs on the same ref; never cancel main-branch runs.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
 jobs:
   qutip-cross-check:
     runs-on: ubuntu-latest

.github/workflows/ci.yml

@@ -8,6 +8,12 @@ on:
 
 permissions: {}
 
+# Auto-cancel superseded runs on the same ref (saves matrix minutes on
+# rapid-fire pushes); never cancel main-branch runs.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
 jobs:
   test:
     runs-on: ${{ matrix.os }}

.github/workflows/codeql.yml

@@ -0,0 +1,49 @@
+# CodeQL — static application security testing (SAST) for the Python package.
+# Docs: https://docs.github.com/en/code-security/code-scanning
+#
+# Satisfies the OpenSSF Scorecard "SAST" check (ruff is a linter, not SAST).
+# Runs on PRs + main pushes + a weekly cron so newly added CodeQL queries
+# retroactively scan the existing code, not just new diffs.
+#
+# NOT branch-protection-required (Quality Workflow OS G6): it is path-relevant
+# to every PR, but keep it advisory until its signal/noise ratio on this
+# codebase is established.
+name: CodeQL
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+  schedule:
+    - cron: "22 5 * * 1"   # Mondays 05:22 UTC — offset from Scorecard/Dependabot
+
+permissions: {}
+
+jobs:
+  analyze:
+    name: CodeQL analyze (python)
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write   # upload CodeQL results to Code Scanning — required
+      contents: read           # checkout — required
+      actions: read            # workflow metadata for private-path resolution — required
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+        with:
+          persist-credentials: false
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@7211b7c8077ea37d8641b6271f6a365a22a5fbfa  # v4.36.0
+        with:
+          languages: python
+          # security-and-quality adds maintainability queries on top of the
+          # default security suite; scope stays src/ + packaged code.
+          queries: security-and-quality
+
+      - name: Perform CodeQL analysis
+        uses: github/codeql-action/analyze@7211b7c8077ea37d8641b6271f6a365a22a5fbfa  # v4.36.0
+        with:
+          category: "/language:python"

.github/workflows/pypi.yml

@@ -30,12 +30,18 @@ jobs:
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
         with:
           python-version: "3.12"
-      - name: Install build
+      - name: Install build + QA tools
         run: |
           python -m pip install --upgrade pip
-          pip install build
+          pip install build twine check-wheel-contents
       - name: Build sdist + wheel
         run: python -m build
+      - name: Release QA gate (fail-closed before upload)
+        # twine check --strict: long-description renders on PyPI, metadata sane.
+        # check-wheel-contents: no stray tests/.pyc/empty-wheel packaging bugs.
+        run: |
+          twine check --strict dist/*
+          check-wheel-contents dist/*.whl
       - name: Publish via Trusted Publishing
         uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14.0
         with:

.github/workflows/scorecard.yml

@@ -3,8 +3,9 @@
 #
 # Note: Scorecard requires read access to the GitHub GraphQL API. On private
 # repos without GitHub Advanced Security this fails with "Resource not
-# accessible by integration". We skip the job on private repos until the
-# repo is made public or GHAS is enabled.
+# accessible by integration"; the `if:` guard keeps the job skipped there.
+# This repo is PUBLIC (since 2026-06), so the job runs and results are
+# published to the Scorecard REST API (badge-capable).
 name: OpenSSF Scorecard
 
 on:
@@ -40,7 +41,9 @@ jobs:
         with:
           results_file: results.sarif
           results_format: sarif
-          publish_results: false
+          # Public repo: publish to the Scorecard REST API so the score is
+          # badge-capable and externally auditable (uses the job's id-token).
+          publish_results: true
 
       - name: Upload artifact
         if: ${{ !cancelled() && hashFiles('results.sarif') != '' }}

.pre-commit-config.yaml

@@ -0,0 +1,40 @@
+# pre-commit — fast local hygiene gates (mirror of the cheap CI checks).
+# Install once:  pip install pre-commit && pre-commit install
+# Run manually:  pre-commit run --all-files
+#
+# Deliberately NOT included: a code formatter (would churn the whole history;
+# adopt ruff-format in a dedicated PR if ever), mypy (needs the full numpy
+# environment — CI covers it), pytest (too slow for a commit hook).
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-yaml
+      - id: check-json
+      - id: check-toml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+      - id: detect-private-key
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.1
+    hooks:
+      - id: ruff-check
+        args: [src, tests, benchmarks]
+        pass_filenames: false
+
+  - repo: https://github.com/citation-file-format/cffconvert
+    rev: b6045d78aac9e02b039703b030588d54d53262ac  # 2.0.0
+    hooks:
+      - id: validate-cff
+
+  - repo: https://github.com/zizmorcore/zizmor-pre-commit
+    rev: v1.26.1
+    hooks:
+      - id: zizmor
+        args: [--persona=regular, --no-online-audits, .github/workflows]
+        pass_filenames: false

AGENTS.md

@@ -91,8 +91,11 @@ python examples/quickstart.py   # smoke run
 4. **SHA-pin all GitHub Actions.** Welle G established the gold-standard:
    every action reference is `@<full-sha>  # vX.Y.Z`. Dependabot is on a
    cooldown to avoid PR-spam.
-5. **Reproducibility.** Manifest seeds, library versions, lattice geometry
-   are recorded automatically; do not bypass the manifest writer.
+5. **Reproducibility.** The run manifest records seed, framework/schema/
+   taxonomy versions, Python/NumPy/SciPy versions, platform, solver path and a
+   run-invariant `input_hash` automatically; do not bypass the manifest writer.
+   (Lattice geometry / dissipator family are NOT yet manifest fields — do not
+   claim them; see MANIFEST_SCHEMA.json for the authoritative field list.)
 6. **Reality-Anchor.** Prefer "anchors pass (verified <date>)" over
    "diagnostics implemented". No claims without code-belege.
 7. **Plain paths in code-blocks** for file references (no markdown links —

CHANGELOG.md

@@ -7,6 +7,55 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [Unreleased]
 
 ### Fixed
+- **D2/D2b symmetrised gaps (`numerics.adjoint`, `diagnostics.spectral`) are
+  now genuine Gram-adjoint constructions** (2026-07 audit A1). Three coupled
+  defects were fixed:
+  - `alicki_adjoint` built the pi-weighted adjoint as
+    `(rho^-1 (x) I) L (rho (x) I)` while the GNS similarity transform used the
+    anchor-B Gram `G = rho.T (x) I`. The two coincide only for real-diagonal
+    steady states; off that manifold the "symmetrised" generator was not
+    G-Hermitian, its silent Hermitisation masked the defect, and `gns_gap()`
+    returned unphysical **negative** values (repro: generic d=3 GKSL with
+    steady-state coherences gave `Delta_s = -4.4` at `Delta = 0.63`). The Kron
+    factors are now transposed — i.e. exactly `G^{-1} L G`. No-op for the
+    real-diagonal anchor fixtures (all 21 anchors unchanged).
+  - `kms_gap` mixed pictures: it symmetrised with the *GNS* adjoint but
+    conjugated with the *KMS* Gram. It now uses the KMS-Gram adjoint via the
+    new `numerics.adjoint.gram_adjoint(L, G)` helper.
+  - Gap extraction (`_real_gap_from_symmetric`) now deflates exactly ONE
+    steady-state zero mode instead of filtering *all* near-zero eigenvalues.
+    A degenerate Hermitian-part kernel means there is **no certified
+    exponential GNS contraction** (`Delta_s = 0`); the old filtering
+    over-certified the bound (`Delta_s > Delta`, contradicting the
+    Kadison-Schwarz contraction property). Consequence: driven pure dephasing
+    with `rho_ss = I/2` now honestly reports `gns_gap = 0` (the sigma_z mode
+    has zero instantaneous GNS decay rate); detailed-balance systems keep
+    `Delta_s = Delta`. New contraction-bound regression tests
+    (`0 <= Delta_s <= Delta`, `0 <= Delta_KMS <= Delta`) pin the fix on
+    non-diagonal steady states (40/40 random systems verified).
+- **`sparse.chi1.chi1_lower_bound` returned `K^(1/4)` instead of the
+  documented `K^(1/2)`** (2026-07 audit A4): the ratio
+  `||r||*||l|| / |<l,r>|` is already the square root of the Petermann factor;
+  the code took a second square root, quadratically weakening the
+  ARPACK-reliability certificate. A regression test now pins the certificate
+  against the dense `petermann_factors` oracle (the old test only asserted
+  `chi > 0`).
+- **Silent zero-width confidence interval on bootstrap failure**
+  (`diagnostics.relaxation.compute_relaxation_layer`, 2026-07 audit A7): a
+  swallowed `parametric_bootstrap`/`bca_ci` exception used to keep the
+  degenerate initialisation `(beta_D, beta_D)`, which the uncertainty layer
+  read as `fit_uncertainty = 0.0` — *perfect certainty* as the failure mode.
+  The CI is now `(nan, nan)` plus a `RuntimeWarning`;
+  `compute_uncertainty_layer` already maps that to `fit_uncertainty = nan`.
+- Robustness guards (2026-07 audit A10/A11): `core.lindblad.steady_state`
+  casts integer/bool input instead of crashing in `np.finfo`;
+  `examples.v4_thermal_two_level` rejects `beta*omega <= 0` (divide-by-zero);
+  `io.seed.seed_everything` rejects `bool` seeds (silent 0/1 seeding);
+  `core.jumps.engineered_target_jumps` rejects a zero target vector and its
+  docstring now matches the two-operator return.
+- Docstring/comment drift fixed against implementations: D4 spread comment in
+  `_types.py`, pseudospectrum grid location, D18 sensitivity ensemble, D7b
+  fallback value, `diagnostics/__init__` layer count.
 - `liouscope.numerics.cptp`: fail-closed input validation now rejects
   non-finite generator/channel entries (`L_super`, `channel_super`) and invalid
   (negative / non-finite) tolerances *before* the matrix exponential, Choi
@@ -15,6 +64,23 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   the CP/TP verdict.
 
 ### Added
+- **Property-based test suite** (`tests/test_property_based.py`, Hypothesis):
+  ground-truth-free invariants on randomly drawn GKSL systems — gap scaling
+  `gap(c*L) = c*gap(L)`, spectrum invariance under unitary similarity,
+  trace-distance axioms + CPTP contractivity, the GKSL semigroup law
+  `Phi_{t1+t2} = Phi_{t2} Phi_{t1}`, and no-false-alarm coverage for the Choi
+  CPTP gate. `derandomize=True` keeps CI deterministic (the `hypothesis` dev
+  dependency was previously declared but unused).
+- **CodeQL SAST workflow** (`.github/workflows/codeql.yml`): weekly + PR/push
+  `security-and-quality` Python analysis, SHA-pinned, minimal permissions
+  (OpenSSF Scorecard SAST check; ruff is a linter, not SAST).
+- **pre-commit configuration** (`.pre-commit-config.yaml`): ruff-check,
+  zizmor (regular persona), CITATION.cff validation (`cffconvert`) and
+  standard hygiene hooks. No formatter (history churn) — CI remains the
+  authoritative gate.
+- `numerics.adjoint.gram_adjoint(L_super, G)`: adjoint of the
+  Heisenberg-picture generator w.r.t. an arbitrary Gram matrix (GNS and KMS
+  are the two instantiations).
 - `jsonschema>=4.18` added to the `dev` extra so CI actually exercises the full
   `Draft202012Validator` structural-conformance path for run manifests. It was
   previously absent from the dev/CI environment, so `_compiled_validator()`
@@ -27,7 +93,42 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   unnormalised maximally entangled operator, *not* `eye(d**2)`) and its
   CP-boundary PSD-ness across `d in {2, 4, 8, 16}`.
 
+### CI
+- `ci.yml`/`ci-qutip.yml`: `concurrency` groups auto-cancel superseded runs on
+  non-main refs (sp-repo-review GH102).
+- `pypi.yml`: fail-closed release QA gate (`twine check --strict` +
+  `check-wheel-contents`) between build and Trusted-Publishing upload.
+- `scorecard.yml`: `publish_results: true` now that the repo is public
+  (badge-capable, externally auditable score); stale private-repo comment
+  refreshed.
+- `pyproject.toml` strictness batch (sp-repo-review): pytest gains
+  `--strict-config`, `xfail_strict`, `log_level` and
+  `filterwarnings = ["error", ...]` (unexpected warnings — including
+  deprecations from dependency drift — now fail CI; the documented
+  `ResolventConvergenceWarning` lower-bound path is allowlisted); mypy gains
+  `warn_unreachable` + `enable_error_code = [ignore-without-code,
+  redundant-expr, truthy-bool]`; `wheel` removed from `build-system.requires`
+  (setuptools adds it itself when needed); redundant ruff `target-version`
+  dropped (inferred from `requires-python`).
+- `pypi.yml`: the Trusted-Publishing step now sets `print-hash: true` so each
+  uploaded sdist/wheel's SHA-256 is logged for the release-evidence lock. No
+  second attestation step is added — the PyPA action already uploads a PEP 740
+  attestation by default under Trusted Publishing, and PyPI rejects duplicate
+  predicates / more than two attestations per file. `docs/RELEASE_AUDIT_v0.5.0.md`
+  §5 documents the evidence flow; the stale "private repo" comment was refreshed
+  to "public".
+
 ### Documentation
+- README: the diagnostic layer table now uses the **code-backed D-numbering**
+  (module docstrings / StabilityReport keys as source of truth) — the previous
+  table circulated a second, contradictory numbering scheme. The "24
+  diagnostics" claim is qualified honestly: D1-D20 (+D2b/D7b/D11b) and D24 are
+  code-backed; D21-D23 are schema-defined but not yet implemented.
+- README/AGENTS.md reproducibility claims corrected to what the code does: the
+  manifest does not (yet) record lattice geometry / dissipator family / full
+  result graph; `seed_everything` does not control SciPy/BLAS threading.
+- README quickstart no longer suggests the dephased-qubit example classifies
+  as "A1" (see the tracked Mpemba false-positive issue).
 - Synchronized `docs/CANON_STATUS.md` and `AGENTS.md` with the v0.5.0 runtime
   canon: public-repo status, Python 3.14 CI coverage, the dedicated QuTiP
   cross-check checks, and the `StabilityReport v2.1` additive projection.
@@ -43,15 +144,6 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   and the old path is reduced to a pointer stub so existing links still resolve.
   Single numbered ADR going forward.
 
-### CI
-- `pypi.yml`: the Trusted-Publishing step now sets `print-hash: true` so each
-  uploaded sdist/wheel's SHA-256 is logged for the release-evidence lock. No
-  second attestation step is added — the PyPA action already uploads a PEP 740
-  attestation by default under Trusted Publishing, and PyPI rejects duplicate
-  predicates / more than two attestations per file. `docs/RELEASE_AUDIT_v0.5.0.md`
-  §5 documents the evidence flow; the stale "private repo" comment was refreshed
-  to "public".
-
 ## [0.5.0] - 2026-06-25
 
 Release cut: the Canon v0.5 diagnostics & contracts wave plus the cross-family