Release process

Current state: v1.2.0 is published and independently verified; S035 prepares its production site/schema update and continues through deployment and live verification after the operator's final PR merge

This document defines the protected release lifecycle around Cueson's repository-owned candidate proof and authorized public releases. It does not provide an executable publishing path or grant release authority by itself. The runnable candidate checks and independent v0.0.0, v1.0.0, v1.1.0 and v1.2.0 publication evidence are recorded in release verification. Historical release sections retain their dated authority and completion boundaries.

Authority split

Candidate construction and verification are ordinary reviewed repository work. Final pull-request merge, tag creation or movement, tag push, GitHub Release publication, release-asset publication, milestone closure, immutable release-schema admission, and production cueson.io changes are distinct governed actions. Each action must remain within an approved release specification and must receive any explicit operator authorization required by the project constitution and AGENTS.md.

An authorization applies only to the named action and state under review. It does not silently authorize a later retry after material changes, another pull request, another tag, another release, or production publication.

For S035, the operator explicitly authorized push and an official preparation PR, then directed that production deployment and verification must not remain unfinished. The recorded S035 authorization covers protected exact-main production deployment and independent live verification immediately after the operator's specific final PR merge. No second kickoff or deployment approval is required for that continuation. It does not grant final PR merge authority or extend to unrelated releases or production changes. Preparation #88 may close on merge; production #86 and milestone v1.2.0 stay open until their complete acceptance criteria pass.

v0.0.0 released state

The repository has a buildable 0.0.0 executable, an embedded 0.0.0 Cue JSON schema, a byte-identical immutable versioned release schema, published v0.0.0 release notes, and a verified non-publishing six-target snapshot pipeline. The current CLI and schema boundary is documented in the CLI contract and schema baseline.

The immutable annotated tag v0.0.0 peels to b294a6952c8bd041d852c502f5d7206c0b58edd6. The GitHub Release is public, final, and contains exactly six archives, six target-bound SPDX JSON SBOMs, and one checksum manifest copied byte for byte from accepted default-branch proof run 34543376814.

The release did not publish the canonical schema endpoint, add a signature or attestation, activate production cueson.io, implement native subtitle codecs, or itself close milestone v0.0.0. The milestone was closed only through later authorized reconciliation. GitHub Actions artifacts from later candidate runs remain review evidence rather than release assets unless another release is explicitly authorized.

Published v1.0.0 release

The immutable annotated tag v1.0.0 peels to 2cad4c816340404289b4d1d87179a4071713bb46. The GitHub Release is public, final, and contains exactly six archives, six target-bound SPDX JSON SBOMs, and one checksum manifest copied byte for byte from accepted default-branch proof run 34621429626.

S020 independently downloaded all thirteen files, matched their names, sizes, and SHA-256 values with the accepted contract, applied the six-archive checksum bijection, reran structural and semantic verification against the public bytes, and executed the Windows amd64 package. Publication did not host the schema at cueson.io, activate production configuration, add signatures or attestations, merge the S020 pull request, or close the v1 epic or milestone.

Candidate readiness

A release decision starts only from a clean, reviewed default-branch commit. Before asking for publication authority, maintainers must verify:

1. Every issue committed to the candidate is closed or truthfully moved, and the Project and milestone agree with that state.
2. The executable version, embedded schema version, and intended tag version are identical.
3. The detailed candidate history and chronological architecture decisions are finalized in one valid dated section for the intended candidate version of CHANGELOG.md, with one fresh [Unreleased] section retained. This prepared metadata must reach reviewed main before tag selection, so the tag contains the finalized changelog; a dated section does not assert public availability.
4. Repository formatting, tests, race detection, vet, vulnerability analysis, CodeQL, platform-native tests, and pure-Go target builds are green.
5. The non-publishing snapshot and repository-owned verifier pass for the exact default-branch candidate commit and record its full revision plus release_schema_sha256 in deterministic evidence.
6. Documentation describes the candidate's actual commands and format-support declarations, distinguishes exact restoration from rendering and conversion, and contains no capability inherited from a different release.
7. No unresolved review or security finding remains.
8. The proposed release does not depend on an unapproved production-domain change.

