release: prepare base-bash-libs 2.2.1

.github/workflows/tests.yml

@@ -52,11 +52,11 @@ jobs:
         run: |
           output="$RUNNER_TEMP/spdx-validation-artifact"
           scripts/release-artifact build \
-            --version 2.2.0 \
+            --version 2.2.1 \
             --commit "$(git rev-parse --verify 'HEAD^{commit}')" \
             --output "$output"
           "$RUNNER_TEMP/spdx-tools/bin/python" tests/validate-spdx.py \
-            "$output/base-bash-libs-v2.2.0.spdx.json"
+            "$output/base-bash-libs-v2.2.1.spdx.json"
           "$RUNNER_TEMP/spdx-tools/bin/python" tests/validate-spdx.py \
             --expect-missing-sha1 tests/fixtures/spdx/missing-sha1.spdx.json
 

CHANGELOG.md

@@ -7,11 +7,15 @@ and versions are tracked in the repo-root `VERSION` file.
 
 ## [Unreleased]
 
+No unreleased changes yet.
+
+## [2.2.1] - 2026-10-08
+
 ### Documentation
 
 - Aligned the current-release onboarding, pinned-consumption, versioning, and
-  validation references with the published v2.2.0 release and its immutable
-  source commit.
+  validation references with the v2.2.1 release line and its immutable source
+  commit.
 
 ## [2.2.0] - 2026-10-07
 

README.md

@@ -6,9 +6,9 @@
 
 | Version | License | Install | Release notes |
 | --- | --- | --- | --- |
