* fix(reset): a comment is content when the question is deletion
GH#5221 stopped `bd admin reset` from deleting hooks it never installed, but
left one path open. classifyResetHook decides a sectioned hook by stripping
bd's block and asking isOnlyShebangOrEmpty whether anything remains — and that
predicate, by its own documented design, treats every comment as nothing.
So a hook of the user's whose own content is a shebang plus comments — a header
they wrote, a note to whoever edits it next, a lint step they commented out for
now — strips to "empty", classifies hookBdOwned, and is deleted whole. There is
nothing to restore it from: performReset renames <hook>.backup back into place,
and a backup exists only for hooks bd itself displaced, which is never the case
for a hook bd only injected a section into. A comment was once again enough to
make a hook bd's to delete, which is the failure GH#5221 exists to close.
The looser predicate is right where it lives. shouldPreserveHookContent is
deciding whether to COPY a hook forward into .beads/hooks, and declining to
carry a comment-only file loses a comment out of a file that still exists on
disk (GH#3536). Reset is deciding whether to DESTROY the file. The two
questions differ in what being wrong costs, so they no longer share an answer:
isOnlyShebangOrBlank counts only the leading shebang and blank lines as
nothing. It anchors the shebang on the first non-blank line rather than on
index 0, so it does not depend on whether stripping bd's section left a blank
line above it, and a second `#!` further down is read as the comment it is.
The divergence is deliberate and one-way, so both tests that could hide it now
say so. TestClassifyResetHook_AgreesWithHookPreservation keeps the arm that
matters — what preservation calls the user's, reset must not delete — and
replaces its converse with the weaker claim that still needs pinning: reset may
never call a marker-carrying file none of bd's business, or a hook bd wrote
survives a reset unremoved and unreported. TestResetEmptinessPredicateIsStricter
ThanPreservation pins the gap between the two predicates directly, so a later
cleanup that notices they answer "the same" question and collapses them into
one fails here instead of quietly restoring the deletion.
Verified the fix is load-bearing: pointed classifyResetHook back at the old
predicate and the three new cases fail (both classify cases, and the
collectResetItems case in both directions — removed when it should be kept,
absent from the preserved report when it should be named).
Agent-Signature: claude-opus-5-high on behalf of maphew
* docs(uninstall): stop handing out an rm -f batch under a "check first" warning
GH#5221 added a warning above the manual-cleanup hook deletions telling the
reader that these are the standard git hook names, that any of them may be a
hook they wrote, and to check each file before deleting it. It then left the
five unconditional `rm -f .git/hooks/<name>` lines directly beneath it, inside
the same copy-pasteable fence.
A warning that is followed, in the same block, by the commands that do the
thing it warns about is not a safeguard. Anyone treating the fence the way
fences in this document are meant to be treated deletes all five hooks and
reads the reason afterwards. Someone in this section has already lost the
command that could tell the difference for them.
So the hook step is no longer a batch. A read-only grep lists which of the five
exist and which carry a beads marker, and the disposition is then per file:
delete the ones beads generated whole, edit the block out of the ones that are
yours, leave the rest. `rm -f .git/hooks/<name>` appears once, with a
placeholder, in a sentence about a file the reader has just opened.
The per-file rules are the ones the code applies, including the case the
accompanying commit fixes: a hook that is your header comment plus beads'
block is yours to edit, not beads' to delete.
`bd dolt stop` and the `.beads` / worktree removals stay executable; those are
beads' own state, not files that might be the user's.
Agent-Signature: claude-opus-5-high on behalf of maphew
* fix(reset): decide hook deletion from provenance, not the word "beads"
`bd admin reset --force` deletes git hooks it believes bd installed. isBdHook
decided that by scanning the first ten lines for the substring "beads" —
anywhere, in any context. A comment, a path, a call to another tool: any of them
made a hook bd's to delete.
The repository's own tracked .githooks/pre-commit is such a file. It is composed
by hand, carries guards bd knows nothing about, and says "the beads section at
the bottom must run for non-Go commits too" on line 9. The old scan matched that
comment and would have removed the whole file. Nothing brings it back:
performReset's restore path renames <hook>.backup into place, and a backup
exists only for hooks bd itself displaced, so a hook bd never installed is
deleted with no restore.
The same scan was wrong in the other direction too — a marker past the tenth
line was invisible — but that failure is merely untidy, and this one loses work.
Provenance is not something reset has to guess at. bd writes markers when it
installs (hookVersionPrefix, shimVersionPrefix, inlineHookMarker) and wraps
injected blocks in section markers, and preservePreexistingHooks already has a
worked-out model of what those mean (GH#3536). classifyResetHook uses the same
markers and the same rules, and returns three states rather than a boolean,
because "bd installed this" and "bd may delete this" are different questions:
hookBdOwned bd wrote the whole file; removing it restores the
state before bd touched the repo.
hookUserOwnedWithBdSection the user's hook with bd's block injected. The file
is theirs. Reset reports it and leaves it.
hookNotOurs no marker. Not ours to remove or to mention.
The middle state is the one the old boolean could not express, and it is not
rare: it is what every marker-managed install since v0.49 produces. Under the
old code such a hook was deleted whole whenever "beads" fell inside the first
ten lines — which the generated section itself guarantees when it lands near the
top, since its second line reads "# This section is managed by beads."
Preserved hooks are reported in both the preview and the --force path, and in
--json as a "preserved" key. Saying nothing would leave the user believing a
reset removed a beads integration that is in fact still live in their hook.
Tests cover each state, both directions of the old first-ten-lines window, and
the missing-file case. TestClassifyResetHook_AgreesWithHookPreservation pins the
invariant across the two functions that decide this independently: if
shouldPreserveHookContent would carry content forward, reset must not delete the
file, and vice versa. It runs over the repo's own .githooks so the inputs are
hooks a person actually wrote, and asserts the agreement rather than a verdict
per file, so editing those hooks cannot make it lie.
Agent-Signature: claude-opus-5-high on behalf of matt wilkie
* docs(uninstall): stop telling users reset removes hook sections
Two claims in docs/recovery/uninstalling.md do not match what the code does,
and both point the same way — at deleting a hook file that is the user's.
The reset section said `bd admin reset` removes "beads-managed git hook
sections". It has never worked on sections; it removes whole files. With the
ownership check in this branch it removes only files beads generated in full,
and reports the ones it left alone, so say that instead.
The manual-cleanup section is worse: it hands the user five unconditional
`rm -f .git/hooks/<name>` lines. Those are the standard git hook names, not
names beads reserves, so any of them may be a hook they wrote — and the section
directly above it explains that `bd hooks uninstall` is preferable precisely
because beads preserves content outside its markers. Someone who reaches
manual cleanup is already in the case where the safe command did not work.
Name the markers so the check is something a reader can actually perform, and
say what to do with a hook that only has a beads block in it.
Agent-Signature: claude-opus-5-high on behalf of matt wilkie
The reporter uninstalled beads by hand (`rm -rf .beads/`) and was left with
git config still pointing core.hooksPath at the directory they had just
deleted, plus a stale beads.role. Nothing told them so: none of the three
registered hooks checks tests whether the configured hooks path still exists,
and `.beads/` reappearing on checkout made it look like beads was
reinstalling itself. It is not — post-checkout runs the JSONL import, which
initialises an embedded-dolt workspace under the old prefix as a side effect
(GH#4440).
Of the reporter's three suggested fixes, one was already implemented and did
not help them, because it only runs when you use the command they did not
use. The other two are here.
- New "Hooks Path" doctor check: warns when core.hooksPath resolves to a
directory that does not exist, naming both the configured value and the
resolved path. `bd doctor --fix` unsets it — but only when it is one of the
values bd itself writes. A third-party hooks path (husky and friends) is
reported and left alone; FixHooksPath re-reads and re-checks both
conditions immediately before acting, so a stale check result cannot cause
it to touch someone else's config.
- `bd hooks uninstall` now also unsets beads.role, and a config reset that
fails is returned as an error instead of a scrolling stderr warning. It no
longer reports success while beads-managed config is still set. beads.role
is read before it is unset rather than treating git's exit 5 as "already
absent": exit 5 also means "refusing an ambiguous unset" on a duplicated
key, and conflating the two would report a clean uninstall with the key
still there.
- docs/recovery/uninstalling.md's Manual Cleanup gains core.hooksPath, with
the reason, and the caveat that it is not a beads-only key.
KNOWN GAP, stated plainly: bare `bd doctor` is gated off in embedded mode by
deliberate policy (GH#3794, doctor.go), and embedded is the default and the
reporter's mode — so the new check does not yet reach the users most likely
to hit this. Lifting that gate is a human-vetted decision per the policy
comment and is deliberately not made here. The uninstall and documentation
changes are mode-independent and do help them.
Agent-Signature: claude-opus-5-high on behalf of matt wilkie
* docs: caveat --parent label inheritance with size/effort labels (#4562)
Children inherit parent labels by default. Examples that use --parent with
size/effort labels on epics silently double-label every child, which breaks
effort queries. Document --no-inherit-labels in labels.md and parent-create
examples (skill, quickstart, molecules, multi-agent coordination).
* docs(labels): consolidate example commands and fix issue-ref style
Maintainer commit per vishnujayvel's request on PR #5123: fold the
two-step "create then label" example under Size/Effort Estimates into
one bd create -l invocation, and normalize the bare #2100 reference
to the GH#NNNN style used elsewhere in the docs.
Agent-Signature: claude-code-sonnet-medium on behalf of matt wilkie
* docs: revert no-op --no-inherit-labels edits, cross-link instead (GH#4562)
--no-inherit-labels was a no-op in the quickstart/molecules/coordination
examples (none created labels), inverting the deliberate #2100 default
for readers who don't have the problem yet. Revert those three plus the
same no-op edit in the plugin's INTEGRATION_PATTERNS.md to match main,
and add a one-line cross-link to the labels.md caveat/worked example
instead, per maphew's review on #5123.
---------
Co-authored-by: matt wilkie <maphew@gmail.com>
Three operational lessons from the July squash windows, in generic terms:
- Git-backed remotes never shrink on force-push: the remote manifest keeps
every historical table file listed as current, so the store must be
replaced in place — delete refs/dolt/data and the __dolt_remote_info__
branch on the git remote, then force-push a fresh store (verified on two
production remotes: 587M->57.8M and 274M->2.6M reachable).
- Sync jobs and writers are separate switches: a peer's sync job stays off
until that machine has verifiably re-cloned; unfencing writers must not
implicitly re-arm peer sync (the re-pollution hole hit twice).
- First push from a re-cloned machine is far larger than a routine tick;
timeout-capped sync jobs orphan partial uploads — one manual uncapped
push before handing back to the schedule.
Gates: go test ./test/docsync PASS, check-doc-freshness.sh PASS.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Add Kiro setup recipe
* docs: register integrations/kiro in docs.json navigation
The docsync guard (TestEveryDocsPageIsPublished) requires every docs/ page
in the Mintlify nav; it landed after this PR was written.
Agent-Signature: claude-fable-5-high on behalf of maphew
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01P3JtQ3ukoVmfg6LCKcKBBh
---------
Co-authored-by: matt wilkie <maphew@gmail.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Commit ab3feda00 removed the len(prefix) > 8 check from validatePrefix,
but "Max length: 8 characters" survived in the command's Long help text,
the plugin skill page, and docs/reference/advanced.md. Remove from all
three sources; generated CLI docs are release-pinned and untouched.
* fix(build) fixing build when using MSVC (#4324)
* fix(build) fixing build when using Windows (#4324)
---------
Co-authored-by: Johann Dirry <johann.dirry@microsea.at>
Co-authored-by: matt wilkie <maphew@gmail.com>
* fix(show): flag comment_count as omitted when comments are not streamed
bd show --json's count-only default (be-ijck6q, pinned by
TestJSONContract_ShowOmitsOptInPayloadsByDefault) returns comment_count
with no comments key unless --include-comments is passed. A caller that
checks only `.comments` reads absence as "no comments" — wrong whenever
comment_count > 0. A caller that reads comment_count has no signal that
the array was left out on purpose rather than omitted by a client bug.
Add comments_omitted (bool, omitempty) to IssueDetails, set true only
when CommentCount > 0 and Comments was not populated. Leaves the
count-only default and its perf rationale untouched — this does not
revert cfcc95799/e538f2881, it makes the partial representation
self-announcing. Symmetric dependent_count/dependents case is a known,
separate gap left for a follow-up (not reported by ga-clgh, out of
scope here).
Did not bump JSONSchemaVersion / regen the golden corpus: this adds an
optional field via omitempty (no existing consumer's parse breaks,
no existing corpus fixture has comment_count > 0 for `show`), and
corpus-regen needs a live Dolt+Docker this sandbox doesn't have to
verify. Deferring that call to whoever can run `make corpus-regen` and
review the diff.
Fixes ga-clgh.
* fix(show): set comments_omitted on the proxied path too
The direct path flags comment_count as omitted when comments are not
streamed (ga-clgh); the proxied path silently left the flag unset. Mirror
the else-branch in proxiedBuildDetails, add proxied-path coverage for
present/included/zero cases, and document comments_omitted in the JSON
schema reference. No schema version bump: additive optional field already
emitted by the direct path.
Addresses the 2026-07-23 review on gastownhall/beads#4865.
Agent-Signature: claude-sonnet-5-medium on behalf of maphew
---------
Co-authored-by: matt wilkie <maphew@gmail.com>
Second adversarial review of the replica-aware lease work, against the opt-in
rewrite. One blocker, in the operating instruction rather than the code.
node_id was documented as "BEADS_NODE_ID, or node_id in config.yaml", and
`bd config set node_id` wrote the PROJECT .beads/config.yaml — a git-TRACKED
file (nothing in .beads/.gitignore excludes it). Commit "node_id: mini" and
every clone that pulls reads "mini", so every granted_node comparison matches
and the guard is at once fully ARMED and fully INERT: laptop reaps mini's
leases exactly as if they were local. That is the precise hazard the feature
exists to close, now happening while the operator believes they are protected
— strictly worse than the pre-feature state, where nobody thought they were.
node_id is per-machine state, the class .beads/.gitignore already excludes as
sync-state.json / push-state.json / redirect. It now routes to the user-global
~/.config/bd/config.yaml through a new exact-key arm of IsUserGlobalKey (the
prefix list only ever held "metrics."); viper already merges that file, so
config.NodeID() reads it straight back.
The docs also said to set it "on every replica sharing the queue", which on a
shared or remote dolt sql-server means every HOST — rebuilding the same
fail-closed regression this commit's parent removed the hostname fallback to
avoid. The load-bearing rule was never stated: node_id names the STORE, not
the host. Clients of one sql-server are ONE replica and must share a value or
leave it unset. Now said outright in federation.md and `bd reclaim --help`.
Also from the review:
- bd show claimed "reclaim will decline it" for any foreign node, but with an
unnamed local node the guard is disarmed and reclaim reverts the lease
happily. The annotation is now gated on config.NodeID() != "".
- TestNodeIDContextOverride's empty-override assertion had gone tautological
when the hostname fallback went away: config.NodeID() is "" under test, so
it passed whether or not WithNodeID worked at all. It now sets a non-empty
fallback, asserts the fallback is what a no-override read returns, and only
then asserts the empty override still beats it.
- The heartbeat backfill's bare `granted_node = ''` is COALESCE'd, matching
the reclaim predicates; under NULL the IF took the else branch and the row
was never backfilled. Unreachable today (0016 is NOT NULL DEFAULT ''), but
the two sites disagreed about whether NULL was possible.
- The --any-replica audit line is skipped when localNode is "" rather than
printing `not this node ("")`: nothing was overridden, the guard was never
armed.
- reclaimReplicaSQL documents WHY granted_node stays unqualified — the DELETE
splices it into a bare `DELETE FROM leases` with no alias to qualify with —
and what to do if issues ever grows a column of that name.
- CHANGELOG entry, which this feature owed: a new flag, a new config key, two
env vars, and two public struct fields shipped without one.
Adversarial review of the landed replica-aware lease work (966ddac5a) found
that deriving the granting replica from os.Hostname() answers the wrong
question: the hostname names the CLIENT PROCESS's machine, not the store.
That is a fail-CLOSED regression in three topologies with no federation to
defend against. With a shared or remote dolt sql-server (BEADS_DOLT_SERVER_HOST,
ServerModeExternal, Hosted Dolt, a VPS) many hosts are clients of ONE store, so
a supervisor would match no worker's lease and reclaim 0 forever. In a container
the hostname is a per-run container ID, so a replaced worker's successor sees
its own single-machine leases as foreign. On macOS/DHCP the transient hostname
follows the network. Stranding a lease on a single-store deployment is a worse
failure than the cross-replica reclaim the guard exists to prevent.
So the guard is now OPT-IN: config.NodeID() reads BEADS_NODE_ID / BD_NODE_ID /
node_id in config.yaml and nowhere else, and "" (the default) disarms the guard
back to exactly the pre-feature behavior. This also settles the heartbeat
backfill hazard — on an unnamed deployment the backfill writes '' over '' and
cannot silently convert a fail-open row into a fail-closed one.
Also from the review:
- node_id joins recognizedConfigKeys and YamlOnlyKeys, so the documented
`node_id: mini` mitigation no longer warns and no longer writes to the Dolt
config table that NodeID() never reads (the GH#536 class YamlOnlyKeys exists
to prevent).
- reclaimReplicaSQL/warnReplica/reportForeignSkips move above the
ReclaimExpiredLeasesInTx doc block, which they had orphaned onto a private
helper.
- The --any-replica audit line moves past both re-checks, so it can no longer
log a revert that a post-snapshot heartbeat prevented.
- lease_granted_node joins ephemeralExportKeys in the conformance round trip.
- New cmd/bd/protocol coverage for the JSONL path (RestoreLeaseOnImportInTx),
the sole reason the field is on the wire: a lease claimed under
BEADS_NODE_ID=mini keeps mini after import on laptop, laptop's reaper
declines it, and --any-replica reverts that same row.
- The embeddeddolt test stops claiming its surviving-lease assertion exercises
the DELETE-side guard; inside one transaction that copy is defense in depth.
- A stray U+201D and an inconsistent COALESCE in reportForeignSkips.
A claim lease is only meaningful on the replica that granted it. Every other
replica's view of the holder's liveness is stale by up to one sync interval,
so a reaper over there can revert a unit that is very much alive here. Until
now the only defense was operator discipline: partition every supervisor's
reclaim by label and hope nobody runs an unscoped sweep.
Leases now record WHICH replica granted them (leases.granted_node, ignored
migration 0016, stamped from config.NodeID(): BEADS_NODE_ID / node_id config,
falling back to the hostname). bd reclaim skips a lease that positively names
another replica — on both the snapshot SELECT and the per-row DELETE
re-check — and names each skip on stderr, since silence there is
indistinguishable from "nothing to recover" while a genuinely dead remote
worker's unit sits in_progress forever. bd reclaim --any-replica is the
operator escape hatch for a replica that is gone for good.
The guard is deliberately fail-open on unknown provenance: granted_node ''
(a row predating the column, or a deployment whose NodeID is empty) is
treated as local, so the upgrade itself can never strand a stale lease the
reaper could previously recover. A heartbeat backfills an unknown row with
the local node and never overwrites a known one.
The one path that can materialize a FOREIGN lease row locally is
RestoreLeaseOnImportInTx — lease fields round-trip the JSONL interchange — so
the granting replica rides types.Issue.LeaseGrantedNode and a restored lease
keeps the replica the snapshot names, never this node. A snapshot from an
older binary carries none, restores as unknown, and behaves exactly as before.
What the guard cannot enforce is documented instead, in both bd reclaim --help
and docs/multi-agent/federation.md: grace window > sync interval, and lease
TTL > sync interval. A TTL shorter than the cadence at which replicas exchange
state is meaningless across the bridge — the remote view is a full interval
old by construction.
doc/beads-upstream-asks.md section 5.
Field incident from the first production run of this runbook (wy-7lmdp,
2026-07-18): all local writers were fenced, but a peer machine's scheduled
bridge-sync job was never stopped. One tick after the clean force-push it
pulled the new baseline, cross-merged it into its old chain, and pushed the
entire old history back to the freshly replaced remote.
Step 1 now tells the operator that writers include scheduled sync jobs on
every machine that syncs the database, to enumerate and verify them by
name, and why one live peer undoes the procedure. Step 5 orders re-enabling
per machine after its re-clone; the top warning says 'on every machine'.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The runbook (#4864) and the release-pinned CLI reference (#4876) crossed
mid-flight: the prevention section links /cli-reference/heartbeat, a page
the pin removed because bd heartbeat is not in v1.1.0. The dangling link
fails the docsync guard on main and on every branch cut from it. Keep the
prose, drop the link.
The v1.1.0 release notes tell the designated migrator to run
BD_ALLOW_REMOTE_MIGRATE=1 bd migrate, but the docs never named the
variable after the escape-hatch scrub. One mention belongs in the upgrade
guide, where a blocked or CI-scripting reader actually looks; the wording
is derived from the v1.1.0 source (remote_migrate_gate.go): boolean values
accepted, consulted only when the gate would fire, and it bypasses the
gate entirely — including the already-forked lanes — so the sentence says
to wire it into exactly one clone's upgrade job.
Old clones share the root by construction (Step 2 keeps it as sole
ancestor), so a pull is not refused — it cross-merges and, if pushed,
resurrects the bloat on the squashed remote. Wording per lion's re-review.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
A Dolt remote accumulates chunks monotonically, so Step 4's force-push
re-points refs without freeing the old chain's storage. Warn and give the
replace-the-remote recipe; clones must re-clone after a squash anyway.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The per-section forwarding map mirrored the live playbook's structure — a
copy that would drift as docs/recovery/ evolves. A stub carries nothing to
maintain: one pointer to the live playbooks plus the reason the file
exists. Deep anchors from the wild land at the top of the page, where the
pointer is the first thing a reader sees.
Released v1.1.0 binaries print
github.com/gastownhall/beads/blob/main/docs/RECOVERY.md#pk-fork-refused in
the Dolt merge-refusal guidance (printAncestorPKMismatchGuidance,
cmd/bd/dolt.go at the tag), and github.com blob paths cannot be redirected —
the URL has 404ed since the docs restructure, at exactly the moment a user
is mid-incident. main's binary already prints the new path; this stub
un-rots the link for binaries already in the wild.
The stub reproduces the old file's section headings verbatim so GitHub
mints the same anchor slugs, and each section forwards to its successor in
docs/recovery/init-safety.md (all four sections map there 1:1). It is
registered in test/docsync's docsPublishExemptions as a deliberate,
documented exception to the no-pointer-stubs rule (decision 6), scoped to
last only while supported releases print the path.
* docs(pipeline): pin the generated CLI docs to the released bd; repair main's CLI reference
The #4874 squash-merge raced the docs-autofix bot: the bot had pushed a
regeneration from main's source onto the PR branch, so the squash landed a
contradictory mix — the release-aligned hand-written docs plus a CLI
reference re-documenting unreleased commands and flags, with docs.json
referencing four pages (heartbeat, migrate-personal, reclaim, unclaim)
whose files do not exist. That broken nav fails the docsync guard on main
and on every branch cut from it. This restores the intended end state of
#4874 and lands the pin that prevents the race from recurring.
- Regenerate the CLI reference from a bd built from the v1.1.0 tag (CI's
canonical pure-Go build), removing the unreleased commands/flags and
fixing the dangling nav entries.
- docs/cli-docs.pin names the release tag; scripts/resolve-docs-bd.sh
builds and caches a canonical pure-Go bd from that tag, fetching the tag
first in shallow CI checkouts.
- generate-cli-docs.sh, check-doc-flags.sh, and check-cli-docs-drift.sh
resolve bd through the pin and ignore a supplied binary while pinned
(BD_DOCS_IGNORE_PIN=1 bypasses), so the drift gates and the autofix bot
now enforce docs-match-release instead of docs-match-main.
- tools/docsmint detects the pre-overhaul Docusaurus staging layout that
bd <= v1.1.0 emits and converts it to the generic form before its normal
Mintlify transform (tested); removable once the pin reaches a release
whose emitter writes build/cli-docs.
- check-doc-flags.sh: run without timeout(1) on macOS instead of failing
Check 4.
- Decision record: engdocs/decisions/2026-07-17-docs-release-pin.md; the
beads-docs skill §8 updated to match.
* lint: annotate gosec G705 false positive in the docsmint legacy bridge
Same class as the existing nav-splice annotation: a developer tool writing
repo Markdown, not a web-output sink.
* docs: align user docs and CLI reference with the v1.1.0 release
The Mintlify site publishes from main, so the docs had drifted ahead of the
latest release — documenting features that no released binary ships.
- Remove architecture/storage-backends: v1.1.0 supports only Dolt (the
SQLite/Postgres/MySQL backends are post-tag work on main). Redirect the
old routes to /architecture/dolt and drop the alternate-backend claims
from README, core-concepts, architecture index, and FAQ.
- Stamp the docs homepage with the release: "These docs are for the 1.1.0
release" plus a link to the v1.1.0 release notes.
- Regenerate the CLI reference (docs/cli-reference/, docs/CLI_REFERENCE.md,
docs.json nav) from the released v1.1.0 binary via tools/docsmint: removes
pages for post-1.1.0 commands (heartbeat, migrate-personal, reclaim,
unclaim) and post-1.1.0 flags.
- Fix hand-written pages that referenced post-1.1.0 CLI surface, verified
against the v1.1.0 binary: bd dep relate/unrelate (not top-level
relate/unrelate), bd admin reset (not bd reset), bd hooks list (not
status), bd history / bd vc status (not vc log/diff), release the claim
via bd assign + bd update (no bd unclaim), drop bd migrate-personal and
bd daemon mentions, and reduce the Cursor integration page to the rules
file that v1.1.0's bd setup cursor actually installs.
- Stop documenting the BD_ALLOW_REMOTE_MIGRATE escape hatch (and the
nonexistent-in-1.1.0 bd migrate --force): the remote-migrate gate prints
its own operator guidance by design; docs now defer to it.
* docs: auto-regenerate CLI reference
Applied from the cli-docs-freshness-patch artifact of https://github.com/gastownhall/beads/actions/runs/29613329749
(generated with CI's canonical pinned build). See
scripts/check-cli-docs-drift.sh for how drift is attributed.
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Addresses lion's review on #4864: remote-tracking refs from past pushes/
fetches keep the pre-squash chain reachable, so Step 3's gc silently
reclaimed nothing on exactly the long-lived synced workspaces this runbook
targets. Step 3 now deletes them (force-push recreates them on the new
chain) and verifies with du -sh. Also: why the root commit stays as the
baseline parent, and Prevention links to the heartbeat/wisps pages.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Fenced-window procedure: backup, soft-reset squash to a baseline commit,
drop stale refs, gc --full, force re-publish, re-clone everywhere else.
Motivated by the wyvern deployment's 3.6G of reachable lease-churn
history (wy-7lmdp).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claims/heartbeats no longer mint dolt commits: lease state (holder,
granted_at, lease_expires_at, heartbeat_at) moves off the issues table
into a leases table registered in dolt_ignore. Migration 0055 +
ignored/0012 move live leases over; all full-issue query sites hydrate
via LEFT JOIN; import never clobbers a live local lease.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Adds the new bd init flags (--proxied-server-external-tls-ca-cert-path,
--proxied-server-external-tls-server-name, --proxied-server-external-tls-skip-verify)
to the generated CLI reference. Also picks up gate help drift already on
this branch.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Review follow-ups on the pool-claim feature:
- The proxied-server (uow) claim path has its own CAS
(issueSQLRepositoryImpl.Claim) and did not get the pool predicate, so
in dolt.mode=proxied-server a pool-assigned issue was still refused as
"already claimed by <pool>". It now resolves claim.pools through the
same issueops.ClaimPoolAliasesInTx and extends its predicate
identically, and ClaimRowResult carries CurrentAssigneeIsPool so the
use-case layer reports a status conflict instead of a held-by-pool
refusal on CAS loss. Covered by three new subtests in the domain/db
suite (pool take + lease, unconfigured alias protected, status
conflict flagged).
- claim.* is now a recognized config namespace: bd config set
claim.pools previously warned "not a recognized config key" on the
feature's own setup command. The embedded pool test now fails on that
warning (the exit code alone missed it), and the recognizer unit test
pins claim.pools.
- bd config --help documents the key (Claim Pools section + example),
including the reclaim caveat: an expired pool take returns to the
unassigned pool, not to the pool alias it was dispatched to. CLI
reference regenerated.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Dispatcher fleets pre-assign issues to a pool pseudo-assignee (e.g.
'fable-crew') and members take items from the pool. --claim refused
those ("already assigned"), forcing a two-step '--assignee <me>
-s in_progress' per issue — reported by the wyvern rig as their
biggest friction, hit on all 10 beads of a review session.
Aliases listed in the claim.pools config (comma-separated) are now
claimable by any actor through the same atomic CAS: the assignee
predicate gains 'OR assignee IN (<pools>)', resolved in-transaction
via GetConfigInTx, so there is no storage-interface change and no new
flag. A pool take stamps the normal lease. Issues assigned to a real
actor — or to an alias not in the config — keep their anti-steal
protection, and the 0-row disambiguation reports a status conflict
for pool-assigned rows instead of a misleading held-by refusal.
Off by default: with no claim.pools configured the predicate and
behavior are byte-identical to before.
New TestEmbeddedClaimPools covers the full dispatcher flow (pool
assign -> claim -> close), a second alias, lease stamping, and both
protection boundaries (real actor, unconfigured alias).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The --claim refusal for an issue assigned to another actor said "Use
bd unclaim <id> to release it before re-claiming". In a multi-agent
fleet that copy taught exactly the wrong move: an agent's silenced
'unclaim; claim' batch loop evicted another agent's live, heartbeated
claim mid-review (wyvern incident wy-yuclk, ask wy-zs5s2).
The ownership check itself (foreign unclaim requires --force) already
landed in #4675; this completes the ask by fixing the guidance around
it:
- The open-but-assigned --claim refusal now says to coordinate with
the holder and notes that releasing another actor's claim requires
bd unclaim --force.
- Unclaim's ErrNotOwner rejection frames --force as an abandoned-claim
escape hatch (crashed agent, expired lease), not a routine override.
- bd unclaim's help documents the ownership rule and points at lease
expiry for genuinely abandoned work.
Tests pin the new coordinate-with-holder copy and assert the old
release-before-reclaiming suggestion stays gone. CLI reference
regenerated; picks up the same pre-existing auto-backup help drift
hunk as #4839 (identical content, merges cleanly either order).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Document the rollback of direct PostgreSQL and MySQL adapters because supporting additional general-purpose server databases adds operational and maintenance complexity. Our goal is to keep Beads as simple as possible and consume as few resources as possible.
Clarify that embedded Dolt, Dolt server, and SQLite remain supported, including Dolt server use of the MySQL wire protocol.
Existing PostgreSQL and MySQL databases are not opened or modified. Migration requires an export from a supporting build, reinitialization guided by bd help init-safety, and import; JSONL remains issue-level interchange rather than a complete backup.
Refresh generated CLI reference material alongside the storage guidance.
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Test User
* feat(graph): add --open flag for LLM-friendly compact layer output (GH#3544)
Add --open flag to `bd graph` that filters out closed/deferred issues and
renders only actionable items in compact layer format.
Key behaviors:
- Filters to open/in_progress/blocked statuses only
- Computes transitive closure of blocking edges through removed nodes
(if A blocks B(closed) blocks C, adds synthetic edge A→C)
- Auto-selects compact layer rendering for LLM-friendly output
- Works with both single-issue and --all modes
- Deduplicates edges when direct and transitive paths overlap
- Falls back to highest-priority open issue when root is filtered out
* docs: regenerate CLI reference for --open flag and federation updates
Resolves modify/delete conflicts on website/* (Mintlify migration deleted
the tree in main; accept deletion). cmd/bd/prime.go auto-merged cleanly,
re-siting --no-memories on top of #4335's custom-PRIME.md/formatMemoriesForPrime
handling and #4230's doltSync gating without further edits.
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
Resolves the Mintlify website-tree deletion conflict (52aea3f7e) against
this PR's now-obsolete website/*/cli-reference/prime.md doc edits: accept
main's deletion. cmd/bd/prime.go merged cleanly (no conflict markers) —
the PR's --memories-only-before-custom-PRIME.md dispatch and its
memory-append-under-custom-PRIME.md logic both survived alongside main's
agent.profile Long-help bullet (#4585). Regenerated CLI docs
(scripts/generate-cli-docs.sh) produced no additional diff beyond the
merge itself.
Agent-Signature: claude-fable-5-high on behalf of matt wilkie