matrixscroll 0.2.4__tar.gz → 0.2.6__tar.gz

{matrixscroll-0.2.4 → matrixscroll-0.2.6}/CHANGELOG.md

@@ -4,6 +4,41 @@ All notable changes to the Matrix Scroll Python SDK are documented here. The
 format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.6] - 2026-06-21
+
+SDK rollout hardening: generic public attribution, SE050 host transport preview,
+and repo-local hardware rollout docs.
+
+### Added
+- **USB CDC host transport preview** - `SerialSE050Transport` for newline-delimited
+  JSON `ping` / `pubkey` / `sign` framing over the RP2350 USB bridge.
+- **Hardware extra** - `pip install "matrixscroll[hardware]"` now pulls in
+  `pyserial` for the SE050 host path.
+- **Rollout docs** - adopter kit, five-minute guide, hardware provider quickstart,
+  SE050 protocol reference, and contractor-facing PoC scope kept inside the SDK repo.
+
+### Changed
+- **Public quickstarts** - replaced editor-specific public quickstarts with
+  generic agent-facing guidance while keeping the manifest schema and API unchanged.
+- **Hardware messaging** - clarified that the SDK now ships a host transport
+  preview and mock path, while real device signing still depends on firmware PoC validation.
+- **Release copy** - aligned README, support docs, CI examples, and package metadata
+  around the `0.2.6` rollout surface.
+
+## [0.2.5] - 2026-06-20
+
+Credibility and compatibility patch: GitHub gpgsig commit binding, SE050 mock transport, YubiKey pubkey export, Rekor/GUAC CLI MVP.
+
+### Added
+- **GitHub `gpgsig` commit binding** — verify envelopes against raw commit object SHA when OpenPGP signatures are present.
+- **SE050 mock transport** — `MATRIXSCROLL_SE050_MOCK=1` enables `HardwareProvider` for development (`providers/se050_transport.py`).
+- **YubiKey public key export** — PKCS#11 EC public key read path (mock + real token).
+- **GUAC export CLI** — `matrixscroll envelope-export-guac --bundle DIR --output guac.jsonl`.
+- **Rekor publish stub** — `matrixscroll envelope-publish-rekor --bundle DIR` (dry-run artifacts; optional `--rekor-cli`).
+
+### Fixed
+- **`parse_commit()` / envelope verify** on GitHub-signed commits with multi-line `gpgsig` headers (Windows CRLF safe).
+
 ## [0.2.4] - 2026-06-20
 
 Who-Acted gate productization: attribution policy, delegation schema, CI hardening.

{matrixscroll-0.2.4 → matrixscroll-0.2.6}/CONTRIBUTING.md

@@ -29,6 +29,25 @@ pip install -e ".[dev]"
 pytest -q
 ```
 
+## Commit envelope provenance (Scroll Gate)
+
+For PRs that include agent-assisted commits, publish signed commit envelopes to git notes:
+
+```bash
+matrixscroll hook-install
+export MATRIXSCROLL_ACTOR_TYPE=agent   # or human / ci as appropriate
+export MATRIXSCROLL_TOOL=agent-runner  # or your editor / agent tool name
+git commit -m "feat: your change"
+matrixscroll envelope-publish-notes --base origin/main --head HEAD
+git push origin refs/notes/matrixscroll
+```
+
+CI verifies the PR range with `matrixscroll envelope-verify-range --source notes`.
+Until repository variable `ENFORCE_PROVENANCE=true` is set, missing notes produce a **warning**
+in the GitHub Step Summary rather than a hard failure.
+
+Optional policy file for release branches: [`.github/trusted-keys.json`](.github/trusted-keys.json).
+
 ## Running the conformance vectors
 
 ```bash
@@ -42,7 +61,7 @@ vectors are welcome.
 
 ## Pull request checklist
 
-- [ ] Tests pass locally (`pytest -q`).
+- [ ] For agent-assisted commits: publish envelope git notes (`envelope-publish-notes` + push `refs/notes/matrixscroll`).
 - [ ] New public API has a docstring and is re-exported from
       `matrixscroll/__init__.py` if it's part of the supported surface.
 - [ ] `CHANGELOG.md` updated with a dated version entry (see Keep a Changelog format).

