Stability and support
What you can build on, how it may change, and how to verify a release.
ocra is an early 0.x release. This page lists the contracts scripts, CI and plugins can rely on, how they may change, and what support to expect.
Versions
ocra follows semantic versioning as it applies before 1.0:
- A patch release (0.1.x) fixes bugs and never changes a contract, except where a security fix cannot be made otherwise; the release notes then say so.
- A minor release (0.x.0) may change a contract, listed in the changelog. Where it can, the old form keeps working, with a warning, for at least one minor release before removal.
All packages share one version and release together.
Below, "0.x rule" means: a minor release may change it, and the changelog says how to adapt.
Contracts
| Contract | Where it is described |
|---|---|
| Commands, options and exit codes | CLI |
.ocra/config.json, .ocra/rules.json, .ocra/memory.json and the OCRA_* environment variables | Configuration, Rules |
The JSON report (--format json, report.json) and the --plan JSON | CLI. Both carry "version": 1; a version only gains optional fields and new values of a listed set, anything else is a new version. JSON Schemas for the report and the plan. For the plan, the JSON Schema file is the contract: no package exports a schema for it |
The SARIF output (--format sarif) | CLI. SARIF 2.1.0; rule ids, the ocra/v1 fingerprint key and property names are covered |
| The GitHub Action's inputs | GitHub pull requests |
| The state ocra keeps in its pull request summary comment | Internal (v1 today), but later releases keep reading it. If one ever cannot, the next review starts over: every file, possibly repeating comments |
The plugin interface (OcraPlugin) | Plugins; 0.x rule |
The library entry: review() and the ReviewOptions fields the Embedding page lists, startPlugins(), the registry's createVcs, createRuntime, reviewers, rules and emit, toReportOutput(), coverageGaps(), isIncompleteReview(), isBlocking() and parseSarifLog() | Embedding ocra; 0.x rule |
The main entry of each package: what @open-cr-agent/core, the adapters and the runtimes export | Embedding ocra and each package's API report in etc/; 0.x rule. /internal entries and @open-cr-agent/vcs-platform are not a contract |
The error model: OcraError, its code values, isOcraError(), and what review() throws | Embedding ocra; 0.x rule (codes may be added; renames and removals are in the changelog). Messages are not a contract |
Not contracts: the wording of text output, error messages, progress lines and pull request comments; session events (events.jsonl); prompts; which findings a model reports; cost. Parse the JSON report, not the text.
Support
- Fixes, security fixes included, go into the latest release only; no backports. Reporting a vulnerability: SECURITY.md.
- Node.js 22.19 or newer (
engines). CI tests on Node.js 22 on Linux, and installs and starts the Action on Linux, macOS and Windows. - Git: tested with the versions on GitHub's hosted runners; no minimum version yet.
- One maintainer; issues and pull requests are answered best-effort, with no paid support.
Verifying a release
Releases are published by this repository's release workflow through npm trusted publishing; token publishing is disabled, and a manual publish needs the maintainer's second factor. Since 0.1.1, each package carries provenance tying it to this repository, the workflow and the tagged commit. To check what you installed:
npm audit signatures --include-attestationsThe container image carries build provenance too: gh attestation verify oci://ghcr.io/jma49/ocra:<version> --repo jma49/Open-CR-Agent.
The GitHub Action installs the published CLI with its tested dependency versions, verifies signatures and ocra's provenance, and builds from source when a version is not on npm or lacks provenance (GitHub pull requests).