matrixscroll 0.1.0__tar.gz → 0.2.0__tar.gz

matrixscroll-0.2.0/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+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.
+
+### Changed
+- Clarified public README and package metadata: v0.1.x ships a software root of
+  trust; SSX360/NXP SE050 hardware signing is the compatible reference-device
+  path in progress.
+- Replaced a direct PDF citation that may return `403` from some environments
+  with resolvable official agency pages for the joint agentic-AI guidance.
+- Added regression checks so PyPI-facing metadata avoids over-strong hardware
+  availability claims.
+
+## [0.1.0] - 2026-06-19
+
+Initial public release. Extracted from the SSX360 reference implementation.
+
+### Added
+- `EmulatedProvider` — software Ed25519 root of trust backed by a local key
+  store at `~/.matrixscroll/device.json` (override with `MATRIXSCROLL_HOME`).
+  Private seed is written 0600 at file-create time (no write-then-chmod race).
+- `HardwareProvider` — typed stub for the NXP SE050 secure element; reports
+  `is_available()` honestly so read-only surfaces can render without crashing
+  before the SE050 transport ships.
+- `status()` — soft status surface returning `available`/`reason` without
+  raising; `identity_info()` retains the loud-failure behavior used by signing.
+- `sign_manifest()` / `verify_manifest()` — manifest-level helpers using a
+  deterministic canonical JSON encoding (sorted keys, ASCII-escaped, NaN
+  rejected, `signature` block excluded).
+- `matrixscroll` console script (`status` / `verify` / `sign`) for field
+  debugging and release-evidence verification without a host application.
+- Conformance test vectors under `vectors/` for third-party implementations.
+
+### Protocol
+- Identity schema: `matrixscroll.identity.v1`.
+- Signature schema: `matrixscroll.signature.v1`.
+- Algorithm: `ed25519`.
+- 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.0 → matrixscroll-0.2.0}/CONTRIBUTING.md

@@ -15,8 +15,8 @@ well-tested, spec-aware."
 - **No new runtime dependencies** without discussion in an issue first. The
   surface area of a cryptographic SDK should stay tight.
 - **Signed commits preferred.** Use `git config commit.gpgsign true` or an SSH
-  signing key. Once the SSX360 device ships, hardware-signed commits are the
-  preferred default.
+  signing key. Once the SSX360 device ships, hardware-backed commit signing is
+  the preferred default.
 
 ## Development setup
 

{matrixscroll-0.1.0 → matrixscroll-0.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: matrixscroll
-Version: 0.1.0
-Summary: Open protocol for hardware-signed AI-assisted code (Ed25519 root of trust, software emulator + SSX360 reference device).
+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
 Project-URL: Source, https://github.com/SSX360/matrixscroll
@@ -31,23 +31,27 @@ 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
 
-**Open protocol for hardware-signed AI-assisted code.**
+**Open protocol for signed AI-assisted code provenance.**
 
-Every AI-generated change in your IDE gets cryptographically signed by an
-Ed25519 key sealed in a hardware root of trust. Anyone can verify the result
-offline with a public key and 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.
 
 - 📜 **Spec:** [`SPEC.md`](SPEC.md) — wire format, canonical encoding, schemas.
 - 🛡 **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). Keys never leave the provider.
+- 🔐 **Algorithm:** Ed25519 (RFC 8032). Private keys are never exposed by the SDK API.
 - 🧪 **Conformance vectors:** [`vectors/`](vectors/) — for non-Python implementations.
 - 🌐 **Site:** <https://matrixscroll.com>