matrixscroll-0.2.6/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: matrixscroll
+Version: 0.2.6
+Summary: Signed provenance for agent-assisted Git commits with offline verification; emulated Ed25519 ships today and the SE050 hardware path remains an optional preview.
+Project-URL: Homepage, https://matrixscroll.com
+Project-URL: Documentation, https://matrixscroll.com/docs
+Project-URL: Source, https://github.com/SSX360/matrixscroll
+Project-URL: Issues, https://github.com/SSX360/matrixscroll/issues
+Project-URL: Specification, https://github.com/SSX360/matrixscroll/blob/main/SPEC.md
+Project-URL: Whitepaper, https://github.com/SSX360/matrixscroll/blob/main/docs/WHITEPAPER.md
+Project-URL: Verifier, https://matrixscroll.com/verify
+Project-URL: Compare, https://matrixscroll.com/compare
+Project-URL: Changelog, https://github.com/SSX360/matrixscroll/blob/main/CHANGELOG.md
+Project-URL: Discussions, https://github.com/SSX360/matrixscroll/discussions
+Project-URL: Security, https://github.com/SSX360/matrixscroll/blob/main/SECURITY.md
+Project-URL: GitHub Action, https://github.com/SSX360/matrixscroll-verify-action
+Project-URL: PyPI Provenance, https://pypi.org/project/matrixscroll/
+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: Reference Device, https://matrixscroll.com/device
+Author-email: SSX360 <security@matrixscroll.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: ai,ed25519,matrixscroll,provenance,root-of-trust,secure-element,signing,ssx360,supply-chain
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=41.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Provides-Extra: git
+Provides-Extra: hardware
+Requires-Dist: pyserial>=3.5; extra == 'hardware'
+Provides-Extra: tpm
+Provides-Extra: yubikey
+Requires-Dist: python-pkcs11>=0.7; extra == 'yubikey'
+Description-Content-Type: text/markdown
+
+# Matrix Scroll
+
+Signed provenance for agent-assisted Git commits with offline verification.
+
+Matrix Scroll is a cryptographic evidence layer for Git. When an agent, CI
+workflow, or human operator produces a commit, a signed commit envelope can
+record the actor, tool, and optional bounded scope. Anyone can verify that
+envelope locally, in CI, or in the browser without trusting the editor session
+that produced it.
+
+The reference SDK ships pure Ed25519 over canonical manifest bytes today. The
+SSX360 / NXP SE050 path is the compatible next trust layer and remains a
+preview path until device acceptance is complete.
+
+## Honest limits
+
+- Shipping now: PyPI `matrixscroll==0.2.6`, Git post-commit hooks,
+  `matrixscroll envelope-verify`, Scroll Gate PR verification, browser
+  verifier, the GitHub Action, and a USB CDC host transport preview for the
+  SE050 rollout path.
+- In progress: RP2350 + SE050 firmware validation, external Ed25519-capable
+  hardware key backends, and transparency-log integrations.
+- Not: IAM, sandboxing, prompt filtering, or an agent runtime.
+
+## Quickstart
+
+```bash
+pip install "matrixscroll==0.2.6"
+matrixscroll hook-install
+
+export MATRIXSCROLL_ACTOR_TYPE=agent
+export MATRIXSCROLL_TOOL=agent-runner
+git commit -m "feat: agent-assisted change"
+
+matrixscroll envelope-verify "$(git rev-parse HEAD)"
+```
+
+See [`docs/quickstart-git.md`](docs/quickstart-git.md) and run
+[`examples/demo/agent-commit-demo.sh`](examples/demo/agent-commit-demo.sh).
+
+## CI verify
+
+### Scroll Gate for a PR commit range
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+- uses: SSX360/matrixscroll-verify-action@v1
+  with:
+    head-ref: ${{ github.event.pull_request.head.sha }}
+    base-ref: ${{ github.event.pull_request.base.sha }}
+    source: notes
+    matrixscroll-version: "0.2.6"
+    require-mode: emulated
+```
+
+Publish envelopes to git notes before review:
+
+```bash
+matrixscroll envelope-publish-notes --base origin/main --head HEAD
+git push origin refs/notes/matrixscroll
+```
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+- uses: SSX360/matrixscroll-verify-action@v1
+  with:
+    head-ref: ${{ github.event.pull_request.head.sha }}
+    base-ref: ${{ github.event.pull_request.base.sha }}
+    source: notes
+    matrixscroll-version: "0.2.6"
+    summary-output: provenance-summary.json
+```
+
+See [`docs/quickstart-git.md`](docs/quickstart-git.md) and
+[`examples/ci/protected-branch.yml`](examples/ci/protected-branch.yml).
+
+The `--require-mode`, `--trusted-keys`, and actor or delegation policy checks
+are available in the `0.2.x` line; the examples in this README pin `0.2.6`.
+
+## Why it is different from Sigstore
+
+Sigstore, GitHub artifact attestations, and SLSA answer "what was built in
+CI?" Matrix Scroll answers "who signed this commit before push?" The systems
+are complementary: Matrix Scroll signs commit envelopes at commit time, while
+artifact-attestation systems sign build outputs later in the delivery chain.
+
+Matrix Scroll does not compete with general authentication keys on their home
+field. Existing hardware roots can become Matrix Scroll signing backends only
+when they preserve the same pure Ed25519 byte contract.
+
+## Public proof links
+
+- Browser verifier: <https://matrixscroll.com/verify/>
+- Compare page: <https://matrixscroll.com/compare/>
+- Specification: [`SPEC.md`](SPEC.md)
+- Commit envelope schema: [`schemas/commit-envelope.v1.json`](schemas/commit-envelope.v1.json)
+- Whitepaper: [`docs/WHITEPAPER.md`](docs/WHITEPAPER.md)
+- Conformance vectors: [`vectors/`](vectors/)
+- GitHub Action: <https://github.com/SSX360/matrixscroll-verify-action>
+- Agentic AI controls: [`docs/AGENTIC_AI_SECURITY.md`](docs/AGENTIC_AI_SECURITY.md)
+- Site: <https://matrixscroll.com>
+- Reference device path: <https://matrixscroll.com/device/>
+
+## Python API
+
+```bash
+pip install "matrixscroll==0.2.6"
+```
+
+```python
+import matrixscroll
+
+print(matrixscroll.status())
+# {'schema': 'matrixscroll.identity.v1', 'available': True,
+#  'mode': 'emulated', 'device_id': 'MS-A3F2-9C81', ...}
+
+signed = matrixscroll.sign_manifest({"release": "v1.0.0", "artifacts": [...]})
+
+assert matrixscroll.verify_manifest(signed)
+```
+
+## CLI
+
+```bash
+$ matrixscroll status
+{
+  "available": true,
+  "device_id": "MS-A3F2-9C81",
+  "mode": "emulated",
+  "public_key": "...",
+  "schema": "matrixscroll.identity.v1"
+}
+
+$ matrixscroll sign release.json > release.signed.json
+$ matrixscroll verify release.signed.json
+{"device_id": "MS-A3F2-9C81", "mode": "emulated", "ok": true, "signed_at": "..."}
+```
+
+`matrixscroll verify` exits `0` on a valid signature and `2` on failure
+(tampered manifest, missing signature block, wrong schema or algorithm,
+mismatched device ID, malformed public key, unreadable file).
+
+## How it works
+
+```text
+your IDE / agent / CI
+         |
+         |  commit envelope, release manifest, evidence pack, SBOM
+         v
+matrixscroll.sign_manifest(...)  /  post-commit hook
+         |
+         |  canonical JSON (sorted keys, ASCII-escaped, no NaN,
+         |  signature block excluded from input)
+         v
+IdentityProvider          -->  Ed25519 signature
+(L1 emulated today,
+ SSX360 / SE050 roadmap)
+         |
+         v
+signed document  -->  matrixscroll.verify_manifest(...)
+                      (anyone, anywhere, offline)
+```
+
+Switch providers with `MATRIXSCROLL_MODE`. Hardware mode includes a USB CDC
+host transport preview and a mock path for CI; real SE050 signing still
+depends on device firmware validation. External-key backends stay out of the
+mainline until they can sign the same canonical bytes with Ed25519.
+
+## Compliance levels
+
+| Level | Provider | Backed by | Status |
+| ----- | -------- | --------- | ------ |
+| **L1** Emulated | `EmulatedProvider` | Software key, file-backed (0600) | Shipping |
+| **L2** Hardware | `HardwareProvider` | NXP SE050 secure element (SSX360) | In progress |
+| **L3** Attested | future | L2 + remote attestation | Roadmap |
+
+`status()` exposes the active level via the `mode` and `available` fields.
+
+## Storage and trust boundaries
+
+- Emulated key store: `~/.matrixscroll/device.json`
+  (override with `MATRIXSCROLL_HOME`).
+- The directory is created `0700`; the seed file is opened `0600` with
+  `O_CREAT|O_EXCL` so the private seed is never momentarily world-readable.
+- A corrupt or truncated store fails loud (`IdentityError`) rather than
+  silently minting a fresh identity.
+- The planned hardware path holds nothing private on disk; the seed is sealed
+  in the secure element.
+
+## Reference implementation, not the only one
+
+Matrix Scroll is a protocol. This Python package is the reference. We welcome
+implementations in Rust, Go, TypeScript, and embedded C. Run them against
+[`vectors/`](vectors/) to self-certify. See `CONTRIBUTING.md`.
+
+## Agentic AI guidance proof
+
+The repo includes a machine-readable control matrix at
+[`controls/agentic_ai_controls.json`](controls/agentic_ai_controls.json), an
+example bounded-agent evidence manifest at
+[`examples/agentic_ai_evidence_manifest.json`](examples/agentic_ai_evidence_manifest.json),
+and executable checks in `tests/test_agentic_guidance.py`.
+
+## License
+
+- Code: **Apache-2.0** (`LICENSE`).
+- Specification text (`SPEC.md`, `vectors/`): **CC0 1.0** - public domain.
+
+## Security
+
+See [`SECURITY.md`](SECURITY.md). Report vulnerabilities privately to
+**security@matrixscroll.com** or via a GitHub Security Advisory.

