Release Candidate Checklist

Offline, read-only compilation of an exact-revision, exact-input release checklist from supplied package contracts and check results. It reports ready or not-ready; it does not package, tag, publish, deploy, or contact a release service.

Node.js 22+; no dependencies or network calls.

node bin/release-candidate-checklist.mjs --root examples/pass --input candidate.json
node bin/release-candidate-checklist.mjs --root examples/fail --input candidate.json
node bin/release-candidate-checklist.mjs --root examples/stale --input candidate.json
npm run check

--help prints usage. Normal runs emit one JSON report on stdout: exit 0=pass/ready, 1=fail/not-ready, 2=incomplete/not-ready or invalid configuration. Invalid options or root produce empty stdout. An unreadable, undecodable, malformed, or out-of-root named input produces an incomplete report. The named input is realpath-confined under the root. UTF-8 decoding is strict and duplicate decoded JSON keys are rejected. Nothing is written.

The passing example shows the full schema. Top-level schemaVersion and checklistVersion are both "1"; complete must assert contracts, inputs, and results are all true from actual exports. The candidate names a package, SemVer version, exact lowercase full Git revision (40- or 64-hex), and every relevant input by opaque ID and 64-hex SHA-256 digest. Each contract gives an opaque check ID, mandatory flag, and the exact list of input IDs its result must bind. Every result declares checkId, revision, status (pass or fail), and the exact input ID/digest pairs observed when that check ran. The tool compares supplied fingerprints; it does not calculate or independently attest them.

For every mandatory contract, a result is required, and every declared candidate input must be bound by at least one mandatory contract. A green result from another revision or with a missing, extra, or changed input is stale, does not count, and leaves the candidate incomplete/not-ready. A matching failed result is fail/not-ready. A matching passed result contributes one ready checklist item. A candidate with no mandatory contracts, no inputs, incomplete export, duplicate identities, unknown fields, or malformed records cannot be ready. Optional contracts may be present; their result does not gate readiness. The checklist and findings use only logical pointers into the exact file named at invocation, never raw package names, revisions, digests, or check IDs. @candidate is logical provenance. Findings sort by (pointer, ruleId) using UTF-16 code-unit order. Optional top-level metadata is non-semantic.

Input ≤65,536 bytes; ≤100 contracts, ≤100 results, ≤100 candidate inputs, ≤20 input bindings per contract or result, opaque IDs ≤64 UTF-16 units, JSON depth ≤16, and evaluation deadline ≤5,000 ms through an injected monotonic clock. N is accepted and N+1 rejected for each bound. The tool neither runs the checks nor proves a supplied completeness flag, revision, or digest is authentic; it only refuses evidence that does not match the declared candidate.