ethos-gemkit 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6874e64af38ffa0301d9db238dc2a7a4a95e4de66df211003491ec5c68f74a0
-  data.tar.gz: 1ef1d85750e28953db05b02d142b4dd728879a3f7c6bfc79525b1fae7c29bcf0
+  metadata.gz: a47dcf57b9f1dfaa0cfee1422dec8eb6ba3af0169358843f67ed36ac957ea294
+  data.tar.gz: 478f8436259e03d5a332a8f88006dbea5a11114d205024effa04cb8dcf19952d
 SHA512:
-  metadata.gz: 13b6137a5f8de672582a52d84c8084d60e9af03718bae99f4d1b3274ccaeac3a97a93a50217e04ade33cdb8421f8b27a9e7c70aa0614582ba061879f677d7994
-  data.tar.gz: f12acfadd4abb54a6f99a9c6eed7ac94747e497bc575c59018ab68ac0631cd6f7e46b4255773d0d9a45af9646d8d79108bbfc01118332483e92f0f90793e8065
+  metadata.gz: 3361ad93a5b3ec3720601b9a98644868e61b7d5b0e90c626b7adeca3dd66118e1c0773124d8a0d7b218ea3193931db0a01b8c7bc2c429f07f8c5695305f71ca4
+  data.tar.gz: 514aae6c1c69381f0d88b32a75c40194389266b391e8db39d385a9af79800fe8eafeb36fea6fca55888f2508a2f90e14bcf1c6ebdc2e0230c860aca06125d9d7

data/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.2] - 2026-11-08
+
+### Changed
+
+- pin native release tools with mise
+
+
+### Documentation
+
+- make Ethos Link the canonical documentation home
+- keep audited technical guidance alongside the code
+
 ## [0.3.1] - 2026-11-05
 
 ### Changed

data/README.md

@@ -4,17 +4,33 @@ Shared development defaults for Ethos Link gems: Ruby 4, Standard, optional Rail
 8 linting, hooks, package checks and one shared release workflow. The toolkit
 belongs in the development/test Gemfile, never a consumer's runtime gemspec.
 