matrixscroll-0.2.6/README.md

@@ -0,0 +1,216 @@
+# Matrix Scroll
+
+Signed provenance for agent-assisted Git commits with offline verification.
+
+Matrix Scroll is a cryptographic evidence layer for Git. When an agent, CI
+workflow, or human operator produces a commit, a signed commit envelope can
+record the actor, tool, and optional bounded scope. Anyone can verify that
+envelope locally, in CI, or in the browser without trusting the editor session
+that produced it.
+
+The reference SDK ships pure Ed25519 over canonical manifest bytes today. The
+SSX360 / NXP SE050 path is the compatible next trust layer and remains a
+preview path until device acceptance is complete.
+
+## Honest limits
+
+- Shipping now: PyPI `matrixscroll==0.2.6`, Git post-commit hooks,
+  `matrixscroll envelope-verify`, Scroll Gate PR verification, browser
+  verifier, the GitHub Action, and a USB CDC host transport preview for the
+  SE050 rollout path.
+- In progress: RP2350 + SE050 firmware validation, external Ed25519-capable
+  hardware key backends, and transparency-log integrations.
+- Not: IAM, sandboxing, prompt filtering, or an agent runtime.
+
+## Quickstart
+
+```bash
+pip install "matrixscroll==0.2.6"
+matrixscroll hook-install
+
+export MATRIXSCROLL_ACTOR_TYPE=agent
+export MATRIXSCROLL_TOOL=agent-runner
+git commit -m "feat: agent-assisted change"
+
+matrixscroll envelope-verify "$(git rev-parse HEAD)"
+```
+
+See [`docs/quickstart-git.md`](docs/quickstart-git.md) and run
+[`examples/demo/agent-commit-demo.sh`](examples/demo/agent-commit-demo.sh).
+
+## CI verify
+
+### Scroll Gate for a PR commit range
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+- uses: SSX360/matrixscroll-verify-action@v1
+  with:
+    head-ref: ${{ github.event.pull_request.head.sha }}
+    base-ref: ${{ github.event.pull_request.base.sha }}
+    source: notes
+    matrixscroll-version: "0.2.6"
+    require-mode: emulated
+```
+
+Publish envelopes to git notes before review:
+
+```bash
+matrixscroll envelope-publish-notes --base origin/main --head HEAD
+git push origin refs/notes/matrixscroll
+```
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+- uses: SSX360/matrixscroll-verify-action@v1
+  with:
+    head-ref: ${{ github.event.pull_request.head.sha }}
+    base-ref: ${{ github.event.pull_request.base.sha }}
+    source: notes
+    matrixscroll-version: "0.2.6"
+    summary-output: provenance-summary.json
+```
+
+See [`docs/quickstart-git.md`](docs/quickstart-git.md) and
+[`examples/ci/protected-branch.yml`](examples/ci/protected-branch.yml).
+
+The `--require-mode`, `--trusted-keys`, and actor or delegation policy checks
+are available in the `0.2.x` line; the examples in this README pin `0.2.6`.
+
+## Why it is different from Sigstore
+
+Sigstore, GitHub artifact attestations, and SLSA answer "what was built in
+CI?" Matrix Scroll answers "who signed this commit before push?" The systems
+are complementary: Matrix Scroll signs commit envelopes at commit time, while
+artifact-attestation systems sign build outputs later in the delivery chain.
+
+Matrix Scroll does not compete with general authentication keys on their home
+field. Existing hardware roots can become Matrix Scroll signing backends only
+when they preserve the same pure Ed25519 byte contract.
+
+## Public proof links
+
+- Browser verifier: <https://matrixscroll.com/verify/>
+- Compare page: <https://matrixscroll.com/compare/>
+- Specification: [`SPEC.md`](SPEC.md)
+- Commit envelope schema: [`schemas/commit-envelope.v1.json`](schemas/commit-envelope.v1.json)
+- Whitepaper: [`docs/WHITEPAPER.md`](docs/WHITEPAPER.md)
+- Conformance vectors: [`vectors/`](vectors/)
+- GitHub Action: <https://github.com/SSX360/matrixscroll-verify-action>
+- Agentic AI controls: [`docs/AGENTIC_AI_SECURITY.md`](docs/AGENTIC_AI_SECURITY.md)
+- Site: <https://matrixscroll.com>
+- Reference device path: <https://matrixscroll.com/device/>
+
+## Python API
+
+```bash
+pip install "matrixscroll==0.2.6"
+```
+
+```python
+import matrixscroll
+
+print(matrixscroll.status())
+# {'schema': 'matrixscroll.identity.v1', 'available': True,
+#  'mode': 'emulated', 'device_id': 'MS-A3F2-9C81', ...}
+
+signed = matrixscroll.sign_manifest({"release": "v1.0.0", "artifacts": [...]})
+
+assert matrixscroll.verify_manifest(signed)
+```
+
+## CLI
+
+```bash
+$ matrixscroll status
+{
+  "available": true,
+  "device_id": "MS-A3F2-9C81",
+  "mode": "emulated",
+  "public_key": "...",
+  "schema": "matrixscroll.identity.v1"
+}
+
+$ matrixscroll sign release.json > release.signed.json
+$ matrixscroll verify release.signed.json
+{"device_id": "MS-A3F2-9C81", "mode": "emulated", "ok": true, "signed_at": "..."}
+```
+
+`matrixscroll verify` exits `0` on a valid signature and `2` on failure
+(tampered manifest, missing signature block, wrong schema or algorithm,
+mismatched device ID, malformed public key, unreadable file).
+
+## How it works
+
+```text
+your IDE / agent / CI
+         |
+         |  commit envelope, release manifest, evidence pack, SBOM
+         v
+matrixscroll.sign_manifest(...)  /  post-commit hook
+         |
+         |  canonical JSON (sorted keys, ASCII-escaped, no NaN,
+         |  signature block excluded from input)
+         v
+IdentityProvider          -->  Ed25519 signature
+(L1 emulated today,
+ SSX360 / SE050 roadmap)
+         |
+         v
+signed document  -->  matrixscroll.verify_manifest(...)
+                      (anyone, anywhere, offline)
+```
+
+Switch providers with `MATRIXSCROLL_MODE`. Hardware mode includes a USB CDC
+host transport preview and a mock path for CI; real SE050 signing still
+depends on device firmware validation. External-key backends stay out of the
+mainline until they can sign the same canonical bytes with Ed25519.
+
+## Compliance levels
+
+| Level | Provider | Backed by | Status |
+| ----- | -------- | --------- | ------ |
+| **L1** Emulated | `EmulatedProvider` | Software key, file-backed (0600) | Shipping |
+| **L2** Hardware | `HardwareProvider` | NXP SE050 secure element (SSX360) | In progress |
+| **L3** Attested | future | L2 + remote attestation | Roadmap |
+
+`status()` exposes the active level via the `mode` and `available` fields.
+
+## Storage and trust boundaries
+
+- Emulated key store: `~/.matrixscroll/device.json`
+  (override with `MATRIXSCROLL_HOME`).
+- The directory is created `0700`; the seed file is opened `0600` with
+  `O_CREAT|O_EXCL` so the private seed is never momentarily world-readable.
+- A corrupt or truncated store fails loud (`IdentityError`) rather than
+  silently minting a fresh identity.
+- The planned hardware path holds nothing private on disk; the seed is sealed
+  in the secure element.
+
+## Reference implementation, not the only one
+
+Matrix Scroll is a protocol. This Python package is the reference. We welcome
+implementations in Rust, Go, TypeScript, and embedded C. Run them against
+[`vectors/`](vectors/) to self-certify. See `CONTRIBUTING.md`.
+
+## Agentic AI guidance proof
+
+The repo includes a machine-readable control matrix at
+[`controls/agentic_ai_controls.json`](controls/agentic_ai_controls.json), an
+example bounded-agent evidence manifest at
+[`examples/agentic_ai_evidence_manifest.json`](examples/agentic_ai_evidence_manifest.json),
+and executable checks in `tests/test_agentic_guidance.py`.
+
+## License
+
+- Code: **Apache-2.0** (`LICENSE`).
+- Specification text (`SPEC.md`, `vectors/`): **CC0 1.0** - public domain.
+
+## Security
+
+See [`SECURITY.md`](SECURITY.md). Report vulnerabilities privately to
+**security@matrixscroll.com** or via a GitHub Security Advisory.

