matrixscroll 0.2.2__tar.gz → 0.2.5__tar.gz

{matrixscroll-0.2.2 → matrixscroll-0.2.5}/CHANGELOG.md

@@ -4,6 +4,48 @@ 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.5] - 2026-06-24
+
+Post-HN 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.
+
+### Added
+- **Attribution policy** — `require_actor_types`, `deny_actor_types`,
+  `require_delegation_for_actor_types`, `verify_agent_scope` in `VerifyPolicy`.
+- **`delegation` block** in commit envelope schema with owner/approver/manifest pin.
+- **`delegation-attestation-rfc.md`**, IDE quickstarts (Cursor, Copilot, Claude Code),
+  branch-protection runbook, Rekor/GUAC bridge design doc.
+- **GitHub Step Summary** in verify-action range mode; fail-closed notes fetch.
+- **pre-push** SHA-bound verification; optional `publish_notes` in hook config.
+
+### Fixed
+- Empty commit ranges in `verify_envelope_range` now pass with `note: no commits in range`.
+
+## [0.2.3] - 2026-06-20
+
+Scroll Gate export MVP: PR commit-range verification with git notes and bundle transport.
+
+### Added
+- **`matrixscroll/gate.py`** — SHA-bound envelope verification, commit-range discovery,
+  filesystem bundle export, git notes publish/fetch, and range verification summaries.
+- **CLI commands** — `envelope-export`, `envelope-publish-notes`, `envelope-fetch-notes`,
+  and `envelope-verify-range` with policy flags and JSON summaries for CI.
+- **GitHub Action range mode** — `head-ref` / `base-ref` inputs for PR provenance gates
+  via notes or bundle sources.
+
 ## [0.2.2] - 2026-06-20
 
 Policy flags for CI and release gates.
@@ -85,6 +127,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.2.2]: https://github.com/SSX360/matrixscroll/releases/tag/v0.2.2
+[0.2.1]: https://github.com/SSX360/matrixscroll/releases/tag/v0.2.1
 [0.2.0]: https://github.com/SSX360/matrixscroll/releases/tag/v0.2.0
 [0.1.1]: https://github.com/SSX360/matrixscroll/releases/tag/v0.1.1
 [0.1.0]: https://github.com/SSX360/matrixscroll/releases/tag/v0.1.0

{matrixscroll-0.2.2 → matrixscroll-0.2.5}/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=cursor        # or your IDE / 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,10 +61,10 @@ 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 under `[Unreleased]`.
+- [ ] `CHANGELOG.md` updated with a dated version entry (see Keep a Changelog format).
 - [ ] `SPEC.md` updated if anything wire-format-related changed.
 - [ ] No private keys, no real device ids, and no fixtures generated by a
       production device in test data.