Candidate readiness proves that a release decision can be made. It does not make the decision and does not grant permission to publish.

Published v1.2.0 release and production continuation

S033 completed consumer-assigned speaker attribution and declared media timing in PR #83, closing #82. S034 preparation #84 merged through PR #87 at 6a1fd7a541767c0b19dcc10022fafc0e46903cff, admitting the exact immutable 1.2.0 schema and finalized dated changelog. Fresh main Release proof bound that revision and the complete candidate inventory before explicit operator publication authority was exercised. Former development identities remain unsupported.

The unsigned annotated v1.2.0 tag, object 386087872854d77b7f130d3b24ec517f1a5d0aad, peels to that exact accepted main revision. The official release was published at 2026-10-07T00:45:58Z (2026-10-06 in America/New_York), is final, non-prerelease and latest, and contains six pure-Go archives, six target-bound SPDX JSON SBOMs and one checksum manifest. #85 completed anonymous download verification of all thirteen public assets and native public Windows proof; accepted main proof additionally covers the matching Linux and macOS amd64 packages. Arm64 proof is structural and build-information verification. No signature or attestation is claimed. The release page and durable publication record document shipped software and exact evidence.

The S034 publication decision contract remains the reviewed preparation contract. Its runtime fields were populated in the accepted decision after fresh main proof; historical source artifacts are not rewritten to predict runtime outcomes. S035 #88 prepares v1.2.0 release/download metadata, release and speaker documentation routes, and the fourth immutable schema route. #86 continues immediately after the operator's merge through fresh exact-main protected deployment, independent public verification and lifecycle reconciliation. The prepared artifact is not proof that production has changed. Live before-state remains the previously deployed v1.1.0 site until the authorized S035 deployment and verification pass.

Release preparation lifecycle

For v0.0.0, S012 prepared the publication state without weakening the existing non-publishing controls.

1. The dated v0.0.0 changelog, concise release notes, and versioned release-schema candidate were reviewed together on the S012 pull request.
2. The complete six-target snapshot and repository-owned verifier proved the pull-request head as review evidence only because squash merge created a different commit.
3. The operator completed the final review and specific merge decision after the pull request was green and fully reviewed.
4. The main push workflow rebuilt and verified the exact squash-merge commit rather than substituting the pull-request head or pre-merge default-branch revision.
5. The default-branch release-evidence.json recorded the full source revision, version, release_schema_sha256, target inventory, archive and SBOM digests, counts, compatible-host execution result, and published: false.
6. S013 froze the complete decision package, received exact tag and release authority, published only the authorized state, and verified the public result independently.

The checked-in GoReleaser configuration remains snapshot-only and has publication disabled. A release slice must not repurpose that reviewed configuration into a hidden publication mechanism. S018 froze the v1 behavior without changing development identity. S019 promoted software, schema, and format maturity to the 1.0.0 stable candidate, admitted the immutable v1 schema, finalized the dated changelog and concise release notes, and proved the exact non-publishing candidate. S020 published and independently verified that exact candidate under explicit authority.

v1.0.0 candidate preparation lifecycle

1. S018 froze the intended v1 CLI, schema, SubRip, WebVTT, conversion, security, conformance, and documentation contracts at development identity 0.1.0.
2. S019 promotes the reviewed executable and schema identity to 1.0.0, changes only the completed SubRip and WebVTT format declarations to stable, and admits a byte-identical immutable repository schema.
3. The accumulated detailed history moves into a dated 1.0.0 changelog section, while concise candidate release notes retain the exact tagged changelog suffix and make no publication claim.
4. One six-target candidate bundle is built from the exact source revision, structurally verified, and executed on available native Linux, Windows, and macOS runners without publishing.
5. Pull-request evidence proves the reviewed head only. After a separately authorized squash merge, the main push proof must bind the resulting commit before issue #38 can request tag or release authority.
6. Public schema hosting, signatures, attestations, milestone closure, and production changes remain outside both S019 and the later GitHub Release transaction unless separately specified and authorized.

