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>
* security: pin build toolchain to go1.26.7
go1.26.5 carries 8 stdlib advisories, 7 of them reachable from the shipped
bd binary. Verified with govulncheck in call-graph mode against ./cmd/bd,
toolchain pinned so the analysis cannot drift:
GO-2026-6218 net/url quadratic resolvePath
GO-2026-6091 html/template JS-regexp context tracking
GO-2026-6090 crypto/tls post-handshake message flood
GO-2026-6089 net/http ReadHeaderTimeout on the h2c check
GO-2026-6088 encoding/xml recursion depth
GO-2026-5972 encoding/asn1 recursion depth
GO-2026-5026 net/http vendored x/net/idna punycode
GO-2026-5942 net dnsmessage SVCB/HTTPS RR (linked, uncalled)
`bd serve` is a real HTTP server and bd makes TLS client connections, so
these are live paths rather than dead weight: httpapi.Serve reaches four of
them directly. go1.26.6 fixes all eight; 1.26.7 adds one more net/http fix.
After the bump the same scan reports zero.
The `go` directive stays at 1.26.5 so importers of the module keep their
current floor; `toolchain` is what we actually build with. release.yml
builds the shipped binaries with a bare `go build` under the default
GOTOOLCHAIN=auto, which honors the toolchain line.
The Makefile needed the second half of this. It pinned GOTOOLCHAIN from the
`go` directive, which is the importer floor, not the build version - left
alone it would have held every make target (the test suite, the npm and MCP
package gates, local `make build`) at 1.26.5 while the release binaries
moved to 1.26.7, which is both a silent downgrade and a split between what
CI tests and what we ship. It now reads `toolchain` first and falls back to
`go` when there is no toolchain directive, preserving the original reason
for pinning: one exact version so the compile tools and coverage
instrumentation cannot disagree.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* security: bump x/crypto, x/mod, klauspost/compress, moby/go-archive
Four advisories, none reachable from the shipped bd binary; these are
hygiene bumps that also clear the Dependabot board.
golang.org/x/crypto v0.54.0 -> v0.55.0 GO-2026-6303
golang.org/x/mod v0.37.0 -> v0.40.0 GO-2026-6179/6180
github.com/klauspost/compress v1.18.5 -> v1.18.7 GO-2026-5841
github.com/moby/go-archive v0.2.0 -> v0.3.3 CVE-2026-17106 (#140)
Reachability, from `go list -deps ./cmd/bd` plus govulncheck call-graph mode:
x/crypto/ssh proper enters only through testcontainers (test-only); the
compress advisory is in the s2 codec, which is not linked into bd at all
(bd links zstd/gzip/flate/huff0 via dolt); the x/mod sumdb/tlog code is
required but never called; go-archive is testcontainers-only and absent
from the binary's package graph entirely.
go-archive goes to v0.3.3, not the advisory's minimum v0.3.0: v0.3.0's
hardened extraction rejected absolute symlinks and hardlinks and broke
device nodes and implied directories, all fixed across v0.3.1-v0.3.3.
MVS carries x/net, x/text, x/tools and x/telemetry along. No replace
directives, and the dolt pin is untouched - dolt requires older versions of
all three x/ modules, so beads' go.mod already wins the version selection.
The examples/ modules reach the parent through a `replace` directive, so
their recorded graph goes stale on any root go.mod change and both failed
scripts/build-examples.sh with the documented "updates to go.mod needed".
Re-tidied here rather than left for the advisory job to warn about; the
diff is purely the mirror of the bumps above.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* security: bump oapi-codegen to v2.7.1 and kin-openapi to v0.144.0
Clears the board's one critical (#133, GHSA-r277-6w6q-xmqw, CVSS 9.1) plus
#142, #141, #134 and the low #132. All five are codegen-tool-only:
kin-openapi reaches the module graph solely through the go.mod `tool`
directive for oapi-codegen, no beads source file imports kin-openapi,
oapi-codegen or openapi3filter, and `go list -deps ./cmd/bd` contains none
of them. The critical is a fail-open bug in openapi3filter's
ValidationHandler.Load(), middleware this repo never runs - request
validation in internal/httpapi is hand-rolled. Dependabot scopes the alert
"runtime" because it cannot model Go tool-directive semantics.
Both must move together: oapi-codegen v2.6.0 does not compile against
kin-openapi v0.144.0 (pkg/codegen/schema.go:909, openapi3.MappingRef vs
string). v2.7.1 is the minimum-fix pair, chosen over the latest 2.8.0/0.149.0
to keep codegen churn off a release branch.
The `make api-gen` regen diff is two lines of real change: the generated
BearerTokenScopes constant picks up a generated named context-key type
instead of being an untyped string. The identifier has no references outside
types.gen.go. `make api-check` is green - regeneration is idempotent,
pinning.go's compile-time welds hold, and TestWireTagBijection passes.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* security: refresh beads-mcp uv.lock (clears all 19 pip alerts)
`uv lock --upgrade` with fastmcp still pinned ==3.4.5. Every one of the 19
Dependabot alerts on integrations/beads-mcp/uv.lock is a fastmcp transitive,
and each lands at or above its first-patched version:
mcp 1.25.0 -> 1.29.1 #129#128#127 (high)
cryptography 48.0.0 -> 50.0.1 #137#138#82#139
pyjwt 2.12.1 -> 2.13.0 #79#136#81#78#135
joserfc 1.6.5 -> 1.7.4 #113#109
python-multipart 0.0.27 -> 0.0.32 #88#87#86#85
idna 3.11 -> 3.19 #68
Real exposure was already low: beads-mcp runs stdio transport only
(server.py's mcp.run_async(transport="stdio")), so the three high mcp-SDK
alerts - WebSocket Host/Origin validation, HTTP session principal handling,
task-handler cross-access - are all HTTP/WS-transport bugs this server never
reaches, and the auth libraries ride along with fastmcp's extras rather than
being used by beads-mcp's own code. The lock governs dev and CI installs;
PyPI users resolve fresh and already get patched versions.
mcp 1.25 -> 1.29 is the only behaviorally interesting jump. The full package
gate is green: uv sync --locked, ruff, mypy, 228 passed / 5 skipped, uv build.
The resolved lock is byte-identical under uv 0.9.5 and CI's uv 0.11.16.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore(nix): update vendorHash for go.sum changes
The go.mod/go.sum bumps in this branch invalidate the proxyVendor
fixed-output hash in default.nix, which fails the nix-build gate. The
workflow that repairs this automatically only fires for dependabot PRs
targeting main, so it does not cover this branch.
Recomputed with scripts/update-nix-vendorhash.sh's flow and verified:
`nix build .#default` completes green, which also confirms the new
`toolchain go1.26.7` directive is compatible with default.nix's
GOTOOLCHAIN = "local".
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* fix(examples): tidy both example modules and build them in CI
Both Go modules under examples/ fail a plain `go build` on current main:
go: updates to go.mod needed; to update it:
go mod tidy
They are separate modules that reach the parent through
`replace github.com/steveyegge/beads => ../..`, so their go.mod and go.sum
record the parent's entire dependency graph. Every root dependency change
therefore invalidates them — and nothing in CI ever compiled them, so the drift
accumulated silently. examples/ is the first code a new user copies, which makes
this a bad first five minutes rather than a cosmetic wart.
Two parts:
1. `go mod tidy` in examples/bd-example-extension-go and examples/library-usage.
The extension example carries most of the churn (~1.6k lines of go.sum),
which is inherent to recording the parent graph through the replace directive
and is why an earlier fix (#4942, the Go 1.26.5 bump) deliberately left it
out. Both modules now build clean with the project's canonical
`-tags gms_pure_go`.
2. scripts/build-examples.sh plus a `build-examples` job in the PR workflow, so
the same drift cannot recur unnoticed. The script discovers example modules
from `git ls-files 'examples/*/go.mod'` (no hardcoded list), sources
.buildflags for the canonical CGO/tag settings, builds into a scratch
directory so it leaves no untracked binaries, reports every failing module
rather than stopping at the first, and prints the exact `go mod tidy`
command to run.
The job is deliberately NOT added to ci-gate's required list. Because of the
replace directive it would fail on any root go.mod change not mirrored into the
examples, so making it blocking imposes a "tidy the examples too" step on every
dependency bump. That is a maintainer call about contributor friction; the job
is visible on the checks list either way, and pr.yml records how to promote it.
Verified locally: both modules build with -tags gms_pure_go; the script exits 1
and names the module when an example go.mod is reverted to its pre-tidy state;
scripts/check-build-tags.sh stays clean (the script sources .buildflags).
Agent-Signature: claude-opus-5-high on behalf of matt wilkie
* fix(examples): address dual-vendor review — vet not build, advisory job, portability
Reviewed by a claude reviewer and scripts/codex-agent reviewer (gpt-5.6-sol).
Four fixes, two of them correctness.
1. `go build -o <dir>/ ./...` was a FALSE GREEN: with -o naming a directory, Go
compiles only the MAIN packages and silently skips every library package.
Reproduced in an isolated module with a good main package plus a library
package containing a type error — `go build -o dir/ ./...` exits 0 while
`go build ./...` and `go vet ./...` both exit 1. The mirror-image bug: a
library-only example module fails `go build` with "no main packages to
build", a false red. Switched to `go vet ./...`, which type-checks every
package INCLUDING test files (examples/library-usage/main_test.go exercises
a lot of live API, and `go mod tidy` counts its imports, so a build that
never compiles it left part of the recorded graph unverified), writes no
artifacts, and still fails on the stale-go.mod condition this exists for.
That also deletes the mktemp/trap/scratch-dir machinery entirely.
2. "Not in ci-gate" is NOT "non-blocking", which the previous comment claimed.
Verified in source: pr-preflight.sh gates on every FAILURE in the raw
statusCheckRollup and calls block(), and pr-babysit requires all rollup
entries SUCCESS/NEUTRAL/SKIPPED before merging. Both ignore ci-gate
membership. So the previous state was the one posture that stalls the merge
patrol repo-wide after any un-mirrored dependency bump while advertising
itself as optional. The job is now continue-on-error: true — genuinely
advisory — and the comment records how to promote it to a real gate. Whether
it SHOULD be a gate remains the maintainers' call.
3. Portability and robustness in the script, all reproduced by the reviewers:
- `mapfile` does not exist in bash 3.2 (stock macOS) and `xargs -r` is
GNU-only, so the advertised local check could not run on macOS. Replaced
with a NUL-delimited read loop, which also fixes module paths containing
whitespace (`git ls-files | xargs -n1 dirname` turned "examples/has
space/go.mod" into two bogus entries).
- `source ./.buildflags` was unguarded under `set -uo pipefail`; a failure
continued with GOFLAGS unset and would type-check the ICU path while
check-build-tags.sh still passed, since that only greps for the literal
string. Now a hard exit.
- Finding zero modules exited 0. A job that checks nothing must not report
success; it is now an error.
Verified: both modules vet clean; reverting an example go.mod to its pre-tidy
state still exits 1 with the exact `go mod tidy` command; a broken library
package now fails where it previously passed; check-build-tags.sh clean
(97 files); shellcheck clean.
Agent-Signature: claude-opus-5-high on behalf of matt wilkie
* fix(examples): drop GNU-only sort -z from the module discovery pipeline
BSD sort has no -z, so on stock macOS — the exact platform the Bash-3.2
compatibility block targets — the sort stage emptied the pipeline and the
script exited claiming 'found no example modules'. git ls-files output is
already sorted, so the stage bought nothing. Found by cross-vendor review
(codex gpt-5.6-sol) of this branch.
Agent-Signature: claude-fable-5-high on behalf of maphew
* fix(ci,examples): disable setup-go cache in build-examples; re-tidy examples after merge
TestGoCacheOwnershipTopology requires every setup-go step in pr.yml to set
cache: false (caching is owned by explicit restore/save steps); the new
build-examples job predates that policy landing on main. Also re-run
go mod tidy in both example modules so their recorded dependency graphs
match the merged main — exactly the drift this PR's CI job exists to catch.
Agent-Signature: claude-fable-5-high on behalf of maphew
* ci(examples): bound build-examples with timeout-minutes: 10
continue-on-error keeps a red result advisory, but a hung job at the
6-hour default timeout holds the check pending, stalling merge-lane
consumers the advisory posture was meant to protect. Matches
pr-preflight-platforms' bound.
Agent-Signature: claude-fable-5-high on behalf of maphew
* ci(examples): make the advisory posture real - step-level continue-on-error
Job-level continue-on-error still reports the check run as FAILURE in the
PR rollup (only the workflow-run conclusion flips), and pr-preflight /
pr-babysit gate on per-check-run conclusions - so the job as written was
de facto blocking while advertising itself advisory. Follow the cygwin-leg
precedent: continue-on-error on the build step, outcome-guarded ::warning
annotation on failure. Also restore the repo-wide Go module cache (the
examples' graph is the parent's via the replace directive) so the job
stops cold-downloading the full dependency graph on every PR.
Agent-Signature: claude-fable-5-high on behalf of maphew
* test: register build-examples' module-cache restore in the cache topology registry
TestGoCacheOwnershipTopology keeps an explicit inventory of every cache
step per job; the advisory-lane fix added a restore step to build-examples
without registering it, so the whole scripts package went red on this
head. Register the job (inventory, managed map, ordering, setup-go id)
and drop the step's unused 'restore-cache' id — the registry compares
ids, and nothing references it.
Agent-Signature: claude-fable-5-high on behalf of maphew
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019CwiLhLbAGZdJtKYT76CPp
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Callers that need ready work across several statuses (e.g. Gas City's
native store Ready(), which spans open/blocked/deferred/pinned/hooked/
review/testing) currently issue one GetReadyWork per status. Each call
re-pays the deferred-parents pre-query, the wisps arm, and the
per-transaction round trips — measured at 30-70ms per call on a live
server-mode store, ~7x per Ready().
WorkFilter.Statuses (OR semantics) renders a single status IN (...)
clause through BuildReadyWorkWhere and propagates to the wisp-side
IssueFilter.Statuses, so multi-status callers pay the fixed per-call
work once. Singular Status keeps precedence; both empty keeps the
legacy ('open', 'in_progress') default.
Review round 2: a conformance audit case (ReadyMultiStatusFilter) pins
the contract at the result level against both backends — real issues
and wisps across several statuses, OR semantics in one call, singular-
Status precedence, the empty default, a custom status through the same
IN clause, and the ephemeral exclusion of wisps without
IncludeEphemeral. The library guide documents Statuses, and
BuildReadyWorkWhere computes the status clause and args in one pass.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(stats): add --no-blocked flag; fix Blocked:0 red render (be-nnqp, be-4b63)
- types.go: BlockedIssues int → *int (nil when --no-blocked skips computation)
- storage: add FastStatisticsStore interface + GetStatisticsNoBlocked to DoltStorage;
implement in DoltStore and EmbeddedDoltStore (ScanIssueCountsInTx only, no blocked traversal)
- status.go: --no-blocked flag (no short alias), BlockedCountSkipped bool in StatusOutput;
fast path calls GetStatisticsNoBlocked; human output renders "(skipped)" in muted style
- be-4b63: Blocked:0 now renders plain text; only Blocked:N>0 uses RenderFail (red)
- nil-guard BlockedIssues callers: getAssignedStatistics, status_test.go, queries_test.go,
examples/library-usage/main.go
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(cli): regen CLI reference for `bd status --no-blocked`
Regenerates docs/CLI_REFERENCE.md and the website CLI reference pages
(`website/docs/cli-reference/status.md` and the version-1.0.0 / 1.0.4
snapshots) from the live `bd help` output so the doc-flags freshness
check passes.
Picks up the new `--no-blocked` flag, the updated `--no-activity`
description ("Skip git activity summary"), and the matching example
lines added in ddf53438c.
Fixes the CI "Check doc flags freshness" failure on PR #4022.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* chore: release gate PASS for be-nnqp+be-4b63 (bd stats --no-blocked)
* fix(stats): ReadyIssues *int, data-derived skip render, proxied-server warning
Address the adjudicated cross-vendor review on PR #4022:
- internal/types.Statistics.ReadyIssues is now *int, mirroring BlockedIssues:
nil when --no-blocked skips the computation (readiness needs the blocked
set), populated by all three backends' full GetStatistics, by
issueops.GetStatisticsInTx, and by buildAssignedStats. Left nil only in
the *NoBlocked fast-path variants. JSON now emits `"ready_issues": null`
instead of a fake 0 a CI consumer could misread as "nothing ready".
- renderStatus derives "(skipped)" rendering from the data itself
(stats.BlockedIssues/ReadyIssues == nil) instead of the noBlocked flag,
fixing the --assigned + --no-blocked contradiction where fully-recomputed
stats were mislabeled as skipped. The noBlocked parameter is gone from
renderStatus entirely; both call sites (status.go, status_proxied_server.go)
simplified accordingly.
- Proxied-server mode now prints a one-line stderr warning when --no-blocked
is passed but not honored, instead of silently discarding the flag; the
flag's help string documents the limitation.
Agent-Signature: claude-sonnet-medium on behalf of maphew
* test(stats): cover GetStatisticsNoBlocked nil semantics and renderStatus skip branch
- internal/storage/dolt: new TestGetStatisticsNoBlocked_LeavesBlockedAndReadyNil
asserts the --no-blocked fast path leaves BlockedIssues/ReadyIssues nil
while the full GetStatistics path on the same store populates both.
- cmd/bd: new TestGetStatisticsNoBlocked (storage-level, same assertion via
the CLI-facing store handle), TestRenderStatus_SkipJSONEmitsNullNotZero
(asserts blocked_count_skipped:true plus literal `"blocked_issues": null`
/ `"ready_issues": null` in the JSON envelope),
TestRenderStatus_SkipHumanRendersSkippedNotZero (asserts the "(skipped)"
human branch renders for both fields), and
TestRenderStatus_AssignedIgnoresSkipEvenWithNoBlockedFlag (guards the
--assigned + --no-blocked fix: fully-populated stats never render
"(skipped)").
- Update existing statistics assertions in
internal/storage/conformance/audit_search-counts-stats.go,
internal/storage/dolt/queries_test.go, and
internal/storage/domain/db/ready_helpers*_test.go for
ReadyIssues's int -> *int change.
Agent-Signature: claude-sonnet-medium on behalf of maphew
* docs(cli): drop --no-blocked doc lines from CLI_REFERENCE.md/status.md (pinned-generator policy)
CI's "Check doc flags freshness" job builds bd from the release pin in
docs/cli-docs.pin (currently v1.1.0) to regenerate docs/CLI_REFERENCE.md
and docs/cli-reference/status.md, not from this branch's HEAD. v1.1.0
predates --no-blocked entirely, so the pinned generator's output omits
every --no-blocked reference (use case bullet, both example lines, the
flag description) and also reverts the --no-activity flag description
wording, flagging both files as stale relative to it. Same trap PR #3920
hit for --mem-profile.
Applied the exact patch CI generated and uploaded as the
cli-docs-freshness-patch artifact on the failing job
(run 30063539327 / job 89390739992) verbatim to both files; the lines
will reappear automatically once the pin advances past a release that
includes --no-blocked.
Agent-Signature: claude-sonnet-medium on behalf of maphew
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
* /{engdocs,examples,go.mod}: bump go version
* deps: bump golang.org/x/text to v0.39.0 (GO-2026-5970)
govulncheck against today's vuln DB flags GO-2026-5970 (infinite loop on
invalid input in x/text, reachable via internal/routing), published after
this PR's original clean scan. Bump x/text to the fixed v0.39.0 (with its
MVS sibling x/* minimums) and re-tidy examples/library-usage, which
builds against the parent via a replace directive and would otherwise
fail with missing go.sum entries.
examples/bd-example-extension-go is left untouched: it already fails
'go build' (needs go mod tidy) at the PR's base state, so its tidy is
pre-existing follow-up work, not fallout from this bump.
Verified: CGO_ENABLED=0 go build -tags gms_pure_go ./cmd/bd; both
example modules build; go test ./internal/routing; govulncheck now
reports 0 affecting vulnerabilities.
Agent-Signature: claude-fable-5-high on behalf of maphew
---------
Co-authored-by: matt wilkie <maphew@gmail.com>
* feat(metadata): MergeMetadata — atomic single-key metadata merge
SlotSet did a read-modify-write across TWO transactions: GetIssue (tx 1),
metadata[key]=value in memory, then UpdateIssue (tx 2). Two concurrent SlotSet
calls — even on DIFFERENT keys — both read the same base metadata and each
wrote back its whole blob, so the second clobbered the first's key. SlotClear
had the same bug. Add MergeMetadata, which does the read-modify-write inside
ONE transaction (so a concurrent conflict is retried and re-reads), stores a
JSON value (nested objects/arrays, not just strings), and reimplement SlotSet
and SlotClear on top of it so they inherit the atomicity.
- issueops.MergeMetadataInTx / DeleteMetadataInTx: read the metadata (routed
issues/wisps; missing issue -> ErrNotFound), merge/delete the one key, and
write the whole object back THROUGH UpdateIssueInTx — so the operation keeps
everything the old SlotSet got from UpdateIssue (the EventUpdated history
event with actor attribution, the configured metadata-schema validation, and
updated_at), now atomic. The read and write share the caller's transaction,
so a concurrent merge of a different key is retried and re-read, never
clobbered.
- Storage.MergeMetadata implemented on DoltStore (perm withRetryTx +
DOLT_ADD(issues,events) + DOLT_COMMIT; wisp path no commit) and
EmbeddedDoltStore (withConn); forwarded on InstrumentedStorage; auto-promoted
on HookFiringStore; no-op on the configStore mock. SlotSet/SlotClear rebuilt
on it (a string value marshals to a JSON string, byte-compatible with the
historical rewrite).
- Cross-backend conformance covers MergeMetadata + atomic SlotClear; the
8-goroutine concurrent-no-clobber test proves the B1 fix on real Dolt, and
a test asserts the EventUpdated event and schema validation are preserved.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(concurrency): expose a per-row version on Issue reads (RowVersion)
The engine's internal row_lock column — a random non-zero int64 the engine
rewrites on every status/ownership-mutating write and on the generic update
path — was not surfaced on the public types.Issue. Consumers that wanted a
fine-grained optimistic-concurrency token had only updated_at, which is stored
at second granularity, so two same-second writes were indistinguishable. Expose
row_lock read-only as types.Issue.RowVersion so a caller can tell same-second
writes apart.
- types.Issue gains RowVersion int64 (json:"-": a Go-only concurrency token,
never on the CLI/export JSON wire — it is opaque and equality-only). Added
row_lock to the canonical sqlbuild.IssueBaseColumns and a matching scan target
in issueops.ScanIssueFrom; both engine write stacks, wisps, and the counts /
dependents parallel scans share those, so the field hydrates everywhere from a
single-point change. Read-only — no CAS/write behavior (that is a follow-up).
- Doc is precise about coverage: RowVersion changes on claim/close/unclaim and
the generic update path; it does NOT change on some direct-UPDATE paths
(restore, compaction text), which bump updated_at — so a complete change key
combines RowVersion with updated_at, status, and labels. A created row is
already non-zero (create stamps row_lock); 0 only appears on legacy rows
backfilled by migration 0054's DEFAULT 0.
- Tests: RowVersion hydrates on read and on the list path, changes on a mutating
write, distinguishes two same-second writes (identical updated_at, distinct
RowVersion), and never appears on any JSON surface.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(deps): return a typed error on dependency type-conflict
Adding a dependency between a pair that already has an edge of a different type
is a deterministic rejection, but the two engine write paths disagreed on how
they surfaced it: one returned a typed *DependencyTypeConflictError, the other a
plain fmt.Errorf string. So a caller could errors.As the conflict on one path
but had to string-match the message on the other. Make both paths return the
same typed error, and re-export the two dependency-conflict types on the public
beads package so `bd` (and the library's own call sites) classify by errors.As
instead of parsing message text.
- issueops.AddDependencyInTx now returns *domain.DependencyTypeConflictError for
the type-conflict case (byte-identical message — the struct's Error() is the
exact former string, so no string-matcher changes). The hierarchy/cross-type
case already returned *domain.DependencyHierarchyConflictError on both paths;
self-dependency and cycle are already typed sentinels.
- beads.go re-exports DependencyTypeConflictError and
DependencyHierarchyConflictError as type aliases, so errors.As against the
public type matches the value the engine returns.
- Tests assert errors.As + the four fields + the byte-identical message on both
write paths (permanent issues->issues and the wisp-source BeginTx/Commit seam),
and lock the re-exports; the deterministic conflict is returned immediately
(never retried as a transient serialization error).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(deps): emit dependency_added / dependency_removed events
`bd dep add` and `bd dep remove` recorded no event, so the events feed never
surfaced dependency changes even though the event types (types.EventDependencyAdded
/ EventDependencyRemoved) have existed since the original SQLite backend, which
emitted them on every add/remove. The emission was dropped when that backend was
removed for the Dolt-only migration and never ported to the current write paths.
Restore it on both Dolt write plumbings, matching the original shape (an events
row on the source issue: "Added dependency: <src> <type> <target>" /
"Removed dependency on <target>").
- issueops.AddDependencyInTx / RemoveDependencyInTx record the event via
RecordEventInTable on the source's event table (wisp-routed), on the genuine
add/remove only — the idempotent same-type re-add and the no-op remove of a
missing edge record nothing.
- The event is committed with the edge: DoltStore.AddDependency/RemoveDependency
DOLT_ADD `events`, and the transaction-path (RunInTransaction / batch /
graph-apply) methods mark the source's event table dirty (events or wisp_events)
so StageAndCommit commits it — without this the event row would dangle in the
working set.
- Emission is gated to the explicit dep-add/remove verb on both plumbings: the
proxied-server repo only records when the use-case sets DepInsertOpts.EmitEvent,
which create-with-deps (implicit parent-child / --deps / waits-for, via a direct
repo Insert) does not — so `bd create --parent` produces the same history on
either backend (the embedded create path via PersistDependencies likewise emits
nothing).
- Tests on both plumbings: add/remove emit exactly once and commit (verified via
`events AS OF 'HEAD'`), idempotent re-add and no-op remove emit nothing, wisp
sources route to wisp_events, and create-with-deps emits no dependency_added.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(close): optional ExpectedVersion CAS on CloseIssueChecked
CloseIssueChecked guards a close on is_blocked in-transaction, but a caller that
read an issue and then closes it has no way to say "only if it hasn't changed
since I read it" — a lost-update window. Add an optional compare-and-swap on the
row's version (the RowVersion / row_lock token): when the caller supplies an
ExpectedVersion, the close proceeds only if the row still has that version, else
it refuses with a typed ErrVersionMismatch. The version read and the close share
one transaction, so it is a true CAS with no read-then-write gap.
- storage.ErrVersionMismatch (re-exported as beads.ErrVersionMismatch) and
CloseIssueOptions.ExpectedVersion *int64 (nil disables the check; a pointer so
nil "no check" is distinct from "require version 0").
- issueops.CheckVersionInTx reads row_lock (wisp-routed; ErrNotFound on a missing
row) and returns ErrVersionMismatch on divergence. CloseIssueCheckedInTx runs
it FIRST — before the is_blocked guard and before the Force short-circuit, so
Force bypasses only the guard, never the CAS (the version check is an
orthogonal precondition). A mismatch returns before any write, so the tx rolls
back leaving the issue open with no `closed` event (atomic refuse).
- The CAS has two limbs: the read-side check catches a writer that committed
before the close began, and on the retry-wrapped permanent path a commit-time
row_lock conflict is replayed by withRetryTx so the re-read refuses.
- Tests on both stores: match closes, stale refuses atomically (still open, zero
closed events), a committed concurrent write invalidates a captured version,
nil is unchanged behavior, Force does not bypass, missing id → ErrNotFound,
wisp sources route to the wisps table, and an already-closed re-close with the
post-close version stays idempotent (Unchanged).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(close): document RowVersion CAS coverage boundary on ExpectedVersion
Both adoption reviewers flagged that the public ExpectedVersion godoc and the
shared CloseIssueCheckedInTx doc could be misread as a full-row "unchanged"
check. RowVersion (row_lock) only tracks lifecycle/ownership writes
(status/assignee/started_at), so concurrent label, dependency, rename, or
is_blocked writes leave it untouched and are intentionally outside this CAS
boundary. Document that on both sites, grounded in the freshRowLock invariant.
Doc-only; no behavior change.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* refactor(cli): bd close delegates to the engine's guarded close
The embedded `bd close` path ran its own is_blocked pre-check and then closed in
a separate call — a read-then-write TOCTOU that duplicated a guard the engine
provides atomically. The verb now builds CloseIssueOptions and delegates to
CloseIssueChecked, which runs the guard and the close in ONE transaction; the
CLI's duplicated guard is deleted. --force maps to Options.Force; a blocked
close refuses with the blockers named and the --force hint.
Behavior-preserving on purpose (verified against the previous binary):
- The engine guard now uses the exact historical CLI predicate — refuse only on
a LIVE direct blocker (blocked && len(blockers) > 0), not on the bare
denormalized is_blocked column. A transitively-blocked child (is_blocked
inherited from a blocked parent, zero direct blockers) still closes without
--force, and a stale is_blocked with since-closed blockers self-heals, exactly
as before.
- An already-closed issue stays an idempotent success: it still appears in the
--json array and the text report (same output shape), still exits 0, but no
longer produces a spurious closed->closed audit entry, a no-op commit, or the
real-close side effects (molecule auto-close, newly-unblocked, claim-next).
Tests cover: direct blocker refuses atomically (still open) and closes with
--force; transitively-blocked and stale-is_blocked beads close without --force;
already-closed emits in --json alone and in a mixed batch; idempotent exit 0 —
on the engine (both stores) and through the bd binary.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(update): UpdateIssueChecked — optional ExpectedVersion CAS on the update
UpdateIssue applies a field-map update with no optimistic-concurrency option, so
a caller that wants "update only if unchanged since I read it" had to
read-then-write — a lost-update window. Add UpdateIssueChecked: when the caller
supplies an ExpectedVersion (the RowVersion / row_lock token), the version read
and the update share ONE transaction, refusing with the typed ErrVersionMismatch
if the row has moved — a true compare-and-swap. Nil disables the check and is
byte-identical to UpdateIssue, which is left untouched on the hot path.
- storage.UpdateIssueOptions{ExpectedVersion *int64} (aliased as
beads.UpdateIssueOptions) + Storage.UpdateIssueChecked, mirroring the
CloseIssueChecked pattern: CheckVersionInTx runs first inside the same
transaction on every route — the permanent withRetryTx path, the wisp path,
AND the demote route (an update carrying no_history/wisp routes through the
demote flow; a pure demoteToWispInTx extraction lets the check compose
atomically with the row move — verified byte-identical to the old
DemoteToWisp).
- Implemented on DoltStore and EmbeddedDoltStore; InstrumentedStorage wraps it;
HookFiringStore fires on_update only on success (never on a refused update).
- Tests on both stores: match updates and bumps RowVersion; stale refuses
atomically (field unchanged, zero updated events); a committed concurrent
write invalidates a captured version; nil behaves exactly like UpdateIssue;
wisp match/stale; demote-route match (migrates + applies) and stale (still in
issues, unchanged); missing id → ErrNotFound; the hook decorator fires once on
success and never on refusal.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* refactor(cli): proxied bd close delegates to a library checked close
The proxied-server `bd close` path duplicated the close guard in the CLI:
it queried blockers via the dependency use-case, refused with its own message,
and then closed in a separate use-case call. Move the guard into the library —
IssueUseCase gains CloseIssueChecked / CloseWispChecked, which run the same
live-direct-blocker predicate (refuse only on blocked && len(blockers) > 0)
and then the untouched unchecked close — and thin the CLI verb to a single
delegated call. Both `bd close` paths now enforce the guard in the library and
emit the byte-identical refusal: the same storage.ErrCloseBlocked sentinel
("cannot close blocked issue: <id> is blocked by [...]") plus the
"(use --force to override)" hint.
- Guard and close run on the one pinned unit-of-work connection (the whole
close batch is a single transaction), and the guard is read-only and refuses
before any write — a refused id leaves the shared batch transaction clean,
and an all-refused batch skips the commit entirely, exactly as before.
- The unchecked CloseIssue / CloseWisp are untouched: internal closes (molecule
auto-close, gate closes, bd todo done) intentionally stay unguarded.
- Behavior-parity preserved: guard ordering (validate → epic-child → gate →
blocked), exit codes, JSON/batch shape, already-closed handling, audit fields,
and commit-message contents are unchanged; a transitively-blocked bead
(is_blocked with no direct open blocker) still closes without --force, and
--force still bypasses. The guard-failure diagnostic now uses the embedded
path's generic wording (further convergence; nothing matched the old text).
- Tests: use-case level on real Dolt (direct blocker refuses with blockers
named + still open, transitive-only closes, force closes, already-closed
parity, wisp refuse/force) plus the proxied CLI integration suite.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(review): cross-backend dependency-event + RowVersion parity
Maintainer review fixups for PR #4911 (adopt-pr review loop):
- RowVersion: the proxied/domain create (insertIssueRow) and generic Update
paths never stamped or rewrote row_lock, so an issue written through the
proxied-server backend read back RowVersion 0 on create and unchanged on
update -- a stale CAS token that violated the types.Issue.RowVersion
contract on that backend. Stamp a fresh non-zero row_lock on insert (and the
duplicate-key rewrite) and append RowLockClause() to the generic update,
mirroring the classic issueops insert/update invariant. Adds domain/db
regression tests proving CreateIssue/CreateWisp are non-zero and
UpdateIssue/UpdateWisp change it.
- Dependency events: embedded issueops AddDependencyInTx/RemoveDependencyInTx
recorded history unconditionally, so structural create-with-deps
(bd create --parent/--deps/--waits-for) and reparent (bd update --parent)
emitted dependency_added/removed on embedded but were silent on the proxied
backend, diverging issue history for identical commands. Gate the embedded
emit on EmitEvent and thread it through AddDependencyWithOptions /
RemoveDependencyWithOptions on both the store and transaction interfaces:
the plain AddDependency/RemoveDependency are the no-event structural default
(create-with-deps, reparent), while the explicit dep verbs (bd dep add/remove,
bd link, bd relate/unrelate) pass EmitEvent -- matching the proxied
DepInsertOpts.EmitEvent gate. DoltStore stages the events table only when an
event was actually written (GH#2455). Corrects the false
"parity with PersistDependencies" comments and adds symmetric embedded/proxied
dep-event coverage for create-with-parent/deps and structural removal.
- Retain iteration-1 fixups: heal molecules on already-closed re-close,
idempotent proxied checked-close, and documented public Storage growth.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix(storage): drop always-constant event param from fireDependencyHookByID (unparam)
golangci-lint (latest, v2.12.2 in CI) unparam flags fireDependencyHookByID:
its `event` parameter always receives hooks.EventUpdate. The parameter was
already effectively constant before this PR (both base call sites passed
EventUpdate); this PR adds two more call sites, all EventUpdate. Remove the
dead parameter and hardcode hooks.EventUpdate at the single runner.Run call.
All four call sites pass hooks.EventUpdate, so behavior is unchanged; go
build, go vet, and a scoped golangci-lint run pass clean.
Maintainer fixup during adoption finalize (PR #4911).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Test User <test@test.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <ci@beads.test>
The #4847 reapply brought back tests written when sqlite was still a
supported backend; update them to the tombstone contract:
- internal/beads: FindDatabasePath returns "" for sqlite metadata (fail
closed at store selection) and never creates the database file.
- doctor: server health reports the generic non-Dolt warning; the perf
refusal message names the backend without a support claim.
- examples/library-usage: exercise the API against embedded Dolt instead
of the removed sqlite backend.
Also sweep stragglers flagged in review: bd sql help text, conformance
audit provenance comments, the test-strategy example path, and a comment
tying the flake devShell sqlite3 CLI to the legacy migration scripts.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Document the rollback of direct PostgreSQL and MySQL adapters because supporting additional general-purpose server databases adds operational and maintenance complexity. Our goal is to keep Beads as simple as possible and consume as few resources as possible.
Clarify that embedded Dolt, Dolt server, and SQLite remain supported, including Dolt server use of the MySQL wire protocol.
Existing PostgreSQL and MySQL databases are not opened or modified. Migration requires an export from a supporting build, reinitialization guided by bd help init-safety, and import; JSONL remains issue-level interchange rather than a complete backup.
Refresh generated CLI reference material alongside the storage guidance.
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Test User
Roll back the direct adapters, dialect layers, credential handling, dependencies, CI services, and conformance profiles for general-purpose server databases. That support adds operational and testing complexity at odds with our goal of keeping Beads as simple as possible and consuming as few resources as possible.
Keep the Storage and DoltStorage interfaces unchanged. Embedded Dolt, Dolt server, and SQLite remain supported; the MySQL wire driver remains because Dolt server uses it.
Retain legacy metadata identifiers and hidden init flags only as compatibility tombstones. Removed, unknown, or corrupt backend metadata now fails safely across CLI, SDK, bootstrap, doctor, factories, and Dolt administration before storage is opened or modified, with guidance to export using a supporting build and reinitialize via bd help init-safety.
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Test User
* docs: redirect legacy Pages site to Mintlify (mybd-aokv)
Agent-Signature: codex-gpt-5.6-sol-high on behalf of matt wilkie
* docs: harden legacy Pages redirect
Agent-Signature: codex-gpt-5.6-terra-medium on behalf of matt wilkie
- 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
- Rewrite docs/core-concepts/index.md as 'How Beads Works' — the one
canonical concept page (modeled on Gas City's how-gas-city-works):
problem-first framing, the bead -> dependencies -> ready-work loop, hash
IDs, the formula -> proto -> molecule/wisp pipeline, gates, Dolt sync,
federation, and storage modes, led by four mermaid diagrams. Other pages
link here instead of re-deriving the model.
- Fact fixes caught while writing (verified against source/live help):
hash IDs are content-derived SHA-256 (internal/types/id_generator.go),
not random; bd pour/bd wisp/bd pin/bd hook are not commands (the real
surface is bd mol pour, bd mol wisp, bd assign, bd update --claim);
wisps are not stored in .beads-wisp/; cross-repo dependency syntax is
external:<project>:<capability> (cmd/bd/dep.go); recovery index claimed
SQLite errors in a Dolt product.
- Section overview pages: rewrite workflows/index, extend recovery,
multi-agent, and integrations indexes to list every child with one-line
summaries; add reference/index and put it in the nav.
- New concept diagrams: sequential-vs-hash ID merge collision
(core-concepts/hash-ids) and embedded-vs-server mode
(architecture/dolt).
- website/README.md: real build/verify instructions and parallel-run
status for the Docusaurus site.
- Repoint example READMEs and page labels at the real quickstart page.
- mint.sh + make docs-dev: local preview of the docs/ Mintlify site
(Node 22 handling modeled on the Gas City wrapper).
- test/docsync: Go guard keeping docs/ and docs.json in exact
correspondence — every nav entry has a file, every page is in the nav
(tiny stub allowlist for paths released bd binaries print), published
pages use root-relative extensionless links that resolve, and engdocs/
plus curated root markdown keep exact GitHub-style paths. Wired into
make check-docs.
- .github/workflows/docs-mintlify.yml: docsync + baseline-aware
mint broken-links check on PRs touching docs/**.
- Retire scripts/sync-website-docs.sh and its mirror-drift gate: the six
mirrored files now live once in the Mintlify site; the committed
Docusaurus mirrors stay frozen so the parallel-run site keeps building.
- Repoint inbound links to moved docs across README, guides, examples,
npm-package, plugin resources, and Go comments; add docs/SYNC_CONCEPTS.md
pointer stub (bd's agent templates print that path). Runtime strings in
cmd/bd (prime.go, store_factory_nocgo.go, init_git_hooks.go) still print
old paths — covered by stubs, flagged in the PR.
* feat(formula): add bd formula schema reflection-driven primitive index (beads-9ib)
Generates internal/formula/schema_gen.go from types.go via go:generate,
exposing all 18 exported structs (Formula, Step, LoopSpec, OnCompleteSpec,
etc.) with field types, json/toml tags, required-flag, and doc comments.
Surfaced via:
bd formula schema # list every primitive
bd formula schema loop # show LoopSpec fields
bd formula primitives on_complete # alias + snake_case match
bd formula schema --json # machine-readable
Lookup prefers exact match over Spec/Rule(s) suffix-strip, so "gate"
resolves to Gate (not GateRule). Fields tagged json:"-" (Step.SourceFormula,
Step.SourceLocation) are excluded.
TestSchemaGenIsCurrent re-runs the AST walker in-memory and byte-diffs
against the committed schema_gen.go, so a new struct in types.go without
a regen will fail CI.
Item 2 of GH#3621.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(formula): point bd formula --help at the primitive index (beads-lnf)
Extends the cobra Long descriptions on `formula`, `formula list`, and
`formula show` so an agent reading any of them is told that
`bd formula schema` (alias `primitives`), the curated
`examples/formulas/primitives/` directory, and the website primitives
reference exist. Without these pointers, agents land on the formula
surface and conclude there is no primitive index — which is the exact
failure mode GH#3621 is closing.
Adds cmd/bd/testdata/formula_help.txt as the regression gate: a
scripttest that runs `bd formula --help` (plus `--help` on the list
and show subcommands) and asserts the four pointers are present. If
someone deletes a pointer, the snapshot fails.
website/docs/cli-reference/formula.md is auto-generated from the Long
descriptions via `bd help --doc formula`, so the website doc inherits
the pointers on its next regeneration with no manual edit.
Item 1 of GH#3621.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(formula): curated primitive examples + smoke harness (beads-0sp)
Adds examples/formulas/primitives/ with one minimal `.formula.toml` per
empirically wired primitive in internal/formula/types.go:
loop-count LoopSpec.count expand body 3x → .iter1.work…
loop-range LoopSpec.range/var {n} substitutes into title
children-epic Step.Children epic + children w/ sibling needs
branch-fanin ComposeRules.Branch fork-join, deploy depends on 3 sibs
condition Step.Condition var-driven step inclusion
gate-timer Step.Gate sibling gate-typed issue blocks step
Each fixture has a header doc-comment explaining the primitive in
plain language; README.md indexes them with a one-line description
each and points back at `bd formula schema`.
cmd/bd/formula_primitives_test.go is the smoke harness: for each
fixture it parses, cooks through the full transformation pipeline
(loops → branches → gates → advice → expansions → conditions), and
asserts the primitive's observable effect on the cooked subgraph
(issue IDs, blocking deps, substituted titles, gate await_type).
Cooks against an in-memory subgraph rather than a Dolt-backed temp
DB so the harness exercises the primitive transformation, not the
persistence/auto-export infrastructure.
A subtest fails if a fixture is added to the directory without a
registered assertion in cases[] — the harness exists to prove
primitives are wired, not just that fixtures parse.
Explicitly omits an `on_complete` fixture; that primitive is a
runtime no-op as of v1.0.3 and ships with beads-i02's resolution,
not this epic.
Item 3 of GH#3621.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(formula): satisfy CI gosec G306 + regen CLI doc for new help text
Two CI fixes for the formula primitives PR:
- internal/formula/cmd/schemagen/main.go:26 — drop WriteFile perms
from 0644 to 0600 (gosec G306).
- website/docs/cli-reference/formula.md and the v1.0.0 mirror —
regenerated from the updated `bd formula --help` Long text via
scripts/generate-cli-docs.sh, using a CGO_ENABLED=0 bd build to
match CI.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(formula): distinguish schema from wired primitives
* fix(formula): regen schema_gen.go for rebase onto current main
Upstream main's Formula struct gained an Intent field after PR #3781 was
opened; regenerate schema_gen.go via go generate so
TestSchemaGenIsCurrent passes after rebasing the PR's commits onto
current main.
Maintainer fix-merge for gastownhall/beads#3781.
Agent-Signature: claude-fable-5-medium on behalf of matt wilkie
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
bd admin compact --tier 2 hard-errors "not yet implemented", yet the command
help, --stats output, and several docs advertised "Tier 2: Ultra compression
(90 days closed, 95% reduction)" as if it worked. Make the surface honest:
- Reject --tier != 1 early with a clear "not yet implemented; only --tier 1 is
available" message instead of failing deep inside a mode.
- --stats labels Tier 2 "not yet implemented" and drops the bogus 95% savings
estimate; the JSON tier2 block gains "implemented": false.
- Update command/flag help, the plugin skill doc, and the examples README;
regenerate the generated CLI reference.
New embedded e2e asserts --tier 2 errors and --stats no longer advertises 95%.
No attempt to implement Tier 2 (semantics undefined); only the false
advertising is removed.
Refs #4463
Agent-Signature: claude-opus-4-8-high on behalf of maphew
* chore: track workflow formulas for portability
Force-add gh-issue-to-pr and gh-pr-review formulas so they can be
cloned to new machines. These live in .beads/formulas/ which is
normally gitignored, but formulas are code (not database state).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* chore: untrack workflow formulas
Remove gh-issue-to-pr and gh-pr-review formulas from git tracking.
These are already covered by .gitignore (.beads/) and shouldn't be
sent upstream.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* examples: add GitHub issue-to-PR and PR triage starter formulas
Ship reusable GitHub automation examples and remove hard-coded beads-specific defaults so teams can adapt them to their own repositories.
Co-authored-by: Cursor <cursoragent@cursor.com>
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
* docs: fix broken xref to docs/EXTENDING.md in extension example
The extension example README referenced docs/EXTENDING.md in three
places, but that file was deliberately deleted in the SQLite -> Dolt
migration (see CHANGELOG entry "Deleted deprecated docs - removed
EXTENDING.md and MULTI_REPO_HYDRATION.md (SQLite-era, no longer
applicable)"). Anyone following the example hits a broken link.
Removed all three references. The example README is itself the
canonical reference for the extension pattern, so no redirect target
is needed.
Note: other docs in the repo still reference the deleted EXTENDING.md
(docs/ADVANCED.md, docs/CONFIG.md, examples/library-usage/README.md,
website/docs/reference/advanced.md). Those are out of scope for this
fix and should be addressed in follow-up issues.
Tracking bead: mybd-q71
GH: #3683
PR: builds on follow-up audit from PR #3706
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: fix remaining broken xrefs to deleted EXTENDING.md across repo
Round 1 (commit ddeff314c) only fixed the extension example README
because the original prompt scoped that PR narrowly. The bead
(mybd-q71) acceptance is repo-wide ("no broken xrefs anywhere"), so
this follow-up sweeps the rest in the same PR per the project's
"one issue per PR" rule.
Per-file treatment (EXTENDING.md was deleted in commit 508387377
before v1.0.0 was tagged, so even the v1.0.0 versioned snapshot has
been broken since release):
- docs/ADVANCED.md (3 refs):
* Note in Extensible Database section: drop trailing "See
EXTENDING.md for details" — the surrounding sentence about
Dolt-era alternatives stands on its own.
* Bold "See EXTENDING.md for complete documentation" line:
redirect to the canonical working example
(examples/bd-example-extension-go).
* Next Steps bullet: same redirect.
- docs/CONFIG.md (2 refs):
* Namespace doc for compact_*: replace "(see EXTENDING.md)" with
"(used by `bd admin compact`)" — the doc itself describes the
keys, no external reference needed.
* See Also bullet: replace with link to docs/ADVANCED.md
(Extensible Database section).
- examples/library-usage/README.md (1 ref):
* See Also bullet: replace EXTENDING.md link with link to the
sibling bd-example-extension-go example.
- website/docs/reference/advanced.md (1 ref):
* Custom Tables section: replace EXTENDING.md link with link to
the bd-example-extension-go README on GitHub.
- website/versioned_docs/version-1.0.0/reference/advanced.md (1 ref):
* Same fix as the live docs. EXTENDING.md was deleted before
v1.0.0 release (commit 508387377 is an ancestor of tag v1.0.0),
so this versioned snapshot has been broken since cut and a fix
here doesn't violate frozen-in-time correctness — the link was
never valid in the v1.0.0 release.
- website/static/llms-full.txt (1 ref, auto-generated artifact):
* Updated to match the corrected source so the on-disk artifact
isn't broken until next regeneration.
- beads.go and internal/beads/beads.go (package doc comments):
* Replaced "see docs/EXTENDING.md" / "see EXTENDING.md" with a
pointer to examples/bd-example-extension-go. These were real
broken pointers in published Go source comments.
CHANGELOG.md historical entries left untouched (intentional history).
cmd/bd/info.go:747 left untouched (it's a programmatic CHANGELOG
entry rendered by `bd info`, equivalent to a CHANGELOG line).
Verification:
grep -rn 'EXTENDING\.md' --include='*.md' .
returns only CHANGELOG.md hits.
Tracking bead: mybd-q71
GH: #3683
PR: #3713 (round 2)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(config): refuse to write secret keys to git-tracked config.yaml
P0 security fix. bd config set for secret keys (api_key, secret, token,
password) now detects git tracking of the target config file and refuses
the write with an actionable error pointing to env var alternatives.
Adds --force-git-tracked escape hatch for tests. Updates stale template
documentation and setup guides to lead with env var approach.
* fix(config): scope secret git safety check to YAML-backed keys
Use real environment variable hints for known secret config keys and avoid blocking database-backed secret-looking keys such as notion.token.
Maintainer follow-up for PR #3652.
* fix(config): silence gosec on env var hint names
The map contains environment variable names, not secret values.
---------
Co-authored-by: matt wilkie <maphew@gmail.com>
- Removed bare first-party go install .../cmd/bd@latest guidance from docs,
website docs, plugin/npm docs, examples, and doctor hints.
- Standardized on:
- CGO_ENABLED=0 go install ... for server-mode only
- CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install ... for embedded-
capable
- Added scripts/check-go-install-guidance.sh and wired it into CI.
- Updated default.nix to use gms_pure_go instead of ICU flags.
Validation passed locally:
- make test
- golangci-lint run --build-tags=gms_pure_go ./...
- ./scripts/check-go-install-guidance.sh
- ./scripts/check-build-tags.sh
- go test -tags gms_pure_go ./cmd/bd/doctor
- doc flag check
Add 3 example .formula.toml files to examples/formulas/:
- feature-workflow: design, implement, review, merge
- release: bump version, test, tag, publish
- quick-check: lint, test, build (designed for wisp use)
These serve as documentation-by-example and give new users
a starting point for creating their own formulas.
Closes#3246
* fix: backward-compatible JSONL import for all pre-v1.0 formats
Three breaking changes accumulated across versions that prevent
importing old JSONL data:
1. Comment.ID changed from int64 to string in v1.0 — old JSONL
with numeric comment IDs crashes the importer. Add custom
UnmarshalJSON that accepts both types.
2. "wisp" field renamed to "ephemeral" in v0.38 — JSONL from
v0.35–v0.37 silently loses the ephemeral flag. Map the old
field name during import.
3. BondRef.proto_id renamed to source_id — old JSONL silently
loses bond source references. Accept proto_id as alias.
Also improve auto-import error messaging: when upgrade recovery
fails, tell the user their data is safe and suggest bd init
--from-jsonl instead of silently swallowing the error.
* fix: use American English spelling for misspell linter
* test: add unit tests for backward-compatible UnmarshalJSON and legacy import
- TestCommentUnmarshalJSON: string IDs, numeric IDs (pre-v1.0),
zero, large numbers, missing ID, invalid JSON
- TestBondRefUnmarshalJSON: source_id, proto_id (legacy),
both fields (precedence), neither, invalid JSON
- TestImportFromLocalJSONL_LegacyFormats: numeric comment IDs
survive import, wisp→ephemeral mapping (true/false/absent)
Add --database flag to bd init so callers can specify a pre-existing server
database name, overriding prefix-based naming. Prevents orphan database creation
when an external tool (e.g. gastown) has already created the database.
Also fixes display bug showing storage path instead of DB name in server mode,
and exports ValidateDatabaseName for use by init validation.
Co-Authored-By: Peter Chanthamynavong <peterkc@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Standardize start-work semantics to `bd update <id> --claim` across docs,
examples, templates, and website static LLM artifacts. Replaces
`--status in_progress` with `--claim` where the meaning is start-work.
Also fixes stale comment in llms.txt ("Update status" → "Start work").
Co-Authored-By: Valeriy Pavlovich <iqdoctor@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Remove examples/markdown-to-jsonl, examples/github-import, and
examples/jira-import. These converters produced JSONL for bd import,
which has been removed. Native bd jira/linear/gitlab sync commands
replace this functionality.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Delete orphaned code left behind after sync-branch, no-db mode, and
daemon removal: worktree engine (zero callers), internal/export package
(zero imports), broken monitor-webui example (imports deleted rpc pkg),
no-db stubs, sync-branch doctor no-ops and their wiring, and vestigial
flush-debounce/remote-sync-interval config keys.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Delete migrate_hash_ids.go (760 lines) and remove hash-ids subcommand,
doctor checks, and readonly test cases. Relocate copyFile to migrate.go
for migrate_dolt.go and repair.go. Rename public API beads.NewStorage()
to beads.Open() across code, tests, examples, and docs. Clean up
transitional SQLite-era comments in store.go and context.go. Add server
mode watchdog with TCP+SQL health probes, auto-restart with stale PID
cleanup, exponential backoff, and clean shutdown.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Executed-By: beads/crew/emma
Rig: beads
Role: crew
Update documentation examples from deprecated NewSQLiteStorage to
NewStorage(ctx, path). Fix monitor-webui to import the public beads
package instead of internal/beads.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Executed-By: beads/crew/emma
Rig: beads
Role: crew
Remove 60 lines of re-exported type aliases and constants from internal/beads
that duplicated internal/types. Update integration tests to import types
directly. Fix examples to use the public beads package API instead of
internal imports.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Executed-By: beads/crew/emma
Rig: beads
Role: crew
Code health review found 30+ instances of error suppression using blank
identifier without explanation. Added comments to 82 files explaining WHY
each error is safely ignored (best-effort cleanup, advisory operations,
safe defaults, etc.) to improve code maintainability.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Executed-By: beads/polecats/jasper
Rig: beads
Role: polecats
Update all documentation to use the new subcommand syntax:
- `bd daemon --start` → `bd daemon start`
- `bd daemon --stop` → `bd daemon stop`
- `bd daemon --status` → `bd daemon status`
- `bd daemon --health` → `bd daemon status --all`
- `--global=false` → `--local`
The old flag syntax is deprecated but still works with warnings.
Closes: bd-734vd
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
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>
Adds closed_by_session tracking for entity CV building per Gas Town
decision 009-session-events-architecture.md.
Changes:
- Add ClosedBySession field to Issue struct
- Add closed_by_session column to issues table (migration 034)
- Add --session flag to bd close command
- Support CLAUDE_SESSION_ID env var as fallback
- Add --session flag to bd update for status=closed
- Display closed_by_session in bd show output
- Update Storage interface to include session parameter in CloseIssue
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Executed-By: beads/crew/dave
Rig: beads
Role: crew