{matrixscroll-0.2.2 → matrixscroll-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrixscroll
-Version: 0.2.2
+Version: 0.2.5
 Summary: Open protocol for signing AI-assisted code provenance with Ed25519; shipping software root of trust with SSX360 hardware support in progress.
 Project-URL: Homepage, https://matrixscroll.com
 Project-URL: Documentation, https://matrixscroll.com/docs
@@ -32,7 +32,9 @@ Provides-Extra: dev
 Requires-Dist: build>=1.0; extra == 'dev'
 Requires-Dist: pytest>=7.4; extra == 'dev'
 Provides-Extra: git
+Provides-Extra: tpm
 Provides-Extra: yubikey
+Requires-Dist: python-pkcs11>=0.7; extra == 'yubikey'
 Description-Content-Type: text/markdown
 
 # Matrix Scroll
@@ -41,10 +43,17 @@ Description-Content-Type: text/markdown
 
 Matrix Scroll is a cryptographic evidence layer: when an AI agent (Cursor, Claude Code, Copilot, etc.) produces a commit, a signed **commit envelope** records actor, tool, and optional scope. Verify locally or in CI without trusting the IDE. The v0.2.x reference SDK ships an emulated Ed25519 root of trust with Git hooks; SSX360/NXP SE050 hardware signing is the compatible reference-device path in progress.
 
-Matrix Scroll is **not** an IAM system, agent sandbox, or prompt-injection filter — it complements those controls with tamper-evident signatures.
+**Honest limits**
 
-- 📜 **Spec:** [`SPEC.md`](SPEC.md) — wire format, canonical encoding, schemas.
+- **Shipping now:** L1 emulated Ed25519 software key; Git post-commit hooks; Scroll Gate PR verification (0.2.3+); delegation attestation schema (0.2.4+)
+- **In progress:** SSX360 SE050 hardware provider; YubiKey PKCS#11 bridge
+- **Not:** IAM, sandbox, prompt-injection filter, or agent runtime
+
+- 📜 **Spec:** [`SPEC.md`](SPEC.md) — wire format, canonical encoding, document types.
+- 📋 **Commit envelope schema:** [`schemas/commit-envelope.v1.json`](schemas/commit-envelope.v1.json)
 - 📄 **Whitepaper:** [`docs/WHITEPAPER.md`](docs/WHITEPAPER.md) — why Git commits, implementation guide.
+- ⚖️ **Comparison:** [`docs/COMPARISON.md`](docs/COMPARISON.md) — vs Sigstore, agentmark, Alien, ForgeProof.
+- 💬 **Support:** [`SUPPORT.md`](SUPPORT.md) — issues, Discussions, security contact.
 - 🛡 **Agentic AI controls:** [`docs/AGENTIC_AI_SECURITY.md`](docs/AGENTIC_AI_SECURITY.md)
   maps Matrix Scroll to the joint *Careful Adoption of Agentic AI Services* guidance.
 - 🔐 **Algorithm:** Ed25519 (RFC 8032). Private keys are never exposed by the SDK API.
@@ -52,35 +61,10 @@ Matrix Scroll is **not** an IAM system, agent sandbox, or prompt-injection filte
 - 🌐 **Site:** <https://matrixscroll.com>
 - 🔧 **Reference device:** [SSX360](https://matrixscroll.com/device) (NXP SE050 hardware path in progress).
 
-```bash
-pip install matrixscroll
-```
-
-## Quickstart
-
-```python
-import matrixscroll
-
-# What identity is active on this machine?
-print(matrixscroll.status())
-# {'schema': 'matrixscroll.identity.v1', 'available': True,
-#  'mode': 'emulated', 'device_id': 'MS-A3F2-9C81', ...}
-
-# Sign anything (a release manifest, a commit envelope, a SBOM, an evidence pack)
-signed = matrixscroll.sign_manifest({"release": "v1.0.0", "artifacts": [...]})
-
-# Verify, anywhere, offline
-assert matrixscroll.verify_manifest(signed)
-```
-
 ## Agent provenance for Git commits
 
-When an AI agent (Cursor, Claude Code, Copilot, etc.) produces a commit, Matrix
-Scroll attaches a signed **commit envelope** with actor, tool, and scope metadata.
-Verify in CI without trusting the IDE.
-
 ```bash
-pip install matrixscroll
+pip install "matrixscroll>=0.2.1"
 matrixscroll hook-install
 
 export MATRIXSCROLL_ACTOR_TYPE=agent
@@ -93,13 +77,59 @@ 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
+### CI verify (single manifest)
 
 ```yaml
 - uses: SSX360/matrixscroll-verify-action@v1
   with:
     manifest: examples/agentic_ai_evidence_manifest.signed.json
-    matrixscroll-version: "0.2.2"
+    matrixscroll-version: "0.2.4"
+    require-mode: emulated
+```
+
+### Scroll Gate (PR commit range)
+
+Developers publish envelopes to git notes before PR 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.4"
+    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).
+
+Policy flags (`--require-mode`, `--trusted-keys`, actor/delegation policy) ship in **0.2.2+**.
+
+## Quickstart (Python API)
+
+```bash
+pip install "matrixscroll>=0.2.1"
+```
+
+```python
+import matrixscroll
+
+print(matrixscroll.status())
+# {'schema': 'matrixscroll.identity.v1', 'available': True,
+#  'mode': 'emulated', 'device_id': 'MS-A3F2-9C81', ...}
+
+# Sign a release manifest, commit envelope, evidence pack, or SBOM
+signed = matrixscroll.sign_manifest({"release": "v1.0.0", "artifacts": [...]})
+
+assert matrixscroll.verify_manifest(signed)
 ```
 
 ## CLI
@@ -129,49 +159,45 @@ parsing the output.
 ```
    your IDE / agent / CI
             │
-            │  manifest (release, commit, evidence pack, SBOM, anything)
+            │  commit envelope, release manifest, evidence pack, SBOM
             ▼
-   matrixscroll.sign_manifest(...)
+   matrixscroll.sign_manifest(...)  /  post-commit hook
             │
             │  canonical JSON  (sorted keys, ASCII-escaped, no NaN,
             │                   signature block excluded from input)
             ▼
    IdentityProvider          ──►  Ed25519 signature
-   (Emulated today,
-    SSX360 / SE050 tomorrow)
+   (L1 emulated today,
+    SSX360 / SE050 roadmap)
             │
             ▼
-   signed manifest  ──►  matrixscroll.verify_manifest(...)
+   signed document  ──►  matrixscroll.verify_manifest(...)
                          (anyone, anywhere, offline)
 ```
 
-The same Python API is designed to serve the local software emulator and the
-physical SSX360 device path. Switch with the `MATRIXSCROLL_MODE` environment
-variable; in v0.1.x, `hardware` mode reports unavailable until the SE050
-transport ships.
+Switch providers with `MATRIXSCROLL_MODE`. Hardware mode reports unavailable
+until the SE050 transport ships.
 
 ## Compliance levels
 
 | Level | Provider | Backed by | Status |
 | ----- | -------- | --------- | ------ |
 | **L1** Emulated | `EmulatedProvider` | Software key, file-backed (0600) | ✅ Shipping |
-| **L2** Hardware | `HardwareProvider` | NXP SE050 secure element (SSX360) | 🛠 Stage-0 prototype |
+| **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 so
-read-only dashboards can render before the hardware path is wired.
+`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 and
-  a race cannot silently clobber an existing key store.
+  `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. Identity rotation is an explicit operation.
+  silently minting a fresh identity.
 - The planned hardware path holds nothing private on disk — the seed is sealed
-  in the secure element. In v0.1.x, this path is a typed availability stub.
+  in the secure element.
 
 ## Reference implementation, not the only one
 
@@ -185,8 +211,7 @@ 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`. These prove each
-claim maps to repo evidence and that signed agent scope changes fail verify.
+and executable checks in `tests/test_agentic_guidance.py`.
 
 ## License
 

{matrixscroll-0.2.2 → matrixscroll-0.2.5}/README.md

@@ -4,10 +4,17 @@
 
 Matrix Scroll is a cryptographic evidence layer: when an AI agent (Cursor, Claude Code, Copilot, etc.) produces a commit, a signed **commit envelope** records actor, tool, and optional scope. Verify locally or in CI without trusting the IDE. The v0.2.x reference SDK ships an emulated Ed25519 root of trust with Git hooks; SSX360/NXP SE050 hardware signing is the compatible reference-device path in progress.
 
-Matrix Scroll is **not** an IAM system, agent sandbox, or prompt-injection filter — it complements those controls with tamper-evident signatures.
+**Honest limits**
 
-- 📜 **Spec:** [`SPEC.md`](SPEC.md) — wire format, canonical encoding, schemas.
+- **Shipping now:** L1 emulated Ed25519 software key; Git post-commit hooks; Scroll Gate PR verification (0.2.3+); delegation attestation schema (0.2.4+)
+- **In progress:** SSX360 SE050 hardware provider; YubiKey PKCS#11 bridge
+- **Not:** IAM, sandbox, prompt-injection filter, or agent runtime
+
+- 📜 **Spec:** [`SPEC.md`](SPEC.md) — wire format, canonical encoding, document types.
+- 📋 **Commit envelope schema:** [`schemas/commit-envelope.v1.json`](schemas/commit-envelope.v1.json)
 - 📄 **Whitepaper:** [`docs/WHITEPAPER.md`](docs/WHITEPAPER.md) — why Git commits, implementation guide.
+- ⚖️ **Comparison:** [`docs/COMPARISON.md`](docs/COMPARISON.md) — vs Sigstore, agentmark, Alien, ForgeProof.
+- 💬 **Support:** [`SUPPORT.md`](SUPPORT.md) — issues, Discussions, security contact.
 - 🛡 **Agentic AI controls:** [`docs/AGENTIC_AI_SECURITY.md`](docs/AGENTIC_AI_SECURITY.md)
   maps Matrix Scroll to the joint *Careful Adoption of Agentic AI Services* guidance.
 - 🔐 **Algorithm:** Ed25519 (RFC 8032). Private keys are never exposed by the SDK API.
@@ -15,35 +22,10 @@ Matrix Scroll is **not** an IAM system, agent sandbox, or prompt-injection filte
 - 🌐 **Site:** <https://matrixscroll.com>
 - 🔧 **Reference device:** [SSX360](https://matrixscroll.com/device) (NXP SE050 hardware path in progress).
 
-```bash
-pip install matrixscroll
-```
-
-## Quickstart
-
-```python
-import matrixscroll
-
-# What identity is active on this machine?
-print(matrixscroll.status())
-# {'schema': 'matrixscroll.identity.v1', 'available': True,
-#  'mode': 'emulated', 'device_id': 'MS-A3F2-9C81', ...}
-
-# Sign anything (a release manifest, a commit envelope, a SBOM, an evidence pack)
-signed = matrixscroll.sign_manifest({"release": "v1.0.0", "artifacts": [...]})
-
-# Verify, anywhere, offline
-assert matrixscroll.verify_manifest(signed)
-```
-
 ## Agent provenance for Git commits
 
-When an AI agent (Cursor, Claude Code, Copilot, etc.) produces a commit, Matrix
-Scroll attaches a signed **commit envelope** with actor, tool, and scope metadata.
-Verify in CI without trusting the IDE.
-
 ```bash
-pip install matrixscroll
+pip install "matrixscroll>=0.2.1"
 matrixscroll hook-install
 
 export MATRIXSCROLL_ACTOR_TYPE=agent
@@ -56,13 +38,59 @@ 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
+### CI verify (single manifest)
 
 ```yaml
 - uses: SSX360/matrixscroll-verify-action@v1
   with:
     manifest: examples/agentic_ai_evidence_manifest.signed.json
-    matrixscroll-version: "0.2.2"
+    matrixscroll-version: "0.2.4"
+    require-mode: emulated
+```
+
+### Scroll Gate (PR commit range)
+
+Developers publish envelopes to git notes before PR 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.4"
+    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).
+
+Policy flags (`--require-mode`, `--trusted-keys`, actor/delegation policy) ship in **0.2.2+**.
+
+## Quickstart (Python API)
+
+```bash
+pip install "matrixscroll>=0.2.1"
+```
+
+```python
+import matrixscroll
+
+print(matrixscroll.status())
+# {'schema': 'matrixscroll.identity.v1', 'available': True,
+#  'mode': 'emulated', 'device_id': 'MS-A3F2-9C81', ...}
+
+# Sign a release manifest, commit envelope, evidence pack, or SBOM
+signed = matrixscroll.sign_manifest({"release": "v1.0.0", "artifacts": [...]})
+
+assert matrixscroll.verify_manifest(signed)
 ```
 
 ## CLI
@@ -92,49 +120,45 @@ parsing the output.
 ```
    your IDE / agent / CI
             │
-            │  manifest (release, commit, evidence pack, SBOM, anything)
+            │  commit envelope, release manifest, evidence pack, SBOM
             ▼
-   matrixscroll.sign_manifest(...)
+   matrixscroll.sign_manifest(...)  /  post-commit hook
             │
             │  canonical JSON  (sorted keys, ASCII-escaped, no NaN,
             │                   signature block excluded from input)
             ▼
    IdentityProvider          ──►  Ed25519 signature
-   (Emulated today,
-    SSX360 / SE050 tomorrow)
+   (L1 emulated today,
+    SSX360 / SE050 roadmap)
             │
             ▼
-   signed manifest  ──►  matrixscroll.verify_manifest(...)
+   signed document  ──►  matrixscroll.verify_manifest(...)
                          (anyone, anywhere, offline)
 ```
 
-The same Python API is designed to serve the local software emulator and the
-physical SSX360 device path. Switch with the `MATRIXSCROLL_MODE` environment
-variable; in v0.1.x, `hardware` mode reports unavailable until the SE050
-transport ships.
+Switch providers with `MATRIXSCROLL_MODE`. Hardware mode reports unavailable
+until the SE050 transport ships.
 
 ## Compliance levels
 
 | Level | Provider | Backed by | Status |
 | ----- | -------- | --------- | ------ |
 | **L1** Emulated | `EmulatedProvider` | Software key, file-backed (0600) | ✅ Shipping |
-| **L2** Hardware | `HardwareProvider` | NXP SE050 secure element (SSX360) | 🛠 Stage-0 prototype |
+| **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 so
-read-only dashboards can render before the hardware path is wired.
+`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 and
-  a race cannot silently clobber an existing key store.
+  `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. Identity rotation is an explicit operation.
+  silently minting a fresh identity.
 - The planned hardware path holds nothing private on disk — the seed is sealed
-  in the secure element. In v0.1.x, this path is a typed availability stub.
+  in the secure element.
 
 ## Reference implementation, not the only one
 
@@ -148,8 +172,7 @@ 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`. These prove each
-claim maps to repo evidence and that signed agent scope changes fail verify.
+and executable checks in `tests/test_agentic_guidance.py`.
 
 ## License
 

{matrixscroll-0.2.2 → matrixscroll-0.2.5}/SECURITY.md

@@ -40,7 +40,8 @@ Out of scope:
 
 | Version | Status |
 | ------- | ------ |
-| 0.1.x   | Active development; security fixes shipped on patch releases. |
+| 0.2.x   | Active development; security fixes on patch releases. |
+| 0.1.x   | Legacy; upgrade to 0.2.x for Git hooks and commit envelopes. |
 
 Pre-1.0 there is no extended support window. Pin to a known-good version
 in production until 1.0.

{matrixscroll-0.2.2 → matrixscroll-0.2.5}/SPEC.md

@@ -13,6 +13,9 @@ Two schema identifiers are stamped into every artifact:
 - `matrixscroll.identity.v1` — identity descriptors (`identity_info`,
   `status`, the on-disk key store).
 - `matrixscroll.signature.v1` — the signature block attached to manifests.
+- `matrixscroll.commit_envelope.v1` — Git commit provenance document (see §10).
+- `matrixscroll.release_manifest.v1` and evidence-pack schemas — release and
+  audit artifacts (see §10).
 
 A breaking change to canonical encoding, signature layout, device id
 derivation, or algorithm choice **must** bump the relevant version. Minor
@@ -155,3 +158,41 @@ A conforming implementation MUST:
   as **invalid**.
 
 It SHOULD also publish its own cross-language vectors for community testing.
+
+## 10. Document types
+
+Beyond the generic signed-manifest pattern in §5–§6, v0.2.x defines typed
+documents. Each document carries a top-level `schema` string and a `signature`
+block conforming to §5.
+
+### 10.1 Commit envelope (`matrixscroll.commit_envelope.v1`)
+
+Binds provenance metadata to a Git commit. Used by post-commit hooks and
+`matrixscroll envelope-verify`.
+
+Required top-level fields:
+
+- `schema` — constant `"matrixscroll.commit_envelope.v1"`.
+- `commit` — normalized commit object (tree, parents, author, committer,
+  message; `expected_id` is informational for pre-sign drafts).
+- `provenance` — `actor_type` (`human` | `agent` | `ci`), `tool`, optional
+  `tool_version`, optional scope manifest reference.
+- `repository` — optional remote URL, branch, and repo name.
+- `signature` — per §5.
+
+Storage path (reference implementation):
+
+    .git/matrixscroll/envelopes/<40-char-commit-sha>.json
+
+JSON Schema: [`schemas/commit-envelope.v1.json`](schemas/commit-envelope.v1.json).
+Conformance vector: [`vectors/valid_commit_envelope.json`](vectors/valid_commit_envelope.json).
+
+### 10.2 Release manifest (`matrixscroll.release_manifest.v1`)
+
+Signed release metadata (version, tag, artifact list). JSON Schema:
+[`schemas/release-manifest.v1.json`](schemas/release-manifest.v1.json).
+
+### 10.3 Evidence pack
+
+Signed audit or agent-scope evidence. JSON Schema:
+[`schemas/evidence-pack.v1.json`](schemas/evidence-pack.v1.json).

{matrixscroll-0.2.2 → matrixscroll-0.2.5}/docs/AGENTIC_AI_SECURITY.md

@@ -52,7 +52,7 @@ Matrix Scroll adds a stronger evidence layer on top:
    Matrix Scroll servers, the original CI system, or the agent runtime.
 2. **Hardware-rooted provenance path** — the SSX360 L2 design moves the signing
    key into a secure element so the agent cannot exfiltrate it as a normal
-   credential. In v0.1.x, this is a typed provider path awaiting SE050 transport.
+   credential. Hardware mode is a typed provider path awaiting SE050 transport.
 3. **Fail-closed policy gates** — the CLI returns exit `2` for tampered,
    unsigned, malformed, wrong-schema, wrong-algorithm, or wrong-device-id input.
 4. **Executable conformance** — `vectors/` lets third-party implementations

matrixscroll-0.2.5/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).