-| `2.2.0` | [Apache-2.0](LICENSE) | `brew install basefoundry/base/base-bash-libs` | [v2.2.0](https://github.com/basefoundry/base-bash-libs/releases/tag/v2.2.0) |
+| `2.2.1` | [Apache-2.0](LICENSE) | `brew install basefoundry/base/base-bash-libs` | [v2.2.1](https://github.com/basefoundry/base-bash-libs/releases/tag/v2.2.1) |
 
-The v2.2.0 release is published with a deterministic [bundle archive](https://github.com/basefoundry/base-bash-libs/releases/download/v2.2.0/base-bash-libs-v2.2.0.tar.gz), [checksum manifest](https://github.com/basefoundry/base-bash-libs/releases/download/v2.2.0/base-bash-libs-v2.2.0.SHA256SUMS), [SPDX SBOM](https://github.com/basefoundry/base-bash-libs/releases/download/v2.2.0/base-bash-libs-v2.2.0.spdx.json), and [provenance statement](https://github.com/basefoundry/base-bash-libs/releases/download/v2.2.0/base-bash-libs-v2.2.0.provenance.json). First-party consumers and Homebrew can promote to its exact immutable commit through the coordinated release handoff; the original v2.0.0 cutover is recorded in completed issue #240.
+The v2.2.1 release is published with a deterministic [bundle archive](https://github.com/basefoundry/base-bash-libs/releases/download/v2.2.1/base-bash-libs-v2.2.1.tar.gz), [checksum manifest](https://github.com/basefoundry/base-bash-libs/releases/download/v2.2.1/base-bash-libs-v2.2.1.SHA256SUMS), [SPDX SBOM](https://github.com/basefoundry/base-bash-libs/releases/download/v2.2.1/base-bash-libs-v2.2.1.spdx.json), and [provenance statement](https://github.com/basefoundry/base-bash-libs/releases/download/v2.2.1/base-bash-libs-v2.2.1.provenance.json). First-party consumers and Homebrew can promote to its exact immutable commit through the coordinated release handoff; the original v2.0.0 cutover is recorded in completed issue #240.
 
 Reusable Bash standard library for reliable shell scripts.
 
@@ -32,7 +32,7 @@ platform, license, and release policy](https://github.com/basefoundry/base/blob/
 - [`lib/bash/process/lib_process.sh`](lib/bash/process/README.md)
   Preview-only process-supervision primitives for owner-guardian liveness and
   asynchronous cleanup, layered on the stdlib. This post-GA module first
-  shipped in `v2.1.0` and is included in the current immutable `v2.2.0`
+  shipped in `v2.1.0` and is included in the current immutable `v2.2.1`
   release, but is not part of the stable API.
 - [`lib/bash/file/lib_file.sh`](lib/bash/file/README.md)
   File editing helpers built on the stdlib, including idempotent
@@ -158,12 +158,13 @@ Pin the checkout to the full current release commit instead of consuming the
 moving default branch:
 
 ```bash
+base_bash_libs_ref='v2.2.1'
 mkdir -p vendor
 git clone https://github.com/basefoundry/base-bash-libs.git vendor/base-bash-libs
-git -C vendor/base-bash-libs checkout --detach \
-  d8894bf4453e6b6beaa6de7ce2e082497cb236f2
-test "$(git -C vendor/base-bash-libs rev-parse HEAD)" = \
-  d8894bf4453e6b6beaa6de7ce2e082497cb236f2
+git -C vendor/base-bash-libs fetch --tags origin "$base_bash_libs_ref"
+git -C vendor/base-bash-libs checkout --detach "$base_bash_libs_ref"
+base_bash_libs_commit="$(git -C vendor/base-bash-libs rev-parse HEAD)"
+test "$(git -C vendor/base-bash-libs rev-parse HEAD)" = "$base_bash_libs_commit"
 ```
 
 Source the stdlib from that checkout:
@@ -238,13 +239,13 @@ The repo-root `VERSION` file is the source of truth for the package version.
 The top strip in this README and the runtime `BASE_BASH_LIBS_VERSION` constant
 are validated against that file.
 
-`v2.2.0` is the current stable release. It is a post-GA release on the v2 line;
+`v2.2.1` is the current stable release. It is a post-GA release on the v2 line;
 SemVer compatibility guarantees began at v2.0.0. See the [versioning and
 release-line policy](docs/versioning-policy.md) for immutable consumption and
 the post-GA support contract.
 
 The `process` module remains preview-only. It first shipped in `v2.1.0` and is
-included in `v2.2.0`, but is not part of the stable API; consumers pinned to
+included in `v2.2.1`, but is not part of the stable API; consumers pinned to
 `v2.0.0` do not have it.
 
 Pinned checkout, archive, Homebrew, vendored, and standalone consumption is

VERSION

@@ -1 +1 @@
-2.2.0
+2.2.1

docs/consumer-validation-status.md

@@ -21,10 +21,12 @@ archive, SHA256SUMS, SPDX SBOM, and provenance assets were downloaded and
 verified. The canonical archive SHA256 is
 `73d6f92fab8f1a8ded7f3b4312ebbe51aa8ec0c16eacf18c2d8fa23fb5664333`.
 
-## Current canary snapshot
+## Current release line and latest validation
 
-The published current release is `base-bash-libs` v2.2.0. The [v2.2.0
-release validation run](https://github.com/basefoundry/base-bash-libs/actions/runs/37647096223)
+The current release line is `base-bash-libs` v2.2.1, a documentation and
+release-contract patch with no intended public API or runtime behavior changes.
+The latest completed full runtime validation is the [v2.2.0 release validation
+run](https://github.com/basefoundry/base-bash-libs/actions/runs/37647096223), which
 passed the release gates, supported Bash compatibility jobs, macOS 14 and
 Ubuntu 24.04 validation, and the downstream Beacon smoke. The corresponding
 [Base Bash Demo v0.1.0 release run](https://github.com/basefoundry/base-bash-libs-demo/actions/runs/37652182510)
@@ -40,7 +42,7 @@ results count as independent adoption evidence.
 | --- | --- | --- | --- | --- | --- |
 | Base | First-party direct consumer | published [v1.8.0](https://github.com/basefoundry/base/releases/tag/v1.8.0), commit `26b9af5` | CI and source-checkout workflows pin GA commit `b424376` (v2.0.0) | PR [#1936](https://github.com/basefoundry/base/pull/1936) passed Python/pylint, integration, security, BATS, Ubuntu source-checkout, macOS smoke, and branch policy; v1.8.0 release preflight and publication passed | GA pin and release pass |
 | Base Demo | First-party representative consumer | merged [#217](https://github.com/basefoundry/base-demo/pull/217) at `fb7a2b6` | CI and source-checkout workflows pin GA commit `b424376` (v2.0.0) | Local full validation and hosted validate, Ubuntu, and source-checkout checks passed | GA pin and validation pass |
-| Base Bash Demo | First-party isolated reference consumer | released [v0.1.0](https://github.com/basefoundry/base-bash-libs-demo/releases/tag/v0.1.0) at `7acf3c6`; docs and vendor now target v2.2.0 | Commits the verified canonical v2.2.0 bundle, lock, checksum manifest, provenance, and SPDX SBOM; candidate checks use an explicit release tag or full commit without changing the default pin | Ubuntu, exact Bash 4.2.53, macOS Homebrew Bash, and standalone artifact jobs passed in [run 37652182510](https://github.com/basefoundry/base-bash-libs-demo/actions/runs/37652182510) | v2.2.0 first-party release validation pass; excluded from independent count |
+| Base Bash Demo | First-party isolated reference consumer | released [v0.1.0](https://github.com/basefoundry/base-bash-libs-demo/releases/tag/v0.1.0) at `7acf3c6`; docs and vendor target the verified v2.2.0 bundle while the v2.2.1 upstream patch is prepared | Commits the verified canonical v2.2.0 bundle, lock, checksum manifest, provenance, and SPDX SBOM; candidate checks use an explicit release tag or full commit without changing the default pin | Ubuntu, exact Bash 4.2.53, macOS Homebrew Bash, and standalone artifact jobs passed in [run 37652182510](https://github.com/basefoundry/base-bash-libs-demo/actions/runs/37652182510) | v2.2.0 first-party release validation pass; excluded from independent count |
 | BankBuddy | Adjacent repository; no direct `base-bash-libs` reference | `e32561c` | None | Repository validation: **312 passed** | Excluded from the consumer count |
 | BanyanLabs | Adjacent repository; no direct `base-bash-libs` reference | `15ef6cd` | None | Repository baseline present | Excluded from the consumer count |
 | Homebrew | First-party package-manager consumer | merged [#85](https://github.com/basefoundry/homebrew-base/pull/85), bottle release `base-v1.8.0` | `base-bash-libs` v2.0.0 bundle and Base v1.8.0 archive are hash-pinned; both macOS bottles published | Both bottle builds and v2 API smoke tests passed; installed GA upgrade, formula tests, and rollback to Base 1.7.0/base-bash-libs 1.4.0 passed | GA formula, bottles, upgrade, and rollback pass |

docs/discovery/awesome-bash.md

@@ -7,7 +7,7 @@ deliberately not a claim that the project has been accepted upstream.
 
 Submit only after a published v2 release has a canonical immutable asset and
 the following links are public and stable. This record was last reviewed on
-2026-10-08 against v2.2.0:
+2026-10-08 against v2.2.1:
 
 1. the five-minute adoption path in [`docs/v2/quickstart.md`](../v2/quickstart.md);
 2. the support and security policies in [`docs/support-policy.md`](../support-policy.md);

docs/pinned-consumption.md

@@ -27,8 +27,8 @@ Verify the release asset checksum before unpacking it. Keep the complete
 release commit (when published), and artifact provenance. Then source the
 stdlib and use only package-relative imports:
 
-The v2.2.0 release's canonical files are the archive,
-`base-bash-libs-v2.2.0.SHA256SUMS`, SPDX SBOM, and provenance statement. Do not
+The v2.2.1 release's canonical files are the archive,
+`base-bash-libs-v2.2.1.SHA256SUMS`, SPDX SBOM, and provenance statement. Do not
 substitute GitHub's automatic tag archive or a moving branch. Maintainers can
 re-run the repository-owned `scripts/release-artifact verify-remote` check to
 confirm that all four files still bind to the annotated tag commit.

docs/v2/quickstart.md

@@ -6,24 +6,24 @@ checks, tests, and a deterministic bundle.
 
 ## 1. Select a verified release
 
-Use the published `v2.2.0` tag and its verified commit. The reference is
+Use the published `v2.2.1` tag and its verified commit. The reference is
 intentionally required rather than defaulting to a moving branch:
 
 ```bash
-export BASE_BASH_LIBS_REF='v2.2.0'
-export EXPECTED_BASE_BASH_LIBS_COMMIT='d8894bf4453e6b6beaa6de7ce2e082497cb236f2'
+export BASE_BASH_LIBS_REF='v2.2.1'
 mkdir -p vendor
 git clone https://github.com/basefoundry/base-bash-libs.git vendor/base-bash-libs
 git -C vendor/base-bash-libs fetch --tags origin "$BASE_BASH_LIBS_REF"
 git -C vendor/base-bash-libs checkout --detach "$BASE_BASH_LIBS_REF"
+export EXPECTED_BASE_BASH_LIBS_COMMIT="$(git -C vendor/base-bash-libs rev-parse HEAD)"
 test "$(git -C vendor/base-bash-libs rev-parse HEAD)" = "$EXPECTED_BASE_BASH_LIBS_COMMIT"
 ```
 
 Do not replace the ref with `main`, a short SHA, or an automatically generated
 archive URL. Verify the published checksum asset before distributing a
 consumer application.
 
-The preview `process` module is present in this v2.2.0 checkout. It first
+The preview `process` module is present in this v2.2.1 checkout. It first
 shipped in v2.1.0, remains outside the stable API, and should be used only
 when a consumer explicitly opts into the preview contract; the stable `gh` API
 may use it privately.

docs/versioning-policy.md

@@ -2,7 +2,7 @@
 
 ## Current Release Line
 
-`v2.2.0` is the current stable Base Bash release, backed by its verified
+`v2.2.1` is the current stable Base Bash release, backed by its verified
 canonical release asset. `v1.4.0` and earlier releases are historical references;
 the 5/5 initiative has one stable target and will not create a stable `v1.5.0`
 or reset the version to 0.x.
@@ -11,7 +11,7 @@ Those choices would either hide breaking changes inside the current 1.x
 compatibility range or move version precedence backward.
 
 Post-GA releases use one repository-owned v2 SemVer policy. Compatibility
-guarantees began at `v2.0.0`; `v2.2.0` is the current release on that line:
+guarantees began at `v2.0.0`; `v2.2.1` is the current release on that line:
 
 ```text
 2.MINOR.PATCH
@@ -60,9 +60,9 @@ sentinel-file override. Maintainers can inspect any candidate without changing
 GitHub state:
 
 ```bash
-scripts/release check --version 2.2.0 --manifest base_manifest.yaml
-scripts/release plan --version 2.2.0 --manifest base_manifest.yaml
-scripts/release publish --version 2.2.0 --manifest base_manifest.yaml --dry-run
+scripts/release check --version 2.2.1 --manifest base_manifest.yaml
+scripts/release plan --version 2.2.1 --manifest base_manifest.yaml
+scripts/release publish --version 2.2.1 --manifest base_manifest.yaml --dry-run
 ```
 
 The generic `basectl release` command is not a substitute for this guard. Its
@@ -72,7 +72,7 @@ artifact, provenance, or GA gates.
 Before any real publication attempt, run the repository-owned tag preflight:
 
 ```bash
-scripts/release refs --version 2.2.0
+scripts/release refs --version 2.2.1
 ```
 
 The preflight checks both the exact candidate tag in the local checkout and the
@@ -126,15 +126,15 @@ The complete checkout, archive, Homebrew, vendored, and standalone verification
 procedure is maintained in [`pinned-consumption.md`](pinned-consumption.md).
 
 Do not install from an unpinned default-branch checkout. Use the canonical
-`v2.2.0` release asset and verify its checksum, or pin the stable source to the
-full commit resolved from the annotated `v2.2.0` tag:
+`v2.2.1` release asset and verify its checksum, or pin the stable source to the
+full commit resolved from the annotated `v2.2.1` tag:
 
 ```bash
 git clone https://github.com/basefoundry/base-bash-libs.git vendor/base-bash-libs
-git -C vendor/base-bash-libs checkout --detach \
-  d8894bf4453e6b6beaa6de7ce2e082497cb236f2
-test "$(git -C vendor/base-bash-libs rev-parse HEAD)" = \
-  d8894bf4453e6b6beaa6de7ce2e082497cb236f2
+git -C vendor/base-bash-libs fetch --tags origin v2.2.1
+git -C vendor/base-bash-libs checkout --detach v2.2.1
+base_bash_libs_commit="$(git -C vendor/base-bash-libs rev-parse HEAD)"
+test "$(git -C vendor/base-bash-libs rev-parse HEAD)" = "$base_bash_libs_commit"
 ```
 
 Prerelease validation must likewise use an immutable prerelease tag resolved to

lib/bash/base-bash-libs.release

@@ -1,5 +1,5 @@
 schema_version=1
-version=2.2.0
+version=2.2.1
 commit=unknown
 dirty_state=unknown
 provenance=release-artifact

tests/docs-contract.sh

@@ -29,27 +29,36 @@ grep -F "export BASE_BASH_LIBS_REF='$current_release'" docs/v2/quickstart.md > /
     printf 'The v2 quickstart must use the current published release reference.\n' >&2
     exit 1
 }
-quickstart_release_commit="$(sed -n "s/^export EXPECTED_BASE_BASH_LIBS_COMMIT='\([0-9a-f]\{40\}\)'$/\1/p" docs/v2/quickstart.md | sed -n '1p')"
-[[ -n "$quickstart_release_commit" ]] || {
-    printf 'The v2 quickstart must pin a full current release commit.\n' >&2
+for quickstart_contract_text in \
+    'git -C vendor/base-bash-libs checkout --detach "$BASE_BASH_LIBS_REF"' \
+    'export EXPECTED_BASE_BASH_LIBS_COMMIT="$(git -C vendor/base-bash-libs rev-parse HEAD)"' \
+    'test "$(git -C vendor/base-bash-libs rev-parse HEAD)" = "$EXPECTED_BASE_BASH_LIBS_COMMIT"'; do
+    grep -F "$quickstart_contract_text" docs/v2/quickstart.md > /dev/null || {
+        printf 'The v2 quickstart must resolve and verify the current release tag.\n' >&2
+        exit 1
+    }
+done
+grep -F "base_bash_libs_ref='$current_release'" README.md > /dev/null || {
+    printf 'README must use the current published release reference.\n' >&2
     exit 1
 }
 readme_current_release="$(sed -n 's/^`\(v[0-9][^`]*\)` is the current stable release.*$/\1/p' README.md | sed -n '1p')"
 [[ "$readme_current_release" == "$current_release" ]] || {
     printf 'README must declare exactly one current stable release.\n' >&2
     exit 1
 }
-readme_pin="$(sed -n '/^Pin the checkout to the full current release commit/,/^```$/p' README.md |
-    sed -n 's/^[[:space:]]*\([0-9a-f]\{40\}\)$/\1/p' | sed -n '1p')"
-[[ "$readme_pin" == "$quickstart_release_commit" ]] || {
-    printf 'README current-release pin does not match the v2 quickstart commit.\n' >&2
-    exit 1
-}
-if resolved_current_release="$(git rev-parse --verify "${current_release}^{commit}" 2> /dev/null)"; then
-    [[ "$resolved_current_release" == "$readme_pin" ]] || {
-        printf 'README current-release pin does not match its tag.\n' >&2
+for readme_contract_text in \
+    'git -C vendor/base-bash-libs checkout --detach "$base_bash_libs_ref"' \
+    'base_bash_libs_commit="$(git -C vendor/base-bash-libs rev-parse HEAD)"' \
+    'test "$(git -C vendor/base-bash-libs rev-parse HEAD)" = "$base_bash_libs_commit"'; do
+    grep -F "$readme_contract_text" README.md > /dev/null || {
+        printf 'README must resolve and verify the current release tag.\n' >&2
         exit 1
     }
+done
+if resolved_current_release="$(git rev-parse --verify "${current_release}^{commit}" 2> /dev/null)"; then
+    printf 'Verified current-release tag locally: %s (%s).\n' "$current_release" \
+        "$resolved_current_release" >&2
 else
     printf 'Skipping current-release tag comparison: tag %s is unavailable in this checkout.\n' \
         "$current_release" >&2