Published v1.1.0 release

S028 combined contract/documentation freeze (#64) and exact candidate proof (#65). Official software, canonical/immutable/embedded/emitted/packaged schema and new native output use exact 1.1.0; bounded ASS/SSA and all twelve conversion directions declare stable implemented capability. Exact-current schema-only and complete experimental observations remain unchanged valid declarations, while former development identities reject. Historical 1.0.0 input uses its immutable local schema and semantics; the verified released v1.0.0 executable rejects every fresh 1.1.0 document, including text-format output. There is no historical-output selector or implicit network loading.

Candidate construction accepts six pure-Go archives, six target-bound SBOMs, one six-entry checksum manifest and identical schema/legal bytes at the exact clean revision. Matching packaged-host native/historical/safety workflows run on governed amd64 Linux, Windows and macOS; arm64 packages receive structural/build-information proof without native execution claims. Pull-request evidence binds the reviewed head only, and fresh post-squash main evidence must identify the later publication commit.

The maintained v1.1.0 release page records the official release, exact tag target and public inventory. The immutable annotated tag v1.1.0 peels to 7ff45c1d8cd8df377e1fb568b9785286b649fd7c. The final non-prerelease GitHub Release publishes the reviewed concise notes, six pure-Go archives, six target-bound SPDX JSON SBOMs and one checksum manifest. Independent verification downloaded and checked all thirteen public assets, executed the compatible Windows package and read back the exact tag/release state. The #66/#76/#67 authority split remains explicit: #66 completed software publication, #76 completed the reviewed schema/site artifact, and #67 completed exact-main production activation and live verification. S032/#78 subsequently completed protected deployment repair.

Reviewed publication preparation

S029 finalized the dated history and froze a separate exact public release-note body while preserving the time-bound candidate guide. The preparation pull request closed only preparation #74, not publication #66. The human operator merged that reviewed change before the publication target was selected, ensuring the tag contains the finalized changelog.

After that squash merge, fresh green main CI, security, Site and same-bundle native package proof bound the actual resulting revision. The operator received one exact decision package with source, schema/legal identity, thirteen named/sized/digested assets, checksum bijection, three governed native evidence records and the digest of the explicitly selected formatted public notes. Neither an earlier S028 bundle nor the preparation PR head substituted for the final publication package.

Exact tag creation/push and official release/asset publication each required their specific authorizations. Source, tool, artifact, schema, note or check changes, expired proof or partial publication would have required a refreshed decision. Independent public verification proved the approved tag, official release, exact assets and body, closing #66. Production deployment, live verification and epic/milestone reconciliation were completed separately through #67. Public software availability at that S029 publication decision was v1.1.0; the current published release is v1.2.0.

Pull-request and default-branch candidate binding

Pull-request proof answers whether the reviewed change can produce the expected candidate. It does not identify the final publication commit. Repository policy uses squash merges, so the pull-request head is not the resulting main revision and must never be recorded as the release target by prediction.

The non-publishing workflow also runs on pushes to main. After the authorized S012 merge, successful run 34543376814 promoted exact 40-character squash-merge revision b294a6952c8bd041d852c502f5d7206c0b58edd6 from reviewed repository state to the authorized publication target. Future releases must repeat this binding; if the default branch moves before authorization, or artifacts, tools, dependencies, notes, schema bytes, or checks change materially, the decision package must be regenerated and reviewed against the new state.

Operator decision package

Before requesting tag or GitHub Release authority, present the operator with one bounded package containing:

• the exact 40-character post-squash main commit proposed for the intended semantic-version tag;
• the intended version, dated changelog, and reviewed concise release notes;
• the lowercase release_schema_sha256 for the byte-identical canonical, versioned, embedded, and packaged schema;
• the exact six-archive and six-SBOM inventory, the six archive checksum entries, and every recorded archive and SBOM digest;
• the accepted release-evidence.json, including target identities, compatible-host execution result, and published: false;
• the green default-branch CI, CodeQL, and release-proof results plus the resolved review and security record;
• every capability limitation that applies to that candidate, plus the explicit absence of signatures, attestations, public schema hosting, or production activation unless those items were separately specified, proved, and authorized.

The operator decision must name the target commit and intended actions. Approval to create or push the tag does not authorize GitHub Release or asset publication, and approval to publish the release does not authorize production-domain work or milestone closure.

Protected publication actions

Authority for one row does not authorize another row. In particular, permission to merge a release-preparation pull request is not permission to create a tag or GitHub Release.

Tag and GitHub Release boundary

After release preparation reaches the verified default branch, the operator may authorize tag and release publication for the exact commit and artifact set recorded by the successful main proof. For v0.0.0, the operator authorized the exact S012 commit and thirteen public files, and S013 read back the resulting tag target, release notes, release state, and asset inventory before treating publication as complete.

The release must use the verified artifacts associated with the approved source commit. A rebuild from different source, a changed dependency, a changed tool version, or a materially different artifact set requires verification and operator judgment again. Draft, partial, or failed publication is not silently promoted to success.

Immutable schema boundary

The versioned repository schema, the schema embedded in every official binary, and the schema distributed in every release archive must be byte-identical. Their schema identity and version must match the release version.

After release, schema/releases/v0.0.0/cueson.schema.json, schema/releases/v1.0.0/cueson.schema.json, schema/releases/v1.1.0/cueson.schema.json and schema/releases/v1.2.0/cueson.schema.json are immutable. Their corresponding tagged canonical, embedded, emitted and packaged copies match byte-for-byte. S028 established exact 1.1.0 bytes, and #66 published and independently verified their packaged release copies. S030 completed the versioned production route, exact-main activation and live byte verification through #76/#67. S034 and #85 established and publicly verified the 191,170-byte v1.2.0 schema, SHA-256 f2661a3d52effbab4a82a4d47197b5c7fae58496dc30a397ea3f2f668358b654; S035 adds its production route while preserving all three prior routes. No path may overwrite a released schema or move a released tag.

The canonical https://cueson.io/schema/v0.0.0/cueson.schema.json and https://cueson.io/schema/v1.0.0/cueson.schema.json paths are published by the separately specified and authorized S021 production continuation. Their bytes must equal the immutable repository and release copies. Consumers may continue using embedded, repository, or release-artifact copies offline. No mutable schema alias is published.

Post-publication verification

Publication is complete only after read-back and independent comparison prove:

• the release tag identifies the authorized commit;
• the GitHub Release identifies the intended tag and is in the intended publication state;
• the published asset inventory is complete and contains no unexpected artifact;
• archive checksums match the published archives;
• every packaged executable contains the verified release marker and expected build identity, the host-compatible executable reports the release version, and every embedded schema reports the schema version;
• every packaged schema matches the immutable tagged repository schema byte-for-byte;
• SBOMs remain associated with the correct target and source revision;
• release notes are the reviewed highlights and end with the exact tagged changelog link;
• no production-domain state changed as a side effect.

If any comparison fails, stop dependent actions, retain the evidence, and ask the operator to choose a recovery path. Do not move a published tag, overwrite an immutable schema, replace assets, or close the milestone by inference.

Milestone lifecycle

S013 publication verification deliberately left the v0.0.0 milestone open because publication authority did not include milestone closure. A later separately authorized reconciliation closed it after the public release and repository record were verified.

The v1.0.0 milestone and epic were closed through authorized post-publication reconciliation. The v1.1.0 publication, independent verification and public hosting outcomes completed, followed by authorized epic/milestone reconciliation. The v1.2.0 candidate preparation #84 and public release verification #85 are complete; S035 preparation #88 and production #86 retain their independently verifiable outcomes. Keep #86 and milestone v1.2.0 open until protected deployment and full independent live verification pass. The operator's recorded S035 continuation includes that lifecycle reconciliation after successful proof.

For a future abandoned release, its milestone may be retired or its remaining commitments moved only through an explicit recorded decision. Repository status must continue to reflect the actual publication outcome.

After a successful release

After publication, maintainers retain the fresh [Unreleased] section for later work, preserve the released changelog and schema, complete post-merge housekeeping, and record any release follow-up as new issues rather than editing historical evidence. Milestone reconciliation follows only when separately authorized.

Signatures and attestations remain future outcomes. S021 separately specifies and authorizes public schema hosting, DNS, redirects, TLS, and documentation hosting; none was implied by the earlier snapshot verifier or the successful v0.0.0 and v1.0.0 GitHub releases.

Production site continuation

The reviewed site change does not deploy from a pull request. After the human merge ritual, an explicitly authorized operator or agent dispatches the protected manual workflow from main with the exact merged main SHA. S035 already has that post-merge deployment and verification authorization. The workflow rejects every other execution ref and any difference between its execution revision, requested revision, checkout, generated deployment record, or freshly fetched origin/main. It proves that equality before checkout-controlled package tooling, before artifact proof, and immediately before mutation, then deploys the Worker and static artifact described in site/wrangler.jsonc. The deployment may configure only the cueson-site Worker and its cueson.io and www.cueson.io Custom Domains; unrelated Cloudflare resources remain untouched.

The ShruggieTech security owner provisions CLOUDFLARE_API_TOKEN as a secret in the GitHub production environment. The account-owned token is restricted to the entire ShruggieTech Cloudflare account for Developer Platform Workers Scripts Legacy: Edit and to the specified cueson.io domain for DNS & Zones DNS: Read and Zone: Read, Rules & Configuration Zone Transform Rules: Read, and Developer Platform Workers Routes: Read. Workers Scripts Legacy Edit covers the cueson-site upload, Worker inventory, and Custom Domain operations. Workers Routes Read covers Wrangler's conflict check against the zone route inventory before it updates Custom Domains. The remaining read permissions cover exact zone identity, DNS, and redirect rulesets used by preflight and read-back. The token is exposed only to the Cloudflare preflight, Wrangler deployment, and Cloudflare post-deployment read-back steps. Checkout, setup, dependency installation, tests, local artifact proof, and public verification do not receive it.

The security owner records the non-secret credential owner, creation date, expiry, resource scope, and next rotation date in the organization credential inventory. Use an explicit expiry when Cloudflare supports it and rotate no less frequently than every 90 days. Validate a replacement through the complete preflight before revoking the prior token, update the protected secret, and read back GitHub secret metadata without attempting to reveal its value. Suspected exposure, owner departure, resource-scope change, or unexplained authentication use requires immediate revocation, replacement, preflight, and audit. Token values, token identifiers, and authentication output never belong in source, logs, issues, pull requests, or release notes.

Production completion requires read-back of exact zone identity, DNS, Worker inventory, Custom Domains, and redirect rulesets, including preservation of unrelated state. Independent S035 public verification then proves DNS, trusted HTTPS independently over IPv4 and IPv6, apex routes and metadata, permanent path-and-query-preserving www redirection, exact official v1.2.0 primary release links, matching GitHub and public deployment revision records, and all four immutable schema hashes and lengths with JSON content type, immutable cache policy and nosniff headers. The release and consumer-speaker routes, historical release links, public content-manifest digest and absence of a latest schema must also pass. Failed propagation, certificate readiness, credential scope, state preservation, or revision identity is diagnosed and corrected within the authorized scope; an incomplete result cannot close #86 or milestone v1.2.0.