* 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>
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>
* ci(bazel): nogo replaces go vet and golangci-lint (ga-96smfk.18)
Lint and vet now run as nogo inside the Bazel build, so they gate wherever
the Bazel lanes execute (rbe-west), and the golangci-lint and go vet jobs
leave pr.yml and main.yml.
- //tools/nogo (own go.mod, joined to beads' for go_deps only through
gazelle.go.work): go test's vet checks (cmd/go's defaultVetFlags, the set
scripts/ci/go-test-vet.sh ran) plus the eight linters .golangci.yml
enables, each a wrapper over the library version golangci-lint v2.10.1
uses (depguard, errcheck, forbidigo, gosec, misspell, sloglint, unconvert,
unparam).
- .golangci.yml stays the single lint policy: Bazel embeds it and
tools/nogo/internal/golangci applies it as golangci-lint does (enabled
set, settings, run.tests: false as library-unit-only analysis, lax
generated-file detection, path/path-except/text exclusion rules), with
strict decoding so an unimplemented key fails the build.
- gascity's rules_go //nolint-range patch and x/tools ctrlflow patch,
byte-identical.
- Windows/darwin: cross-configured, not a golangci leg. The pure lane's
release cross-compile (//tools/bazel:release_cross, every library and
binary for all eight release platforms, cgo off) runs nogo on every
compile, a superset of golangci-lint's windows and darwin legs.
scripts/pr-lint (make ci-pr-lint, bd preflight) runs `bazel build
--config=nogo //...` plus release_cross for windows_amd64,darwin_arm64.
release_cross skips tools/nogo, a separate Go module `go build ./...`
never compiled.
- pr.yml: scripts-go-checks (vet) and pr-lint-wrapper (x3) are gone, with
their ci-gate entries; main.yml: pr-lint-wrapper (x6) and go-vet-cache.
scripts/ci/go-test-vet.sh and install-golangci-lint.sh are deleted.
- pre-commit hook and .pre-commit-config.yaml run `make lint-changed
LINT_CHANGED_SCOPE=staged` (nogo over the staged packages); Makefile adds
lint, vet and lint-changed. pr-lint.sh no longer runs gofmt
(//scripts/repochecks:fmt_test owns it; ga-96smfk.41).
- internal/testutil/integration: five gosec findings in integration-tagged
library files golangci-lint never built, now linted by the integration
lanes, carry reasoned //nolint directives.
Parity: with the exclusion rules removed, golangci-lint and nogo report the
same 3,916 findings natively and 3,859 each for windows and darwin (file,
line, linter, text); with .golangci.yml as committed both report none.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* ci(bazel): equivalence.py leaves nested Go modules' tests out of go test's set
tools/nogo is its own Go module, so `go test ./...` in the root never runs
its tests; Bazel's unit lane does. Its packages are neither expected nor
extra.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
#7223 made a linked, documented issue mandatory for every PR. That is
the right default for user-visible bugs and changes worth discussing,
but it adds ceremony to small, self-explanatory fixes without adding
context.
AGENTS.md, CONTRIBUTING.md, ROADMAP.md, the PR template and the feature
form now advise filing an issue when it adds context and let small fixes
go straight to a PR whose description explains the why. End-to-end
evidence is still required, and Closes #N is used when an issue exists.
No CI check or ruleset enforced the requirement; scripts/pr-preflight.sh
already only warns when a PR has no closing issue.
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Makes the repo's agent and contributor surface describe developing beads, not using bd, and requires every PR to link a documented issue.
- Contributor-only root AGENTS.md with a routing table; cmd/bd/AGENTS.md and engdocs/AGENTS.md seam files; CLAUDE.md symlinks so Claude Code loads nested files.
- Bug and feature issue forms, a PR template that requires Closes #, CONTRIBUTING sections for the triage and pipeline labels, and the opt-in fork-cache during dev setup.
- ROADMAP.md for 1.4: versioned beads (#6132), Graph Preview 2 (#7170), contributor onboarding (#7228).
- docsync guards: root AGENTS.md at or under 20 KB; every AGENTS.md symlinked, routed, and with resolving links, paths, and guard-test names.
Agent-Signature: claude-code-claude-opus-5-5-high on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(update): fence unforced --notes overwrites behind --force across all surfaces
bd update --notes silently replaced existing notes, destroying handoff
history. The contract now refuses an unforced overwrite of non-empty
notes with ErrNotesOverwrite (409 notes_overwrite_refused over HTTP,
force_notes_overwrite to override), enforced inside the mutation
transaction on both the dolt and uow backends, for single updates and
batch apply alike. CAS guards keep precedence: a stale
--if-assignee/--if-status still surfaces as the exit-13 mismatch, on
both backends, before the fence speaks.
CLI: --force and --if-assignee are no longer mutually exclusive (that
exclusion made overwriting under a guard impossible); both update
routes translate the fence's sentinel into the same actionable advice
(--force to overwrite, --append-notes to preserve history), and the
post---force warning is worded as an audit statement. The shipped
plugin skill docs and bd note help now prescribe --append-notes for
handoffs instead of the newly fenced bare --notes.
The fence is the single enforcement point: no client-side pre-read
copies of the rule. Conformance contracts, unit tests for
AuthorizeNotesOverwrite, and embedded/proxied/httpapi regression
coverage included.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MAFpn9pUw8WKMfymteZHbh
* fix(update): exempt explicit clears from the notes fence; share its predicate
CI surfaced three gaps in the fence's reach:
- Clearing notes (--notes "" / patch.notes: "") was refused, diverging
from every sibling text field's clear and from the backend behavior
contracts. The fence now targets only its actual footgun — replacing
non-empty notes with different non-empty content — via a single shared
predicate, issueops.NotesReplacement, used by both the contract's
AuthorizeNotesOverwrite and the CLI's warning path, so the two can no
longer drift. Prose updated to match everywhere the rule is stated
(ErrNotesOverwrite, ForceNotesOverwrite, OpenAPI spec + regenerated
types).
- The revision-CAS integration tests' incidental concurrent writes now
patch design instead of notes, so they no longer depend on notes-fence
semantics at all.
- The historical-upgrade harness deliberately replaces fixture notes and
asserts the new value; its two bd update --notes calls now pass
--force.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MAFpn9pUw8WKMfymteZHbh
* fix(update): address review — changelog BREAKING entry, problem.go doc block, close-policy-under-guard test
Review follow-ups on #5946 (bee-ghosttrack, MERGE-AFTER-FIXES):
- CHANGELOG: BREAKING entry under [Unreleased] ### Changed for the notes
fence on both wires (CLI exit 1, HTTP 409 notes_overwrite_refused), with
the --force / --append-notes migration line. It also names the two
deliberate edges: the explicit-clear exemption, and --force widening to
the close-policy half under --if-assignee now that the flag pair is legal.
- problem.go: CodeNotesOverwrite's comment had landed inside
CodeDependencyCycle's doc block; each const now sits under its own docs.
- assign_fence_embedded_test.go: pin the previously untested close-policy
half of --force under --if-assignee (refused unforced, authorized forced).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JyuQ6Tjv3D7tpNqeb2WDED
* test(update): align TestWarnNotesReplacement with the post-fence warning copy
The test landed on main after this branch was cut and pins the pre-fence
wording, where the warning fired on any unforced overwrite. Since the fence,
an unforced overwrite is refused outright and warnNotesReplacement fires only
after a forced one — the audit trail for a habitual --force — so the copy it
pins is now '--force replaced existing notes'.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JyuQ6Tjv3D7tpNqeb2WDED
* docs(import): record bd import's notes-fence exemption as by-design (GH#6190)
Import consults none of the per-field live-state fences — notes overwrite,
live-claim reassign, close policy — and that is the intended shape, not an
omission: its contract is wholesale row replacement, guarded by its own
staleness check (only strictly-newer rows rewrite local state, --allow-stale
is the single deliberate-overwrite opt-in) and reported field-by-field in
updated_issues. Named in AuthorizeNotesOverwrite's enforcement-boundary
comment and in bd import's help; the published CLI docs pick the help text
up at the next release pin bump.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JyuQ6Tjv3D7tpNqeb2WDED
* fix(update): refuse --notes "" and add --clear-notes; stop --notes help reading as additive
GH#6021: an empty --notes wiped the whole notes field at exit 0 behind the
same ✓ Updated receipt as a successful write — and the empty string is
exactly what a dead command substitution collapses to. The empty value is
now refused on both CLI routes (the accident and the deliberate clear are
the same bytes at the flag layer), and the deliberate clear gets its own
verb, --clear-notes, mutually exclusive with --notes/--append-notes. A verb
rather than the proposed --allow-empty-notes opt-in: what needs authorizing
is an intent, not an input path — --allow-empty-description unblocks
stdin/file plumbing, which notes does not have — and an opt-in passed
habitually would silently disarm the guard while a habitual --clear-notes
fails loudly. --force does not bypass the refusal; the fence's clear
exemption stands, so the verb alone authorizes the erase. The HTTP API is
unchanged: patch.notes "" still clears.
GH#6272: bd update --help called --notes "Additional notes" and the prime
text said "Add supplementary notes" — both read as appending, so agents
following the injected guidance faithfully clobbered prior context. The
update help now names the operation with the --append-notes contrast at the
point of use, the shared/create help is field-named like --description and
--design, and the prime line points at bd update --append-notes.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JyuQ6Tjv3D7tpNqeb2WDED
* fix(bazel): enumerate the PR-new files in cmd/bd and issueops srcs
The base added cmd/bd/BUILD.bazel and internal/storage/issueops/BUILD.bazel
with EXPLICIT srcs lists after this branch was cut, so the three files this
PR adds were never enumerated:
cmd/bd/update_notes_guard.go (go_library bd_lib)
cmd/bd/update_notes_guard_test.go (go_test bd_test)
internal/storage/issueops/aggregate_authorize_notes_test.go (go_test)
The go_library omission is a hard build break, not a silent skip:
update.go:215,220 and update_input.go:106,111 are enumerated and call
validateNotesUpdate / clearNotesRequested, so //cmd/bd:bd_lib compiles the
callers without the callee. bazel.yml arms unconditionally for fork PRs
(head.repo.fork == true) and builds //cmd/bd:bd + //cmd/bd:bd_test, so this
reds the lane. make bazel-sync-check cannot see it -- go_srcs.py only
validates the glob-based go_srcs filegroup, never the rule srcs lists.
Generated by make bazel-sync (gazelle), not hand-edited, so the workflow's
own BUILD-files-in-sync drift step agrees byte-for-byte.
* fix(notes): name --clear-notes in bd note's rm guidance, correct the fence boundary comment, pin both request-shape rules
Takes all three non-gating minors from the review. No behavior change: two
prose fixes and two test cases.
1. cmd/bd/note.go's rm|remove|delete branch advised
`bd update <id> --notes "text" --force` under "To change or clear notes",
but clearing through --notes is exactly what this PR made impossible --
validateNotesUpdate refuses an empty value unconditionally and --force does
not reach it. The branch now names both verbs separately: --notes --force to
replace, --clear-notes to clear. The edit and update branches speak only of
replacing and were already correct, so they are untouched.
2. aggregate.go's enforcement-boundary comment claimed the UpdateIssueInTx
funnel's "one notes-replacing caller is bd edit". Under this PR's own
NotesReplacement predicate there are at least four more (bd note's
read-combine-write, bd defer --reason, bd rename and delete-tombstoning's
mechanical ID rewrites, bd compact's clears). The exemption is still sound --
every funnel writer derives its new value from the current notes -- so the
comment now names those CLASSES instead of a single caller, which is the
claim that is actually true and that a future fence auditor can check.
3. Both branches this PR adds to ValidateUpdateRequest were uncovered: the
batch apply leg reaches them here and nowhere else, while the single-issue
HTTP handler's own pre-check returns before storage. Added a sibling table
(the existing one varies only the patch; these two rules are properties of
the REQUEST) with a case each. Mutation-checked, disjoint: neutralizing the
force-without-notes branch reds only the first case, neutralizing the
notes+append branch reds only the second, and the pre-existing
canonical-fields table stays green under both.
Not an amend of 5ffcc9c16c: that commit's message states it was generated by
make bazel-sync and not hand-edited, so folding hand-written Go into it would
falsify the claim its own BUILD-files-in-sync argument rests on. No new files,
so the srcs lists it repaired stay correct.
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
Priority used the filled circle also mapped to status-blocked, so agents
misread ready work as blocked (GH#4996). Render P-labels only; document
the convention for agents; keep ● for blocked status alone.
Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
Consolidate test execution and design guidance around the smallest trustworthy seam, narrow doubles, semantic versus persistence conformance, strict E2E admission, and proportional verification. Convert the former philosophy documents to compatibility pointers.
Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of CI Bot
Co-authored-by: CI Bot <ci@beads.test>
The policy that embedded-mode doctor support is enabled one human-vetted
subcommand at a time lived only in GH#3794 and PR review threads. The
embedded gate in doctor.go is exactly where the next contributor will be
tempted to remove it wholesale (PR #3439 did, and was closed for it), so
state the rule there and beside the Storage Boundary section it derives
from.
Comment/docs only; no behavior change.
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
Per decision 7, bd's user-facing strings now reference the Mintlify-era
paths: prime policy-profiles help, storage-backend comparison help
(store_factory_nocgo, init --backend), init-safety help (recovery
playbooks now docs/recovery/init-safety.md; the ADR reference now
engdocs/adr/), the pk-fork-refused recovery URL (dolt.go), doctor's plugin
suggestions (claude.go) and managed-handoff pointer, aider setup guidance
and the shared recipe template (quickstart URL), and the agent instruction
templates (sync-concepts URL, quickstart URL). bd mol pour's help no
longer claims molecules are 'synced with git' — they sync via Dolt like
any other bead.
Also corrects the stale claude recipe ProjectPath metadata
(.claude/settings.local.json -> .claude/settings.json; the dedicated
installer has written settings.json since the migration sweep).
This repo's AGENTS.md managed section is refreshed to the new template
body (hash bacef91e, has-remote variant preserved), and agents.md.tmpl's
embedded marker matches. Template tests updated to pin the new fragment;
CLI docs regenerated.
Recorded, not fixed (behavior-level, see the decision record):
routing.mode's maintainer/contributor no-op values and the
sync.require_confirmation_on_mass_delete key with no consumer.
Note: TestCheckBeadsRole_NotConfigured/_NotGitRepo in cmd/bd/doctor fail
on any machine with beads.role in the global git config (no HOME
isolation) — pre-existing, unrelated to this change.
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).
Fix four doc-seam duplications (mybd-melg):
1. AGENT_INSTRUCTIONS.md's "Release Process (Maintainers)" duplicated
RELEASING.md with a divergent 7-step manual process, cited a
nonexistent ./scripts/update-homebrew.sh, and used a stale 0.9.3
example. Replaced the section body with a pointer to RELEASING.md.
2. CONTRIBUTING.md's "Testing Guidelines" was a parallel test-running
guide that never linked docs/TESTING.md, and was self-contradictory
("make test" listed as both the fast tier and the full suite;
described a -short two-tier strategy scripts/test.sh does not
implement). Cut the command matrix, kept only contributor etiquette
(what to run before a PR, expectations), and pointed to
docs/TESTING.md and docs/TESTING_PHILOSOPHY.md.
3. Moved FEDERATION-SETUP.md to docs/FEDERATION.md as the canonical
federation home. Left a short pointer stub at the root path (inbound
links from website quickstart pages and llms-full.txt keep
resolving). Folded DOLT.md's federation section (architecture
diagram, sync/status/topology commands, credentials) into
docs/FEDERATION.md, then reduced DOLT.md's section to a summary
paragraph plus a link. While merging, corrected the stale "Planned
Features" list (list-peers/sync/status are implemented; only
single-peer push/pull remain unexposed - bd federation sync already
covers both directions) and the stale --json output example.
Added a docs/DOC_INVENTORY.md row for docs/FEDERATION.md.
4. Folded the two divergent hand-maintained "Landing the Plane" /
session-completion protocols (AGENTS.md, AGENT_INSTRUCTIONS.md) into
one canonical copy in AGENTS.md - union of the still-true content
(explicit quality-gate commands, cleanup commands, and the
next-session hand-off prompt format from AGENT_INSTRUCTIONS.md).
Reduced the AGENT_INSTRUCTIONS.md copy to a pointer.
Agent-Signature: claude-sonnet-5-high on behalf of matt wilkie
* docs: align agent maintainer conventions
Agent-Signature: codex-gpt-5.5-medium on behalf of matt wilkie
* docs: refresh checked-in AGENTS.md managed block to generated content
The PR self-review flagged the execution metadata key rename (item 4) as a
local experiment; that content was already dropped from this branch. Upstream
PR #4358 has since documented the existing execution_* model/effort keys as
portable hints in docs/METADATA.md, which remains the canonical reference.
Refresh the checked-in AGENTS.md managed Beads block to the current rendered
full-profile section so the marker hash is truthful. This drops the
experimental "read execution metadata first" workflow step from the managed
block (execution hints stay documented in docs/METADATA.md and
AGENT_INSTRUCTIONS.md) and picks up the conservative agent context profiles
from #4220.
Agent-Signature: claude-unknown-model-high on behalf of matt wilkie
Captures the architectural direction that beads talks to storage through a
driver interface (dolthub/driver) and should not reach across that boundary.
Concurrency, locking, and crash-safety are the driver's job; storage-
implementation details should not appear on the public SDK surface.
Notes that storage issues are still welcome from the beads side, but should
be flagged for routing to the driver rather than worked around in beads.
Context: gastownhall/beads#3614 (removing the embedded-mode flock) is an
example of this direction — that PR motivated capturing the principle so
future contributors and agents don't reflexively reintroduce cross-boundary
workarounds.
Co-authored-by: CI Bot <ci@beads.test>
* doctor: detect AGENTS.md / CLAUDE.md user-authored divergence
Adds CheckAgentDocDivergence to bd doctor and bd preflight. The check
flags cases where AGENTS.md and CLAUDE.md exist as independent regular
files whose content outside the BEGIN/END BEADS INTEGRATION markers has
drifted apart — a common drift mode when agents hand-edit one of the
pair without mirroring the change.
Skipped when:
- Either file is missing
- The pair is symlinked or shares an inode (hardlink)
- Normalized user-authored content matches
- Either file contains the opt-out marker
<!-- bd-doctor-divergence: ok --> (for projects that intentionally
keep distinct files for different audiences, like beads itself)
Adds the opt-out marker to AGENTS.md so the upstream beads repo, whose
AGENTS.md and CLAUDE.md serve intentionally different audiences, does
not regress its own preflight.
Closes mybd-31m.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(lint): hyphenate hardlinked to satisfy misspell linter
misspell flags 'hardlinked' as a typo for 'hardline'. Hyphenating to
'hard-linked' is a common alternate spelling and sidesteps the false
positive without changing meaning.
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: CI Bot <ci@beads.test>
* cmd/bd: extract sanitizeDBName to its own file for CGO_ENABLED=0 lint
sanitizeDBName lived in store_factory.go which is //go:build cgo,
but init.go (no tag) calls it. The pre-commit golangci-lint runs
with CGO_ENABLED=0 and flagged it as undefined. Move the pure-Go
function to its own untagged file and drop the now-unused strings
import from store_factory.go. No behavior change.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* schema: tolerate "does not have column" errors in migration runner
Broadens isConcurrentInitError to also treat "does not have column"
as a benign migration error, symmetric with the existing "duplicate
column" tolerance for ADD races. Makes DROP COLUMN migrations
idempotent across databases bootstrapped with different base schemas.
Observed failure: migration 0032 (DROP COLUMN applied_at) loops
forever on any database that lands at v31 without the column. Dolt
has no DROP COLUMN IF EXISTS, so the SQL itself can't be guarded;
handling it in the runner keeps the migration file trivial.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Add migration 0032 idempotence tests (bd-7mh.3)
* Document bd execution metadata workflow (bd-b1a)
* Revert "Document bd execution metadata workflow (bd-b1a)"
This reverts commit 0d6a96babd.
* Reapply "Document bd execution metadata workflow (bd-b1a)"
This reverts commit df90cf5404.
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
Prevents agents from silently overwriting external contributor PRs.
Prompted by PR #3143 where bgjackma's work was reimplemented without
attribution.
- CONTRIBUTING.md: "Your PR Will Not Be Overwritten" section
- AGENT_INSTRUCTIONS.md: check-before-you-build procedure + CONTRIBUTING.md reference
- AGENTS.md: cross-reference to contributor protection
bd create/update --description=- reads from stdin, avoiding shell
escaping failures with backticks, nested quotes, and special characters.
This capability already exists in flags.go but was not surfaced in
agent instructions or plugin skills.
Update AGENT_INSTRUCTIONS.md, AGENTS.md, and CLI_REFERENCE.md to show
the stdin pipe pattern as the recommended approach for descriptions
with special characters.
Closes: GH#1376
Co-authored-by: Amp <amp@ampcode.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019ca7ab-f5f9-761f-8934-60d3c590adc3
* fix(configfile): respect backend field in metadata.json
GetBackend() was hardcoded to always return "dolt", ignoring the
backend field in metadata.json. This forced all SQLite users onto
Dolt with no migration path and no way to opt out.
- Add BackendSQLite constant and case-insensitive normalization
- GetBackend() reads backend field: sqlite → sqlite, empty/dolt → dolt
- DatabasePath() routes to SQLite or Dolt path based on backend
- BEADS_BACKEND env var override as escape hatch for corrupted configs
- CapabilitiesForBackend handles sqlite backend
- Warning on unrecognized BEADS_BACKEND values
- 55 tests covering all paths including env var, case normalization,
roundtrip persistence, and DatabasePath routing
Fixes#2016.
Authored by: Aaron Lippold<lippold@gmail.com>
* feat(migrate): add shared migration safety functions
Extract reusable safety functions for SQLite→Dolt migration:
- backupSQLite: file copy with O_EXCL + 0600 permissions
- verifyServerTarget: TCP + SQL check to prevent wrong-server writes
- verifyMigrationCounts: source vs target count verification
- finalizeMigration: atomic metadata update (last step only)
- rollbackMetadata: restore original config on failure
22 unit tests covering all functions including counter overflow,
non-MySQL server detection, deps-only mismatch, nil config rollback,
server config preservation, and no-metadata scenarios.
Authored by: Aaron Lippold<lippold@gmail.com>
* refactor(migrate): use safety functions in auto-migration
Refactor both CGO and non-CGO auto-migration paths to use shared
safety functions instead of inline logic:
Phase 1 (pre-flight):
- Always backup SQLite before any migration attempt
- Verify server target to prevent writing to wrong Dolt server
- Skip migration when backend explicitly set to sqlite (GH#2016)
- Use GetBackend() for SQLite guard, strings.EqualFold for Dolt
stale-leftover detection (preserves legacy empty-backend migration)
Phase 2 (import):
- Unchanged: extract from SQLite, create Dolt store, import data
Phase 3 (verify + finalize):
- Verify issue counts match before updating metadata
- Atomic finalization via finalizeMigration (metadata last)
- Rollback with warning on failure (not silent discard)
Clear, actionable error messages at every failure point showing
backup path. 13 unit tests including new SQLite backend guard test.
Authored by: Aaron Lippold<lippold@gmail.com>
* fix(main): clear error when SQLite backend detected
When GetBackend() returns "sqlite" (user opted to stay on SQLite or
migration was skipped), print a clear error with migration instructions
instead of falling through to dolt.New() which produces a confusing
Dolt connection failure.
Fixes#2016.
Authored by: Aaron Lippold<lippold@gmail.com>
* feat(doctor): detect and fix broken migration states
Add three new doctor checks for migration-related issues:
CheckBrokenMigrationState: detects metadata claiming Dolt backend
but no Dolt directory present (with server-mode awareness). Offers
bd doctor --fix to restore SQLite backend from beads.db or
beads.db.migrated files.
CheckSQLiteResidue: detects leftover beads.db after successful
migration. Fix renames to .migrated (with backend guard to prevent
accidentally renaming active SQLite database).
CheckEmbeddedModeConcurrency: detects embedded mode with lock
contention indicators (dolt-access.lock, noms LOCK files).
Recommends switching to server mode for multi-agent workflows.
Addresses #2086.
19 doctor tests covering all detection paths including server mode,
backup file detection, .migrated-only recovery, zero-byte files,
concurrent access with access locks and noms locks.
Fixes#2086.
Authored by: Aaron Lippold<lippold@gmail.com>
* test(migrate): add integration tests for migration safety
8 integration tests covering key business flows:
- Full migration lifecycle (SQLite → backup → Dolt → bd list works)
- Failed migration recovery (corrupt SQLite → backup exists → intact)
- Doctor detects broken state and fix restores SQLite backend
- Doctor fixes beads.db.migrated rename-back recovery
- Idempotent retry (second migration is no-op)
- SQLite guard prevents auto-migration (data intact, no backup)
- Backup content matches source byte-for-byte
- Metadata JSON valid with all required fields after migration
Authored by: Aaron Lippold<lippold@gmail.com>
* feat(scripts): add migrate-audit.sh for batch SQLite→Dolt migration
Utility script to audit and batch-migrate beads boards:
- Scans all .beads/ directories under a configurable root
- Reports backend state, issue count, and schema version for each board
- --dry-run: shows what --migrate would do without changes
- --migrate: batch converts eligible SQLite boards to Dolt
- --exclude PATTERN: skip projects matching regex (e.g., "backup|test")
- --port/--host: target a specific Dolt server
Safety features:
- Backs up metadata.json before modifying each board
- Restores original metadata.json on migration failure
- Skips boards with old schema (missing owner column)
- bd binary handles SQLite backup, server verification, count verification
- Uses jq for JSON (consistent with existing scripts, no python dependency)
Companion tool for the migration safety PR (GH#2016, GH#2086).
Authored by: Aaron Lippold<lippold@gmail.com>
* fix(migrate): handle all schema versions in SQLite extract
Databases from older beads versions are missing columns added over time
(owner, created_by, crystallizes, mol_type, work_type, quality_score,
source_system, and others). The extract functions hardcoded COALESCE
for all columns, causing "no such column" errors.
Fix: make ALL non-id columns use sqliteOptionalTextExpr via a DRY
opt() helper in both CGO extract and shim extract paths. Missing
columns default to empty/zero/null. Also adds empty/corrupt beads.db
handling to the migrate-audit.sh script.
Tested against 12 real-world databases spanning multiple beads versions,
from the earliest (~30 columns) to the current schema (50+ columns).
All 28 boards migrated successfully.
Authored by: Aaron Lippold<lippold@gmail.com>
Adds documentation warning agents to always use -f flags with cp, mv, rm
to avoid hanging on interactive confirmation prompts. This is especially
important for polecats running on systems where shell aliases include
the -i flag by default.
Also includes guidance for scp, ssh, apt-get, and brew.
Fixes bd-tm2p
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
SQLite-era instruction causing agents to run deprecated bd sync.
With Dolt backend, there is no sync - database is live.
Part of hq-e4eefc (Dolt migration epic)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Fixes#1049 - AGENTS.md referenced CLAUDE.md which doesn't exist on main.
Changes:
- "Key Sections in CLAUDE.md" -> "Key Sections"
- "See CLAUDE.md..." -> "See AGENT_INSTRUCTIONS.md..."
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The bd edit command opens an interactive editor ($EDITOR) which AI agents
cannot use. Added warnings to AGENTS.md, AGENT_INSTRUCTIONS.md, and
cmd/bd/AGENTS.md directing agents to use bd update with flags instead.
Fixes: bd-3ft33
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implements bd mol distill to reverse the spawn operation:
- molecule → proto (spawn is proto → molecule)
Features:
- --as flag for custom proto title
- --var value=variable to replace concrete values with placeholders
- --dry-run to preview the distilled structure
- Preserves full subgraph structure and dependencies
- Adds template label to all cloned issues
Also updates AGENTS.md with landing checklist.
Closes: bd-iq19
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Move all agent instructions from AGENTS.md into CLAUDE.md, which
Claude Code reads automatically. AGENTS.md now just redirects.
Also remove MCP server from plugin.json - the plugin now uses
hooks-only mode for better token efficiency.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Remove the external MCP Agent Mail server integration that required
running a separate HTTP server and configuring environment variables.
The native `bd mail` system (stored as git-synced issues) remains
unchanged and is the recommended approach for inter-agent messaging.
Files removed:
- cmd/bd/message.go - Legacy `bd message` command
- integrations/beads-mcp/src/beads_mcp/mail.py, mail_tools.py
- lib/beads_mail_adapter.py - Python adapter library
- examples/go-agent/ - Agent Mail-focused example
- examples/python-agent/agent_with_mail.py, AGENT_MAIL_EXAMPLE.md
- docs/AGENT_MAIL*.md, docs/adr/002-agent-mail-integration.md
- tests/integration/test_agent_race.py, test_mail_failures.py, etc.
- tests/benchmarks/ - Agent Mail benchmarks
Updated documentation to remove Agent Mail references while keeping
native `bd mail` documentation intact.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add bd cleanup --ephemeral flag for transient message cleanup (bd-kwro.9)
- Add Ephemeral filter to IssueFilter type
- Add ephemeral filtering to SQLite storage queries
Tests (bd-kwro.10):
- Add internal/hooks/hooks_test.go for hook system
- Add cmd/bd/mail_test.go for mail commands
- Add internal/storage/sqlite/graph_links_test.go for graph links
Documentation (bd-kwro.11):
- Add docs/messaging.md for full messaging reference
- Add docs/graph-links.md for graph link types
- Update AGENTS.md with inter-agent messaging section
- Update CHANGELOG.md with all bd-kwro features
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Refine ExtractIssuePrefix to better distinguish hash IDs from English
words in multi-part issue IDs. Hash suffixes now require digits or be
exactly 3 chars, preventing "test", "gate", "part" from being treated
as hashes. This fixes prefix extraction for IDs like "vc-baseline-test".
Also updates git hooks to use -q flag and adds AGENTS.md documentation.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: fix Go version typo in CONTRIBUTING.md (1.25 -> 1.24)
* docs: update Go version requirement to 1.24+ across docs
* docs: fix broken links to docs/ in npm-package/README.md
* docs: fix QUICKSTART.md path reference in AGENTS.md
Add section explaining the cognitive trap where temporal language
("Phase 1", "Step 1", "before") causes inverted dependency direction.
Includes examples of correct vs incorrect dependency setup and
verification using bd blocked.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Completes the deletion propagation epic (bd-imj) with all 9 subtasks:
- Cross-clone deletion propagation via deletions.jsonl
- bd deleted command for audit trail
- Auto-compact during sync (opt-in)
- Git history fallback with timeout and regex escaping
- JSON output for pruning results
- Integration tests for deletion scenarios
- Documentation in AGENTS.md, README.md, and docs/DELETIONS.md
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Move detailed event-driven daemon documentation to docs/DAEMON.md.
Keep only brief mention in AGENTS.md with reference to full docs.
Reduces duplication and improves documentation organization.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
This implements the ability to separate bd-specific instructions from
project-specific instructions by generating a canonical BD_GUIDE.md file.
## Changes
1. Added `--output` flag to `bd onboard` command
- Generates version-stamped BD_GUIDE.md at specified path
- Includes both agentsContent and copilotInstructionsContent
- Auto-generated header warns against manual editing
2. Version tracking integration
- checkAndSuggestBDGuideUpdate() detects outdated BD_GUIDE.md
- Suggests regeneration when bd version changes
- Integrated with maybeShowUpgradeNotification()
3. Comprehensive test coverage
- Tests for BD_GUIDE.md generation
- Tests for version stamp validation
- Tests for content inclusion
4. Documentation updates
- Updated AGENTS.md with BD_GUIDE.md workflow
- Added regeneration instructions to upgrade workflow
## Benefits
- Clear separation of concerns (bd vs project instructions)
- Deterministic updates (no LLM involved)
- Git-trackable diffs show exactly what changed
- Progressive disclosure (agents read when needed)
## Usage
\`\`\`bash
# Generate BD_GUIDE.md
bd onboard --output .beads/BD_GUIDE.md
# After upgrading bd
bd onboard --output .beads/BD_GUIDE.md # Regenerate
\`\`\`
Closes bd-woro
Implements bd-hwmp and bd-5otr (part of epic bd-nxgk) to help AI agents
automatically detect and adapt to bd upgrades.
## Changes
### Documentation (bd-hwmp)
- Added "After Upgrading bd" section to AGENTS.md with step-by-step workflow
- Enhanced "Pro Tips for Agents" with upgrade detection guidance
- Documents bd info --whats-new and bd hooks install commands
- References GitHub Discussion #239
### Startup Hook (bd-5otr)
- Created examples/startup-hooks/bd-version-check.sh
- Auto-detects bd version changes via .beads/metadata.json
- Shows bd info --whats-new when upgrade detected
- Auto-updates outdated git hooks
- Handles edge cases (no jq, not in beads project, etc.)
- Created examples/startup-hooks/README.md with integration examples
- Claude Code, GitHub Copilot, Cursor integration patterns
- Comprehensive usage and troubleshooting guide
- Updated examples/README.md with new startup-hooks section
## Impact
Agents can now:
- Automatically detect bd upgrades at session start
- See what changed without re-reading all documentation
- Keep git hooks in sync automatically
- Adapt workflows based on new features
Works today with zero bd code changes required!
Related: #239🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes#340
Created AGENT_INSTRUCTIONS.md to house detailed operational instructions,
reducing AGENTS.md from 963 to 626 lines (~35% reduction).
Changes:
- New AGENT_INSTRUCTIONS.md with development, testing, and release procedures
- AGENTS.md now serves as quick overview with references to detailed docs
- Updated README.md link to "Landing the Plane" section
- Fixed broken team-workflow README links
Benefits:
- Prevents context pollution when multiple tools add instructions
- Better separation: quick reference vs detailed operations
- Enables tool-specific instruction files
- Maintains all content, just reorganized
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>