runspecimen 0.2.0rc9__tar.gz

runspecimen-0.2.0rc9/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "personal",
+  "interface": {
+    "displayName": "Personal"
+  },
+  "plugins": [
+    {
+      "name": "runspecimen",
+      "source": {
+        "source": "local",
+        "path": "./plugins/runspecimen"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

runspecimen-0.2.0rc9/.cursor/rules/runspecimen.mdc

@@ -0,0 +1,20 @@
+---
+description: Guard consequential local commands with RunSpecimen
+alwaysApply: false
+---
+
+When a user asks for a consequential, long-running, expensive, or provenance-
+sensitive local command, use the installed `runspecimen` CLI on `PATH`. Start
+with `doctor` and `validate`. Never type or pipe the `APPROVE` phrase; the user
+must complete `runspecimen approve --workspace … --contract …` in a real
+terminal. After approval, invoke `preflight`, `run`, `postflight`, then
+`runspecimen verify --workspace … --contract … --campaign-id … --run-id …`
+sequentially and stop on any refusal. Never bypass the CLI with RunSpecimen's
+internal test helpers. Explain that RunSpecimen is an orchestration/evidence
+layer and not an OS sandbox.
+
+When the user requests a visual view, launch only the loopback, read-only
+dashboard with `runspecimen dashboard --workspace … --contract … --open`.
+`dashboard` blocks in the foreground; background or detach it so the agent can
+keep running lifecycle commands. The dashboard cannot replace the real-terminal
+approval step.

runspecimen-0.2.0rc9/.cursor-plugin/marketplace.json

@@ -0,0 +1,21 @@
+{
+  "name": "runspecimen",
+  "owner": {
+    "name": "RunSpecimen Contributors"
+  },
+  "metadata": {
+    "description": "Run assurance for consequential local agent workloads",
+      "version": "0.2.0-rc.9"
+  },
+  "plugins": [
+    {
+      "name": "runspecimen",
+      "source": "plugins/runspecimen",
+      "description": "Guard serious local agent runs with approval, bounds, provenance, and receipts.",
+      "version": "0.2.0-rc.9",
+      "logo": "plugins/runspecimen/assets/runspecimen-logo.png",
+      "category": "Agent Orchestration",
+      "tags": ["safety", "provenance", "local automation"]
+    }
+  ]
+}

runspecimen-0.2.0rc9/CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+## 0.2.0rc9 - 2026-09-13
+
+### Security Hardening
+
+- **Abandoned runs are permanently terminal**: Abandoned run IDs cannot be
+  re-approved, preflighted, or executed. Predecessors with `refuse_if_failed`
+  now reject abandoned predecessors.
+
+- **Recovery status checks active leases**: `needs_recovery` is only true when
+  `phase=running` AND no active workspace lease exists. Prevents abandoning
+  runs that are still executing.
+
+- **Key storage hardening**: Key IDs are validated against a strict safe-ID
+  grammar. Path traversal attacks are blocked. Keys cannot be overwritten
+  without explicit rotation.
+
+- **Certificate validation before signing**: Sign command validates certificate
+  schema and recomputes `certificate_id` before signing. Rejects malformed or
+  tampered certificates.
+
+- **HMAC terminology corrected**: Documentation and CLI now accurately describe
+  HMAC-SHA256 as shared-secret authentication (not digital signatures). Anyone
+  with the key can both create and verify MACs.
+
+- **Interpreter provenance is truthful**: Configured interpreters must resolve
+  to executables and are fingerprinted. Missing or non-executable interpreters
+  cause hard failures. Library capture uses the interpreter (not the script).
+
+- **Environment values not persisted**: Raw environment variable values are
+  never stored in artifacts. Only variable names and domain-separated hashes
+  are recorded.
+
+- **Portable path identity**: Added helper for macOS /var vs /private/var
+  symlink aliasing in path comparisons.
+
+### Bug Fixes
+
+- Fixed macOS path-alias test failures using `os.path.realpath` comparisons.
+- Library capture explicitly reports unsupported platforms (non-Linux).
+
+## 0.2.0rc8 - 2026-09-10
+
+- Package the RunSpecimen logo in source and plugin archives and reference it
+  from the Cursor plugin and marketplace manifests.
+- Extend the release gate so missing plugin branding fails before publication.
+
+## 0.2.0rc7 - 2026-09-08
+
+- Made the installed-dashboard release smoke deterministic on macOS runners by hosting and probing the loopback server in one process.
+
+## 0.2.0rc6 - 2026-09-08
+
+- Replaced the release-gate dashboard startup log dependency with direct loopback HTTP readiness verification for reliable macOS checks.
+
+## 0.2.0rc5 - 2026-09-08
+
+- Make the offline release gate wait for dashboard startup without relying on
+  platform-specific pipe readiness notifications.
+
+## 0.2.0rc4 - 2026-09-07
+
+- Harden lifecycle supervision so inherited output pipes, timeouts, and
+  interruption all leave bounded captures and a terminal recorded state.
+- Bind approvals and receipts to the exact parsed contract bytes, reject unsafe
+  source-root symlinks, and recheck expiry at launch.
+- Make the local dashboard honest about recorded evidence versus live receipt
+  verification; reject cross-origin access, contract drift, and write requests.
+- Add a dashboard About panel plus User guide / FAQ links, `docs/ABOUT.md`, and
+  a `runspecimen about` command (docs URLs also appear in `doctor` and `--help`).
+- Add a fresh `init-demo` onboarding command and a clean-install release gate
+  for source archives, wheels, the dashboard, and the plugin package.
+
+## 0.2.0rc3 - 2026-09-04
+
+- Add a contract-scoped, loopback-only local dashboard that renders phase,
+  evidence, and the exact lifecycle commands for Codex and Cursor users.
+- Keep the dashboard read-only: it cannot approve or execute commands, so the
+  real-TTY approval and CLI enforcement boundaries remain intact.
+- Teach the Codex and Cursor adapters to launch the dashboard on request.
+
+## 0.2.0rc2 - 2026-09-03
+
+- Execute the exact absolute executable whose digest was approved, including
+  correct resolution of relative `PATH` entries against the contract working directory.
+- Reject unknown and duplicate contract fields so misspelled safety controls fail closed.
+- Add a native Cursor plugin manifest, marketplace metadata, packaged rule, and local-test docs.
+- Expand release checks to keep the Python, Codex, and Cursor package versions aligned.
+
+## 0.2.0rc1 - 2026-09-01
+
+- Bind approvals and receipts to the resolved executable SHA-256.
+- Remove stale lease-owner metadata and make status report only active holders.
+- Add `doctor` and `validate` readiness commands.
+- Add Codex plugin and Cursor rule adapters that preserve the TTY approval gate.
+- Add threat model, security policy, CI, release checks, and clean-install smoke tests.
+- Declare Apache-2.0 licensing and Python 3.9+ support.
+
+## 0.1.0 - 2026-08-24
+
+- Initial bounded-run engine with TTY approval, workspace lease, atomic state,
+  predecessor gating, postflight assertions, and tamper-evident receipts.

runspecimen-0.2.0rc9/LICENSE

@@ -0,0 +1,188 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. "Submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or otherwise designated in writing by the copyright owner as
+      "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 RunSpecimen Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

runspecimen-0.2.0rc9/MANIFEST.in

@@ -0,0 +1,24 @@
+include LICENSE
+include CHANGELOG.md
+include SECURITY.md
+include docs/ABOUT.md
+include docs/FAQ.md
+include docs/MARKET_AND_DISTRIBUTION.md
+include docs/PRODUCT_PLAN.md
+include docs/RELEASE_CHECKLIST.md
+include docs/THREAT_MODEL.md
+include docs/USER_GUIDE.md
+include examples/demo_contract.json
+include examples/showcase/README.md
+include examples/showcase/contract.json
+include examples/showcase/work/compute.py
+include work/compute.py
+include plugins/runspecimen/assets/runspecimen-logo.png
+recursive-include scripts *.py *.sh
+recursive-include tests *.py
+recursive-include plugins *.json *.md *.mdc *.py
+recursive-include .cursor *.mdc
+recursive-include .cursor-plugin *.json
+recursive-include .agents *.json
+prune examples/showcase/.runspecimen
+global-exclude __pycache__ *.py[cod] .DS_Store

runspecimen-0.2.0rc9/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: runspecimen
+Version: 0.2.0rc9
+Summary: Bounded, approved, tamper-evident local research/engineering runs
+Author: RunSpecimen Contributors
+License: Apache-2.0
+Keywords: agents,automation,provenance,safety,local-first
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# RunSpecimen
+
+RunSpecimen is a local safety and evidence layer for consequential agent-driven
+research and engineering commands. This repository contains the `0.2.0rc9`
+release candidate.
+
+## Core promise
+
+Exactly **one** approved, bounded run at a time, with:
+
+1. **Approved provenance** — interactive TTY approval binds contract, source, and resolved executable hashes with expiry
+2. **Crash-safe state** — atomic JSON state writes
+3. **Mandatory postflight** — successor runs refuse an unpostflighted / failed predecessor
+4. **Tamper-evident receipts** — append-only SHA-256 hash-chained event log + verifiable certificate
+
+No watchers, no recurring scheduler, no parallel workers.
+
+## Requirements
+
+- Python 3.9+
+- POSIX (`fcntl` leases)
+- Stdlib only (no third-party dependencies)
+
+## Docs
+
+- [About](docs/ABOUT.md) — what RunSpecimen does, lifecycle, safety model, dashboard role
+- [User guide](docs/USER_GUIDE.md) — install, lifecycle, contracts, dashboard, plugins, troubleshooting
+- [FAQ](docs/FAQ.md) — vs CI/sandbox/agents, TTY approval, verify-after-clone, parallelism, receipts
+- [Product plan](docs/PRODUCT_PLAN.md) — invariants and roadmap
+- [Market and distribution](docs/MARKET_AND_DISTRIBUTION.md) — wedge, channels, commercial sequence
+- [Marketing pitches](docs/MARKETING_PITCHES.md) — honest one-liners, elevators, CTAs
+- [Grok tandem](docs/GROK_TANDEM.md) — external xAI Grok review log (Composio `GROK_*`)
+- [Threat model](docs/THREAT_MODEL.md) — trusted boundary and residual risks
+
+## Install
+
+```bash
+python3 -m pip install .
+```
+
+For development, prefer the bootstrap. It pins `setuptools>=77` and performs
+a regular local install; this avoids an editable-install edge case in some
+Python builds where the command is created but cannot import the package:
+
+```bash
+sh scripts/bootstrap_dev.sh
+```
+
+Or manually: `python3 -m pip install --upgrade 'setuptools>=77' wheel` then
+`python3 -m pip install --no-build-isolation .`. Stock setuptools before 77
+rejects the project metadata used by `scripts/release_check.py`. Re-run the
+install after source edits.
+
+Check the host and contract before approval:
+
+```bash
+runspecimen doctor --workspace .
+runspecimen validate --workspace . --contract examples/demo_contract.json
+```
+
+Create a fresh, unapproved demo workspace without modifying an existing
+directory:
+
+```bash
+runspecimen init-demo --workspace ./runspecimen-demo
+```
+
+## Typical sequence
+
+```bash
+# 1) Bind approval on a real TTY (refuses pipes/CI without a TTY)
+runspecimen approve --workspace . --contract examples/demo_contract.json
+
+# 2) Optional explicit preflight
+runspecimen preflight --workspace . --contract examples/demo_contract.json
+
+# 3) Execute one bounded run (reacquires lease + rechecks under lease)
+runspecimen run --workspace . --contract examples/demo_contract.json
+
+# 4) Assert outcomes and issue certificate (required before a successor)
+runspecimen postflight --workspace . --contract examples/demo_contract.json
+
+# 5) Verify receipts (requires contract; rehashes live contract+source+runtime)
+runspecimen verify --workspace . --contract examples/demo_contract.json \
+  --campaign-id demo-campaign --run-id run-001
+runspecimen status --workspace . --campaign-id demo-campaign --run-id run-001
+```
+
+## Local dashboard for Codex and Cursor users
+
+Open a contract-scoped dashboard from a terminal, or ask the installed Codex or
+Cursor RunSpecimen integration to do so:
+
+```bash
+runspecimen dashboard --workspace . --contract examples/demo_contract.json --open
+```
+
+`dashboard` blocks in the foreground while it serves HTTP. Background it
+(`&`), detach it, or use a separate terminal if you still need the shell for
+`approve` / lifecycle commands (agents should not wait on it in the main turn).
+
+It binds only to `127.0.0.1`, has no remote service or telemetry, and is
+read-only: it shows an About overview, the current phase, approval/lease/receipt
+evidence, and the exact lifecycle commands. It cannot approve or execute a run.
+This keeps the real-TTY approval gate and the CLI enforcement boundary intact
+while making the workflow visible in the browser. Docs links open the published
+About, User guide, and FAQ on GitHub. CLI shortcut: `runspecimen about`.
+
+### Showcase receipt
+
+`examples/showcase/` holds a regeneratable postflight receipt with
+`outputs/result.json`. Verify it with:
+
+```bash
+runspecimen verify --workspace examples/showcase \
+  --contract examples/showcase/contract.json \
+  --campaign-id showcase-campaign --run-id run-001
+```
+
+Refresh without a TTY (uses the library test hook `skip_tty_check`; not for
+production approvals): `python3 scripts/refresh_showcase.py`. Interactive TTY
+path: `scripts/demo_rc.sh`.
+
+Any local `/.runspecimen/runs/demo-campaign/run-001` left from earlier RCs is
+**historical / pre-`runtime` certificate** and is **not** verifiable on rc2.
+
+## Contract surface (v1)
+
+See `examples/demo_contract.json`. Important fields:
+
+| Field | Role |
+| --- | --- |
+| `argv` | Executed as an argument vector (`shell=False` always) |
+| `source.roots` / `excludes` | Deterministic source hashing / provenance |
+| `outputs.required` | Must be absent at preflight; present at postflight when required |
+| `caps.*` | Wall timeout + bounded stdout/stderr capture (hard tool maxima apply) |
+| `approval.ttl_sec` | Approval expiry bound into the approval document |
+| `predecessor` | Gate on prior run postflight / failure |
+| `postflight.*` | Exit code, output existence/SHA, JSON field equality, source unchanged |
+
+Every path involved in an output existence, SHA-256, or JSON assertion must be
+absent before launch and is hashed into the receipt after it passes.
+
+## State layout
+
+Per run under `{workspace}/.runspecimen/runs/{campaign_id}/{run_id}/`:
+
+- `approval.json` — bound hashes + expiry
+- `state.json` — atomic phase document
+- `events.jsonl` — hash-chained append-only log (`events.append.lock` serializes appends)
+- `stdout.capture` / `stderr.capture` — bounded captures
+- `certificate.json` — postflight receipt
+
+Workspace-wide execution lease: `{workspace}/.runspecimen/execution.lock` (held by
+approve/preflight/run/postflight; status is read-only).
+
+## New in rc9: Missing features implemented
+
+### Crash recovery with audited human decisions
+
+When a run crashes mid-execution, use the new recovery commands:
+
+```bash
+# Check if a run needs recovery
+runspecimen recovery-status --workspace . --campaign-id demo --run-id run-001
+
+# Abandon a crashed run (TTY confirmation required)
+runspecimen abandon --workspace . --campaign-id demo --run-id run-001
+```
+
+### Authenticated receipts (shared-secret)
+
+Authenticate certificates with local HMAC keys for tamper detection:
+
+```bash
+# Generate an authentication key
+runspecimen keygen --workspace .
+
+# List available keys
+runspecimen list-keys --workspace .
+
+# Authenticate a certificate (creates .signed.json with MAC)
+runspecimen sign --workspace . --key-id <key-id> --certificate path/to/certificate.json
+
+# Verify an authenticated certificate
+runspecimen verify-signature --workspace . --key-id <key-id> --signed path/to/certificate.signed.json
+```
+
+**Shared-secret limitation**: HMAC-SHA256 uses the same key for authentication
+and verification. Anyone with the key can forge certificates. For independent
+third-party verification without sharing secrets, use asymmetric cryptography.
+
+### Extended runtime provenance
+
+Contracts now support a `runtime` field for enhanced provenance binding:
+
+```json
+{
+  "runtime": {
+    "env_allowlist": ["PATH", "HOME", "PYTHONPATH"],
+    "interpreter": "/usr/bin/python3",
+    "capture_libs": true
+  }
+}
+```
+
+This binds environment variables, interpreter, and optionally linked libraries
+into the certificate's `runtime_id`.
+
+## Release-candidate limitations
+
+- Authenticated receipts use HMAC-SHA256 shared-secret MACs (MVP). This provides
+  tamper detection but NOT digital signatures: anyone with the key can forge
+  certificates. Production deployments should upgrade to Ed25519/RSA via
+  optional dependencies for true asymmetric signatures with non-repudiation.
+- The executed payload is not sandboxed and CPU, memory, network, filesystem,
+  and child-process limits are not yet enforced. The current hard bounds are one
+  workspace run, wall-clock duration, and captured output size.
+- The resolved executable or interpreter is automatically hashed. Native
+  libraries, environment variables, and input datasets still need to be placed
+  in `source.roots` or otherwise asserted by the workload.
+- This release is licensed under Apache-2.0. The CLI remains the enforcement
+  boundary; Codex and Cursor integrations are constrained adapters to it.
+
+## Non-goals
+
+- **Not an OS sandbox.** Process groups, wall clocks, and path containment are orchestration controls, not a security boundary against a hostile payload.
+- **Finite computation is not proof.** A green postflight and a valid certificate mean the approved contract ran under recorded provenance and assertions passed — not that the scientific/engineering claim is true.
+- **Not a job scheduler.** No cron, no watchers, no fan-out workers, no multi-run parallelism inside one lease domain.
+- **Not a remote execution fabric.** Local workspace only.
+
+## Tests
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+For the complete release-candidate gate, run `python3 scripts/release_check.py`.
+Day-to-day usage: [about](docs/ABOUT.md), [user guide](docs/USER_GUIDE.md), and [FAQ](docs/FAQ.md).
+Before sensitive work: [threat model](docs/THREAT_MODEL.md),
+[release checklist](docs/RELEASE_CHECKLIST.md), and [security policy](SECURITY.md).