Commit graph

654 commits

Author SHA1 Message Date
matt wilkie
2c0f92318e
fix(reset): a comment is content when the question is deletion (follow-up to #5221) (#5227)
* 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
2026-08-01 03:04:55 -07:00
matt wilkie
916365150f
fix(reset): decide hook deletion from provenance, not the word "beads" (#5221)
* 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
2026-08-01 02:16:20 -07:00
matt wilkie
868dd077ab
fix(doctor,hooks): diagnose a dangling core.hooksPath and clear beads.role on uninstall (#5203)
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
2026-07-31 16:16:47 -07:00
Vishnu J
1a5393dc97
docs: caveat --parent label inheritance with size/effort labels (#4562) (#5123)
* 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>
2026-07-31 01:44:50 -07:00
Steve Yegge
8bb0d36be0
docs(recovery): fold squash-window lessons into the history-squash runbook (bd-gpgdy) (#5176)
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>
2026-07-30 18:05:31 -07:00
Kevin Chan
59cfc4a000
[codex] Add Kiro setup recipe (#4535)
* 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>
2026-07-27 22:28:43 -07:00
Kevin Glynn
f4fcc318d2
docs: remove stale 8-char prefix limit claim from rename-prefix help (GH#770) (#4813)
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.
2026-07-26 12:29:39 -07:00
Ransom
446538a8e4
docs: add Beadazzle to Native Apps in community-tools.md (#4735) 2026-07-26 12:28:50 -07:00
Johann Dirry
3dbda07f19
fix(build) fixing build when using MSVC (#4324) (#4325)
* 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>
2026-07-26 11:40:47 -07:00
Athos Bernardes
3102cbd4d4
fix(show): flag comment_count as omitted when comments are not streamed (#4865)
* 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>
2026-07-25 16:16:41 -07:00
Steve Yegge
5a4c68a89c fix(leases): keep node_id off the committed config; tighten the replica guard (wy-jpd3.7)
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.
2026-07-25 02:32:31 -07:00
Steve Yegge
c00e4d6a9e fix(leases): make the replica guard opt-in — drop the hostname fallback (wy-jpd3.7)
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.
2026-07-25 02:32:31 -07:00
Steve Yegge
966ddac5af feat(leases): replica-aware leases — record the granting node, refuse cross-replica reclaim (wy-jpd3.7)
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.
2026-07-24 23:53:34 -07:00
Jackson Cantrell
3ab419583e
docs: add emBEADings to community tools (#4850)
* docs: add emBEADings to community tools

* docs: use PyPI install for emBEADings

---------

Co-authored-by: Jackson Cantrell <cantrelljax@gmail.com>
2026-07-23 22:26:13 -07:00
Pavlos Vinieratos
1125ef3b46
Rename the reserved "graph" mermaid node id so diagrams render (#4958) 2026-07-23 17:14:09 -07:00
Steve Yegge
00a6ab5030 docs(recovery): squash fence must cover every syncing machine's scheduled jobs (bd-g3di3)
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>
2026-07-18 06:08:53 -07:00
Chris Sells
3697516436 docs(recovery): drop the dead bd-heartbeat link from the squash runbook
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.
2026-07-17 21:07:18 -07:00
Chris Sells
ff413433df docs(upgrading): document BD_ALLOW_REMOTE_MIGRATE for scripted upgrades
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.
2026-07-17 21:07:18 -07:00
Steve Yegge
f6d8d56ac7
Merge pull request #4864 from gastownhall/docs/bd-okqpv-history-squash-runbook
docs(recovery): history-squash runbook (bd-okqpv / wy-7lmdp)
2026-07-17 20:38:17 -07:00
Steve Yegge
3374003682 docs(recovery): squash runbook — correct Step 5 pull hazard: cross-merge re-anchors old history (bd-okqpv)
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>
2026-07-17 20:38:06 -07:00
Steve Yegge
cbe8efacea docs(recovery): squash runbook — force-push does not shrink the remote; replace it to reclaim the published side (bd-okqpv)
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>
2026-07-17 20:14:26 -07:00
Chris Sells
b9ed0aa4fb docs(recovery): reduce the stub to a pure pointer
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.
2026-07-17 18:56:33 -07:00
Chris Sells
787d3aaf5e docs(recovery): restore RECOVERY.md as a forwarding stub for shipped v1.1.0 links
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.
2026-07-17 18:14:00 -07:00
Chris Sells
d2f87d50de
docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876)
* 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.
2026-07-17 18:03:28 -07:00
Chris Sells
8c974d8dc4
docs: align user docs and CLI reference with the v1.1.0 release (#4874)
* 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>
2026-07-17 14:17:28 -07:00
Steve Yegge
079a6bf49d docs(recovery): squash runbook — delete remote-tracking refs before gc, verify with du; root-commit rationale; lease/wisp cross-links (bd-okqpv)
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>
2026-07-17 13:42:36 -07:00
Steve Yegge
d431fe8b55 docs(recovery): history-squash runbook — shed reachable history dolt gc can't reclaim (bd-okqpv)
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>
2026-07-17 01:53:45 -07:00
Steve Yegge
59f8d6ae97 feat(leases): move leases to ephemeral dolt_ignored leases table (bd-lrgn1)
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>
2026-07-17 01:02:29 -07:00
coffeegoddd☕️✨
8c779d3aa5 docs: regenerate CLI reference for proxied-server external TLS flags
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>
2026-07-16 16:44:26 -07:00
Julian Knutsen
0cf3b3ca09
Revert "Simplify the supported backends: roll back the direct PostgreSQL and MySQL adapters" (#4857) 2026-07-16 16:35:51 -07:00
Julian Knutsen
69f33cedd3
Merge pull request #4847 from gastownhall/chore/simplify-storage-backends
Simplify the supported backends: roll back the direct PostgreSQL and MySQL adapters
2026-07-16 15:44:17 -07:00
Steve Yegge
849c05ba92
Merge pull request #4843 from gastownhall/feat/bd-bguz6-pool-claim
feat(claim): pool-aware claiming via the claim.pools config key (bd-bguz6)
2026-07-16 15:06:13 -07:00
Steve Yegge
cd89dfd88a
Merge pull request #4841 from gastownhall/fix/bd-at6rc-claim-copy
fix(claim): stop the refusal copy from teaching claim eviction (bd-at6rc)
2026-07-16 13:54:32 -07:00
github-actions[bot]
d9e4bf24fd docs: auto-regenerate CLI reference
Applied from the cli-docs-freshness-patch artifact of https://github.com/gastownhall/beads/actions/runs/29527276674
(generated with CI's canonical pinned build). See
scripts/check-cli-docs-drift.sh for how drift is attributed.
2026-07-16 19:21:18 +00:00
Steve Yegge
e10e19b44e fix(claim): pool-claim parity for the proxied-server path + recognized claim.* config namespace (bd-bguz6)
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>
2026-07-16 10:09:09 -07:00
Steve Yegge
9bab22995f feat(claim): pool-aware claiming via the claim.pools config key (bd-bguz6)
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>
2026-07-16 10:09:09 -07:00
github-actions[bot]
3bab9e7b39 docs: auto-regenerate CLI reference
Applied from the cli-docs-freshness-patch artifact of https://github.com/gastownhall/beads/actions/runs/29517882064
(generated with CI's canonical pinned build). See
scripts/check-cli-docs-drift.sh for how drift is attributed.
2026-07-16 17:06:43 +00:00
Steve Yegge
bd73c75292 fix(claim): stop the refusal copy from teaching claim eviction (bd-at6rc)
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>
2026-07-15 23:03:34 -07:00
matt wilkie
4489f63c35
docs: regenerate backup help (mybd-mvc3) (#4825)
Agent-Signature: codex-gpt-5.6-terra-medium on behalf of matt wilkie
2026-07-15 21:54:58 -07:00
Test User
98573a4983 docs(storage): explain focused Dolt and SQLite support (bd-sadcd)
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
2026-07-16 03:42:17 +00:00
coffeegoddd☕️✨
e79ea8e65d /{.github,docs,engdocs,go,internal,scripts}: bump dolt 2026-07-15 13:14:34 -07:00
Kevin Glynn
f5dd5072b8
feat(graph): add --open flag for LLM-friendly compact output (GH#3544) (#3778)
* 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
2026-07-14 10:17:30 -07:00
matt wilkie
6a127f8eea
Merge pull request #4336 from kevglynn/feat/3961-prime-no-memories
feat(prime): add --no-memories to omit the persistent memories section (#3961)
2026-07-13 22:14:07 -07:00
matt wilkie
880f34b120 Merge remote-tracking branch 'upstream/main' into pr-4336-fix
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
2026-07-13 21:42:55 -07:00
matt wilkie
4557c2f8d7
Merge pull request #4229 from kevglynn/fix/4222-no-color-flag
feat(cli): add --no-color flag for explicit color suppression
2026-07-13 21:40:24 -07:00
matt wilkie
4b9bd91fab
Merge pull request #4335 from kevglynn/fix/3941-prime-memories-custom-primemd
fix(prime): inject memories under custom PRIME.md; fix --memories-only (#3941)
2026-07-13 21:36:19 -07:00
matt wilkie
0cf3836e75
Merge pull request #4347 from mlushpenko/feature/list-external-ref-filter
feat(list): add --external-ref exact-match filter
2026-07-13 21:35:38 -07:00
matt wilkie
00107e6ed5 docs: regenerate CLI reference for global --no-color flag
Agent-Signature: claude-fable-5-high on behalf of maphew
2026-07-13 20:54:50 -07:00
matt wilkie
94208767aa Merge upstream/main into fix/3941-prime-memories-custom-primemd
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
2026-07-13 20:44:33 -07:00
matt wilkie
75f30b0b49 docs: regenerate CLI reference for bd list --external-ref
Agent-Signature: claude-fable-5-high on behalf of maphew
2026-07-13 20:40:22 -07:00