From 4e368a3801d45232e397b3d23b241bdba4a9d1af Mon Sep 17 00:00:00 2001 From: Search Date: Mon, 6 Jul 2026 17:21:22 +0000 Subject: [PATCH] docs(claude): refresh version-location guidance Co-Authored-By: Paperclip --- CLAUDE.md | 13 +++++++------ llms-full.txt | 13 +++++++------ 2 files changed, 14 insertions(+), 12 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 30c36e6dfa..eb36c95c9f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -458,10 +458,11 @@ ms, max waiters) for `--json`; a one-line summary prints to stderr. ## Version locations (single source of truth: `VERSION` file) -Every release advances the version in **five files at once**. Keep these in -sync. `/ship` enforces this via Step 12's idempotency check (VERSION vs -package.json drift), but the canonical list lives here so future runs and -the auto-update agent know where to look. +Every release advances the explicit version in `VERSION`, `package.json`, and +`CHANGELOG.md`; release-adjacent references in `TODOS.md` and `CLAUDE.md` are +audited and updated only when their owned content changes. `/ship` enforces the +VERSION/package.json idempotency check via Step 12, but the canonical list lives +here so future runs and the auto-update agent know where to look. **Version format is mandatory: `MAJOR.MINOR.PATCH.MICRO` (four numeric segments, dot-separated, no leading `v`).** Every new release MUST use the @@ -474,7 +475,7 @@ four numeric segments are required first. Historical 3-segment versions (`0.31.3`, `0.22.1`) remain valid in `git log` and migration filenames (`skills/migrations/v0.21.0.md`); do NOT rewrite them. Going forward only. -**Required (every release must update all five):** +**Required (every release must audit all five):** | File | What lives there | Format | |---|---|---| @@ -482,7 +483,7 @@ four numeric segments are required first. Historical 3-segment versions | `package.json` | Bun/npm package version. `gbrain --version` reads it via the compiled binary's bundled package metadata. CI version-gate cross-checks this against `VERSION` and fails if they drift. | `"version": "0.31.4.1"` | | `CHANGELOG.md` | Top entry header `## [0.31.4.1] - YYYY-MM-DD` plus the "To take advantage of v0.31.4.1" block. | Standard Keep-a-Changelog header. | | `TODOS.md` | Any TODO entries that mention "follow-up from vX.Y.Z.W" use the version of the release that filed them. Update only when filing NEW follow-up TODOs. | Inline `vX.Y.Z.W` references in TODO bodies. | -| `CLAUDE.md` | The Key Files section's per-file annotations carry `vX.Y.Z.W (#NNN)` tags noting which release introduced a behavior. Update whenever a wave's annotations get folded in. | Inline `vX.Y.Z.W (#NNN, contributed by @user)` references. | +| `CLAUDE.md` | Always-loaded orientation + release-critical rules. Update when the release changes those rules, reference-map entries, or cross-cutting invariants; do not reintroduce inline per-file release annotations. | Current-state prose, no append-only per-file version clauses. | **Auto-derived (no manual edit; refreshed by their own commands):** diff --git a/llms-full.txt b/llms-full.txt index 2dcb09aad0..989234d584 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -607,10 +607,11 @@ ms, max waiters) for `--json`; a one-line summary prints to stderr. ## Version locations (single source of truth: `VERSION` file) -Every release advances the version in **five files at once**. Keep these in -sync. `/ship` enforces this via Step 12's idempotency check (VERSION vs -package.json drift), but the canonical list lives here so future runs and -the auto-update agent know where to look. +Every release advances the explicit version in `VERSION`, `package.json`, and +`CHANGELOG.md`; release-adjacent references in `TODOS.md` and `CLAUDE.md` are +audited and updated only when their owned content changes. `/ship` enforces the +VERSION/package.json idempotency check via Step 12, but the canonical list lives +here so future runs and the auto-update agent know where to look. **Version format is mandatory: `MAJOR.MINOR.PATCH.MICRO` (four numeric segments, dot-separated, no leading `v`).** Every new release MUST use the @@ -623,7 +624,7 @@ four numeric segments are required first. Historical 3-segment versions (`0.31.3`, `0.22.1`) remain valid in `git log` and migration filenames (`skills/migrations/v0.21.0.md`); do NOT rewrite them. Going forward only. -**Required (every release must update all five):** +**Required (every release must audit all five):** | File | What lives there | Format | |---|---|---| @@ -631,7 +632,7 @@ four numeric segments are required first. Historical 3-segment versions | `package.json` | Bun/npm package version. `gbrain --version` reads it via the compiled binary's bundled package metadata. CI version-gate cross-checks this against `VERSION` and fails if they drift. | `"version": "0.31.4.1"` | | `CHANGELOG.md` | Top entry header `## [0.31.4.1] - YYYY-MM-DD` plus the "To take advantage of v0.31.4.1" block. | Standard Keep-a-Changelog header. | | `TODOS.md` | Any TODO entries that mention "follow-up from vX.Y.Z.W" use the version of the release that filed them. Update only when filing NEW follow-up TODOs. | Inline `vX.Y.Z.W` references in TODO bodies. | -| `CLAUDE.md` | The Key Files section's per-file annotations carry `vX.Y.Z.W (#NNN)` tags noting which release introduced a behavior. Update whenever a wave's annotations get folded in. | Inline `vX.Y.Z.W (#NNN, contributed by @user)` references. | +| `CLAUDE.md` | Always-loaded orientation + release-critical rules. Update when the release changes those rules, reference-map entries, or cross-cutting invariants; do not reintroduce inline per-file release annotations. | Current-state prose, no append-only per-file version clauses. | **Auto-derived (no manual edit; refreshed by their own commands):**