* fix(init): wire git origin as Dolt remote
Default bd init now treats a git origin as the Dolt remote, persists sync.remote, and still skips synthesis in --stealth. JSONL auto-export/import paths now warn or skip based on sync.remote so exports do not masquerade as cross-machine sync.
Docs and generated agent/CLI references now state that Dolt is canonical, refs/dolt/data is the sync channel, and .beads/issues.jsonl is export/interchange/backup only.
_codex-gpt-5-xhigh on behalf of maphew_
* test: keep embedded command stderr out of parsed stdout
Embedded command tests parse IDs and JSON from command output. The new auto-export warnings correctly go to stderr, but several tests used CombinedOutput and treated warnings as stdout, which broke CI shards that parse issue IDs or JSON lists. Capture stdout separately on success while preserving combined output for error diagnostics.\n\n_codex-gpt-5-medium on behalf of CI Bot_
---------
Co-authored-by: CI Bot <ci@beads.test>
Remove gastown-specific language. Replace the formula command's Rig/Cook/Run lifecycle wording with existing beads verbs: define formulas, cook them into protos, then pour or wisp them into work. Describe GT_ROOT formulas as a shared workspace root instead of an orchestrator path. Update generated CLI references and add a regression check for the help text.
_codex-gpt-5-medium on behalf of matt wilkie_
Reverts PR #3498 / commit 0fffa44a2302a496dfa4ffa838843b3bbf0ee122.\n\nPR #3498 added BEADS_DOLT_CLI_DIR routing without a confirmed reproduction and introduced an external-server push/pull regression. Remove that override and its docs/tests so main no longer requires a local CLI database directory in external-server mode.\n\n_codex-gpt-5- on behalf of CI Bot_
Complete mybd-pnm docs evidence review.\n\n- Add verified docs disposition inventory and canonical seams.\n- Stage stale duplicate docs under docs/staged-for-removal with a manifest.\n- Refresh generated CLI docs and harden the generator for CRLF/stdin handling.\n\nFollow-up: mybd-xfr for automated docs freshness checks.
Fixes Gemini CLI hook integration by emitting the required SessionStart JSON envelope. Extends the same standard to Claude Code hooks (documented spec, not just tolerated raw text). Adds legacy detection in bd setup gemini --check.
- Add `--hook-json` flag to `bd prime` wrapping output in the cross-CLI `hookSpecificOutput.additionalContext` JSON envelope (Claude Code, Gemini CLI, and Codex all share this contract)
- Update `bd setup gemini` to register `bd prime --hook-json` on SessionStart; remove PreCompress registration (advisory-only, no additionalContext support per Gemini docs v0.40.1)
- Update `bd setup claude` to register `bd prime --hook-json` on SessionStart and PreCompact (JSON form is the documented spec; raw text was merely tolerated)
- Migration sweeps in both setup commands so re-running upgrades bare-command installs cleanly
- `bd setup gemini --check` distinguishes current (`--hook-json`) from legacy (bare `bd prime`) installs and emits upgrade advisory for legacy
- Fix `removeHookCommand` bug: previously dropped entire hook entry on first command match, silently deleting sibling commands; now filters only the matching command and drops the entry only when empty
- Refresh docs and recipes to reflect SessionStart-only Gemini hook behavior
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Resolve the stale CLAUDE.md problem by removing the duplicated workflow/build/storage guide from the root Claude entrypoint. The root file now points to canonical sources, while the unique Visual Design System content moves into AGENT_INSTRUCTIONS.md where AGENTS.md already directs agents for full guidance.
Also refresh docs/CLAUDE.md architecture paths that had drifted from current main.
Refs GH#3426.
Co-authored-by: Steven Syrek <steven.syrek@deepl.com>
The dolt.idle-timeout config key has had no consumer in the tree since
GH#2452 (commit 4df17ca34, in v0.60.0) removed the idle-monitor and
activity-signal daemon infrastructure. There is:
- No SetDefault for it in internal/config/config.go
- No GetString/GetDuration/viper consumer anywhere in cmd/ or internal/
- Only references are docs, the YamlOnlyKeys entry, and a validator case
The validator case (yaml_config.go:521) and YamlOnlyKeys entry served
no purpose since the value was never read. Remove both, plus the
'time' import that becomes unused, and update docs.
Out of scope: docs/DOLT-BACKEND.md:467 has 'idle_timeout: "30s"' under
Dolt server lock-retry settings — that's a different idle_timeout from
the upstream Dolt server config, not the removed beads key. Untouched.
Discovered while reviewing PR #3714 (mybd-b5q).
Amp-Thread-ID: https://ampcode.com/threads/T-019dfe19-17ae-713e-bc3a-d7c9da6a117d
Co-authored-by: Amp <amp@ampcode.com>
* docs: generate CLI reference from live help
* docs(cli): move bd version stamp from per-command pages to index only
Drops the `(bd version X.Y.Z)` suffix from the auto-generated header on
every per-command CLI reference page (writeSingleCommandDoc) and the
docs/CLI_REFERENCE.md preamble (writeAllHelp). The version label now
lives only on the index page emitted by scripts/generate-cli-docs.sh:
- Dev tree (website/docs/cli-reference/index.md, docs/CLI_REFERENCE.md):
labelled "Latest"
- Versioned snapshots (website/versioned_docs/version-X.Y.Z/...):
labelled with the explicit semver tag parsed from the directory name
This eliminates the 100+-file no-signal diff a release version bump
otherwise produces, restoring the "regen as a separate small commit"
workflow PR #3704 enables. After this change a version bump alone
yields zero diff on the dev tree; only the new versioned snapshot
created at release-cut time carries the new tag. No datestamps are
introduced anywhere — scripts/generate-cli-docs.sh --check remains
deterministic across CI runs.
Refs: mybd-afb, PR #3704
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Phase 1 of mybd-p71. PR #3704 made docs/CLI_REFERENCE.md and the website
CLI reference pages generated-from-live-help with a --check freshness
gate. The same drift shape exists in many other reference-style docs
across the repo; without a maintenance prompt the same trust gap that
caused GH#3683 will recur.
This commit adds docs/DOC_INVENTORY.md, which:
- Enumerates every hand-written .md file in the repo (246 files; 12
excluded as already covered by PR #3704).
- Classifies each as (a) intentionally hand-written / (b) reference-style
drift candidate / (c) other (snapshots, historical, stubs).
- Identifies the (b) files with a clean machine-readable data source
(config struct, cobra tree, OTel attributes, exit-code constants) and
estimates generator size for each.
- Identifies the (b) files with no clean source as freshness-check only.
- Compares five plausible freshness mechanisms (cron, bd preflight,
CONTRIBUTING checklist, per-doc --check validators, hybrid) and
recommends a hybrid: per-doc --check generators (modelled on PR #3704)
for docs with a clean source, plus an explicit `Last reviewed:` field
(already in production use in docs/SECURITY-DEPENDENCY-EXCEPTIONS.md)
for the rest.
Surprises documented in the inventory include
website/docs/reference/configuration.md being wholly stale (TOML +
BEADS_* env vars vs. the live YAML + BD_* implementation), docs/FAQ.md
opening with "git-based issue tracker", docs/EXTENDING.md being missing
but referenced by an example, a second hand-written CLI reference
inside the plugin skill bundle, and several duplication candidates
(docs/DOLT.md vs docs/DOLT-BACKEND.md; root vs docs/ RELEASING.md).
This is **Phase 1 only**: inventory + classification + recommendation.
Phase 2 (apply hand-written-status markers per doc, file follow-up
beads per category, implement freshness-check code) is scoped after
maintainer review of this inventory.
Tracking bead: mybd-p71.
Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Address PR #3670 review nits:
1. The managed Codex AGENTS.md section pointed at "the beads skill"
without saying where SKILL.md lives. Codex does not auto-discover
.agents/skills/, so include explicit project and global paths in
the section body so an agent reading AGENTS.md can find the skill.
2. bd setup codex uses its own BEADS CODEX SETUP markers, separate
from the BEADS INTEGRATION markers used by factory/mux. Document
in docs/SETUP.md that both can coexist in the same AGENTS.md and
that each setup's --check/--remove only touches its own section.
The "Current Status" section opened with "**22 issues** as of Nov 6,
2025", a date-stamped count that fossilizes immediately after the date
passes and leaves readers unsure whether the rest of the doc is
current. Removed the count and date, plus the "Historical note"
paragraph tracking the cleanup arc through October 2025.
While in the file, also dropped the "(N issues)" sub-counts on each
linter section heading and on the gosec pattern bullets, and reworded
the two later references to "the 22 lint warnings" / "the baseline 22"
in the Recommendation section. These were the same antipattern at
smaller scale and would have drifted out of sync the moment the
baseline changed.
The narrative point — that the remaining warnings are intentional /
idiomatic and not a quality problem — is preserved, and readers who
want a current count are pointed at running golangci-lint locally.
Refs: mybd-6yw, GH#3683, PR#3706
Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The FAQ opened by calling beads a "git-based issue tracker", which
contradicts the Dolt-native architecture documented elsewhere (README
opens with "Distributed graph issue tracker for AI agents, powered by
Dolt"; the FAQ itself later explains `bd dolt push` / `bd dolt pull`
and Dolt branches independent of git branches).
Newcomers reading the FAQ first formed an incorrect mental model:
storage backend = git, sync mechanism = git push/pull. In reality,
issues live in a local Dolt database and sync via Dolt remotes; git
is only involved for project code (and optionally for ferrying the
exported `.beads/issues.jsonl` between machines).
Replaced "git-based issue tracker" with "version-controlled issue
tracker" — accurate without dropping the "Dolt" vendor name in the
opening line (newcomers do not yet recognize Dolt; it is introduced
later in the FAQ where context is built up).
Also fixed downstream misframings in the same file:
- "Git-First, ..." differentiator header -> "Offline-First, ..."
- "git-synchronized task memory" -> "version-controlled task memory"
- "Git-native sync" -> "Built-in sync" (Taskwarrior comparison)
- "Sync via git commits" -> "Sync via `bd dolt push` / `bd dolt pull`"
- "bd's git-based sync" -> "bd's version-controlled storage" + cell-level merge
- "Sync happens via git push/pull" -> "Sync happens via `bd dolt push` / `bd dolt pull`"
Left genuine git references untouched: the merge-conflict section
showing JSONL diffs (issues.jsonl is a real git-tracked artifact for
portability), git hooks, `bd init`'s git interaction, the "walks up
like git" auto-discovery analogy, and the worktree FAQs.
Tracking: mybd-ujr
GH: #3683
PR: #3706 (precursor)
Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: fix broken xref to docs/EXTENDING.md in extension example
The extension example README referenced docs/EXTENDING.md in three
places, but that file was deliberately deleted in the SQLite -> Dolt
migration (see CHANGELOG entry "Deleted deprecated docs - removed
EXTENDING.md and MULTI_REPO_HYDRATION.md (SQLite-era, no longer
applicable)"). Anyone following the example hits a broken link.
Removed all three references. The example README is itself the
canonical reference for the extension pattern, so no redirect target
is needed.
Note: other docs in the repo still reference the deleted EXTENDING.md
(docs/ADVANCED.md, docs/CONFIG.md, examples/library-usage/README.md,
website/docs/reference/advanced.md). Those are out of scope for this
fix and should be addressed in follow-up issues.
Tracking bead: mybd-q71
GH: #3683
PR: builds on follow-up audit from PR #3706
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: fix remaining broken xrefs to deleted EXTENDING.md across repo
Round 1 (commit ddeff314c) only fixed the extension example README
because the original prompt scoped that PR narrowly. The bead
(mybd-q71) acceptance is repo-wide ("no broken xrefs anywhere"), so
this follow-up sweeps the rest in the same PR per the project's
"one issue per PR" rule.
Per-file treatment (EXTENDING.md was deleted in commit 508387377
before v1.0.0 was tagged, so even the v1.0.0 versioned snapshot has
been broken since release):
- docs/ADVANCED.md (3 refs):
* Note in Extensible Database section: drop trailing "See
EXTENDING.md for details" — the surrounding sentence about
Dolt-era alternatives stands on its own.
* Bold "See EXTENDING.md for complete documentation" line:
redirect to the canonical working example
(examples/bd-example-extension-go).
* Next Steps bullet: same redirect.
- docs/CONFIG.md (2 refs):
* Namespace doc for compact_*: replace "(see EXTENDING.md)" with
"(used by `bd admin compact`)" — the doc itself describes the
keys, no external reference needed.
* See Also bullet: replace with link to docs/ADVANCED.md
(Extensible Database section).
- examples/library-usage/README.md (1 ref):
* See Also bullet: replace EXTENDING.md link with link to the
sibling bd-example-extension-go example.
- website/docs/reference/advanced.md (1 ref):
* Custom Tables section: replace EXTENDING.md link with link to
the bd-example-extension-go README on GitHub.
- website/versioned_docs/version-1.0.0/reference/advanced.md (1 ref):
* Same fix as the live docs. EXTENDING.md was deleted before
v1.0.0 release (commit 508387377 is an ancestor of tag v1.0.0),
so this versioned snapshot has been broken since cut and a fix
here doesn't violate frozen-in-time correctness — the link was
never valid in the v1.0.0 release.
- website/static/llms-full.txt (1 ref, auto-generated artifact):
* Updated to match the corrected source so the on-disk artifact
isn't broken until next regeneration.
- beads.go and internal/beads/beads.go (package doc comments):
* Replaced "see docs/EXTENDING.md" / "see EXTENDING.md" with a
pointer to examples/bd-example-extension-go. These were real
broken pointers in published Go source comments.
CHANGELOG.md historical entries left untouched (intentional history).
cmd/bd/info.go:747 left untouched (it's a programmatic CHANGELOG
entry rendered by `bd info`, equivalent to a CHANGELOG line).
Verification:
grep -rn 'EXTENDING\.md' --include='*.md' .
returns only CHANGELOG.md hits.
Tracking bead: mybd-q71
GH: #3683
PR: #3713 (round 2)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add staleness detection so agents and devs automatically get fresh
Linear data without retry infrastructure.
- New staleness library (internal/linear/staleness.go): WriteLastPull,
ReadLastPull, IsPullStale, IsWithinDebounce, GetStalenessInfo
- --pull-if-stale flag on bd linear sync with configurable --threshold
(default 20m) and 5-minute debounce to prevent agent loops
- bd prime auto-pulls when stale and LINEAR_API_KEY is set
- Per-session stderr warning on any bd command when data is stale
- 14 new tests covering all staleness functions
Design validated by three adversarial reviewers (architecture,
performance, agent-native). Morning storm (50 devs) = 1% of rate
limits. Scales to 500 devs safely.
Refs: PLAN.md d16, btl-seo
* fix(config): refuse to write secret keys to git-tracked config.yaml
P0 security fix. bd config set for secret keys (api_key, secret, token,
password) now detects git tracking of the target config file and refuses
the write with an actionable error pointing to env var alternatives.
Adds --force-git-tracked escape hatch for tests. Updates stale template
documentation and setup guides to lead with env var approach.
* fix(config): scope secret git safety check to YAML-backed keys
Use real environment variable hints for known secret config keys and avoid blocking database-backed secret-looking keys such as notion.token.
Maintainer follow-up for PR #3652.
* fix(config): silence gosec on env var hint names
The map contains environment variable names, not secret values.
---------
Co-authored-by: matt wilkie <maphew@gmail.com>
* Add init remote bootstrap path (bd-cil)
* fix(init): adopt source _project_id when bootstrapping from remote
When `bd init --remote=<url>` cloned an existing Dolt remote, the
ProjectID adoption gate at init.go:867 only fired for `--database`
(GH#2922), so a fresh ProjectID was minted and then written back to
the cloned database, overwriting the source rig's identity and
breaking cross-project verification on subsequent pulls.
Extend the gate to also adopt when `bootstrappedFromRemote` is true,
matching the GH#2922 intent: if another rig already chose an
identity, inherit it rather than overwrite.
Fixes the failing TestEmbeddedInit/remote_bootstraps_existing_dolt_data
subtest added in this PR. The other --remote subtests (empty source,
plain git origin) and the GH#2922 --database path are unaffected.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* cmd/bd: extract sanitizeDBName to its own file for CGO_ENABLED=0 lint
sanitizeDBName lived in store_factory.go which is //go:build cgo,
but init.go (no tag) calls it. The pre-commit golangci-lint runs
with CGO_ENABLED=0 and flagged it as undefined. Move the pure-Go
function to its own untagged file and drop the now-unused strings
import from store_factory.go. No behavior change.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* schema: tolerate "does not have column" errors in migration runner
Broadens isConcurrentInitError to also treat "does not have column"
as a benign migration error, symmetric with the existing "duplicate
column" tolerance for ADD races. Makes DROP COLUMN migrations
idempotent across databases bootstrapped with different base schemas.
Observed failure: migration 0032 (DROP COLUMN applied_at) loops
forever on any database that lands at v31 without the column. Dolt
has no DROP COLUMN IF EXISTS, so the SQL itself can't be guarded;
handling it in the runner keeps the migration file trivial.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Add migration 0032 idempotence tests (bd-7mh.3)
* Document bd execution metadata workflow (bd-b1a)
* Revert "Document bd execution metadata workflow (bd-b1a)"
This reverts commit 0d6a96babd.
* Reapply "Document bd execution metadata workflow (bd-b1a)"
This reverts commit df90cf5404.
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
Fix stale agent-facing documentation for Dolt-only storage, build/test commands, claiming work, and removed references. Includes maintainer cleanup to align remaining stale test guidance with the current make test / test-icu-path policy.\n\nCo-authored-by: Kevin Glynn <12972584+kevglynn@users.noreply.github.com>\nCo-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Removed bare first-party go install .../cmd/bd@latest guidance from docs,
website docs, plugin/npm docs, examples, and doctor hints.
- Standardized on:
- CGO_ENABLED=0 go install ... for server-mode only
- CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install ... for embedded-
capable
- Added scripts/check-go-install-guidance.sh and wired it into CI.
- Updated default.nix to use gms_pure_go instead of ICU flags.
Validation passed locally:
- make test
- golangci-lint run --build-tags=gms_pure_go ./...
- ./scripts/check-go-install-guidance.sh
- ./scripts/check-build-tags.sh
- go test -tags gms_pure_go ./cmd/bd/doctor
- doc flag check
* fix(init): refuse --force when remote has Dolt history
bd init --force in a repo whose origin has refs/dolt/data silently
skipped the bootstrap-from-remote path and then wired origin as a Dolt
remote anyway. The next write auto-pushed an orphan history, failing
with "no common ancestor". Recovery options were all destructive.
This change:
- Adds --reinit-local (named-intent replacement for --force) and
--discard-remote (explicit cross-boundary authorization).
- Routes --force to --reinit-local with a DeprecationWarning. --force
continues to work for ≥2 releases.
- Refuses bd init --force / --reinit-local when origin has
refs/dolt/data, unless --discard-remote is also passed. Exit code 10
(ExitRemoteDivergenceRefused).
- Adds stable numeric exit codes for init refusals (10/11/12).
- Adds bd init-safety documenting the full flag surface and the
destroy-token format.
- Adds an internal race-safety re-check: if remote state changes
during the TTY confirmation window, abort rather than overwrite.
- Retrofits the existing destroy-token echo at init.go:231 to not
print a copy-pasteable destructive invocation, matching the new
error-text-no-echo ADR invariant.
Adds:
- cmd/bd/init_safety.go — CheckRemoteSafety chokepoint (pure fn).
- cmd/bd/init_safety_test.go — guard matrix (13 cases) + subprocess
regression test with a synthetic refs/dolt/data fixture.
- docs/adr/0002-init-safety-invariants.md — ADR encoding the five
invariants (single-source identity, scope-bound --force, central
chokepoint, error-text-no-echo, race-safety).
- docs/RECOVERY.md — named recovery playbooks per refusal exit code.
- .github/CODEOWNERS — review ownership for init*.go pointing at the
ADR so future flags must extend the guard matrix.
Historical pattern (git log for cmd/bd/init.go): 8+ prior commits
patched individual surfaces of this class without encoding the
invariant. The guard matrix test is the structural hedge — adding a
new flag or data source is a signal to extend the table, not to add
another `&& !someFlag` at the call site.
(bd-q83)
* fix(init): satisfy lint for origin safety helpers (bd-main-nwo)
---------
Co-authored-by: matt wilkie <maphew@gmail.com>
Auto-push was enabled whenever an "origin" remote existed. At any
concurrency above one writer, git+ssh remotes have no chunk-level
upload atomicity: concurrent dolt pushes race on the remote manifest
and can leave it referencing chunks that were never uploaded. Any
subsequent clone/fetch/push then propagates the dangling reference.
Change the default to off. Set dolt.auto-push=true in
.beads/config.yaml (or BD_DOLT_AUTO_PUSH=true) to restore auto-push
on single-writer setups.
Rename TestIsDoltAutoPushEnabled_DefaultNoStore to _DefaultOff —
the test now documents the intended default, not a nil-store edge case.
Co-authored-by: gastown/crew/woodhouse <5449665+ckumar1@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat: add BD_JSON_ENVELOPE=1 opt-in for uniform JSON wrapping
Follow-up to #3368 as discussed with @maphew. Adds the envelope format
that wraps all --json output as {"schema_version": N, "data": <payload>},
gated behind BD_JSON_ENVELOPE=1 to avoid breaking existing consumers.
Legacy mode (default): unchanged behavior from #3368 — objects get
schema_version injected inline, arrays pass through raw.
Envelope mode (BD_JSON_ENVELOPE=1): uniform wrapping for all types.
The original payload is untouched inside .data — no type corruption,
no field injection. A one-time deprecation notice is emitted to stderr
when --json is used without the env var.
Timeline: envelope becomes default in v2.0, with BD_JSON_ENVELOPE=0
as a temporary escape hatch for one release cycle.
Includes:
- wrapWithSchemaVersion dual-mode logic
- outputJSONError and buildJSONError envelope support
- Deprecation notice on stderr (once per process)
- Tests for both legacy and envelope modes
- Migration guide in docs/JSON_SCHEMA.md
* fix: suppress deprecation notice when stderr is not a TTY
Gate emitEnvelopeDeprecation() on ui.IsStderrTerminal() so the
"NOTE: bd --json output format will change in v2.0" message only
appears in interactive terminals. Test harnesses and pipelines
capture stderr via CombinedOutput(), and the trailing notice after
the JSON closing brace caused json.Unmarshal to fail with
"invalid character 'N' after top-level value" in 15 CI tests.
Follows the same TTY-gating pattern used by ShouldUseColor and
ShouldUseEmoji.
* fix: suppress gosec G304 false positive in hookWorkTreeRoot
The path is filepath.Join(os.Getenv("GIT_DIR"), "gitdir") — reading a
well-known git internal file from a trusted environment variable set by
git itself during hook execution. Not a user-controlled file inclusion.
This false positive causes the Lint CI check to fail on every PR in
the repo, masking real lint issues.