docs: Release-As is always the current version plus one patch; a behaviour-changing refactor is not a hidden type

skills/branch-and-commit/SKILL.md

@@ -32,10 +32,13 @@ code that closes it. Getting the format right keeps `git log`, the changelog, an
    | `test` | Test-only changes | No version bump |
 
    "No version bump" means release-please does not open a release PR for it at
-   all — it is a hidden type. A change users will notice that only fits a hidden
-   type (a new CI gate under `ci`, a behaviour-changing `refactor`) still has to
-   ship: put a `Release-As: X.Y.Z` footer in the PR body (the body becomes the
-   squash commit's message) and release-please cuts that version.
+   all — it is a hidden type, and hidden-type commits are left out of the
+   changelog as well (one exception, below). So first ask whether the type is
+   right: a change users will notice is usually a `feat` or a `fix`, not a hidden
+   type. When the type is genuinely right and a tag is still needed anyway, a
+   `Release-As` footer in the PR body can cut one; the recipe, its limits and the
+   changelog exception live in `skills/release-management` rule 2 and are not
+   repeated here.
 
 4. Breaking changes append `!` after the type (`feat!:`) or add a `BREAKING CHANGE:`
    footer — either triggers a major bump. Use whichever is more visible for the

skills/release-management/SKILL.md

@@ -17,7 +17,7 @@ A release must never ship from an unverified state, and version/changelog bookke
    2. **A human merges the release PR — never auto-merge.** The branch ruleset requires the `ci` status check to be green before merge is even possible; this is the mitigation for the fact that both CI and release-please trigger on `push:main`, so an unverified commit could otherwise reach the release PR.
    3. Merging the release PR cuts the git tag and GitHub Release automatically.
    4. The maintainer then edits the published release notes to add a short, hand-written TLDR **above** the generated changelog. Release notes have non-technical readers — the generated bullet list alone is not the message.
-2. **Version bump is derived, not chosen.** It comes from Conventional Commit types accumulated since the last release: `fix` → patch, `feat` → minor, any commit with `!` or a `BREAKING CHANGE:` footer → major. This is exactly why commit type discipline matters (see `CONTRIBUTING.md`).
+2. **Version bump is derived, not chosen.** It comes from Conventional Commit types accumulated since the last release: `fix` → patch, `feat` → minor, any commit with `!` or a `BREAKING CHANGE:` footer → major. This is exactly why commit type discipline matters (see `CONTRIBUTING.md`). One exception: a change that adopters must pick up but that genuinely is a hidden type (a new CI gate under `ci`) produces no release on its own; then a `Release-As: X.Y.Z` footer in the PR body cuts one, and X.Y.Z is always the current version plus one patch — if you want more than a patch, the type was wrong. Before the first release there is no current version: that release is numbered by `initial-version` in `release-please-config.json` (see `docs/setup/bootstrap.md`), so a footer there names that version. Use the footer only when nothing is already waiting: the footer overrides release-please's computed version for the whole range since the last tag, so with a release PR already open (an unreleased `feat` or `fix`) a patch footer would under-version that release — merge it first, or leave the footer out and let the hidden-type change ride along. The footer goes on the PR that is the change, not on a follow-up: hidden-type commits are omitted from the generated changelog except the one that carries `Release-As`, which release-please always renders under its type's section, so a footer on a follow-up makes the changelog name the follow-up and omit the change.
 3. **Pre-1.0 semantics**: a minor bump may contain breaking changes. Don't assume `0.x` minor bumps are safe to blindly consume — read the changelog.
 4. **Documented alternative — manual tag-first.** Use this instead of release-please when release cadence is near-zero or the team wants zero release automation:
    1. Decide the version by hand.
@@ -64,7 +64,7 @@ gh release edit v0.2.0 --notes "TLDR: ...\n\n$(gh release view v0.2.0 --json bod
 
 ## Pitfalls
 
-- Shipping a release-worthy change under a hidden type (`ci`, `chore`, `docs`, `refactor`, `test`) and waiting for a release PR that never comes — release-please logs `No user facing commits found … skipping`. Either the type was wrong (`feat`/`fix`), or add `Release-As: X.Y.Z` to the PR body so the squash commit carries it (see `skills/branch-and-commit` rule 3).
+- Shipping a release-worthy change under a hidden type (`ci`, `chore`, `docs`, `refactor`, `test`) and waiting for a release PR that never comes — release-please logs `No user facing commits found … skipping`. Usually the type was wrong (`feat`/`fix`); when it was right, the `Release-As` exception in rule 2 applies.
 
 - Publishing or delivering a repository whose `LICENSE` still names the upstream template author — `head -3 LICENSE` before anything leaves the building. For client work an inherited MIT grants the client, and everyone else, far more than the commission contract does, and it cannot be withdrawn (`docs/setup/licensing.md`).
 - Enabling auto-merge on the release-please PR "to save a click" — this defeats the entire point of the human gate described in ADR-0002; the `push:main` race is only closed because a human reviews before merge.