* docs(agents): bazel test is authoritative; agents never run go test
Agents run tests only with `bazel test`, also while iterating on one
behavior: AGENTS.md shows the focused form
(`bazel test //cmd/bd:bd_test --config=ci --test_filter='^TestName$'`), the
target naming, that one --test_filter covers every target, that a cached
result for unchanged inputs is the same evidence, and that a new test file
needs `make bazel-sync` before Bazel runs it. `go test` (`./scripts/test.sh`,
`make test-go`) stays a convenience for humans working offline. TESTING.md's
focused red/green row and its plain-go-test section say the same.
Why: on the maintainer-city factory host, seats' own uncached `go test`
reruns of the same packages are the largest tool cost in adopt-pr, while
`bazel test` there executes on rbe-west and returns an unchanged target's
cached result in seconds.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* docs(agents): check that a focused test ran; exempt golden regeneration
Review fixes for #7695 (iterations 1 and 2).
The focused form exits 0 with "1 test passes" when the test never ran: a
filter that matches nothing, an integration-tagged file --config=ci does not
compile, the TestEmbedded* name skip, a -short skip, and a parent test whose
every subtest skipped (Go still prints "--- PASS" for the parent). It now
adds --test_output=all, and a run counts only when its log shows
"--- PASS: <TestName>" and no "--- SKIP" for the test or a <TestName>/...
subtest; a subtest that skips by design is left out with a subtest filter.
engdocs/TESTING.md gains "Check That the Test Ran"; AGENTS.md links there
instead of restating it. The section names the tests --config=ci does not
run and the way into each:
- Dolt-backed: the three --test_env flags, or the test's Dolt lane.
- -short-gated: --test_arg=-test.short=false.
- integration-tagged: --config=integration; the Dolt-backed ones of cmd/bd,
tests/regression and internal/storage/dolt run in their Dolt-server lane
target, whose env the suite needs. No lane runs those of other packages
with Dolt, so a failure there is compared with the base commit first.
- TestEmbedded*: --test_arg=-test.skip= lifts the name skip; a test that
then still skips for BEADS_TEST_EMBEDDED_DOLT=1 runs in its package's
embedded-tagged target under --config=embedded (the cmd/bd and
internal/storage/embeddeddolt targets are named).
- files BUILD.bazel does not list: make bazel-sync.
A lane's sh_test can hand the test binary its own -test.run, which
overrides --test_filter, so a trailing --test_arg=-test.run with sharding
disabled selects the test there. In a sharded target the other shards print
"testing: warning: no tests to run". The section also gives the
target-naming rule.
Golden regeneration (make corpus-regen, make githooks-regen,
BD_UPDATE_GOLDEN=1 ... go test, -update-ledger-doc) writes the source tree,
which a Bazel test cannot do: it runs from its runfiles tree, and on
rbe-west update mode fails with "permission denied". AGENTS.md and the new
"Regenerating Golden Files" section exempt these go test runs; where a host
refuses go test even for them, a maintainer regenerates. The factory seat
shim (gastownhall/workflows#102, scripts/seat-bin/go) still refuses update
mode and needs the same carve-out there.
Also: the plain-go-test opener scopes "humans working offline" to the
runner and its go test targets, so the Dolt-backend, fixture and
testing.Short() rules still bind agents; make ci-pr-core is marked plain go
test; the beads-docs skill's docsync gate is the Bazel target; RELEASING.md
and engdocs/RELEASE-STABILITY-GATE.md name the regression suite's Bazel
target (//tests/regression:regression_test under --config=doltserver-cmd)
in place of make test-regression, which is plain go test.
Measured on rbe-west (exit 0 unless noted). Iteration 1, at c4d5409895:
- a mistyped filter, and //internal/compact TestNew (integration-tagged)
under --config=ci: "testing: warning: no tests to run"
- TestNew under --config=integration: "--- SKIP" (BEADS_TEST_SKIP=dolt);
with the Dolt flags added it runs (and fails, exit 3, on the local
backend: its store finds no "beads" database; outside this PR)
- TestConcurrentHeartbeatReclaimClose with the Dolt flags: "--- SKIP"
(short mode); plus --test_arg=-test.short=false: "--- PASS"
- //cmd/bd:bd_embedded_test, sharding disabled: --test_filter alone ran
TestEmbeddedUpdateConcurrent (manifest shard 1's test); the trailing
-test.run ran "--- PASS: TestEmbeddedShowBasicsAndJSON"
- //scripts:go_test_sources_test
TestEmbeddedCmdShardManifestBareWriteIsIdempotent: --config=ci "no tests
to run"; plus --test_arg=-test.skip=: "--- PASS"
Iteration 2, at b1d25543aa (the same Go inputs):
- //internal/storage/dolt:dolt_test TestMoveIssuePersistenceInTxTransitions
under --config=ci: "--- PASS" for the parent and "--- SKIP" for all 6
subtests (BEADS_TEST_SKIP=dolt), "1 test passes"; with the Dolt flags and
--test_filter='^TestMoveIssuePersistenceInTxTransitions$/^persistent-to-ephemeral$'
"--- PASS" for the parent and that subtest only, no "--- SKIP"
- //internal/storage/embeddeddolt:embeddeddolt_test
TestEmbeddedRemoteMigrateGate_BlocksReopen under --config=ci plus
--test_arg=-test.skip=: "--- SKIP" (BEADS_TEST_EMBEDDED_DOLT unset);
//internal/storage/embeddeddolt:embeddeddolt_embedded_test under
--config=embedded, sharding disabled, trailing -test.run: "--- PASS"
(the shard script listed 433 tests; only the named one ran)
- --config=ci plus --test_arg=-test.skip=: "--- PASS" for //tools/nogo
TestEmbeddedConfigIsTheRepositoryConfig and //internal/tracker
TestEmbeddedDoltExternalRefChangedAfterUsesHistoryFastPath
- sharding disabled, trailing -test.run: "--- PASS" for
//internal/storage/dolt:dolt_server_full_test
TestWispDeleteCascade_TransactionDeleteIssue under
--config=doltserver-integration, and for //cmd/bd:bd_dolt_server_test
TestCLI_ReopenClearsDeferUntil under --config=doltserver-cmd
- make check-docs: exit 0 (docsync: 10 test cases ran, none skipped)
Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Eddie the Engineer <338826946+gascity-eddie[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Push to main and the nightly schedule no longer run go test or repo checks
on GitHub runners (ga-96smfk.22, ga-96smfk.58):
- main.yml keeps only the macOS -race -short suite, the Windows smoke build
and the push-to-main savers of the GOCACHEs pr.yml's Windows/macOS jobs
restore. Its Linux jobs (migration hygiene, build artifacts, build tags,
versions, duplicate migrations, doc flags, package gates, PR policy
wrapper, gofmt, the Linux and setup-go cache seeders, the Nix flake
check) are gated on the merge queue's pr.yml/pr-risk.yml run of the
same commit and re-run as Bazel targets by bazel.yml's push run.
- nightly.yml is the fresh bazel.yml call plus the worker-env check; its
Full Test Suite, PR Core go-test-json side and measure dispatch are gone,
as are ci-measurements.yml and bazel.yml's go-test-json-artifact input.
- The non-race embedded batch-apply step becomes
//internal/storage/embeddeddolt:embeddeddolt_batch_apply_nonrace_test
(go_test_race_off, BEADS_TEST_EMBEDDED_DOLT=1) in the embedded tier.
- make ci-pr-policy and scripts/ci/pr-policy.sh go: every check it ran is
a Bazel test (TestPRPolicyChecksRunAsBazelTargets).
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Bazel is beads' build and test system: bazel.yml's lanes gate every PR,
and nogo (lint + vet), gofmt and the repository guards exist only as
Bazel targets. The docs, the Makefile and the hooks now say so.
Makefile: `make test` runs bazel.yml's test lane (`bazel test //...
--config=ci`), `make check` adds the testing.Short policy and the
`make ci-pr-lint` nogo gate, and `make check-docs` runs the docsync and
doc-freshness Bazel targets before the pinned-release CLI flag check.
BAZEL_FLAGS passes --config=fork-cache or --config=remote-exec through.
The plain-Go recipes stay as explicit twins: test-go, check-go,
check-docs-go. No workflow called the primary names, and
TestWorkflowsNameTheirTestEngine keeps it that way.
Hooks: pre-push runs scripts/pre-push-suite.sh for branch pushes whose
commits change Go or Bazel inputs: the test lane with
--config=remote-exec when some rc names an executor, else
--config=fork-cache. Without bazel, or with BD_PREPUSH_SUITE=go, it runs
make test-go under a banner saying that is not what CI gates on.
Docs: AGENTS.md, CONTRIBUTING.md, engdocs/TESTING.md (a per-lane command
table and the fork-cache/remote-exec setup), README, RELEASING, the PR
template and the .bazelrc header. Bazelisk is a required prerequisite;
go test is an inner-loop convenience CI does not enforce.
Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
pr.yml's check-release-target-cross-compilation ran `CGO_ENABLED=0
GOOS/GOARCH go build -tags gms_pure_go ./...` for the eight release targets
on two GitHub/Blacksmith runners. It is now a step of bazel.yml's pure-Go
lane (BAZEL_PURE, already required by ci-gate):
scripts/ci/bazel-release-cross-compile.sh builds //tools/bazel:release_cross
once, remotely, with --//tools/bazel:release_platforms set from
scripts/ci/release-targets.txt (still the single source of truth, pinned to
.goreleaser.yml). release_cross's split transition configures every
go_library/go_binary for each rules_go platform with cgo off, so all eight
platforms build in parallel in one invocation.
- tools/bazel/release_cross.bzl: the split-transition rule and the
string-list flag.
- tools/bazel/go_srcs.py (make bazel-sync, checked by bazel-sync-check and
TestBazelGoSrcsBlocksCurrent) keeps the release_cross target list; the
script checks with bazel query that every Bazel package holding Go
targets is reached before it builds.
- //tools/bazel:pure_bd_has_no_cgo_only_deps: Bazel compiles gozstd's pure
stubs where `go build` rejects them, so the pure bd of every platform
must not link gozstd.
- //internal/storage/embeddeddolt/cmd:cmd (cgo-only main, skipped by
`go build ./...` under CGO_ENABLED=0) is tagged cgo-only and incompatible
with pure builds.
- A failed build is re-run per platform (cache hits) to name each failing
GOOS/GOARCH.
Same cgo-off coverage boundary as the retired job. Refs ga-96smfk.20.
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* chore: bump version to 1.3.0
Runs scripts/update-versions.sh 1.3.0, the sanctioned path per RELEASING.md.
Covers everything scripts/check-versions.sh gates: cmd/bd/version.go, the
three plugin manifests plus the marketplace, the MCP pyproject/__init__/
uv.lock pin, npm-package/package.json, the tracked .githooks managed-section
markers, default.nix and the Windows PE resource metadata.
scripts/check-versions.sh passes at 1.3.0.
* docs(changelog): roll up [1.3.0] for 2026-08-28
Creates the [1.3.0] section dated 2026-08-28 and leaves [Unreleased] empty
but present.
- Rolls up everything that was under [Unreleased].
- Adds a 'Breaking changes for v1.2.2 users' section. v1.2.2 shipped the
v1.1.2 tree, so its users never received [1.2.1]; the five behavioral
breaks documented there are restated (close policy on bd update -s, search
including closed, the interactive-only last-touched fallback, bd human list
status handling, dolt push/sync remote-adoption consent) with a pointer to
the historical section rather than a copy of it. The two breaks new in
1.3.0 (BEADS_DOLT_PORT precedence, actor '--' decoding) are indexed here
and written up in full under Changed.
- Adds upgrade notes: first invocation auto-migrates v53 -> v66 (13
migrations, 0054..0066, verified against the embedded migrations dir);
per-step progress on stderr is TTY-gated, so CI sees nothing; back up
first; the forward skew guard means co-resident older binaries refuse the
store, so a shared-store fleet upgrades together; rollback via the recovery
runbook's cursor-rollback procedure.
- Adds entries for eight changes that had no changelog line at all, each
verified against the code on this branch: --profile -> --cpu-profile with
no alias (#5126); the one-time content-derived aux-row id rekey, main 0061
(#5150); events becoming clone-local, 0062 (#5162); the interactions.jsonl
sidecar becoming opt-in behind audit.enabled (#4688); bd import erroring on
redirected stdin with no source (#5171); auto-backup defaulting off under a
sql-server (wy-zrmqr); bd hooks install --chain/--force becoming no-ops
under marker sections (#5284); the new *.gate.lock workspace/physical-root
gate files (#5046, #5093); and purge/prune tier selection (#5995).
- Moves the 'sort on listIssues' entry (#5666) out of [1.2.2] and into
[1.3.0]. Its commit 8aaefe2d4 is not an ancestor of the v1.2.2 tag, so it
never shipped in that release.
* feat(info): add the 1.3.0 versionChanges entry
RELEASING.md makes cmd/bd/info.go a required release step: versionChanges is
the channel 'bd info --whats-new' uses to tell an agent what changed under it.
The entry matches the existing format and carries the same upgrade notes as
CHANGELOG's [1.3.0] — the v53->v66 migration and its cost, the fleet
implication of the forward skew guard, the rollback pointer, the seven
behavioral breaks a v1.2.2 user meets, and the headline changes.
* docs(releasing): document the release-branch process, fix the semver wording, close the audited checklist gaps
Release-branch process (now in use for 1.3.0): a new 'Release Branches'
section covers cutting release/x.y.z from a SHA green on both Main and
Nightly Full Tests, landing every release-targeted change as a PR based on
the release branch and labeled status/needs-review-auto, tagging from the
branch, and forward-porting to main afterwards. Hotfixes are folded into the
same shape rather than a parallel one.
Semver: MAJOR is now removals and incompatible interface changes; documented
behavioral breaks that ship with migration notes are a MINOR bump, with the
obligation that makes that legitimate (CHANGELOG entry naming the override,
plus an info.go summary). 1.3.0 is cited as the worked example.
Checklist gaps the audit found: cross-compiling every goreleaser target
before tagging (GH#5662 — PR CI builds none of them, and the freebsd break
burned the v1.2.0 tag), the docs cutover (cli-docs.pin bump plus regen, and
the hand-maintained release line on docs/index.md, which had gone stale at
1.1.0), a release-notes rollup check for both an unemptied [Unreleased] and
entries misfiled under a previous tag, an explicit check-versions.sh gate,
and the info.go entry.
Also retires the bump-version.sh instructions: that script has been a
deprecation stub that exits 1 for some time, so the document's primary
version-bump instruction could not work. Replaced with update-versions.sh
plus check-versions.sh, and the file list corrected against what the script
touches now (uv.lock, the copilot plugin, the .githooks markers, winres) —
the old list named cmd/bd/templates/hooks/* and PLUGIN.md, neither of which
it writes. 'The Easy Way' now names the release molecule; release.sh is a
gateway that prints it.
Fixes the drifted table of contents while in the area.
* fix(release-formula): bump via update-versions.sh, verify via check-versions.sh
The formula carried its own hand-rolled copy of the version bump, and it had
drifted from the scripts it was copied from. bump-plugin-json pointed at
claude-plugin/.claude-plugin/plugin.json, a path that has not existed since
the plugins moved under plugins/beads/ — so the step would have failed
outright — and the copy covered none of the files added to the gate since:
the codex and copilot plugin manifests, integrations/beads-mcp/uv.lock, and
the BEADS INTEGRATION markers in .githooks/*. A release driven by this
formula would either die on the stale path or ship inconsistent versions,
which is how the v1.1.1 tag burned (stale uv.lock, discovered only in the
tag-triggered run) and how the v1.2.0 bump reddened main (stale hook
markers).
Replaces the seven hand-rolled bump steps with one that runs
scripts/update-versions.sh, which is the sanctioned path and cannot drift
from itself, and turns verify-versions into scripts/check-versions.sh — the
same gate the release-tag pre-push hook and CI run — instead of a grep list
that has to be maintained in parallel with the real one. Both steps carry the
two failure modes worth knowing about: uv missing (leaves uv.lock stale, fails
only after the tag exists) and the hook markers being rewritten wholesale
rather than matched.
Also renames push-main to reflect the release-branch process now documented
in RELEASING.md, and adds the forward-port reminder there.
Verified: each listed file checked against scripts/update-versions.sh and
scripts/check-versions.sh as they exist on this branch, and against a real
./scripts/update-versions.sh 1.3.0 run. go test ./scripts/ -run Release
passes (the formula still parses, and the cleanup-stale-dolt-orphans,
verify-homebrew-core and local-install assertions are untouched).
* docs: point the release banner at 1.3.0 and tell 1.2.2 users what this upgrade costs
The docs homepage carries a hand-maintained 'These docs are for the X.Y.Z
release' line that nothing generates or validates, so it had gone stale at
1.1.0 while the CLI docs pin had already moved to v1.2.2. It now names 1.3.0
and sends the reader to Upgrading first, since this upgrade crosses a schema
migration. RELEASING.md now carries a checklist item for it.
docs/getting-started/upgrading.md was entirely version-agnostic: strong on
mechanism (install methods, hooks, the remote-migrate gate, backup-first,
the multi-clone flow) and silent on which release you are coming from. A
1.2.2 user could read the whole page without learning that their database is
at v53 and that this step crosses 13 migrations. Adds an 'Upgrading to 1.3.0'
section covering the v53->v66 jump and why it is bigger than a routine one,
the slower first invocation and its TTY-gated per-step progress, the
forward-skew consequence for a shared store (upgrade every client together),
and the cursor-rollback runbook. It links to the backup and multi-clone
procedures already on the page rather than restating them.
Also adds the schema-version-mismatch runbook to the Recovery index table.
It was reachable only from the sidebar and the CHANGELOG, and the new
Upgrading section links to it.
Generated docs untouched: scripts/check-cli-docs-drift.sh passes against the
v1.2.2 pin, and the pin bump is a post-tag step (generate-cli-docs.sh builds
bd from the pinned tag, which does not exist until v1.3.0 is pushed).
go test ./test/docsync and scripts/check-doc-freshness.sh pass.
* fix(release-notes): correct the backup advice, the migration count, and the breaks undercount
Review round on #6038. Four findings, all of which made the upgrade notes
actively misleading rather than merely incomplete.
CRITICAL — bare 'bd backup' takes no backup. backupCmd is a runless cobra
parent (no Run/RunE, children init/sync/restore/remove/status, no default),
so cobra prints usage and exits 0 without writing anything. A user following
'bd backup' before an irreversible 27-migration upgrade sees help text and
proceeds believing a snapshot exists; in a script, 'bd backup && ...' proceeds
on exit 0. Replaced with 'bd backup init <path>' then 'bd backup sync' in
CHANGELOG, info.go and upgrading.md, and said in each place that bare
'bd backup' takes no backup.
Also CRITICAL, same class: the backup had no ordering rule. Under 1.3.0
'bd export' triggers autoMigrateOnVersionBump before it exports, so a backup
taken after installing is a post-migration snapshot that cannot protect
against the migration going wrong. All three copies now say to back up with
the OLD binary before installing, and carry the neighbouring rule that
remote-backed stores must finish 'bd dolt push' first, since the
pending-migration gate refuses push/pull too.
Migration count: '13' was the main series only. schema.go runs the main
source then the ignored source through the same 'Applying migration %04d'
printer, and the ignored series moves 0011 -> 0025 here, so the run is ~27
migrations and the counter visibly restarts from 0066 back to 0012. That
backwards jump is exactly the signature an operator reads as a loop and
kills — while these same notes say 'do not interrupt it'. All three copies
now state ~27, show the restart in sample output with real migration names,
and label it as not a restart.
Breaks undercount: 'seven' read as an enumeration, but [1.2.1] carries three
more entries explicitly labelled BREAKING that a v1.2.2 user also meets.
Retitled as highlights with an explicit pointer to the full [1.2.1] section,
and added the three: '--readonly serve' now refused (load-bearing next to the
'restart any long-running bd serve' advice — it will not come back up), the
config kv-plane drop, and the backend package's orphan-handling removal. The
info.go entry gets the same pointer and the same three, since 'bd info' is the
only copy reachable after installing.
Upgrade-time reader is now pointed at 'bd upgrade review', which computes the
delta since the previously-run version via getVersionsSince, instead of
'bd info --whats-new', whose showWhatsNew loops the entire versionChanges
array with no cap (~80 entries) to deliver the ~11 relevant bullets.
* fix(check-versions): gate the copilot manifest and the winres files, stop overclaiming
Three review findings, all cases where the gate said more than it checked.
Copilot manifest was bumped but never gated. update-versions.sh:101 rewrites
plugins/beads/.copilot-plugin/plugin.json with a sed anchored on the OLD
version, and check-versions.sh never read the file — the string 'copilot' did
not appear in it. That is the same drift class that carried stale .githooks
markers through v1.2.0: once the file drifts the bump silently no-ops on it,
the green line prints, the pre-push hook and CI pass, and the Copilot plugin
ships advertising the previous version. Now gated. Verified it fails: drifting
the file to 1.2.2 reddens the run and exits 1.
winres was verified by nothing after the formula rewrite deleted the steps
that grepped it. Restored as real gates rather than formula prose, since
manifest.xml's <assemblyIdentity> version has no backstop at all —
gen-winres.sh re-derives winres.json's numeric fields from version.go at build
time, but the manifest's version is embedded verbatim, and update-versions.sh
rewrites it with a sed anchored on the old base version. Prerelease-correct:
file_version/product_version and the manifest's four-part version are checked
against the BASE version while FileVersion/ProductVersion are checked against
the full string, which is what update-versions.sh writes. The manifest grep is
anchored at line start because the XML declaration also carries a version=
attribute. Verified it fails on drift.
The success line claimed a 'released-docs policy pass' for a check that no
longer exists — the script reads no docs file — while this same release adds
a MANUAL docs-cutover checklist item precisely because nothing automated
covers docs. An operator reading that line would reasonably skip the manual
checks. Now says version files only, and names the manual steps. The two
vestigial echoes left behind by the deleted check are gone.
The failure remedy was also wrong, and wrong in the direction that loops the
operator: it said to re-run update-versions.sh, which derives CURRENT_VERSION
from cmd/bd/version.go (line 70) and substitutes old->new literally. After the
first bump version.go already holds the new version, so a re-run rewrites
new->new and no-ops on exactly the drifted file the gate just named. Verified
empirically — with the copilot manifest and manifest.xml drifted to 1.2.2,
'update-versions.sh 1.3.0' prints 'Bumping: 1.3.0 → 1.3.0' and leaves both at
1.2.2. Only the githooks markers (wholesale regex) and uv.lock (uv lock) heal
on a re-run, and the message now says so and gives the three remedies that
actually work.
shellcheck clean.
* docs(releasing): make the release-branch policy internally consistent
The policy landed in the previous commit but three procedures in the same
files still contradicted it, and the formula implemented the wrong one.
RELEASING.md said 'Nothing is pushed straight to the release branch' and then,
150 lines down, direct-pushed the release branch and minted the tag before the
merge. Two concrete failures: with branch protection the push is rejected
after the tag already exists locally, and with a squash merge the tag points
at a commit that is not an ancestor of release/x.y.z — goreleaser packages
CHANGELOG.md FROM THE TAG into every published archive, so the release ships
the pre-review notes. Both the CHANGELOG-commit block and the bump block now
open a PR, and tagging is a separate step against the merged commit. The
literal 'git push origin main' under the substitution blockquote is gone, as
is the direct push in the docs-pin block.
The formula implemented the wrong order too: commit-release -> create-tag ->
push-main. Reordered to commit-release -> push-main (land the PR) -> create-tag
(on the merged commit) -> push-tag, and create-tag now states why the order
matters.
preflight-pull was untouched by the last commit and still hard-coded main:
divergence recovery was 'git reset --hard origin/main'. Running the molecule on
a release branch and following that destroys the reviewed release-prep commit
and leaves the operator tagging an untested main SHA — precisely the failure
the policy exists to prevent. It now pins the release branch into a variable
first and resets to that; the backup branch moved to Option 1 rather than
Option 3.
'git push origin release/{{version}}' broke every prerelease run: the branch
convention is release/x.y.z, so an RC rendered release/1.3.0-rc.1 and failed
with 'src refspec does not match any', and the forward-port 'git log
main..release/{{version}}' then died on an unknown revision. Now derives the
base version and says why.
The RC workflow still cut tags from the tip of main, which is what the new
policy calls 'a SHA nobody has fully tested' — and worse, an RC exists to
validate the SHA the stable release ships, while the stable tag now comes off
the release branch, so it validated a different SHA by construction. RCs are
now cut on the base version's release branch, and promotion stays on it.
Accuracy fixes in the same pass: verify-versions no longer claims the (now
corrected) 'released-docs policy' string or tells the operator to re-run the
bump — a no-op after the first run, proven in the previous commit — and no
longer prints a prerelease-broken 'grep -c {{version}} winres.json # 4', which
yields 2 for an RC because the numeric PE fields carry the base version. It
now points at check-versions.sh, which gates winres correctly. The 'three
plugin manifests' and 'compares everything else against it' claims are
corrected to match what the script actually reads, and RELEASING.md names
default.nix and README.md as bumped-but-ungated.
go test ./scripts/ and ./test/docsync/ pass; formula still parses and the DAG
is acyclic.
* ci: run PR workflows on release/** branches
Release-targeted PRs currently run almost no CI. pr.yml, pr-risk.yml,
conformance.yml, regression.yml and cross-version-smoke.yml all declare
'pull_request: branches: [ main ]', and every push trigger in the repo is
'branches: [main]' or 'tags: v*'. So a push to release/1.3.0 fires zero
workflows, and a PR based on it gets only the three workflows with no branch
filter (migration-test, nix-build on its paths, docs-mintlify).
That puts the new release-branch policy on a contradiction: it routes the
version bump and 'any fix the release validation turns up' onto a branch where
they land with no unit, lint, conformance or regression coverage, and the
first full signal is the tag build — where a failure burns the tag by this
document's own rule. The policy was written to stop tagging untested SHAs and
was quietly producing them.
Adds release/** to the pull_request branch filter of those five. Push triggers
are deliberately left alone: release branches take changes through PRs, so the
pull_request event is the one that matters, and widening push would double
every run on merge.
cross-version-smoke is the highest-value of the five here — a release-targeted
PR is exactly where cross-version upgrade breakage is most expensive to find
at tag time.
This PR is the vehicle because it targets release/1.3.0, so the new filters
take effect for its own subsequent pushes.
All five files parse; go test ./scripts/ (which includes the workflow lint
tests) passes.
* docs: reconcile the 1.3.0 upgrade notes with the merged release set
Merging origin/release/1.3.0 changed three facts the upgrade notes assert.
Migration count. The merge added ignored/0026_dep_rekey_dedup_marker (#6045),
so the clone-local series now runs 0012 -> 0026, not 0012 -> 0025. Recounted
from the tree: 13 main-series (0054..0066, unchanged) + 15 clone-local = ~28,
not ~27. Corrected in CHANGELOG, cmd/bd/info.go and upgrading.md, including
the trailing line count in the 'counter restarts' explanation.
Shared servers. #6048 (#5920, #5043) means a shared dolt sql-server is no
longer auto-migrated at all — it waits for explicit consent via
'bd migrate schema'. The notes said flatly that 'the first invocation migrates
your schema in place', which is now true only for embedded/local stores and
would have sent a shared-server operator looking for a migration that never
runs. All three copies now scope that claim and point at the new 'Shared
servers' section upgrading.md gained in the same merge. Verified
'bd migrate schema' exists (cmd/bd/migrate.go:848) and that --global is a root
persistent flag (main.go:818), so the cited invocations are real.
#5896. The auto-export entry said #5896 'stays open for embedded mode, where
bd delete still wedges auto-export'. #6059 closed exactly that. Reworded to
point at the store-history heal rather than claiming a live bug.
check-versions.sh 25/25 green, go build ./... clean, go test ./scripts/... and
./test/docsync/ pass, check-cli-docs-drift and check-doc-freshness pass.
* docs(changelog): fold in the proposed changelog lines from the merged 1.3.0 set
Adds the 'proposed changelog' text carried in the bodies of the PRs that
merged into release/1.3.0 after this rollup was first written. Text is the
authors' own; where a body gave it in conventional-commit form rather than as
a bullet, the sentence is preserved and only the 'fix(scope):' prefix dropped
and a bold lead added to match the section.
Changed: #6048 (two bullets — shared-store consent, and the smart gate's
first-mover/fast-forward arms going embedded-only), #6036 (exported packages
marked EXPERIMENTAL), #6053's revision-token bullet, #6049 (migration-test and
upgrade-smoke wisp-plane coverage).
Fixed: #6040 (server-mode lost updates), #6044 (removed-backend rejection),
#6045 (convergent dependency rekey), #6046 (tracked ignored_schema_migrations
heal), #6054 (ignored-cursor floor clamp), #6059 (delete-wedge heal), #6057
(full GC after flatten/compact), #6060 (--storage-class routes), #6061
(journal actor attribution), #6062 (proxied/gateway init errors), and #6053's
two typed-JSON bullets.
Security: new subsection for #6047 (Go 1.26.7 toolchain bump closing seven
reachable stdlib advisories, plus the dependency bumps clearing all 25).
Placed after Fixed per Keep a Changelog ordering.
Documentation: #6052's multi-rig/proxied gate limitation. Its body calls it a
release-notes line rather than a changelog line, so it may want moving.
Contributor credit carried where the PR body gives it: #6040 keeps its
'Reported and fixed by @nova-submodules' sentence, and #6044 gains a note that
its detection helper is ported from @steveyegge's #4740. NOTE: #5064 (aux
row-key encoding drift) carries credit to @marcodelpin in its body but no
proposed changelog line, so it has no entry here — flagging rather than
inventing one.
#6043 was a REPLACEMENT, not an addition: it asked for the existing
MIGRATION-FREEZE bullet to be swapped for vendor-neutral text. Done — the old
bullet named the gt CLI, 'town root' and 'gt migrate thaw'; the new one
describes the generic marker discovery, exit code 14, and the wider set of
maintenance that stands down.
#6055 and #6056 were still OPEN at the time of writing. Their four proposed
lines are included but fenced in a PROVISIONAL HTML comment block that says to
delete it before tagging if either PR does not land.
check-versions.sh 25/25, go build clean, go test ./scripts/... and
./test/docsync/ pass, check-cli-docs-drift and check-doc-freshness pass.
* docs(changelog): credit the three carried contributor fixes
Adds the entries for the merged PRs that carried contributor work but shipped
no proposed changelog line of their own, in the maintainer's supplied wording,
expanded to the surrounding entries' voice.
ATTRIBUTION CORRECTED on #5064. The supplied wording read 'Reported by
@marcodelpin, fixed by @maphew'; the PR body says the opposite. Its '## Credit'
section: 'The fix is @marcodelpin's, from 767d5dcd on their fork... The
diagnosis behind it — the chunk-level characterisation, the negative result on
the minimised fixture, the dolt 2.1.10 re-test, the recover-rows verification —
is theirs too... isSchemaEncodingDriftErr and its table-driven test come from
that commit.' @maphew (the PR author) absorbed it with a review-requested
semantic rework. Written as 'Diagnosis and fix by @marcodelpin, carried and
reworked by @maphew' so the contributor is not demoted to reporter of a bug
they also fixed.
Scope corrected on the same entry. The supplied wording reads as new behavior,
but git grep against the v1.1.2 tag finds both isSchemaEncodingDriftErr and
aux_row_rekey_drifted already present in internal/storage/schema/
aux_row_id_backfill.go — v1.2.2 is the v1.1.2 tree, so v1.2.2 users already
have this fix, and it is already documented under [1.1.2]. #5064 carries it
onto the main line. The entry says so, so a v1.2.2 reader does not conclude
they were exposed and go looking for a migration that does not concern them.
#5783 and #6037 verified against their PR bodies before writing; both supplied
claims hold. #5783: Config.LenientOpen reached server mode but newServerMode
never read it and the field's doc comment said 'Ignored in server mode', so the
dirty-table refusal's own recovery command could not run — and server mode has
no 'move the directory aside and re-bootstrap' alternative. #6037: bd init
persists a git-origin-derived sync.remote into the tracked config by design,
bootstrap rejected exactly that shape before the origin auto-detect, and
Action=='none' conflated 'already exists' with 'refused', printing a success
tick and exiting 0 having created nothing.
Also notes in the PROVISIONAL fence that the RC is gated on #6055/#6056
merging, so the fence comes off at RC-prep time rather than being an open
question.
check-versions.sh 25/25, go test ./test/docsync/ passes.
* fix(release): create release-prep branch before pushing it
The new release-branch/prep-PR flow pushed `release-prep/v<version>`
without ever creating that branch, so `push-main` (and the RELEASING.md
runbook) failed on first run with
`error: src refspec release-prep/v<version> does not match any`.
Add `git checkout -b` before each prep-branch push — the formula
`push-main` step and both RELEASING.md landing snippets — so the branch
exists before it is pushed, mirroring the existing `REL_BRANCH` guard in
the same step.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
RELEASING.md said the generated CLI reference is kept fresh by the PR
drift gate, "not by the release process" — but docs/cli-docs.pin (the
release-tag pin the whole docs corpus is generated from and validated
against) is only ever bumped at release time, and nothing in the release
checklist said so. Between bumps, check-doc-flags.sh Check 4 validates
against the stale pinned bd, so any command added on main since the last
bump (e.g. `bd sync`, wy-jpd3.4) is invisible to it and the "covers all
live top-level CLI commands" check passes vacuously instead of catching
the gap.
Add the bump + regenerate as an explicit step under "Documentation Site
(Mintlify)", and a pin-freshness check under "Verify Release", so this is
a known, checked release step instead of a surprise pile of "missing from
docs/CLI_REFERENCE.md" failures whenever the pin finally catches up.
- beads-release formula: drop the snapshot-docs step (ran the deleted
scripts/snapshot-release-docs.sh on the critical needs-chain); stamp-
changelog now needs update-vendorhash
- update-versions.sh: remove the mangled --skip-docs/docs-snapshot logic
and garbled usage text left by mid-line deletions
- pre-push hook: drop the snapshot-script remediation hint
- release.yml: collapse the prerelease branch; BEADS_REQUIRE_RELEASE_DOCS
has no consumer since check-docs-version.sh was deleted
- RELEASING.md / scripts/docs.md: describe the current pipeline (no
--versioned, no website/ outputs, no check-docs-version.sh)
- docs-mintlify.yml: paths filter now includes engdocs/** and the curated
root markdown files the docsync guard validates
- docs-render-check.sh: pin mint@4.2.687, fail closed when mint dies
without producing a broken-links report, parse report lines only, drop
dead extract_page_links(), fix the stale jq requirement; mint.sh pins
the same version
- nightly.yml: remove the deleted website measurement suite option
- CODEOWNERS: init-safety ADR gate follows the file to engdocs/adr/
- beads-docs skill: align with settled decision 6 — no pointer stubs,
moved pages get docs.json redirects; bd's printed paths are fixed at
the source
- CHANGELOG (edited line), FEDERATION-SETUP, README, examples, oracle-a,
.buildflags, gh-issue-to-pr formula: retarget moved-file references;
anchor the build/ gitignore pattern
Per the decision record: no parallel run and no cutover PR. Removes
website/ (including the four versioned doc snapshots — current-only
versioning; snapshots remain in git history), deploy-docs.yml,
generate-llms-full.sh (Mintlify serves llms.txt natively), the ci-website
package gate (Makefile target, scripts/ci/website.sh, the package-website
jobs and their aggregate-gate entries in pr.yml/main.yml/release.yml, the
ci-measurements suite, detect-package-gates wiring), and the release-time
docs snapshot flow (snapshot-release-docs.sh, check-docs-version.sh, their
call sites in update-versions.sh/check-versions.sh, RELEASING.md section
rewritten for the Mintlify reality).
Drift machinery now covers exactly the Mintlify artifacts:
check-cli-docs-drift.sh pathspecs/fingerprint, docs-autofix-push.sh
allowlist, and check-doc-flags.sh scans drop the website/llms paths. The
beads-docs skill's generated-content and verification sections updated to
the bd-generic + docsmint pipeline.
NOTE for merge time: if branch protection requires the 'Package Gate
(website)' check by name (rather than the aggregate gate), drop it from
the required checks or PRs will wait forever.
Gates: docsync PASS, generate-cli-docs.sh --check PASS, freshness PASS.
Relocate contributor- and maintainer-facing material out of docs/ so the
directory can become the user-facing Mintlify site. Moves preserve subpaths
(adr/, design/, staged-for-removal/ intact). messaging.md, UI_PHILOSOPHY.md,
and AGENT_SIGNING.md move per their DOC_INVENTORY dispositions (design doc,
design philosophy, maintainer convention).
Inbound links updated repo-wide: root guides, CONTRIBUTING, AGENTS,
workflows, lint config, scripts (check-doc-freshness now resolves the
inventory at engdocs/DOC_INVENTORY.md), Go comments, and the synced website
metadata page (regenerated via sync-website-docs.sh + generate-llms-full.sh).
The emitted help text in cmd/bd/init_safety_help.go still references
docs/adr/0002-init-safety-invariants.md; changing it would change bd's
runtime output, which is out of scope for this branch (flagged in the PR).
Re-lands the v1.1.0-rc.1 release prep so the candidate can be reviewed before
the tag is cut (#4476 auto-merged the original prep; #4477 backed it out).
Restores v1.1.0-rc.1 version metadata across all package manifests, the
prerelease-aware release workflow and version scripts (prerelease tags skip the
stable docs-snapshot requirement and stay off the stable Homebrew/PyPI/npm
channels), the CHANGELOG and cmd/bd/info.go entries, and regenerates uv.lock to
1.1.0rc1.
Beyond the straight re-land:
- fix(release): match the winres/manifest numeric PE versions on the base
version in update-versions.sh, so a later prerelease-to-different-base bump
does not silently leave them stale.
- docs(release): document the prerelease / release-candidate workflow in
RELEASING.md.
Agent-Signature: claude-opus-4-8-xhigh on behalf of matt wilkie
* Retire legacy Homebrew tap publishing
Stop the release workflow from publishing the independent bd tap formula, and document Homebrew core beads as the supported Homebrew package with migration commands for legacy tap users.
Agent-Signature: codex-gpt-5.5-medium on behalf of matt wilkie
* Sync beads-mcp uv.lock with pyproject version
CI Package Gate (MCP) fails on `uv sync --all-groups --locked` because
integrations/beads-mcp/uv.lock still pins the editable package at 1.0.5
while pyproject.toml declares 1.1.0-rc.1. This drift exists on
upstream/main itself, not from this branch (PR #4478 only retires the
legacy Homebrew tap and touches no MCP package files), so the branch is
already on top of the latest upstream/main and a rebase cannot resolve it.
Regenerate the lockfile with `uv lock`. The only change is the package's
own version (1.0.5 -> 1.1.0rc1); no dependency versions change.
Agent-Signature: claude-opus-4-8-high on behalf of matt wilkie
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Main already converted docs/DOLT-BACKEND.md and docs/RELEASING.md into canonical pointer stubs. Finish the consolidation by moving the still-useful verified details into the authoritative docs and fixing stale inbound references that still sent readers to the pointer files.
DOLT.md keeps the server-mode Dolt install notes, remote setup guidance, macOS LaunchAgent setup, direct Dolt CLI usage, accidental data-directory commit cleanup, and the embedded-mode data path correction.
RELEASING.md keeps the release.sh easy path and Docusaurus versioning steps from the retired docs-level guide. AGENT_INSTRUCTIONS.md now links directly to the root releasing guide, and the init error path now links to the canonical Dolt guide under gastownhall/beads.
Refs: GH#3683, PR#3706
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
_codex-gpt-5.5-medium on behalf of matt wilkie_
- Add docs/RELEASE-STABILITY-GATE.md defining the upgrade matrix,
verification criteria, and sign-off process
- Add scripts/upgrade-smoke-test.sh that tests data preservation,
mode preservation, role preservation, and doctor health across
upgrade scenarios (embedded maintainer, contributor, mode flip)
- Add 'make test-upgrade' target
- Update RELEASING.md checklist with upgrade smoke tests, regression
tests, and breaking-change documentation requirements
- Links to #2764, #2765, #2949, #2950 for related test gap work
Amp-Thread-ID: https://ampcode.com/threads/T-019d4a99-63c8-779f-bb8e-ee8522b61cdf
Co-authored-by: Amp <amp@ampcode.com>
The Homebrew formula is named "beads" (not "bd"), so all brew commands
must use `brew install beads` / `brew upgrade beads`. Also removes the
dead update-homebrew job from release.yml — homebrew-core handles
formula updates automatically.
Follows up on #1557 which fixed the Go code in bd doctor.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat: update to use core tap for beads installation
Signed-off-by: Rui Chen <rui@chenrui.dev>
* remove custom tap related code and refs
Signed-off-by: Rui Chen <rui@chenrui.dev>
---------
Signed-off-by: Rui Chen <rui@chenrui.dev>
Update documentation and scripts to reflect the plugin move from
root level to claude-plugin/ subdirectory:
- Fix command links in docs/DAEMON.md, docs/SYNC.md, examples/
- Update plugin.json path references in RELEASING.md, AGENT_INSTRUCTIONS.md
- Update scripts/bump-version.sh and scripts/check-versions.sh
- Update skill documentation paths in claude-plugin/skills/beads/
The marketplace.json correctly stays at .claude-plugin/ (root level)
while plugin.json moved to claude-plugin/.claude-plugin/.
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Improves the version bump workflow with missing local installation steps:
- --install: Now installs bd to BOTH ~/go/bin AND ~/.local/bin
- --mcp-local: Install beads-mcp from local source via uv/pip
- --restart-daemons: Restart all bd daemons to pick up new version
- --all: Shorthand for --install --mcp-local --restart-daemons
Also updated RELEASING.md with flag documentation and recommended workflow.
Closes bd-of2p
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Adds automatic beads-mcp upgrade during version bumps
- Tries pip first, falls back to uv tool
- Warns if version mismatch (normal before PyPI publish)
- Updates RELEASING.md Post-Release section with usage
- Adds reminders in 'Next steps' output if not used
This addresses confusion where version bump doesn't trigger release.
The script now supports:
- --commit: Create git commit
- --tag: Create annotated git tag (requires --commit)
- --push: Push commit and tag (requires --tag)
Updated RELEASING.md to use: ./scripts/bump-version.sh X.Y.Z --commit --tag --push
Fixes the gap between version bump and actual release trigger.
Integration Tests:
- Comprehensive test suite covering all major functionality
- 5 test scenarios: installation, binary functionality, workflow,
Claude Code for Web simulation, platform detection
- Tests JSONL import/export across sessions
- Tests all major commands (init, create, list, show, update, close, ready)
- All tests passing ✅
Testing Documentation:
- TESTING.md with complete test documentation
- Describes unit vs integration tests
- Manual testing scenarios
- CI/CD recommendations
- Troubleshooting guide
Release Documentation:
- RELEASING.md with comprehensive release process
- Covers all distribution channels: GitHub, Homebrew, PyPI, npm
- Step-by-step instructions for each channel
- Version numbering and release cadence
- Hotfix and rollback procedures
- Automation opportunities with GitHub Actions
npm Package Updates:
- Added test:integration and test:all scripts
- Integration tests validate real-world usage patterns
- Tests simulate Claude Code for Web SessionStart hooks
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Move RELEASING.md and LINTING.md to docs/ (maintainer-only content)
- Delete WORKFLOW.md (agent workflow content belongs in AGENTS.md)
- Delete TEXT_FORMATS.md (technical details belong in ADVANCED.md)
- Update all cross-references to point to new locations
- Keep CLAUDE.md (required by Claude Code)
Reduces root-level docs from 20 to 16 files with clearer organization.
Amp-Thread-ID: https://ampcode.com/threads/T-fe1db4f3-16c6-4a79-8887-c7f4c1f11c43
Co-authored-by: Amp <amp@ampcode.com>
Issues fixed:
- Added explicit rebuild step after version bump (source changes but binary doesn't)
- Clarified Homebrew formula update must happen AFTER tag push
- Added git pull step for /tmp/homebrew-beads to avoid stale repo
- Made it clear users won't get new version until Homebrew formula is updated
- Removed redundant git config steps (already configured in cloned repo)
- Add .goreleaser.yml for automated releases
- Add .github/workflows/release.yml triggered on version tags
- Build matrix: darwin/linux/windows for amd64/arm64
- Update install.sh to download from GitHub releases first
- Add install.sh symlink at root for convenience
- Update RELEASING.md with automation documentation
Closes#89 (vendorable executables as releases)
Implements bd-85
Amp-Thread-ID: https://ampcode.com/threads/T-02baad43-7e97-4710-bc60-777643d2eb77
Co-authored-by: Amp <amp@ampcode.com>
- Add daemon kill step before build/test
- Add local Go install update step
- Add TMPDIR=/tmp to all go commands
- Update Homebrew install instructions with --build-from-source
- Add git config setup for homebrew-beads repo