* pm: decompose be-zej8mz → 3 builder beads for reference-aware prune
Child beads:
- be-jewoem: core implementation in cmd/bd/purge.go
- be-u2mw2x: --help and README docs update
- be-0wt833: bench asserting <5s on 10K-open-bead fixture (blocked on core)
Plan at docs/plans/reference-aware-prune.md.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(prune): reference-aware bd prune skips closed beads cited by open beads (be-jewoem, be-u2mw2x)
Implements be-5sn FR-01 through FR-06:
- buildReferencedSet scans description/notes/comments of every non-closed
bead for literal candidate IDs using word-boundary regexp alternation.
Uses Statuses filter (not ExcludeStatus) to avoid the PG coverage gap
(be-jdeief guardrail per be-5sn §15).
- runPurgeOrPrune filters referenced beads after pinned-filtering when
scope.cmdName == "prune" && !scope.ignoreReferences.
- All 4 human output paths updated: preview, dry-run, force, nothing-to-do.
referenced_skipped/referenced_count always in prune JSON; absent in purge.
referenced_ids_sample omitted when 0 (per be-zej8mz §5).
- --ignore-references flag registered in pruneCmd.Flags() only; purge
init() unchanged so bd purge --ignore-references gives "unknown flag".
- pruneCmd.Long gains reference-protection paragraph per be-zej8mz §3.
- README.md adds Maintenance section documenting prune, purge, and the
reference-aware skip with --ignore-references escape hatch.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* test(prune): NFR-02 bench test for buildReferencedSet on 10K-bead fixture (be-0wt833)
TestPruneLargeFixture generates 10K open beads × ~5KB bodies + 100 closed
candidates with 20 seeded references; asserts buildReferencedSet completes
<5s and returns exactly the seeded IDs.
Passes in ~1.2s on a standard dev machine. Skips under -short.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(prune): regen CLI reference + release gate PASS (be-jewoem)
Regenerate CLI docs with CGO_ENABLED=0 -tags gms_pure_go binary built
from PR HEAD. Adds --ignore-references flag to prune command docs in
CLI_REFERENCE.md and three website prune.md pages.
Gate evaluation: all 6 criteria PASS (AC-6 integration tests deferred
to be-zkzw per reviewer).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(contributor): bd-umbf contributor namespace isolation (Children 1-3)
Child 1 (be-c7696f): Auto-configure contributor routing in bd init
when upstream remote is detected. Non-interactive, idempotent — skips if
routing.contributor is already set. Creates ~/.beads-planning, sets
routing.mode=auto, routing.contributor, sync.remote=upstream, and pins
git beads.role=contributor.
Child 2 (be-9d2b67): bd export --exclude-owner flag and config-driven
export.exclude_owners / export.exclude_owner config. Filters issues by
created_by before writing JSONL. --verbose emits filtered count.
Child 3 (be-3c5a0f): New bd migrate-personal command. Finds project DB
issues whose created_by matches the current git identity, prompts for
confirmation, then moves them to the planning repo (routing.contributor),
copying labels, dependencies, and comments atomically.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(init): match autoConfigureForkContributor output to be-0ccf34 design spec
Three variants were missing; the one present used wrong symbol (✓ instead of ▶).
Happy path: ▶ header, upstream URL echoed, three ✓ action lines, opt-out hint last.
Opt-out path (--role=maintainer on a fork): ⚠ with explanation and recovery hint.
Re-init path (routing already configured): ⚠ with existing path and reconfigure hint.
Non-interactive/quiet: silent (unchanged).
Pass roleFlag through to autoConfigureForkContributor so the opt-out variant fires
when --role=maintainer is given explicitly on a fork.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(contributor): separate insert/delete phases in migrate-personal; suppress nonInteractive output
migrate-personal now copies all issues to planning DB first, then
deletes them from project DB in a single transaction via DeleteIssues.
A mid-loop failure before the delete phase leaves no issues deleted,
making re-runs safe.
Also pass quiet || nonInteractive to autoConfigureForkContributor so
bd init --non-interactive does not emit fork-detection output.
Fixes B4 and the nonInteractive gap from be-72b53f review.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(prune): regen CLI reference — add bd migrate-personal, update bd export flags
Regenerated from bd 1.0.4 dev (9ed33b68d) with CGO_ENABLED=0 -tags gms_pure_go.
Fixes B1: bd migrate-personal was missing from docs/CLI_REFERENCE.md and
all website cli-reference pages.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(gate): update be-jewoem release gate to cover bd-umbf scope
Expands gate scope from be-jewoem/be-u2mw2x only to include bd-umbf
Children 1-3 commits added to the branch. Documents blocker resolution
status (B1/B2/B4 resolved, B3 pending validator), updates CI results to
latest all-green run 26009209774, and marks overall gate ON HOLD pending
validator tests.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(gate): update be-jewoem gate — PR description refreshed, B3 dependency chain clarified (2026-05-19)
* test(contributor): be-f9a104 — bd-umbf export+migrate-personal tests
6 tests for bd-umbf Children 2-3 per be-f9a104 scope:
cmd/bd/export_exclude_owner_test.go (be-9d2b67):
- TestExportExcludeOwner_flag: --exclude-owner=alice filters alice's issues
- TestExportExcludeOwner_config: export.exclude_owners config drives filter
- TestExportExcludeOwner_verbose: --verbose reports filtered count
cmd/bd/migrate_personal_test.go (be-3c5a0f):
- TestMigratePersonal_noopWhenEmpty: no matching issues → 0/success
- TestMigratePersonal_movesIssues: personal issues moved to planning repo
- TestMigratePersonal_abortOnNoConfirm: EOF stdin → abort, issues stay
All gate on BEADS_TEST_EMBEDDED_DOLT=1. Fork-detection init tests
covered by be-de99a6 (tests/be-de99a6-fork-detect) per PM scope.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(test): be-36oa — skip TestMigratePersonal_movesIssues on Dolt unavailable
Broaden the skip condition in TestMigratePersonal_movesIssues to also skip
when the planning dir's Dolt server is unavailable (BEADS_DOLT_AUTO_START=0
leaves port=0, causing dolt.New() to fail). Adds "dolt", "cannot connect",
and "server" to the skip-trigger strings alongside the existing routing
and actor-mismatch conditions.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* test(init): be-de99a6 — fork-detection UX output format tests
4 embedded tests for autoConfigureForkContributor output per be-de99a6:
- TestBdInit_ForkAutoContributor: upstream remote → 'Fork detected' in output,
routing.mode=auto set
- TestBdInit_ForkAutoContributor_Idempotent: second init run → routing.mode
still 'auto' (no double-write)
- TestBdInit_ForkAutoContributor_MaintainerFlag: --role=maintainer → routing.mode
NOT set to auto
- TestBdInit_ForkAutoContributor_NonInteractive: --quiet → no '▶' block, but
routing still configured
All gate on BEADS_TEST_EMBEDDED_DOLT=1. Uses initForkRepo helper to
add upstream remote for fork detection.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(bd-umbf): be-jewoem B3 — fix yaml/DB store mismatch in export owner-filter and fork routing
Two real bugs found while landing the B3 validator tests:
1. buildOwnerExcludeSet (export.go) was only reading export.exclude_owners
from the database. The export.* prefix is yaml-only (config.yaml), so
config set via 'bd config set export.exclude_owners' was invisible to the
filter. Now reads yaml first, falls back to database.
2. autoConfigureForkContributor (init_contributor.go) was writing
routing.mode, routing.contributor, and sync.remote via store.SetConfig
(database). Those keys carry the routing.*/sync.* prefixes which are
yaml-only. Reading back via 'bd config get routing.mode' always returned
empty. Now uses config.SetYamlConfig for these keys; idempotency check
updated to read from yaml too.
Also: update TestBdInit_ForkAutoContributor to verify routing config state
rather than output text (suppressed in non-TTY test environments); remove
temporary debug_fork_test.go; mark B3 RESOLVED in release gate.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(lint): drop unused ctx+store params from autoConfigureForkContributor
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* chore: release gate PASS for bd-3852 (orphaned children doctor check)
* fix(rebase): update second autoConfigureForkContributor call to 2-arg signature
Later commits in this branch dropped ctx and store params from
autoConfigureForkContributor. The second call site added by be787e4b5
still used the old 4-arg form; update to match the final 2-arg form.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(rebase): drop #4028-superseded fork-detect; take main init.go/init_contributor.go (be-15y28)
PR #4028 landed autoConfigureForkContributor on main. PR #4023 had its own
version of init.go and init_contributor.go plus a fork_detect_embedded_test.go
that collided with TestEmbeddedInit/fork_auto_contributor, causing CI to fail.
Take origin/main's init.go and init_contributor.go verbatim; remove
fork_detect_embedded_test.go. The unique features — reference-aware prune,
export --exclude-owner, bd migrate-personal — are untouched.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(prune): scan active custom statuses in reference-aware skip
buildReferencedSet scanned only the built-in non-closed statuses, so a closed bead cited by a bead in an active *custom* status (status.custom) was unprotected and could be deleted by 'bd prune --pattern ... --force'. Now include every configured custom status whose category != done (via GetCustomStatusesDetailed); the read is required, not best-effort, so a destructive prune never silently under-scans. Adds TestPrune_protectsBeadCitedByCustomStatusBead. Addresses maphew's review of PR #4023 (be-e2nb).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(export): apply export.exclude_owners to auto-export
The export.exclude_owners safety net was applied only by manual 'bd export'; the git-committed auto-export (.beads/issues.jsonl) did not filter, so contributor/personal issues could still leak into git history and PRs. exportToFile now applies the same owner filter (config-sourced owners). Adds TestAutoExportExcludeOwner_config. Addresses maphew's review of PR #4023 (be-e2nb).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(migrate-personal): all-or-error copy preserving comments before delete
migrate-personal copied labels/deps/comments best-effort (warnings) and used event-style AddComment, then deleted the source -- so a partial copy could silently drop comments and dependencies while reporting success. Make the copy all-or-error in two passes (create all issue rows, then copy relations so same-prefix intra-set deps resolve), roll back the planning-DB rows and abort before touching the project DB on any failure, and copy comments via ImportIssueComment (structured row + original timestamp). Adds TestCopyIssueRelations_preservesCommentWithTimestamp and TestMigratePersonal_preservesComments. Addresses maphew's review of PR #4023 (be-e2nb).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(ci): register TestPruneLargeFixture in check-testing-short allowlist
Large-fixture bench introduced in this PR was blocked by pr-policy.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(docs): restore version-1.0.5 migrate-personal CLI reference
The 2026-06-03 main merge (72a2a2521) pulled in main's wholesale website
doc regeneration, which dropped
website/versioned_docs/version-1.0.5/cli-reference/migrate-personal.md
(migrate-personal is new in this PR and absent on main). check-doc-flags'
generate-cli-docs.sh --check then failed: the live bd emits the command but
the 1.0.5 snapshot lacked the page, turning Build Artifacts, PR Policy,
Check doc flags freshness, and the CI Gate rollup red.
Regenerated with scripts/generate-cli-docs.sh ./bd — only this file
changed (index.md and llms-full.txt already reference the command).
Verified the full pr-policy sequence passes locally: build-tags,
go-install-guidance, versions, doc-flags (incl. llms-full), doc-freshness,
testing-short, and the jsonl guard.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(gate): finalize be-jewoem gate — re-review PASS, CI green 2026-06-04
Re-review PASS confirmed (gm-wisp-765hi, 2026-05-22, commit 9cfe6206f).
Post-review CI/docs commits (merge, CI allowlist, version-1.0.5 docs)
are non-behavioral. CI run 26924427657: 51/51 checks SUCCESS.
PR #4023 mergeStateStatus: CLEAN. Gate: definitive PASS.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(docs): true up CLI reference after upstream rebase
Mechanical doc-conflict resolution during the rebase onto upstream/main
(
|
||
|---|---|---|
| .. | ||
| bench-ready-indexes | ||
| ci | ||
| hooks | ||
| migration-test | ||
| repro-dolt-hang | ||
| repro-dolt-prod-timeouts | ||
| bump-version.sh | ||
| check-build-tags.sh | ||
| check-cli-docs-drift.sh | ||
| check-doc-flags.sh | ||
| check-doc-freshness.sh | ||
| check-docs-version.sh | ||
| check-go-install-guidance.sh | ||
| check-migration-hygiene.sh | ||
| check-testing-short.sh | ||
| check-versions.sh | ||
| clean-test-tmp.sh | ||
| cross-version-smoke-test.sh | ||
| docs.md | ||
| gen-winres.sh | ||
| generate-cli-docs.sh | ||
| generate-llms-full.sh | ||
| generate-newsletter.py | ||
| generate-newsletter_README.md | ||
| gh-body-lint | ||
| install-hooks.sh | ||
| install.sh | ||
| migrate-jsonl-to-dolt.sh | ||
| migrate-sqlite-to-current.sh | ||
| pr-preflight.sh | ||
| README.md | ||
| release.sh | ||
| release_script_test.go | ||
| sign-windows.sh | ||
| snapshot-release-docs.sh | ||
| sync-website-docs.sh | ||
| test-cgo.sh | ||
| test-git-remote.sh | ||
| test-icu-path.sh | ||
| test.sh | ||
| update-nix-vendorhash.sh | ||
| update-versions.sh | ||
| update-winget.sh | ||
| upgrade-smoke-test.sh | ||
| verify-cgo.sh | ||
Beads Scripts
Utility scripts for maintaining the beads project.
ci/
Repository-owned CI command wrappers. These scripts are the source of truth for the target CI tiers; Make targets are aliases for local discoverability.
make ci-pr-core
make ci-pr-policy
make ci-pr-lint
make ci-package-mcp
make ci-package-npm
make ci-website
Each wrapper auto-detects the repository root, sources .buildflags when it
invokes Go in the default build mode, and records per-command timing through
scripts/ci/lib/timing.sh.
Broad Go test wrappers also source scripts/ci/lib/test-env.sh, which creates a
temporary HOME/XDG/Dolt root, isolates Git global/system config, clears runtime
Beads/Dolt environment variables, and sets BEADS_TEST_SKIP=dolt before tests
run. This keeps local make test and make ci-pr-core results comparable to
the fast PR-core contract even on shared agent hosts. Set
BEADS_TEST_ENV_RUN_DOLT=1 only when intentionally running the Dolt-dependent
tests through these broad wrappers, or BEADS_TEST_ENV_DISABLE=1 when debugging
against your real local configuration.
The broad Go wrappers also cap package and test parallelism to 4 by default
(GO_TEST_PKG_PARALLEL and GO_TEST_PARALLEL). This avoids turning high-core
shared hosts into a different test topology than GitHub Actions.
make ci-pr-policy includes scripts/check-testing-short.sh, which enforces
that testing.Short() is only used for runtime, stress, or large-fixture skips.
Use build tags, environment checks, or named wrappers for integration/e2e/API
boundaries.
Package gate wrappers validate publishable/package-adjacent surfaces:
make ci-package-mcpbuilds or consumes abdbinary, puts it onPATHasbd, then runs locked MCP packageuv sync, Ruff, mypy, pytest, and build checks.make ci-package-npmbuilds or consumes the native binary expected bynpm-package/bin/bd, runs the npm package test suite, and checksnpm pack --dry-run.make ci-websiteruns website dependency install, typecheck,llms-full.txtgeneration, and Docusaurus build.
Set BEADS_TEST_BD_BINARY=/path/to/bd for MCP and npm package gates to reuse a
prebuilt candidate binary instead of rebuilding it inside the wrapper.
pr-preflight.sh
Read-only PR safety check for agents and maintainers.
# Before implementing or opening a related PR
./scripts/pr-preflight.sh --search "topic keywords" --repo gastownhall/beads
# Before changing, closing, or merging an existing PR
./scripts/pr-preflight.sh 123 --repo gastownhall/beads
It reports contributor/fork status, draft/review/merge/check state, risky diff
signals such as .beads/ changes or missing tests, and the required
contributor-protection next steps. It does not replace code review or local
validation.
gh-body-lint
Lint Markdown files before posting them with gh ... --body-file.
./scripts/gh-body-lint body.md
./scripts/gh-body-lint --fix body.md
The lint catches literal \n sequences, which render poorly on GitHub, and
GH#123 references, which do not auto-link like #123 or owner/repo#123.
release.sh (⭐ The Easy Button)
One-command release from version bump to local installation.
Usage
# Full release (does everything)
./scripts/release.sh 0.9.3
# Preview what would happen
./scripts/release.sh 0.9.3 --dry-run
What It Does
This master script automates the entire release process:
- ✅ Stops running Dolt servers (avoids version conflicts)
- ✅ Runs tests and linting
- ✅ Bumps version in all files
- ✅ Commits and pushes version bump
- ✅ Creates and pushes git tag
- ✅ Verifies or opens the Homebrew core formula PR
- ✅ Upgrades local Homebrew installation
- ✅ Verifies everything works
After this script completes, your system is running the new version!
Examples
# Release version 0.9.3
./scripts/release.sh 0.9.3
# Preview a release (no changes made)
./scripts/release.sh 1.0.0 --dry-run
Prerequisites
- Clean git working directory
- All changes committed
- golangci-lint installed
- Homebrew installed (for local upgrade)
- Push access to gastownhall/beads
Output
The script provides colorful, step-by-step progress output:
- 🟨 Yellow: Current step
- 🟩 Green: Step completed
- 🟥 Red: Errors
- 🟦 Blue: Section headers
What Happens Next
After the script finishes:
- GitHub Actions builds binaries for all platforms (~5 minutes)
- PyPI package is published automatically
- Homebrew core formula is verified or tracked through its canonical PR
- Users can
brew upgrade beadsto get the new version after Homebrew merges - GitHub Release is created with binaries and changelog
bump-version.sh
Bumps the version number across all beads components in a single command.
Usage
# Show usage
./scripts/bump-version.sh
# Update versions (shows diff, no commit)
./scripts/bump-version.sh 0.9.3
# Update versions and auto-commit
./scripts/bump-version.sh 0.9.3 --commit
What It Does
Updates version in all these files:
cmd/bd/version.go- bd CLI version constantplugins/beads/.claude-plugin/plugin.json- Claude plugin versionplugins/beads/.codex-plugin/plugin.json- Codex plugin version.claude-plugin/marketplace.json- Claude marketplace plugin versionintegrations/beads-mcp/pyproject.toml- MCP server versionREADME.md- Alpha status versionPLUGIN.md- Version requirements
Features
- Validates semantic versioning format (MAJOR.MINOR.PATCH)
- Verifies all versions match after update
- Shows git diff of changes
- Auto-commits with standardized message (optional)
- Cross-platform compatible (macOS and Linux)
Examples
# Bump to 0.9.3 and review changes
./scripts/bump-version.sh 0.9.3
# Review the diff, then manually commit
# Bump to 1.0.0 and auto-commit
./scripts/bump-version.sh 1.0.0 --commit
git push origin main
Why This Script Exists
Previously, version bumps only updated cmd/bd/version.go, leaving other components out of sync. This script ensures all version numbers stay consistent across the project.
Safety
- Checks for uncommitted changes before proceeding
- Refuses to auto-commit if there are existing uncommitted changes
- Validates version format before making any changes
- Verifies all versions match after update
- Shows diff for review before commit
sign-windows.sh
Signs Windows executables with an Authenticode certificate using osslsigncode.
Usage
# Sign a Windows executable
./scripts/sign-windows.sh path/to/bd.exe
# Environment variables required for signing:
export WINDOWS_SIGNING_CERT_PFX_BASE64="<base64-encoded-pfx>"
export WINDOWS_SIGNING_CERT_PASSWORD="<certificate-password>"
What It Does
This script is called automatically by GoReleaser during the release process:
- Decodes the PFX certificate from base64
- Signs the Windows executable using osslsigncode
- Timestamps the signature using DigiCert's RFC3161 server
- Replaces the original binary with the signed version
- Verifies the signature was applied correctly
Prerequisites
osslsigncodeinstalled (apt install osslsigncodeorbrew install osslsigncode)- EV code signing certificate exported as PFX file
- GitHub secrets configured:
WINDOWS_SIGNING_CERT_PFX_BASE64- base64-encoded PFX fileWINDOWS_SIGNING_CERT_PASSWORD- certificate password
Graceful Degradation
If the signing secrets are not configured:
- The script prints a warning and exits successfully
- GoReleaser continues without signing
- The release proceeds with unsigned Windows binaries
This allows releases to work before a certificate is acquired.
Why This Script Exists
Windows code signing helps reduce antivirus false positives that affect Go binaries.
Kaspersky and other AV software commonly flag unsigned Go executables as potentially
malicious due to heuristic detection. See docs/ANTIVIRUS.md for details.
Future Scripts
Additional maintenance scripts may be added here as needed.