matrixscroll 0.2.1__tar.gz → 0.2.4__tar.gz

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

@@ -4,6 +4,43 @@ 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.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.
+
+### Added
+- **CLI policy flags** — `matrixscroll verify` and `matrixscroll envelope-verify` accept
+  `--require-mode` and `--trusted-keys` (JSON policy file), wired to
+  `verify_manifest_with_policy()`.
+
 ## [0.2.1] - 2026-06-20
 
 Windows and cross-platform commit envelope fix.
@@ -76,6 +113,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.1 → matrixscroll-0.2.4}/CONTRIBUTING.md

@@ -45,7 +45,7 @@ vectors are welcome.
 - [ ] Tests pass locally (`pytest -q`).
 - [ ] 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.1 → matrixscroll-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrixscroll
-Version: 0.2.1
+Version: 0.2.4
 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
@@ -37,15 +37,21 @@ Description-Content-Type: text/markdown
 
 # Matrix Scroll
 
-**Open protocol for signed AI-assisted code provenance.**
+**Signed provenance for agent-assisted Git commits — verify offline, one command.**
 
-Every AI-generated change in your IDE can be cryptographically signed by an
-Ed25519 identity and verified offline with a public key and one command. The
-v0.2.x reference implementation ships a well-tested software root of trust
-with Git commit-envelope hooks; SSX360/NXP SE050 hardware signing is the
-compatible reference-device path in progress.
+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.
 
-- 📜 **Spec:** [`SPEC.md`](SPEC.md) — wire format, canonical encoding, schemas.
+**Honest limits**
+
+- **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.
@@ -53,35 +59,10 @@ compatible reference-device path in progress.
 - 🌐 **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
@@ -94,13 +75,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.0"
+    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
@@ -130,49 +157,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
 
@@ -186,8 +209,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.1 → matrixscroll-0.2.4}/README.md

@@ -1,14 +1,20 @@
 # Matrix Scroll
 
-**Open protocol for signed AI-assisted code provenance.**
+**Signed provenance for agent-assisted Git commits — verify offline, one command.**
 
-Every AI-generated change in your IDE can be cryptographically signed by an
-Ed25519 identity and verified offline with a public key and one command. The
-v0.2.x reference implementation ships a well-tested software root of trust
-with Git commit-envelope hooks; SSX360/NXP SE050 hardware signing is the
-compatible reference-device path in progress.
+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.
 
-- 📜 **Spec:** [`SPEC.md`](SPEC.md) — wire format, canonical encoding, schemas.
+**Honest limits**
+
+- **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.
@@ -16,35 +22,10 @@ compatible reference-device path in progress.
 - 🌐 **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
@@ -57,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.0"
+    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
@@ -93,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
 
@@ -149,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.1 → matrixscroll-0.2.4}/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.1 → matrixscroll-0.2.4}/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.1 → matrixscroll-0.2.4}/docs/AGENTIC_AI_SECURITY.md

@@ -36,9 +36,9 @@ The machine-readable control matrix lives at
 | AAI-04 | Human accountability | Owner, approver, reviewer, break-glass contact, and kill-switch fields are signed. |
 | AAI-05 | Threat modeling | Threats are mapped to strict verification and tamper vectors. |
 | AAI-06 | Secure defaults / validation | Wrong schema, algorithm, device id, malformed key, NaN, and unsigned manifests fail closed. |
-| AAI-07 | Monitoring and auditability | Signed manifests are portable audit records verifiable offline. |
+| AAI-07 | Monitoring and auditability | Signed manifests and **commit envelopes** (`.git/matrixscroll/envelopes/<sha>.json`) are portable audit records verifiable offline. |
 | AAI-08 | Incident response / kill switch | CI/CLI verification exits non-zero; manifests include escalation and shutdown metadata. |
