release: prepare base-cli 0.4.0

.github/workflows/tests.yml

@@ -69,7 +69,14 @@ jobs:
       - name: Run static security checks
         run: |
           bandit -q -r lib/python/base_cli scripts -lll -iii
-          pip-audit --strict
+          # The project itself is installed from this checkout and may not be
+          # published to PyPI yet (for example, while validating a release PR).
+          # Audit every installed third-party package without asking pip-audit
+          # to resolve the unpublished project distribution.
+          python -m pip freeze \
+            | grep -Eiv '^base-cli([[:space:]]|$)' \
+            > "$RUNNER_TEMP/base-cli-audit-requirements.txt"
+          pip-audit --strict -r "$RUNNER_TEMP/base-cli-audit-requirements.txt"
 
   linux-distributions:
     name: Validate (${{ matrix.name }})

CHANGELOG.md

@@ -5,7 +5,21 @@ All notable changes to base-cli will be documented in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and versions are tracked in the repo-root `VERSION` file.
 
-## [Unreleased]
+## [0.4.0] - 2026-08-05
+
+This is a pre-1.0 minor release and therefore a compatibility boundary. See
+the API stability policy and migration guide before upgrading from `0.3.x`.
+
+### Migration notes
+
+- Consumer profiles should raise `base_cli.ConfigurationError` for expected,
+  user-correctable configuration failures instead of plain `ValueError`.
+- Consumers should import `RuntimeLayout` from `base_cli.runtime`; the private
+  `_runtime` module is not a compatibility surface.
+- `base_cli.testing.invoke()` now exercises the production `run_app()` boundary,
+  so tests should assert the same exit status users receive.
+- Click-native `--option=value` syntax is accepted and redacted like the
+  space-separated form.
 
 ### Added
 
@@ -81,6 +95,12 @@ and versions are tracked in the repo-root `VERSION` file.
 - Restore Click-native `--option=value` parsing, including redaction of
   sensitive equals-form values.
 
+## [Unreleased]
+
+### Planned
+
+- Continue compatibility hardening and adoption work for the next release.
+
 ## [0.3.0] - 2026-08-01
 
 ### Changed

SECURITY.md

@@ -29,13 +29,14 @@ repository maintainers through the private contact route shown on the
 
 Security fixes are targeted at the latest released minor line and the current
 development branch. At the time this policy was published, that means the
-`0.3.x` release line and `main`. Older pre-1.0 lines are best effort only;
+`0.4.x` release line and `main`. Older pre-1.0 lines are best effort only;
 upgrade to the latest release before requesting a backport. A release that
 changes the supported window will update this table and the changelog.
 
 | Version | Security support |
 | --- | --- |
-| `0.3.x` | Supported |
+| `0.4.x` | Supported |
+| `0.3.x` | Upgrade strongly recommended; best effort only |
 | `main` | Supported for fixes merged before the next release |
 | `<0.3` | Upgrade strongly recommended; best effort only |
 

VERSION

@@ -1 +1 @@
-0.3.0
+0.4.0

docs/adopter-readiness.md

@@ -10,7 +10,7 @@ owns product configuration, commands, services, and release policy.
 Before the first production pilot, the adopter should be able to check every
 box below:
 
-- [ ] Pin a supported `base-cli` minor release (for example, `~=0.3.0`) and
+- [ ] Pin a supported `base-cli` minor release (for example, `~=0.4.0`) and
   record Click, PyYAML, and any optional integration versions in a lock file.
 - [ ] Run the adopter's command suite on CPython 3.10--3.14 on every platform
   the product supports; retain at least one installed-wheel smoke job.

docs/api-stability.md

@@ -45,7 +45,7 @@ Until 1.0, the leading zero is meaningful: patch releases remain compatible,
 while a minor release is a compatibility boundary and may contain a breaking
 change. We still prefer additive changes, and any pre-1.0 break must include a
 warning where practical, a migration path, and a changelog entry. Consumers
-that need a frozen API should pin a minor release (for example, `~=0.3.0`).
+that need a frozen API should pin a minor release (for example, `~=0.4.0`).
 
 The core package requires Python `>=3.10` and currently tests CPython 3.10
 through 3.14 on Linux, macOS, and Windows. Core runtime dependencies are