Python Package Versioning with Semantic Release

You are working in a Python package repository.

Before editing files, read the canonical recipe at:
https://bluebook.nightmode.dev/docs/python-package-versioning-semantic-release

Treat that page as the source of truth for the implementation order,
workflow structure, verification process, and code snippets. Follow the
numbered steps on the page deterministically and adapt the snippets only
where repository names, package names, paths, or existing project
conventions require it.

First inspect the repository and infer every input you can. Ask the user
only for missing values, credentials, publishing settings, or choices with
multiple valid options before editing files.

- Repository: <ORG>/<REPO>
- Default branch: <DEFAULT_BRANCH>
- Package name: <PACKAGE_NAME>
- Package directory: <PACKAGE_DIRECTORY_OR_REPO_ROOT>
- Version file: <VERSION_FILE>
- Version field: <VERSION_FIELD>
- Tag format: <TAG_FORMAT>
- Build command: <BUILD_COMMAND>
- Distribution glob: <DIST_GLOB>
- Changelog file: <CHANGELOG_FILE>
- Publish target: <PYPI_OR_INTERNAL_INDEX>
- Generated SDK repository: <YES_OR_NO>

Goal: implement production-ready Python package versioning and release
automation with python-semantic-release.

Use this architecture:

1. Pull requests run normal package CI only.
2. Release automation runs only after changes merge to the default branch.
3. Version numbers are derived from Conventional Commits.
4. python-semantic-release owns version stamping, changelog updates, tags,
   and GitHub releases.
5. Package build and publishing happen from the package repository, not
   from an upstream producer repository.
6. PyPI or internal registry publishing should be optional unless the
   project explicitly requires it.
7. Use least-privilege GitHub Actions permissions.

Implement the following:

1. Inspect the repository packaging and release layout:
   - identify the package `pyproject.toml`
   - identify the existing version field and value
   - identify the build backend
   - identify whether artifacts build from repo root or a subdirectory
   - identify existing changelog files
   - identify existing release tags and tag format
   - identify existing release workflows and publishing steps
2. Add `python-semantic-release` to development dependencies.
3. Add or update `CHANGELOG.md` with the semantic-release insertion marker:
   `<!-- version list -->`.
   - If a changelog already exists, preserve historical entries.
   - Add the insertion marker near the top instead of overwriting the file.
4. Configure `[tool.semantic_release]` in `pyproject.toml`:
   - `commit_parser = "conventional"`
   - `tag_format = "<TAG_FORMAT>"`
   - `version_toml = ["<VERSION_FILE>:<VERSION_FIELD>"]`
   - `commit_message = "chore(release): v{version}"` or a package-specific
     variant such as `"chore(release): SDK v{version}"`
   - `build_command = "<BUILD_COMMAND>"`
   - changelog file configuration
   - publish `dist_glob_patterns`
5. Add `.github/workflows/release.yml` that:
   - runs on push to `<DEFAULT_BRANCH>` and workflow_dispatch
   - uses concurrency to prevent overlapping releases
   - checks out the triggering branch
   - resets to `${{ github.sha }}`
   - runs `python-semantic-release/python-semantic-release@v10.5.3`
   - builds wheel and source distribution only when a release is created
   - uploads distributions to the GitHub release with
     `python-semantic-release/publish-action@v10.5.3`
   - uploads distributions as workflow artifacts when useful
   - publishes to PyPI or internal registry only when credentials are
     configured
6. Ensure `.github/workflows/ci.yml` or equivalent pull request CI runs:
   - format or lint
   - tests
   - package build
7. If this is a generated SDK repository:
   - do not publish artifacts from the API repository
   - ensure generated PR commits use Conventional Commit subjects that
     match the contract impact
   - map major impact to `feat(sdk)!: ...` with a `BREAKING CHANGE:`
     footer
   - map minor impact to `feat(sdk): ...`
   - map patch impact to `fix(sdk): ...`
   - map no release impact to `chore(sdk): ...`
8. Add tests or workflow checks that prove the release configuration loads.
9. Run local verification:
   - package lint
   - package tests
   - package build
   - `semantic-release --noop version --no-commit --no-tag --no-push
--no-vcs-release --skip-build`
10. If the repository has a stamped version but no matching release tag,
    propose a baseline tag plan before enabling automated releases.
11. Review the final diff for secrets, hardcoded credentials, and
    accidental generated artifacts.

Security and release-management requirements:

- Ask for explicit user approval before any remote write, merge, tag,
  release, or registry publish.
- Do not reset existing package versions.
- Do not overwrite existing changelog history.
- Do not change existing tag formats without asking.
- Do not remove existing signing, SBOM, provenance, approval, or registry
  publishing steps unless they are replaced with equivalent controls.
- Do not use personal access tokens unless the organization explicitly
  requires them.
- Do not print private keys, registry tokens, or GitHub tokens.
- Prefer PyPI trusted publishing with OIDC when available.
- Keep token-based publishing as an optional fallback.
- Do not require release workflows on pull requests.
- Keep release permissions scoped to the release job.
- Keep release commits generated by GitHub Actions or the configured bot.

Conventional Commit policy:

- `feat(...)` creates a minor release.
- `fix(...)` creates a patch release.
- `feat(...)!` or `BREAKING CHANGE:` creates a major release.
- `chore(...)` normally creates no release.

Verification steps:

1. Confirm CI passes on pull requests.
2. Confirm semantic-release no-op runs locally.
3. Merge a patch-level change and confirm a patch tag is created.
4. Confirm the GitHub release contains wheel and source distribution
   artifacts.
5. Confirm the changelog contains the release entry.
6. Confirm PyPI or internal registry publishing succeeds when configured.
7. Confirm dependency bots can detect the new package version.

Do not stop at writing workflow files. Run the local verification steps
and fix failures until release configuration is valid.

The release workflow is running on pull requests. Refactor it so release
automation only runs after merge to the default branch.

The package lives in a generated SDK subdirectory. Update version_toml,
build paths, dist_glob_patterns, and publish paths to use the generated
package directory.

Semantic-release is not creating a release. Inspect the commit history,
Conventional Commit parser settings, tag format, and current tags, then
fix the release configuration.

The GitHub release exists but artifacts are missing. Fix the build step,
distribution glob, and publish-action tag wiring.

Replace token-based PyPI publishing with trusted publishing where the
registry supports OIDC.

<!-- version list -->