* 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>
* 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>
- 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
Add 3 example .formula.toml files to examples/formulas/:
- feature-workflow: design, implement, review, merge
- release: bump version, test, tag, publish
- quick-check: lint, test, build (designed for wisp use)
These serve as documentation-by-example and give new users
a starting point for creating their own formulas.
Closes#3246
* fix: backward-compatible JSONL import for all pre-v1.0 formats
Three breaking changes accumulated across versions that prevent
importing old JSONL data:
1. Comment.ID changed from int64 to string in v1.0 — old JSONL
with numeric comment IDs crashes the importer. Add custom
UnmarshalJSON that accepts both types.
2. "wisp" field renamed to "ephemeral" in v0.38 — JSONL from
v0.35–v0.37 silently loses the ephemeral flag. Map the old
field name during import.
3. BondRef.proto_id renamed to source_id — old JSONL silently
loses bond source references. Accept proto_id as alias.
Also improve auto-import error messaging: when upgrade recovery
fails, tell the user their data is safe and suggest bd init
--from-jsonl instead of silently swallowing the error.
* fix: use American English spelling for misspell linter
* test: add unit tests for backward-compatible UnmarshalJSON and legacy import
- TestCommentUnmarshalJSON: string IDs, numeric IDs (pre-v1.0),
zero, large numbers, missing ID, invalid JSON
- TestBondRefUnmarshalJSON: source_id, proto_id (legacy),
both fields (precedence), neither, invalid JSON
- TestImportFromLocalJSONL_LegacyFormats: numeric comment IDs
survive import, wisp→ephemeral mapping (true/false/absent)
Add --database flag to bd init so callers can specify a pre-existing server
database name, overriding prefix-based naming. Prevents orphan database creation
when an external tool (e.g. gastown) has already created the database.
Also fixes display bug showing storage path instead of DB name in server mode,
and exports ValidateDatabaseName for use by init validation.
Co-Authored-By: Peter Chanthamynavong <peterkc@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Standardize start-work semantics to `bd update <id> --claim` across docs,
examples, templates, and website static LLM artifacts. Replaces
`--status in_progress` with `--claim` where the meaning is start-work.
Also fixes stale comment in llms.txt ("Update status" → "Start work").
Co-Authored-By: Valeriy Pavlovich <iqdoctor@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Remove examples/markdown-to-jsonl, examples/github-import, and
examples/jira-import. These converters produced JSONL for bd import,
which has been removed. Native bd jira/linear/gitlab sync commands
replace this functionality.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Delete orphaned code left behind after sync-branch, no-db mode, and
daemon removal: worktree engine (zero callers), internal/export package
(zero imports), broken monitor-webui example (imports deleted rpc pkg),
no-db stubs, sync-branch doctor no-ops and their wiring, and vestigial
flush-debounce/remote-sync-interval config keys.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Delete migrate_hash_ids.go (760 lines) and remove hash-ids subcommand,
doctor checks, and readonly test cases. Relocate copyFile to migrate.go
for migrate_dolt.go and repair.go. Rename public API beads.NewStorage()
to beads.Open() across code, tests, examples, and docs. Clean up
transitional SQLite-era comments in store.go and context.go. Add server
mode watchdog with TCP+SQL health probes, auto-restart with stale PID
cleanup, exponential backoff, and clean shutdown.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Executed-By: beads/crew/emma
Rig: beads
Role: crew
Update documentation examples from deprecated NewSQLiteStorage to
NewStorage(ctx, path). Fix monitor-webui to import the public beads
package instead of internal/beads.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Executed-By: beads/crew/emma
Rig: beads
Role: crew
Remove 60 lines of re-exported type aliases and constants from internal/beads
that duplicated internal/types. Update integration tests to import types
directly. Fix examples to use the public beads package API instead of
internal imports.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Executed-By: beads/crew/emma
Rig: beads
Role: crew
Code health review found 30+ instances of error suppression using blank
identifier without explanation. Added comments to 82 files explaining WHY
each error is safely ignored (best-effort cleanup, advisory operations,
safe defaults, etc.) to improve code maintainability.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Executed-By: beads/polecats/jasper
Rig: beads
Role: polecats
Update all documentation to use the new subcommand syntax:
- `bd daemon --start` → `bd daemon start`
- `bd daemon --stop` → `bd daemon stop`
- `bd daemon --status` → `bd daemon status`
- `bd daemon --health` → `bd daemon status --all`
- `--global=false` → `--local`
The old flag syntax is deprecated but still works with warnings.
Closes: bd-734vd
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Update documentation and scripts to reflect the plugin move from
root level to claude-plugin/ subdirectory:
- Fix command links in docs/DAEMON.md, docs/SYNC.md, examples/
- Update plugin.json path references in RELEASING.md, AGENT_INSTRUCTIONS.md
- Update scripts/bump-version.sh and scripts/check-versions.sh
- Update skill documentation paths in claude-plugin/skills/beads/
The marketplace.json correctly stays at .claude-plugin/ (root level)
while plugin.json moved to claude-plugin/.claude-plugin/.
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Adds closed_by_session tracking for entity CV building per Gas Town
decision 009-session-events-architecture.md.
Changes:
- Add ClosedBySession field to Issue struct
- Add closed_by_session column to issues table (migration 034)
- Add --session flag to bd close command
- Support CLAUDE_SESSION_ID env var as fallback
- Add --session flag to bd update for status=closed
- Display closed_by_session in bd show output
- Update Storage interface to include session parameter in CloseIssue
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Executed-By: beads/crew/dave
Rig: beads
Role: crew
Two fixes for real-world Jira Cloud usage:
1. Add fields=*all to API request - v3 search/jql endpoint returns
only issue IDs by default, causing empty title/description imports
2. Add adf_to_text() converter for Atlassian Document Format - API v3
returns rich text fields as ADF JSON instead of plain text/HTML
Also documented:
- Silent auth failure gotcha (200 with empty results vs 401)
- ADF format explanation with conversion examples
Update docs to reflect CLI command restructuring:
- migrate-tombstones → migrate tombstones
- bd quickstart is now hidden, point to docs/QUICKSTART.md
- Add CLI consolidation section to CHANGELOG.md
- Remove quickstart from command tables
🤖 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>
LABELS.md is in docs/, not root.
Fixes#666🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add Linear integration CLI with sync and status commands
- Add `bd linear sync` for bidirectional issue sync with Linear
- Add `bd linear status` to show configuration and sync state
- Stub pull/push functions pending GraphQL client (bd-b6b.2)
* Implement Linear GraphQL client with full sync support
- Add LinearClient with auth, fetch, create, update methods
- Implement pull/push operations with Beads type mapping
- Clean up redundant comments and remove unused code
* Add configurable data mapping and dependency sync for Linear
- Add LinearMappingConfig with configurable priority/state/label/relation maps
- Import parent-child and issue relations as Beads dependencies
- Support custom workflow states via linear.state_map.* config
* Add incremental sync support for Linear integration
- Add FetchIssuesSince() method using updatedAt filter in GraphQL
- Check linear.last_sync config to enable incremental pulls
- Track sync mode (incremental vs full) in LinearPullStats
* feat(linear): implement push updates for existing Linear issues
Add FetchIssueByIdentifier method to retrieve single issues by identifier
(e.g., "TEAM-123") for timestamp comparison during push.
Update doPushToLinear to:
- Fetch Linear issue to get internal ID and UpdatedAt timestamp
- Compare timestamps: only update if local is newer
- Build update payload with title, description, priority, and state
- Call UpdateIssue for issues where local has newer changes
Closes bd-b6b.5
* Implement Linear conflict resolution strategies
- Add true conflict detection by fetching Linear timestamps via API
- Implement --prefer-linear resolution (re-import from Linear)
- Implement timestamp-based resolution (newer wins as default)
- Fix linter issues: handle resp.Body.Close() and remove unused error return
* Add Linear integration tests and documentation
- Add comprehensive unit tests for Linear mapping (priority, state, labels, relations)
- Update docs/CONFIG.md with Linear configuration reference
- Add examples/linear-workflow guide for bidirectional sync
- Remove AI section header comments from tests
* Fix Linear GraphQL filter construction and improve test coverage
- Refactor filter handling to combine team ID into main filter object
- Add test for duplicate issue relation mapping
- Add HTTP round-trip helper for testing request payload validation
* Refactor Linear queries to use shared constant and add UUID validation
- Extract linearIssuesQuery to deduplicate FetchIssues/FetchIssuesSince
- Add linearMaxPageSize constant and UUID validation with regex
- Expand test coverage for new functionality
* Refactor Linear integration into internal/linear package
- Extract types, client, and mapping logic from cmd/bd/linear.go
- Create internal/linear/ package for better code organization
- Update tests to work with new package structure
* Add linear teams command to list available teams
- Add FetchTeams GraphQL query to Linear client
- Refactor config reading to support daemon mode
- Add tests for teams listing functionality
* Refactor Linear config to use getLinearConfig helper
- Consolidate config/env var lookup using getLinearConfig function
- Add LINEAR_TEAM_ID environment variable support
- Update error messages to include env var configuration options
* Add hash ID generation and improve Linear conflict detection
- Add configurable hash ID mode for Linear imports (matches bd/Jira)
- Improve conflict detection with content hash comparison
- Enhance conflict resolution with skip/force update tracking
* Fix test for updated doPushToLinear signature
- Add missing skipUpdateIDs parameter to test call
Remove the external MCP Agent Mail server integration that required
running a separate HTTP server and configuring environment variables.
The native `bd mail` system (stored as git-synced issues) remains
unchanged and is the recommended approach for inter-agent messaging.
Files removed:
- cmd/bd/message.go - Legacy `bd message` command
- integrations/beads-mcp/src/beads_mcp/mail.py, mail_tools.py
- lib/beads_mail_adapter.py - Python adapter library
- examples/go-agent/ - Agent Mail-focused example
- examples/python-agent/agent_with_mail.py, AGENT_MAIL_EXAMPLE.md
- docs/AGENT_MAIL*.md, docs/adr/002-agent-mail-integration.md
- tests/integration/test_agent_race.py, test_mail_failures.py, etc.
- tests/benchmarks/ - Agent Mail benchmarks
Updated documentation to remove Agent Mail references while keeping
native `bd mail` documentation intact.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When bd sync pushes from the sync-branch worktree, the pre-push hook
would detect uncommitted JSONL changes and suggest running bd sync -
which is circular since that's what the user is already doing.
Fix: Set BD_SYNC_IN_PROGRESS=1 environment variable when pushing from
worktree, and update pre-push hook to skip checks when this var is set.
Updated files:
- internal/syncbranch/worktree.go: Set env var on push command
- cmd/bd/templates/hooks/pre-push: Check for env var and exit early
- examples/git-hooks/pre-push: Same check
- .beads-hooks/pre-push: Same check
Fixes GH#409 - Documentation inconsistently referred to beads.jsonl
as the canonical filename when issues.jsonl has been the default
since v0.25.1 (bd-6xd).
Updated files:
- docs/ARCHITECTURE.md
- docs/CLI_REFERENCE.md
- docs/PROTECTED_BRANCHES.md
- docs/ADVANCED.md
- docs/GIT_INTEGRATION.md
- docs/MULTI_REPO_AGENTS.md
- docs/MULTI_REPO_MIGRATION.md
- docs/TROUBLESHOOTING.md
- examples/*/README.md
- skills/beads/references/CLI_REFERENCE.md
Note: beads.jsonl is still supported for backward compatibility.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Two fixes to make pre-commit hook more resilient:
1. Check if beads is actually initialized (has db, config, or jsonl)
- Empty .beads directory no longer triggers sync attempt
- Handles case where .beads was removed from git but dir lingers
2. Make sync failure a warning instead of blocking error
- Beads issues shouldn't prevent code commits
- User can still run 'bd sync --flush-only' manually
Also synced examples/git-hooks/pre-commit with template (worktree handling).
Closes#483🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Fixes GH#483 - The pre-commit hook was blocking commits when
`bd sync --flush-only` failed, even if the user had removed beads
from their branch. This made it impossible to commit on branches
that don't have beads configured.
Changes:
- Change "Error:" to "Warning:" in the message
- Remove `exit 1` so commits proceed even if flush fails
- Add comments explaining why we don't block commits
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: fix Go version typo in CONTRIBUTING.md (1.25 -> 1.24)
* docs: update Go version requirement to 1.24+ across docs
* docs: fix broken links to docs/ in npm-package/README.md
* docs: fix QUICKSTART.md path reference in AGENTS.md
Reorganize the claude-code-skill into a publishable plugin that can be
installed through the beads-marketplace. Users can now reference the
'beads' skill right after installing the marketplace.
Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
Update `/bd-create` and `/bd-ready` to `/beads:create` and `/beads:ready`
in the claude-code-skill README. This was missed in PR #467.
Relates to #463🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Replaces manual working directory save/restore patterns
with Go's built-in `t.Chdir()` helper across 23 test files.
The manual pattern involved calling `os.Getwd()` to save
the original directory, using `defer os.Chdir(origWd)` for
restoration, and manually handling errors during directory
changes. This boilerplate has been replaced with single
`t.Chdir(path)` calls that handle cleanup automatically.
The `t.Chdir()` method automatically restores the working
directory when the test completes, eliminating the need for
manual defer statements and error handling.
Total:
~75 instances replaced (assuming Claude's math is right)
Co-authored-by: Claude <noreply@anthropic.com>
- Fix DEPENDENCIES.md: correct parent-child syntax (child depends on parent)
- Update bd show: display Children instead of Blocks for parent-child deps
- Group dependents by type with distinct labels
Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes#441. The JIRA REST API v2 /search endpoint has been deprecated
and returns HTTP 410 Gone. Migrate to API v3 /search/jql endpoint.
Changes:
- Update API endpoint from /rest/api/2/search to /rest/api/3/search/jql
- Add URL encoding for JQL query parameter (Python 3.14 compatibility)
- Add reference to Atlassian migration guide
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>