matrixscroll 0.7.0__tar.gz → 0.9.0__tar.gz

{matrixscroll-0.7.0 → matrixscroll-0.9.0}/.gitignore

@@ -46,9 +46,15 @@ credentials/
 .cursor/
 .playwright-cli/
 
+# Local operational data (workbench / envelopes)
+data/
+
 # Matrix Scroll local store (never commit a private key)
 .matrixscroll/
 device.json
+session.secret
+credentials.once.txt
+workbench.sqlite3
 
 # TLA+ tools (download locally or in CI)
 tla2tools.jar
@@ -66,3 +72,6 @@ site/
 .vale/styles/write-good/
 .vale/styles/ai-tells/
 .vale/styles/ai-tells-commits/
+
+.mcp-resign-home/
+

{matrixscroll-0.7.0 → matrixscroll-0.9.0}/CHANGELOG.md

@@ -6,6 +6,125 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-09-13
+
+Device-agnostic custody and CNSA 2.0 Category 5 sealed evidence packs. The USB/SE050
+signing path is removed from the public SDK; historical `signature.mode=hardware`
+envelopes still verify.
+
+### Removed
+- **`matrixscroll[hardware]`**, `HardwareProvider`, USB CDC SE050 transport, MCP
+  `connect_card`, SE050 acceptance vectors, and USB-first documentation. Setting
+  `MATRIXSCROLL_MODE=hardware` raises `IdentityError` with migration guidance.
+- Product visualizations and protocol docs that described a single USB signer as the
+  custody path.
+
+### Added
+- **Sealed evidence packs** (`matrixscroll.sealed`, schema
+  `matrixscroll.sealed-evidence-pack.v1`): hybrid X25519 + ML-KEM-1024 key agreement,
+  AES-256-GCM body, Ed25519 + ML-DSA-87 signatures. Requires `matrixscroll[pqc]`.
+  Parameter-set readiness through liboqs; not a CNSA certification or FIPS validation.
+- Device-agnostic custody documentation: implement `IdentityProvider` for any device
+  or HSM; default remains the file-backed `emulated` provider.
+
+### Changed
+- MCP stdio server is **13 tools** (was 14). Version pins, action default, and
+  public docs target **0.9.0**.
+- CRYPTO_ROADMAP sealed-pack step marked shipping for 0.9.0.
+
+## [0.8.0] - 2026-09-12
+
+Default post-quantum signature set moves to the CNSA 2.0 parameter set. No
+wire-format change; Ed25519 remains the default signature scheme and the
+post-quantum overlay remains opt-in through `MATRIXSCROLL_PQC`.
+
+### Changed
+- **Default PQC algorithm is now `ml-dsa-87`.** When you run
+  `matrixscroll pqc-keygen` without `--algorithm`, and when a library caller
+  invokes `load_pqc_keypair` or `attach_pqc_overlay` without an algorithm while
+  `MATRIXSCROLL_PQC` is unset, the SDK selects ML-DSA-87 (FIPS 204 Category 5).
+  That matches the CNSA 2.0 signature parameter set. Git commit envelopes and
+  `sign_manifest_with_pqc` attach the overlay only when you enable it:
+  `MATRIXSCROLL_PQC` names the set (`MATRIXSCROLL_PQC=ml-dsa-87`) or the caller
+  passes `pqc_algorithm`; `0`, `false`, `off` and `no` disable it, and an unset
+  variable leaves the manifest Ed25519-only. `matrixscroll sign`, the MCP
+  `sign_action` tool and `sign_mcp_manifest` remain Ed25519-only, as in 0.7.0;
+  the MCP `create_envelope` tool signs Git envelopes through
+  `sign_manifest_with_pqc`. It is parameter-set readiness through liboqs, not
+  CNSA certification, FIPS CMVP validation, or NSA approval.
+  Callers can still pass `ml-dsa-44` or `ml-dsa-65` explicitly. Existing key
+  files under `~/.matrixscroll/pqc/` are unchanged; a new default only affects
+  newly generated keys. `0.7.0` and earlier default to `ml-dsa-65`. Status of
+  each algorithm (shipping now, in progress, not planned) is the table in
+  `docs/CRYPTO_ROADMAP.md`.
+- The public README and documentation now lead with the offline verification
+  outcome, use explicit verification-boundary sections, and reserve signer
+  implementation detail for qualified setup.
+- **Documentation refreshed against the standards status of 12 September 2026.**
+  `docs/CRYPTO_ROADMAP.md` gains a policy-dates table (CNSSP-15 and the CNSA 2.0
+  FAQ v2.1, Executive Order 14412 and OMB M-26-15, the Department of War PQC
+  strategy, the NIST IR 8547 draft) and rows for FIPS 206, ML-KEM, LMS/XMSS and
+  the ACVP tests; `docs/COMPARISON.md` gains a dated landscape section (Sigstore,
+  GitHub attestations, gittuf, forge commit signing, MCP scanners, 2025-2026
+  agent-receipt projects) and a list of claims Matrix Scroll does not make. The
+  README and the documentation home open with the SSX360 USB signer render
+  (`docs/images/ssx360-usb-signer.jpg`, replaced) and the signer section shows
+  the sign round-trip sequence.
+
+### Added
+- **`slh-dsa-sha2-256s` and `slh-dsa-sha2-256f`** in the allowed PQC algorithm
+  list (FIPS 205 Category 5 hash-based options), schema, and CLI choices.
+- **NIST ACVP vectors** for the overlay: `vectors/acvp-sigver-fips204-fips205.json`
+  carries a subset of the ACVP-Server sample vectors for ML-DSA-87,
+  SLH-DSA-SHA2-256s and SLH-DSA-SHA2-256f (external interface, pure variant):
+  sigVer cases with the NIST tcIds, verdicts and reason strings, and sigGen
+  expected signatures over an empty context restated as positive cases. The
+  provenance block records the URL and SHA-256 of each source file. This is an
+  evidence mapping to NIST sample vectors, not a certification claim
+  (`docs/CRYPTO_ROADMAP.md`).
+- **`tests/test_acvp_sigver.py`** verifies the NIST-valid empty-context
+  signatures through `pqc_verify`, verifies and rejects the context-string
+  cases through liboqs's `verify_with_ctx_str` on the same mechanism the
+  overlay uses, and treats a wrong-length signature as invalid without calling
+  the verifier; the provenance check runs without liboqs.
+- **`tests/test_pqc.py`** signs, verifies and rejects a tampered signature for
+  every identifier in `PQC_ALGORITHMS`, and checks that a key file naming a set
+  the build does not enable fails through `IdentityError`.
+- **`tools/independent_verify.py`**, a second implementation of the verifier
+  written from SPEC.md alone: its own canonical serializer, a pure-Python
+  RFC 8032 Ed25519, the device-id derivation and the section 6 procedure, with
+  no import from the SDK (the section 11 overlay is checked when liboqs is
+  present). `tests/test_independent_verifier.py` holds it against the SDK on
+  every committed vector, on 500 random documents and on fresh signatures; the
+  README's "Ten-minute check for reviewers" names the commands.
+- **`matrixscroll.kem`** (CNSA 2.0 full-suite track, in progress): ML-KEM-1024
+  and ML-KEM-768 key generation, encapsulation and decapsulation through liboqs,
+  with deterministic key generation from the FIPS 203 seed. No envelope or
+  export format uses the module yet; `docs/CRYPTO_ROADMAP.md` names the sealed
+  evidence-pack design that will. `vectors/acvp-mlkem-fips203.json` and
+  `tests/test_acvp_mlkem.py` check it against the NIST ACVP sample vectors
+  (keyGen, decapsulation of NIST ciphertexts, implicit rejection of modified
+  ciphertexts); evidence mapping, not a certification claim.
+- **`CNSA_PREFERRED_PQC_ALGORITHM`** constant (`ml-dsa-87`) for policy and docs
+  that need a named CNSA 2.0 signature target without hard-coding the string.
+- **`docs/CRYPTO_ROADMAP.md`** CNSA 2.0 shipping / in progress / not table.
+
+### Fixed
+- **SLH-DSA identifiers now resolve against liboqs.** The overlay mapped the
+  `slh-dsa-*` identifiers to mechanism names liboqs does not expose
+  (`SLH-DSA-SHA2-256s`), so every SLH-DSA key generation, signature and
+  verification raised `MechanismNotSupportedError` on liboqs 0.16. The backend
+  now resolves each identifier against `oqs.get_enabled_sig_mechanisms()`
+  (`SLH_DSA_PURE_SHA2_256S` on liboqs 0.13 and later, the hyphenated spelling as
+  a fallback) and reports an unsupported set as `IdentityError` with the liboqs
+  version. ML-DSA was unaffected.
+- **`pqc_available()` no longer flips to true on the second call.** The probe
+  cached its negative result as an empty string and returned it unchanged on
+  later calls, so any second query reported the backend as present without
+  liboqs installed and the next signing call failed with a raw import error
+  instead of `IdentityError`. Found by the new tests, which query the probe
+  from two modules.
+
 ## [0.7.0] - 2026-08-11
 
 Fail-closed verification, package completeness, and public positioning. No
