The current source tree produces a Prepared publication-candidate artifact. Prepared describes
the frozen bytes and remains true before and after publication. It does not assert that a GitHub
Release or marketplace entry exists, that a host loaded the Plugin, that a support level is current,
or that Production promotion passed. Those changing external facts require authenticated metadata
and attestations outside the immutable archive.
The package uses strict Semantic Versioning:
- Major: incompatibly changes a behavior contract, routing boundary, evidence state, safety rule, or supported-platform guarantee;
- Minor: adds a backward-compatible Skill, optional method, evaluation capability, or verified platform;
- Patch: corrects an implementation or documentation defect without intentionally changing the public behavior contract.
During 0.x, breaking changes remain possible but still require migration notes. VERSION,
.codex-plugin/plugin.json, changelog heading, migration guide, evidence manifest, Git tag, archive
filename, and checksum must agree. pyproject.toml uses the corresponding PEP 440 spelling; for
example, SemVer 0.1.0-rc.1 maps to 0.1.0rc1.
Before the RC workflow, the current changelog heading must be <version> - Prepared. Its section
must say that publication, marketplace availability, current support, and Production certification
are external facts requiring authenticated metadata. Do not add a release date, tag URL,
marketplace availability, current support, or withdrawal claim to the candidate archive in
anticipation of success.
The deterministic.yml workflow runs without model credentials. It validates Python, tests,
catalog and schemas, documentation, distribution metadata, archive reproducibility, workflow
contracts, safety assertions, and generated drift. Protect main, require the check, and enforce
CODEOWNERS for Skill, evaluation, release, and policy surfaces.
Run the full local gate before merge. A local pass is necessary but does not create model, private-case, platform, RC, or soak evidence.
The protected nightly.yml workflow runs behavior treatment/control ten times per case and runs
the full trigger catalog once per query. It uses clean isolation, exact model identifiers, current
calibration where applicable, unique uncached provider requests, and immutable retained artifacts.
Nightly evidence detects drift; it does not create a release. Missing credentials, unavailable models, malformed adapter output, or infrastructure failure remain failed or incomplete rather than becoming synthetic output. A blocker failure starts an investigation and breaks a candidate soak window.
From a clean candidate checkout, run the full deterministic gate and build the archive twice into independent output directories:
version="$(rtk cat VERSION)"
first_archive="/tmp/first-build/structured-thinking-${version}.tar.gz"
second_archive="/tmp/second-build/structured-thinking-${version}.tar.gz"
rtk uv run --frozen python .github/scripts/build_distribution.py \
--root . --output-dir /tmp/first-build
rtk uv run --frozen python .github/scripts/build_distribution.py \
--root . --output-dir /tmp/second-build
rtk cmp -s "$first_archive" "$second_archive"
rtk cmp -s "${first_archive}.sha256" "${second_archive}.sha256"Both cmp -s commands must exit zero. Inspect archive members against the documented allowlist and
validate the staged archive independently. A matching pair proves byte reproducibility for that
source tree; it does not authenticate the publisher or make the archive proof of publication,
marketplace availability, host compatibility, or current support.
- Choose the SemVer; update
VERSION, Plugin manifest, Python version, changelog, migration notes, and documentation status consistently. The changelog and bundled documentation describe a Prepared publication candidate, not a current external publication state. - Merge the candidate to protected
main; require deterministic CI and the reproducibility rehearsal to pass for the exact commit. - Provide protected
ST_EVAL_MODEL_CONFIG, model credentials, and a current judge-calibration manifest bound to the exact judge model, adapter, rubric, dataset, metrics, and approver. - Dispatch
release-candidate.ymlfor the exact version and commit through therelease-candidateprotected environment. - Require at least 30 behavior runs per case and condition and at least three treatment runs per trigger query. Validate behavior and trigger evidence manifests independently.
- Review deterministic blockers, per-case results, Wilson intervals, paired comparisons, regressions, judge disagreements, infrastructure rate, request IDs, token accounting, model and adapter provenance, archive digest, and all artifact hashes.
- Record approval through the protected environment and retain the immutable workflow run ID.
Do not edit an RC artifact. Any source, documentation, adapter, configuration, evidence, or archive correction requires a new commit and an independent new RC run.
Dispatch release.yml with the approved version and RC workflow run ID. The protected workflow:
- verifies that the publish commit is exactly the accepted RC commit;
- downloads and revalidates the immutable RC evidence;
- verifies calibration, manifest, catalog, evaluator, environment, model, adapter, and archive bindings;
- stages the exact Plugin archive recorded in RC evidence—without rebuilding it;
- verifies and publishes SHA-256 checksums and the permitted aggregate evidence;
- creates the immutable Git tag and GitHub Release from the evaluated commit and archive.
The publish workflow performs no stochastic generation. The archive is an audit and distribution
artifact; it is not a direct Plugin-install input. Publishing the archive does not mutate its
Prepared heading or add transient availability claims to its bundled documentation. The
authenticated GitHub Release record supplies the publication time and URL. Marketplace publication
is a separate external action, and current support is a separate evidence decision.
Do not infer current state from the candidate bytes, a tag-shaped string, a copied checksum, or a
bundled support table. Create an append-only, authenticated evidence record for every external
transition. The record must identify all of the following, using null plus a reason when a field is
not yet established:
| Area | Required evidence |
|---|---|
| Publisher | Canonical publisher account or organization, authenticated identity, repository, and the authority that approved publication |
| Version | Exact SemVer, evaluated commit, immutable tag, Plugin manifest version, and candidate workflow run ID |
| Archive | Filename, SHA-256 digest, checksum asset, evidence-manifest digest, and proof that the marketplace entry resolves to these exact bytes |
| GitHub Release | Release ID and URL, tag target, publication timestamp, prerelease flag, and an authenticated API response or signed export |
| Marketplace | Marketplace name and source, entry ID, publisher shown to users, listed version, source revision, availability timestamp, archive digest binding, and authenticated listing response |
| Host platform | Surface, operating system where material, exact host build or pinned version, installation method, observed publisher/version/digest, and installation/reference/routing/behavior/safety evidence IDs |
| Current support | Surface support level, decision timestamp, approver, evidence IDs and hashes, durable raw-evidence locator and digest, retention expiry, retest date, and any material limitation |
| Production | Promotion-attestation ID and checksum, exact version and commit, covered hosts, approval identity, and effective time |
| Withdrawal | Availability state, reason, effective time, affected publisher/marketplace/version/digest, replacement or mitigation, approver, and revocation evidence; use explicit null only while no withdrawal is asserted |
A GitHub Release claim is valid only when authenticated release metadata binds its tag and assets to the evaluated commit and archive digest. A Marketplace claim is valid only when an authenticated listing binds the expected publisher, marketplace source, version, and archive digest. A current support or Production claim additionally requires unexpired host evidence and the applicable attestation. Store the evidence record and its checksum with release governance artifacts; publish only the non-secret fields required for independent verification.
The 90-day Actions artifact is a transport and review window, not durable evidence for a longer claim. Before publishing a performance number or current-support decision, promote the complete recomputable public evidence bundle to an authenticated durable store, or the access-controlled bundle to a protected durable store, and record its immutable locator, digest, access authority, and retention expiry. The claim or support decision must expire no later than its raw evidence.
Never rewrite an earlier evidence record when availability or support changes. Append a superseding
record, preserve the old release and digest for audit, and make the current external authority point
to the new state. The repository may later add a dated historical changelog entry on a subsequent
commit, but the tagged candidate archive remains unchanged and truthfully Prepared.
Publication does not imply Production certification. A stable release is blocked unless the protected release environment supplies a schema-valid promotion attestation bound to the exact version and commit. It must record:
- at least two independent successful RC workflow run IDs;
- fourteen consecutive clean nightly windows;
- at least 50 access-controlled cases comprising at least 20% of the promotion set;
- zero critical failures;
- current installation, reference-loading, routing, behavior, and safety evidence for each pinned Production platform;
- approver identity, artifact hashes, and the exact promotion schema version.
Publish the approved attestation and checksum with the stable release. Documentation, an environment approval, local mocks, public-reserved catalog cases, or a single successful model run cannot substitute for these bindings.
If a release violates a safety or factual-integrity blocker:
- append authenticated withdrawal metadata, mark the GitHub Release and each bound marketplace entry as affected, and stop recommending installation;
- disable promotion and new publication workflows for the affected line while triage proceeds;
- preserve the tag, archive, checksum, evidence, and workflow logs for audit—never rewrite history;
- identify the last known-good immutable version and publish explicit install/rollback guidance;
- update the support matrix, security policy, and user lifecycle status to
Withdrawnwhere applicable; - issue a patch only when the public behavior contract remains compatible; otherwise select the required minor or major version and update migration notes;
- rerun the complete candidate process. Revocation evidence does not waive a new RC.
For user-side removal and rollback, link to the lifecycle guide. For private vulnerability handling, use SECURITY.md.