beads/docs/docs.json
Steve Yegge 70f9e2f8a3
Beads 1.2 remediation: migration-consent gate — bd never migrates an existing database without explicit consent (#5764)
* 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>
2026-10-08 08:21:31 +00:00

458 lines
12 KiB
JSON

{
"$schema": "https://mintlify.com/docs.json",
"theme": "linden",
"name": "Beads Documentation",
"logo": {
"light": "/images/logo.svg",
"dark": "/images/logo.svg"
},
"favicon": "/images/favicon.svg",
"navbar": {
"links": [
{
"label": "GitHub",
"icon": "github",
"iconType": "brands",
"href": "https://github.com/gastownhall/beads"
},
{
"label": "npm",
"href": "https://www.npmjs.com/package/@beads/bd"
}
]
},
"colors": {
"primary": "#2e8555",
"light": "#3cad6e",
"dark": "#29784c"
},
"redirects": [
{
"source": "/QUICKSTART",
"destination": "/getting-started/quickstart"
},
{
"source": "/INSTALLING",
"destination": "/getting-started/installation"
},
{
"source": "/SETUP",
"destination": "/getting-started/ide-setup"
},
{
"source": "/SYNC_SETUP",
"destination": "/getting-started/sync-setup"
},
{
"source": "/SYNC_CONCEPTS",
"destination": "/core-concepts/sync-concepts"
},
{
"source": "/LABELS",
"destination": "/core-concepts/labels"
},
{
"source": "/METADATA",
"destination": "/core-concepts/metadata"
},
{
"source": "/DEPENDENCIES",
"destination": "/core-concepts/dependencies"
},
{
"source": "/ADAPTIVE_IDS",
"destination": "/core-concepts/adaptive-ids"
},
{
"source": "/graph-links",
"destination": "/core-concepts/graph-links"
},
{
"source": "/ARCHITECTURE",
"destination": "/architecture/index"
},
{
"source": "/DOLT",
"destination": "/architecture/dolt"
},
{
"source": "/DOLT-BACKEND",
"destination": "/architecture/dolt"
},
{
"source": "/STORAGE-BACKENDS",
"destination": "/architecture/dolt"
},
{
"source": "/architecture/storage-backends",
"destination": "/architecture/dolt"
},
{
"source": "/MOLECULES",
"destination": "/workflows/molecules"
},
{
"source": "/TODO",
"destination": "/workflows/todo"
},
{
"source": "/RECOVERY",
"destination": "/recovery/init-safety"
},
{
"source": "/UNINSTALLING",
"destination": "/recovery/uninstalling"
},
{
"source": "/ROUTING",
"destination": "/multi-agent/routing"
},
{
"source": "/MULTI_REPO_AGENTS",
"destination": "/multi-agent/coordination"
},
{
"source": "/MULTI_REPO_MIGRATION",
"destination": "/multi-agent/multi-repo-migration"
},
{
"source": "/FEDERATION",
"destination": "/multi-agent/federation"
},
{
"source": "/PLUGIN",
"destination": "/integrations/claude-code-plugin"
},
{
"source": "/ADO_CONFIG",
"destination": "/integrations/azure-devops"
},
{
"source": "/COPILOT_INTEGRATION",
"destination": "/integrations/github-copilot"
},
{
"source": "/COPILOT_CLI_INTEGRATION",
"destination": "/integrations/copilot-cli"
},
{
"source": "/CLAUDE_INTEGRATION",
"destination": "/integrations/claude-code"
},
{
"source": "/CODEX_INTEGRATION",
"destination": "/integrations/codex"
},
{
"source": "/AIDER_INTEGRATION",
"destination": "/integrations/aider"
},
{
"source": "/CONFIG",
"destination": "/reference/configuration"
},
{
"source": "/GIT_INTEGRATION",
"destination": "/reference/git-integration"
},
{
"source": "/WORKTREES",
"destination": "/reference/worktrees"
},
{
"source": "/PROTECTED_BRANCHES",
"destination": "/reference/protected-branches"
},
{
"source": "/ADVANCED",
"destination": "/reference/advanced"
},
{
"source": "/JSON_SCHEMA",
"destination": "/reference/json-schema"
},
{
"source": "/OBSERVABILITY",
"destination": "/reference/observability"
},
{
"source": "/TROUBLESHOOTING",
"destination": "/reference/troubleshooting"
},
{
"source": "/ANTIVIRUS",
"destination": "/reference/antivirus"
},
{
"source": "/FAQ",
"destination": "/reference/faq"
},
{
"source": "/COMMUNITY_TOOLS",
"destination": "/community-tools"
},
{
"source": "/RELATED_PROJECTS",
"destination": "/related-projects"
},
{
"source": "/CLI_REFERENCE",
"destination": "/cli-reference/index"
},
{
"source": "/next/:slug*",
"destination": "/:slug*"
},
{
"source": "/1.0.0/:slug*",
"destination": "/:slug*"
},
{
"source": "/1.0.4/:slug*",
"destination": "/:slug*"
},
{
"source": "/1.0.5/:slug*",
"destination": "/:slug*"
},
{
"source": "/1.1.0/:slug*",
"destination": "/:slug*"
}
],
"navigation": {
"groups": [
{
"group": "Getting Started",
"pages": [
"index",
"getting-started/installation",
"getting-started/quickstart",
"getting-started/ide-setup",
"getting-started/sync-setup",
"getting-started/upgrading"
]
},
{
"group": "Core Concepts",
"pages": [
"core-concepts/index",
"core-concepts/issues",
"core-concepts/dependencies",
"core-concepts/hash-ids",
"core-concepts/adaptive-ids",
"core-concepts/graph-links",
"core-concepts/sync-concepts",
"core-concepts/labels",
"core-concepts/metadata"
]
},
{
"group": "Architecture",
"pages": [
"architecture/index",
"architecture/dolt"
]
},
{
"group": "Workflows",
"pages": [
"workflows/index",
"workflows/molecules",
"workflows/formulas",
"workflows/gates",
"workflows/wisps",
"workflows/todo"
]
},
{
"group": "Recovery",
"pages": [
"recovery/index",
"recovery/accidental-1-2-1-release",
"recovery/init-safety",
"recovery/database-corruption",
"recovery/merge-conflicts",
"recovery/circular-dependencies",
"recovery/sync-failures",
"recovery/history-squash",
"recovery/unmigrate-schema-v65",
"recovery/uninstalling"
]
},
{
"group": "Multi-Agent",
"pages": [
"multi-agent/index",
"multi-agent/routing",
"multi-agent/coordination",
"multi-agent/federation",
"multi-agent/bucket-federation",
"multi-agent/multi-repo-migration"
]
},
{
"group": "Integrations",
"pages": [
"integrations/index",
"integrations/aider",
"integrations/claude-code",
"integrations/claude-code-plugin",
"integrations/codex",
"integrations/cody",
"integrations/cursor",
"integrations/factory",
"integrations/gemini",
"integrations/junie",
"integrations/kilocode",
"integrations/kiro",
"integrations/mux",
"integrations/opencode",
"integrations/windsurf",
"integrations/mcp-server",
"integrations/github-copilot",
"integrations/copilot-cli",
"integrations/azure-devops"
]
},
{
"group": "Community",
"pages": [
"community-tools",
"related-projects"
]
},
{
"group": "Reference",
"pages": [
"reference/index",
"reference/configuration",
"reference/git-integration",
"reference/worktrees",
"reference/protected-branches",
"reference/advanced",
"reference/json-schema",
"reference/events-journal",
"reference/observability",
"reference/troubleshooting",
"reference/antivirus",
"reference/faq",
{
"group": "CLI Reference",
"pages": [
"cli-reference/index",
"cli-reference/admin",
"cli-reference/ado",
"cli-reference/assign",
"cli-reference/audit",
"cli-reference/backup",
"cli-reference/batch",
"cli-reference/blocked",
"cli-reference/bootstrap",
"cli-reference/branch",
"cli-reference/children",
"cli-reference/close",
"cli-reference/comment",
"cli-reference/comments",
"cli-reference/compact",
"cli-reference/completion",
"cli-reference/config",
"cli-reference/context",
"cli-reference/cook",
"cli-reference/count",
"cli-reference/create-form",
"cli-reference/create",
"cli-reference/defer",
"cli-reference/delete",
"cli-reference/dep",
"cli-reference/diff",
"cli-reference/doctor",
"cli-reference/dolt",
"cli-reference/duplicate",
"cli-reference/duplicates",
"cli-reference/edit",
"cli-reference/epic",
"cli-reference/export",
"cli-reference/federation",
"cli-reference/find-duplicates",
"cli-reference/flatten",
"cli-reference/forget",
"cli-reference/formula",
"cli-reference/gate",
"cli-reference/gc",
"cli-reference/github",
"cli-reference/gitlab",
"cli-reference/graph",
"cli-reference/history",
"cli-reference/hooks",
"cli-reference/human",
"cli-reference/import",
"cli-reference/info",
"cli-reference/init-safety",
"cli-reference/init",
"cli-reference/jira",
"cli-reference/kv",
"cli-reference/label",
"cli-reference/linear",
"cli-reference/link",
"cli-reference/lint",
"cli-reference/list",
"cli-reference/mail",
"cli-reference/memories",
"cli-reference/merge-slot",
"cli-reference/metrics",
"cli-reference/migrate",
"cli-reference/mol",
"cli-reference/note",
"cli-reference/notion",
"cli-reference/onboard",
"cli-reference/orphans",
"cli-reference/ping",
"cli-reference/preflight",
"cli-reference/prime",
"cli-reference/priority",
"cli-reference/promote",
"cli-reference/prune",
"cli-reference/purge",
"cli-reference/q",
"cli-reference/query",
"cli-reference/quickstart",
"cli-reference/ready",
"cli-reference/recall",
"cli-reference/recompute-blocked",
"cli-reference/remember",
"cli-reference/rename-prefix",
"cli-reference/rename",
"cli-reference/reopen",
"cli-reference/repo",
"cli-reference/restore",
"cli-reference/rules",
"cli-reference/search",
"cli-reference/set-state",
"cli-reference/setup",
"cli-reference/ship",
"cli-reference/show",
"cli-reference/sql",
"cli-reference/stale",
"cli-reference/state",
"cli-reference/status",
"cli-reference/statuses",
"cli-reference/supersede",
"cli-reference/swarm",
"cli-reference/tag",
"cli-reference/todo",
"cli-reference/types",
"cli-reference/undefer",
"cli-reference/update",
"cli-reference/upgrade",
"cli-reference/vc",
"cli-reference/version",
"cli-reference/where",
"cli-reference/worktree"
]
}
]
}
]
}
}