matrixscroll-0.2.6/docs/ADOPTER_KIT.md

@@ -0,0 +1,70 @@
+# Adopter Kit
+
+This page is for OSS maintainers, platform teams, and design-partner engineers
+who want to trial Matrix Scroll without changing their core workflow.
+
+## Best first-fit teams
+
+- OSS repos with active PR review and at least one protected branch
+- platform or DevSecOps teams evaluating agent-assisted coding controls
+- teams that already use GitHub Actions and can add one verification job
+
+## 15-minute pilot
+
+1. Install `matrixscroll==0.2.6` in one repo.
+2. Run `matrixscroll hook-install`.
+3. Make one agent-assisted commit and verify it locally.
+4. Publish notes with `matrixscroll envelope-publish-notes`.
+5. Add `SSX360/matrixscroll-verify-action@v1` to PR CI.
+
+## Suggested evaluation workflow
+
+```yaml
+name: Verify PR commit envelopes
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  verify-provenance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: SSX360/matrixscroll-verify-action@v1
+        with:
+          head-ref: ${{ github.event.pull_request.head.sha }}
+          base-ref: ${{ github.event.pull_request.base.sha }}
+          source: notes
+          matrixscroll-version: "0.2.6"
+          require-mode: emulated
+```
+
+## What to collect during the pilot
+
+- one passing local `envelope-verify`
+- one passing PR range check
+- one example of a failed verify after tampering or missing notes
+- reviewer feedback on whether actor / tool attribution is useful
+
+## Success criteria
+
+- the team can explain the difference between commit-time and artifact-time proof
+- the GitHub Action is understandable to the repo owner
+- the team can point to one real decision that the envelope data improved
+
+## What not to assume
+
+- L1 emulated mode is not a hardware root of trust
+- Matrix Scroll does not replace IAM or sandboxing
+- Matrix Scroll does not replace release-signing or artifact attestations
+
+## Public follow-through
+
+If a pilot works, publish one of these:
+
+- a short repo note describing the evaluation
+- a screenshot of the passing GitHub Action
+- a testimonial about why commit-time attribution mattered