-| AAI-09 | Supply-chain management | Minimal deps, Dependabot, CI build verification, and conformance vectors. |
+| AAI-09 | Supply-chain management | Git post-commit hooks + CI verify-action; minimal deps; Dependabot; conformance vectors. |
 | AAI-10 | Strong authentication / non-repudiation | Ed25519 identity; the planned SSX360 hardware mode keeps private keys out of agent runtimes. |
 | AAI-11 | Governance and change control | CODEOWNERS + CI protect spec/core/vectors/security files. |
 | AAI-12 | Deception / prompt-injection resilience | Trust is verified after agent action; model text cannot forge signatures. |
@@ -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
@@ -63,14 +63,12 @@ Matrix Scroll adds a stronger evidence layer on top:
 ## Recommended deployment pattern
 
 1. Define the agent task as a low-risk, bounded pilot.
-2. Create an evidence manifest like
+2. Install Git hooks (`matrixscroll hook-install`) and set `MATRIXSCROLL_ACTOR_TYPE=agent`.
+3. Create an evidence manifest like
    [`examples/agentic_ai_evidence_manifest.json`](../examples/agentic_ai_evidence_manifest.json).
-3. Have a human owner approve the resource/operation/timeframe scope.
-4. Sign the manifest with `matrixscroll sign`.
-5. Require `matrixscroll verify` in CI before the agent can act or before its
-   output can be accepted.
-6. Retain the signed manifest with logs, SBOM, model/provider metadata, and
-   incident-response records.
+4. Have a human owner approve the resource/operation/timeframe scope.
+5. Sign the manifest with `matrixscroll sign`; require `matrixscroll envelope-verify` on each agent commit in CI.
+6. Retain signed envelopes and manifests with logs, SBOM, and incident-response records.
 
 ## Residual risks outside SDK scope
 

matrixscroll-0.2.4/docs/COMPARISON.md

