Releases
What each bassclef release changed for adopters. Newest first.
Scan the table to answer "worth bumping?" Read the sections below for the release-by-release detail. Same source. Two views. Categories drive both.
| Version | Adopter impact | Headline | Worth bumping? |
|---|---|---|---|
| v1.6.62026-09-28 | Safe | retire compounding-axis compat shim symlinks | Yes |
| v1.6.52026-09-28 | Safe | cold-adopter timeout fix + /onboard-repo jargon cure | Yes |
| v1.6.42026-09-28 | Safe | statusline hang fix + /longrun scope class taxonomy | Yes |
| v1.4.02026-09-22 | Safe | Three cold-install fixes for the first five minutes | Yes |
| v1.0.02026-09-20 | Migration steps | MAJOR — cleaner adopter install | Depends |
| v0.45.02026-09-18 | Safe | Seven fixes surfaced by bassclef-cli sessions | Yes |
v1.6.6— 2026-09-28
Cures the context-bloat class named in bassclef-upstream#1989. Symlinks left behind by an earlier rename got double-counted by the harness at session start, inflating the loaded rule set for every adopter.
Full release notes on GitHub ↗.
v1.6.5— 2026-09-28
Two Q1 defects from peer defect hunt (bassclef-web + bassclef-cli) ship. Cold-adopter `/temperance` now completes under 120s. Docs.bassclef.dev shows plain descriptions on `/onboard-repo` where jargon used to bounce Sam and Louis.
Full release notes on GitHub ↗.
v1.6.4— 2026-09-28
Two fixes ship. The statusline pointer no longer hangs on TTY-attached invocation or self-loop. The adopter sync writes a state file the reader can consume. The `/longrun` skill adds a scope class taxonomy so per-ticket discipline scales with change class.
Full release notes on GitHub ↗.
v1.4.0— 2026-09-22
Three fixes for problems adopters hit in the first five minutes of a cold install. Each one fires only under the failing shape. Adopters not hitting the bug see no change.
Fresh install
- Cold installs no longer show a false BLOCKED banner. The check for stale hooks used a directory to know how old the install was. But that directory only gets created after one hook fires. So a four-minute-old install with one hook fired reported six of seven critical hooks as "never fired." First-run adopters saw a scary red banner. The check now uses the oldest marker file to date the install, and waits 24 hours before flagging silent hooks. Set `FRESH_INSTALL_GRACE_SECONDS` to change the wait. Sources bassclef-upstream#1895.
- Dispatcher stops complaining when bassclef is already on disk. The dispatcher used to try four ways to fetch bassclef code — peer directory, GitHub API, S3, git clone. None of them worked when the source repo was private. Every session showed "couldn't find bassclef substrate." Adopters read that as a broken install. The dispatcher now checks first whether `.claude/hooks/`, `.claude/rules/`, and `.claude/skills/` already have content. If they do, it exits quietly. Set `BASSCLEF_DISPATCHER_STRICT=1` if you want the old strict behavior for debugging. Sources bassclef-upstream#1849.
CLI + install shell
- install.sh writes the right hook path. install.sh wrote a settings file pointing at `$HOME/.claude/hooks/bassclef-sync.sh`. But the hook file itself landed at the project directory, not at $HOME. The path in settings pointed nowhere, and the dispatcher never fired on cold install. install.sh now writes `$CLAUDE_PROJECT_DIR/.claude/hooks/bassclef-sync.sh` — matching where the hook file actually lives. Sources bassclef-upstream#1902.
Migration
If your `settings.json` has the old `$HOME` path, it still works today. Re-running install.sh will not add duplicates. To use the new path, open `.claude/settings.json` and change `$HOME/.claude/hooks/bassclef-sync.sh` to `$CLAUDE_PROJECT_DIR/.claude/hooks/bassclef-sync.sh`. Fresh installs get the right path automatically.
Why these are safe
Every fix fires only when the bug fires. Adopters who never hit the failure see no change. The grace window and the "already on disk" check are additive. The install-path change only affects fresh installs.
Full release notes on GitHub ↗.
v1.0.0— 2026-09-20
MAJOR release. The manifest that ships to adopters is now clearer about which files belong to the operator and which belong to the adopter. Three operator-only files no longer land in the lite bundle. 33 empty hook entries dropped out of the adopter settings template. 30 hardcoded operator paths were replaced with variables. `/onboard-repo` gained a top-up mode for existing repos.
Full release notes on GitHub ↗.
v0.45.0— 2026-09-18
Seven fixes surfaced by bassclef-cli sessions, plus one release pipeline fix. Each one fires only under the failing shape. Adopters not hitting the bug see no change.
Fresh install
- Cold repos no longer show the red BLOCKED banner. A truly cold repo used to hit the red BLOCKED banner on first session. A new library, `lib/fresh-install-check.sh`, notices when the repo has no commits and no active session lock. The banner still fires when `docs/whereami.md` or a goal doc exists — that means you have already started work. Sources bassclef-cli#102.
- Cold repos skip the "session crashed" banner. A cold repo no longer shows "ABRUPT STOP DETECTED" on first session. `bassclef init` skips the crash-recovery banner for a session that never existed. Sources bassclef-cli#108.
Substrate integrity
- The CLI finds bassclef on disk in the right order. A new library, `lib/bassclef-dir-resolver.sh`, walks four candidate paths in order — peer checkout, `$HOME/bassclef`, bundled copy, and $CWD fallback. The old resolver was two lines and lost the bundled path. Sources bassclef-cli#105.
- Hook wiring diff ignores the guard wrapper. The diff that compares your hook wiring against the shipped shape used to flag adopters who wrapped their hook lines with `[ -f "path" ] && ` and ` || true`. The diff now strips that prefix and suffix before comparing. Adopters using the guarded shape no longer see phantom "missing" reports. The empty banner is also suppressed when the missing list has zero entries. Sources bassclef-upstream#1742.
CLI + install shell
- Clone failures name the real cause. A new library, `lib/clone-failure-classifier.sh`, reads the `git clone` error and picks one of four causes — auth, visibility, network, unknown. Each cause gets its own hint. Before this change, every failure banner said "Set up GitHub auth" — even when the real cause was a private repo you cannot see. The auth hint now reads: `Optional: set up GitHub auth to unlock full-tier sync — run: gh auth login`. Sources bassclef-cli#106.
Session start
- textstat warning fires once per session, not per prompt. The textstat fallback warning used to fire once per prompt. It now fires once per session. `plain-english-steering.sh` writes a per-session marker under `$HOME/.claude/state/sessions/<id>/textstat-warned` so it does not repeat. Sources bassclef-cli#107.
Release pipeline
- Drift check fires on more paths. The lite-manifest drift check now runs when files change under `lib/**` or when `scripts/build-adopter-tree.sh` changes. The old trigger missed edits to lib files that ship at lite.
Session-start signals restored at operator install
Two session-start signals used to go silent at operator install. `session-reflection.d/80-hook-heartbeat-check.sh` now checks the bundled `standards/` path first and falls back to `$BASSCLEF_DIR/standards/`. `session-reflection.d/81-hook-manifest-staleness.sh` uses the same fallback. Before this fix, both returned silently at operator install (where `$BASSCLEF_DIR` is `$HOME`, which has no `standards/`). Adopters never saw the stale-hook warning. Both hooks now declare `# install-class: dual`.
Release pipeline
The release PR body now auto-populates from `docs/release-notes/v<SEMVER>.md` via a new helper, `lib/build-release-pr-body.sh`. Sources bassclef-upstream#1614. `session-reflection.sh` creates `.claude/` before writing the session lock, so adopters in repos without a pre-existing `.claude/` no longer hit "No such file or directory" on session start. Sources bassclef-upstream#1730.
New hook at lite
`session-reflection.d/91-npm-version-drift.sh` is a new hook at lite tier. It warns when your installed `@thebassclef/lite` version drifts from what the pinned bassclef version expects.
Why these are safe
Every fix fires only when the bug fires. All seven cures use the pattern "check bundled path first" (ADR-056 D3). The two Phase A hooks both declare `# install-class: dual` (ADR-058). Adopters who never hit the failure see no change (ADR-031).
Full release notes on GitHub ↗.
| Version | Adopter impact | Headline | Worth bumping? | Full notes |
|---|---|---|---|---|
| v1.6.32026-09-27 | Safe | session-start-and-release cures across seven tickets | Yes | GitHub ↗ |
| v1.6.22026-09-26 | Safe | bassclef-version.json direct-tag write fix | Yes | GitHub ↗ |
| v1.6.12026-09-26 | Safe | Resolver precedence swap + filter-on-read + log-on-skip | Yes | GitHub ↗ |
| v1.6.02026-09-26 | Safe | B + C1 tier-drift cure — cold-adopter first-open shows clean state | Yes | GitHub ↗ |
| v1.5.02026-09-24 | Safe | Q1 tail — adopter template postcondition + git-stash guard + welcome banner | Yes | GitHub ↗ |
| v1.3.02026-09-22 | Safe | More first-5-10-min fixes and cleaner /longrun prep | Yes | GitHub ↗ |
| v1.2.02026-09-21 | Safe | Statusline works on tarball installs | Yes | GitHub ↗ |
| v1.1.12026-09-21 | Safe | Release CI stops false alarms on 6 excluded hooks | Yes | GitHub ↗ |
| v1.1.02026-09-21 | Safe | /longrun prep uses one settled shape | Yes | GitHub ↗ |
| v0.46.02026-09-19 | Safe | CI/CD subsystem lands; auto-regen manifest hook | Yes | GitHub ↗ |
| v0.44.02026-09-18 | Safe | session-start signals reach adopters at operator scope | Yes | GitHub ↗ |
| v0.43.02026-09-17 | Safe | a fresh install stops crying wolf | Yes | GitHub ↗ |
| v0.42.02026-09-16 | Safe | install-class dispatch on adopter machines + 2 debugging luminaries | Yes | GitHub ↗ |
| v0.41.12026-09-14 | Safe | lite bundle self-contained + /longrun prep render check | Yes | GitHub ↗ |
| v0.41.02026-09-14 | Safe | v0.40.1 — /longrun SKILL polish + /onboard-repo preset overlay | Yes | GitHub ↗ |
| v0.40.02026-09-14 | Safe | Real cure for #1619: `dist/lite/` hook binaries ship + persona-scrub V2 body scope + `/launch` desc rewrite | Yes | GitHub ↗ |
| v0.39.02026-09-14 | Safe | Wiring manifest tier extension + `dist/<tier>/` build + ADR-055 | Yes | GitHub ↗ |
| v0.38.02026-09-14 | Safe | /sprint three-preset picker + persona-name scrub at SKILL descriptions | Yes | GitHub ↗ |
| v0.37.52026-09-14 | Safe | six-axis prescription for /longrun prep option tables | Yes | GitHub ↗ |
| v0.37.32026-09-08 | Safe | em-dash fix plus jargon cleanup for the launch | Yes | GitHub ↗ |
| v0.37.22026-09-07 | Safe | curated descriptions land for docs.bassclef.dev launch | Yes | GitHub ↗ |
| v0.37.12026-09-07 | Safe | content lands for the four skill fields shipped in v0.37.0 | Yes | GitHub ↗ |
| v0.37.02026-09-07 | Safe | lite-manifest schema shape ready for docs.bassclef.dev | Yes | GitHub ↗ |
| v0.36.02026-09-07 | Safe | parse cache + steering to lite + CI cure + release-report + schema extension + description backfill | Yes | GitHub ↗ |
| v0.34.02026-09-06 | Safe | State engine subsystem + 5 cures + migration bootstrap | Yes | GitHub ↗ |
| v0.31.22026-09-01 | Safe | release-step6 path resolution fix | Yes | GitHub ↗ |
| v0.31.12026-08-31 | Safe | regressions cure plus Option F remaining paths | Yes | GitHub ↗ |
| v0.31.02026-08-20 | Safe | 2026-08-20 | Yes | GitHub ↗ |
| v0.29.22026-08-19 | Safe | 2026-08-19 | Yes | GitHub ↗ |
| v0.29.12026-08-19 | Safe | 2026-08-19 | Yes | GitHub ↗ |
| v0.29.02026-08-19 | Safe | 2026-08-19 | Yes | GitHub ↗ |
| v0.28.22026-08-13 | Safe | 2026-08-13 | Yes | GitHub ↗ |
| v0.28.12026-08-13 | Safe | 2026-08-13 | Yes | GitHub ↗ |
| v0.26.02026-08-12 | Safe | 2026-08-12 | Yes | GitHub ↗ |
| v0.25.12026-08-03 | Safe | bassclef v0.25.1 — telemetry + lite-manifest + release fixture exclusion + substrate.tar.gz asset | Yes | GitHub ↗ |
| v0.24.02026-07-31 | Safe | bassclef v0.24.0 — hook liveness backstop + deferred-actions lib cure | Yes | GitHub ↗ |
| v0.23.02026-07-31 | Safe | bassclef v0.23.0 — release automation + state-validate cure | Yes | GitHub ↗ |
| v0.2.12026-07-10 | Safe | bassclef v0.2.1 — /longrun + /release SKILL discipline | Yes | GitHub ↗ |
| v0.2.02026-07-10 | Safe | bassclef v0.2.0 — adopter self-heal + polish | Yes | GitHub ↗ |
v1.6.3. <!-- andon-allow: docs/journals/[a-z0-9-]+\.md -->
v1.6.2. Closes `bassclef-upstream#1852` (release-step6 .version drift on descendant tags). Adopter statuslines now read the tag that just shipped, not an old ancestor tag reachable from a stale `release_sha`.
v1.6.1. Closes `bassclef-upstream#1954` (the resolver + filter cure). Cold-adopter Mac with an adjacent bassclef checkout — the `#1953` shadow class the v1.6.0 tier filter could not reach — now gets a clean first-open. Belt-plus-braces: adopter-runtime resolver precedence plus filter-on-read plus per-skip stderr observability.
v1.6.0. Two paired cures close the class the cold-adopter session on 2026-09-25 filed at #1946. Adopters at lite tier stop seeing phantom hook banners on session-start. Author-time drift prevention closes the class going forward.
v1.5.0. Three additive changes close the Q1 first-5-10-min friction thread. Each targets a source of friction Sam or Louis hits on a fresh install.
v1.3.0. More first-five-to-ten-minute fixes. Session-start banners now carry severity tiers. `/longrun prep` reads the whereami queue as a signal that scope is settled. Fresh installs stop hitting false BLOCKED banners.
v1.2.0. Statusline works on tarball installs. Two opt-in release-time checks catch drift between the CLI version pin and what the substrate actually ships.
v1.1.1. The release check reads `template-hook-exclusions.txt` so it stops raising alarms about six hooks we already excluded on purpose. The auto-regen path filter catches seven more file classes that used to slip through.
v1.1.0. `/longrun prep` now uses one settled shape when the scope is clear. The output leads with what will ship, then the recommended option, then a small table of the other options. Detail is one question away.
v0.46.0. First shipment of the CI/CD subsystem. Workflow metrics start recording. A pre-commit hook regenerates the manifest so it never drifts from the source. Three CI reliability fixes — the paths filter no longer drops the wrong files, a SIGPIPE race is fixed, and per-test wall clock is honored.
v0.44.0. Two session-start signals that were silent for lite adopters at operator install layout now surface: hook cadence checks and manifest staleness. Sam and Louis (npm install of `@thebassclef/lite`) hear the substrate again.
v0.43.0. An adopter's very first session no longer warns about a stop that never happened. Alongside it: one tier declaration per file, a local test command that gives CI's answer, and an ADR index that names every record.
v0.42.0. Hooks now install to the scope their header names. The adopter template + operator sync both call `install_by_class` per hook. `# install-class: operator` ships to `$HOME/.claude/hooks/`. `# install-class: project` ships to `$CLAUDE_PROJECT_DIR/.claude/hooks/`. `# install-class: dual` ships to both. Two new debugging luminaries land — Zeller (systematic debugging + Delta Debugging) at lite tier, Agans (9 Debugging Rules) at upstream tier.
v0.41.1. The lite tarball now stands alone — every hard `source` inside a bundled hook resolves to a bundled path. `/longrun prep` output gets a Stop hook that catches four render regressions (path-label repetition, per-option full render, TUI-unsafe cells, `(Via /SKILL)` placeholder leak). Sync becomes an optional upgrade path, not a runtime dependency.
v0.41.0. Two SKILL bodies get UX polish. `/longrun prep` output reads clean on mobile. `/onboard-repo` first-touch shows an adopter-facing preset picker at the top. Zero adopter runtime code touched.
v0.40.0. Ships the `dist/<tier>/` tree that adopters need — 24 lite hook binaries land on public bassclef for the first time. Cures the #1619 regression where PR #1488 shipped 8 files with zero under `dist/`. Adds persona-scrub V2 body scope + `/launch` description rewrite.
v0.39.0. Goal 12e ships end-to-end. The wiring manifest gains per-entry `tier` tags. A new build step emits `dist/<tier>/.claude/settings.json` per tier. A Feathers parity test pins the shape. ADR-055 pins the manifest as init contract source for bassclef-cli. Cures the cold-adopter empty-hooks class since 0.1.0.
v0.38.0. `/sprint` gets the same three-preset picker `/longrun` shipped in v0.37.5. A new hook scans SKILL descriptions for bassclef persona names (Sam, Louis, Jamie, Morgan) that leaked to adopter docs.
v0.37.5. `/longrun` prep option tables now render six practical axes instead of five abstract ones. Adopters see Deliverable, Problem, Value prop, Turns, Risk, and Shipping priority per option. The five-axis legacy shape still works through the 2026-10-31 grace window. Hook accepts both.
v0.37.3. The lite manifest now emits em-dashes as clean characters. Two skill bodies drop internal ticket numbers that leaked into adopter docs. One line in the whereami skill matches the fix that shipped in v0.37.1.
v0.37.2. All 96 skill descriptions were re-curated with Ogilvy discipline — verb-first, ≤270 chars, modes named inline, grade 8-9. Closes the last field bassclef-web renders on the launch page.
v0.37.1. All 34 lite skills now carry curated `problem`, `value`, `inputs`, and `outputs` content. docs.bassclef.dev renders populated columns from this release forward. Plus a small fix for `/substrate-check` prose.
v0.37.0. The lite manifest now declares four new optional fields — `inputs`, `outputs`, `problem`, `value`. docs.bassclef.dev can start rendering them today. Content ships in the next release.
v0.36.0. Session-end runs faster on dense whereami. Lite adopters get plain-English steering + kiss expansion hooks. Ubuntu CI stops rejecting stat-order tests. Release reports read straight. Lite manifest schema gains inputs + outputs. 356 substrate files backfilled with description. 26 lite skills populated with inputs+outputs. Wave B renderer on bassclef-web + bassclef-cli #25 unblocked.
v0.34.0. State engine subsystem gets its architecture pin (ADR-054), 5 read/write cures, plus an opt-in migration script that bootstraps `docs/whereami.json` from the existing markdown frontmatter shape.
v0.31.2. Ships PR #1447 (`3dbd1a29`) — cures the `SCRIPT_LIB` path bug I introduced in the shared-helper refactor (#1435, `2f734238`). Now `rewrite_bassclef_version` uses `$ORIG_DIR` (caller invocation dir) not `$SOURCE_REPO` (may be test fixture) or BASH_SOURCE (breaks after `cd $TARGET_REPO`).
v0.31.1. Ships PR #1446 (`56205bdf`) to public bassclef via release PR #1469 (`af251223`).
v0.31.0. Cold-adopter install unblock. Ships install.sh at bassclef repo root so `curl -fsSL .../install.sh | bash` works in a fresh git repo. Cures HTTP 404 that blocked every new adopter at Step 3 of the cold-adopter chain. Shipped via release commit `fb7a6366`.
v0.29.2. Cumulative release covering session 2026-08-19e (Lane 3 hook re-add cure at source). Shipped via release commit `e2eb06fb`.
v0.29.1. Cumulative release covering session 2026-08-19c (SessionStart hook re-add cure). Shipped via release commit `5a84f13e`.
v0.29.0. Cumulative release covering session 2026-08-19 overnight (Goal A + Goal C spike + Goal D-lite v2) plus session 2026-08-19 AM planning. Shipped via release commit `415d7930`.
v0.28.2. Cumulative release covering session 2026-08-13b (`#1193` + `#1144` bundle) plus session 2026-08-13c (`#1196` + `#1198`). Shipped via PR sunj-labs/bassclef#1454 (merged as `ae5e2bf0`).
v0.28.1. Cumulative release covering session 2026-08-13a (`#1189` bundle). Shipped via PR sunj-labs/bassclef#1453 (merged as `bd9589b3`).
v0.26.0. Cumulative release covering sessions 2026-08-11a appendix, 2026-08-12a, and 2026-08-12b. Shipped via PR sunj-labs/bassclef#1450 (merged); superseded prior PR sunj-labs/bassclef#1449.
v0.25.1. - **feat(#1002) telemetry Iteration 2** — hook + aggregator + adopter uptake report. Opt-in event schema (5 event types, PII-free structurally). 29 Tier 0 tests GREEN. - **feat(#1020) lite-manifest v1.0.0** — schema + generator + companion doc + CI drift-check. Machine-readable lite-tier manifest at repo root (104 entries across 7 substrate surfaces). - **feat(#1028) /promote target config** — new `promote_target` field in bassclef-configs. - **feat(#1035) /manifest-align skill** — persona×stage
v0.24.0. Two ships in one release window. First — a new hook liveness backstop that surfaces silent hook failures within one session cycle instead of quarters. Second — a lib fix that stops the session-start banner from inflating the malformed deferred-actions count.
v0.23.0. Two ships in one release window. First — a new `scripts/release-step6.sh` that automates the tag cut and GitHub Release page for every future `/release`. Second — a state-validate cure so first-time file writes stop firing a false positive when the JSON schema is fine.
v0.2.1. Two SKILL amendments that make substrate work more visible at the moment operators read it.
v0.2.0. Three drift shapes now fix themselves on next session-start. Two small polish items land alongside. One new discipline rule.