@@ -387,6 +506,8 @@ Initial public release. Extracted from the SSX360 reference implementation.
 - Device id format: `MS-XXXX-XXXX` (SHA-256 of the raw public key, first 8 hex
   chars, uppercase).
 
+[0.9.0]: https://github.com/SSX360/matrixscroll/releases/tag/v0.9.0
+[0.8.0]: https://github.com/SSX360/matrixscroll/releases/tag/v0.8.0
 [0.7.0]: https://github.com/SSX360/matrixscroll/releases/tag/v0.7.0
 [0.6.4]: https://github.com/SSX360/matrixscroll/releases/tag/v0.6.4
 [0.6.3]: https://github.com/SSX360/matrixscroll/releases/tag/v0.6.3

{matrixscroll-0.7.0 → matrixscroll-0.9.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: matrixscroll
-Version: 0.7.0
-Summary: MCP server for signed machine-action records, offline tool-surface checks, and SSX360 USB signer support.
+Version: 0.9.0
+Summary: MCP server for signed machine-action records, offline tool-surface checks, with device-agnostic custody and CNSA 2.0 Category 5 crypto (ML-DSA-87, ML-KEM-1024).
 Project-URL: Homepage, https://matrixscroll.com
-Project-URL: Documentation, https://matrixscroll.com/docs/
-Project-URL: Specification, https://matrixscroll.com/spec/
-Project-URL: Verifier, https://matrixscroll.com/verify/
+Project-URL: Documentation, https://github.com/SSX360/matrixscroll/tree/main/docs
+Project-URL: Specification, https://github.com/SSX360/matrixscroll/blob/main/SPEC.md
+Project-URL: Verifier, https://matrixscroll.com/#verify-offline
 Project-URL: Repository, https://github.com/SSX360/matrixscroll
 Project-URL: Source, https://github.com/SSX360/matrixscroll
 Project-URL: Issues, https://github.com/SSX360/matrixscroll/issues
@@ -16,12 +16,12 @@ Project-URL: Security, https://github.com/SSX360/matrixscroll/blob/main/SECURITY
 Project-URL: GitHub Action, https://github.com/SSX360/matrixscroll/tree/main/.github/actions/verify
 Project-URL: Tests, https://github.com/SSX360/matrixscroll/tree/main/tests
 Project-URL: Public Roadmap, https://github.com/SSX360/matrixscroll/blob/main/docs/ROADMAP_2026-07.md
-Project-URL: Hardware Status, https://github.com/SSX360/matrixscroll/blob/main/docs/hardware-provider.md
+Project-URL: Crypto Roadmap, https://github.com/SSX360/matrixscroll/blob/main/docs/CRYPTO_ROADMAP.md
 Project-URL: Maintainer, https://ssx360.com/about
 Author-email: SSX360 <security@matrixscroll.com>
 License-Expression: Apache-2.0
 License-File: LICENSE
-Keywords: authorization,ed25519,fips-204,fips-205,machine-action,matrixscroll,ml-dsa,post-quantum,provenance,root-of-trust,secure-element,signing,slh-dsa,ssx360,supply-chain
+Keywords: authorization,ed25519,fips-204,fips-205,machine-action,matrixscroll,ml-dsa,ml-kem,post-quantum,provenance,root-of-trust,signing,slh-dsa,ssx360,supply-chain
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Information Technology
@@ -46,8 +46,6 @@ Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
 Requires-Dist: pytest>=9.1.1; extra == 'dev'
 Requires-Dist: pyyaml>=6.0.3; extra == 'dev'
 Provides-Extra: git
-Provides-Extra: hardware
-Requires-Dist: pyserial>=3.5; extra == 'hardware'
 Provides-Extra: mcp
 Requires-Dist: mcp<2.0.0,>=1.28.0; extra == 'mcp'
 Provides-Extra: pqc
@@ -59,18 +57,16 @@ Description-Content-Type: text/markdown
 
 # Matrix Scroll
 
-Model Context Protocol server for signed machine-action records and offline tool-surface verification.
+Signed machine-action records with offline verification for MCP, Git, and CI.
 
 [![ci-unit](https://github.com/SSX360/matrixscroll/actions/workflows/ci-unit.yml/badge.svg)](https://github.com/SSX360/matrixscroll/actions/workflows/ci-unit.yml)
 [![PyPI](https://img.shields.io/pypi/v/matrixscroll)](https://pypi.org/project/matrixscroll/)
 [![Python](https://img.shields.io/pypi/pyversions/matrixscroll)](https://pypi.org/project/matrixscroll/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/SSX360/matrixscroll/blob/main/LICENSE)
 
-An MCP server can change its tool descriptions or input schemas after installation. A Git commit can also declare an actor or tool without carrying a signed authorization record. Matrix Scroll addresses both gaps with Ed25519-signed evidence that reviewers can verify offline.
+An MCP server can change its tool descriptions or input schemas after installation. A Git commit can also declare an actor or tool without carrying a signed authorization record. Matrix Scroll records both surfaces as Ed25519-signed evidence that reviewers can verify offline, with an optional ML-DSA-87 post-quantum overlay and ML-KEM-1024 sealed evidence packs on the CNSA 2.0 Category 5 track.
 
-The `matrixscroll-mcp` stdio server exposes 14 tools for commit envelopes, action records, pull-request checks, Git notes, MCP surface manifests, agent traces, and the SSX360 USB signer. Local signing and verification need no cloud account.
-
-SSX360 has completed and produced the USB signer shown below. The device uses an RP2350 USB bridge and an NXP SE050 secure element. SSX360 supplies the signer by direct inquiry through [SSX360 contact](https://ssx360.com/contact) or `mission@ssx360.com`.
+The `matrixscroll-mcp` stdio server exposes 13 tools for commit envelopes, action records, pull-request checks, Git notes, MCP surface manifests, and agent traces. Custody is device-agnostic: the default is a file-backed software provider, and any device or HSM plugs in through the `IdentityProvider` seam. Local signing and verification need no cloud account.
 
 Matrix Scroll is an open protocol. The Python SDK is Apache-2.0 software, and the specification and vectors are CC0 1.0.
 
@@ -79,10 +75,11 @@ Matrix Scroll is an open protocol. The Python SDK is Apache-2.0 software, and th
 - [Install the MCP server](#install-the-mcp-server)
 - [MCP tools](#mcp-tools)
 - [Detect MCP tool-surface changes](#detect-mcp-tool-surface-changes)
-- [Use the SSX360 USB signer](#use-the-ssx360-usb-signer)
+- [Device-agnostic custody](#device-agnostic-custody)
 - [Sign and verify from the CLI](#sign-and-verify-from-the-cli)
-- [Honest limits](#honest-limits)
+- [Verification boundaries](#verification-boundaries)
 - [Verify the release](#verify-the-release)
+- [Ten-minute check for reviewers](#ten-minute-check-for-reviewers)
 - [Security and license](#security-and-license)
 
 ## Install the MCP server
@@ -90,7 +87,7 @@ Matrix Scroll is an open protocol. The Python SDK is Apache-2.0 software, and th
 Install the current release from PyPI:
 
 ```bash
-pip install "matrixscroll[mcp]==0.7.0"
+pip install "matrixscroll[mcp]==0.9.0"
 ```
 
 Register the stdio server in your MCP client:
@@ -118,7 +115,7 @@ After your client connects, call `status`. The server reports the local identity
 
 ## MCP tools
 
-The `0.7.0` server exposes these tools:
+The `0.9.0` server exposes these tools:
 
 | Tool | What it does | Network or write behavior |
 | --- | --- | --- |
@@ -130,21 +127,20 @@ The `0.7.0` server exposes these tools:
 | `publish_notes` | Publishes local envelopes to `refs/notes/matrixscroll` | Writes local Git notes |
 | `audit_export` | Exports evidence for review | Writes a local bundle or uses the hosted API when configured |
 | `list_envelopes` | Lists organization envelopes | Requires `SSX360_API_KEY` and the hosted API |
-| `connect_card` | Probes the SSX360 USB signer over USB CDC | Opens the configured serial port |
 | `scan_mcp_server` | Fingerprints MCP tool names, descriptions, and input schemas | Read-only when tools are supplied |
 | `sign_mcp_manifest` | Signs an MCP tool-surface manifest | Writes only when `save_path` is set |
 | `verify_mcp_manifest` | Verifies a manifest and compares it with a signed baseline | Read-only and local |
 | `sign_agent_trace` | Signs a browser-agent JSONL trace | Writes a signed envelope |
 | `verify_agent_trace` | Verifies a signed trace and optionally checks the source bytes | Read-only and local |
 
-An API key is optional. Local signing, offline verification, MCP manifest checks, and USB signer access do not require one. Hosted organization history and hosted range verification use `SSX360_API_KEY`.
+An API key is optional. Local signing, offline verification, and MCP manifest checks do not require one. Hosted organization history and hosted range verification use `SSX360_API_KEY`.
 
 ## Detect MCP tool-surface changes
 
 Matrix Scroll records an MCP server's tool names, descriptions, and input schemas in a signed manifest. Re-scan the server after an update and compare it with the install-time baseline.
 
 ```bash
-pip install "matrixscroll[mcp]==0.7.0"
+pip install "matrixscroll[mcp]==0.9.0"
 
 matrixscroll mcp scan \
   --connect stdio \
@@ -174,83 +170,25 @@ The verify command exits with code `2` when the signature is invalid or the curr
 matrixscroll mcp scan --tools tools.json --output manifest.json --pretty
 ```
 
-## Use the SSX360 USB signer
-
-![Completed SSX360 USB signer](https://raw.githubusercontent.com/SSX360/matrixscroll/main/docs/images/ssx360-usb-signer.jpg)
-
-Install the hardware and MCP extras:
-
-```bash
-pip install "matrixscroll[mcp,hardware]==0.7.0"
-```
-
-Set the hardware provider and USB CDC port before starting the MCP server.
-
-Windows PowerShell:
-
-```powershell
-$env:MATRIXSCROLL_MODE = "hardware"
-$env:MATRIXSCROLL_SE050_PORT = "COM3"
-matrixscroll status
-matrixscroll-mcp
-```
-
-Linux:
-
-```bash
-export MATRIXSCROLL_MODE=hardware
-export MATRIXSCROLL_SE050_PORT=/dev/ttyACM0
-matrixscroll status
-matrixscroll-mcp
-```
-
-You can also pass the hardware settings through the MCP client configuration:
+## Device-agnostic custody
 
-```json
-{
-  "mcpServers": {
-    "matrixscroll": {
-      "command": "matrixscroll-mcp",
-      "args": [],
-      "env": {
-        "MATRIXSCROLL_MODE": "hardware",
-        "MATRIXSCROLL_SE050_PORT": "COM3"
-      }
-    }
-  }
-}
-```
+Signing goes through an `IdentityProvider` (`public_key_bytes`, `sign`, `mode`). The default `emulated` provider stores an Ed25519 key under `~/.matrixscroll`. To adapt Matrix Scroll to any device or HSM, implement that interface and select it with `MATRIXSCROLL_MODE` (or pass a provider instance to the library APIs). Experimental `tpm` and `yubikey` previews remain available; they are not the Category 5 story and do not claim hardware ML-DSA.
 
-Call `connect_card` to confirm that the signer responds. Then call `status` to inspect the active provider before creating an envelope.
+Historical envelopes with `signature.mode` equal to `"hardware"` still verify. The USB/SE050 signing path was removed in 0.9.0; `MATRIXSCROLL_MODE=hardware` raises instead of opening a serial port.
 
-SSX360 supplies the finished signer through direct contact. Ask for the Matrix Scroll USB signer through [SSX360 contact](https://ssx360.com/contact). The hardware is not distributed through PyPI or listed for self-service purchase.
-
-### How hardware signing works
-
-![USB signing round trip](https://raw.githubusercontent.com/SSX360/matrixscroll/main/docs/images/ssx360-usb-signer-round-trip.jpg)
-
-1. The host sends `GEN_KEY` through the RP2350 USB bridge.
-2. The SE050 creates an Ed25519 key pair in the secure element. The private key is non-exportable.
-3. The host reads the 32-byte public key.
-4. The host sends canonical bytes with a `SIGN` request.
-5. The SE050 returns a 64-byte Ed25519 signature.
-6. Matrix Scroll assembles the signed record and verifies it with the same offline verifier used for software signing.
-
-The host receives the public key and signature. The private key stays inside the SE050.
-
-![USB signer architecture](https://raw.githubusercontent.com/SSX360/matrixscroll/main/docs/images/ssx360-usb-signer-architecture.jpg)
+Sealed evidence packs (`matrixscroll.sealed`) encrypt a payload to a recipient's ML-KEM-1024 key with a hybrid X25519 + ML-KEM-1024 agreement, AES-256-GCM for the body, and Ed25519 plus ML-DSA-87 signatures over the pack. Install `matrixscroll[pqc]`. This is parameter-set readiness through liboqs, not a CNSA certification or FIPS validation.
 
 ## Sign and verify from the CLI
 
 The Python package includes a CLI and Git hooks for workflows that do not use MCP.
 
 ```bash
-pip install "matrixscroll==0.7.0"
+pip install "matrixscroll==0.9.0"
 matrixscroll hook-install
 
-export MATRIXSCROLL_ACTOR_TYPE=agent
-export MATRIXSCROLL_TOOL=agent-runner
-git commit -m "feat: agent-assisted change"
+export MATRIXSCROLL_ACTOR_TYPE=ci
+export MATRIXSCROLL_TOOL=release-runner
+git commit -m "feat: automate release"
 
 matrixscroll envelope-verify "$(git rev-parse HEAD)"
 ```
@@ -264,16 +202,16 @@ matrixscroll verify release.signed.json
 
 `matrixscroll verify` exits with code `0` for a valid signature and code `2` for invalid input, a failed signature, a mismatched device identity, or an unsupported schema or algorithm.
 
-## Honest limits
+## Verification boundaries
 
 <!-- vale ai-tells.ShipOveruse = NO -->
 
-- Shipping now: PyPI `matrixscroll==0.7.0` installs the 14-tool stdio MCP server and Git hooks. The release also includes the MCP Trust Scanner, offline verification, and USB CDC integration for the SSX360 signer.
-- Hardware availability: SSX360 produces the USB signer and supplies it after a direct inquiry. PyPI distributes the host software only.
-- Hosted tools: `list_envelopes` and the hosted modes of `verify_pr_range` and `audit_export` require `SSX360_API_KEY` and a deployed SSX360 API. Local alternatives remain available without a key.
-- Post-quantum overlay: the optional `matrixscroll[pqc]` extra provides ML-DSA and SLH-DSA through liboqs. This module has no CMVP validation. liboqs states that applications should not rely on it to protect sensitive data in production.
-- Verification scope: an Ed25519 signature proves that the signed bytes match and correspond to the included public key. The declared `actor_type` still requires a trusted-key and authorization policy.
-- Not included: identity and access management, sandboxing, prompt filtering, or an agent runtime.
+- Release: PyPI `matrixscroll==0.9.0` installs the 13-tool stdio MCP server and Git hooks, the MCP Trust Scanner, offline verification, sealed evidence packs, and device-agnostic custody.
+- Hosted tools: `list_envelopes` and the hosted modes of `verify_pr_range` and `audit_export` require `SSX360_API_KEY` and a deployed SSX360 API. Local signing and verification remain available without a key.
+- Post-quantum evaluation path: the optional `matrixscroll[pqc]` extra provides ML-DSA and SLH-DSA through liboqs, including Category 5 sets (`ml-dsa-87`, `slh-dsa-sha2-256s`/`256f`). Release `0.9.0` defaults new software keys to `ml-dsa-87` for CNSA 2.0 signature-parameter alignment (`0.7.0` and earlier default to `ml-dsa-65`; pass `--algorithm` or `MATRIXSCROLL_PQC` to choose a set explicitly). That is parameter-set readiness, not CNSA certification, FIPS CMVP validation, or NSA approval. This module has no CMVP validation. liboqs states that applications should not rely on it to protect sensitive data in production.
+- CNSA 2.0 full-suite track: `matrixscroll.kem` provides ML-KEM-1024 primitives (ACVP-checked). Sealed evidence packs in `matrixscroll.sealed` use hybrid X25519 + ML-KEM-1024 with Ed25519 + ML-DSA-87. Same boundary as the signature overlay: evidence mapping against NIST vectors, not a validation. See `docs/CRYPTO_ROADMAP.md`.
+- Verification scope: an Ed25519 signature proves that the signed bytes match and correspond to the included public key. A trusted-key and authorization policy establishes whether the declared `actor_type` can perform the action.
+- Adjacent controls: identity and access management, sandboxing, prompt filtering, and agent runtime policy remain separate controls.
 
 <!-- vale ai-tells.ShipOveruse = YES -->
 
@@ -281,11 +219,11 @@ matrixscroll verify release.signed.json
 
 GitHub Actions publishes each Matrix Scroll release through PyPI Trusted Publishing. PyPI records a PEP 740 attestation for the wheel and source distribution.
 
-Ask PyPI for the `0.7.0` wheel provenance:
+Ask PyPI for the `0.9.0` wheel provenance:
 
 ```bash
 curl -H "Accept: application/vnd.pypi.integrity.v1+json" \
-  https://pypi.org/integrity/matrixscroll/0.7.0/matrixscroll-0.7.0-py3-none-any.whl/provenance
+  https://pypi.org/integrity/matrixscroll/0.9.0/matrixscroll-0.9.0-py3-none-any.whl/provenance
 ```
 
 The response names the GitHub publisher:
@@ -301,6 +239,16 @@ The response names the GitHub publisher:
 
 Compare the attested `subject[].digest.sha256` value with the SHA-256 digest of the file you downloaded. Stop if the repository, workflow, or digest differs.
 
+## Ten-minute check for reviewers
+
+Five questions a programme manager or auditor asks first, each with the command that answers it. Everything below runs offline from a clone of this repository with `pip install "matrixscroll[pqc]==0.9.0"` (the `pqc` extra is needed only for the last two lines of question 3).
+
+1. **Does it run in one command, offline?** `matrixscroll verify vectors/valid_simple.json` prints `"ok": true` and exits `0`; `matrixscroll verify vectors/tampered_field.json` prints `"ok": false` and exits `2`. Neither command opens a network connection. Exit codes are fixed in [docs/reference/exit-codes.md](https://github.com/SSX360/matrixscroll/blob/main/docs/reference/exit-codes.md).
+2. **Is there a second implementation of the verifier?** `python tools/independent_verify.py vectors/` re-implements SPEC.md sections 3 to 6 from the text, with its own canonical serializer and a pure-Python RFC 8032 Ed25519, and imports nothing from the SDK. It must reach the same verdict as the SDK on every committed vector and on 500 randomly generated documents; `tests/test_independent_verifier.py` enforces that in CI on every change.
+3. **Are the vectors committed?** `vectors/valid_*.json`, `tampered_*.json` and `unsigned_*.json` are the conformance set (CC0 1.0); `vectors/acvp-sigver-fips204-fips205.json` and `vectors/acvp-mlkem-fips203.json` are NIST ACVP sample vectors with source URLs and SHA-256 digests. `python -m pytest tests/test_vectors.py tests/test_independent_verifier.py -q` runs the conformance set; `python -m pytest tests/test_acvp_sigver.py tests/test_acvp_mlkem.py -q` runs the NIST vectors through liboqs.
+4. **Is the boundary stated?** [Verification boundaries](#verification-boundaries) above, [docs/CRYPTO_ROADMAP.md](https://github.com/SSX360/matrixscroll/blob/main/docs/CRYPTO_ROADMAP.md) (Shipping now / In progress / Not, with policy dates) and [docs/COMPARISON.md](https://github.com/SSX360/matrixscroll/blob/main/docs/COMPARISON.md) (a dated landscape and the claims Matrix Scroll does not make). Compliance language everywhere is evidence mapping, not a certification claim.
+5. **Are the design rules checked by a model checker?** `formal/tla/` holds TLA+ models of the canonical bytes, the dual signature and the Scroll Gate range rules; `.github/workflows/formal-verify.yml` runs TLC on all seven configurations on every change to them. The models check the design, not the Python implementation; the tests above check the implementation. [docs/WHITEPAPER.md](https://github.com/SSX360/matrixscroll/blob/main/docs/WHITEPAPER.md) is the written account of the protocol.
+
 ## Security and license
 
 Read the [security policy](https://github.com/SSX360/matrixscroll/blob/main/SECURITY.md) and [security properties](https://github.com/SSX360/matrixscroll/blob/main/docs/SECURITY_PROPERTIES.md). Report vulnerabilities privately to `security@matrixscroll.com` or through a GitHub Security Advisory.
@@ -309,9 +257,11 @@ Matrix Scroll code is licensed under Apache-2.0. [`SPEC.md`](https://github.com/
 
 | Resource | Link |
 | --- | --- |
-| Documentation | [matrixscroll.com/docs](https://matrixscroll.com/docs/) |
-| MCP Trust Scanner | [matrixscroll.com/scan](https://matrixscroll.com/scan/) |
-| Offline verifier | [matrixscroll.com/verify](https://matrixscroll.com/verify/) |
-| Protocol specification | [matrixscroll.com/spec](https://matrixscroll.com/spec/) |
+| Tombstone / schemas | [matrixscroll.com](https://matrixscroll.com/) |
+| Documentation | [GitHub docs](https://github.com/SSX360/matrixscroll/tree/main/docs) |
+| Where Matrix Scroll fits (dated comparison) | [docs/COMPARISON.md](https://github.com/SSX360/matrixscroll/blob/main/docs/COMPARISON.md) |
+| Cryptographic roadmap (Ed25519, ML-DSA-87 overlay, policy dates) | [docs/CRYPTO_ROADMAP.md](https://github.com/SSX360/matrixscroll/blob/main/docs/CRYPTO_ROADMAP.md) |
+| Offline verification | [CLI guide](https://github.com/SSX360/matrixscroll#sign-and-verify-from-the-cli) |
+| Protocol specification | [SPEC.md](https://github.com/SSX360/matrixscroll/blob/main/SPEC.md) |
 | Source repository | [github.com/SSX360/matrixscroll](https://github.com/SSX360/matrixscroll) |
 | SSX360 contact | [Contact SSX360](https://ssx360.com/contact) |