matrixscroll-0.2.6/docs/CI_HARD_GATE.md

@@ -0,0 +1,49 @@
+# CI hard gate — Scroll Gate Phase C
+
+Enable required provenance on `SSX360/matrixscroll` after contributors can publish git notes.
+
+## 1. Repository variable
+
+```bash
+gh variable set ENFORCE_PROVENANCE --body true --repo SSX360/matrixscroll
+```
+
+When set, [`verify-manifest.yml`](.github/workflows/verify-manifest.yml) **fails** PRs missing `refs/notes/matrixscroll` envelopes.
+
+## 2. Branch protection
+
+In GitHub → Settings → Branches → `main`:
+
+- Require status check: **Verify Matrix Scroll manifest**
+- Require branches up to date before merging
+
+```bash
+gh api repos/SSX360/matrixscroll/branches/main/protection \
+  --method PUT \
+  -f required_status_checks[strict]=true \
+  -f required_status_checks[checks][][context]='Verify Matrix Scroll manifest' \
+  -f enforce_admins=false \
+  -f required_pull_request_reviews[required_approving_review_count]=0
+```
+
+Adjust review count to match your team policy.
+
+## 3. Contributor flow
+
+Every PR must:
+
+```bash
+matrixscroll envelope-publish-notes --base origin/main --head HEAD
+git push origin refs/notes/matrixscroll
+matrixscroll envelope-verify-range --base origin/main --head HEAD --source notes
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Rollback
+
+```bash
+gh variable set ENFORCE_PROVENANCE --body false --repo SSX360/matrixscroll
+```
+
+Soft gate resumes (warning only in Step Summary).