From 3d742fb56b6d95bd9641646abbce52c99e90b3f9 Mon Sep 17 00:00:00 2001 From: Your Name Date: Fri, 31 Jul 2026 21:24:21 -0700 Subject: [PATCH] =?UTF-8?q?chore(claude):=20SemVer=20section=20=E2=86=92?= =?UTF-8?q?=20release-only=20tagging=20(retire=20per-commit=20bump+tag;=20?= =?UTF-8?q?align=20with=20canonical=20VERSIONING-POLICY)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- home_root/.claude/CLAUDE.md | 76 ++++++++++++++++++++++++------------- 1 file changed, 49 insertions(+), 27 deletions(-) diff --git a/home_root/.claude/CLAUDE.md b/home_root/.claude/CLAUDE.md index 7f681dd..8c591f4 100644 --- a/home_root/.claude/CLAUDE.md +++ b/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 -differ on cadence or tier choice, this section governs; for format, -contract semantics, pre-release staging, and release mechanics, the -policy governs. Operator ruling (2026-07-02): pre-1.0 **milestone +pre-release, and dev bumps are agent-discretion). This section governs +**tier** choice (patch/minor/major) and the approval gates; **tagging +cadence follows the canonical policy — release-only, dev commits +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 -the project's `pyproject.toml` (or equivalent), refreshes the -lockfile, gets a `vX.Y.Z` git tag. Establishes a fine-grained -changelog and lets any peer pin against a known-good substrate -state. +**A version is a property of a *released artifact*, not of a commit** +(canonical `VERSIONING-POLICY.md`). Commits accumulate on the way to a +release and are **not** tagged — they are identified by SHA + +conventional-commit messages (`feat:` / `fix:` / … — the changelog +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. -Includes: +Patch is the **default release tier** — most releases are patches. A +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 — -often 5-15 patches between minors during active development. - -A TDD red/green/refactor cycle bumps once or twice (GREEN as patch, -REFACTOR as patch — never three times for the same logical change). -A feature shipped as several incremental green commits bumps each as -patch; the minor that "publishes" the feature can fire at the end of -the arc if it warrants a release-note, OR can be skipped if patches -were sufficient. +Most **releases** are patches; minor/major are rarer. **Commits are +not releases** — a TDD red/green/refactor cycle is just commits +(conventional messages), not bumps, and the work is versioned when +it's cut as a release, not per cycle. A feature shipped across several +commits is versioned once, at the release that publishes it — its tier +set by the tier-bar test. Cadence = release when there's something +worth releasing, not on a per-commit clock. 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 -paragraph, or am I just accumulating substantive work? +patch and ask: does this *release* warrant a release-note paragraph, +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 - message) is deliberate for per-bump tags: the commit object - carries the rationale, and the tag is just a ref naming the - substrate state. +5. `git tag vX.Y.Z` on the release commit — **one tag per release, + never per commit** (dev commits between releases stay untagged). + Lightweight (no `-a`, no message) for patch/minor releases: the + 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