+## Documentation
+
+This README and the linked repository guides describe the checked-out code.
+The [Ethos Link project page](https://www.ethos-link.com/opensource/ethos-gemkit)
+provides the canonical public project guide, overview and resources.
+
+- [Release preparation, registries and recovery](docs/releasing.md)
+
+## Requirements
+
+Ruby 4.0 or newer, Bundler, Git and mise. Install the pinned native tools with
+`bundle exec rake tools:install` after installing the bundle. Rails is optional;
+Rails-specific linting activates when Rails 8 components are in the bundle.
+
+## Setup
+
 Install the published gem in the development/test Gemfile:
 
 ```ruby
-gem "ethos-gemkit", "0.2.1", group: [:development, :test], require: false
+gem "ethos-gemkit", "0.3.1", group: [:development, :test], require: false
 ```
 
 Pin workflow callers to the full commit behind the installed Gemkit release tag.
 Resolve that commit with:
 
 ```sh
-git ls-remote https://github.com/ethos-link/ethos-gemkit.git 'refs/tags/v0.2.1^{}'
+git ls-remote https://github.com/ethos-link/ethos-gemkit.git 'refs/tags/v0.3.1^{}'
 ```
 
 Upgrade the gem version and workflow pins together. Consumer READMEs should cover
@@ -53,6 +69,46 @@ release tasks while a repository is adopting the toolkit.
 `bundle exec rake verify` runs lint, registered checks, a disposable native gem
 build, and git-cliff validation.
 
+The gem ships `mise.toml` and `mise.lock` to pin development tools for local use
+and CI. No Node.js or npm installation is needed for Gemkit.
+
+| Tools | Installation and version ownership |
+| --- | --- |
+| git-cliff 2.12.0, GitHub CLI 2.103.2 | Native binaries installed by mise from the shipped lockfile |
+| Ruby 4.0.9 | Local mise pin; matching `ruby/setup-ruby` pin in CI |
+| Bundler 4.0.11 | Explicit CI pin; install the same version locally |
+| Standard, Standard Rails, Rake, Lefthook | Bundler and the consumer's `Gemfile.lock` |
+| Git, SSH, sha256sum, shell utilities | System prerequisites; hosted CI uses the Ubuntu runner image |
+| Consumer-specific binaries | Consumer local setup |
+
+Install mise (CI uses 2026.10.19), Ruby and Bundler, then run:
+
+```sh
+bundle install
+bundle exec rake tools:install
+bundle exec rake verify
+```
+
+The install task trusts the gem's mise configuration and installs its pinned
+native git-cliff and GitHub CLI binaries. Verification and release preparation
+resolve those binaries through mise using the installed gem's configuration,
+even when called from a consumer directory. They do not fall back to global
+installations or download tools on demand. Re-run installation after upgrading
+Gemkit. Consumer repositories need no npm manifest or copied tool pins.
+
+For work on Gemkit itself, install the Ruby and CLI pins with
+`mise install --locked ruby git-cliff gh`; activate mise in your shell or run
+`mise exec ruby git-cliff gh -- bundle exec rake verify`. The lockfile covers
+Linux and macOS on x64 and arm64. Ruby version parity with CI is checked by
+the tests.
+Git and OS utilities still come from the host; identical tool versions do not
+provide an identical operating system.
+
+The release build workflow loads the installed gem's configuration through a
+SHA-pinned mise action. The isolated release-notes job has its own
+exact GitHub CLI pin, checked against `mise.toml` by the tests, so it can publish
+notes without loading consumer code.
+
 Run verification locally before pushing and when preparing a release. GitHub
 Actions checks commit messages on ordinary PRs and main pushes; it does not run
 tests, lint, browser checks or integration suites. Release workflows validate
@@ -78,173 +134,14 @@ token. See [GitHub's registry guide](https://docs.github.com/en/packages/working
 
 ## Releasing a gem
 
-**Run `release:prepare` from clean, up-to-date `main`.** It creates the conventional
-release branch and opens a PR. **Merging that release PR starts publication.**
-This is the same process for Gemkit itself and its adopted consumer gems.
-Ordinary feature/fix PRs run commitlint; only a release PR starts publication.
-
-### One-time prerequisites
-
-- Commit `Gemfile.lock`. Before its first commit, run
-  `bundle lock --add-checksums`; frozen CI installs reject empty registry
-  checksum entries, even when the gems are already installed locally.
-- Ignore `/.bundle/`, `/vendor/bundle/` and `/pkg/` in `.gitignore`. The shared
-  workflows use Ruby setup's native `vendor/bundle` cache; generated files must
-  leave the release checkout clean.
-- Install the bundle, Git, git-cliff and GitHub CLI. Configure your Git identity,
-  authenticate with `gh auth login`, and install hooks with
-  `bundle exec lefthook install`. You need permission to push branches and open PRs.
-- Public gems: configure a matching RubyGems trusted publisher for **each gem**
-  before merging its first release PR. Use the exact settings below. Gemkit's
-  publisher does not authorize consumer gems.
-- A new gem also needs a pending trusted publisher. Supply its numeric RubyGems
-  owner through the caller's `rubygems-owner` input or the repository/organization
-  variable `RUBYGEMS_OWNER` (the publisher account used by Tunnel is `27209`).
-- Private gems: set `registry: github_packages`. Publishing uses the workflow's
-  short-lived `GITHUB_TOKEN`; the package must grant its repository Actions access.
-  Pass `PACKAGES_TOKEN` only when an explicit token override is needed. Local
-  installation from other private repositories still needs `read:packages` access.
-- Configure the `rubygems` GitHub environment to allow `main` and `v*` tags.
-  Release callers grant `contents: write`, `id-token: write` and `packages: write`.
-  Repository rules must permit the workflow's annotated release tags.
-
-The SDK release workflow listens directly for merged release PRs and version-tag
-pushes. Consumer callers must listen for both `pull_request: types: [closed]`
-against `main` and `push: tags: ["v*"]`, and pin the commit matching the installed
-Gemkit release.
-See the [Tunnel caller](https://github.com/ethos-link/cloudflare-tunnel/blob/main/.github/workflows/release.yml).
-
-Projects keep their own local checks. Engines can register `checks: [ci:local]`
-in `.ethos-gemkit.yml` and have that task run `bin/ci`. Provision PostgreSQL or
-browser dependencies locally before running verification. Release callers do
-not install test dependencies or accept `build-setup`.
-
-### RubyGems trusted-publisher settings
-
-On RubyGems, open the **consumer gem's** page, then **Trusted publishers**. For
-Cloudflare Tunnel, create or update the publisher with these exact values:
-
-| RubyGems field | Value |
-|---|---|
-| Repository owner | `ethos-link` |
-| Repository name | `cloudflare-tunnel` |
-| Workflow filename | `release.yml` |
-| Environment | `rubygems` |
-| Workflow Repository Owner | `ethos-link` |
-| Workflow Repository Name | `ethos-gemkit` |
-
-The repository identifies the consumer; the Workflow Repository fields identify
-the repository containing the shared workflow file. Those last two fields are
-required for consumers,
-even though RubyGems labels them optional. For another consumer, substitute its
-repository name. For Gemkit itself, use repository name `ethos-gemkit` and leave
-both Workflow Repository fields blank because the workflow is in the same repo.
-
-The numeric `rubygems-owner` input identifies the account for pending publishers;
-it does not register a publisher or grant access to a consumer gem. See the
-[upstream reusable-workflow instructions](https://guides.rubygems.org/trusted-publishing/#using-reusable-workflows).
-
-### Prepare and review
-
-For a normal patch release:
-
-```sh
-git switch main
-git pull --ff-only
-bundle install
-bundle exec rake release:prepare
-```
-
-The default is `patch`. Select another target explicitly:
+Run `bundle exec rake release:prepare` only from clean, current `main` when
+preparing an actual release. It updates the version, changelog and lockfile,
+runs verification, pushes a release branch and opens a PR. Merging that release
+PR starts publication; `rake verify` alone does not publish.
 
-```sh
-bundle exec rake 'release:prepare[minor]'
-bundle exec rake 'release:prepare[major]'
-bundle exec rake 'release:prepare[1.2.0]'
-```
-
-For an initial, unpublished version that is already in the gemspec and has no
-tag, an explicit current version is supported. For example, a new gem starting
-at 0.1.0 can use `bundle exec rake 'release:prepare[0.1.0]'` after pending-publisher
-setup.
-
-The task prints each step and streams command output as it runs. It checks the
-working tree, canonical origin, current main, installed hooks and target tag.
-It creates `chore/release-vX.Y.Z`, updates the version and
-changelog, runs `bundle lock --add-checksums` and the full `rake verify`, then
-commits the three metadata files with hooks enabled, pushes the branch, and opens a
-`chore(release): prepare vX.Y.Z` PR. Main stays unchanged. You can also start on
-that exact pre-created release branch if its HEAD still equals `origin/main`.
-When starting from main, a leftover local release branch is recreated only if
-all its commits are already in main; unmerged work is preserved and stops the task.
-
-Review the generated notes, lockfile and version in the PR. Add or adjust upgrade
-notes in a follow-up commit when needed, rerun affected checks locally, and wait
-for commitlint before merging. The task
-prints the PR URL and makes clear that merging it publishes the release.
-
-### Merge and publish
-
-Merging a same-repository `chore/release-vX.Y.Z` PR into main runs the shared
-workflow against its exact merge commit, including squash and rebase merges:
-
-1. Verify the expected version, main ancestry, notes and committed package bytes;
-   build one release artifact through Bundler. Tests and lint already ran locally
-   during `release:prepare` and are not repeated in Actions.
-2. Create and push the annotated `vX.Y.Z` tag without overwriting existing tags
-   or following unrelated local tags.
-3. In an isolated job, verify the artifact's SHA-256 checksums, obtain the proper
-   registry credentials, and publish that exact gem.
-4. In a separate job, create the GitHub release with the same gem and notes.
-
-There is no manual tagging step in the normal flow. Build, tag and publication
-continue in the same run because a tag pushed by GitHub's `GITHUB_TOKEN` does not
-start another workflow. Existing manually pushed annotated version tags remain a
-supported trigger and receive full canonical-tag verification.
-
-Publish and notes jobs never check out or evaluate consumer code. Public gems
-use short-lived OIDC credentials; private gems use the workflow token or an
-explicit override. Both profiles push the same verified artifact to their
-configured host; no registry fallback exists.
-
-### Failures and retries
-
-If preparation fails, inspect `git status` and `git diff`. A failed verification
-leaves changes on the local release branch without a release commit or push.
-Fix and finish that ordinary branch, or restore the changes before starting over.
-If the commit/push succeeded but opening the PR failed, use
-`gh pr create --base main --head chore/release-vX.Y.Z --fill` after fixing access.
-There is no journal or automatic reset of your working tree.
-
-If credential setup fails with `No trusted publisher configured for this workflow`,
-check the consumer's RubyGems settings against the table above. A successful
-build and tag do not mean the gem was published. When `gem push` was skipped,
-correct the publisher settings, then rerun **failed jobs only** in the original
-workflow run. This reuses its verified artifact and existing tag; do not run
-`release:prepare` again, bump the version or replace the tag for this failure.
-
-```sh
-gh run rerun RUN_ID --repo OWNER/REPOSITORY --failed
-```
-
-If a failed build needs a source fix and no tag or upload exists, keep the
-prepared version and notes. Update its `chore/release-vX.Y.Z` branch from main,
-commit the fix, run verification and open a replacement release PR. Merge that
-PR to run the corrected source. The original run stays pinned to its original
-commit; rerunning it cannot pick up a source fix. Do not replace an existing tag
-or reuse a version that was already published.
-
-For transient CI failures, retry **failed jobs in the original run** within GitHub's 30-day
-retry window. Artifacts are retained for 90 days. A failed tag step can reuse an
-existing annotated tag only when it points to the same verified commit. A failed
-notes job reuses the original artifact without uploading again. Ambiguous uploads,
-already published versions, existing GitHub releases or expired runs/artifacts
-require registry/release reconciliation. Never replace a tag or rebuild a
-published version to repair release notes.
-
-Provider references: [reusable RubyGems trusted publishers](https://guides.rubygems.org/trusted-publishing/#using-reusable-workflows),
-[GitHub token-trigger behavior](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow),
-and [failed-job retries](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/re-run-workflows-and-jobs).
+See the [release guide](docs/releasing.md) for registry permissions, trusted
+publishers, version selection, merge behaviour and recovery. The guide is
+versioned with the release tooling it describes.
 
 GitLab is a separate optional [workflow](.github/workflows/sync-gitlab.yml).
 Only add its caller when a target exists, passing an SSH `url`, a project write
@@ -254,19 +151,24 @@ push, without tags, force or deletions. Provision target visibility no broader
 than the source. Local bare-repository fixtures cover repeat/stale events and
 divergence; live SSH credentials and host keys still require target validation.
 
+## Development and releases
+
 Develop with `bundle install` and `bundle exec rake verify`. Release and registry
 fixtures live in tests, using real Git and native gem builds with fake network
 publishers. No production rehearsal command or registry client is required.
 
-## Built by Ethos Link
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).
+
+## About Ethos Link
+
+[Ethos Link](https://www.ethos-link.com) is a software company founded by
+[Paulo Fidalgo](https://www.fidalgo.pt). This gem is part of the open-source
+tooling we publish alongside our business products:
 
-[Ethos Link](https://www.ethos-link.com) builds business software and integrations
-that replace manual handoffs with connected workflows. We help teams automate
-routine work, use their data and improve the processes their business runs on.
+- [Reviato](https://www.reviato.com): collect private customer feedback and analyse public reviews.
+- [Nuntio](https://www.nuntiohq.com): prepare, review and schedule social posts.
+- [EthosPlaces](https://www.ethos.place): find places, opening hours and contact details.
 
-- [Reviato](https://www.reviato.com): Read public review trends and collect
-  private customer feedback, so your team can decide what to improve.
-- [EthosPlaces](https://www.ethos.place): Give customers the details they need to
-  choose and visit your business, from opening hours to directions.
-- [Nuntio](https://www.nuntiohq.com): Draft, review and schedule social posts in
-  one workspace, then track each publishing result.
+Explore our [open-source projects](https://www.ethos-link.com/opensource).

data/UPGRADE.md

@@ -1,5 +1,47 @@
 # Upgrading Gemkit
 
+## Next release
+
+Install mise (CI uses 2026.10.19) and run `bundle exec rake tools:install` after
+upgrading the gem and matching workflow pins. Gemkit now uses native git-cliff
+and GitHub CLI binaries pinned in its shipped `mise.toml` and `mise.lock`.
+Node.js/npm is not required. Existing global CLI installations are no longer
+used by verification or release preparation. git-cliff stays at 2.12.0 for this
+installation change; GitHub CLI is pinned to 2.103.2.
+
+## Maintaining tool versions
+
+Dependabot checks Ruby dependencies and GitHub Actions weekly. Review the mise
+CLI, tool pins and system dependencies monthly, or sooner for security fixes;
+Dependabot does not update mise tool versions. Do not auto-merge tool upgrades.
+
+To update a tool, edit its exact version in `mise.toml`, then regenerate the
+lockfile for every supported platform and install it:
+
+```sh
+mise lock --platform linux-x64,linux-arm64,macos-x64,macos-arm64
+bundle exec rake tools:install
+bundle exec rake verify
+```
+
+Commit `mise.toml` and `mise.lock` together. For Ruby updates, also update
+`.ruby-version` and every `ruby/setup-ruby` pin; preserve native Bundler caching
+in CI. For GitHub CLI updates, also update the release-notes job's isolated mise
+configuration. Tests reject version drift in these duplicated pins. For mise
+updates, keep the action's `version` input aligned across jobs and verify with
+that version locally. Review Bundler's explicit version separately and keep
+local installation aligned with the workflow pins.
+
+Verification exercises changelog parsing, release preparation against disposable
+Git repositories, and registry fixtures. Review changed changelog output before
+accepting an upgrade, and wait for commitlint before merging. Tests and lint remain local. Never
+use a real consumer release, tag or registry publication as a test. Update
+consumer gem and workflow pins together after the toolkit release.
+
+Git and shell utilities follow the host or CI runner image. Review image
+upgrades separately; exact OS parity would require a shared container. Keep
+Bundler-owned tools in Bundler rather than adding them to mise.
+
 ## 0.3.1
 
 Run `bundle exec rake verify` locally before pushing. `release:prepare` still

data/docs/releasing.md

@@ -0,0 +1,172 @@
+# Releasing a gem
+
+[README](../README.md) · [Project guide](https://www.ethos-link.com/opensource/ethos-gemkit)
+
+**Run `release:prepare` from clean, up-to-date `main`.** It creates the conventional
+release branch and opens a PR. **Merging that release PR starts publication.**
+This is the same process for Gemkit itself and its adopted consumer gems.
+Ordinary feature/fix PRs run commitlint; only a release PR starts publication.
+
+## One-time prerequisites
+
+- Commit `Gemfile.lock`. Before its first commit, run
+  `bundle lock --add-checksums`; frozen CI installs reject empty registry
+  checksum entries, even when the gems are already installed locally.
+- Ignore `/.bundle/`, `/vendor/bundle/` and `/pkg/` in `.gitignore`. The shared
+  workflows use Ruby setup's native `vendor/bundle` cache; generated files must
+  leave the release checkout clean.
+- Install the bundle, Git and mise. Run
+  `bundle exec rake tools:install`. Configure your Git identity,
+  authenticate with `gh auth login`, and install hooks with
+  `bundle exec lefthook install`. You need permission to push branches and open PRs.
+- Public gems: configure a matching RubyGems trusted publisher for **each gem**
+  before merging its first release PR. Use the exact settings below. Gemkit's
+  publisher does not authorize consumer gems.
+- A new gem also needs a pending trusted publisher. Supply its numeric RubyGems
+  owner through the caller's `rubygems-owner` input or the repository/organization
+  variable `RUBYGEMS_OWNER` (the publisher account used by Tunnel is `27209`).
+- Private gems: set `registry: github_packages`. Publishing uses the workflow's
+  short-lived `GITHUB_TOKEN`; the package must grant its repository Actions access.
+  Pass `PACKAGES_TOKEN` only when an explicit token override is needed. Local
+  installation from other private repositories still needs `read:packages` access.
+- Configure the `rubygems` GitHub environment to allow `main` and `v*` tags.
+  Release callers grant `contents: write`, `id-token: write` and `packages: write`.
+  Repository rules must permit the workflow's annotated release tags.
+
+The SDK release workflow listens directly for merged release PRs and version-tag
+pushes. Consumer callers must listen for both `pull_request: types: [closed]`
+against `main` and `push: tags: ["v*"]`, and pin the commit matching the installed
+Gemkit release.
+See the [Tunnel caller](https://github.com/ethos-link/cloudflare-tunnel/blob/main/.github/workflows/release.yml).
+
+Projects keep their own local checks. Engines can register `checks: [ci:local]`
+in `.ethos-gemkit.yml` and have that task run `bin/ci`. Provision PostgreSQL or
+browser dependencies locally before running verification. Release callers do
+not install test dependencies or accept `build-setup`.
+
+## RubyGems trusted-publisher settings
+
+On RubyGems, open the **consumer gem's** page, then **Trusted publishers**. For
+Cloudflare Tunnel, create or update the publisher with these exact values:
+
+| RubyGems field | Value |
+|---|---|
+| Repository owner | `ethos-link` |
+| Repository name | `cloudflare-tunnel` |
+| Workflow filename | `release.yml` |
+| Environment | `rubygems` |
+| Workflow Repository Owner | `ethos-link` |
+| Workflow Repository Name | `ethos-gemkit` |
+
+The repository identifies the consumer; the Workflow Repository fields identify
+the repository containing the shared workflow file. Those last two fields are
+required for consumers,
+even though RubyGems labels them optional. For another consumer, substitute its
+repository name. For Gemkit itself, use repository name `ethos-gemkit` and leave
+both Workflow Repository fields blank because the workflow is in the same repo.
+
+The numeric `rubygems-owner` input identifies the account for pending publishers;
+it does not register a publisher or grant access to a consumer gem. See the
+[upstream reusable-workflow instructions](https://guides.rubygems.org/trusted-publishing/#using-reusable-workflows).
+
+## Prepare and review
+
+For a normal patch release:
+
+```sh
+git switch main
+git pull --ff-only
+bundle install
+bundle exec rake release:prepare
+```
+
+The default is `patch`. Select another target explicitly:
+
+```sh
+bundle exec rake 'release:prepare[minor]'
+bundle exec rake 'release:prepare[major]'
+bundle exec rake 'release:prepare[1.2.0]'
+```
+
+For an initial, unpublished version that is already in the gemspec and has no
+tag, an explicit current version is supported. For example, a new gem starting
+at 0.1.0 can use `bundle exec rake 'release:prepare[0.1.0]'` after pending-publisher
+setup.
+
+The task prints each step and streams command output as it runs. It checks the
+working tree, canonical origin, current main, installed hooks and target tag.
+It creates `chore/release-vX.Y.Z`, updates the version and
+changelog, runs `bundle lock --add-checksums` and the full `rake verify`, then
+commits the three metadata files with hooks enabled, pushes the branch, and opens a
+`chore(release): prepare vX.Y.Z` PR. Main stays unchanged. You can also start on
+that exact pre-created release branch if its HEAD still equals `origin/main`.
+When starting from main, a leftover local release branch is recreated only if
+all its commits are already in main; unmerged work is preserved and stops the task.
+
+Review the generated notes, lockfile and version in the PR. Add or adjust upgrade
+notes in a follow-up commit when needed, rerun affected checks locally, and wait
+for commitlint before merging. The task
+prints the PR URL and makes clear that merging it publishes the release.
+
+## Merge and publish
+
+Merging a same-repository `chore/release-vX.Y.Z` PR into main runs the shared
+workflow against its exact merge commit, including squash and rebase merges:
+
+1. Verify the expected version, main ancestry, notes and committed package bytes;
+   build one release artifact through Bundler. Tests and lint already ran locally
+   during `release:prepare` and are not repeated in Actions.
+2. Create and push the annotated `vX.Y.Z` tag without overwriting existing tags
+   or following unrelated local tags.
+3. In an isolated job, verify the artifact's SHA-256 checksums, obtain the proper
+   registry credentials, and publish that exact gem.
+4. In a separate job, create the GitHub release with the same gem and notes.
+
+There is no manual tagging step in the normal flow. Build, tag and publication
+continue in the same run because a tag pushed by GitHub's `GITHUB_TOKEN` does not
+start another workflow. Existing manually pushed annotated version tags remain a
+supported trigger and receive full canonical-tag verification.
+
+Publish and notes jobs never check out or evaluate consumer code. Public gems
+use short-lived OIDC credentials; private gems use the workflow token or an
+explicit override. Both profiles push the same verified artifact to their
+configured host; no registry fallback exists.
+
+## Failures and retries
+
+If preparation fails, inspect `git status` and `git diff`. A failed verification
+leaves changes on the local release branch without a release commit or push.
+Fix and finish that ordinary branch, or restore the changes before starting over.
+If the commit/push succeeded but opening the PR failed, use
+`gh pr create --base main --head chore/release-vX.Y.Z --fill` after fixing access.
+There is no journal or automatic reset of your working tree.
+
+If credential setup fails with `No trusted publisher configured for this workflow`,
+check the consumer's RubyGems settings against the table above. A successful
+build and tag do not mean the gem was published. When `gem push` was skipped,
+correct the publisher settings, then rerun **failed jobs only** in the original
+workflow run. This reuses its verified artifact and existing tag; do not run
+`release:prepare` again, bump the version or replace the tag for this failure.
+
+```sh
+gh run rerun RUN_ID --repo OWNER/REPOSITORY --failed
+```
+
+If a failed build needs a source fix and no tag or upload exists, keep the
+prepared version and notes. Update its `chore/release-vX.Y.Z` branch from main,
+commit the fix, run verification and open a replacement release PR. Merge that
+PR to run the corrected source. The original run stays pinned to its original
+commit; rerunning it cannot pick up a source fix. Do not replace an existing tag
+or reuse a version that was already published.
+
+For transient CI failures, retry **failed jobs in the original run** within GitHub's 30-day
+retry window. Artifacts are retained for 90 days. A failed tag step can reuse an
+existing annotated tag only when it points to the same verified commit. A failed
+notes job reuses the original artifact without uploading again. Ambiguous uploads,
+already published versions, existing GitHub releases or expired runs/artifacts
+require registry/release reconciliation. Never replace a tag or rebuild a
+published version to repair release notes.
+
+Provider references: [reusable RubyGems trusted publishers](https://guides.rubygems.org/trusted-publishing/#using-reusable-workflows),
+[GitHub token-trigger behavior](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow),
+and [failed-job retries](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/re-run-workflows-and-jobs).

data/lib/ethos/gemkit/release.rb

@@ -4,6 +4,7 @@ require "open3"
 require "bundler"
 require_relative "configuration"
 require_relative "branch"
+require_relative "tools"
 
 module Ethos
   module Gemkit
@@ -18,6 +19,8 @@ module Ethos
 
       # Release metadata uses an ordinary branch and PR; main is never committed.
       def prepare(target = "patch")
+        git_cliff = Tools.executable("git-cliff")
+        github = Tools.executable("gh")
         progress "Checking working tree and repository"
         clean
         canonical_origin
@@ -53,7 +56,7 @@ module Ethos
           raise Error, "Start from main or #{branch} at origin/main"
         end
         progress "Checking GitHub authentication"
-        run("gh", "auth", "status", "--hostname", "github.com")
+        run(github, "auth", "status", "--hostname", "github.com")
         progress "Preparing #{branch}"
         if current_branch == "main"
           unless git("branch", "--list", branch).empty?
@@ -67,7 +70,7 @@ module Ethos
         Branch.check(@config.root)
         progress "Updating version and changelog to #{target}"
         File.write(file, text.sub(literal, %(VERSION = "#{target}")))
-        run("git-cliff", "--config", "cliff.toml", "--unreleased", "--tag", "v#{target}", "--prepend", "CHANGELOG.md", live: true)
+        run(git_cliff, "--config", "cliff.toml", "--unreleased", "--tag", "v#{target}", "--prepend", "CHANGELOG.md", live: true)
         progress "Updating Gemfile.lock"
         run("bundle", "lock", "--add-checksums", live: true)
         progress "Running verification (lint, tests, package, changelog)"
@@ -85,7 +88,7 @@ module Ethos
         progress "Pushing #{branch}"
         run("git", "push", "--no-follow-tags", "--set-upstream", "origin", branch, live: true)
         progress "Opening release PR"
-        url = run("gh", "pr", "create", "--repo", @config.data.fetch("repository"),
+        url = run(github, "pr", "create", "--repo", @config.data.fetch("repository"),
           "--base", "main", "--head", branch, "--title", title,
           "--body", "#{body}\n\nMerging this PR creates annotated tag v#{target} and publishes the verified gem.").strip
         "#{url}\nMerge this release PR to tag and publish v#{target}."

data/lib/ethos/gemkit/tasks.rb

@@ -3,6 +3,7 @@
 require "standard/rake"
 require_relative "configuration"
 require_relative "package"
+require_relative "tools"
 
 config = Ethos::Gemkit::Configuration.load
 standard = YAML.safe_load_file(config.path(".standard.yml"), aliases: false)
@@ -11,6 +12,11 @@ unless standard.is_a?(Hash) && standard["ruby_version"].to_s == "4.0" && Array(s
 end
 task lint: :standard
 task "lint:fix" => "standard:fix"
+desc "Install pinned development binaries with mise"
+task "tools:install" do
+  sh "mise", "trust", File.join(Ethos::Gemkit::Tools::ROOT, "mise.toml")
+  sh "mise", "--cd", Ethos::Gemkit::Tools::ROOT, "install", "--locked", "git-cliff", "gh"
+end
 task "package:verify" do
   Ethos::Gemkit::Package.new(config).verify
 end
@@ -18,5 +24,5 @@ end
 desc "Run lint, gem checks, package validation and changelog validation"
 task verify: [:lint, *config.checks, "package:verify"] do
   require "tempfile"
-  Tempfile.create("gemkit-changelog") { |file| sh "git-cliff", "--config", "cliff.toml", "--unreleased", "--output", file.path }
+  Tempfile.create("gemkit-changelog") { |file| sh Ethos::Gemkit::Tools.executable("git-cliff"), "--config", "cliff.toml", "--unreleased", "--output", file.path }
 end

data/lib/ethos/gemkit/tools.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "../gemkit"
+
+module Ethos
+  module Gemkit
+    module Tools
+      ROOT = File.expand_path("../../..", __dir__)
+
+      # Resolve against the installed gem, even when called from a consumer.
+      # --tool prevents an unrelated executable on PATH from satisfying lookup.
+      def self.executable(name)
+        output, error, status = Open3.capture3("mise", "--cd", ROOT, "which", "--tool", name, name)
+        unless status.success? && File.executable?(output.strip)
+          raise Error, "Install pinned #{name} with bundle exec rake tools:install: #{error.strip}"
+        end
+        output.strip
+      rescue Errno::ENOENT
+        raise Error, "Install mise, then run bundle exec rake tools:install"
+      end
+    end
+  end
+end

data/lib/ethos/gemkit/version.rb

@@ -2,6 +2,6 @@
 
 module Ethos
   module Gemkit
-    VERSION = "0.3.1"
+    VERSION = "0.3.2"
   end
 end

data/mise.lock

@@ -0,0 +1,91 @@
+# @generated - this file is auto-generated by `mise lock` https://mise.jdx.dev/dev-tools/mise-lock.html
+
+lockfile_version = 3
+
+[[tools.gh]]
+version = "2.103.2"
+backend = "aqua:cli/cli"
+specifiers = ["2.103.2"]
+
+[tools.gh."platforms.linux-arm64"]
+checksum = "sha256:4c3e99a50bd8b181a3fe9d69b25dd978bac768148d88f01507c6b4d1ef61a443"
+url = "https://github.com/cli/cli/releases/download/v2.103.2/gh_2.103.2_linux_arm64.tar.gz"
+url_api = "https://api.github.com/repos/cli/cli/releases/assets/670305069"
+provenance = "github-attestations"
+
+[tools.gh."platforms.linux-x64"]
+checksum = "sha256:62ccf747115ddc61237efffdde66a3c8f70ba249433dc64f70801089b59c59c8"
+url = "https://github.com/cli/cli/releases/download/v2.103.2/gh_2.103.2_linux_amd64.tar.gz"
+url_api = "https://api.github.com/repos/cli/cli/releases/assets/670305062"
+provenance = "github-attestations"
+
+[tools.gh."platforms.macos-arm64"]
+checksum = "sha256:5416000f5d17580a187339e0c4068a01ca5c87f7d4fe6ca64933696f967bc418"
+url = "https://github.com/cli/cli/releases/download/v2.103.2/gh_2.103.2_macOS_arm64.zip"
+url_api = "https://api.github.com/repos/cli/cli/releases/assets/670305145"
+provenance = "github-attestations"
+
+[tools.gh."platforms.macos-x64"]
+checksum = "sha256:2dc7f1fc4761f96732995f6e4f4c6b4d705f2635da4126620c8b30eaa67b9c98"
+url = "https://github.com/cli/cli/releases/download/v2.103.2/gh_2.103.2_macOS_amd64.zip"
+url_api = "https://api.github.com/repos/cli/cli/releases/assets/670305131"
+provenance = "github-attestations"
+
+[[tools.git-cliff]]
+version = "2.12.0"
+backend = "aqua:orhun/git-cliff"
+specifiers = ["2.12.0"]
+
+[tools.git-cliff."platforms.linux-arm64"]
+checksum = "sha256:9d7aa3c1a860d9c9813458fcdd1846e2859c560d86c7b401e5e58dc10790f94b"
+checksum_source = "mise-versions"
+url = "https://github.com/orhun/git-cliff/releases/download/v2.12.0/git-cliff-2.12.0-aarch64-unknown-linux-gnu.tar.gz"
+url_api = "https://api.github.com/repos/orhun/git-cliff/releases/assets/343377984"
+
+[tools.git-cliff."platforms.linux-x64"]
+checksum = "sha256:6241bd23554daf527ca8ff0dc475a272b0155bede8a000e7a9d74b771036a7bd"
+checksum_source = "mise-versions"
+url = "https://github.com/orhun/git-cliff/releases/download/v2.12.0/git-cliff-2.12.0-x86_64-unknown-linux-gnu.tar.gz"
+url_api = "https://api.github.com/repos/orhun/git-cliff/releases/assets/343377955"
+
+[tools.git-cliff."platforms.macos-arm64"]
+checksum = "sha256:2ae72a0061bee98d0e375f2ea8e0f4b23b4915ac2e37fa45a705066de49b43a0"
+checksum_source = "mise-versions"
+url = "https://github.com/orhun/git-cliff/releases/download/v2.12.0/git-cliff-2.12.0-aarch64-apple-darwin.tar.gz"
+url_api = "https://api.github.com/repos/orhun/git-cliff/releases/assets/343378832"
+
+[tools.git-cliff."platforms.macos-x64"]
+checksum = "sha256:fd4bce35ea8a6f3af6ac4891073781ca24c654c36c83c865bc30bab332c05a14"
+checksum_source = "mise-versions"
+url = "https://github.com/orhun/git-cliff/releases/download/v2.12.0/git-cliff-2.12.0-x86_64-apple-darwin.tar.gz"
+url_api = "https://api.github.com/repos/orhun/git-cliff/releases/assets/343379425"
+
+[[tools.ruby]]
+version = "4.0.9"
+backend = "core:ruby"
+specifiers = ["4.0.9"]
+
+[tools.ruby.options]
+compile = "false"
+precompiled_url = "jdx/ruby"
+ruby_build_repo = "https://github.com/rbenv/ruby-build.git"
+ruby_install = "false"
+
+[tools.ruby."platforms.linux-arm64"]
+checksum = "sha256:e115ae4dce7193d862e1f105d7969472f0fcead4a440bbb08c9af92528ed0dd9"
+url = "https://github.com/jdx/ruby/releases/download/4.0.9-1/ruby-4.0.9.arm64_linux.tar.gz"
+provenance = "github-attestations"
+
+[tools.ruby."platforms.linux-x64"]
+checksum = "sha256:7e74db7ddb8f44f534fa4937d98b6d1691e053c5c190af6d130464b0467e87c4"
+url = "https://github.com/jdx/ruby/releases/download/4.0.9-1/ruby-4.0.9.x86_64_linux.tar.gz"
+provenance = "github-attestations"
+
+[tools.ruby."platforms.macos-arm64"]
+checksum = "sha256:6eca5d2aaf6bb6c805daa31b4139a3c974526f41dae990ab0cef0ee3db8ea5d1"
+url = "https://github.com/jdx/ruby/releases/download/4.0.9-1/ruby-4.0.9.macos.tar.gz"
+provenance = "github-attestations"
+
+[tools.ruby."platforms.macos-x64"]
+checksum = "sha256:c35350682ff050b79702d57ade4516e7336063f510155d19fb2fb5b3f3909511"
+url = "https://cache.ruby-lang.org/pub/ruby/4.0/ruby-4.0.9.tar.gz"

data/mise.toml

@@ -0,0 +1,4 @@
+[tools]
+ruby = "4.0.9"
+git-cliff = "2.12.0"
+gh = "2.103.2"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ethos-gemkit
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Ethos Link
@@ -92,6 +92,7 @@ files:
 - LICENSE.txt
 - README.md
 - UPGRADE.md
+- docs/releasing.md
 - exe/ethos-gemkit
 - lib/ethos-gemkit.rb
 - lib/ethos/gemkit.rb
@@ -104,11 +105,17 @@ files:
 - lib/ethos/gemkit/release.rb
 - lib/ethos/gemkit/release_tasks.rb
 - lib/ethos/gemkit/tasks.rb
+- lib/ethos/gemkit/tools.rb
 - lib/ethos/gemkit/version.rb
-homepage: https://github.com/ethos-link/ethos-gemkit
+- mise.lock
+- mise.toml
+homepage: https://www.ethos-link.com/opensource/ethos-gemkit
 licenses:
 - MIT
 metadata:
+  homepage_uri: https://www.ethos-link.com/opensource/ethos-gemkit
+  documentation_uri: https://www.ethos-link.com/opensource/ethos-gemkit
+  bug_tracker_uri: https://github.com/ethos-link/ethos-gemkit/issues
   allowed_push_host: https://rubygems.org
   source_code_uri: https://github.com/ethos-link/ethos-gemkit
   changelog_uri: https://github.com/ethos-link/ethos-gemkit/blob/main/CHANGELOG.md