docs: align bump policy and docs-bump cadence

Author: mrlunchbox777

.agents/README.md

@@ -21,6 +21,9 @@ Last updated: 2026-04-09
 - Follow the response option framing in `AGENTS.md`.
 - When presenting a minimal implementation path, also offer to provide `recommended` and `full` options with clear scope and tradeoffs.
 
+## Docs bump cadence
+- If the current branch already includes a docs bump/version entry, rerun docs-bump checks after each meaningful change to avoid missing version/changelog drift.
+
 ## Work snapshot guidance
 - Local handoff file: `.agents/work-snapshot.local.md`.
 - Read it at session start when present to recover intent/next steps.

.agents/skills/update-changelog/SKILL.md

@@ -40,11 +40,13 @@ Update the current version changelog entry without changing the version.
 3. If the version exists in branch changelog (including when it is not yet merged to `main`), update that same entry in place.
 4. If branch entry is missing but `main` already has that version entry, cherry-pick/recreate that entry at the top and then update it.
 5. If branch and `main` both lack that version entry, stop and run [Version Bump Skill](../version-bump/SKILL.md).
-6. Consolidate the entry before finalizing: merge overlapping bullets, collapse low-level implementation-only bullets into higher-level outcomes, and remove duplicates.
-7. Update Added/Changed/Fixed bullets with concise, user-visible or contributor-impacting changes; keep style and tense consistent.
-8. When updating an existing entry, keep the version unchanged and set the entry date to today's date (`YYYY-MM-DD`, UTC).
-9. If adding more changes later without bumping a new version, update that same entry again (rewrite/refine, not append-only) and refresh the date to today's date.
-10. Validate with `git diff`; run tests if code changed.
+6. If this PR branch already contains one bump, keep reusing that entry for subsequent commits; do not create another version header unless explicitly requested.
+7. Consolidate the entry before finalizing: merge overlapping bullets, collapse low-level implementation-only bullets into higher-level outcomes, and remove duplicates.
+8. Update Added/Changed/Fixed bullets with concise, user-visible or contributor-impacting changes; keep style and tense consistent.
+9. When updating an existing entry, keep the version unchanged and set the entry date to today's date (`YYYY-MM-DD`, UTC).
+10. If adding more changes later without bumping a new version, update that same entry again (rewrite/refine, not append-only) and refresh the date to today's date.
+11. Validate with `git diff`; run tests if code changed.
+12. If this branch already has a docs bump/current-version entry, rerun docs-bump checks after each meaningful change to catch version/changelog drift early.
 
 ## Outputs
 - Updated `CHANGELOG.md` entry for the current version reflecting all new work.

.agents/skills/version-bump/SKILL.md

@@ -16,6 +16,12 @@ Keep the BasicSetup CLI version and changelog in sync for releases.
 - Automated bumps (e.g., Dependabot) are not handling this branch.
 - For changelog-only edits after a bump, use [Update Changelog Skill](../update-changelog/SKILL.md).
 
+## Precedence rules
+- Default to one version bump per PR branch.
+- After a branch has been bumped, do not bump again for follow-up commits unless the user explicitly requests another bump or release policy requires it.
+- For follow-up commits on the same PR, update the existing current-version changelog entry via [Update Changelog Skill](../update-changelog/SKILL.md).
+- If a docs bump is already present on the branch, rerun docs-bump checks after each meaningful change.
+
 ## Prerequisites
 - Tools: `yq`, `git`, `make` (for tests when code changes are included).
 - Permissions to push branch changes.
@@ -34,6 +40,12 @@ Keep the BasicSetup CLI version and changelog in sync for releases.
 4. Verify alignment: top changelog version matches `.BasicSetupCliVersion`; date is valid for CI validation (UTC +/- 1 day).
 5. Validate changes: at minimum `git diff`; run `make test` if code changed.
 
+## Decision table
+- No bump yet on the PR branch: create a new version entry and set version files.
+- Branch already has a bump for this PR: do not bump again; update that same entry.
+- User explicitly requests another bump: create the next version.
+- Release policy explicitly requires another bump: create the next version and document why.
+
 ## Outputs
 - Updated `resources/version.yaml` with the new version (and mirrored `bsctl/static/resources/constants.yaml` during transition).
 - Matching `CHANGELOG.md` entry for `X.Y.Z`.

AGENTS.md

@@ -426,8 +426,11 @@ Follow [Semantic Versioning 2.0.0](https://semver.org/):
 4. **Automated Bumping**
    - Dependabot PRs are automatically bumped via workflow
    - Manual PRs require manual version bump
-   - Every MR/PR/changeset should include a version bump and matching CHANGELOG entry unless explicitly exempted
-   - Always bump version before merging
+   - Every MR/PR should include at least one version bump and matching CHANGELOG entry unless explicitly exempted
+   - Default to one bump per PR branch; follow-up commits should update the existing current-version entry rather than creating another version
+   - Only bump again on the same PR when explicitly requested by the user or required by release policy
+   - If a docs bump is already present on the branch, rerun docs-bump checks after each meaningful change to reduce missed changelog/version drift
+   - Always ensure the branch is bumped before merging
 
 ### Example CHANGELOG Entry
 

CHANGELOG.md

@@ -3,14 +3,6 @@
 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.24] - 2026-04-09
-
-### Changed
-
-- Added a `Response Option Framing` standard in `AGENTS.md` requiring agents that present a minimal path to also offer `recommended` and `full` options with explicit scope/tradeoff framing.
-- Updated `.agents/README.md` to reference the new response-framing policy and refreshed instruction metadata date.
-
 ---
 ## [0.1.23] - 2026-04-09
 
@@ -22,6 +14,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 - Updated `docs/plans/bsctl-codeql-decommission-plan.md` with Phase C status and immediate next steps for static-check validation before CodeQL re-scope/removal.
 - Refined static-check workflow behavior so `shellcheck`/`shfmt -d` run on `*.sh`/`*.bash` and zsh files are validated separately with `zsh -n`.
+- Added a `Response Option Framing` standard in `AGENTS.md` requiring agents that present a minimal path to also offer `recommended` and `full` options with explicit scope/tradeoff framing.
+- Updated `.agents/README.md` to reference the new response-framing policy and refreshed instruction metadata date.
+- Clarified versioning policy across `AGENTS.md` and changelog/version skills to default to one bump per PR and reuse the current-version entry for follow-up commits unless explicitly requested to bump again.
+- Added docs-bump cadence guidance across agent docs/skills: when a branch already has a docs bump, rerun docs-bump checks after each meaningful change.
 
 ---
 ## [0.1.22] - 2026-04-09

bsctl/static/resources/constants.yaml

@@ -1,2 +1,2 @@
 # BasicSetupCliVersion - constant for semantic versioning
-BasicSetupCliVersion: "0.1.24"
+BasicSetupCliVersion: "0.1.23"

resources/version.yaml

@@ -1,2 +1,2 @@
 # BasicSetupCliVersion - primary version source for releases and docs bump automation
-BasicSetupCliVersion: "0.1.24"
+BasicSetupCliVersion: "0.1.23"