matrixscroll 0.1.1__tar.gz → 0.2.0__tar.gz

{matrixscroll-0.1.1 → matrixscroll-0.2.0}/CHANGELOG.md

@@ -4,6 +4,30 @@ 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.0] - 2026-06-20
+
+Agent provenance release: Git commit envelopes, SDK module split, CI scaffolding.
+
+### Added
+- **Git integration** — `matrixscroll/git.py` with post-commit envelope signing
+  and pre-push verification for commits being pushed.
+- **Hook installer** — `matrixscroll hook-install` / `matrixscroll hook-status`
+  (hooks ship inside the wheel at `matrixscroll/hooks/`).
+- **Commit envelope schema** — `schemas/commit-envelope.v1.json` plus release and
+  evidence-pack schemas under `schemas/`.
+- **Signed examples** — `examples/*.signed.json` for CI and documentation.
+- **Agent demo** — `examples/demo/agent-commit-demo.sh` and signed-example generator.
+- **SDK split** — `canonical.py`, `manifest.py`, `policy.py`, `providers/` with
+  `_core.py` retained as a compatibility shim.
+- **Policy verification** — `verify_manifest_with_policy()` for mode and trusted-key gates.
+- **YubiKey prototype** — `providers/yubikey.py` boundary (`MATRIXSCROLL_MODE=yubikey`).
+- **CI** — `verify-manifest` workflow and protected-branch example using
+  `SSX360/matrixscroll-verify-action@v1`.
+
+### Changed
+- CLI adds `envelope`, `envelope-verify`, and hook subcommands.
+- Commit envelopes bind to the **actual** commit SHA via post-commit signing.
+
 ## [0.1.1] - 2026-06-19
 
 Copy and citation hardening patch. No protocol or API changes.
@@ -44,5 +68,6 @@ 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.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.1.1 → matrixscroll-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrixscroll
-Version: 0.1.1
+Version: 0.2.0
 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
@@ -31,6 +31,8 @@ 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: yubikey
 Description-Content-Type: text/markdown
 
 # Matrix Scroll
@@ -39,9 +41,9 @@ Description-Content-Type: text/markdown
 
 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.1.x reference implementation ships a well-tested software root of trust;
-SSX360/NXP SE050 hardware signing is the compatible reference-device path in
-progress.
+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.
 
 - 📜 **Spec:** [`SPEC.md`](SPEC.md) — wire format, canonical encoding, schemas.
 - 🛡 **Agentic AI controls:** [`docs/AGENTIC_AI_SECURITY.md`](docs/AGENTIC_AI_SECURITY.md)
@@ -72,6 +74,35 @@ signed = matrixscroll.sign_manifest({"release": "v1.0.0", "artifacts": [...]})
 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
+matrixscroll hook-install
+
+export MATRIXSCROLL_ACTOR_TYPE=agent
+export MATRIXSCROLL_TOOL=cursor
+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
+
+```yaml
+- uses: SSX360/matrixscroll-verify-action@v1
+  with:
+    manifest: examples/agentic_ai_evidence_manifest.signed.json
+    matrixscroll-version: "0.2.0"
+```
+
 ## CLI
 
 ```bash

{matrixscroll-0.1.1 → matrixscroll-0.2.0}/README.md

@@ -4,9 +4,9 @@
 
 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.1.x reference implementation ships a well-tested software root of trust;
-SSX360/NXP SE050 hardware signing is the compatible reference-device path in
-progress.
+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.
 
 - 📜 **Spec:** [`SPEC.md`](SPEC.md) — wire format, canonical encoding, schemas.
 - 🛡 **Agentic AI controls:** [`docs/AGENTIC_AI_SECURITY.md`](docs/AGENTIC_AI_SECURITY.md)
@@ -37,6 +37,35 @@ signed = matrixscroll.sign_manifest({"release": "v1.0.0", "artifacts": [...]})
 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
+matrixscroll hook-install
+
+export MATRIXSCROLL_ACTOR_TYPE=agent
+export MATRIXSCROLL_TOOL=cursor
+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
+
+```yaml
+- uses: SSX360/matrixscroll-verify-action@v1
+  with:
+    manifest: examples/agentic_ai_evidence_manifest.signed.json
+    matrixscroll-version: "0.2.0"
+```
+
 ## CLI
 
 ```bash

