Document the base-bash-libs release process

AGENTS.md

@@ -0,0 +1,22 @@
+# Agent Guidance
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) for the issue, worktree, pull request,
+validation, and cleanup workflow. Read [STANDARDS.md](STANDARDS.md) before
+changing the shell libraries.
+
+## Release Work
+
+Read [docs/release-process.md](docs/release-process.md) before doing release
+work. Ordinary pull requests must leave `VERSION` unchanged; a release-prep
+pull request owns the version, README release row, and changelog transition.
+
+The repository release contract is declared in `base_manifest.yaml`. Use the
+guarded `basectl release check|plan|notes|publish` commands after the release
+preparation pull request is merged, and complete the Homebrew and Base
+downstream handoffs documented in the release process.
+
+## Shell Changes
+
+- Keep each public sourceable library in its single-file boundary.
+- Do not add `set -e`, `set -u`, or `set -o pipefail` to production libraries.
+- Add focused BATS coverage for behavior changes and run `./tests/validate.sh`.

CONTRIBUTING.md

@@ -7,6 +7,10 @@ repository inherits Base's shell-library standards, including the convention
 that each sourceable shell library remains a single file at its library
 boundary.
 
+For release work, read [docs/release-process.md](docs/release-process.md). The
+repository release contract is declared in `base_manifest.yaml`; ordinary pull
+requests leave `VERSION` unchanged.
+
 ## Workflow
 
 1. Create or choose a GitHub issue before starting implementation work.

README.md

@@ -173,6 +173,10 @@ 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.
 
+Release preparation and downstream Homebrew/Base handoffs are documented in
+[`docs/release-process.md`](docs/release-process.md). The machine-readable
+release contract lives in [`base_manifest.yaml`](base_manifest.yaml).
+
 ## License
 
 base-bash-libs is licensed under [Apache-2.0](LICENSE). See [NOTICE](NOTICE) for

base_manifest.yaml

@@ -5,3 +5,18 @@ project:
 
 test:
   command: ./tests/validate.sh
+
+release:
+  version_file: VERSION
+  changelog: CHANGELOG.md
+  tag_prefix: v
+  github:
+    repository: basefoundry/base-bash-libs
+    release_title: "base-bash-libs v{version}"
+  homebrew:
+    required: true
+    tap_repository: basefoundry/homebrew-base
+    formula_path: Formula/base-bash-libs.rb
+    package: basefoundry/base/base-bash-libs
+
+artifacts: []

docs/release-process.md

@@ -0,0 +1,78 @@
+# base-bash-libs Release Process
+
+This repository declares its release contract in
+[`base_manifest.yaml`](../base_manifest.yaml). It is consumed by Base's guarded
+release commands and is the source of truth for the version file, changelog,
+GitHub Release, and Homebrew handoff.
+
+## Standard Sequence
+
+1. Create or choose a release issue and set its repository Project metadata.
+2. Create a release-preparation branch and dedicated worktree from
+   `origin/main`.
+3. Move the relevant `Unreleased` entries in `CHANGELOG.md` into a dated
+   release section. Update `VERSION` and the top release row in `README.md` to
+   the same version. Ordinary pull requests do not change `VERSION`.
+4. Run the full library validation and inspect the diff:
+
+   ```bash
+   ./tests/validate.sh
+   git diff --check
+   ```
+
+5. Open and merge the release-preparation pull request.
+6. Sync local `main`, then inspect the release from the repository root:
+
+   ```bash
+   basectl release check --version X.Y.Z --manifest base_manifest.yaml
+   basectl release plan --version X.Y.Z --manifest base_manifest.yaml
+   basectl release notes --version X.Y.Z --manifest base_manifest.yaml
+   basectl release publish --version X.Y.Z --manifest base_manifest.yaml --dry-run
+   ```
+
+7. Publish only after the readiness checks pass. Use `--yes` only from a
+   trusted non-interactive release shell:
+
+   ```bash
+   basectl release publish --version X.Y.Z --manifest base_manifest.yaml --yes
+   ```
+
+8. Verify the annotated `vX.Y.Z` tag and the GitHub Release for
+   `basefoundry/base-bash-libs`.
+
+## Homebrew Handoff
+
+The release contract requires the tap-owned formula
+`basefoundry/base/base-bash-libs` in `basefoundry/homebrew-base`.
+
+After the GitHub Release exists:
+
+1. Create a tap release branch and update `Formula/base-bash-libs.rb` to the
+   new archive URL, version, SHA256, and version assertions in the formula test.
+2. Validate the formula from the tap checkout:
+
+   ```bash
+   brew install --build-from-source Formula/base-bash-libs.rb
+   brew test basefoundry/base/base-bash-libs
+   brew audit --new --formula Formula/base-bash-libs.rb
+   ```
+
+3. Publish any tap bottle artifacts required by the tap policy, then open and
+   merge the tap pull request.
+4. Smoke-test a consumer install and verify that `BASE_BASH_LIBS_VERSION` and
+   the `base-bash` launcher report the new version.
+
+## Base Handoff
+
+Base pins this repository by full commit SHA in its GitHub Actions workflows.
+After the release, update the Base pin to the release commit, run Base's
+source-checkout and integration tests, and record the dependency update in the
+Base changelog when it is user-visible or release-relevant.
+
+## Finish
+
+Record the library release URL, Homebrew tap pull request, and Base dependency
+pull request on the release issue. Remove the release worktree and merged
+branches when safe. Do not publish a release while the worktree is dirty, the
+version metadata disagrees, the changelog section is missing, or a declared
+downstream handoff has not been completed or explicitly deferred.