@@ -0,0 +1,84 @@
+# How Matrix Scroll Compares
+
+Matrix Scroll signs **Git commit envelopes** — cryptographic evidence of who (human, agent, CI) produced a change, attached inside the commit. This page is an honest map of adjacent tools. Most are **complementary**, not replacements.
+
+**Positioning in one line:** Sigstore and SLSA answer “what was built in CI?” Matrix Scroll answers “who signed this commit before push?”
+
+## At a glance
+
+| Tool | Layer | Signs commits? | Agent identity | Hardware root of trust | Open source |
+|------|-------|----------------|----------------|------------------------|-------------|
+| **Matrix Scroll** | Commit | Yes (envelope in commit) | Yes | Yes (SSX360 / SE050 path; emulated L1 today) | Protocol + SDK |
+| [agentmark](https://github.com/karta-oss/karta) | Commit + CI gate | Yes (manifest in message) | Yes (pipeline key) | No | Apache 2.0 |
+| [Alien Agent ID](https://github.com/alien-id) | Commit (git notes) | Yes | Yes (owner-bound via OIDC) | No | SDK on GitHub |
+| [ForgeProof](https://github.com/forgeproof/forgeproof) | File-level | No | Partial (model/provider) | No | Apache 2.0 |
+| [Sigstore / cosign](https://docs.sigstore.dev/) | Artifact / container | No | No | No (keyless OIDC) | Yes |
+| [GitHub artifact attestations](https://docs.github.com/en/actions/concepts/security/artifact-attestations) | CI artifact | No | No | No | Partial |
+| [SLSA](https://slsa.dev/) | Build provenance framework | No | No | N/A | Yes |
+| [in-toto](https://in-toto.io/) | Pipeline layout | No | No | Functionary keys | Yes |
+| [OpenSSF GUAC](https://github.com/guacsec/guac) | Aggregation graph | No | No | N/A | Yes |
+
+Runtime audit tools (Provedex, ProvenanceOne, etc.) log **what agents do at runtime** — useful, but they do not bind authorship to Git history.
+
+## Closest commit-level competitors
+
+### agentmark
+
+- **Similar:** Commit-time Ed25519 manifest, CI verification gate, EU AI Act Article 50 cited as a use case.
+- **Different:** Software pipeline keys (exfiltration risk). Matrix Scroll targets **hardware-sealed** Ed25519 (SSX360) with offline verify; emulated L1 ships today.
+- **Takeaway:** Strongest software-only peer. Matrix Scroll differentiates on tamper-resistant keys and commit-embedded envelopes.
+
+### Alien Agent ID
+
+- **Similar:** Ed25519 commit signing, public verification story.
+- **Different:** Owner binding via cloud OIDC/DPoP; proof bundles in git notes. Matrix Scroll emphasizes **offline verification** and dedicated hardware, not a hosted identity network.
+- **Takeaway:** Alien leads on human→agent delegation chains; Matrix Scroll leads on hardware non-repudiation without cloud dependency.
+
+### ForgeProof
+
+- **Similar:** Ed25519 + SHA-256 provenance for AI-assisted code.
+- **Different:** **Per-file receipts** before build, not commit envelopes. Provenance is a separate artifact; Matrix Scroll embeds evidence in every clone of the repo.
+- **Takeaway:** Complementary granularity (file vs commit); potential interop, not a fork in the road.
+
+## Established supply chain (CI / artifact)
+
+Sigstore, GitHub attestations, SLSA, in-toto, and GUAC secure **build outputs and pipeline steps**. They do not record which AI tool authored a line at commit time.
+
+Matrix Scroll envelopes can **feed** these systems (e.g., as in-toto link metadata or GUAC evidence) rather than compete with them.
+
+## What Matrix Scroll adds that others don’t combine
+
+1. **Commit-time** signing (not post-build artifact attestation)
+2. **Agent/human actor** in the envelope schema
+3. **Hardware root of trust** path (SSX360 / NXP SE050) plus emulated dev mode today
+4. **Offline verify** — `matrixscroll verify` or [matrixscroll.com/verify](https://matrixscroll.com/verify)
+
+No single competitor listed above combines all four today.
+
+## Honest gaps (what we’re still building)
+
+- **CI gate:** Scroll Gate ships in **0.2.3+** — PR commit-range verification via `envelope-verify-range`, git notes transport (`refs/notes/matrixscroll`), and filesystem bundles. [`matrixscroll-verify-action`](https://github.com/SSX360/matrixscroll-verify-action) supports `head-ref`/`base-ref` range mode with agent/human counts.
+- **Owner/delegation attestation:** Optional `delegation` block in commit envelope schema (**0.2.4+**); see [`delegation-attestation-rfc.md`](delegation-attestation-rfc.md). Alien still leads on OIDC/DPoP owner binding.
+- **Multi-agent commits:** Multiple actors in one envelope — on the roadmap.
+- **Rekor / transparency log:** Not shipped yet; would align with Sigstore ecosystem expectations.
+- **Hardware:** SSX360 reference device and Scroll Key retail are **in progress**; L1 emulated key is what you can use now.
+
+## When to use what
+
+| You need… | Reach for… |
+|-----------|------------|
+| Container/image signatures, Rekor log | Sigstore / cosign |
+| SLSA Level 3 build provenance on GitHub Actions | `slsa-github-generator` + artifact attestations |
+| Supply chain graph / SBOM aggregation | GUAC |
+| Prove an AI pipeline wrote code with no human edit path (software keys) | agentmark |
+| Bind agent commits to a hosted human identity chain | Alien Agent ID |
+| Per-file “which model wrote this file” receipts | ForgeProof |
+| **Hardware-backed, commit-embedded agent provenance with offline verify** | **Matrix Scroll** |
+
+## Further reading
+
+- Full research brief (internal): `research/competitive-landscape-2026-06.md` in the SSX360 launch kit
+- [Whitepaper](WHITEPAPER.md) — threat model and envelope design
+- [SPEC.md](../SPEC.md) — wire format and verification rules
+
+*Last updated: June 2026. Comparisons reflect public docs and OSS repos; contact security@matrixscroll.com for corrections.*