matrixscroll-0.2.0/docs/hardware-provider.md

@@ -0,0 +1,20 @@
+# SSX360 hardware provider (L2)
+
+**Status:** Stage-0 prototype — `HardwareProvider` reports unavailable until the
+NXP SE050 transport ships on the SSX360 reference device.
+
+## Planned behavior
+
+- `MATRIXSCROLL_MODE=hardware` selects the secure-element provider
+- Private keys never leave the SE050; no seed on disk
+- User-presence touch gating for protected-branch commits
+- Compatible with the same manifest and commit-envelope schemas as L1 emulated mode
+
+## Related docs
+
+- [`docs/yubikey-bridge.md`](yubikey-bridge.md) — bridge path before SSX360 GA
+- [`SPEC.md`](../SPEC.md) — wire format (unchanged for L2 signing algorithm)
+
+## Device
+
+Reference hardware: [matrixscroll.com/device](https://matrixscroll.com/device)

matrixscroll-0.2.0/docs/quickstart-git.md

@@ -0,0 +1,61 @@
+# Git Quickstart
+
+Matrix Scroll Git hooks attach a signed **commit envelope** to every local commit.
+
+## Install hooks
+
+```bash
+pip install matrixscroll
+matrixscroll hook-install
+matrixscroll hook-status
+```
+
+Hooks ship inside the Python wheel (`matrixscroll/hooks/`). No separate clone path
+is required for pip-installed users.
+
+## What happens on commit
+
+1. **post-commit** reads the new commit SHA and builds a commit envelope from `git show`
+2. The envelope is signed with your active Matrix Scroll identity
+3. The signed envelope is stored at `.git/matrixscroll/envelopes/<sha>.json`
+
+**pre-push** verifies envelopes only for commits being pushed (not every envelope
+ever stored locally).
+
+By default hooks run in **warn mode** (signing failures do not block commits).
+Enable enforce mode in `.git/matrixscroll/config.json`:
+
+```json
+{
+  "enforce": true,
+  "actor_type": "human",
+  "tool": "cursor"
+}
+```
+
+## Agent provenance
+
+Set environment variables before committing:
+
+```bash
+export MATRIXSCROLL_ACTOR_TYPE=agent
+export MATRIXSCROLL_TOOL=cursor
+export MATRIXSCROLL_AGENT_SCOPE=examples/agentic_ai_evidence_manifest.signed.json
+```
+
+## Verify in CI
+
+```bash
+matrixscroll verify .git/matrixscroll/envelopes/<commit-sha>.json
+matrixscroll envelope-verify <commit-sha>
+```
+
+Or use [`SSX360/matrixscroll-verify-action@v1`](https://github.com/SSX360/matrixscroll-verify-action).
+
+## Demo
+
+```bash
+bash examples/demo/agent-commit-demo.sh
+```
+
+See [spec](../superpowers/specs/2026-06-19-matrixscroll-git-design.md).

matrixscroll-0.2.0/docs/superpowers/plans/2026-06-19-ci-action-plan.md

@@ -0,0 +1,88 @@
+# CI Action Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Provide a zero-config GitHub Action that runs `matrixscroll verify` with CI-friendly exit codes.
+
+**Architecture:** Composite action installs matrixscroll from PyPI, runs verify on one or more manifest paths, optionally applies policy flags.
+
+**Tech Stack:** GitHub Actions, Python 3.10+, matrixscroll CLI
+
+---
+
+## Exit code contract
+
+| Code | Meaning | CI interpretation |
+|------|---------|-------------------|
+| 0 | Valid signature | Pass check |
+| 1 | Usage/config error | Fail workflow (misconfiguration) |
+| 2 | Verification failed | Fail workflow (tampered/invalid) |
+
+The action MUST propagate CLI exit codes unchanged (`set -e` in bash step).
+
+## Action inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `manifest` | yes | — | Path to signed manifest JSON |
+| `python-version` | no | `3.12` | Python for pip install |
+| `matrixscroll-version` | no | `latest` | Pin e.g. `0.1.1` for reproducibility |
+| `require-mode` | no | `` | Pass through to policy verify (v0.2.1) |
+| `trusted-keys` | no | `` | Path to trusted keys JSON (v0.2.1) |
+
+## Action outputs
+
+| Output | Description |
+|--------|-------------|
+| `ok` | `true` or `false` |
+| `device_id` | Signer device id from manifest |
+| `mode` | Provider mode (`emulated`, `hardware`, `yubikey`) |
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `matrixscroll-action/action.yml` | Composite action definition |
+| `matrixscroll-action/README.md` | Usage docs |
+| `matrixscroll/.github/workflows/verify-manifest.yml` | Dogfood workflow |
+| `matrixscroll/examples/ci/protected-branch.yml` | Copy-paste template |
+
+## Protected branch pattern
+
+```yaml
+name: provenance
+on:
+  pull_request:
+    branches: [main]
+jobs:
+  verify-release-manifest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: SSX360/matrixscroll-verify-action@v1
+        with:
+          manifest: examples/release-manifest.signed.json
+```
+
+## Release verification pattern
+
+1. Build job signs release manifest, uploads artifact
+2. Verify job downloads artifact, runs action
+3. Deploy job requires verify job success
+
+## Task checklist
+
+- [x] Write action.yml composite action
+- [x] Add dogfood workflow in matrixscroll repo
+- [x] Add protected-branch example
+- [ ] Publish action repo and tag v1 (manual release step)
+- [ ] Add signed release-manifest to examples once v0.2.0 ships
+
+## Verification
+
+```bash
+cd matrixscroll
+pip install -e ".[dev]"
+pytest tests/test_cli.py -v
+matrixscroll verify examples/agentic_ai_evidence_manifest.json  # expect exit 2 unsigned
+```

matrixscroll-0.2.0/docs/superpowers/plans/2026-06-19-sdk-refactor-plan.md

@@ -0,0 +1,166 @@
+# SDK Refactor Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Split the monolithic `_core.py` into focused modules while preserving the public API in `matrixscroll/__init__.py`.
+
+**Architecture:** Move crypto, canonical encoding, manifest signing, providers, and policy into separate modules. Keep `_core.py` as a thin compatibility shim that re-exports everything until v0.3.0.
+
+**Tech Stack:** Python 3.10+, cryptography, pytest
+
+---
+
+## Target module layout
+
+```
+matrixscroll/
+  __init__.py          # unchanged public API
+  _core.py             # compatibility re-exports (deprecated v0.3.0)
+  canonical.py         # deterministic JSON encoding
+  manifest.py          # sign_manifest / verify_manifest
+  policy.py            # policy-aware verification
+  errors.py            # IdentityError, VerificationError
+  git.py               # git hooks (v0.2.0)
+  providers/
+    __init__.py
+    base.py            # IdentityProvider ABC
+    emulated.py        # EmulatedProvider
+    hardware.py        # HardwareProvider stub
+    yubikey.py         # YubiKey bridge (optional extra)
+  cli.py
+  py.typed
+```
+
+## Public API contract (must not break)
+
+These symbols remain importable from `matrixscroll`:
+
+- Constants: `SCHEMA`, `SIGNATURE_SCHEMA`, `ALGORITHM`, `DEVICE_FILE`
+- Exceptions: `IdentityError`
+- Providers: `IdentityProvider`, `EmulatedProvider`, `HardwareProvider`
+- Functions: `store_dir`, `device_id`, `get_provider`, `identity_info`, `status`, `public_key_b64`, `sign`, `verify`, `sign_manifest`, `verify_manifest`
+
+## Task 1: Extract errors and constants
+
+**Files:**
+- Create: `matrixscroll/errors.py`
+- Create: `matrixscroll/constants.py`
+- Modify: `matrixscroll/_core.py`
+
+Move `IdentityError`, `SCHEMA`, `SIGNATURE_SCHEMA`, `ALGORITHM`, `DEVICE_FILE`, `SEED_LEN`, mode constants.
+
+## Task 2: Extract canonical encoding
+
+**Files:**
+- Create: `matrixscroll/canonical.py`
+- Modify: `matrixscroll/manifest.py`
+
+Move `_canonical()` → `canonical_bytes(payload: dict) -> bytes`.
+
+## Task 3: Extract manifest signing
+
+**Files:**
+- Create: `matrixscroll/manifest.py`
+
+Move `sign_manifest`, `verify_manifest`, keep importing `sign`/`verify` from providers layer.
+
+## Task 4: Extract providers
+
+**Files:**
+- Create: `matrixscroll/providers/base.py`
+- Create: `matrixscroll/providers/emulated.py`
+- Create: `matrixscroll/providers/hardware.py`
+- Create: `matrixscroll/providers/__init__.py`
+
+Move provider classes and `get_provider()`.
+
+## Task 5: Add policy module
+
+**Files:**
+- Create: `matrixscroll/policy.py`
+- Modify: `matrixscroll/cli.py`
+
+Add:
+
+```python
+@dataclass
+class VerifyPolicy:
+    require_mode: str | None = None
+    trusted_public_keys: set[str] | None = None
+    allowed_schemas: set[str] | None = None
+
+def verify_manifest_with_policy(manifest: dict, policy: VerifyPolicy) -> tuple[bool, str | None]:
+    ...
+```
+
+CLI flags (v0.2.1):
+
+```
+matrixscroll verify manifest.json --require-mode hardware --trusted-keys keys.json
+```
+
+## Task 6: Compatibility shim
+
+**Files:**
+- Modify: `matrixscroll/_core.py`
+
+Replace body with re-exports:
+
+```python
+from .canonical import canonical_bytes as _canonical
+from .manifest import sign_manifest, verify_manifest
+from .providers import EmulatedProvider, HardwareProvider, IdentityProvider, get_provider
+...
+```
+
+Add deprecation comment; remove shim in v0.3.0.
+
+## Task 7: Update tests
+
+**Files:**
+- Modify: `tests/test_core.py` — add imports from new modules
+- Create: `tests/test_policy.py`
+- Create: `tests/test_canonical.py`
+
+Run: `pytest -ra`
+
+## Task 8: Update packaging
+
+**Files:**
+- Modify: `pyproject.toml` — include `schemas/`, optional `[yubikey]` extra
+
+```toml
+[project.optional-dependencies]
+yubikey = []  # PKCS#11 deps added when bridge ships
+git = []
+```
+
+## Migration guide (for downstream consumers)
+
+| Before | After (preferred) |
+|--------|-------------------|
+| `from matrixscroll._core import _canonical` | `from matrixscroll.canonical import canonical_bytes` |
+| `verify_manifest(m)` | `verify_manifest_with_policy(m, policy)` for CI gates |
+| `MATRIXSCROLL_MODE=hardware` | unchanged |
+
+## Version bump
+
+- v0.2.0: git module, schemas, provider split (shim retained)
+- v0.2.1: policy CLI flags
+- v0.3.0: remove `_core.py` shim, add YubiKey extra
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| Import cycles | providers → manifest → canonical (one direction) |
+| Vector drift | run `tests/test_vectors.py` after every task |
+| Breaking private imports | document `_core` deprecation; grep GitHub for `_core` usage |
+
+## Verification checklist
+
+- [ ] `pytest` green
+- [ ] `matrixscroll status` unchanged output shape
+- [ ] All vectors pass
+- [ ] `pip install -e .` works
+- [ ] No new runtime deps without CONTRIBUTING discussion

matrixscroll-0.2.0/docs/superpowers/specs/2026-06-19-matrixscroll-git-design.md

@@ -0,0 +1,205 @@
+# matrixscroll-git — Design Spec
+
+**Date:** 2026-06-19  
+**Status:** Approved for v0.2.0 implementation  
+**Scope:** Local Git hooks, commit-envelope manifest, CLI extensions, CI verification contract
+
+## 1. Goal
+
+Attach a Matrix Scroll cryptographic provenance envelope to every Git commit made
+by a human or AI agent. Verify envelopes offline in CI without trusting the
+host IDE or agent runtime.
+
+This is the Day-1 beachhead: Git commits are standardized, high-consequence, and
+already support signing workflows.
+
+## 2. Non-goals (v0.2.0)
+
+- Replacing GPG/SSH commit signing (Matrix Scroll is additive metadata)
+- Remote attestation (L3) or hardware touch gating (L2 transport)
+- Server-side registry or enrollment APIs
+
+## 3. Commit envelope schema
+
+Schema id: `matrixscroll.commit_envelope.v1`
+
+See [`schemas/commit-envelope.v1.json`](../schemas/commit-envelope.v1.json) and
+[`examples/commit-envelope.json`](../../examples/commit-envelope.json).
+
+### Required fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `schema` | string | Constant `matrixscroll.commit_envelope.v1` |
+| `commit` | object | Git commit identity material |
+| `commit.tree` | string | Full tree SHA-1 hex |
+| `commit.parents` | string[] | Parent commit SHAs (empty for root) |
+| `commit.author` | object | `{name, email, date}` from commit object |
+| `commit.committer` | object | `{name, email, date}` from commit object |
+| `commit.message` | string | Raw commit message bytes as UTF-8 string |
+| `provenance` | object | Who/what produced the commit |
+| `provenance.actor_type` | string | `human` \| `agent` \| `ci` |
+| `provenance.tool` | string | e.g. `cursor`, `claude-code`, `git-cli` |
+| `provenance.tool_version` | string | Optional semver or build id |
+| `provenance.agent_scope` | string | Optional reference to signed agent evidence manifest |
+| `repository` | object | `{name, remote_url}` best-effort from git config |
+| `signature` | object | Matrix Scroll signature block (see SPEC.md §5) |
+
+### Signing input
+
+The envelope is signed with `sign_manifest()` using canonical JSON rules from
+SPEC.md §4. The top-level `signature` block is excluded from the signing input.
+
+### Commit binding
+
+The envelope MUST be bound to the commit it describes:
+
+```
+commit_id = SHA-1( commit_object_bytes )
+```
+
+The hook computes `commit_id` from the staged tree + message at commit time
+(before the commit object exists) using:
+
+```
+tree = git write-tree
+commit_body = git commit-tree $tree -p $parents -m "$message"
+commit_id = SHA-1(commit_body)  # computed, not yet committed
+```
+
+The envelope stores `commit.expected_id` (the computed SHA). After commit,
+`commit.actual_id` is written to `.git/matrixscroll/envelopes/<sha>.json`.
+
+## 4. Storage layout
+
+```
+.git/matrixscroll/
+  config.json          # hook config (require_envelope, actor defaults)
+  envelopes/
+    <40-char-sha>.json # one signed envelope per commit
+```
+
+Envelopes are **local provenance artifacts**. They may be exported to CI as
+build artifacts or pushed to a release evidence bucket; they are not committed
+to the source tree by default.
+
+## 5. CLI commands
+
+Extend the `matrixscroll` CLI:
+
+| Command | Description | Exit codes |
+|---------|-------------|------------|
+| `matrixscroll hook install` | Install pre-commit + pre-push hooks | 0 ok, 1 error |
+| `matrixscroll hook uninstall` | Remove hooks | 0 ok |
+| `matrixscroll hook status` | JSON: installed, config, envelope count | 0 |
+| `matrixscroll envelope build` | Build envelope for staged commit (stdin/flags) | 0 ok, 2 fail |
+| `matrixscroll envelope verify <sha\|file>` | Verify envelope for commit | 0 pass, 2 fail |
+| `matrixscroll verify <file>` | *(existing)* verify any signed manifest | 0 pass, 2 fail |
+
+Environment variables (inherit from SDK):
+
+- `MATRIXSCROLL_MODE` — `emulated` (default) or `hardware`
+- `MATRIXSCROLL_HOME` — key store override
+- `MATRIXSCROLL_ACTOR_TYPE` — default `human` | `agent` | `ci`
+- `MATRIXSCROLL_TOOL` — default tool name for provenance block
+
+## 6. Hook behavior
+
+### pre-commit
+
+1. Read staged tree via `git write-tree`
+2. Build commit preview (parents from `HEAD`, message from `-F` or `-m`)
+3. Construct commit envelope manifest
+4. Sign with active provider via `sign_manifest()`
+5. Write envelope to `.git/matrixscroll/envelopes/<expected_id>.json`
+6. Exit 0 (never block commit on signing failure in v0.2.0 **warn mode**;
+   **enforce mode** exits 2)
+
+Config flag `enforce: true` blocks commits when signing fails.
+
+### pre-push
+
+1. For each commit being pushed not already on remote:
+   - Load envelope from `.git/matrixscroll/envelopes/<sha>.json`
+   - Run `verify_manifest()`
+2. Exit 2 if any envelope missing or invalid (when `enforce: true`)
+
+### prepare-commit-msg (optional, phase 2)
+
+Append `Matrix-Scroll-Envelope: <sha>` trailer to commit message for
+human-visible provenance pointer.
+
+## 7. CI verification contract
+
+CI MUST NOT parse free-text hook output. Use exit codes:
+
+| Exit code | Meaning |
+|-----------|---------|
+| 0 | Signature valid |
+| 1 | Usage / configuration error |
+| 2 | Verification failed (tampered, missing, wrong schema) |
+
+### GitHub Actions pattern
+
+```yaml
+- uses: actions/setup-python@v5
+  with:
+    python-version: "3.12"
+- run: pip install matrixscroll
+- run: matrixscroll verify evidence/commit-envelope.json
+```
+
+For protected branches, CI receives exported envelopes as artifacts from a
+prior build job or fetches them from object storage.
+
+Policy extensions (v0.2.1):
+
+```bash
+matrixscroll verify release.json \
+  --require-mode hardware \
+  --trusted-keys trusted-keys.json
+```
+
+## 8. Error handling
+
+| Failure | Hook (warn) | Hook (enforce) | CI |
+|---------|-------------|----------------|-----|
+| Provider unavailable | warn, continue | exit 2 | exit 2 |
+| Corrupt envelope | warn | exit 2 | exit 2 |
+| Tampered manifest | warn | exit 2 | exit 2 |
+| Missing envelope | warn | exit 2 | exit 2 |
+| Wrong schema version | warn | exit 2 | exit 2 |
+
+## 9. Security considerations
+
+- Envelopes prove **who signed the provenance record**, not that Git's native
+  signature is valid. Pair with branch protection + required status checks.
+- Emulated mode (L1) is suitable for dev; release branches SHOULD require
+  `mode: hardware` once L2 ships.
+- Never store private keys in envelope files; only public key + signature.
+
+## 10. Test plan
+
+- Unit: envelope schema validation, commit_id computation
+- Integration: `hook install` → commit → envelope exists → `verify` passes
+- Tamper: modify envelope field → `verify` exits 2
+- Vectors: add `vectors/valid_commit_envelope.json` in v0.2.0
+
+## 11. Implementation files
+
+| File | Responsibility |
+|------|----------------|
+| `schemas/commit-envelope.v1.json` | JSON Schema |
+| `examples/commit-envelope.json` | Reference example |
+| `tools/git/install.py` | Hook installer |
+| `tools/git/hooks/pre-commit` | Pre-commit hook script |
+| `tools/git/hooks/pre-push` | Pre-push hook script |
+| `matrixscroll/git.py` | Python hook/envelope API (v0.2.0) |
+| `tests/test_git_envelope.py` | Tests |
+
+## 12. Rollout phases
+
+1. **v0.2.0-alpha:** warn-mode hooks, emulated signing, local envelopes
+2. **v0.2.0:** enforce-mode, GitHub Action, commit-envelope vectors
+3. **v0.2.1:** policy flags (`--require-mode`, trusted keys)
+4. **v0.3.0:** YubiKey bridge provider, hardware mode for release branches