* fix(update): resolve metadata/note merges inside the mutation transaction
bd update --metadata/--set-metadata/--unset-metadata/--append-notes and
bd note resolved their merges client-side: read the issue in one
transaction, merge in process memory, write the merged blob back in a
later transaction. Two concurrent writers touching DIFFERENT keys of
the SAME issue both exited 0, but the later commit silently erased the
earlier writer's committed keys. The multiprocess-safety audit proved
the loss empirically: 7 of 200 exit-0 --set-metadata writes vanished in
an 8-writer same-issue hammer against the stock binary.
The first version of this fix moved the merge into the mutation
transaction on the direct path only; red-team review blocked it because
the proxied-server route still snapshot-merged in
buildUpdateSpecForIssue — and worse: on a Dolt serialization rollback,
uow.CommitWithRetries retried only the COMMIT, re-committing the
rolled-back (now empty) session. Dolt answered "nothing to commit",
isDoltNothingToCommit swallowed it, and bd printed "Updated" and exited
0 for a write that never landed.
This revision closes both paths:
- Merge-shaped edits travel as operation keys (issueops.OpMergeMetadata,
OpSetMetadata, OpUnsetMetadata, OpAppendNotes) and are resolved
against the row re-read INSIDE the mutation transaction
(issueops.ResolveMergeOps) — in both the embedded path
(updateIssueInTx) and the domain/db repository used by proxied-server
mode. CLI paths (bd update, bd note) no longer pre-merge; the shared
merge helpers live in internal/storage.
- The in-transaction read takes a row write lock
(GetIssueForUpdateInTx, SELECT ... FOR UPDATE) so the read itself
serializes on Postgres (READ COMMITTED) and MySQL (REPEATABLE READ).
sqlitedialect strips the clause — safe because _txlock=immediate
already takes the database write lock at BEGIN. Dolt parses FOR
UPDATE as a no-op and relies on commit-time conflict detection plus
the whole-attempt retry below.
- The proxied server redoes the WHOLE read-merge-write attempt in a
fresh unit of work on a serialization failure (new exported
uow.IsSerializationError; exponential backoff, 15s budget), commits
each attempt exactly once, and fails loudly to stderr when retries
exhaust instead of exiting 0.
Verification: cross-backend regression body in
internal/storage/conformance/lostupdate.go (two independent store
handles plus a lock-holding third pool) wired into the sqlite, dolt
(embedded and sql-server), mysql, and postgres suites; cmd/bd
multi-process race tests for --set-metadata and bd note; proxied-server
attempt/retry unit tests. Re-running the audit hammer against the
patched binary: 0 lost of 200 exit-0 writes across natural and
lock-widened runs (stock binary lost writes in both), with the one
contention exhaustion surfacing as a nonzero exit instead of a silent
loss.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(update): string --set-metadata, proxied partial-failure exit, drop dead locking scaffolding
Maintainer adoption-review fixes for PR #4732 (review iterations 1 and 3):
- metadata: MetadataEditValue stores --set-metadata values as JSON strings
again (GH#4146) instead of inferring numbers/booleans/null from content,
which silently broke map[string]string round-trips. Typed values stay
available via --metadata / --metadata-json. Domain merge-op tests now
expect string values for --set-metadata.
- cmd/bd: restore the proxied multi-ID partial-failure accumulator so a batch
with any failed ID exits non-zero (had regressed #4726), and derive success
output from the resolved jsonOutput signal so --format json and config
json:true are honored on the proxied path.
- storage: remove the dead internal/storage/sqlitedialect package (509 LOC,
zero importers) and the FOR UPDATE / GetIssueForUpdateInTx row-locking
scaffolding. SQLite/Postgres/MySQL are gone and Dolt treats FOR UPDATE as a
parse-only no-op; the read-merge-write is made safe by commit-time conflict
detection plus the whole-attempt retry. Also drop the uncalled MVCC-only
conformance helper. updateIssueInTx returns to baseline complexity via a
small read-and-resolve helper.
- tests: remove the SQLite-backend race tests (the removed backend can't run
them); Dolt concurrency coverage in uow/embeddeddolt/domain-db is
load-bearing.
- readability: split ResolveMergeOps into resolveMetadataMergeOps and
resolveNotesAppendOp (with an isMergeOpKey helper) so each diff-authored
merge-op resolver stays below the review complexity gate (cyclomatic <21 /
cognitive <26). Pure structure change: same resolution order, error strings,
schema validation, and copy-not-mutate semantics.
- policy: allowlist TestUOW_ConcurrentMergeOps_NoLostUpdate in
scripts/check-testing-short.sh. Its testing.Short() skip is a legitimate
runtime/stress skip (it starts a Dolt container and a dbproxy subprocess),
matching the other allowlisted Dolt concurrency stress tests; without the
entry the ci-pr-policy check fails on the adopted head.
- tests: remove the two obsolete cmd/bd multi-ID tests
(TestMultiIDUpdatePartialMetadataMergeFailure and
TestMultiIDUpdatePartialMetadataEditFailureJSON) and their now-unused
seedNonObjectMetadata/showMultiIDUpdateMetadataValue helpers. They seeded a
non-object array via `bd update --metadata "[]"` to force a later per-ID
metadata-merge failure, but the new in-transaction merge correctly rejects
non-object metadata ("new metadata is not a JSON object"), so that seeding
path is unreachable and the tests now fail at setup. The four #4726 per-ID
exit-code tests in the same file are retained.
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>
Extend #4847's rollback to the last alternative backend: bd now ships a
single storage engine (Dolt, embedded and server mode).
- Delete internal/storage/{sqlite,sqlitedialect} and the packages the
removal orphans: sqlkit (sole importer was the sqlite store),
unsupportedgen (sole go:generate consumer), the NonCommitGraphBackend
marker and its two dead consumer checks, and the domain-db parity test
that used sqlite as its harness. Drop modernc.org/sqlite from go.mod
and regenerate the nix vendorHash.
- Tombstone backend="sqlite" exactly like postgres/mysql: recognized in
metadata (never silently aliased to a fresh Dolt DB), rejected before
any open with its own rationale and the export -> re-init -> import
guidance. The fail-closed guarantee now also covers never creating the
beads.db file the removed backend would have provisioned.
- bd init: --backend=sqlite reaches removed-backend guidance;
--sqlite-path becomes a hidden parser tombstone like the pg/mysql
flags; help text and supported-backend enumerations say Dolt only.
- Doctor: sqlite workspaces fail closed like the other tombstones; the
modern sqlite stub payloads are gone. The legacy pre-Dolt surface
(artifact scans, migration validation, migrate-sqlite-to-current.sh,
the migration-test harness) is untouched; genuine pre-Dolt workspaces
carry no backend field and never hit the tombstone.
- Conformance: drop the sqlite profile; the CLI differential runner
idles (skip, not fail) until another backend profile is registered,
and the export/import round-trip keeps running against the embedded
Dolt reference. Tier-1 oracle legs are unchanged.
Backend selection has never shipped in a release (v1.1.0 predates it),
so released workflows are unaffected and the pinned CLI docs already
describe the resulting behavior.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(pipeline): pin the generated CLI docs to the released bd; repair main's CLI reference
The #4874 squash-merge raced the docs-autofix bot: the bot had pushed a
regeneration from main's source onto the PR branch, so the squash landed a
contradictory mix — the release-aligned hand-written docs plus a CLI
reference re-documenting unreleased commands and flags, with docs.json
referencing four pages (heartbeat, migrate-personal, reclaim, unclaim)
whose files do not exist. That broken nav fails the docsync guard on main
and on every branch cut from it. This restores the intended end state of
#4874 and lands the pin that prevents the race from recurring.
- Regenerate the CLI reference from a bd built from the v1.1.0 tag (CI's
canonical pure-Go build), removing the unreleased commands/flags and
fixing the dangling nav entries.
- docs/cli-docs.pin names the release tag; scripts/resolve-docs-bd.sh
builds and caches a canonical pure-Go bd from that tag, fetching the tag
first in shallow CI checkouts.
- generate-cli-docs.sh, check-doc-flags.sh, and check-cli-docs-drift.sh
resolve bd through the pin and ignore a supplied binary while pinned
(BD_DOCS_IGNORE_PIN=1 bypasses), so the drift gates and the autofix bot
now enforce docs-match-release instead of docs-match-main.
- tools/docsmint detects the pre-overhaul Docusaurus staging layout that
bd <= v1.1.0 emits and converts it to the generic form before its normal
Mintlify transform (tested); removable once the pin reaches a release
whose emitter writes build/cli-docs.
- check-doc-flags.sh: run without timeout(1) on macOS instead of failing
Check 4.
- Decision record: engdocs/decisions/2026-07-17-docs-release-pin.md; the
beads-docs skill §8 updated to match.
* lint: annotate gosec G705 false positive in the docsmint legacy bridge
Same class as the existing nav-splice annotation: a developer tool writing
repo Markdown, not a web-output sink.
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
Query closing-issue presence through GraphQL nodes instead of the unsupported gh pr view field. Reject malformed and partial responses before applying contributor policy.
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Test User
Co-authored-by: Test User <test@test.com>
* fix(security,ci): redact all DSN password forms in telemetry; require pg/mysql conformance
Post-merge remediation for #4601 (choose-your-own-backend), reviewed landed
range 812ad6d..3f0474a. Addresses the two gating findings from the post-merge
review.
Security (telemetry DSN leak): scrubArgsForTelemetry only redacted
user:PASS@host userinfo, so `bd init --pg-url` URL `?password=`/`?sslpassword=`
query params and libpq `password=`/`sslpassword=` keyword/value forms leaked
into the bd.args telemetry span before init reached the parser-backed
redaction path. Route --pg-url/--mysql-url values (both `--flag=value` and
`--flag value`) through the parser-backed pgdialect scrubber via a new exported
pgdialect.ScrubDSNString; every other arg keeps the narrow userinfo scrub, so
ordinary text is never over-redacted.
CI (conformance anti-skip): scripts/conformance.sh ran the pg/mysql Tier-1
suites with no skip/PASS detector, so a missing BEADS_*_TEST_URL self-skipped
to green and silently narrowed backend coverage. Add require_backend +
run_sql_conformance mirroring the embedded-Dolt reference guard, and set
BEADS_CONFORMANCE_REQUIRE=postgres,mysql in conformance.yml (which also arms
the existing Tier-2 e2e hard-fail).
Tests: pgdialect TestScrubDSNString; cmd/bd TestScrubArgsForTelemetry (all DSN
password forms x both spellings) and TestScrubArgsForTelemetryLeavesOrdinaryArgs
(no over-redaction + userinfo defense-in-depth). Bash guards unit- and
integration-tested against real `go test` self-skip/required paths.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix(security): redact federation add-peer --password/-p from telemetry args
The bd.args telemetry root span scrubbed --pg-url/--mysql-url DSN passwords
but not federation add-peer's --password/-p, so `bd federation add-peer
<name> <url> --user u --password <secret>` leaked the plaintext SQL
password verbatim into the exported bd.args attribute and trace logs — the
same sink and harm class the DSN scrub already closed.
Redact by flag identity: secretFlagTokens resolves the secret flag's actual
--long/-short tokens from the running command, so -p is redacted only on the
command that binds it to --password (federation add-peer) and never on the
many commands that bind -p to --priority/--prefix/--parallel. The value is
redacted wholesale across every pflag spelling: --password <v>,
--password=<v>, -p <v>, -p=<v>, and the concatenated -p<v> shorthand.
Tests cover all five spellings, the command-aware token resolution, and the
no-over-redaction guarantee for the overloaded -p on non-secret commands.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix(security): redact raw encoded URL-userinfo passwords in DSN scrubber
Post-merge remediation follow-up review (attempt-4) for #4601: the shared
pgdialect DSN redactor missed percent-encoded URL-userinfo passwords when
called directly — ScrubDSNError in driver.go, and any telemetry/log sink that
scrubs a raw DSN through ScrubDSNString.
dsnPasswordValues added only url.User.Password(), which url.Parse returns
percent-DECODED, so ScrubDSNString("postgres://u:SUPER%2ASECRET@h/db", same)
left the raw "SUPER%2ASECRET" in error text and logs. The query-param branch
already adds both the raw and decoded forms; the userinfo branch now does too,
extracting the raw as-written password structurally (rawURLUserinfoPassword)
so it matches regardless of encoding form (mixed case, over-encoding).
Tests: add encoded-userinfo cases to TestScrubDSNError and TestScrubDSNString
(the latter now checks every leak form, matching TestScrubDSNError). Both new
cases fail on the pre-fix redactor and pass after.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix(security): close five telemetry DSN-redaction bypasses found in review
Test-first fixes, each reproduced against pgx.ParseConfig before fixing:
- percent-encoded query KEYS (pass%77ord=, %70assword=) are live password
params after url.Query() decoding; compare unescaped keys too
- pflag boolean-shorthand clusters (-qpSECRET parses as -q -p SECRET) leaked
the raw token; walk the leading letter run to the first secret shorthand
- backslash-escaped whitespace in unquoted libpq values (password=SUPER\ SECRET)
leaked the tail; value pattern now consumes escaped sequences
- pgx treats \v as DSN whitespace but Go regexp \s does not; spell the
whitespace class out explicitly
- overlapping secrets (one a prefix of another) leaked the longer tail;
replace longest-first in ScrubDSNString
Found by paired cross-vendor review (claude fable-5 + codex gpt-5.6-sol) on
PR 4712.
Agent-Signature: claude-fable-5-high on behalf of maphew
---------
Co-authored-by: Eddie the Engineer <test@test.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
- 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
- docsmint: all page rewrites (HTML-comment, relative-link, ESM) now skip
fenced code blocks; fence contents render verbatim
- docsmint: spliceCLINav fails closed when the "pages" key found after
"group": "CLI Reference" is not a sibling key of the same object, and
validates the spliced docs.json parses before writing
- docsmint: neutralize MDX ESM hazards in docs/CLI_REFERENCE.md too (bd
emits it without the per-page transforms, but Mintlify serves it as a
hidden page); regenerated docs/CLI_REFERENCE.md accordingly
- help_all: fail loudly when two commands collide on the same doc page ID
instead of letting the later write win; repair a garbled comment
- generate-cli-docs.sh: --check no longer trusts a repo-root ./bd it was
not explicitly given (the CGO guard detects CGO-ness, not staleness)
- docsync: validate the docs.json redirects array (well-formed, no dup
sources, destinations resolve)
- pour: runtime strings match the corrected Long text (Dolt sync, issue
database — not "sync to git" / "persistent in .beads/")
- testdata: formula_help.txt asserts the new docs/workflows/formulas.md path
check-build-tags requires every go test/go run in tracked scripts,
workflows, and the Makefile to carry -tags=gms_pure_go (ICU-linkage
guard): added to the docsync invocations in docs-mintlify.yml and
make check-docs, and to the docsmint stage of generate-cli-docs.sh
(the flagged workflow job name no longer embeds a bare invocation).
docsmint's two variable-path os.ReadFile sites get justified
#nosec G304 annotations — both read only repo-owned files derived
from the tool's repo-root argument. golangci-lint: 0 issues.
Three generated-content defects from the adversarial review, all
structurally invisible to the drift gate (generated-vs-generated):
- Usage lines now mirror Cobra's help template: a runnable command shows
its UseLine, a command with subcommands shows '<path> [command]', both
when both apply. Previously bare UseLine() stamped 'bd mol [flags]' on
30 parent pages — a line the binary never prints.
- The generated CLI index publishes the Global Flags block; the binary
prints it on every --help but no page carried it.
- docsmint neutralizes prose lines that Mintlify's prebuild would dedent
into MDX ESM blocks (a line beginning 'export'/'import' outside a
fence gets wrapped in a code span). This is why /cli-reference/mail
returned HTTP 200 while rendering only a parse-error placeholder —
reproduced, fixed, and covered by a planted-hazard test; fenced
content stays verbatim.
Also rewords check-cli-docs-drift.sh's early-PASS message, which
asserted 'the supplied binary differs' as the cause when uncommitted
local edits produce the same result.
All 113 pages + docs/CLI_REFERENCE.md regenerated through the pipeline;
TDD'd in cmd/bd/help_all_test.go and tools/docsmint/docsmint_test.go.
Verified live: /cli-reference/mail renders real content, zero parse
errors; generate-cli-docs.sh --check, docsync, freshness, and
mint broken-links all pass on this tree.
Per the decision record: no parallel run and no cutover PR. Removes
website/ (including the four versioned doc snapshots — current-only
versioning; snapshots remain in git history), deploy-docs.yml,
generate-llms-full.sh (Mintlify serves llms.txt natively), the ci-website
package gate (Makefile target, scripts/ci/website.sh, the package-website
jobs and their aggregate-gate entries in pr.yml/main.yml/release.yml, the
ci-measurements suite, detect-package-gates wiring), and the release-time
docs snapshot flow (snapshot-release-docs.sh, check-docs-version.sh, their
call sites in update-versions.sh/check-versions.sh, RELEASING.md section
rewritten for the Mintlify reality).
Drift machinery now covers exactly the Mintlify artifacts:
check-cli-docs-drift.sh pathspecs/fingerprint, docs-autofix-push.sh
allowlist, and check-doc-flags.sh scans drop the website/llms paths. The
beads-docs skill's generated-content and verification sections updated to
the bd-generic + docsmint pipeline.
NOTE for merge time: if branch protection requires the 'Package Gate
(website)' check by name (rather than the aggregate gate), drop it from
the required checks or PRs will wait forever.
Gates: docsync PASS, generate-cli-docs.sh --check PASS, freshness PASS.
Per the decision record (engdocs/decisions/2026-07-10-mintlify-docs-overhaul.md):
bd's doc generator is vendor-neutral. `bd help --docs-root` now writes
docs/CLI_REFERENCE.md plus a generic per-command tree (title/description
frontmatter, portable CommonMark, HTML-comment markers) into build/cli-docs/
— uncommitted staging, gitignored. All site-generator-specific output leaves
the binary: Docusaurus frontmatter, sidebarPositionMap, the website/ writers,
the Mintlify writers, the docs.json nav splice, and the --docs-version
snapshot flag are gone from cmd/bd.
tools/docsmint (Go, unit-tested) is the Mintlify post-processor: it turns
the staging tree into the committed docs/cli-reference/ pages (JSX comment
markers, extensionless route links) and splices the CLI Reference pages
array in docs/docs.json. scripts/generate-cli-docs.sh runs both stages;
--check seeds the committed artifacts into a scratch root, regenerates, and
diffs, exactly as before.
Regenerated output: the 113 pages are byte-identical through the new
pipeline; docs.json nav ordering is now plain filename sort;
docs/CLI_REFERENCE.md drops the removed --docs-version flag.
`bd help --doc <cmd>` stdout is likewise generic now (no Docusaurus
id/slug/sidebar_position).
Sixteen same-ground pairs reconciled: the ported website page won and every
fact living only in the older docs/ original was merged in before deleting
it (INSTALLING, SETUP, ARCHITECTURE, CONFIG, GIT_INTEGRATION, ADVANCED,
TROUBLESHOOTING, FAQ, MOLECULES, ROUTING, MULTI_REPO_AGENTS, and the five
agent-integration guides). The two divergent FAQs are now one canonical
FAQ with the comparison-first framing leading and pre-1.0 version gating
removed.
The routing pair inverted: the ported page described a routing system that
does not exist (bd routes, bd hydrate, .beads/routes.jsonl); the page was
rebuilt from the accurate sources (ROUTING.md + MULTI_REPO_AGENTS.md)
against the real surface (routing.mode config, role detection,
repos.primary/additional hydration, --repo override).
Every claim was verified against the Go source or the generated CLI
reference. Phantom surfaces removed across the corpus: bd pin/hook/pour/
wisp/routes/hydrate/reserve/lock/merge/stats, bd hooks status, bd vc
conflicts/log, bd dolt set shared-server, fictional beads_* MCP tool names
(real names taken from beads-mcp server.py), import.orphan_handling and
export.error_policy config keys, database.wal_mode/cache_size, stale
.beads/dolt/sql-server.log paths, and SQLite-era file paths. Notable
corrections: min_hash_length default is 3, .beads/metadata.json is
git-tracked, tombstone status is removed, wisps live in the main database
under an ephemeral flag.
Freshness markers moved with their content (configuration, ide-setup) and
the freshness gate + DOC_INVENTORY ledger now point at the new locations.
Load-bearing anchors preserved: #branchless-workflows-jujutsu--jj,
#circuit-breaker-server-appears-down-failing-fast, #extensible-database,
#multi-repo-hydration. Pointer stubs remain at docs/{SETUP,INSTALLING,
GIT_INTEGRATION}.md because released binaries print those paths
(allowlisted in the docsync guard).
Gates: go test ./test/docsync PASS; generate-cli-docs.sh --check PASS;
check-doc-freshness.sh PASS; mint broken-links: no broken links; mint dev
serves all sections (11 routes spot-checked at 200).
- 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.
bd help --docs-root now additionally writes docs/cli-reference/ in Mintlify
form (frontmatter title as H1, extensionless root-relative links, JSX
auto-generated markers since Mintlify parses .md through MDX) and rewrites
the CLI Reference pages array inside docs/docs.json via a textual splice
that leaves the rest of the file byte-identical — the ~113 nav entries are
never hand-maintained. The Docusaurus outputs (docs/CLI_REFERENCE.md,
website/docs/cli-reference/, versioned snapshots) are unchanged.
generate-cli-docs.sh --check seeds docs/docs.json and docs/cli-reference/
into its scratch root and diffs both; check-cli-docs-drift.sh adds them to
GEN_PATHSPECS and the regeneration fingerprint; docs-autofix-push.sh
allowlists the new generated paths; check-doc-flags.sh scans the new
docs/ subdirectories and requires command coverage in docs/cli-reference/.
Includes the initial docs/docs.json scaffold (nav mirrors the Docusaurus
sidebar IA) and the generated docs/cli-reference/ pages.
TDD: new emitter behavior covered in cmd/bd/help_all_test.go
(Mintlify page format, nav splice correctness + idempotence, bare-root
generation without docs.json).
Port the website's current (non-versioned) authored pages into docs/ as
Mintlify pages: frontmatter title as H1 (body H1s removed), Docusaurus
admonitions converted to Mintlify components, root-relative extensionless
links, mermaid fences kept as-is. website/docs/** is untouched and keeps
serving the Docusaurus site until cutover.
git-mv the user-facing docs/ originals with no website twin into the new
IA (core-concepts/, architecture/, workflows/, recovery/, multi-agent/,
integrations/, reference/), converted to Mintlify form. The six files
previously mirrored by sync-website-docs.sh now live once in the site.
ERROR_HANDLING.md and CONTRIBUTOR_NAMESPACE_ISOLATION.md move to engdocs/
(contributor pattern guide and design doc per content review).
Pointer stubs remain at docs/{DOLT,STORAGE-BACKENDS,PLUGIN,RECOVERY,
JSON_SCHEMA}.md because released bd binaries print those paths; QUICKSTART
and DOLT-BACKEND stay as existing pointer stubs.
Corrected while porting: the intro's storage diagram claimed data lives at
.beads/dolt/; embedded mode (the default) uses .beads/embeddeddolt/
(internal/storage/embeddeddolt/store.go), server mode uses .beads/dolt/.
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).
Maintainer fixup for the choose-your-own-storage-backend PR, amended across the
pre-review CI-repair and the review-loop apply-fixes iterations so contributor
commits stay intact under one maintainer commit.
CI repair (pre-review):
- default.nix: bump vendorHash for the added Postgres/MySQL driver deps.
- conformance.yml: provision the Postgres service DB with a C-locale cluster so
text ORDER BY sorts by code point, matching Dolt's utf8mb4_0900_bin oracle.
Review fixes — blockers:
- uow/doltserver_tx: on a non-serialization DOLT_COMMIT failure, ROLLBACK on the
pinned session before releasing it, and poison (pool-discard via driver.ErrBadConn)
the connection when the rollback also fails, so a later borrower can't inherit an
open transaction and implicitly commit orphaned writes. Satisfies the existing
doltserver_tx_test rollback/poison cases.
- sqlitedialect: translate GREATEST/LEAST to SQLite scalar max/min so the
ReconcileChildCounters upsert (GREATEST(last_child, ?)) no longer aborts creation
or import of hierarchical dotted issue IDs (e.g. x-1.2) on the SQLite backend.
Review fixes — majors:
- conformance: add a portable dotted hierarchical child-ID scenario (x-1, x-1.1,
x-1.2, x-1.2.1) exercising the ReconcileChildCounters GREATEST path on every
backend — the coverage hole that let the SQLite blocker ship green. Verified
against the embedded-Dolt oracle and the real SQLite driver.
- postgres: warn at provision/open when the database collation is not code-point
ordered (C/POSIX/C.*), since text ORDER BY otherwise diverges from Dolt silently.
- sqlite: pin the pool to one connection and add busy_timeout + WAL to the DSN so
overlapping operations wait instead of surfacing a raw "database is locked"
(matches the Dolt backend's single-connection posture). Adds a concurrency guard.
- cmd/bd: gate explicit `bd dolt commit` / `bd vc commit` with a typed
storage.ErrUnsupported on non-Dolt backends instead of the no-op Commit printing
"Committed."; internal opportunistic auto-commit is untouched.
Review fixes — attempt 2 (stale init backend-flag test contract):
- cmd/bd/init_test, init_embedded_test: the init backend-flag tests still asserted
the pre-#3151 one-backend contract (--backend=sqlite must fail "SQLite backend
has been removed"; --backend=postgres is an "unknown backend"), so
`go test ./cmd/bd -run '^TestInitBackendFlag$'` failed in a clean environment now
that sqlite/postgres/mysql are supported pluggable backends. Rewrite
TestInitBackendFlag and the cgo TestEmbeddedInit sibling (rejected_backends →
sql_backend_flags) for the new contract: --backend=sqlite initializes and
persists backend=sqlite; --backend=postgres is recognized and fails only on
missing connection config (not "unknown backend"); a genuinely unknown backend
is still rejected. Pin BEADS_DIR and scrub BEADS_*/BD_* so the subtests are
hermetic against an ambient .beads or Dolt server.
Cleanups (non-gating):
- cmd/bd/init: extract checkExistingSQLBackend so the added SQL-backend branches
don't inflate checkExistingBeadsDataAt's complexity, and load config once.
- configfile: correct the stale "Deprecated: always dolt" Backend field comment.
Review fixes -- attempt 3 (SQLite datetime parity blocker + conformance/rewrite
hardening of the storage-parity gate):
- sqlite/dsn: add _time_format=datetime. Without it modernc binds time.Time via
t.String() ("2026-07-09 12:34:56.123 +0000 UTC"), a shape SQLite's date functions
cannot parse, so the counts mega-query's DATE_FORMAT(created_at,...) (strftime on
SQLite) returns NULL and deps_json exposes a zero created_at while Dolt emits the
real timestamp. datetime stores whole-second "2026-07-09 12:34:56", matching
Dolt/MySQL datetime(0). Verified end-to-end against the real modernc driver.
- conformance: add ReadyWorkDepCreatedAtParity -- imports a dependency with a known
created_at (the bd import / CreateIssuesWithFullOptions bound-time.Time path) and
asserts the counts-rendered deps_json created_at equals it, closing the blind spot
that let the SQLite blocker ship green (the counts tests only checked DependencyCount).
Proven to fail on the pre-fix DSN and pass on both the fixed SQLite backend and the
embedded-Dolt oracle.
- conformance: add ClaimReadyIssueConcurrentExclusivity -- races 24 workers over 8
ready issues and asserts each is claimed exactly once, exercising the SQL backends'
multi-writer claim property that was previously only asserted, never raced. Gated to
the multi-connection dialects (postgres/mysql) via DialectName; SQLite (single-conn
pool) and embedded-Dolt skip.
- conformance.sh: run the embedded-Dolt reference conformance with
BEADS_TEST_EMBEDDED_DOLT=1 and fail loudly if it skips. It self-skips without the env
var, so the parity gate was reporting success while never running the reference oracle.
- mysqldialect: drive the is_blocked-recompute error-1093 rewrite test from the real
issueops templates (new issueops.SelfReferentialRecomputeTemplates) instead of a
hand-copied fixture, so template drift fails a non-gated test rather than only the
env-gated MySQL conformance suite. All four mark/unmark x issue/wisp templates
verified rewritten into the materialized derived-table form.
Note: the review re-flagged TestInitBackendFlag as failing, but it passes in a clean run
(plain and gms_pure_go, matching the scorecard's own rerun); the only cmd/bd failure in
this sandbox is an unrelated pre-existing embedded-Dolt/CGO test not in this PR's diff.
Review fixes -- attempt 4 (conformance-gate self-brick + all-wisps inline-dependency
drop blockers; Postgres error-log password-leak major):
- conformance.sh: anchor the embedded-Dolt reference skip/pass guards to top-level
result lines (^--- SKIP/PASS: TestConformance). The attempt-3 loud-fail guard used
an unanchored grep, so the indented, legitimate subtest skip of
ClaimReadyIssueConcurrentExclusivity (embedded-Dolt is single-writer) matched it and
false-failed the entire storage-parity gate on every run even when the top-level
suite passed. Whole-suite-skip protection is preserved.
- sqlkit/portable + embeddeddolt/create_issue: the all-wisps arm looped the
single-issue issueops.CreateIssueInTx, which runs no batch dependency-persist pass,
so an all-wisps batch carrying inline dependencies (e.g. importing no-history beads
with inter-bead edges -- export DOES include no-history beads, GH#2619) silently
dropped every edge (not even reported via OnSkippedDependency) and, one transaction
per issue, forfeited batch atomicity. Both now mark ephemeral, then run the whole
batch in ONE transaction through issueops.CreateIssuesInTx, matching the server-mode
DoltStore all-wisps arm. The embedded-Dolt reference oracle had the same latent drop,
so the oracle and the new SQL backends were corrected together to keep conformance
parity (the finding compared sqlkit against the server-mode DoltStore, which already
persisted these edges).
- conformance: add CreateAllWispsInlineDependencies -- an all-wisp batch with one valid
inter-wisp edge and one unresolvable edge; asserts the valid edge persists and the
unresolvable one is reported via OnSkippedDependency. Fails on the pre-fix per-issue
loop, passes on the batch path; verified on SQLite and the embedded-Dolt oracle, with
a full embedded-Dolt conformance re-run clean.
- pgdialect: scrub query-param/sslpassword secrets from pgx ParseConfig errors in Open
and OpenRaw (new ScrubDSNError). pgx's ParseConfigError redacts only URL userinfo, so
a postgres://u@h/db?password=SECRET DSN (the shape bd init connects with) leaked the
cleartext secret through the wrapped parse/TLS-config error into logs. Connect-time
errors were verified not to carry the password. Adds redact_error_test coverage for
the query-param, sslpassword, userinfo, and libpq-keyword shapes plus the real
Open/OpenRaw parse-failure path.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Rebase of PR #4601 (feat/choose-your-own-backend) onto current origin/main,
squashed to a single commit because the original 73-commit history built and then
removed the uowStore derisk spike incrementally, which does not replay cleanly
over the 125 commits main has since advanced (notably #4679, the ready-work
counts fix, which merged to main and is now inherited rather than re-applied).
The full pre-rebase history remains on the original branch tip for reference.
Contents (multi-backend feature + the six review follow-ups):
- bd init --backend=postgres|mysql|sqlite provisioning behind the Dolt-parity
seam; the three SQL backends share *sqlkit.Store over pluggable dialects and
carry a generated typed-unsupported shell for the non-core surface.
- Passwords in init DSNs are redacted before persisting to metadata.json (driver
parser + re-parse verification), with a negative-test matrix proving no secret
survives (pgdialect + mysql).
- The uowStore derisk spike and its report artifacts are removed; the shell
generator now lives in internal/storage/unsupportedgen (neutral name).
- Compile-time guard `var _ storage.DoltStorage = (*Store)(nil)` on each backend
plus a regen-idempotence test keep the generated skip lists honest.
- sqlkit exposes CountReadyWork so every SQL backend satisfies
storage.ReadyWorkCounter and inherits the shared page-pushed ready-counts path.
- Commercial/product names scrubbed from the feature's own code for vendor
neutrality.
Rebase reconciliations: adopted main's metadata-load hardening in the store
factories alongside the backend dispatch; combined the config interface
(GetMetadata + ReconcileVersion) and the conformance registrations (ReadyCounts +
Claim/lease); took main's versions of the shared-infra concurrency (uow
doltserver_tx) and delete-cascade (domain/issue_delete) evolutions; implemented
the interface's new UnclaimIssue on sqlkit (delegating to issueops) and added it
to the skip lists.
Verified: go build (cgo + CGO_ENABLED=0) and go vet clean; unit tests
(sqlbuild/issueops/pgdialect/mysql/unsupportedgen) and the SQLite conformance
suite green (RunAll, incl. ReadyCounts equivalence and Claim/lease on the real
sqlkit backend).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(website): refresh committed sync-website-docs mirrors
Regenerate the Docusaurus mirrors of docs/METADATA.md and
docs/COMMUNITY_TOOLS.md with scripts/sync-website-docs.sh: the metadata
mirror was missing the "portable hints" paragraph and the gh-3541
resolution wording (#4358), and community-tools.md was missing five
entries (bd-board, Bead Me Up Scotty, beads.nvim, BeadSpec, LoopTroop)
present in the source doc. sync-website-docs.sh also regenerates the
versioned_docs/version-1.1.0 copies, so both metadata.md drift sites are
fixed by running the script; no manual versioned_docs edit was needed.
Agent-Signature: claude-sonnet-5-high on behalf of matt wilkie
* ci: add website-docs drift gate to pr.yml
Add scripts/check-website-docs-drift.sh, mirroring the seam
scripts/check-cli-docs-drift.sh uses in the check-doc-flags job: run the
generator (scripts/sync-website-docs.sh) and fail if it produces any diff
against the committed website/docs and website/versioned_docs mirrors.
Unlike the CLI reference docs, the website-docs mirror is a pure text
transform of files already committed in this repo, so no bd binary build
and no merge-base attribution are needed; the check backs up the tree,
regenerates, diffs, and restores the tree either way so it is
side-effect-free.
Wire it into the check-doc-flags job in .github/workflows/pr.yml as a new
"Validate website doc mirrors" step alongside "Validate docs against CLI".
Not extended: the docs-autofix.yml / docs-autofix-push.sh auto-push loop
that closes the loop for CLI docs drift. That pipeline is a nontrivial
addition (patch artifact, path allowlist, workflow_run consumer) built
specifically around generate-cli-docs.sh's build-dependent regeneration;
extending it for the website mirrors is left as a follow-up rather than
bolted on here.
Agent-Signature: claude-sonnet-5-high on behalf of matt wilkie
* docs: regenerate llms-full.txt for refreshed website mirrors
The mirror refresh changed website/docs content (metadata.md portable-hints
paragraph, community-tools.md new tools), and llms-full.txt is generated
from those pages. CI's check-doc-flags caught the stale committed copy;
this applies the cli-docs-freshness-patch artifact from run 28923961592's
PR job verbatim.
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
* ci(docs): auto-apply CLI docs regeneration to PR branches
The check-doc-flags gate already computes the exact regeneration patch
with CI's canonical build and uploads it as an artifact; contributors
still had to notice, download, and apply it by hand - a recurring
friction point (most recently the 2026-07-07 agent.profile drift).
Close the loop with a workflow_run job: on a failed PR run that left
the cli-docs-freshness-patch artifact, push the regen commit to
same-repo PR branches, or leave an idempotent comment with the apply
recipe on fork PRs (always - no token we hold can push to a fork).
Security: the privileged side checks out base main only and treats the
patch as untrusted data. An anchored allowlist (single path segment,
no traversal, symlink modes refused) pins which files may change, and
git apply --index supplies the underlying escape guards, so a hostile
patch can at most rewrite generated docs on its own PR branch. A
circuit breaker refuses to stack autofix commits if regeneration ever
stops converging.
Default-token pushes do not retrigger PR checks; an optional
DOCS_AUTOFIX_TOKEN secret upgrades same-repo PRs to fully hands-off.
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ci(docs): split API token from push token in docs-autofix
Review finding (maphew, 2026-07-07): with a contents-only
DOCS_AUTOFIX_TOKEN configured, all gh api calls used the PAT, so the
push would succeed and the comment endpoints would 403 (they need
pull-requests write). gh api now always uses the workflow token, which
carries this job's pull-requests:write; the optional PAT flows only
into the git extraheader for the push, so contents:write remains the
complete requirement documented for it.
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
CI installed golangci-lint v2.9.0 via `go install` in main.yml and pr.yml,
while .pre-commit-config.yaml pinned v2.10.1. Under v2.10.1, gosec's taint
analysis (G702/G704/G705) and secret-pattern check (G117) surface 8 new
findings that v2.9.0 does not report, so contributors running pre-commit
hit lint failures CI never shows and can't reproduce locally against CI's
pinned version.
Bump the CI `go install ... @v2.9.0` pins to v2.10.1 in main.yml, pr.yml,
and ci-measurements.yml so CI and pre-commit run the same version.
Triage the 8 new findings against v2.10.1:
- internal/github/client.go G704 (SSRF via taint on c.HTTPClient.Do):
same category as the existing G704 exclusion for gitlab/jira/linear API
clients with user-configured URLs; add it to that path list.
- internal/linear/oauth.go G704 (SSRF via taint on m.client.Do): same
category, OAuth token endpoint is user-configured; add to the G704 path
list alongside linear/client.go.
- internal/linear/oauth.go G117 x2 (ClientSecret, AccessToken exported
fields matching secret patterns): same category as the existing G117
exclusion for jira/client.go and linear/types.go; add oauth.go.
- internal/linear/client.go G705 (XSS via taint on fmt.Fprintf to
os.Stderr): CLI stderr output, no browser context - same category as
the existing G705 exclusion for cmd/bd/compact.go; add linear/client.go.
- scripts/repro-dolt-prod-timeouts/main.go G704 (SSRF via taint on
net.DialTimeout to 127.0.0.1) and G702 x2 (command injection via taint
on exec.CommandContext with cfg.BDPath): throwaway local repro tool
probing a locally started dolt server with fixed subcommand args and an
operator-supplied binary path; resolved with inline `#nosec` comments
matching the existing style in this repo (e.g. init_stealth.go, dolt
store.go) rather than a repo-wide .golangci.yml exclusion.
Verified: golangci-lint v2.10.1 (installed to a private GOBIN outside the
repo tree) reports 0 issues with --build-tags=gms_pure_go ./..., `go build
-tags gms_pure_go ./...` passes, and `go test -tags gms_pure_go
./internal/github/... ./internal/linear/...` passes.
Claude-Session: https://claude.ai/code/session_01FWVnjn3Bq4PSG1akpFpKnY
Agent-Signature: claude-sonnet-5-medium on behalf of matt wilkie
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
The migration-test harness (scripts/migration-test/) already builds a
BUG->TASK dependency fixture (create_dataset in lib/features.sh: `dep add
"$bug_id" "$task_id"`, i.e. bug depends on task, task is the blocker) and
migrates it in place with the candidate binary, but only verified fidelity
via bd list/show JSON. It never exercised bd's blocker-aware query paths on
the migrated DB, which is exactly the surface of the historical `bd close`
Dolt errno 1105 failure on a stale post-migration dependency schema
(verified manually for the 1.0.5 release in mybd-kdxj).
Add check_blocker_paths() in lib/snapshot.sh, run against the migrated DB
after check_fidelity in all three harness outcomes (direct upgrade, recipe
fallback, stepping-stone) plus the --self-test path:
- bd blocked lists the dependent (bug) while the blocker (task) is open
- bd ready excludes the dependent but includes the open blocker
- bd close on the blocker succeeds post-migration (the errno 1105 path)
- bd ready then lists the dependent (unblock/is_blocked recompute)
Violations fold into the existing violation count and flip AUTO/MANUAL
results to BLOCKED so a regression fails the harness loudly, matching the
existing report.sh exit-code convention. Skips gracefully when the source
version's dataset has no dependency.
cross-version-smoke.yml's parallel gate (scripts/upgrade-smoke-test.sh)
already added equivalent Scenario 6 blocker-path assertions in #4238; no
change needed there.
Verified: `--self-test` (candidate -> candidate, no downloads) and a real
`v0.63.3 -> candidate` direct upgrade both pass with the new BLOCKER-CHECK
line green.
Agent-Signature: claude-opus-4-8-high on behalf of matt wilkie
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* test: port Windows hardening fixes
Port the live Windows/test hardening fixes from contributor PRs #3797, #3801, #3802, #3806, and #3812 onto current upstream/main.
#3801 is applied to the moved dbproxy server test path. The release-script test harness also normalizes Bash-visible paths so the fake bd is selected reliably from Windows-hosted test runs.
Co-authored-by: sms <114885497+seanmartinsmith@users.noreply.github.com>
Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie
* fix(test): keep release-script fixtures out of source tree, preserve PATH
releaseTestTempDir previously created .tmp-release-tests under the
source repo root, requiring a writable checkout to even start the
release-script tests. Use t.TempDir() instead so the tests run from
read-only checkouts and packaging build directories.
runReleaseDryRunWithEnv hard-coded PATH to "<fakebin>:/usr/bin:/bin",
dropping the caller's PATH entirely. On systems where bash or core
utilities live elsewhere (e.g. Nix/Guix), the inner `bash
scripts/release.sh` invocation then failed. Prepend the fake bd
directory to the caller's actual PATH (converted per-entry via
shellPath for Bash) instead of replacing it.
Addresses Codex cross-vendor review finding (2026-07-07) on PR #4600.
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
Keep the base-branch CI verdict aligned with PR check handling by treating timed_out and action_required workflow conclusions as red. Cancelled runs remain ignored because they are normally superseded pushes.
Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie
During 2026-07-05..07-07 upstream main was red for ~33 hours while ~50
salvaged PRs merged. Every open PR inherited the red checks, so "failures
are pre-existing" became the default reasoning and three further breakages
(errcheck, testing.Short policy, unclaim test regressions, plus a -race
prune flake) rode in under that cover until #4623/#4624 batch-fixed main.
pr-preflight.sh now reports the base branch's CI health next to the PR's
own check status: for each workflow, judge by its newest completed run
that finished success-or-failure (cancelled runs are superseded pushes
and carry no signal; a green unrelated workflow that ran last must not
mask a red test workflow). Red base emits a warn by default explaining
the pre-existing-failure trap and the merge-only-the-fix rule;
PR_PREFLIGHT_BLOCK_RED_BASE=1 escalates it to a blocking finding.
Degrades to a warn (never a hard error) when gh cannot list runs for the
repo, so preflight keeps working on repos without Actions.
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* pm: decompose be-zej8mz → 3 builder beads for reference-aware prune
Child beads:
- be-jewoem: core implementation in cmd/bd/purge.go
- be-u2mw2x: --help and README docs update
- be-0wt833: bench asserting <5s on 10K-open-bead fixture (blocked on core)
Plan at docs/plans/reference-aware-prune.md.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(prune): reference-aware bd prune skips closed beads cited by open beads (be-jewoem, be-u2mw2x)
Implements be-5sn FR-01 through FR-06:
- buildReferencedSet scans description/notes/comments of every non-closed
bead for literal candidate IDs using word-boundary regexp alternation.
Uses Statuses filter (not ExcludeStatus) to avoid the PG coverage gap
(be-jdeief guardrail per be-5sn §15).
- runPurgeOrPrune filters referenced beads after pinned-filtering when
scope.cmdName == "prune" && !scope.ignoreReferences.
- All 4 human output paths updated: preview, dry-run, force, nothing-to-do.
referenced_skipped/referenced_count always in prune JSON; absent in purge.
referenced_ids_sample omitted when 0 (per be-zej8mz §5).
- --ignore-references flag registered in pruneCmd.Flags() only; purge
init() unchanged so bd purge --ignore-references gives "unknown flag".
- pruneCmd.Long gains reference-protection paragraph per be-zej8mz §3.
- README.md adds Maintenance section documenting prune, purge, and the
reference-aware skip with --ignore-references escape hatch.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* test(prune): NFR-02 bench test for buildReferencedSet on 10K-bead fixture (be-0wt833)
TestPruneLargeFixture generates 10K open beads × ~5KB bodies + 100 closed
candidates with 20 seeded references; asserts buildReferencedSet completes
<5s and returns exactly the seeded IDs.
Passes in ~1.2s on a standard dev machine. Skips under -short.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(prune): regen CLI reference + release gate PASS (be-jewoem)
Regenerate CLI docs with CGO_ENABLED=0 -tags gms_pure_go binary built
from PR HEAD. Adds --ignore-references flag to prune command docs in
CLI_REFERENCE.md and three website prune.md pages.
Gate evaluation: all 6 criteria PASS (AC-6 integration tests deferred
to be-zkzw per reviewer).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(contributor): bd-umbf contributor namespace isolation (Children 1-3)
Child 1 (be-c7696f): Auto-configure contributor routing in bd init
when upstream remote is detected. Non-interactive, idempotent — skips if
routing.contributor is already set. Creates ~/.beads-planning, sets
routing.mode=auto, routing.contributor, sync.remote=upstream, and pins
git beads.role=contributor.
Child 2 (be-9d2b67): bd export --exclude-owner flag and config-driven
export.exclude_owners / export.exclude_owner config. Filters issues by
created_by before writing JSONL. --verbose emits filtered count.
Child 3 (be-3c5a0f): New bd migrate-personal command. Finds project DB
issues whose created_by matches the current git identity, prompts for
confirmation, then moves them to the planning repo (routing.contributor),
copying labels, dependencies, and comments atomically.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(init): match autoConfigureForkContributor output to be-0ccf34 design spec
Three variants were missing; the one present used wrong symbol (✓ instead of ▶).
Happy path: ▶ header, upstream URL echoed, three ✓ action lines, opt-out hint last.
Opt-out path (--role=maintainer on a fork): ⚠ with explanation and recovery hint.
Re-init path (routing already configured): ⚠ with existing path and reconfigure hint.
Non-interactive/quiet: silent (unchanged).
Pass roleFlag through to autoConfigureForkContributor so the opt-out variant fires
when --role=maintainer is given explicitly on a fork.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(contributor): separate insert/delete phases in migrate-personal; suppress nonInteractive output
migrate-personal now copies all issues to planning DB first, then
deletes them from project DB in a single transaction via DeleteIssues.
A mid-loop failure before the delete phase leaves no issues deleted,
making re-runs safe.
Also pass quiet || nonInteractive to autoConfigureForkContributor so
bd init --non-interactive does not emit fork-detection output.
Fixes B4 and the nonInteractive gap from be-72b53f review.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(prune): regen CLI reference — add bd migrate-personal, update bd export flags
Regenerated from bd 1.0.4 dev (9ed33b68d) with CGO_ENABLED=0 -tags gms_pure_go.
Fixes B1: bd migrate-personal was missing from docs/CLI_REFERENCE.md and
all website cli-reference pages.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(gate): update be-jewoem release gate to cover bd-umbf scope
Expands gate scope from be-jewoem/be-u2mw2x only to include bd-umbf
Children 1-3 commits added to the branch. Documents blocker resolution
status (B1/B2/B4 resolved, B3 pending validator), updates CI results to
latest all-green run 26009209774, and marks overall gate ON HOLD pending
validator tests.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(gate): update be-jewoem gate — PR description refreshed, B3 dependency chain clarified (2026-05-19)
* test(contributor): be-f9a104 — bd-umbf export+migrate-personal tests
6 tests for bd-umbf Children 2-3 per be-f9a104 scope:
cmd/bd/export_exclude_owner_test.go (be-9d2b67):
- TestExportExcludeOwner_flag: --exclude-owner=alice filters alice's issues
- TestExportExcludeOwner_config: export.exclude_owners config drives filter
- TestExportExcludeOwner_verbose: --verbose reports filtered count
cmd/bd/migrate_personal_test.go (be-3c5a0f):
- TestMigratePersonal_noopWhenEmpty: no matching issues → 0/success
- TestMigratePersonal_movesIssues: personal issues moved to planning repo
- TestMigratePersonal_abortOnNoConfirm: EOF stdin → abort, issues stay
All gate on BEADS_TEST_EMBEDDED_DOLT=1. Fork-detection init tests
covered by be-de99a6 (tests/be-de99a6-fork-detect) per PM scope.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(test): be-36oa — skip TestMigratePersonal_movesIssues on Dolt unavailable
Broaden the skip condition in TestMigratePersonal_movesIssues to also skip
when the planning dir's Dolt server is unavailable (BEADS_DOLT_AUTO_START=0
leaves port=0, causing dolt.New() to fail). Adds "dolt", "cannot connect",
and "server" to the skip-trigger strings alongside the existing routing
and actor-mismatch conditions.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* test(init): be-de99a6 — fork-detection UX output format tests
4 embedded tests for autoConfigureForkContributor output per be-de99a6:
- TestBdInit_ForkAutoContributor: upstream remote → 'Fork detected' in output,
routing.mode=auto set
- TestBdInit_ForkAutoContributor_Idempotent: second init run → routing.mode
still 'auto' (no double-write)
- TestBdInit_ForkAutoContributor_MaintainerFlag: --role=maintainer → routing.mode
NOT set to auto
- TestBdInit_ForkAutoContributor_NonInteractive: --quiet → no '▶' block, but
routing still configured
All gate on BEADS_TEST_EMBEDDED_DOLT=1. Uses initForkRepo helper to
add upstream remote for fork detection.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(bd-umbf): be-jewoem B3 — fix yaml/DB store mismatch in export owner-filter and fork routing
Two real bugs found while landing the B3 validator tests:
1. buildOwnerExcludeSet (export.go) was only reading export.exclude_owners
from the database. The export.* prefix is yaml-only (config.yaml), so
config set via 'bd config set export.exclude_owners' was invisible to the
filter. Now reads yaml first, falls back to database.
2. autoConfigureForkContributor (init_contributor.go) was writing
routing.mode, routing.contributor, and sync.remote via store.SetConfig
(database). Those keys carry the routing.*/sync.* prefixes which are
yaml-only. Reading back via 'bd config get routing.mode' always returned
empty. Now uses config.SetYamlConfig for these keys; idempotency check
updated to read from yaml too.
Also: update TestBdInit_ForkAutoContributor to verify routing config state
rather than output text (suppressed in non-TTY test environments); remove
temporary debug_fork_test.go; mark B3 RESOLVED in release gate.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(lint): drop unused ctx+store params from autoConfigureForkContributor
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* chore: release gate PASS for bd-3852 (orphaned children doctor check)
* fix(rebase): update second autoConfigureForkContributor call to 2-arg signature
Later commits in this branch dropped ctx and store params from
autoConfigureForkContributor. The second call site added by be787e4b5
still used the old 4-arg form; update to match the final 2-arg form.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(rebase): drop #4028-superseded fork-detect; take main init.go/init_contributor.go (be-15y28)
PR #4028 landed autoConfigureForkContributor on main. PR #4023 had its own
version of init.go and init_contributor.go plus a fork_detect_embedded_test.go
that collided with TestEmbeddedInit/fork_auto_contributor, causing CI to fail.
Take origin/main's init.go and init_contributor.go verbatim; remove
fork_detect_embedded_test.go. The unique features — reference-aware prune,
export --exclude-owner, bd migrate-personal — are untouched.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(prune): scan active custom statuses in reference-aware skip
buildReferencedSet scanned only the built-in non-closed statuses, so a closed bead cited by a bead in an active *custom* status (status.custom) was unprotected and could be deleted by 'bd prune --pattern ... --force'. Now include every configured custom status whose category != done (via GetCustomStatusesDetailed); the read is required, not best-effort, so a destructive prune never silently under-scans. Adds TestPrune_protectsBeadCitedByCustomStatusBead. Addresses maphew's review of PR #4023 (be-e2nb).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(export): apply export.exclude_owners to auto-export
The export.exclude_owners safety net was applied only by manual 'bd export'; the git-committed auto-export (.beads/issues.jsonl) did not filter, so contributor/personal issues could still leak into git history and PRs. exportToFile now applies the same owner filter (config-sourced owners). Adds TestAutoExportExcludeOwner_config. Addresses maphew's review of PR #4023 (be-e2nb).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(migrate-personal): all-or-error copy preserving comments before delete
migrate-personal copied labels/deps/comments best-effort (warnings) and used event-style AddComment, then deleted the source -- so a partial copy could silently drop comments and dependencies while reporting success. Make the copy all-or-error in two passes (create all issue rows, then copy relations so same-prefix intra-set deps resolve), roll back the planning-DB rows and abort before touching the project DB on any failure, and copy comments via ImportIssueComment (structured row + original timestamp). Adds TestCopyIssueRelations_preservesCommentWithTimestamp and TestMigratePersonal_preservesComments. Addresses maphew's review of PR #4023 (be-e2nb).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(ci): register TestPruneLargeFixture in check-testing-short allowlist
Large-fixture bench introduced in this PR was blocked by pr-policy.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(docs): restore version-1.0.5 migrate-personal CLI reference
The 2026-06-03 main merge (72a2a2521) pulled in main's wholesale website
doc regeneration, which dropped
website/versioned_docs/version-1.0.5/cli-reference/migrate-personal.md
(migrate-personal is new in this PR and absent on main). check-doc-flags'
generate-cli-docs.sh --check then failed: the live bd emits the command but
the 1.0.5 snapshot lacked the page, turning Build Artifacts, PR Policy,
Check doc flags freshness, and the CI Gate rollup red.
Regenerated with scripts/generate-cli-docs.sh ./bd — only this file
changed (index.md and llms-full.txt already reference the command).
Verified the full pr-policy sequence passes locally: build-tags,
go-install-guidance, versions, doc-flags (incl. llms-full), doc-freshness,
testing-short, and the jsonl guard.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(gate): finalize be-jewoem gate — re-review PASS, CI green 2026-06-04
Re-review PASS confirmed (gm-wisp-765hi, 2026-05-22, commit 9cfe6206f).
Post-review CI/docs commits (merge, CI allowlist, version-1.0.5 docs)
are non-behavioral. CI run 26924427657: 51/51 checks SUCCESS.
PR #4023 mergeStateStatus: CLEAN. Gate: definitive PASS.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(docs): true up CLI reference after upstream rebase
Mechanical doc-conflict resolution during the rebase onto upstream/main
(cb33b566a) picked a stale --include-infra description and live
top-level command count. Re-run scripts/generate-cli-docs.sh to
resync docs/CLI_REFERENCE.md and website/docs/cli-reference/* with the
post-rebase bd binary; scripts/check-doc-flags.sh passes clean.
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
* test(export): teach fakeStateHashStore GetConfig for auto-export owner-exclude path (fixes PR Core panic)
buildOwnerExcludeSet reads export.exclude_owners / export.exclude_owner
from the store as a database fallback after the YAML-only lookup. The
fake store used by the auto-export tests embeds a nil storage.DoltStorage
and never implemented GetConfig, so any exercised auto-export path
(TestMaybeAutoExportExportsOnStateHashChange et al.) panicked on the
embedded nil interface. Add a GetConfig stub returning ("", nil), the
same pattern used by other embedded-nil-interface fakes in this package
(captureOptsStore, mockRefStore).
Agent-Signature: claude-code-sonnet-5-medium on behalf of matt wilkie
---------
Co-authored-by: Jim Wordelman <jim@wordelman.name>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
Add a release workflow step for Homebrew core formula handling so stable releases track the canonical bump PR, avoid duplicate manual PRs, preserve BrewTestBot bottle handling, and verify the merged formula points at gastownhall/beads. Also fix the local Homebrew upgrade command to use the core formula name, beads.
Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie
* fix(dolt): retry mutate+commit methods on serialization conflict (1213/1205)
ClaimIssue, ClaimReadyIssue, UpdateIssue and CloseIssue each hand-rolled
their own tx (BeginTx + DOLT_ADD/DOLT_COMMIT + Commit) outside
withRetryTx, so a concurrent writer that lost Dolt's optimistic
commit-time merge surfaced MySQL 1213/1205 as a hard failure instead of
retrying. Dolt has no real row locking — FOR UPDATE / SKIP LOCKED are
parse-only no-ops (https://www.dolthub.com/blog/2023-10-23-hold-my-beer/)
— so retry is the only safety net under N concurrent workers. These four
are the work-queue hot paths: `bd ready --claim`, claim, update, close.
Move each body into a withRetryTx closure (which owns BeginTx and the
final Commit and retries serialization failures with backoff), preserving
the single-tx CAS/mutation + DOLT_COMMIT atomicity exactly. On retry,
ClaimReadyIssue re-scans the ready front from a fresh snapshot and claims
the next available issue.
Tested: TestEmbeddedReadyClaimConcurrent, TestEmbeddedReadyConcurrent,
TestEmbeddedCloseConcurrent, TestEmbeddedUpdateConcurrent and the
non-concurrent embedded Update/Close/Ready tests pass; build + vet clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* test(dolt): add concurrent work-queue drain test (Gas Station claim invariant)
N workers concurrently dequeue one shared ready-front via ClaimReadyIssue
until empty; asserts every issue claimed exactly once, none stranded, no
double-claims, and no serialization error ever surfaces (withRetryTx absorbs
the 1213/1205 from the claim-CAS cell collision). This is the regression guard
for the multi-agent claim queue that #4491 makes safe.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(lease): claim-TTL + heartbeat + reclaim for dead-worker recovery
Gas Station v1.1 (wy-5r9j). A claim was previously permanent: a worker that
died mid-task stranded its issue in_progress forever. This adds a lease so a
claim can expire and be recovered.
Schema (migration 0054): add lease_expires_at, heartbeat_at (DATETIME) and
row_lock (BIGINT) to issues (and wisps, for uniform issueops routing), plus
idx_issues_lease for the reaper scan. assignee doubles as the lease owner.
Lifecycle (shared issueops, so both server-mode DoltStore and EmbeddedDoltStore
get it):
- Claim stamps lease_expires_at = now + TTL (default 5m, WithLeaseTTL to
override), heartbeat_at = now, and a fresh row_lock.
- bd heartbeat <id> — owner-only; pushes the lease forward and rewrites
row_lock. Fails (ErrNotClaimable/ErrAlreadyClaimed) once the lease is gone.
- bd reclaim --older-than <dur> — reverts in_progress issues whose lease
expired more than <dur> ago back to ready (clears assignee/started_at,
records a lease_reclaimed event). Default grace 2×TTL.
The row_lock trick: Dolt has no row locking and merges concurrent commits
cell-by-cell, so a heartbeat (writes heartbeat_at) racing a reclaim (writes
status) would silently cell-merge into a zombie — an open/unassigned issue that
still carries the worker's fresh heartbeat. Every mutating path (claim, close,
update, heartbeat, reclaim) now rewrites the shared row_lock cell, forcing the
loser to a 1213/1205 serialization conflict that withRetryTx replays. All lease
paths are withRetryTx/withConn wrapped.
Tests (real Dolt): TestRowLockForcesConflictOnDisjointCellWrites proves the bug
without row_lock (silent merge to zombie) and correctness with it (conflict);
TestConcurrentHeartbeatReclaimClose is the integration race (live workers
heartbeat+close vs a continuous reaper vs dead workers) asserting exactly-once,
no lost close, no zombie; plus claim/heartbeat/reclaim unit coverage on both
backends.
Note: lease columns are second-granular DATETIME (Dolt rounds), so sub-second
TTLs are meaningless — production TTL is minutes. Heartbeat writes a Dolt
commit, so cadence must stay ≪ claim cadence to avoid history bloat.
Fixes the test coupling in TestMigration0053PromotesRigWisps, which assumed the
rig-wisp repair was always LatestVersion().
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* ci+docs: allowlist lease stress tests; scope the row_lock invariant comment
- Add TestConcurrentWorkQueueDrain and TestConcurrentHeartbeatReclaimClose
to the check-testing-short.sh allowlist; both are real-Dolt runtime/stress
skips and were failing ci-pr-policy.
- freshRowLock doc said "EVERY mutating path" rewrites row_lock, which
overstates it. Scope it to status/ownership/lease-mutating paths (the set
the reclaim/heartbeat races care about) and document the invariant + why
orthogonal-cell writers (is_blocked, compaction, deps, rename, reopen) are
intentionally exempt, so a future writer does not silently reintroduce the
zombie-merge bug.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(show): surface lease_expires_at/heartbeat_at in bd show (--json + text) (wy-9cdw)
Migration 0054 added lease_expires_at/heartbeat_at (and internal row_lock) to
the issues/wisps tables for the claim/heartbeat/reclaim leasing feature, but
bd show could not observe lease state — you had to drop to raw SQL.
- types.Issue: add LeaseExpiresAt/HeartbeatAt (*time.Time, omitempty), matching
the StartedAt nullable-timestamp convention. row_lock stays unexported.
- sqlbuild.IssueSelectColumns: append lease_expires_at, heartbeat_at to the
canonical hydration list (flows to every stack via the shared constant).
- issueops.ScanIssueFrom: scan + map the two nullable columns (before the
trailing extra dests, keeping positional parity across all scan sites).
- bd show text view: emit a muted 'Lease: expires <rel> (heartbeat <rel> ago)'
line only for in_progress issues holding an active lease; add formatTimeUntil
as the forward-looking mirror of formatTimeAgo.
- types_test: assert lease keys appear when set, are omitted when nil, and that
row_lock is never surfaced.
* fix(lease): settle v54 review blockers
Address #4537 review blockers before landing v54: keep heartbeat off wisps in both backends, keep direct status/assignee updates from leaving stale leases, guard the down migration, and emit reclaim JSON as snake_case.
Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie
* fix(lease): cover lease fields in tests and hooks
Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
Why: regenerating CLI docs on a machine with a C compiler links CGO by
default, so `bd federation --help` emits the full federation subcommand tree.
The committed docs are built by CI with CGO_ENABLED=0, which stubs federation
("built without CGO support"), so a naive regen produces ~hundreds of lines of
spurious federation churn (federation.md, CLI_REFERENCE.md, llms-full.txt)
unrelated to the actual change. The existing guard force-rebuilds a pure-go
binary but offered no escape hatch and announced the swap on stdout.
What:
- Route the CGO-mismatch notice to stderr (keeps --check/CI stdout clean and
makes it a proper warning).
- Add a documented BD_DOCS_ALLOW_CGO=1 override hook so an intentional
full-federation regen can trust the supplied binary as-is; default stays
safe (rebuild pinned CGO_ENABLED=0 -tags gms_pure_go).
- Make the message name the pure-go recipe and reference the stub marker
("Federation commands require CGO", cmd/bd/federation_nocgo.go).
- Document the override in the script's --help text.
generate-llms-full.sh builds no bd binary, so it needs no change.
Agent-Signature: claude-opus-4-8-high on behalf of matt wilkie
Re-lands the v1.1.0-rc.1 release prep so the candidate can be reviewed before
the tag is cut (#4476 auto-merged the original prep; #4477 backed it out).
Restores v1.1.0-rc.1 version metadata across all package manifests, the
prerelease-aware release workflow and version scripts (prerelease tags skip the
stable docs-snapshot requirement and stay off the stable Homebrew/PyPI/npm
channels), the CHANGELOG and cmd/bd/info.go entries, and regenerates uv.lock to
1.1.0rc1.
Beyond the straight re-land:
- fix(release): match the winres/manifest numeric PE versions on the base
version in update-versions.sh, so a later prerelease-to-different-base bump
does not silently leave them stale.
- docs(release): document the prerelease / release-candidate workflow in
RELEASING.md.
Agent-Signature: claude-opus-4-8-xhigh on behalf of matt wilkie
* revert: back out v1.1.0-rc.1 release prep
Reverts merge commit 427fdd0c85 from #4476 so the RC release prep can go back through maintainer review.
Agent-Signature: codex-gpt-5.5-xhigh on behalf of matt wilkie
* fix(mcp): sync uv.lock to reverted 1.0.5 version
The #4476 revert rolled integrations/beads-mcp/pyproject.toml back to
1.0.5 but left uv.lock pinned at 1.1.0rc1, so `uv lock --locked` (the
Package Gate (MCP) check) failed and the aggregate CI Gate went red.
Regenerate the lockfile so pyproject and uv.lock agree on 1.0.5.
Agent-Signature: claude-unknown-model-high on behalf of matt wilkie
Add a bulk help docs writer that emits the root CLI reference and website command pages from a single Cobra walk. Update the shell generator to call that mode, preserve the pure-Go docs binary guard, and refresh historical versioned CLI docs only when release snapshotting requests a specific version.
Agent-Signature: codex-gpt-5.5-medium on behalf of matt wilkie
Allow prerelease version bumps without promoting stable docs, keep Windows resource versions numeric for prerelease builds, and skip Homebrew/npm/PyPI publishing for prerelease tags while still producing GitHub prerelease artifacts.
Agent-Signature: codex-gpt-5.5-xhigh 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
The doc freshness gate regenerated all generated doc artifacts and failed
the PR on any diff, even drift the contributor did not cause: staleness
inherited from the base branch, or local regeneration environments that
do not match CI's canonical build. Contributors ended up futzing with
regeneration loops for docs unrelated to their change (#4300, #4301).
New scripts/check-cli-docs-drift.sh keeps the strict regenerate-and-diff
probe as the fast path, but on failure in a PR it attributes the drift
before failing anyone: it regenerates the artifacts at HEAD and at the
merge-base in scratch worktrees, each with the canonical pinned build
(CGO_ENABLED=0 -tags gms_pure_go). If the PR neither changed the
regenerated CLI surface nor touched generated files, the drift is
inherited: warn and pass. Contributors only own docs for code they
actually touched.
When the drift IS attributable, CI now writes the exact regenerated fix
as a patch and uploads it as the cli-docs-freshness-patch artifact, so
the fix never depends on the contributor's local environment: download,
git apply, push.
Strict behavior is preserved wherever there is no PR base ref: pushes to
main, releases, and plain local runs. The pr-policy wrapper picks up the
same logic through check-doc-flags.sh.
Refs #4301, #4203. Complements #4312 (docgen binary pinning).
Agent-Signature: claude-unknown-model-high on behalf of matt wilkie
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Eight of the nineteen roll-up items were safe, self-contained fixes:
- dolt: autoResolveConflictsAfterCLIPull pins a single connection and
resets @@dolt_allow_commit_conflicts before releasing it (discarding
the conn if the reset fails) so the session variable no longer leaks
into the pool (item 4)
- issueops: mergeAffectedSets propagates context cancellation instead of
degrading to a full recompute on a dead context (item 6)
- .gitattributes: migration SQL pinned to LF so CRLF checkouts hash
identically to release builds (item 8)
- schema: remote-migrate gate message warns that re-cloning discards
unpushed local work and says how to save it first (item 13)
- dberrors: ancestor-PK table extraction regex is now case-insensitive,
matching the lowercased detector; add unit tests (item 14)
- hygiene lint: flag UUID_SHORT() and migration-time CURRENT_TIMESTAMP
(DEFAULT / ON UPDATE attribute positions excluded); run the check on
direct pushes to main, not just PRs (item 16)
- embeddeddolt: TestSchemaAfterInit asserts dependencies.id has no
DEFAULT, proving 0050's prepared DROP DEFAULT applies via dolt sql and
settling the 0051-variant premise question (item 17)
- doctor dep-keys: failed repairs are counted and summarized as FAILED
instead of Fixed, and the Dolt commit stages only the repaired tables
instead of -Am sweeping the whole working set (item 19)
Remaining items are accepted with dispositions recorded on the issue.
Also gofmt cycles.go (left unformatted by the round-3 commit).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
scripts/check-migration-hygiene.sh consolidates the inline duplicate-version
CI check and adds two guards derived from the Apr-Jun audit:
- Lint UUID()/NOW()/RAND() in migration SQL (the PR 4039 / #4259 root-cause
class), with a justification-required allowlist grandfathering shipped
files. Stale or unjustified allowlist entries fail CI.
- Freeze migration files that exist on the base branch (the PR 3991/3918/3942
in-place-edit class): modification, deletion, or rename fails; fix forward
with a new version. Complements the PR 4270 content hashes, which assume
applied migration content never changes.
CODEOWNERS now routes migrations/ and the hygiene script to maintainers
(enforcement still needs the code-owner branch-protection toggle, tracked
under bd-6dnrw.23). Duplicate-version coverage now includes migrations/ignored/.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Fixes#4259 by replacing clone-local dependency UUIDs with deterministic IDs derived from the dependency edge. Existing rows are backfilled, the random default is removed so missed insert paths fail loudly, and same-edge merge conflicts become normal resolvable row conflicts instead of unmergeable duplicate logical edges.
Agent-Signature: kilocode-gpt-5.5-unknown-reasoning on behalf of maphew
* docs: publish community tools on website
Mirror docs/COMMUNITY_TOOLS.md into Docusaurus so the Pages build publishes it for the default released docs and unreleased docs without relying on manual copy steps.
Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie
* docs: publish core support docs on website
Mirror Sync Concepts, Labels, Metadata, Uninstalling, and Antivirus docs into Docusaurus and include them in the default released snapshot and LLM bundle.
Clarify that agent execution and verification metadata are examples of metadata as a schema extension point, not native issue fields.
Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie
* docs: clarify metadata examples
Replace local verification queue metadata with a tracker round-trip example so public metadata docs show upstream-aligned schema extension patterns.
Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie
---------
Root cause of the 1.0.5 incident: the beads-release formula's snapshot-docs
step is advisory prose, not enforced. A release can bump cmd/bd/version.go and
tag/push while skipping the Docusaurus snapshot, and nothing blocks publish, so
the drift only surfaces as a red main after artifacts ship.
Three layered guards:
A. Atomic bump — scripts/snapshot-release-docs.sh encapsulates the docs
snapshot (docusaurus docs:version + lastVersion + regenerate CLI/llms +
verify) as one idempotent unit. scripts/update-versions.sh now calls it so
version.go and the docs snapshot cannot diverge (escape hatch: --skip-docs).
The formula's snapshot-docs step now invokes the same script.
B. Pre-publish gate — release.yml gains a verify-version-consistency job that
checks the tag matches version.go and runs check-versions.sh. goreleaser
(and thus all downstream publish jobs) needs it; publish-pypi keeps its
always() decoupling from goreleaser but is hard-gated on the verify result.
Drift now blocks publish instead of redding main afterward.
C. Pre-push refusal — .githooks/pre-push runs check-versions.sh when a
refs/tags/v* tag is pushed and refuses on drift, catching it on the
developer's machine before CI. Installed via the existing core.hooksPath.
Verified: shellcheck clean; release.yml valid YAML; script guard paths and the
hook's branch/tag dispatch tested.
Refs: mybd-a5hn
Agent-Signature: claude-opus-4-8-medium on behalf of matt wilkie
The upgrade-smoke gate created issues but never a dependency, so the
data-copy in 0041_split_dependencies_target only ran as DDL on an empty
table, and the rewritten ready_issues (0044) / blocked_issues (0045) views
plus the is_blocked backfill (0046/0047) got zero post-migration query
coverage. That is exactly the surface of the current `bd close` errno 1105
on a stale schema.
Add Scenario 6: create a blocker task + dependent bug, wire the dependency
with the PREVIOUS binary (so the row is written in the pre-split schema),
upgrade to candidate, then assert the migrated dependency survives and the
blocker paths work — bd ready, bd blocked, bd close all succeed, the
dependent is reported blocked pre-close and ready post-close.
Verified green against the real v1.0.4 -> candidate path (all 6 scenarios
pass).
Agent-Signature: claude-opus-4-8-high on behalf of matt wilkie