* feat(schema): never migrate an existing database without explicit consent (bd-qhn8y)
Beads 1.2 release remediation. 1.2.0/1.2.1 auto-applied migrations 54-65 at
store open on ANY command, including reads; older binaries then refuse the
migrated database. MigrateUp now refuses pending main-sequence migrations on
an existing database before any write (dolt_ignore seeding included) unless
the operator consented: bd migrate / bd migrate schema (preview flags
withhold), bd migrate --force, or BD_ALLOW_MIGRATE=1
(BD_ALLOW_REMOTE_MIGRATE honored as an alias). Fresh init and at-latest
databases are unaffected; the #4259 remote gate keeps all its protections.
Also: freeze shipped migrations (hash-pin test, main 0001-0065 + ignored
0001-0024), retract v1.2.0/v1.2.1 in go.mod, agent-executable un-migrate
runbook (docs/recovery/unmigrate-schema-v65.md), and the upgrade smoke +
historical migration harnesses now model the consent contract and assert
the refusal carries guidance.
No version bump here by design: cutting the release stays with the release
owner.
Rebased onto main 800d43eb8d: the go.mod retract hunk is dropped -
main already retracts v1.2.0/v1.2.1 (and v1.1.1) since #5782. The
uow consent grant moves into the TestMain main added in #6441 (a
second TestMain no longer compiles), and the new files are listed
in the BUILD.bazel targets main now carries (gazelle).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(schema): cloned-workspace bootstrap carries creation-consent (bd-qhn8y)
The consent gate treated a workspace `bd init --remote` / `bd bootstrap`
just cloned into existence like a pre-existing database, refusing the
smart gate's provably-safe first-mover migration and stranding init in
the generic open-error path (bypassing the bd-4mpy7 finalize+guidance
ergonomics). Cloning IS creating: those paths now record consent
explicitly, and the #4259 remote-migrate gate still applies to them
unchanged (consent is not its designated-migrator override). Fixes CI
TestEmbeddedInit/remote_behind_schema_gate.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(migration): consent first in main's wisp lanes too (bd-qhn8y)
The rebase onto 800d43eb8d brought in #6049's wisp-plane lanes, which
postdate this PR's harness changes. Each one makes an ordinary candidate
command the first touch on an old-schema database, and the consent gate
refuses it:
- historical-dolt-upgrade-test.sh run_wisp_plane_upgrade opens with
`bd list` before any migrate: "candidate could not open the seeded
wisp workspace" for v1.0.1, v1.1.0, v1.1.2 and v1.2.2 (the
Migration Test Harness dolt-runtime shard).
- run_dirty_tracked_wisp_scenario (v1.1.2): the consent refusal stops
the open before MigrateUp reaches the #5816 dirty tables, so the lane
fails "without naming them".
- upgrade-smoke-test.sh "Wisp plane survives upgrade" upgrades with a
bare cand_init, so list/ready/blocked/update all hit the refusal
(4 failures each for v1.3.0 and v1.3.1, both in the PR smoke set).
Use the PR's own pattern: the explicit `bd migrate schema` is the first
candidate touch (cand_upgrade in the smoke script). Base 800d43eb8d
passes these lanes unchanged; with this fixup the full 14-version
historical corpus and all five PR smoke versions pass.
Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(schema): close consent-gate review findings (bd-qhn8y)
Review fixes for the migration-consent gate (adopt-pr review, attempts
1 and 2).
Majors:
- #4566 deadlock rebuilt one check earlier: on a database that is both
behind and dirty, the consent refusal fired before the dirty-table
guard, whose remedy (`bd dolt commit`) opens without consent. The
working-set-reconcile opens now tolerate MigrateConsentError: embedded
(toleratesConsentRefusal, WSR intent only) and server mode
(LenientOpen's warnLenientOpenRefusal) print WorkingSetWarning and
commit at the current schema; strict, read-only and RemoteSync opens
still refuse. Covered by an embedded test (a refused open writes
nothing: dolt_status, dolt_ignore and schema_migrations unchanged) and
a server-mode integration subtest.
- Bare `bd migrate` consented: isMigrateConsentCommand now matches only
the schema verb, so `bd migrate` (metadata reconcile, including
--update-repo-id, --inspect and --dry-run) no longer consents to a
one-way migration; `bd migrate schema` and --force do.
TestLocalMigrateConsentScope pins the scope through the root pre-run.
The dirty-table warnings name `bd migrate schema` accordingly.
- Runnable JSON hint: the JSON refusal follows the #4259 AgentDirective
convention, a non-runnable hint plus a migrate_consent object
(versions, pending, severity, human_decision_required, options) whose
commands are retargeted with --global for the shared global database.
The text refusal prints the same --global hint under `bd --global`.
- Freeze floor: the hash-pinned freeze now covers what v1.3.x shipped,
main 0001-0066 and ignored 0001-0026; the CHANGELOG puts new
migrations in 0070+ / 0028+.
- Fresh-bootstrap heal: MigrateUpWithLock with heal authority takes the
consent-free migrate path, so a retried bd init whose first pass left
a non-zero cursor converges; other lock callers keep the gate.
Minors: the uow team-server guards are repinned on `bd migrate schema`;
the un-migrate runbook is linked from the recovery index and
cross-linked with the 1.2.1 repair-forward doc; the CHANGELOG BREAKING
entry matches the shipped contract; harness comment grammar.
Docs: the user docs and README named bare `bd migrate` as the step that
applies schema migrations; they now say `bd migrate schema`, which also
exists in the pinned docs release (v1.2.2) and in v1.3.x. The
`bd migrate schema` help no longer claims migrations run automatically
on store open. The Go remedy that sends a remote-gate stop to bare
`bd migrate` for its migrate-or-adopt options is unchanged (pinned by
TestNoticeSharedMigrateRefusalPerDecision).
Upgrade smoke (attempt 2): the consent-gate assertion is graded only when
the old binary left a database. Releases before v1.0 have no
`init --non-interactive`, so prev_init creates nothing there and the
candidate's `bd list` fails with "no beads database found", which has no
consent guidance. Main's Bazel smoke lane (#7331) runs the newest 30
releases, 20 of them pre-1.0, under the required ci-gate; all 20 went red
on the merge. The 10 v1.x releases still take the refusal branch.
Shard manifest (pre-approval CI): the new embedded test
TestEmbeddedMigrateConsent_BehindAndDirtyWorkingSetReconcileRecovers is
listed in the Bazel 15-shard block of embedded-storage-test-shards.txt
(incremental --write; shard 15). Main's ci lane runs
TestStorageEmbeddedShardManifestGeneratorNotStale in //scripts:scripts_test,
which fails on any unlisted top-level embeddeddolt test.
Not addressed (optional): env-only consent docs for embedders, the
unparseable BD_ALLOW_REMOTE_MIGRATE alias hint, and the harness
`|| true` on `cand migrate schema`.
Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <julianknutsen@users.noreply.github.com>
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.com>
The gs:// remote path works — full clone of a 115k-chunk production DB in
5 seconds, incremental syncs in ~4s, ADC auth, zero servers — but nothing
in the docs said "point two machines at a bucket and you have a
federation", so discovering it meant reading Dolt internals.
New page docs/multi-agent/bucket-federation.md walks the whole path:
create the bucket path -> bd dolt remote add + bd dolt push to seed ->
bd init --remote to birth the second replica -> bd sync on a timer, with
the exit-code table a timer branches on and the three rules that set the
interval (staleness is the interval; lease TTL and reclaim grace must
exceed it; a longer interval means more conflicts, because updated_at is
touched by every mutation).
Carries the measured cost from a production two-machine deployment
(28s cold push, 5s clone, ~4s incremental push, ~1s pull+merge at ~1.3k
issues / ~115k chunks) and the failure modes that path actually hits:
raw `dolt remote add` leaving the SQL server blind to the remote, a
fresh machine with no Dolt commit identity failing even a no-op merge,
server-mode credentials being whatever the server inherited at startup
(GH#6), remote-name drift between replicas, conflict resolution through
the dolt_conflicts tables, and one bucket path per database.
Registered in the Mintlify nav and cross-linked from the multi-agent
index and from the federation guide, which keeps DoltHub as the
zero-config default and points here for the BYO-cloud story.
Adds docs/reference/events-journal.md: what the journal is (a durable,
replayable, clone-local record of committed mutations), how to enable it,
the record contract and its seven ops, the typed truncation error and how a
consumer recovers, manual pruning and the retention floors, the boundaries
(per replica, per branch, sync/raw SQL/store-open/compaction non-coverage),
and how the dolt_ignored tables sit in Dolt.
Every technical claim is derived from the code on this branch — cmd/bd
events help text, the issueops journal engine, the migrations, and the
config defaults — and states the same contract the CLI help does.
It lands in Reference rather than Core Concepts because the page specifies a
machine-facing contract rather than teaching the bead/dependency model; it
sits beside the JSON output contract and observability, the two other pages
an integrator reads. A short orientation section separates the three
event-ish systems (script hooks, audit history, the journal) so a reader
picks the right one, and reference/advanced.md no longer claims there is no
`bd events` command.
CHANGELOG records the new commands, the opt-in journal and its three config
keys, the events_journal_truncated failure mode, and is_blocked joining the
documented /v0 issue schemas.
Both the page and migration 0064's down script also record the one destructive
outcome that raises no error: dropping and recreating the journal tables, or
losing bd_events_seq, restarts the sequence space at 1, so a parked consumer's
checkpoint sits above the new head and reads as "caught up" forever. Nothing
about the new journal looks pruned, so the typed truncation error cannot report
it — the only remedy is to re-baseline, and the only defence is saying so where
someone will be standing when it happens.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of julianknutsen
* Add Kiro setup recipe
* docs: register integrations/kiro in docs.json navigation
The docsync guard (TestEveryDocsPageIsPublished) requires every docs/ page
in the Mintlify nav; it landed after this PR was written.
Agent-Signature: claude-fable-5-high on behalf of maphew
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01P3JtQ3ukoVmfg6LCKcKBBh
---------
Co-authored-by: matt wilkie <maphew@gmail.com>
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.
* docs: align user docs and CLI reference with the v1.1.0 release
The Mintlify site publishes from main, so the docs had drifted ahead of the
latest release — documenting features that no released binary ships.
- Remove architecture/storage-backends: v1.1.0 supports only Dolt (the
SQLite/Postgres/MySQL backends are post-tag work on main). Redirect the
old routes to /architecture/dolt and drop the alternate-backend claims
from README, core-concepts, architecture index, and FAQ.
- Stamp the docs homepage with the release: "These docs are for the 1.1.0
release" plus a link to the v1.1.0 release notes.
- Regenerate the CLI reference (docs/cli-reference/, docs/CLI_REFERENCE.md,
docs.json nav) from the released v1.1.0 binary via tools/docsmint: removes
pages for post-1.1.0 commands (heartbeat, migrate-personal, reclaim,
unclaim) and post-1.1.0 flags.
- Fix hand-written pages that referenced post-1.1.0 CLI surface, verified
against the v1.1.0 binary: bd dep relate/unrelate (not top-level
relate/unrelate), bd admin reset (not bd reset), bd hooks list (not
status), bd history / bd vc status (not vc log/diff), release the claim
via bd assign + bd update (no bd unclaim), drop bd migrate-personal and
bd daemon mentions, and reduce the Cursor integration page to the rules
file that v1.1.0's bd setup cursor actually installs.
- Stop documenting the BD_ALLOW_REMOTE_MIGRATE escape hatch (and the
nonexistent-in-1.1.0 bd migrate --force): the remote-migrate gate prints
its own operator guidance by design; docs now defer to it.
* docs: auto-regenerate CLI reference
Applied from the cli-docs-freshness-patch artifact of https://github.com/gastownhall/beads/actions/runs/29613329749
(generated with CI's canonical pinned build). See
scripts/check-cli-docs-drift.sh for how drift is attributed.
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Fenced-window procedure: backup, soft-reset squash to a baseline commit,
drop stale refs, gc --full, force re-publish, re-clone everywhere else.
Motivated by the wyvern deployment's 3.6G of reachable lease-churn
history (wy-7lmdp).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: redirect legacy Pages site to Mintlify (mybd-aokv)
Agent-Signature: codex-gpt-5.6-sol-high on behalf of matt wilkie
* docs: harden legacy Pages redirect
Agent-Signature: codex-gpt-5.6-terra-medium on behalf of matt wilkie
- FAQ: fix bulk migration/export commands (tracker pull/push need explicit
IDs; bulk lives on sync --pull-only / --pull / --push-only / --push) and
correct the cross-project isolation claim (hydration + external targets)
- quickstart: replace the broken DOLT.md blob URL with site links
- installation: Quick Install Script heading matches its macOS/Linux/FreeBSD
body
- rewrite 33 stale SCREAMING_CASE link labels to the target pages' titles
- add description frontmatter to the 55 authored pages missing it
- docs.json: wildcard redirects for the old /next/ and version-prefixed
route spaces (1.0.0, 1.0.4, 1.0.5)
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.
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 (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).
- 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.
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).