chore(claude): SemVer section → release-only tagging (retire per-commit bump+tag; align with canonical VERSIONING-POLICY)

home_root/.claude/CLAUDE.md

@@ -510,19 +510,32 @@ section doesn't cover.
 This section is Corviduo's **operational cadence layer on top of that
 policy**: which commits become releases and at what tier (tier-bar
 test, patch-default, operator approval for minor/major only — patch,
-pre-release, and dev bumps are agent-discretion). Where the two
+pre-release, and dev bumps are agent-discretion). This section governs
-differ on cadence or tier choice, this section governs; for format,
+**tier** choice (patch/minor/major) and the approval gates; **tagging
-contract semantics, pre-release staging, and release mechanics, the
+cadence follows the canonical policy — release-only, dev commits
-policy governs. Operator ruling (2026-07-02): pre-1.0 **milestone
+untagged** (the prior per-commit override is retired, 2026-07-30). For
+format, contract semantics, pre-release staging, and release mechanics,
+the policy governs. Operator ruling (2026-07-02): pre-1.0 **milestone
 minors stay legal** — this section's non-breaking milestone-minor
 examples override the policy's § 4 strict reading (pre-1.0 minor =
 breaking changes only). Settled; do not re-litigate.
 
-Each code-bearing or substantive-artifact commit bumps a version in
+**A version is a property of a *released artifact*, not of a commit**
-the project's `pyproject.toml` (or equivalent), refreshes the
+(canonical `VERSIONING-POLICY.md`). Commits accumulate on the way to a
-lockfile, gets a `vX.Y.Z` git tag. Establishes a fine-grained
+release and are **not** tagged — they are identified by SHA +
-changelog and lets any peer pin against a known-good substrate
+conventional-commit messages (`feat:` / `fix:` / … — the changelog
-state.
+source). **At a release** (a version you publish, ship to a consumer,
+or cut as a milestone), bump the version in `pyproject.toml` (or
+equivalent), refresh the lockfile, and cut **one** `vX.Y.Z` git tag.
+Fine-grained history lives in the commit log; per-commit *tags* do not
+— nobody pins against an arbitrary mid-development commit, so a
+tag-per-commit is clutter (the 2026-07-30 audit found 495–507 tags on
+the busiest repos, ~97% of them redundant per-commit tags for a
+per-commit-pin benefit nobody exercises). **Retired 2026-07-30
+(operator-ratified):** the prior per-commit bump+tag cadence — an
+operational-layer override of the canonical policy — no longer applies;
+this section is now consistent with the policy's release-only tagging
+("dev commits MUST NOT be tagged").
 
 **Tier-bar test (the decision tool):**
 
@@ -598,8 +611,10 @@ authorizations.
 
 ### Patch (`X.Y.Z` → `X.Y.Z+1`) — workhorse default
 
-The default for any code-bearing or substantive-artifact commit.
+Patch is the **default release tier** — most releases are patches. A
-Includes:
+patch *release* bundles the bug fixes / internal improvements /
+refactors / new-artifacts-in-a-family that accumulated as commits
+since the last release. A patch release includes:
 
 - Bug fixes
 - Internal correctness improvements
@@ -702,24 +717,30 @@ test.
 - Worktree-rebuild or env-config changes
 - `.claude/` configuration edits
 
+**Forward-only.** Existing per-commit tags stay (no retroactive prune,
+mirroring the no-retroactive-bump posture); new tags follow the
+release-only cadence from here. The SKIP list above now names things
+that never constitute a release on their own.
+
 ### Cadence
 
-Most commits should be patches. Minor should be rarer than commits —
+Most **releases** are patches; minor/major are rarer. **Commits are
-often 5-15 patches between minors during active development.
+not releases** — a TDD red/green/refactor cycle is just commits
-
+(conventional messages), not bumps, and the work is versioned when
-A TDD red/green/refactor cycle bumps once or twice (GREEN as patch,
+it's cut as a release, not per cycle. A feature shipped across several
-REFACTOR as patch — never three times for the same logical change).
+commits is versioned once, at the release that publishes it — its tier
-A feature shipped as several incremental green commits bumps each as
+set by the tier-bar test. Cadence = release when there's something
-patch; the minor that "publishes" the feature can fire at the end of
+worth releasing, not on a per-commit clock.
-the arc if it warrants a release-note, OR can be skipped if patches
-were sufficient.
 
 If you find yourself bumping minor multiple times per session on the
 same project, you're likely over-applying minor. Default back to
-patch and ask: does this *specific* commit warrant a release-note
+patch and ask: does this *release* warrant a release-note paragraph,
-paragraph, or am I just accumulating substantive work?
+or am I just accumulating substantive work?
 
-### Mechanics every bump
+### Mechanics — every release
+
+These fire **at a release**, not per commit (dev commits are just
+SHAs + conventional messages):
 
 0. **If minor or major (an `X` or `Y` field change), get operator
    approval first** per the § *Operator approval required for minor +
@@ -733,10 +754,11 @@ paragraph, or am I just accumulating substantive work?
 3. Stage both files alongside the actual change.
 4. Commit with the conventional shape (e.g., `feat(#N): …` /
    `fix(#N): …` / `refactor: …`).
-5. `git tag vX.Y.Z` after the commit. Lightweight (no `-a`, no
+5. `git tag vX.Y.Z` on the release commit — **one tag per release,
-   message) is deliberate for per-bump tags: the commit object
+   never per commit** (dev commits between releases stay untagged).
-   carries the rationale, and the tag is just a ref naming the
+   Lightweight (no `-a`, no message) for patch/minor releases: the
-   substrate state.
+   commit object carries the rationale, and the tag is just a ref
+   naming the released state.
    **Exception — milestone releases** (v1.0, v2.0, future major
    cuts) get annotated tags (`git tag -a -m "…"`, or `git tag -s`
    when signing). At a milestone the attestation matters separately