-- 🔧 **Reference device:** [SSX360](https://matrixscroll.com/device) (NXP SE050).
+- 🔧 **Reference device:** [SSX360](https://matrixscroll.com/device) (NXP SE050 hardware path in progress).
 
 ```bash
 pip install matrixscroll
@@ -70,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
@@ -113,8 +146,10 @@ parsing the output.
                          (anyone, anywhere, offline)
 ```
 
-The same Python API serves the local software emulator and the physical
-SSX360 device. Switch with the `MATRIXSCROLL_MODE` environment variable.
+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.
 
 ## Compliance levels
 
@@ -136,8 +171,8 @@ read-only dashboards can render before the hardware path is wired.
   a race cannot silently clobber an existing key store.
 - A corrupt or truncated store **fails loud** (`IdentityError`) rather than
   silently minting a fresh identity. Identity rotation is an explicit operation.
-- The hardware path holds nothing private on disk — the seed is sealed in the
-  secure element.
+- 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.
 
 ## Reference implementation, not the only one
 

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

@@ -1,18 +1,20 @@
 # Matrix Scroll
 
-**Open protocol for hardware-signed AI-assisted code.**
+**Open protocol for signed AI-assisted code provenance.**
 
-Every AI-generated change in your IDE gets cryptographically signed by an
-Ed25519 key sealed in a hardware root of trust. Anyone can verify the result
-offline with a public key and 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.
 
 - 📜 **Spec:** [`SPEC.md`](SPEC.md) — wire format, canonical encoding, schemas.
 - 🛡 **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). Keys never leave the provider.
+- 🔐 **Algorithm:** Ed25519 (RFC 8032). Private keys are never exposed by the SDK API.
 - 🧪 **Conformance vectors:** [`vectors/`](vectors/) — for non-Python implementations.
 - 🌐 **Site:** <https://matrixscroll.com>
-- 🔧 **Reference device:** [SSX360](https://matrixscroll.com/device) (NXP SE050).
+- 🔧 **Reference device:** [SSX360](https://matrixscroll.com/device) (NXP SE050 hardware path in progress).
 
 ```bash
 pip install matrixscroll
@@ -35,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
@@ -78,8 +109,10 @@ parsing the output.
                          (anyone, anywhere, offline)
 ```
 
-The same Python API serves the local software emulator and the physical
-SSX360 device. Switch with the `MATRIXSCROLL_MODE` environment variable.
+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.
 
 ## Compliance levels
 
@@ -101,8 +134,8 @@ read-only dashboards can render before the hardware path is wired.
   a race cannot silently clobber an existing key store.
 - A corrupt or truncated store **fails loud** (`IdentityError`) rather than
   silently minting a fresh identity. Identity rotation is an explicit operation.
-- The hardware path holds nothing private on disk — the seed is sealed in the
-  secure element.
+- 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.
 
 ## Reference implementation, not the only one
 

{matrixscroll-0.1.0 → matrixscroll-0.2.0}/controls/agentic_ai_controls.json

@@ -1,8 +1,10 @@
 {
   "schema": "matrixscroll.agentic_ai_controls.v1",
   "sources": [
-    "https://media.defense.gov/2026/Apr/30/2003922823/-1/-1/0/CAREFUL%20ADOPTION%20OF%20AGENTIC%20AI%20SERVICES_FINAL.PDF",
+    "https://www.cyber.gov.au/business-government/secure-design/artificial-intelligence/careful-adoption-of-agentic-ai-services",
     "https://www.cisa.gov/resources-tools/resources/careful-adoption-agentic-ai-services",
+    "https://www.nsa.gov/aisc/",
+    "https://www.cyber.gc.ca/en/news-events/joint-guidance-careful-adoption-agentic-artificial-intelligence-services",
     "https://www.ncsc.govt.nz/protect-your-organisation/careful-adoption-of-agentic-ai-services/",
     "https://www.ncsc.gov.uk/blogs/thinking-carefully-before-adopting-agentic-ai"
   ],
@@ -13,7 +15,7 @@
       "guidance": "Adopt agentic AI incrementally; prefer tightly scoped pilots before connecting agents to real systems or sensitive data.",
       "matrixscroll_control": "Matrix Scroll signs bounded manifests rather than granting agents authority. The SDK records scope, task, reviewer, and policy fields as verifiable evidence.",
       "evidence_paths": ["examples/agentic_ai_evidence_manifest.json", "README.md"],
-      "goes_beyond": "Hardware-rooted signatures make the boundary review portable and independently auditable."
+      "goes_beyond": "Signed boundary reviews are portable and independently auditable; the planned hardware path can bind them to a physical signer."
     },
     {
       "id": "AAI-02",
@@ -29,7 +31,7 @@
       "guidance": "Use temporary credentials where possible and revoke elevated access when work completes.",
       "matrixscroll_control": "Manifests can require short-lived credential metadata and explicitly avoid embedding secrets. Tests enforce redaction-sensitive fields stay unsigned as labels only.",
       "evidence_paths": ["SECURITY.md", "examples/agentic_ai_evidence_manifest.json"],
-      "goes_beyond": "The signing key itself never appears as an application credential; hardware mode seals it in SSX360/SE050."
+      "goes_beyond": "The signing key itself never appears as an application credential; the planned hardware mode seals it in SSX360/SE050."
     },
     {
       "id": "AAI-04",
@@ -37,7 +39,7 @@
       "guidance": "Define who owns the agent, approves access, monitors behaviour, reviews incidents, and can stop it.",
       "matrixscroll_control": "Signed manifests carry owner, approver, reviewer, and break-glass contact fields as tamper-evident accountability evidence.",
       "evidence_paths": ["examples/agentic_ai_evidence_manifest.json", "docs/AGENTIC_AI_SECURITY.md"],
-      "goes_beyond": "Approvals can be bound to a physical root of trust instead of a mutable log entry."
+      "goes_beyond": "Approvals can be bound to a signature instead of a mutable log entry; the planned hardware path can bind that signature to a physical root of trust."
     },
     {
       "id": "AAI-05",
@@ -83,7 +85,7 @@
       "id": "AAI-10",
       "title": "Strong authentication and non-repudiation",
       "guidance": "Use strong authentication and avoid relying on weak internal safeguards for agent authority.",
-      "matrixscroll_control": "Ed25519 signatures bind agent evidence to a public key; hardware mode moves the private key into SSX360/SE050.",
+      "matrixscroll_control": "Ed25519 signatures bind agent evidence to a public key; the planned hardware mode moves the private key into SSX360/SE050.",
       "evidence_paths": ["SPEC.md", "matrixscroll/_core.py", "SECURITY.md"],
       "goes_beyond": "The private signing key is separated from agent runtime credentials and can be physically held or removed."
     },

{matrixscroll-0.1.0 → matrixscroll-0.2.0}/docs/AGENTIC_AI_SECURITY.md

@@ -4,13 +4,12 @@ This document maps Matrix Scroll to the joint guidance **Careful Adoption of
 Agentic AI Services** published by ASD's ACSC, CISA, NSA, the Canadian Centre
 for Cyber Security, NCSC-NZ, and NCSC-UK.
 
-Primary source:
-
-- <https://media.defense.gov/2026/Apr/30/2003922823/-1/-1/0/CAREFUL%20ADOPTION%20OF%20AGENTIC%20AI%20SERVICES_FINAL.PDF>
-
-Additional public mirrors/summaries used for traceability:
+Official public sources verified for traceability:
 
+- <https://www.cyber.gov.au/business-government/secure-design/artificial-intelligence/careful-adoption-of-agentic-ai-services>
 - <https://www.cisa.gov/resources-tools/resources/careful-adoption-agentic-ai-services>
+- <https://www.nsa.gov/aisc/>
+- <https://www.cyber.gc.ca/en/news-events/joint-guidance-careful-adoption-agentic-artificial-intelligence-services>
 - <https://www.ncsc.govt.nz/protect-your-organisation/careful-adoption-of-agentic-ai-services/>
 - <https://www.ncsc.gov.uk/blogs/thinking-carefully-before-adopting-agentic-ai>
 
@@ -40,7 +39,7 @@ The machine-readable control matrix lives at
 | AAI-07 | Monitoring and auditability | Signed manifests 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-10 | Strong authentication / non-repudiation | Ed25519 identity; SSX360 hardware mode keeps private keys out of agent runtimes. |
+| 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. |
 
@@ -51,8 +50,9 @@ Matrix Scroll adds a stronger evidence layer on top:
 
 1. **Offline verification** — auditors can verify a manifest without trusting
    Matrix Scroll servers, the original CI system, or the agent runtime.
-2. **Hardware-rooted provenance** — SSX360 L2 mode moves the signing key into a
-   secure element so the agent cannot exfiltrate it as a normal credential.
+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.
 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.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
+```