* 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>
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.
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: 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>
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>
* fix: enable auto-export by default with canonical issues.jsonl name (GH#2973)
Users expected JSONL export to refresh automatically but export.auto
defaulted to false, requiring explicit opt-in. Also the default filename
(export.jsonl) didn't match the canonical issues.jsonl used in docs and
git hooks. Change defaults: export.auto=true, export.path=issues.jsonl,
export.git-add=true so viewers (bv) and git workflows see fresh data
without extra configuration.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat(init): add auto-export prompt and document export.* config (GH#2973)
Interactive bd init now asks whether to enable auto-export (default: yes).
Users can opt out during setup instead of discovering the setting later.
Also documents the export.* config namespace in bd config --help with
all four keys (export.auto, export.path, export.interval, export.git-add)
and adds export examples.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: document export.* auto-export config keys (GH#2973)
Document the export.auto/path/interval/git-add keys in docs/CONFIG.md
and note the default-on switch in CHANGELOG.md [Unreleased].
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(export): don't prime throttle on empty init and skip git-add without git (GH#2973)
Review feedback on #3204 surfaced two regressions in the default-on
auto-export path:
1. bd init's PersistentPostRun fired maybeAutoExport with zero issues,
writing an empty .beads/issues.jsonl and saving export-state.json with
the current dolt commit + timestamp. The next `bd create` was then
throttled for up to export.interval (default 60s) because the
timestamp check in maybeAutoExport returned before considering the new
commit, leaving issues.jsonl stale on fresh repos.
Skip saving state and remove the empty file when the export produced
no issues and no memories. The next write runs a real export
immediately.
2. export.git-add defaulting to true emitted
`Warning: auto-export: git add failed: exit status 128` on every
write in the supported standalone BEADS_DIR flow where init
intentionally skips `git init`. Gate the git add call on isGitRepo()
so standalone users get silent, working auto-export.
Adds a scripttest regression guard for the init -> immediate create
path.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* test(memory): disable auto-export in concurrent test (GH#2973)
TestEmbeddedMemoryConcurrent started failing on this branch after
auto-export became the default: every concurrent 'bd remember'/'bd
forget' call now fires maybeAutoExport, which reads store state after
the write. Under 8-worker contention this intermittently leaves a
forgotten key visible to 'bd memories'.
The test exercises memory concurrency, not export behavior; opt it
out of auto-export so the signal stays focused. Followup: investigate
the race between write commit and post-write auto-export read in
embedded Dolt concurrent paths.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add az:// (Azure Blob Storage) as a recognized Dolt remote URL scheme.
Azure Blob Storage URLs were already functional for bootstrap via sync.git-remote, but the URL validator didn't recognize az:// — so config validate and error hints were incomplete.
Thanks to @harry-miller-trimble for the contribution!
* fix: make auto-export and auto-backup errors visible on stderr
Previously, failures in auto-export (JSONL flush) and auto-backup were
logged only via debug.Logf, invisible to normal users. One user lost 46
issues because JSONL export silently stopped working with no warnings.
Upgrade critical error paths from debug.Logf to fmt.Fprintf(os.Stderr)
so users see warnings when their backup/export pipeline breaks. Keep
debug.Logf for non-critical diagnostics (throttle, no-change skip).
Closes#2489
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: remove stale sync references
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add category-aware custom statuses that control behavior in bd ready
and bd list. New config format: bd config set status.custom
"in_review:active,qa_testing:wip,archived:done,on_hold:frozen".
Backward compatible with old flat format. New bd statuses command
lists all statuses with --json support.
Also fix TestKillStaleServersPreservesOtherRepoServers to clear
BEADS_DOLT_AUTO_START env var, since the new IsAutoStartDisabled guard
in killStaleServersForDir short-circuits when set.
PR: #2665
Co-Authored-By: Harry Miller <harry-miller-trimble@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace gastown-specific references with generic alternatives throughout
the codebase:
- Rename --gastown flag to --orchestrator in bd doctor
- Rename gastownMode/gastownThreshold params to orchestratorMode/orchestratorThreshold
- Rename isGasTownTownRoot() to isOrchestratorRoot()
- Replace "gastown" in CLI examples with generic rig names (my-project, other-project)
- Update comments replacing "Gas Town" with "orchestrator" or "multi-agent workspace"
- Update active docs (DOLT.md, CONFIG.md, ADVANCED.md, etc.)
- Update test data to use generic names instead of "gastown"
- Update role templates (deacon, witness, refinery) to use generic language
Preserved as historical (not changed):
- CHANGELOG.md entries (historical record)
- ARTICLES.md (links to real published articles)
- info.go version notes (historical release notes)
- gastown/ file path references in dolt-concurrency.md (point to actual repo)
Simplify actor resolution chain to: --actor > BEADS_ACTOR > BD_ACTOR (deprecated) >
git config user.name > $USER > "unknown". BD_ACTOR still works for backwards compat
but BEADS_ACTOR is now the canonical beads-native env var. Updates all code paths,
tests, and documentation.
Three fixes for validation consistency:
1. bd create --validate now uses LintIssue() instead of ValidateTemplate(),
bringing it to parity with bd lint. A non-empty --acceptance field now
satisfies the "Acceptance Criteria" requirement without needing the
heading in --description. (GH#2468 parity)
2. --dry-run no longer bypasses --validate. Validation now runs before the
dry-run exit, so users get feedback on template issues during preview.
3. New validation.on-close config option (none|warn|error, default: none).
When enabled, warns on terse close reasons (<20 chars) or default
"Closed" reasons. Mirrors existing validation.on-create pattern.
Co-Authored-By: seanmartinsmith <114885497+seanmartinsmith@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Introduces BEADS_DOLT_SHARED_SERVER mode where multiple beads projects
share a single Dolt server on a fixed port (3308), avoiding per-project
server sprawl. Includes `bd init --shared-server`, `bd dolt shared-*`
commands, doctor checks, and comprehensive tests.
Co-Authored-By: Shybko <shybko@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Remove ConflictStrategy, FieldStrategy types and all associated config
validation, getters, and tests. The 3-way merge engine was superseded by
Dolt-native cell-level merge. Also adds DOLT_ROOT_HOST=% to test containers
for Docker port-forwarding compatibility.
Co-Authored-By: Rudy Alvarez <rudygt@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Executed-By: beads/crew/emma
Rig: beads
Role: crew
Update documentation to reflect that only dolt-native sync mode is supported:
- docs/CONFIG.md: Remove git-portable and belt-and-suspenders references
- docs/DOLT-BACKEND.md: Simplify sync mode section
- FEDERATION-SETUP.md: Remove deprecated sync mode table
- agents.md.tmpl: Update "Git-friendly: JSONL" to "Version-controlled: Dolt"
The sync mode code was already cleaned up (only SyncModeDoltNative is valid
in internal/config/sync.go), but documentation still referenced removed modes.
w-bd-004
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add maybeAutoPush() in PersistentPostRun (after auto-commit and auto-backup)
that pushes to the Dolt remote when an origin is configured. Uses the same
pattern as maybeAutoBackup: debounce interval, change detection via commit
hash comparison, and non-fatal warnings on failure.
Config keys: dolt.auto-push (bool, auto-enabled when origin exists),
dolt.auto-push-interval (duration, default 5m).
This completes the Dolt replication story: users add a remote once and
data flows automatically.
Closes: bd-5x9
Executed-By: beads/polecats/quartz
Rig: beads
Role: polecats
Adds `bd backup` command that exports all database tables to sorted JSONL
files in .beads/backup/ for off-machine recovery. Events are exported
incrementally using a high-water mark. Each table is written atomically
via temp file + rename.
Auto-backup runs in PersistentPostRun when backup.enabled is true,
throttled by backup.interval (default 15m). Optional git-push mode
auto-commits and pushes backup files.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Executed-By: beads/crew/emma
Rig: beads
Role: crew
* feat: support issue_id_mode=counter for sequential IDs (GH#2002)
When `issue_id_mode=counter` is set via `bd config set issue_id_mode counter`,
`bd create` now assigns monotonically increasing integer IDs instead of
hash-based IDs. The counter is stored in a new `issue_counter` table (one row
per prefix) and incremented atomically within the same transaction as the issue
insert.
- Add `issue_counter` table to schema (version bumped to 5)
- Add migration 006 to create `issue_counter` table on existing databases
- Add `GetNextIssueCounter()` to queries.go (standalone transaction, for
callers outside CreateIssue)
- Modify `generateIssueID()` to check `issue_id_mode` config and use counter
path when set to "counter"; hash mode remains the default when unset
- Explicit `--id` flag continues to take precedence over counter mode
- Tests: TestGetNextIssueCounter_Sequential, TestGetNextIssueCounter_MultiplePrefixes,
TestCreateIssue_CounterMode, TestCreateIssue_ExplicitIDOverridesCounter,
TestCreateIssue_HashModeDefault, TestMigrateIssueCounterTable
* docs: document issue_id_mode=counter feature (GH#2002)
Add documentation for the sequential counter ID mode across all relevant docs:
- docs/CONFIG.md: new issue_id_mode namespace entry and full example section
with tradeoff table, migration guidance, and per-prefix counter isolation
- .beads/BD_GUIDE.md: counter mode section with when-to-use, migration
considerations, and explicit --id override behavior
- docs/ADAPTIVE_IDS.md: alternative counter mode section with cross-reference
to CONFIG.md
- website/docs/reference/configuration.md: issue_id_mode under ID Generation
with comparison table
* fix: seed counter from existing issues when enabling counter mode (GH#2002)
When issue_id_mode=counter is enabled on a repo that already has manually-created
sequential IDs (e.g., plug-1 through plug-50), the counter used to start at 1,
causing immediate collisions.
Add seedCounterFromExistingIssuesTx() which scans existing issue IDs, finds the
highest numeric suffix for the given prefix, and seeds the issue_counter table
from there. The function is idempotent (skips if a counter row already exists)
and only counts purely-numeric suffixes (ignoring hash-based IDs like test-a3f2).
The seeding is called at first counter use: in generateIssueID() (issues.go) and
GetNextIssueCounter() (queries.go) when sql.ErrNoRows is returned for the prefix.
Add four tests covering: seeding from existing numeric IDs, mixed hash+numeric
IDs, fresh repos (counter starts at 1), and already-seeded counters (no regress).
* feat: add bd config schema and describe commands for agent discoverability (GH#2002)
Adds machine-readable config schema so agents can programmatically discover
all available configuration keys without reading source code.
- internal/config/schema.go: new ConfigKeyDef struct and Schema slice with
43 entries covering core, sync, routing, jira, linear, gitlab, team, mail,
and YAML-only keys; includes type, default, valid values, description, and
storage location per key
- cmd/bd/config.go: adds 'bd config schema' (table + --json) and
'bd config describe <key>' (single-key detail + --json) subcommands
Usage:
bd config schema
bd config schema --json | jq '.[] | select(.key == "issue_id_mode")'
bd config describe issue_id_mode
bd config describe jira.url --json
* refactor: remove overengineered config schema (keep docs only)
Remove the configSchemaCmd and configDescribeCmd subcommands added in
the previous commit, along with internal/config/schema.go (390 lines of
config key definitions). These are out of scope for GH#2002.
- Remove stale "realtime" references from comments, docs, and config
(realtime mode was already removed from valid modes)
- Fix config validation to use actual mode/strategy/sovereignty values
instead of stale names (local/git-branch/external → git-portable/
dolt-native/belt-and-suspenders; lww → newest; none/isolated/federated
→ T1/T2/T3/T4)
- Remove 6 dead functions from config.go (IsSyncModeValid,
IsConflictStrategyValid, IsSovereigntyValid, ShouldExportOnChange,
ShouldImportOnChange, NeedsDoltRemote) — only used in tests,
redundant with existing validators in sync.go
- Update tests and docs to match
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Executed-By: beads/polecats/opal
Rig: beads
Role: polecats
Remove references to SQLite as primary backend, JSONL auto-sync daemon,
daemon configuration settings, and daemon-based architecture descriptions.
Replace with Dolt-native equivalents: Dolt as primary storage, git hooks
for JSONL portability, direct database access, and Dolt server mode for
multi-writer scenarios. (woho.6)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds Dolt auto-commit functionality for write commands and sets explicit commit authors.
Includes fix for race condition in commandDidWrite (converted to atomic.Bool).
Original PR: #1267 by @coffeegoddd
Co-authored-by: Dustin Brown <dustin@dolthub.com>
- Insert git config user.name in fallback chain before final $USER default
- Consolidate duplicate actor resolution logic into single function
- Add BEADS_ACTOR as env var alias for MCP compatibility
- Add tests for actor resolution priority
- Update CONFIG.md with Actor Identity Resolution section
The new fallback order is:
--actor flag > BD_ACTOR > BEADS_ACTOR > git user.name > $USER > "unknown"
Co-authored-by: Ohffs <ohffsnotnow@gmail.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Add .beads/config.yaml support for template validation settings:
- validation.on-create: warn|error|none (default: none)
- validation.on-sync: warn|error|none (default: none)
When set to "warn", issues missing required sections (based on type) show
warnings but operations proceed. When set to "error", operations fail.
Implementation:
- Add validation keys to YamlOnlyKeys in yaml_config.go
- Add defaults in config.go
- Wire up bd create to check validation.on-create config
- Wire up bd sync to run validation before export
- Add tests for config loading
- Update CONFIG.md documentation
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Move cleanup, compact, and reset commands under `bd admin` namespace.
Creates hidden aliases for backwards compatibility that show deprecation
notice when used.
- Create cmd/bd/admin.go with parent command
- Create cmd/bd/admin_aliases.go for hidden backwards-compat aliases
- Update cleanup.go, compact.go, reset.go to remove rootCmd.AddCommand
- Update all documentation to use `bd admin <cmd>` syntax
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Replace beads-metadata with beads-sync throughout docs
(matches code default and internal examples)
- Fix bd daemon start → bd daemon --start (correct flag syntax)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implements on_close hooks in .beads/config.yaml for automation and
notifications. Hooks receive issue data via environment variables
(BEAD_ID, BEAD_TITLE, BEAD_TYPE, BEAD_PRIORITY, BEAD_CLOSE_REASON)
and run via sh -c.
Changes:
- internal/config: Add HookEntry type and GetCloseHooks()
- internal/hooks: Add RunConfigCloseHooks() for executing config hooks
- cmd/bd: Call RunConfigCloseHooks after successful close
- docs/CONFIG.md: Document hooks configuration with examples
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>