ethos-gemkit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5445351e6ccbd6c2155a603d7c7fcf5d57e3e6a2e275cafa307431c4f4ae63fb
+  data.tar.gz: 8b2a74b858376f970c096b2599e5607eb88ca8b78e2ba53f11485d4a2b4d8059
+SHA512:
+  metadata.gz: 9cdf0c22ba2d534f270e02904ddc018ebad5448b68bf656ecdd3fceea8f8408b241f108da2f6024a253c67d291d63dbae7e13e3a3fd14c628d8bdcaeab2a5138
+  data.tar.gz: d9464b72094dafe244db34ac048e8dda59154784df181db4005c674b217fe946f8d873ecb323617531543b5faa13ffde4f22af1d44b352f40f5576209ed41033

data/CHANGELOG.md

@@ -0,0 +1,124 @@
+# Changelog
+
+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.1.0] - 2026-11-04
+
+
+### Added
+
+- bootstrap shared gem development contracts
+
+- enforce the shared commit message policy
+
+- centralize verified gem release orchestration
+
+- prepare release PRs and publish after merging
+
+
+
+
+### Changed
+
+- exercise standalone core operations
+
+- expose shared commit message validation
+
+- replace release orchestration with native workflows
+
+- remove the redundant bootstrap fixture
+
+
+
+
+### Fixed
+
+- lock toolkit development to patched Active Support
+
+- disable inherited publishing tasks
+
+- complete checksums for frozen hosted installs
+
+- declare and isolate framework fixture dependencies
+
+- bind package files to the verified tag tree
+
+- expose scoped bundle executables to subprocesses
+
+- retain confirmed publication evidence for recovery
+
+- scope source fetch authentication to GitHub
+
+- select the current artifact run explicitly
+
+- prevent implicit pushes of unrelated tags
+
+- bootstrap Bundler for plain rake commands
+
+- keep Bundler's CI cache out of release source
+
+- recycle fully merged local release branches
+
+
+
+## [0.1.0] - 2026-11-04
+
+
+### Added
+
+- bootstrap shared gem development contracts
+
+- enforce the shared commit message policy
+
+- centralize verified gem release orchestration
+
+- prepare release PRs and publish after merging
+
+
+
+
+### Changed
+
+- exercise standalone core operations
+
+- expose shared commit message validation
+
+- replace release orchestration with native workflows
+
+- remove the redundant bootstrap fixture
+
+
+
+
+### Fixed
+
+- lock toolkit development to patched Active Support
+
+- disable inherited publishing tasks
+
+- complete checksums for frozen hosted installs
+
+- declare and isolate framework fixture dependencies
+
+- bind package files to the verified tag tree
+
+- expose scoped bundle executables to subprocesses
+
+- retain confirmed publication evidence for recovery
+
+- scope source fetch authentication to GitHub
+
+- select the current artifact run explicitly
+
+- prevent implicit pushes of unrelated tags
+
+- bootstrap Bundler for plain rake commands
+
+
+
+# Changelog
+
+Changes are generated from Conventional Commits when preparing a release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ethos Link
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,168 @@
+# Ethos Gemkit
+
+Shared development defaults for Ethos Link gems: Ruby 4, Standard, optional Rails
+8 linting, hooks, package checks and one shared release workflow. The toolkit
+belongs in the development/test Gemfile, never a consumer's runtime gemspec.
+
+During bootstrap, pin the Git dependency and workflow callers to the same reviewed
+commit; the toolkit has not been published. See the working
+[Cloudflare Tunnel Gemfile](https://github.com/ethos-link/cloudflare-tunnel/blob/feat/ethos-gemkit/Gemfile).
+
+A standard gem needs this Rakefile:
+
+```ruby
+require "bundler/setup"
+require "ethos/gemkit/rake"
+```
+
+Use the native configuration files rather than a setup generator:
+
+```yaml
+# .standard.yml
+ruby_version: "4.0"
+plugins:
+  - ethos-gemkit
+```
+
+Keep Standard exclusions locally. The plugin detects Rails 8 components from the
+bundle without booting an application; plain Ruby and Active Support-only bundles
+use Ruby rules. SDK Rake tasks reject configurations that omit the shared plugin.
+Existing hooks call `bundle exec ethos-gemkit guard` before commits and
+`bundle exec ethos-gemkit commitlint --message {1}` for commit messages. Install
+hooks with `bundle exec lefthook install`. Direct main/master commits are blocked.
+
+No `.ethos-gemkit.yml` is needed for standard public gems. Private gems declare
+`registry: github_packages`; custom checks use `checks: [ci:local]`. Optional
+`gem_name`, `repository` and `version_file` override the one-gemspec, Ethos Link
+repository and one-version-file conventions. Unknown keys and unsafe paths fail.
+The lower-level `ethos/gemkit/tasks` entrypoint retains existing custom test and
+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.
+
+## 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 verification; only a release PR starts publication.
+
+### One-time prerequisites
+
+- 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 RubyGems trusted publishing for the gem. Use environment
+  `rubygems`, workflow filename `release.yml`, and the consumer owner/repository.
+  For a consumer such as Tunnel, set workflow repository owner `ethos-link` and
+  workflow repository `ethos-gemkit`. For Gemkit's own publisher, leave those
+  optional workflow-repository fields blank because it is the same repository.
+- 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 Ethos account used by Tunnel is `27209`).
+- Private gems: set the GitHub Packages registry profile and pass a scoped
+  `PACKAGES_TOKEN` secret to the release workflow. The two profiles use the same
+  native `gem push` with their respective host and credentials.
+- Configure the `rubygems` GitHub environment to allow releases from `main` and
+  `v*` tags. Grant the release workflow contents-write and id-token-write
+  permissions; repository rules must permit its 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 same SDK commit as the Gemfile.
+See the [Tunnel caller](https://github.com/ethos-link/cloudflare-tunnel/blob/feat/ethos-gemkit/.github/workflows/release.yml).
+
+### 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. Gemkit's initial release can use
+`bundle exec rake 'release:prepare[0.1.0]'` after pending-publisher setup.
+
+The task 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 --local` 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, and wait for CI 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, committed package bytes and
+   all registered checks; build one release artifact through Bundler.
+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 supplied scoped token.
+No registry fallback exists. Live private publication still needs a private pilot.
+
+### 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.
+
+For 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).
+
+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
+deploy key and independently verified known hosts. Without a URL the job skips;
+Cloudflare Tunnel has no caller. It copies current main using a fast-forward
+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.
+
+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.

data/exe/ethos-gemkit

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "ethos/gemkit/branch"
+require "ethos/gemkit/commit_message"
+require "optparse"
+
+begin
+  command = ARGV.shift
+  case command
+  when "commitlint"
+    input = nil
+    OptionParser.new do |opts|
+      opts.on("--message MESSAGE_OR_FILE") { |value| input = value }
+    end.parse!(ARGV)
+    abort "Usage: ethos-gemkit commitlint --message MESSAGE_OR_FILE" if input.nil? || !ARGV.empty?
+    message = File.file?(input) ? File.read(input) : input
+    Ethos::Gemkit::CommitMessage.validate(message)
+    puts "Commit message valid"
+  when "guard"
+    abort "Usage: ethos-gemkit guard" unless ARGV.empty?
+    Ethos::Gemkit::Branch.check
+  when "version", "--version"
+    puts Ethos::Gemkit::VERSION
+  else
+    abort "Usage: ethos-gemkit guard | commitlint --message MESSAGE_OR_FILE | --version"
+  end
+rescue Ethos::Gemkit::Error, OptionParser::ParseError => error
+  abort error.message
+end

data/lib/ethos/gemkit/branch.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "../gemkit"
+
+module Ethos
+  module Gemkit
+    class Branch
+      def self.check(root = Dir.pwd)
+        output, error, status = Open3.capture3("git", "branch", "--show-current", chdir: root)
+        raise Error, "Cannot inspect Git branch: #{error.strip}" unless status.success?
+        branch = output.strip
+        if branch.empty? || %w[main master].include?(branch)
+          raise Error, "Use a feature branch; direct commits to main/master or detached HEAD are blocked"
+        end
+        true
+      end
+    end
+  end
+end

data/lib/ethos/gemkit/commit_message.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "../gemkit"
+
+module Ethos
+  module Gemkit
+    class CommitMessage
+      TYPES = %w[feat fix chore refactor docs test perf ci build].freeze
+
+      def self.validate(message)
+        cleaned = message.lines.reject { |line| line.start_with?("#") }.join.strip
+        header = cleaned.lines.first.to_s.chomp
+        type = header[/\A([a-z]+)(?:\([^()\n]+\))?!?: \S/, 1]
+        unless TYPES.include?(type)
+          raise Error, "Use a Conventional Commit header with one of: #{TYPES.join(", ")}"
+        end
+        raise Error, "Commit subject must be at most 72 characters" if header.length > 72
+        if cleaned.lines.size > 1 && !cleaned.lines[1].strip.empty?
+          raise Error, "Separate the commit subject and body with a blank line"
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/ethos/gemkit/configuration.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "../gemkit"
+
+module Ethos
+  module Gemkit
+    class Configuration
+      KEYS = %w[gem_name repository version_file registry checks].freeze
+      REGISTRIES = {"rubygems" => "https://rubygems.org", "github_packages" => "https://rubygems.pkg.github.com/ethos-link"}.freeze
+
+      attr_reader :root, :data
+
+      def self.load(root = Dir.pwd)
+        path = File.join(root, ".ethos-gemkit.yml")
+        new(root, File.exist?(path) ? YAML.safe_load_file(path, permitted_classes: [], permitted_symbols: [], aliases: false) : {})
+      rescue Psych::Exception, Errno::ENOENT => error
+        raise Error, "Cannot load .ethos-gemkit.yml: #{error.message}"
+      end
+
+      def initialize(root, data)
+        @root = File.realpath(root)
+        raise Error, "Configuration must be a mapping" unless data.is_a?(Hash)
+        gemspecs = Dir[File.join(@root, "*.gemspec")]
+        raise Error, "Expected exactly one gemspec, or an explicit gem_name" if !data["gem_name"] && !gemspecs.one?
+        name = data["gem_name"] || File.basename(gemspecs.first, ".gemspec")
+        versions = Dir[File.join(@root, "lib/**/version.rb")].reject { |file| file.include?("templates/") }
+        registry = data.fetch("registry", "rubygems")
+        registry = {"kind" => registry, "host" => REGISTRIES[registry]} if registry.is_a?(String)
+        @data = {"gem_name" => name,
+                 "repository" => "ethos-link/#{name}", "checks" => ["test"],
+                 "version_file" => versions.one? ? versions.first.delete_prefix(@root + "/") : "lib/#{name}/version.rb"}.merge(data).merge("registry" => registry)
+        validate
+      end
+
+      def name
+        data.fetch("gem_name")
+      end
+
+      def checks
+        data.fetch("checks")
+      end
+
+      def path(relative)
+        unless relative.is_a?(String) && !relative.empty? && !Pathname.new(relative).absolute?
+          raise Error, "Expected a relative repository path"
+        end
+        expanded = File.expand_path(relative, root)
+        unless expanded.start_with?(root + File::SEPARATOR)
+          raise Error, "Path escapes repository: #{relative}"
+        end
+        # Existing symlinks must stay inside the checkout too.
+        parent = expanded
+        parent = File.dirname(parent) until File.exist?(parent) || File.symlink?(parent)
+        if File.symlink?(parent) && !File.exist?(parent)
+          raise Error, "Dangling symlink is not a repository path: #{relative}"
+        end
+        unless File.realpath(parent).start_with?(root + File::SEPARATOR) || File.realpath(parent) == root
+          raise Error, "Symlink escapes repository: #{relative}"
+        end
+        expanded
+      end
+
+      private
+
+      def validate
+        require_value(data.is_a?(Hash), "Configuration must be a mapping")
+        require_value((data.keys - KEYS).empty?, "Unknown configuration keys: #{data.keys - KEYS}")
+        require_value(name.is_a?(String) && name.match?(/\A[a-z0-9][a-z0-9_-]*\z/), "Invalid gem name")
+        require_value(data["repository"].is_a?(String) && data["repository"].match?(/\A[a-zA-Z0-9_-]+\/[a-zA-Z0-9_.-]+\z/), "Expected GitHub owner/repository")
+        path(data.fetch("version_file"))
+        registry = data["registry"]
+        require_value(registry.is_a?(Hash) && registry.keys.sort == %w[host kind], "registry requires only kind and host")
+        require_value(REGISTRIES.key?(registry["kind"]) && registry["host"] == REGISTRIES[registry["kind"]], "Unsupported registry/host pair")
+        require_value(checks.is_a?(Array) && !checks.empty? && checks.all? { |check| check.is_a?(String) && check.match?(/\A[a-zA-Z][a-zA-Z0-9_:]*\z/) }, "checks must name existing Rake tasks")
+        require_value(checks.none? { |check| %w[verify default release].include?(check) || check.start_with?("release:") }, "Verification checks must not recurse or publish")
+      rescue KeyError => error
+        raise Error, "Missing configuration: #{error.key}"
+      end
+
+      def require_value(condition, message)
+        raise Error, message unless condition
+      end
+    end
+  end
+end

data/lib/ethos/gemkit/package.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "rubygems/package"
+require "tmpdir"
+require_relative "configuration"
+
+module Ethos
+  module Gemkit
+    class Package
+      def initialize(config)
+        @config = config
+      end
+
+      def verify
+        Dir.chdir(@config.root) do
+          spec = Gem::Specification.load(@config.path("#{@config.name}.gemspec"))
+          raise Error, "Cannot load gemspec" unless spec
+          validate_spec(spec)
+          Dir.mktmpdir("ethos-gemkit-package-") do |directory|
+            artifact = File.join(directory, "#{spec.full_name}.gem")
+            Gem::Package.build(spec, false, false, artifact)
+            package = Gem::Package.new(artifact)
+            package.verify
+            unless package.spec.dependencies.none? { |dependency| dependency.type == :runtime && dependency.name == "ethos-gemkit" }
+              raise Error, "ethos-gemkit must not be a runtime dependency"
+            end
+          end
+        end
+        true
+      end
+
+      private
+
+      def validate_spec(spec)
+        raise Error, "Configured gem name differs from gemspec" unless spec.name == @config.name
+        requirement = spec.required_ruby_version
+        unless requirement.satisfied_by?(Gem::Version.new("4.0.0")) && !requirement.satisfied_by?(Gem::Version.new("3.4.99"))
+          raise Error, "Gems must require Ruby 4.0 or newer"
+        end
+        unless spec.metadata["allowed_push_host"] == @config.data.fetch("registry").fetch("host")
+          raise Error, "allowed_push_host differs from configured registry"
+        end
+        raise Error, "Package contains no files" if spec.files.empty?
+        spec.files.each do |file|
+          @config.path(file)
+          if file.match?(%r{(?:\A|/)(?:\.git|\.bundle|node_modules|coverage)(?:/|\z)|(?:\A|/)(?:master\.key|credentials\.yml|\.env(?:\..*)?)\z})
+            raise Error, "Unsafe package path: #{file}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ethos/gemkit/plugin.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "bundler"
+require "lint_roller"
+require_relative "../gemkit"
+
+module Ethos
+  module Gemkit
+    # Delegate through lint_roller's public interface; never mutate RuboCop internals.
+    class Plugin < LintRoller::Plugin
+      FRAMEWORKS = %w[rails railties activerecord activemodel actionpack actionview activejob actionmailer activestorage actioncable actionmailbox actiontext].freeze
+
+      def about
+        LintRoller::About.new(name: "ethos-gemkit", version: VERSION,
+          homepage: "https://github.com/ethos-link/ethos-gemkit",
+          description: "Standard Rails rules when framework components are bundled")
+      end
+
+      def supported?(context)
+        true
+      end
+
+      def rules(context)
+        specs = Bundler.load.specs.select { |spec| FRAMEWORKS.include?(spec.name) }
+        if specs.empty?
+          LintRoller::Rules.new(type: :object, config_format: :rubocop, value: {})
+        else
+          versions = specs.map { |spec| spec.version.segments.first(2) }.uniq
+          if versions.size != 1 || versions.first.first != 8
+            raise Error, "Rails linting requires consistent Rails 8 components; found #{specs.map { |spec| "#{spec.name}=#{spec.version}" }.join(", ")}"
+          end
+          require "standard/rails"
+          Standard::Rails::Plugin.new(@config.merge("target_rails_version" => versions.first.join(".").to_f)).rules(context)
+        end
+      rescue LoadError => error
+        raise Error, "Install compatible standard-rails support with bundle install: #{error.message}"
+      end
+    end
+  end
+end

data/lib/ethos/gemkit/rake.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+unless Rake::Task.task_defined?(:test)
+  Rake::TestTask.new(:test) { |task|
+    task.libs << "test"
+    task.pattern = "test/**/*_test.rb"
+  }
+end
+require_relative "release_tasks"
+task default: :verify unless Rake::Task.task_defined?(:default)

data/lib/ethos/gemkit/release.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "open3"
+require "bundler"
+require_relative "configuration"
+require_relative "branch"
+
+module Ethos
+  module Gemkit
+    class Release
+      attr_reader :spec
+
+      def initialize(config)
+        @config = config
+        @spec = Gem::Specification.load(config.path("#{config.name}.gemspec"))
+        raise Error, "Cannot load gemspec" unless spec
+      end
+
+      # Release metadata uses an ordinary branch and PR; main is never committed.
+      def prepare(target = "patch")
+        clean
+        canonical_origin
+        git("fetch", "--no-tags", "origin", "refs/heads/main:refs/remotes/origin/main")
+        unless git("rev-parse", "HEAD") == git("rev-parse", "origin/main")
+          raise Error, "Start from clean main at origin/main; fetch and fast-forward before preparing a release"
+        end
+        %w[pre-commit commit-msg].each do |hook|
+          path = File.expand_path(git("rev-parse", "--git-path", "hooks/#{hook}"), @config.root)
+          raise Error, "Install hooks with bundle exec lefthook install" unless File.executable?(path)
+        end
+        file = @config.path(@config.data.fetch("version_file"))
+        text = File.read(file)
+        current = spec.version.to_s
+        parts = current.split(".").map(&:to_i)
+        index = %w[major minor patch].index(target)
+        if index
+          parts[index] += 1
+          ((index + 1)..2).each { |position| parts[position] = 0 }
+          target = parts.join(".")
+        end
+        unless target.to_s.match?(/\A\d+\.\d+\.\d+\z/) && Gem::Version.new(target) >= spec.version
+          raise Error, "Use major, minor, patch or a X.Y.Z version that has not been tagged"
+        end
+        literal = %(VERSION = "#{current}")
+        raise Error, "Expected a literal #{literal} in version_file" unless text.include?(literal)
+        raise Error, "Release tag already exists" unless git("tag", "--list", "v#{target}").empty? && git("ls-remote", "--tags", "origin", "refs/tags/v#{target}").empty?
+        branch = "chore/release-v#{target}"
+        current_branch = git("branch", "--show-current")
+        unless ["main", branch].include?(current_branch)
+          raise Error, "Start from main or #{branch} at origin/main"
+        end
+        run("gh", "auth", "status", "--hostname", "github.com")
+        if current_branch == "main"
+          unless git("branch", "--list", branch).empty?
+            unless git("rev-list", "--count", "origin/main..#{branch}") == "0"
+              raise Error, "Existing #{branch} contains unmerged commits; review it before retrying"
+            end
+            git("branch", "-d", branch)
+          end
+          git("switch", "-c", branch)
+        end
+        Branch.check(@config.root)
+        File.write(file, text.sub(literal, %(VERSION = "#{target}")))
+        run("git-cliff", "--config", "cliff.toml", "--unreleased", "--tag", "v#{target}", "--prepend", "CHANGELOG.md")
+        run("bundle", "lock", "--local")
+        run("bundle", "exec", "rake", "verify")
+        files = [@config.data.fetch("version_file"), "CHANGELOG.md", "Gemfile.lock"]
+        unless (git("diff", "--name-only").lines.map(&:strip) - files).empty? && git("ls-files", "--others", "--exclude-standard").empty?
+          raise Error, "Verification changed unrelated files; review git diff before committing"
+        end
+        title = "chore(release): prepare v#{target}"
+        body = "Prepare #{spec.name} #{target} for publication.\n\nRecord the version, generated notes and lockfile after verification."
+        git("add", "--", *files)
+        git("commit", "-m", title, "-m", body)
+        clean
+        git("push", "--no-follow-tags", "--set-upstream", "origin", branch)
+        url = run("gh", "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}."
+      end
+
+      def verify(tag, tagged: true)
+        clean
+        raise Error, "Tag and gem version differ" unless tag == "v#{spec.version}"
+        canonical_origin
+        ref = "refs/tags/#{tag}"
+        if tagged
+          object = git("rev-parse", ref)
+          raise Error, "Release tag must be annotated" unless git("cat-file", "-t", ref) == "tag"
+          raise Error, "Tag must identify HEAD" unless git("rev-parse", "#{ref}^{}") == git("rev-parse", "HEAD")
+          raise Error, "Canonical tag object differs" unless git("ls-remote", "--refs", "origin", ref).split.first == object
+        end
+        git("fetch", "--no-tags", "origin", "refs/heads/main:refs/remotes/origin/main")
+        git("merge-base", "--is-ancestor", "HEAD", "origin/main")
+        spec.files.each do |file|
+          unless git("hash-object", "--no-filters", "--", @config.path(file)) == git("rev-parse", "HEAD:#{file}")
+            raise Error, "Package file differs from the release commit: #{file}"
+          end
+        end
+        notes = File.read(@config.path("CHANGELOG.md")).split(/^## /).find { |section| section.lines.first.to_s.strip.match?(/\A\[#{Regexp.escape(spec.version.to_s)}\](?: - .*)?\z/) }
+        raise Error, "Missing meaningful release notes" unless notes.to_s.lines.any? { |line| line.start_with?("- ") }
+        "## #{notes}"
+      end
+
+      private
+
+      def canonical_origin
+        origin = git("config", "--get", "remote.origin.url")
+        repo = ENV.fetch("GITHUB_REPOSITORY", @config.data.fetch("repository"))
+        unless ["https://github.com/#{repo}.git", "https://github.com/#{repo}", "git@github.com:#{repo}.git", "ssh://git@github.com/#{repo}.git"].include?(origin)
+          raise Error, "Release origin must be the canonical GitHub repository"
+        end
+      end
+
+      def clean
+        status = git("status", "--porcelain")
+        raise Error, "Release requires a clean working tree:\n#{status}" unless status.empty?
+      end
+
+      def git(*arguments)
+        run("git", *arguments).strip
+      end
+
+      def run(*arguments)
+        environment = {"BUNDLE_GEMFILE" => File.join(@config.root, "Gemfile"),
+                       "GEM_PATH" => [*Gem.path, *Gem.loaded_specs.values.map(&:base_dir)].uniq.join(File::PATH_SEPARATOR)}
+        output, error, status = Bundler.with_unbundled_env { Open3.capture3(environment, *arguments, chdir: @config.root) }
+        raise Error, "#{arguments.first(3).join(" ")} failed: #{output}#{error}" unless status.success?
+        output
+      end
+    end
+  end
+end

data/lib/ethos/gemkit/release_tasks.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "tasks"
+require_relative "release"
+
+config = Ethos::Gemkit::Configuration.load
+desc "Create a verified release PR from clean, up-to-date main"
+task "release:prepare", [:target] do |_task, args|
+  puts Ethos::Gemkit::Release.new(config).prepare(args[:target] || "patch")
+end
+
+desc "Verify release source and build using Bundler's native task"
+task "release:build" => :verify do
+  release = Ethos::Gemkit::Release.new(config)
+  notes = release.verify(ENV.fetch("RELEASE_TAG"), tagged: ENV["RELEASE_FROM_PR"] != "true")
+  Rake::Task[:build].invoke
+  File.write(config.path("pkg/release-notes.md"), notes)
+  Dir.chdir(config.path("pkg")) do
+    sh "sha256sum", "#{release.spec.full_name}.gem", "release-notes.md", out: "SHA256SUMS"
+  end
+  if ENV["GITHUB_OUTPUT"]
+    File.open(ENV.fetch("GITHUB_OUTPUT"), "a") do |file|
+      file.puts "gem=#{release.spec.full_name}.gem", "host=#{release.spec.metadata.fetch("allowed_push_host")}", "tag=v#{release.spec.version}"
+    end
+  end
+end
+
+%w[release release:source_control_push release:rubygem_push].each do |name|
+  Rake::Task[name].clear if Rake::Task.task_defined?(name)
+  task(name) { abort "Publish a reviewed tag through GitHub Actions; local publication is disabled" }
+end

data/lib/ethos/gemkit/tasks.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "standard/rake"
+require_relative "configuration"
+require_relative "package"
+
+config = Ethos::Gemkit::Configuration.load
+standard = YAML.safe_load_file(config.path(".standard.yml"), aliases: false)
+unless standard.is_a?(Hash) && standard["ruby_version"].to_s == "4.0" && Array(standard["plugins"]).include?("ethos-gemkit")
+  raise Ethos::Gemkit::Error, ".standard.yml must target Ruby 4.0 and register ethos-gemkit"
+end
+task lint: :standard
+task "lint:fix" => "standard:fix"
+task "package:verify" do
+  Ethos::Gemkit::Package.new(config).verify
+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 }
+end

data/lib/ethos/gemkit/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ethos
+  module Gemkit
+    VERSION = "0.1.0"
+  end
+end

data/lib/ethos/gemkit.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "gemkit/version"
+
+module Ethos
+  module Gemkit
+    class Error < StandardError; end
+  end
+end

data/lib/ethos-gemkit.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "ethos/gemkit"
+require_relative "ethos/gemkit/plugin"

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: ethos-gemkit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ethos Link
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.57'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.57'
+- !ruby/object:Gem::Dependency
+  name: standard-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: lint_roller
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: lefthook
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+description: Common Ruby gem tasks, conditional Rails linting, package validation
+  and release verification.
+email:
+- devel@ethos-link.com
+executables:
+- ethos-gemkit
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- exe/ethos-gemkit
+- lib/ethos-gemkit.rb
+- lib/ethos/gemkit.rb
+- lib/ethos/gemkit/branch.rb
+- lib/ethos/gemkit/commit_message.rb
+- lib/ethos/gemkit/configuration.rb
+- lib/ethos/gemkit/package.rb
+- lib/ethos/gemkit/plugin.rb
+- lib/ethos/gemkit/rake.rb
+- lib/ethos/gemkit/release.rb
+- lib/ethos/gemkit/release_tasks.rb
+- lib/ethos/gemkit/tasks.rb
+- lib/ethos/gemkit/version.rb
+homepage: https://github.com/ethos-link/ethos-gemkit
+licenses:
+- MIT
+metadata:
+  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
+  rubygems_mfa_required: 'true'
+  default_lint_roller_plugin: Ethos::Gemkit::Plugin
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Shared development and verification tooling for Ethos Link gems
+test_files: []