CI's golangci-lint v2.10.1 carries a newer gosec with taint-analysis rule
G705 (XSS), which flags directory-listing-derived strings flowing into
the docs.json write. Not a web-output sink: this developer tool writes
the repo's own docs.json with %q-quoted slugs the same pipeline
generates. Verified 0 issues under the exact CI linter version.
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.
Adversarial review reproduced four dead references from the built
binary that the earlier printed-path sweep missed (two pointed at the
deleted website/ tree, which the sweep's docs/-anchored patterns never
covered): the --server help in bd init (second STORAGE-BACKENDS
occurrence), bd formula's narrative-reference pointer, the
remote-migrate gate's docs URL, and the whats-new Dolt guide entry.
Also updates the storage-backends pointer in the emitted Postgres
schema comment.
Every fix verified against the binary or a traced source call path:
- How Beads Works: parent-child DOES affect ready work (a blocked parent
blocks its children — the blocked-state SQL inherits it), hash-ID
inputs are title/description/creator/creation-time plus a collision
nonce (live generator is internal/idgen, not the legacy one), and
bead gates dropped from the gates bullet (currently unresolvable).
- Graph-link type strings are hyphenated (relates-to, replies-to);
underscore forms are rejected by the parser. Fixed corpus-wide
including the README feature bullet.
- upgrading.md: the version-era table's boundaries were refuted by git
archaeology (embedded Dolt shipped in v0.60.0 and always used
.beads/embeddeddolt/; nothing changed at the claimed v0.63.3
boundary) — replaced with a layout-based identification table.
- Phantom .beads/dolt/sql-server.log path in sync-failures and the FAQ;
the managed server writes .beads/dolt-server.log.
- FAQ: ID growth matches DefaultAdaptiveConfig (min 3, max 8,
probability-driven), dependency-type wording no longer claims exactly
four types, and unmeasured performance figures are hedged instead of
stated as facts.
- quickstart: bd migrate --cleanup doesn't exist; init installs hooks
by default (no prompt) and has no merge-driver step; ready output
quote and bd restore recovery source corrected.
- formulas.md: step types map to issue types (task/bug/feature/epic/
chore; anything else falls back to task — human/gate are not step
types), and there is no built-in formula search tier.
- todo.md: bd update takes --set-labels, not --labels.
- graph-links.md: broken #dependencies fragment → #add-dependencies.
Adversarial review falsified this page: 10 of its 12 checkable claims
contradicted the binary. It taught a phantom TOML gate schema (approvers,
require_all, duration, event, status, action, merged — all silently
dropped by the parser), phantom subcommands (bd gate approve/skip), a
nonexistent pending/open/closed state model, list-valued waits_for, and
7d durations that time.ParseDuration rejects.
Rewritten from source: the four-field [steps.gate] schema
(type/id/await_id/timeout per internal/formula/types.go), the real
subcommand set (list/create/show/resolve/check/add-waiter), gate types
with their closers (human resolves manually; timer and gh:* close via
bd gate check; bead gates currently unresolvable — multi-rig routing
removed), needs vs waits_for fan-in semantics, and a worked example
taken from beads' own release formula.
Closure: every TOML construct on the page round-trips intact through
bd formula show --json (gh:run/human/timer gates, needs, waits_for).
The 113-page generated CLI Reference moves from a top-level nav group to
a nested group inside Reference — Mintlify renders nested groups
collapsed by default, so the command list no longer dominates the
sidebar. The docsmint nav splice is depth-agnostic (indentation is
derived from the pages key's line), verified by regenerating and by
re-pointing its test fixture at the nested shape. Reference overview and
the beads-docs skill IA note updated.
A CI website build left website/node_modules on disk; once website/ (and
its .gitignore) was deleted, a blanket git add swept 500MB of webpack
caches into a commit and GitHub rejected the push. History was rewritten
to drop them; this guard prevents a recurrence.
make diagrams-excalidraw renders committed .excalidraw sources under
docs/diagrams/excalidraw/ to SVGs in docs/diagrams/excalidraw-rendered/
(idempotent, @swiftlysingh/excalidraw-cli via npx), matching the Gas City
convention. No diagrams authored yet — the nine existing diagrams stay
mermaid. The beads-docs skill names the real target and paths.
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.
Per decision 6: the eleven pointer stubs at old top-level docs/ paths are
deleted; the docs.json redirects array now maps every moved page's old
route to its new home (43 entries covering the full pre-port top-level
namespace). The docsync exemption list shrinks to the one generated file
(docs/CLI_REFERENCE.md). Plugin and npm-package quickstart pointers now
link the real in-repo page.
Old GitHub deep links to the deleted paths 404 from here on — accepted in
the decision record; bd's own printed paths are updated to the new
locations in the next commit, so only already-released binaries are
affected.
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).
Twelve settled decisions: generic-MD-only emitter, all-in on Mintlify (no
parallel run), committed generated output, Go post-processor, current-only
versioning, redirects instead of pointer stubs (accepting 404s from
already-released binaries), printed-path string fixes on this branch,
disposition confirmations, no bd tracking from this clone, Excalidraw
machinery port, push-without-PR, and this record's home.
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).
README drops from 254 to ~190 lines: the server-mode connection table,
Unix-socket note, prune/purge maintenance semantics (including
reference-aware protection), and backup/migration walkthrough move into
docs/architecture/dolt.md, which now owns that material once. The README
keeps the pitch, quick start, features, essential commands, and a
condensed storage-modes summary with links, and gains a hero mermaid
diagram of the create -> ready -> claim -> close loop (GitHub renders
mermaid natively).
The ported workflow pages documented commands that do not exist in bd:
bd pour, bd wisp create/list/show/delete/cleanup, bd pin, bd hook, and a
.beads-wisp/ storage directory. Verified against the live binary: the
real surface is bd cook, bd mol pour, bd mol wisp (+ list/gc), bd mol
squash/burn, bd create --ephemeral, and bd purge; wisps are rows in the
main database with Ephemeral=true, excluded from federation push by
default, not a separate gitignored store.
Rewrote workflows/wisps.md around the verified lifecycle
(create -> execute -> squash or burn), fixed formulas.md instantiation
examples, dropped the design-doc status header from adaptive-ids, and
linked the home page's concept table to the canonical pages.
- Rewrite docs/core-concepts/index.md as 'How Beads Works' — the one
canonical concept page (modeled on Gas City's how-gas-city-works):
problem-first framing, the bead -> dependencies -> ready-work loop, hash
IDs, the formula -> proto -> molecule/wisp pipeline, gates, Dolt sync,
federation, and storage modes, led by four mermaid diagrams. Other pages
link here instead of re-deriving the model.
- Fact fixes caught while writing (verified against source/live help):
hash IDs are content-derived SHA-256 (internal/types/id_generator.go),
not random; bd pour/bd wisp/bd pin/bd hook are not commands (the real
surface is bd mol pour, bd mol wisp, bd assign, bd update --claim);
wisps are not stored in .beads-wisp/; cross-repo dependency syntax is
external:<project>:<capability> (cmd/bd/dep.go); recovery index claimed
SQLite errors in a Dolt product.
- Section overview pages: rewrite workflows/index, extend recovery,
multi-agent, and integrations indexes to list every child with one-line
summaries; add reference/index and put it in the nav.
- New concept diagrams: sequential-vs-hash ID merge collision
(core-concepts/hash-ids) and embedded-vs-server mode
(architecture/dolt).
- website/README.md: real build/verify instructions and parallel-run
status for the Docusaurus site.
- Repoint example READMEs and page labels at the real quickstart page.
Project-scoped skill at .claude/skills/beads-docs/ (SKILL.md +
references/), adapted from the Gas City gascity-docs skill with
beads-specific content: the canonical concept model verified against live
bd help output (bead/issue, dependencies and ready work, the
formula -> cook -> proto -> pour -> molecule / wisp pipeline, gates, Dolt
sync, federation), a required-terminology table with the prose-vs-literal
rename discipline, content stance and prose doctrine with loss-check and
fact-check guardrails, emphasis/MDX rules, the generated-content-edited-
at-source rule naming the drift gates, and the verification gates
including the render-and-review rule for diagrams.
Also records the beads <-> Gas City vocabulary bridge once (shared words
molecule/formula/wisp/gate carry different senses in the two corpora) so
cross-project prose stays consistent.
- 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).
* fix(label): support comma-separated multi-label add/remove; fail hard on bad issue IDs (bd-vu5kv)
'bd label add <id> a b c' silently applied only 'c': the grammar treats
the last arg as THE label and everything before it as issue IDs, and
unresolvable IDs were skipped with a stderr warning while the command
exited 0. An agent hit this in the wild and only noticed because
'bd ready --label ...' came back empty.
Two changes:
- The final positional arg now splits on commas, so
'bd label add bd-123 a,b,c' adds all three labels in one transaction
(same convention as 'bd create --labels a,b,c'). Same for remove.
- Issue-ID args that fail to resolve are now a hard error before any
mutation, instead of warn-and-continue. When several ID-position args
fail, the error hints at the comma-separated form, which is exactly
the space-separated-labels mistake.
The reserved 'provides:' check now runs against every label in the
list. Regenerated CLI reference docs (freshness probe) and updated
docs/LABELS.md.
Closes bd-vu5kv
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012VBUR4qkHbssPomBDuJgkQ
* docs: sync website label mirrors
Agent-Signature: codex-gpt-5.6-terra-high on behalf of matt wilkie
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
BuildReadyWorkWhere emitted clauses for --label (AND-set) and
--exclude-label but none at all for --label-any, so the OR-set filter was
silently dropped by `bd ready` and `bd ready --claim` on every backend
(with or without --parent), while `bd list`/`bd search` honored it.
On an atomic claim the silent drop is dangerous rather than merely wrong:
a worker fencing itself to its own lane
(`bd ready --claim --label-any lane-a --parent epic-1`) would claim
another lane's issue and believe it was fenced. Reproduced on current
main: the new conformance case claims a lane-b issue when lane-a was
requested.
Emit an OR-set membership clause (same shape as the list path in
sqlbuild/filter.go) that AND-combines with Labels, ExcludeLabels and the
parent filter. All claim paths (Dolt, embedded-Dolt, sqlkit SQL family)
funnel through ClaimReadyIssueInTx -> GetReadyWorkInTx ->
BuildReadyWorkWhere, so the single seam fixes every backend.
Tests: a SQL-shape unit test in sqlbuild, plus a behavioral conformance
case (ClaimReadyIssueLabelFilters) asserting the claim is fenced by the
OR-set alone, AND-combined with --label and --parent, and — the safety
property — that an exhausted lane claims NOTHING rather than falling back
to unfenced ready work.
Routine issue history already lands in the database events tables. Stop creating or appending the interactions JSONL sidecar by default, add audit.enabled for explicit sidecar use, and expose database events via bd history --events.
Fixesgastownhall/beads#4687
Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie
Mirrors upstream #4716. ManageLeaseOnUpdate armed a 5-minute lease
whenever a generic update left an issue in_progress+assigned, so a plain
interactive claim (bd update -s in_progress -a <who>) silently entered
the heartbeat/reclaim protocol nobody was running for it. The lease
lapsed, bd reclaim reverted the bead out from under its owner, a
supervisor restore re-armed the lease, and the churn self-sustained —
until a headless fleet worker legitimately claimed a bead whose owner
was mid-implementation (observed live on the wyvern constellation).
Leases now arm ONLY via the lease-aware verbs (claim/heartbeat).
ManageLeaseOnUpdate is clear-only:
- leaving the claimed state (not in_progress, or unassigned) clears the
lease, as before;
- changing who holds the claim (assignee transfer, or a fresh
transition into in_progress) clears the previous owner's lease so it
cannot count down against the new holder — the new holder gets a
lease only by claiming or heartbeating through the lease-aware verbs;
- a same-claim edit (already in_progress, same assignee) leaves the
lease columns untouched, so a worker's live lease survives unrelated
edits to its issue.
A real worker restored by a supervisor self-heals: its next heartbeat
re-arms the lease. Interactive hand-dole claims stay durable until the
actor releases them or a human reclaims.
Flips TestUpdateIssueMaintainsLeaseOwnership (which pinned the old
transfer-stamps-fresh-lease behavior), adds the bd-9hpgf regression
guard TestBareUpdateClaimDoesNotArmLease plus
TestUpdatePreservesLeaseOnSameClaim, and a pure unit table-test for the
clear-only contract.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U5mtSXJuNGs4tmeKDbwNif
Adds a second, opt-in tier to Oracle A: the enumerated catalog
(`tests/oracle-a/harness/scenarios/enumerated.json` — 523 entries, 501
deterministic) that sweeps the wider bd CLI surface as data. The curated set
stays the fast default (~2-7 min); `ORACLE_CATALOG=1` pulls in the catalog for a
deep run (~10-15 min).
- `catalog()` now loads `scenarios/enumerated.json` (harness-relative), and
`scoreboard` gates it on `ORACLE_CATALOG` — symmetric with `capture_golden` —
so a default run scores exactly the curated set with no no-golden noise.
- `run-oracle-a.sh` exports `ORACLE_CATALOG` through to both the capture and score
steps (only when non-empty; the tools treat any set value as "on").
- Floor assertion reworked. The old per-scenario "every create must exit 0 with an
id" check false-positived on the catalog's intentional error-path scenarios
(invalid priority/type, missing title, unknown flag, ...), whose creates SHOULD
exit non-zero, and aborted before scoring. It now aggregates: the reference must
produce >= 1 successful create (proving bd can init + create a workspace);
per-scenario error behavior is validated by the ref-vs-candidate diff, not the
floor.
Verified (bd-vs-bd on origin/main d23ba38f8): deep-tier IN-SCOPE 323/323 PASS, 0
divergences; fast tier remains 44/44. The 45 out-of-scope failures are
informational only (build-stamp / human-output deltas that always vary between two
builds — the in-scope predicate excludes them, e.g. the non-deterministic
`version --json` scenarios).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Oracle A is a black-box differential conformance rig for `bd`. It builds `bd`
from the merge-base with origin/main (REFERENCE, "before") and from the working
tree (CANDIDATE, "after"), runs a curated set of CLI contract scenarios against
both as real processes, and diffs every step — exit code, stderr, and JSON-aware
stdout — with volatile values (timestamps / UUIDs / actor / email) normalized.
Zero in-scope divergences is the gate: green means the change altered no
user-visible bd behavior on the covered surface.
The rig is purely additive and treats bd as a black box — it needs only cargo,
go, and a CGO toolchain, and works against any bd tree. It is useful for
reviewing any refactor (storage seam, serialization, output plumbing), not just
one feature.
Layout (all under tests/oracle-a/):
- run-oracle-a.sh — orchestrator: builds reference + candidate bd in isolated
worktrees, builds the harness, captures goldens from the
reference, scores the candidate, sets exit status.
- harness/ — a self-contained Rust conformance harness (MIT OR
Apache-2.0): capture_golden + scoreboard binaries over a
curated scenario set with JSON-aware, order-aware diffing.
- README.md — how to run, and the explicit what-green-does /
does-not-prove boundary.
Extracted from #4601, where it was used to prove the SQL backends byte-identical
to the Dolt reference; it stands on its own as a general regression gate.
Verified: the main-vs-main leak test is green — 44/44 in-scope scenarios, 0
divergences — on origin/main d23ba38f8.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat: auto-resolve issues-table modify/modify conflicts by LWW (updated_at)
Add an issues case to TryAutoResolveMergeConflicts that auto-resolves
modify/modify conflicts on the issues table using row-wise last-write-wins
by updated_at. This eliminates the biggest remaining manual wall in
multi-clone sync: the issues-table conflicts that follow routine cross-clone
pulls (GH#4698).
Safety predicate (issuesConflictsAreLWWSafe):
- Only modify/modify (base_id valid, both our_id and their_id valid)
- Reject add/add (no base row), delete/modify (one side NULL)
- Reject equal updated_at (ambiguous)
Resolution (resolveIssuesLWWConflicts):
- For rows where ours wins: DELETE the conflict row from
dolt_conflicts_issues (working set already holds our values)
- For remaining rows (theirs wins): DOLT_CONFLICTS_RESOLVE('--theirs')
- Stage with DOLT_ADD('issues')
Updated TestPullFromReportsOperatorConflicts to pin updated_at to equal
values on both sides, making the conflict ambiguous so the safety check
rejects it — the test exercises the operator-conflict reporting path which
requires a conflict the auto-resolver declines.
Added four new tests covering theirs-wins, ours-wins, ambiguous, and
add/add scenarios.
Agent-Signature: amp-gpt-5.4-2026-03-05-high on behalf of maphew
* feat: narrow issues LWW auto-resolve to losing-side-predates-merge-base
Tighten the issuesConflictsAreLWWSafe predicate so a modify/modify
issues-table conflict is only auto-resolved by last-write-wins when the
losing side's updated_at predates the merge base (equals the base row's
updated_at). If the losing side also moved its updated_at past the base
value, both sides made real edits since the last sync and row-level LWW
would silently drop the losing side's field-level changes — that
concurrent-edit case is now left for the operator (GH#4698 Risk
mitigation).
This preserves the common case the basic LWW fix targets: one side's
conflict is a migration artifact (the row was rewritten by a schema
change but updated_at did not move) and the other side made the only
real edit. bd is primarily single-user-multi-machine, so concurrent
same-issue edits since a shared merge base are rare.
Implementation: issuesConflictsAreLWWSafe now also selects
base_updated_at from dolt_conflicts_issues and, after the existing
modify/modify and unequal-timestamp checks, verifies the losing side's
(older) updated_at does not exceed the base value. The resolution
function (resolveIssuesLWWConflicts) is unchanged — it already does
row-wise LWW; only the safety gate is stricter.
Tests:
- Updated setupIssueMergeConflict to seed a controlled base updated_at
(the helper now explicitly sets updated_at on the seed row instead of
relying on CURRENT_TIMESTAMP, which made the base value timing-
dependent).
- Existing theirs-wins/ours-wins tests set the losing side's updated_at
equal to the base so they exercise the auto-resolve path.
- New TestTryAutoResolveMergeConflicts_IssuesConcurrentEditLeftAlone:
both sides' updated_at > base → left for the operator.
Agent-Signature: amp-gpt-5.4-2026-03-05-high on behalf of maphew
The leasing stack (claim-TTL, heartbeat, reclaim, migration 0054) landed
on main after the v1.1.0 tag but had no changelog entry. Add it under
[Unreleased] per the release follow-through checklist (wyvern wy-8gqu).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Fix prime guidance for local-only repositories
* Honor authority profiles in local-only prime guidance (#4321)
Keep the contributor behavior while allowing team-maintainer profiles to
commit locally, and isolate the regression test from ambient workspace state.
Agent-Signature: codex-gpt-5.6-sol-high on behalf of maphew
---------
Co-authored-by: matt wilkie <maphew@gmail.com>
Cursor support is anemic compared to Claude Code and Codex. It ships
only a static rules file: no agent lifecycle hooks, so `bd prime`
context is never injected at session start and is silently lost after
context compaction, and it has no `bd init` auto-install, no `--global`
scope, no shared agent skill, and no `bd doctor` coverage.
This PR brings Cursor up to the same footing as the tier-1 integrations.
- `bd setup cursor` now installs agent lifecycle hooks
(`.cursor/hooks.json`) alongside the rules file, wiring
sessionStart/preCompact/postToolUse to a hidden `bd cursor-hook`
command so Beads context survives compaction:
* sessionStart injects full `bd prime` context into new sessions
* preCompact arms a one-shot refresh marker
* postToolUse re-injects `bd prime` once after a compaction, then
no-ops
- `bd init` auto-installs Cursor (rules + skill + hooks) and stages
`.cursor/`
- `bd setup cursor --global` writes `~/.cursor/hooks.json` +
`~/.agents/skills/beads`
- Canonical rules: `.cursor/rules/beads.mdc` wraps the shared
`recipes.Template` instead of a hand-maintained copy
- Shared agent skill (`.agents/skills/beads`), removed only once neither
Cursor nor Codex still relies on it
- `bd doctor` reports Cursor Integration, Settings Health, and Hook
Completeness checks with agent-mode enrichment
Shared hook mechanics (prime runner + one-shot refresh marker) are
factored into `cmd/bd/agent_hook.go` and reused by codex-hook.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
An adversarial fable red-team of the multi-backend PR surfaced 19 findings; the
verified, non-regressing subset is fixed here (two were confirmed intentional and
left as-is with clarified comments).
Dolt-parity (high):
- sqlkit tx AddLabel/RemoveLabel/CloseIssue recorded no audit event, unlike both
Dolt references, so bd label add/remove and bd batch / mol squash close lost
their EventLabel*/EventClosed rows on Postgres/MySQL/SQLite. Delegate to the
same issueops with-event helpers the embedded oracle uses.
- Heartbeat left updated_at stale on Postgres/SQLite (no ON UPDATE trigger;
MySQL/Dolt auto-bump), so bd stale diverged. Stamp updated_at on the heartbeat
UPDATE (claim already stamps it, so no double-assign).
Correctness / hardening:
- postgres/mysql/sqlite stampSchemaVersion: idempotent insert (ON CONFLICT /
INSERT IGNORE / INSERT OR IGNORE) + re-read, so concurrent first provisions do
not fail one opener with a duplicate-key error.
- sqlkit tx SetConfig now syncs custom_statuses/custom_types like the oracle.
- pgdialect INSTR->POSITION leaves the call loud when both args carry a
placeholder, preventing a silent parameter swap.
- creds command runner uses cmd.exe on Windows (sh is POSIX-only).
- Dolt gateway credential command is gated on the Dolt backend, not just
shared-server mode (was failing closed for SQL workspaces).
- Scrub pg/mysql URL passwords from the bd.args telemetry span.
Conformance rigor:
- E2E normalize() maps zero/epoch timestamps to <ZERO-TS> so a lost timestamp no
longer reads as byte-identical to a real one.
- E2E logs its candidate set and honors BEADS_CONFORMANCE_REQUIRE so a
sqlite-only run cannot masquerade as full coverage.
Docs/hygiene:
- Scrub dev-machine paths (/data/tmp/pg-recon, proposal_2.md, "proof-wedge") from
the Postgres schema DDL comment; clarify the SQLite timestamp comment.
Deliberately not changed (would regress): sqlkit UpdateIssue uses the without-event
variant to MATCH dolt-server (only embedded differs); sub-second timestamp
precision is an intentional per-backend waiver (whole-second round-trip is the
portable contract) — forcing round-down would discard PG/SQLite fidelity.
Verified: embedded + postgres + mysql + sqlite + server-dolt TestConformance and
the pg/mysql/sqlite E2E differential all pass.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The differential Rust oracle was carried in this feature PR as a stale,
un-neutralized copy (older scenarios, a /data/projects/bts-rs dev path in
PROVENANCE.md). Its canonical home is #4678, a strict superset: same 45 curated
scenarios plus a 523-entry enumerated deep tier, crate/env renamed and dev-paths
scrubbed, cargo build+tests green. Drop the copy so the public repo does not carry
the private-path version twice.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Fixing the Tier-1 reconcile ambiguity unmasked a Tier-2 (TestConformanceE2E)
failure previously hidden behind the aborted Tier-1 run: on CI the SQL candidate
backends print the "beads.role not configured (GH#2950)" nudge to stderr while
the dolt-embedded reference does not, so 8 scenarios diverged on that warning
alone (stdout byte-identical on all three backends).
The nudge fires from git-config state (unset beads.role) that differs on the CI
runner vs a dev box — it does not fire locally — so it is cross-env noise, not a
storage divergence. Strip it in normalize() exactly as the random tip banner
already is; the strip runs on both reference and candidate and preserves any
genuine error line that precedes it.
Verified: full TestConformanceE2E passes locally against pg + mysql + sqlite
candidates (231s); the regex strips the exact 3-line nudge while keeping real
error lines.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Three independent CI failures on the multi-backend line:
- Postgres ReconcileHierarchicalChildIDs failed with "column reference
last_child is ambiguous" (SQLSTATE 42702): the child-counter upsert's bare
last_child on the ON DUPLICATE KEY UPDATE RHS is a valid MySQL current-row
reference but ambiguous between the target row and EXCLUDED in Postgres.
Table-qualify it (%[1]s.last_child) — unambiguous on pg/mysql/sqlite/dolt.
- Server-Dolt Audit/molecule-wisp-batch-iter/ListWisps returned wisps in id
order instead of priority order: DoltStore.getWispsByIDs selects ordered IDs
then re-fetches via WHERE id IN (...), which drops the ORDER BY. Re-emit in
the requested ID order so priority ordering survives the two-step fetch.
- Embedded-Dolt conformance timed out at 15m: the branch-new audit suite plus
-race pushed the run past the split job's budget (completes in ~7m without
-race locally). Bump the embedded conformance timeout 15m->30m to match the
repo's integration timeout.
Verified: pg/mysql/sqlite TestConformance pass; full server-Dolt TestConformance
passes (109s); embedded TestConformance passes (426s) well under 30m.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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>
Add a short upgrade checklist to the README, installing docs, live website installation pages, and upgrade guide so remote-backed migration rules are visible from common entry points.
Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie