Skip to content

docs(claude): weekly CLAUDE.md refresh 2026-07-06 #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
allyblockcast wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs(claude): weekly CLAUDE.md refresh 2026-07-06 #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 7 additions & 6 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -474,15 +475,15 @@ 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 |
|---|---|---|
| `VERSION` | The single source of truth. Read first by `/ship`, the binary, and CI version-gate. | Bare 4-segment string `MAJOR.MINOR.PATCH.MICRO` (e.g. `0.31.4.1`), no leading `v`. |
| `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):**

Expand Down
13 changes: 7 additions & 6 deletions llms-full.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -623,15 +624,15 @@ 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 |
|---|---|---|
| `VERSION` | The single source of truth. Read first by `/ship`, the binary, and CI version-gate. | Bare 4-segment string `MAJOR.MINOR.PATCH.MICRO` (e.g. `0.31.4.1`), no leading `v`. |
| `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):**

Expand Down
Loading