Harden specification release controls

.github/workflows/ci.yml

@@ -4,12 +4,19 @@ on:
   push:
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   specification:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v7
-      - uses: actions/setup-python@v7
+      # v7.0.1: https://github.com/actions/checkout/commit/3d3c42e5aac5ba805825da76410c181273ba90b1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          persist-credentials: false
+      # v7.0.0: https://github.com/actions/setup-python/commit/5fda3b95a4ea91299a34e894583c3862153e4b97
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
         with:
           python-version: "3.13"
       - run: python tools/validate_repository.py

CHANGELOG.md

@@ -17,9 +17,13 @@ Until a protected or signed `v0.3.0` tag targets this work, implementations MUST
   action followed by an existing-target apply with no automatic Dolt commit.
 - Added independent synthetic golden fixtures, hashes, examples, and repository
   validation gates for the new contracts.
-- Corrected the SPSS Syntax Frontend 0.1 schema's `$defs` and `$ref` keywords
-  so typed value-label values are constrained as the existing contract states;
-  this is eligible for a patch-series backport under the schema-defect policy.
+
+## v0.2.1 - 2026-08-04
+
+- Corrected the SPSS Syntax Frontend 0.1 schema's `$defs` and `$ref`
+  keywords so typed value-label values are constrained as the existing
+  contract states. This maintenance release contains no Transformation Plan or
+  SPSS Syntax Frontend 0.2 work.
 
 ## v0.2.0 - 2026-07-31
 

README.md

@@ -25,7 +25,7 @@ remains an explicitly unsupported [future dialect](docs/mssql-dialect-roadmap.md
 
 OpenStatSpec does not define long-form cells, EAV storage, table splitting, reshaping, automatic harmonization, or questionnaire/study entities. It does not infer respondent keys or combine datasets. All conformant database-object identifiers are generic; the double-underscore prefix is reserved for standard technical identifiers.
 
-[Versioning](VERSIONING.md) defines compatibility and release rules. [Roadmap](ROADMAP.md) tracks remaining project work and maintainer setup.
+[Versioning](VERSIONING.md) defines compatibility and release rules. [Releasing](RELEASING.md) defines the maintainer release checklist. [Roadmap](ROADMAP.md) tracks remaining project work and maintainer setup.
 
 ## Optional SQL transformation workflow
 
@@ -76,7 +76,7 @@ to be provisioned separately before an in-place transformation apply.
 
 Implementations must preflight target capabilities before import. If the target cannot faithfully create one wide table because of column, identifier, string, or row limits, import must fail atomically with a machine-readable capability diagnostic. It must never silently truncate, drop, split, transpose, pivot, or transform source data.
 
-This specification repository publishes only normative Transformation Plan and SPSS syntax frontend schemas, documentation, and declarative fixtures. Executable validation or behavioral conformance code, including parser, SQL-engine, transaction, and adapter behavior, belongs in each implementation or adapter repository.
+This specification repository publishes normative Transformation Plan and SPSS syntax frontend schemas, documentation, declarative fixtures, and its own structural/hash/fixture validation in tools/validate_repository.py. It does not contain executable implementation or behavioral conformance code: parser, SQL-engine, transaction, and adapter behavior belong in each implementation or adapter repository.
 
 ## Who it is for
 

RELEASING.md

@@ -0,0 +1,52 @@
+# Releasing OpenStatSpec
+
+This checklist governs releases of this specification repository. It does not
+publish an implementation package and does not substitute for implementation
+or adapter conformance evidence.
+
+The repository release maintainer with repository-admin authority is responsible
+for completing this checklist and preserving the release controls it requires.
+
+## Before preparing a release
+
+- Choose an exact reviewed commit on the appropriate branch and record its
+  full commit ID. Stable tags use the convention `vX.Y.Z`.
+- Keep maintenance releases on their maintained release branch. Merge the
+  equivalent corrective change to `main` separately when it is also needed by
+  the next minor release; do not make a maintenance tag point at unrelated
+  unreleased `main` work.
+- Run the repository validation at that exact commit and confirm the required
+  CI run for that commit is successful. A green run for a nearby commit is not
+  sufficient.
+- For a release that claims adapter, dialect, transformation, or syntax-front
+  end support, collect the required adapter conformance and service-matrix
+  evidence for that same specification commit. Do not convert a
+  `release_candidate` claim into `released` before those gates pass.
+- Confirm the changelog, versioning impact, and release notes describe only
+  the included specification changes.
+
+## Tag and release
+
+- Create and push `vX.Y.Z` only after the exact release commit has passed
+  CI. Use the selected signed annotated-tag path where signing is available,
+  or the selected protected-tag path restricted to release maintainers. Do not
+  move or reuse a published tag.
+- Wait for the CI run in that exact tag context to succeed before creating or
+  publishing the immutable GitHub release; a branch-commit CI result is not a
+  substitute for the tag-context result.
+- Create the GitHub release as a draft from that exact tag and verify the tag
+  target, title, notes, links, and any release assets before publication.
+- Before publishing, verify the repository immutable-releases setting is
+  enabled. If that setting or the selected signed-or-protected tag path is
+  unavailable, stop and restore the missing selected control before publishing.
+- Publish the release only after those checks are confirmed.
+
+## After publication
+
+- Verify GitHub reports immutable true for the published release and its tag as
+  the intended full commit ID.
+- Verify the tag-triggered CI run is successful and that the release notes are
+  visible from the repository release page.
+- Record any remaining future-release gates in the roadmap. Publishing a
+  specification release never completes pending adapter or service-matrix
+  evidence by itself.

ROADMAP.md

@@ -28,8 +28,8 @@ Prerequisite: the core mapping and canonical fixtures are stable enough to test
 
 - [x] Add continuous checks for specification links, schema examples, fixtures, and adapter conformance once the relevant repositories exist.
 - [x] Define versioning and compatibility guidance for the specification and profiles.
-- [x] Publish release notes and tagged specification releases; `v0.2.0` is the
-  current public specification release.
+- [x] Publish release notes and tagged specification releases; `v0.2.1` is the
+  current public specification release and is immutable.
 - [ ] Expand implementation, dialect-profile, and adoption documentation from real adapter experience.
 
 ## 5. Future adapters
@@ -108,5 +108,6 @@ These are maintainer actions, not implementation tasks for the specification rep
 - [x] Register and publish the OpenStatSpec PHP package through Packagist. The
   public package establishes the registry setup; repository update ownership
   still needs release-process verification.
-- [ ] Decide the release owner(s), tag naming convention, and release checklist for every repository.
+- [x] Define the specification release tag convention and maintainer checklist in
+  [RELEASING.md](RELEASING.md); the repository release maintainer with repository-admin responsibility owns release-process controls.
 - [ ] Protect the default branches and ensure release tags are created only by the agreed release workflow; `main` is currently unprotected.