Commit graph

587 commits

Author SHA1 Message Date
Chris Sells
de0200ff77 docs(emitter): Cobra-accurate usage lines, published global flags, MDX ESM guard
Three generated-content defects from the adversarial review, all
structurally invisible to the drift gate (generated-vs-generated):

- Usage lines now mirror Cobra's help template: a runnable command shows
  its UseLine, a command with subcommands shows '<path> [command]', both
  when both apply. Previously bare UseLine() stamped 'bd mol [flags]' on
  30 parent pages — a line the binary never prints.
- The generated CLI index publishes the Global Flags block; the binary
  prints it on every --help but no page carried it.
- docsmint neutralizes prose lines that Mintlify's prebuild would dedent
  into MDX ESM blocks (a line beginning 'export'/'import' outside a
  fence gets wrapped in a code span). This is why /cli-reference/mail
  returned HTTP 200 while rendering only a parse-error placeholder —
  reproduced, fixed, and covered by a planted-hazard test; fenced
  content stays verbatim.

Also rewords check-cli-docs-drift.sh's early-PASS message, which
asserted 'the supplied binary differs' as the cause when uncommitted
local edits produce the same result.

All 113 pages + docs/CLI_REFERENCE.md regenerated through the pipeline;
TDD'd in cmd/bd/help_all_test.go and tools/docsmint/docsmint_test.go.
Verified live: /cli-reference/mail renders real content, zero parse
errors; generate-cli-docs.sh --check, docsync, freshness, and
mint broken-links all pass on this tree.
2026-07-12 10:37:17 -07:00
Chris Sells
5b660081ed docs: fix fact errors found by adversarial review
Every fix verified against the binary or a traced source call path:

- How Beads Works: parent-child DOES affect ready work (a blocked parent
  blocks its children — the blocked-state SQL inherits it), hash-ID
  inputs are title/description/creator/creation-time plus a collision
  nonce (live generator is internal/idgen, not the legacy one), and
  bead gates dropped from the gates bullet (currently unresolvable).
- Graph-link type strings are hyphenated (relates-to, replies-to);
  underscore forms are rejected by the parser. Fixed corpus-wide
  including the README feature bullet.
- upgrading.md: the version-era table's boundaries were refuted by git
  archaeology (embedded Dolt shipped in v0.60.0 and always used
  .beads/embeddeddolt/; nothing changed at the claimed v0.63.3
  boundary) — replaced with a layout-based identification table.
- Phantom .beads/dolt/sql-server.log path in sync-failures and the FAQ;
  the managed server writes .beads/dolt-server.log.
- FAQ: ID growth matches DefaultAdaptiveConfig (min 3, max 8,
  probability-driven), dependency-type wording no longer claims exactly
  four types, and unmeasured performance figures are hedged instead of
  stated as facts.
- quickstart: bd migrate --cleanup doesn't exist; init installs hooks
  by default (no prompt) and has no merge-driver step; ready output
  quote and bd restore recovery source corrected.
- formulas.md: step types map to issue types (task/bug/feature/epic/
  chore; anything else falls back to task — human/gate are not step
  types), and there is no built-in formula search tier.
- todo.md: bd update takes --set-labels, not --labels.
- graph-links.md: broken #dependencies fragment → #add-dependencies.
2026-07-12 10:37:17 -07:00
Chris Sells
8bf92257b4 docs: rewrite workflows/gates.md against the real gate surface
Adversarial review falsified this page: 10 of its 12 checkable claims
contradicted the binary. It taught a phantom TOML gate schema (approvers,
require_all, duration, event, status, action, merged — all silently
dropped by the parser), phantom subcommands (bd gate approve/skip), a
nonexistent pending/open/closed state model, list-valued waits_for, and
7d durations that time.ParseDuration rejects.

Rewritten from source: the four-field [steps.gate] schema
(type/id/await_id/timeout per internal/formula/types.go), the real
subcommand set (list/create/show/resolve/check/add-waiter), gate types
with their closers (human resolves manually; timer and gh:* close via
bd gate check; bead gates currently unresolvable — multi-rig routing
removed), needs vs waits_for fan-in semantics, and a worked example
taken from beads' own release formula.

Closure: every TOML construct on the page round-trips intact through
bd formula show --json (gh:run/human/timer gates, needs, waits_for).
2026-07-12 10:37:17 -07:00
Chris Sells
cf2711f13e docs(nav): nest the CLI Reference under Reference
The 113-page generated CLI Reference moves from a top-level nav group to
a nested group inside Reference — Mintlify renders nested groups
collapsed by default, so the command list no longer dominates the
sidebar. The docsmint nav splice is depth-agnostic (indentation is
derived from the pages key's line), verified by regenerating and by
re-pointing its test fixture at the nested shape. Reference overview and
the beads-docs skill IA note updated.
2026-07-12 10:37:17 -07:00
Chris Sells
4e97ae25f7 docs: port the Excalidraw diagram pipeline (machinery only)
make diagrams-excalidraw renders committed .excalidraw sources under
docs/diagrams/excalidraw/ to SVGs in docs/diagrams/excalidraw-rendered/
(idempotent, @swiftlysingh/excalidraw-cli via npx), matching the Gas City
convention. No diagrams authored yet — the nine existing diagrams stay
mermaid. The beads-docs skill names the real target and paths.
2026-07-12 10:37:17 -07:00
Chris Sells
cc9601f85c fix(cli): printed doc paths point at the new docs locations
Per decision 7, bd's user-facing strings now reference the Mintlify-era
paths: prime policy-profiles help, storage-backend comparison help
(store_factory_nocgo, init --backend), init-safety help (recovery
playbooks now docs/recovery/init-safety.md; the ADR reference now
engdocs/adr/), the pk-fork-refused recovery URL (dolt.go), doctor's plugin
suggestions (claude.go) and managed-handoff pointer, aider setup guidance
and the shared recipe template (quickstart URL), and the agent instruction
templates (sync-concepts URL, quickstart URL). bd mol pour's help no
longer claims molecules are 'synced with git' — they sync via Dolt like
any other bead.

Also corrects the stale claude recipe ProjectPath metadata
(.claude/settings.local.json -> .claude/settings.json; the dedicated
installer has written settings.json since the migration sweep).

This repo's AGENTS.md managed section is refreshed to the new template
body (hash bacef91e, has-remote variant preserved), and agents.md.tmpl's
embedded marker matches. Template tests updated to pin the new fragment;
CLI docs regenerated.

Recorded, not fixed (behavior-level, see the decision record):
routing.mode's maintainer/contributor no-op values and the
sync.require_confirmation_on_mass_delete key with no consumer.

Note: TestCheckBeadsRole_NotConfigured/_NotGitRepo in cmd/bd/doctor fail
on any machine with beads.role in the global git config (no HOME
isolation) — pre-existing, unrelated to this change.
2026-07-12 10:37:17 -07:00
Chris Sells
874e74bdf3 docs: replace pointer stubs with Mintlify redirects
Per decision 6: the eleven pointer stubs at old top-level docs/ paths are
deleted; the docs.json redirects array now maps every moved page's old
route to its new home (43 entries covering the full pre-port top-level
namespace). The docsync exemption list shrinks to the one generated file
(docs/CLI_REFERENCE.md). Plugin and npm-package quickstart pointers now
link the real in-repo page.

Old GitHub deep links to the deleted paths 404 from here on — accepted in
the decision record; bd's own printed paths are updated to the new
locations in the next commit, so only already-released binaries are
affected.
2026-07-12 10:37:17 -07:00
Chris Sells
73a4d95fbc docs(emitter): bd emits generic Markdown only; Mintlify targeting moves to tools/docsmint
Per the decision record (engdocs/decisions/2026-07-10-mintlify-docs-overhaul.md):
bd's doc generator is vendor-neutral. `bd help --docs-root` now writes
docs/CLI_REFERENCE.md plus a generic per-command tree (title/description
frontmatter, portable CommonMark, HTML-comment markers) into build/cli-docs/
— uncommitted staging, gitignored. All site-generator-specific output leaves
the binary: Docusaurus frontmatter, sidebarPositionMap, the website/ writers,
the Mintlify writers, the docs.json nav splice, and the --docs-version
snapshot flag are gone from cmd/bd.

tools/docsmint (Go, unit-tested) is the Mintlify post-processor: it turns
the staging tree into the committed docs/cli-reference/ pages (JSX comment
markers, extensionless route links) and splices the CLI Reference pages
array in docs/docs.json. scripts/generate-cli-docs.sh runs both stages;
--check seeds the committed artifacts into a scratch root, regenerates, and
diffs, exactly as before.

Regenerated output: the 113 pages are byte-identical through the new
pipeline; docs.json nav ordering is now plain filename sort;
docs/CLI_REFERENCE.md drops the removed --docs-version flag.

`bd help --doc <cmd>` stdout is likewise generic now (no Docusaurus
id/slug/sidebar_position).
2026-07-12 10:37:07 -07:00
Chris Sells
5c2fe0d496 docs: loss-check merge legacy docs/ originals into the site pages
Sixteen same-ground pairs reconciled: the ported website page won and every
fact living only in the older docs/ original was merged in before deleting
it (INSTALLING, SETUP, ARCHITECTURE, CONFIG, GIT_INTEGRATION, ADVANCED,
TROUBLESHOOTING, FAQ, MOLECULES, ROUTING, MULTI_REPO_AGENTS, and the five
agent-integration guides). The two divergent FAQs are now one canonical
FAQ with the comparison-first framing leading and pre-1.0 version gating
removed.

The routing pair inverted: the ported page described a routing system that
does not exist (bd routes, bd hydrate, .beads/routes.jsonl); the page was
rebuilt from the accurate sources (ROUTING.md + MULTI_REPO_AGENTS.md)
against the real surface (routing.mode config, role detection,
repos.primary/additional hydration, --repo override).

Every claim was verified against the Go source or the generated CLI
reference. Phantom surfaces removed across the corpus: bd pin/hook/pour/
wisp/routes/hydrate/reserve/lock/merge/stats, bd hooks status, bd vc
conflicts/log, bd dolt set shared-server, fictional beads_* MCP tool names
(real names taken from beads-mcp server.py), import.orphan_handling and
export.error_policy config keys, database.wal_mode/cache_size, stale
.beads/dolt/sql-server.log paths, and SQLite-era file paths. Notable
corrections: min_hash_length default is 3, .beads/metadata.json is
git-tracked, tombstone status is removed, wisps live in the main database
under an ephemeral flag.

Freshness markers moved with their content (configuration, ide-setup) and
the freshness gate + DOC_INVENTORY ledger now point at the new locations.
Load-bearing anchors preserved: #branchless-workflows-jujutsu--jj,
#circuit-breaker-server-appears-down-failing-fast, #extensible-database,
#multi-repo-hydration. Pointer stubs remain at docs/{SETUP,INSTALLING,
GIT_INTEGRATION}.md because released binaries print those paths
(allowlisted in the docsync guard).

Gates: go test ./test/docsync PASS; generate-cli-docs.sh --check PASS;
check-doc-freshness.sh PASS; mint broken-links: no broken links; mint dev
serves all sections (11 routes spot-checked at 200).
2026-07-12 10:37:07 -07:00
Chris Sells
7c4ac15a16 docs: README diet — move storage detail to the Dolt guide, add hero diagram
README drops from 254 to ~190 lines: the server-mode connection table,
Unix-socket note, prune/purge maintenance semantics (including
reference-aware protection), and backup/migration walkthrough move into
docs/architecture/dolt.md, which now owns that material once. The README
keeps the pitch, quick start, features, essential commands, and a
condensed storage-modes summary with links, and gains a hero mermaid
diagram of the create -> ready -> claim -> close loop (GitHub renders
mermaid natively).
2026-07-12 10:37:07 -07:00
Chris Sells
1ea7ea2a99 docs: fix phantom command surfaces in workflow pages
The ported workflow pages documented commands that do not exist in bd:
bd pour, bd wisp create/list/show/delete/cleanup, bd pin, bd hook, and a
.beads-wisp/ storage directory. Verified against the live binary: the
real surface is bd cook, bd mol pour, bd mol wisp (+ list/gc), bd mol
squash/burn, bd create --ephemeral, and bd purge; wisps are rows in the
main database with Ephemeral=true, excluded from federation push by
default, not a separate gitignored store.

Rewrote workflows/wisps.md around the verified lifecycle
(create -> execute -> squash or burn), fixed formulas.md instantiation
examples, dropped the design-doc status header from adaptive-ids, and
linked the home page's concept table to the canonical pages.
2026-07-12 10:37:07 -07:00
Chris Sells
54a7547b0d docs: canonical concept page, section overviews, and concept diagrams
- Rewrite docs/core-concepts/index.md as 'How Beads Works' — the one
  canonical concept page (modeled on Gas City's how-gas-city-works):
  problem-first framing, the bead -> dependencies -> ready-work loop, hash
  IDs, the formula -> proto -> molecule/wisp pipeline, gates, Dolt sync,
  federation, and storage modes, led by four mermaid diagrams. Other pages
  link here instead of re-deriving the model.
- Fact fixes caught while writing (verified against source/live help):
  hash IDs are content-derived SHA-256 (internal/types/id_generator.go),
  not random; bd pour/bd wisp/bd pin/bd hook are not commands (the real
  surface is bd mol pour, bd mol wisp, bd assign, bd update --claim);
  wisps are not stored in .beads-wisp/; cross-repo dependency syntax is
  external:<project>:<capability> (cmd/bd/dep.go); recovery index claimed
  SQLite errors in a Dolt product.
- Section overview pages: rewrite workflows/index, extend recovery,
  multi-agent, and integrations indexes to list every child with one-line
  summaries; add reference/index and put it in the nav.
- New concept diagrams: sequential-vs-hash ID merge collision
  (core-concepts/hash-ids) and embedded-vs-server mode
  (architecture/dolt).
- website/README.md: real build/verify instructions and parallel-run
  status for the Docusaurus site.
- Repoint example READMEs and page labels at the real quickstart page.
2026-07-12 10:37:07 -07:00
Chris Sells
3198395a32 docs(ci): add Mintlify preview, docsync guard, and broken-links workflow
- mint.sh + make docs-dev: local preview of the docs/ Mintlify site
  (Node 22 handling modeled on the Gas City wrapper).
- test/docsync: Go guard keeping docs/ and docs.json in exact
  correspondence — every nav entry has a file, every page is in the nav
  (tiny stub allowlist for paths released bd binaries print), published
  pages use root-relative extensionless links that resolve, and engdocs/
  plus curated root markdown keep exact GitHub-style paths. Wired into
  make check-docs.
- .github/workflows/docs-mintlify.yml: docsync + baseline-aware
  mint broken-links check on PRs touching docs/**.
- Retire scripts/sync-website-docs.sh and its mirror-drift gate: the six
  mirrored files now live once in the Mintlify site; the committed
  Docusaurus mirrors stay frozen so the parallel-run site keeps building.
- Repoint inbound links to moved docs across README, guides, examples,
  npm-package, plugin resources, and Go comments; add docs/SYNC_CONCEPTS.md
  pointer stub (bd's agent templates print that path). Runtime strings in
  cmd/bd (prime.go, store_factory_nocgo.go, init_git_hooks.go) still print
  old paths — covered by stubs, flagged in the PR.
2026-07-12 10:37:07 -07:00
Chris Sells
4ea6fa3ac0 docs(emitter): emit Mintlify CLI reference and generated docs.json nav
bd help --docs-root now additionally writes docs/cli-reference/ in Mintlify
form (frontmatter title as H1, extensionless root-relative links, JSX
auto-generated markers since Mintlify parses .md through MDX) and rewrites
the CLI Reference pages array inside docs/docs.json via a textual splice
that leaves the rest of the file byte-identical — the ~113 nav entries are
never hand-maintained. The Docusaurus outputs (docs/CLI_REFERENCE.md,
website/docs/cli-reference/, versioned snapshots) are unchanged.

generate-cli-docs.sh --check seeds docs/docs.json and docs/cli-reference/
into its scratch root and diffs both; check-cli-docs-drift.sh adds them to
GEN_PATHSPECS and the regeneration fingerprint; docs-autofix-push.sh
allowlists the new generated paths; check-doc-flags.sh scans the new
docs/ subdirectories and requires command coverage in docs/cli-reference/.

Includes the initial docs/docs.json scaffold (nav mirrors the Docusaurus
sidebar IA) and the generated docs/cli-reference/ pages.

TDD: new emitter behavior covered in cmd/bd/help_all_test.go
(Mintlify page format, nav splice correctness + idempotence, bare-root
generation without docs.json).
2026-07-12 10:37:07 -07:00
Chris Sells
a86a2c5dfc docs: port user docs into the Mintlify site tree under docs/
Port the website's current (non-versioned) authored pages into docs/ as
Mintlify pages: frontmatter title as H1 (body H1s removed), Docusaurus
admonitions converted to Mintlify components, root-relative extensionless
links, mermaid fences kept as-is. website/docs/** is untouched and keeps
serving the Docusaurus site until cutover.

git-mv the user-facing docs/ originals with no website twin into the new
IA (core-concepts/, architecture/, workflows/, recovery/, multi-agent/,
integrations/, reference/), converted to Mintlify form. The six files
previously mirrored by sync-website-docs.sh now live once in the site.
ERROR_HANDLING.md and CONTRIBUTOR_NAMESPACE_ISOLATION.md move to engdocs/
(contributor pattern guide and design doc per content review).

Pointer stubs remain at docs/{DOLT,STORAGE-BACKENDS,PLUGIN,RECOVERY,
JSON_SCHEMA}.md because released bd binaries print those paths; QUICKSTART
and DOLT-BACKEND stay as existing pointer stubs.

Corrected while porting: the intro's storage diagram claimed data lives at
.beads/dolt/; embedded mode (the default) uses .beads/embeddeddolt/
(internal/storage/embeddeddolt/store.go), server mode uses .beads/dolt/.
2026-07-12 10:37:07 -07:00
Chris Sells
0e017821f4 docs: move internal/maintainer docs from docs/ to engdocs/
Relocate contributor- and maintainer-facing material out of docs/ so the
directory can become the user-facing Mintlify site. Moves preserve subpaths
(adr/, design/, staged-for-removal/ intact). messaging.md, UI_PHILOSOPHY.md,
and AGENT_SIGNING.md move per their DOC_INVENTORY dispositions (design doc,
design philosophy, maintainer convention).

Inbound links updated repo-wide: root guides, CONTRIBUTING, AGENTS,
workflows, lint config, scripts (check-doc-freshness now resolves the
inventory at engdocs/DOC_INVENTORY.md), Go comments, and the synced website
metadata page (regenerated via sync-website-docs.sh + generate-llms-full.sh).

The emitted help text in cmd/bd/init_safety_help.go still references
docs/adr/0002-init-safety-invariants.md; changing it would change bd's
runtime output, which is out of scope for this branch (flagged in the PR).
2026-07-12 10:37:07 -07:00
Steve Yegge
672d942083
fix(label): support comma-separated multi-label add/remove; fail hard on bad issue IDs (#4713)
* fix(label): support comma-separated multi-label add/remove; fail hard on bad issue IDs (bd-vu5kv)

'bd label add <id> a b c' silently applied only 'c': the grammar treats
the last arg as THE label and everything before it as issue IDs, and
unresolvable IDs were skipped with a stderr warning while the command
exited 0. An agent hit this in the wild and only noticed because
'bd ready --label ...' came back empty.

Two changes:

- The final positional arg now splits on commas, so
  'bd label add bd-123 a,b,c' adds all three labels in one transaction
  (same convention as 'bd create --labels a,b,c'). Same for remove.
- Issue-ID args that fail to resolve are now a hard error before any
  mutation, instead of warn-and-continue. When several ID-position args
  fail, the error hints at the comma-separated form, which is exactly
  the space-separated-labels mistake.

The reserved 'provides:' check now runs against every label in the
list. Regenerated CLI reference docs (freshness probe) and updated
docs/LABELS.md.

Closes bd-vu5kv

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012VBUR4qkHbssPomBDuJgkQ

* docs: sync website label mirrors

Agent-Signature: codex-gpt-5.6-terra-high on behalf of matt wilkie

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
2026-07-12 08:23:52 -07:00
matt wilkie
64a136d56e
fix(audit): make JSONL sidecar opt-in (#4688)
Routine issue history already lands in the database events tables. Stop creating or appending the interactions JSONL sidecar by default, add audit.enabled for explicit sidecar use, and expose database events via bd history --events.

Fixes gastownhall/beads#4687

Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie
2026-07-11 00:09:17 -07:00
Michael Hackner
6829d2418a
feat(cursor): bring Cursor integration to parity with Claude/Codex (#4649)
Cursor support is anemic compared to Claude Code and Codex. It ships
only a static rules file: no agent lifecycle hooks, so `bd prime`
context is never injected at session start and is silently lost after
context compaction, and it has no `bd init` auto-install, no `--global`
scope, no shared agent skill, and no `bd doctor` coverage.

This PR brings Cursor up to the same footing as the tier-1 integrations.

- `bd setup cursor` now installs agent lifecycle hooks
  (`.cursor/hooks.json`) alongside the rules file, wiring
  sessionStart/preCompact/postToolUse to a hidden `bd cursor-hook`
  command so Beads context survives compaction:
  * sessionStart injects full `bd prime` context into new sessions
  * preCompact arms a one-shot refresh marker
  * postToolUse re-injects `bd prime` once after a compaction, then
    no-ops
- `bd init` auto-installs Cursor (rules + skill + hooks) and stages
  `.cursor/`
- `bd setup cursor --global` writes `~/.cursor/hooks.json` +
  `~/.agents/skills/beads`
- Canonical rules: `.cursor/rules/beads.mdc` wraps the shared
  `recipes.Template` instead of a hand-maintained copy
- Shared agent skill (`.agents/skills/beads`), removed only once neither
  Cursor nor Codex still relies on it
- `bd doctor` reports Cursor Integration, Settings Health, and Hook
  Completeness checks with agent-mode enrichment

Shared hook mechanics (prime runner + one-shot refresh marker) are
factored into `cmd/bd/agent_hook.go` and reused by codex-hook.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-10 13:10:46 -07:00
github-actions[bot]
1caf4b2899 docs: auto-regenerate CLI reference
Applied from the cli-docs-freshness-patch artifact of https://github.com/gastownhall/beads/actions/runs/28990677930
(generated with CI's canonical pinned build). See
scripts/check-cli-docs-drift.sh for how drift is attributed.
2026-07-10 17:44:37 +00:00
Test User
1fc38ba778 feat: choose your own storage backend (Postgres / MySQL / SQLite) — rebased on main
Rebase of PR #4601 (feat/choose-your-own-backend) onto current origin/main,
squashed to a single commit because the original 73-commit history built and then
removed the uowStore derisk spike incrementally, which does not replay cleanly
over the 125 commits main has since advanced (notably #4679, the ready-work
counts fix, which merged to main and is now inherited rather than re-applied).
The full pre-rebase history remains on the original branch tip for reference.

Contents (multi-backend feature + the six review follow-ups):
- bd init --backend=postgres|mysql|sqlite provisioning behind the Dolt-parity
  seam; the three SQL backends share *sqlkit.Store over pluggable dialects and
  carry a generated typed-unsupported shell for the non-core surface.
- Passwords in init DSNs are redacted before persisting to metadata.json (driver
  parser + re-parse verification), with a negative-test matrix proving no secret
  survives (pgdialect + mysql).
- The uowStore derisk spike and its report artifacts are removed; the shell
  generator now lives in internal/storage/unsupportedgen (neutral name).
- Compile-time guard `var _ storage.DoltStorage = (*Store)(nil)` on each backend
  plus a regen-idempotence test keep the generated skip lists honest.
- sqlkit exposes CountReadyWork so every SQL backend satisfies
  storage.ReadyWorkCounter and inherits the shared page-pushed ready-counts path.
- Commercial/product names scrubbed from the feature's own code for vendor
  neutrality.

Rebase reconciliations: adopted main's metadata-load hardening in the store
factories alongside the backend dispatch; combined the config interface
(GetMetadata + ReconcileVersion) and the conformance registrations (ReadyCounts +
Claim/lease); took main's versions of the shared-infra concurrency (uow
doltserver_tx) and delete-cascade (domain/issue_delete) evolutions; implemented
the interface's new UnclaimIssue on sqlkit (delegating to issueops) and added it
to the skip lists.

Verified: go build (cgo + CGO_ENABLED=0) and go vet clean; unit tests
(sqlbuild/issueops/pgdialect/mysql/unsupportedgen) and the SQLite conformance
suite green (RunAll, incl. ReadyCounts equivalence and Claim/lease on the real
sqlkit backend).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-10 17:44:37 +00:00
matt wilkie
812ad6df0a docs: surface upgrade checklist
Add a short upgrade checklist to the README, installing docs, live website installation pages, and upgrade guide so remote-backed migration rules are visible from common entry points.

Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie
2026-07-09 16:47:52 -07:00
coffeegoddd☕️✨
8c00cefdc8 /{cmd,docs,internal,website}: add option for indefinite server uptime 2026-07-09 12:11:22 -07:00
coffeegoddd☕️✨
84ec888cfc docs: regenerate CLI reference for --proxied-server-idle-timeout
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-08 13:08:46 -07:00
Dustin Brown
91b18b7fbe
Merge pull request #4676 from coffeegoddd/db/more-fixes
proxied-server: configurable proxy port, shutdown GC, and commit retries
2026-07-08 12:31:25 -07:00
matt wilkie
aa85f96f06
docs: inventory hygiene - add missing rows, remove stale superpowers artifacts (#4659)
Add DOC_INVENTORY.md disposition rows for four docs/ files created after
the 2026-05-08 review (CI_REQUIRED_CHECK_TOPOLOGY.md, COPILOT_CLI_INTEGRATION.md,
RELATED_PROJECTS.md, SYNC_CONCEPTS.md), all spot-checked healthy and kept.
Note SYNC_CONCEPTS.md as the sanctioned website-mirror source per
.github/workflows/deploy-docs.yml and its widespread cross-doc linking.

Delete docs/superpowers/plans/2026-05-03-unclaim-command.md and
docs/superpowers/specs/2026-05-03-unclaim-command-design.md: PR-passenger
planning/spec artifacts from a contributor's personal multi-agent rig, the
same class removed in commit 187ba85f3 (#4632). Content stays in git
history; the now-empty docs/superpowers/ tree is removed with them, and
their removal is recorded as inventory rows.

Refresh the Reviewed: date on DOC_INVENTORY.md and
staged-for-removal/MANIFEST.md to 2026-07-07. Note in the manifest that all
11 staged entries reach the 2-month threshold around 2026-09-09 with zero
rescue activity so far, and that the next docs health check executes the
deletion.

Agent-Signature: claude-sonnet-5-high on behalf of matt wilkie
2026-07-08 12:21:21 -07:00
coffeegoddd☕️✨
71677e9168 docs: regenerate CLI reference for --proxied-server-port
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-08 12:06:34 -07:00
Harry Miller
d25ec89faa
fix(config): derive tracker config namespaces from the registry (#4428)
* fix(config): derive tracker config namespaces from the registry

`bd config set ado.org <org>` warned "not a recognized config key" (and
unhelpfully suggested "ai.org") even though ADO is a registered tracker
and the value persists correctly. The recognizer's allowlist hardcoded
jira./linear./github. but had drifted — it never gained ado. (GH#4427).

Rather than just add "ado.", make the tracker registry the single source
of truth: drop the hardcoded tracker prefixes from recognizedConfigPrefixes
and derive them at runtime from tracker.List() via a new
allRecognizedConfigPrefixes helper, used by both isRecognizedConfigKey and
suggestConfigKey. This eliminates the drift class so the next tracker is
covered automatically. As a bonus, a genuine typo near a tracker name
(e.g. "add.org") now suggests "ado.org" instead of "ai.org".

Also adds the missing tracker namespaces (gitlab, ado, notion) to the
'Common namespaces' help text.

Tests: extend TestIsRecognizedConfigKey with ado/gitlab/notion/linear/github
keys, add TestTrackerConfigPrefixesRecognized asserting every registered
tracker prefix is recognized, and a suggester case.

Fixes gastownhall/beads#4427

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs: regenerate CLI reference for registry-derived config namespaces

The config-key registry change surfaces gitlab.*, ado.*, and notion.*
in the 'bd config set' help text; regenerate the committed CLI docs to
match so the doc-freshness gate passes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-08 10:30:25 -07:00
matt wilkie
c52c23060d
docs: deduplicate release/testing/federation seams (#4660)
Fix four doc-seam duplications (mybd-melg):

1. AGENT_INSTRUCTIONS.md's "Release Process (Maintainers)" duplicated
   RELEASING.md with a divergent 7-step manual process, cited a
   nonexistent ./scripts/update-homebrew.sh, and used a stale 0.9.3
   example. Replaced the section body with a pointer to RELEASING.md.

2. CONTRIBUTING.md's "Testing Guidelines" was a parallel test-running
   guide that never linked docs/TESTING.md, and was self-contradictory
   ("make test" listed as both the fast tier and the full suite;
   described a -short two-tier strategy scripts/test.sh does not
   implement). Cut the command matrix, kept only contributor etiquette
   (what to run before a PR, expectations), and pointed to
   docs/TESTING.md and docs/TESTING_PHILOSOPHY.md.

3. Moved FEDERATION-SETUP.md to docs/FEDERATION.md as the canonical
   federation home. Left a short pointer stub at the root path (inbound
   links from website quickstart pages and llms-full.txt keep
   resolving). Folded DOLT.md's federation section (architecture
   diagram, sync/status/topology commands, credentials) into
   docs/FEDERATION.md, then reduced DOLT.md's section to a summary
   paragraph plus a link. While merging, corrected the stale "Planned
   Features" list (list-peers/sync/status are implemented; only
   single-peer push/pull remain unexposed - bd federation sync already
   covers both directions) and the stale --json output example.
   Added a docs/DOC_INVENTORY.md row for docs/FEDERATION.md.

4. Folded the two divergent hand-maintained "Landing the Plane" /
   session-completion protocols (AGENTS.md, AGENT_INSTRUCTIONS.md) into
   one canonical copy in AGENTS.md - union of the still-true content
   (explicit quality-gate commands, cleanup commands, and the
   next-session hand-off prompt format from AGENT_INSTRUCTIONS.md).
   Reduced the AGENT_INSTRUCTIONS.md copy to a pointer.

Agent-Signature: claude-sonnet-5-high on behalf of matt wilkie
2026-07-08 08:12:46 -07:00
matt wilkie
7804a7ecde
fix(dolt): report pre-push fsck timeout as timeout, not dangling chunk reference (#4650)
* fix(dolt): report pre-push fsck timeout as timeout, not dangling chunk reference (GH#4258)

When dolt fsck exceeds its 30-second deadline, exec.CommandContext SIGKILLs
the process. The killed run typically produces empty output, which fell through
to the generic failure path and was wrapped as ErrDanglingReference
("dangling chunk reference: aborting push..."), a false corruption report on
healthy but large stores (root-caused by a user: 2.6 GB store needed 67.8 s;
CALL DOLT_GC() shrank it to 24 MB and fsck to 0.5 s).

This commit: adds ErrFSCKTimeout sentinel; extracts classifyFSCKFailure to
distinguish five fsck failure modes (non-empty output routes by content;
parent Canceled → plain cancellation; parent DeadlineExceeded → ErrFSCKTimeout
pointing at the caller's timeout, e.g. dolt.auto-push-timeout for auto-push,
noting BEADS_FSCK_TIMEOUT cannot extend it; fsck's own timeout → ErrFSCKTimeout
with BEADS_FSCK_TIMEOUT guidance; generic empty-output → ErrDanglingReference);
makes the timeout overridable via BEADS_FSCK_TIMEOUT (mirrors BEADS_PRIME_TIMEOUT
pattern); updates doc comments; and adds unit tests for all five branches plus
the timeout-duration helper. Parent-context vs own-timeout classification
prevents misdirecting users to BEADS_FSCK_TIMEOUT when the caller's deadline
(e.g. auto-push-timeout) is the real constraint, and avoids a false
"dangling chunk reference" on user Ctrl-C.

Agent-Signature: claude-fable-5-high on behalf of matt wilkie

* docs(config): document fsck timeout override

Document the BEADS_FSCK_TIMEOUT runtime override alongside the Dolt push timeout settings so users can discover the new PR #4650 recovery knob.

Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie
2026-07-07 23:10:16 -07:00
Dustin Brown
716324c810
Merge pull request #4655 from coffeegoddd/db/handleerror
cmd/bd: replace FatalError* with HandleError* to preserve deferred cleanup
2026-07-07 16:09:30 -07:00
matt wilkie
ef3ffd45b3
feat(migrate): add --force flag as CLI twin of BD_ALLOW_REMOTE_MIGRATE (#4654)
* feat(migrate): add --force flag as CLI twin of BD_ALLOW_REMOTE_MIGRATE

The remote-migrate gate (#4259) refuses to auto-apply pending schema
migrations to a remote-backed database because two clones migrating
independently fork the schema unrecoverably. Until now the only unlock
was the env var BD_ALLOW_REMOTE_MIGRATE=1, which is awkward at the CLI
and can leak into child processes (git hooks, dolt subprocesses). The
--force flag is the natural CLI form of the designated-migrator escape
hatch: it is set before both autoMigrateOnVersionBump and the main store
open in the root PersistentPreRunE via a package-level bool, so it never
leaks out of the process. The env var remains supported for scripted/CI
use and is documented as a parenthetical alongside the new primary form.

Agent-Signature: claude-sonnet-4-6-high on behalf of matt wilkie

* fix(embeddeddolt): point lenient-gate guidance at bd migrate --force

The soft-fail (warn-and-continue) gate warning for read-only and
working-set-reconcile opens still named the env-var escape hatch; align
it with the new primary form introduced for the strict gate.

Agent-Signature: claude-fable-5-high on behalf of matt wilkie

* fix(migrate): reject --force with preview flags; harden override lifecycle

Review findings on the --force flag (cross-vendor: codex gpt-5.5 + claude
opus):

- --force combined with --dry-run/--inspect must fail before the store
  opens: with the gate overridden, the open itself applies pending
  migrations, so the preview flag would be honored only after the
  destructive work it exists to prevent (codex P2).
- Set-or-clear the override unconditionally so it is self-clearing under
  any future in-process root-command reuse (reviewer nit).
- Lock the agent-safety contract against the new flag form: AgentDirective
  must not embed 'bd migrate --force' any more than the env form (nit).

Agent-Signature: claude-fable-5-high on behalf of matt wilkie
2026-07-07 15:58:18 -07:00
coffeegoddd☕️✨
5d87c30015 /{cmd,docs}: remove FatalError* use HandleError* 2026-07-07 14:51:51 -07:00
matt wilkie
939e85e20b docs: regenerate CLI reference for agent.profile config key
Follow-up to #4585: the agent.profile prime/config help text landed
without a CLI docs regen, tripping check-doc-flags.sh on main
(strict freshness probe, no PR diff base to attribute drift).
Regenerated with CGO_ENABLED=0 -tags gms_pure_go per AGENTS.md.

Agent-Signature: claude-fable-5-high on behalf of matt wilkie
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-07 13:52:51 -07:00
matt wilkie
6402f8a5c5
ci(lint): enforce Dolt storage boundary with depguard (deny dolthub imports outside storage adapter) (#4589)
docs/PROJECT_CHARTER.md's "Storage Boundary" section has stated since it was
written that beads packages should not depend on the Dolt engine directly
outside the storage adapter, but nothing checked that mechanically - it was
social-only convention. Add a depguard rule (golangci-lint v2 schema) that
denies any `github.com/dolthub/` import from packages outside
internal/storage/** and internal/doltserver/**, with a message pointing back
at the charter section.

Two pre-existing imports are carved out as justified exceptions via the
rule's `files` negation list, each with an inline comment explaining why:

- cmd/bd/proxied_server.go - imports dolt server config (servercfg, filesys)
  to launch/manage a real `dolt sql-server` process; candidate for later
  migration behind the storage adapter.
- internal/metrics/flusher.go, internal/metrics/metrics.go - import
  DoltHub's eventkit analytics/telemetry client, which is not the Dolt
  storage engine and is out of scope for this boundary. These two files get
  a second, narrowly-scoped depguard rule
  (dolt-storage-boundary-metrics-exception) that allows only
  github.com/dolthub/eventkit and still denies every other dolthub import
  (e.g. the engine itself), so metrics can't become a backdoor around the
  boundary.

Verified against the CI-pinned golangci-lint v2.9.0
(--timeout=5m --build-tags=gms_pure_go ./...): clean with the new rules, and
two temporary probes were reverted after confirming they fail as expected -
a blank import of github.com/dolthub/driver/v2 in cmd/bd, and a blank import
of github.com/dolthub/go-mysql-server/sql in internal/metrics/metrics.go
(the latter proves the metrics exception allows eventkit only, not the
engine).

Agent-Signature: claude-sonnet-5-high on behalf of matt wilkie
2026-07-07 13:33:18 -07:00
matt wilkie
fff254e21b
docs: clarify reserved log export (#4588)
Clarify that VictoriaLogs and BD_OTEL_LOGS_URL are reserved for future log export, while current telemetry export is metrics/stdout only.

Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie
2026-07-07 13:32:54 -07:00
matt wilkie
8e4b9e75a7
feat(prime): add agent.profile config + BD_AGENT_PROFILE runtime knob (#4585)
* feat(prime): add agent.profile config + BD_AGENT_PROFILE runtime knob (mybd-44me)

PR #4220 added the conservative/minimal/team-maintainer PROFILE VOCABULARY
to the generated Beads block and `bd prime` output, but selection stayed
implicit (driven by no-push / ephemeral-branch / no-git-remote checks).
This answers gh#3423 (follow-up to #4220) by adding first-class runtime
plumbing:

- New `agent.profile` config key (default "conservative"), validated with
  a safe fallback to conservative on an unrecognized value (mirrors the
  existing GetSovereignty() pattern in internal/config/sync.go).
- `BD_AGENT_PROFILE` env override, wired for free via viper's existing
  AutomaticEnv + BD prefix/key-replacer wiring (no new BindEnv needed).
- `bd prime` now layers the explicit profile on top of its existing
  implicit branches: when agent.profile=team-maintainer and no hard git
  constraint applies (not stealth/local-only/ephemeral/no-push), the
  close-protocol wording becomes definitive ("commit/sync/push as part of
  routine work") instead of the prior ambiguous "may... when enabled"
  text. Unset/conservative/minimal leaves existing wording unchanged.
- docs/SETUP.md and docs/CONFIG.md now point at the actual knob instead
  of "edit your own AGENTS.md".

Deliberately out of scope: the generated AGENTS.md/CLAUDE.md template
text in internal/templates/agents/defaults/*.md and
internal/recipes/template.go still describes profiles narratively for
tools without config-file access; changing those golden templates is a
larger, separate follow-up.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Agent-Signature: claude-opus-4-8-high on behalf of matt wilkie

* fix(config): register agent. prefix as recognized config key

bd config set agent.profile team-maintainer succeeded but printed a
false "not a recognized config key" warning because cmd/bd/config.go's
allowlist never learned about the agent.* namespace added alongside
the agent.profile knob. Add "agent." to recognizedConfigPrefixes and
cover it in the isRecognizedConfigKey test.

Addresses Codex cross-vendor review finding (2026-07-07) on PR #4585.

Agent-Signature: claude-fable-5-high on behalf of matt wilkie

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-07 13:23:21 -07:00
matt wilkie
4998999a22
docs: remove stale sync-branch worktree guidance (#4593)
* docs: remove stale sync-branch worktree guidance

Clarify that current protected-branch and worktree workflows use Dolt-native sync rather than the removed sync.branch branch/worktree model.

Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie

* docs: fix broken command references and anchor in PR #4593

PROTECTED_BRANCHES.md staged a nonexistent .gitattributes file instead
of the .gitignore that bd init actually creates, and told users to run
the nonexistent `bd vc conflicts` command instead of `bd vc merge
<branch> --strategy [ours|theirs]`. FAQ.md and TROUBLESHOOTING.md still
linked to the old "Beads-Created Worktrees (Sync Branch)" anchor in
WORKTREES.md, which was renamed to "Legacy Cleanup" earlier in this PR.

Addresses Codex cross-vendor review finding (2026-07-07).

Agent-Signature: claude-fable-5-high on behalf of matt wilkie
2026-07-07 13:00:12 -07:00
matt wilkie
75d3d9593d
fix(import): respect import.auto=false in the empty-DB import-on-write path (#4595)
* fix(import): respect import.auto=false on empty DB in bd update (fixes #4304, mybd-3fvn)

shouldRunAutoImportJSONL gated the empty-database upgrade-recovery
auto-import (maybeAutoImportJSONL, GH#2994) on read-only/global/server-mode
flags only. It never consulted the import.auto config key, so
BD_IMPORT_AUTO=false (or import.auto: false in config.yaml) had no effect on
this path -- only the separate git-hook sync importer (importJSONLForSync)
honored it. Any write command (e.g. bd update) against a fresh/empty
database with a stale issues.jsonl present would silently auto-import it and
report success, exactly as reported in #4304.

Add the missing config.GetBool("import.auto") check to
shouldRunAutoImportJSONL. Explicit `bd import` is unaffected: it already
short-circuits on cmd.Name() == "import" regardless of this flag.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FWVnjn3Bq4PSG1akpFpKnY
Agent-Signature: claude-sonnet-5-medium on behalf of matt wilkie

* fix(config): route import.auto through YAML config

bd config set import.auto previously treated the startup gate as a database-backed key, so the value landed where the auto-import checks never read it. Mark it YAML-only like import.path and cover both direct and config set-many routing tables.

Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie

* fix(config): exempt config-set of import.auto=false from pre-run auto-import

Running `bd config set import.auto false` (or `config set-many ...
import.auto=false`) triggered the very auto-import it was meant to
disable: shouldRunAutoImportJSONL runs in PersistentPreRun before the
config command writes the new value, so it still saw the old default
(true) and imported first when a stale .beads/issues.jsonl sat next to
an empty database. Add isDisablingImportAutoViaConfigCommand to detect
this specific invocation and skip the pre-run import so the master
switch takes effect on the same command that sets it.

Addresses Codex cross-vendor review finding (2026-07-07) on PR #4595
(mybd-ycu4).

Agent-Signature: claude-fable-5-high on behalf of matt wilkie

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-07 12:59:29 -07:00
matt wilkie
187ba85f3c
chore: remove agent-rig workflow artifacts (release-gates/, private plan docs) (#4632)
The release-gates/ directory (16 files) and two docs/plans/ files
(schema-skew-guard.md, reference-aware-prune.md) are internal artifacts
from a contributor's personal multi-agent development rig: release-gate
checklists and PM handoff plans referencing bead IDs (be-*) from a
private tracker that does not exist in this repo. They arrived as
passengers on otherwise-valuable contribution PRs between April and
July 2026 and have no readers here - the user-facing documentation for
those features landed in --help text and README via the same PRs.

Removing them keeps the tree free of files that reference untraceable
issue IDs and confuse both human readers and coding agents that treat
docs/plans/ as authoritative. Content remains available in git history.

Agent-Signature: claude-fable-5-high on behalf of matt wilkie
2026-07-07 09:54:01 -07:00
matt wilkie
c3d68d9f9d
docs: regenerate CLI reference after clean-databases prefix-list change (#4631)
Main went red at the 'Check doc flags freshness' gate: 64d67e09
(chore(dolt): converge bd dolt clean-databases prefix list) updated the
command help text without regenerating the generated docs. Regenerated
with scripts/generate-cli-docs.sh (pinned pure-Go binary); delta is the
prefix list line in both generated files, nothing else.

Agent-Signature: claude-fable-5-high on behalf of matt wilkie
2026-07-07 09:28:10 -07:00
Scott Hamilton
b7d483f963
fix(cli): register --gated flag on bd mol ready subcommand (#3744)
Why: the help text advertised --gated on bd mol ready but Cobra flags do not propagate between sibling commands, so the advertised flag was a hard error; this registers it on molReadyGatedCmd directly. Landed manually (auto-merge disabled) after the branch was updated past the #4623 main-CI fixes and the full check suite ran green.

Co-Authored-By: Scott Hamilton <scotthamilton77@gmail.com>
Co-Authored-By: matt wilkie <maphew@gmail.com>
2026-07-07 06:42:43 -07:00
Kevin Glynn
c36afd74e1
feat(q): add --parent for hierarchical quick capture (#4597)
bd q is designed for scripting and agent integration, but batch-creating
epic breakdowns required falling back to the heavier bd create --parent.

Mirrors create.go's parent handling: validate the parent exists, inherit
its labels (create's default), reserve the hierarchical child ID via
GetNextChildID/WithReservedChildCounter, add the parent-child dependency
after CreateIssue, and follow up with the post-write Dolt commit
(GH#2009 pattern). Output stays ID-only.

Closes #4596

Assisted-by: Claude:claude-fable-5 [Cursor]

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-07 05:50:25 -07:00
matt wilkie
5d6ffc7c37
docs: regenerate CLI reference (fixes doc-flags-freshness after #4613) (#4616)
The hand-port of gastownhall/beads#3759 (PR #4613) added inline help text
to `bd linear sync` but deliberately skipped a docs regen to avoid
pulling in unrelated churn. "Check doc flags freshness" failed on main
afterward because `docs/CLI_REFERENCE.md` and the website CLI reference
pages had also drifted from several other recent merges (new issue types
spike/story/milestone, the `bd unclaim` command, `bd formula schema`
flag, `bd types --sections`) - the freshness check compares the whole
generated doc set, not per-PR.

Regenerated via `./scripts/generate-cli-docs.sh` using a pinned
CGO_ENABLED=0 -tags gms_pure_go build of bd, confirming no federation
churn (identical diff whether generated via the script's own build or
the pinned pure-Go binary). `./scripts/generate-cli-docs.sh --check`
now passes.

Agent-Signature: claude-fable-5-high on behalf of matt wilkie
2026-07-06 23:03:41 -07:00
matt wilkie
31a6ec9511
feat: add bd unclaim command to release stuck issues (replaces #3694) (#4614)
* feat: Add bd unclaim command to release stuck issues

- Add UnclaimIssue method to storage interface and implementations
- Add bd unclaim CLI command: clears assignee, resets status to 'open'
- Improve claim error message when issue has assignee but status is 'open'
  (now suggests using bd unclaim)
- Update documentation: CLI_REFERENCE.md, QUICKSTART.md, setup templates
- Add unclaim tests
- Fix telemetry wrapper to implement UnclaimIssue method
- Add test mocks for UnclaimIssue in jira tests

* docs: regenerate CLI reference for bd unclaim

Runs scripts/generate-cli-docs.sh to add the bd unclaim entry that
gastownhall/beads#3694 introduced but whose CLI_REFERENCE.md/website
delta was lost in the conflict resolution during the cherry-pick.
Scoped to only the unclaim addition; unrelated doc drift already
present on main (formula/lint/types/linear entries) is left untouched.

Agent-Signature: claude-fable-5-medium on behalf of matt wilkie

---------

Co-authored-by: Abner S. Alves Junior <abnersajr@gmail.com>
2026-07-06 22:51:35 -07:00
Zir
810c3e9890
fix(cli): list all bead types with required sections in help output and add bd types --sections (#4129)
- Fix bd lint --help and --type flag to list all 9 types (not just 4)
- Fix bd create --type flag to include spike, story, milestone
- Add bd types --sections flag displaying RequiredSections() from code
- Fix docs/CLI_REFERENCE.md section requirements table
- Fix bead-checklists.md to match code (decision: Rationale not "Chosen option",
  chore/spike/story/milestone corrected)
2026-07-06 22:41:21 -07:00
Jim Wordelman
3e10077dc5
feat(preflight): implement --fix mode for vendorHash and version sync (#4054)
* feat(preflight): implement --fix mode for vendorHash and version sync

- Add fixNixHash(): uses sentinel-hash trick with nix build to compute
  and write the correct vendorHash into default.nix when go.sum has
  uncommitted changes; prints clear error if nix not in PATH
- Add fixVersionSync(): syncs cmd/bd/version.go to match default.nix
  version field (default.nix is source of truth)
- Add runFixes(): wires both to --fix flag with human-readable and
  --json output modes
- Remove outdated 'not yet implemented / bd-lfak.3-5' stub
- Preserve original file permissions on all writes

Closes be-xra8, be-roho

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: sync CLI_REFERENCE.md --fix help text with live CLI (be-xra8, be-roho)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(preflight): regenerate website CLI reference for --fix flag (be-laor)

Update website/docs and both versioned_docs variants to reflect --fix
flag description change from 'not yet implemented' to 'vendorHash, version sync'.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* chore: release gate PASS for be-xra8+be-roho (bd preflight --fix mode)

---------

Co-authored-by: Jim Wordelman <jim@wordelman.name>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
2026-07-06 22:33:29 -07:00
Graeme Foster
66371c7afb
fix(telemetry): wire WrapStorage decorator into bd storage chain (#3858)
InstrumentedStorage was fully implemented in internal/telemetry/storage.go
but never instantiated. As a result bd.storage.* metrics, bd.issue.count
snapshots, and per-operation storage spans never reached any backend, even
when an OTel exporter was wired up. Only bd.db.pool_* gauges (registered
separately inside the dolt store) were emitted.

Two structural changes are needed before the wiring can compile:

1. WrapStorage now operates on storage.DoltStorage instead of
   storage.Storage. The store variable in cmd/bd/main.go is typed
   DoltStorage, as is the input to NewHookFiringStore, so a decorator that
   only implements Storage cannot sit in the chain. InstrumentedStorage
   embeds DoltStorage to passthrough capability sub-interfaces
   (VersionControl, HistoryViewer, SyncStore, etc.) — those operations
   already have their own dolt.* spans inside the dolt layer, so wrapping
   them here would double-count.

2. storage.UnwrapStore now peels arbitrary chains of decorators via a
   small Unwrapper interface (Unwrap() DoltStorage). The previous
   implementation only knew about *HookFiringStore and would have left
   InstrumentedStorage in front of the concrete store, breaking the ~25
   cmd/bd type assertions to optional capability interfaces (StoreLocator,
   BackupStore, RawDBAccessor, etc.). HookFiringStore.Inner() is renamed
   to Unwrap() — internal package, no external callers.

Chain composition is extracted into wireStorageDecorators in a new
cmd/bd/storage_chain.go file so the wiring is unit-testable. Six tests
cover the cartesian product of telemetry on/off × hooks on/off/nil-runner
and assert the chain layout via type assertions and Unwrap. The
TelemetryOn_HookOn case is the direct regression test for this bug — if
a future refactor drops the WrapStorage call from the helper, that test
fails. docs/OBSERVABILITY.md gains a local verification snippet.

Co-authored-by: matt wilkie <maphew@gmail.com>
2026-07-06 22:27:32 -07:00
Jack J Garzella
7be354810f
feat(formula): make primitives discoverable to coding agents (GH#3621) (#3781)
* feat(formula): add bd formula schema reflection-driven primitive index (beads-9ib)

Generates internal/formula/schema_gen.go from types.go via go:generate,
exposing all 18 exported structs (Formula, Step, LoopSpec, OnCompleteSpec,
etc.) with field types, json/toml tags, required-flag, and doc comments.

Surfaced via:
  bd formula schema                 # list every primitive
  bd formula schema loop            # show LoopSpec fields
  bd formula primitives on_complete # alias + snake_case match
  bd formula schema --json          # machine-readable

Lookup prefers exact match over Spec/Rule(s) suffix-strip, so "gate"
resolves to Gate (not GateRule). Fields tagged json:"-" (Step.SourceFormula,
Step.SourceLocation) are excluded.

TestSchemaGenIsCurrent re-runs the AST walker in-memory and byte-diffs
against the committed schema_gen.go, so a new struct in types.go without
a regen will fail CI.

Item 2 of GH#3621.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(formula): point bd formula --help at the primitive index (beads-lnf)

Extends the cobra Long descriptions on `formula`, `formula list`, and
`formula show` so an agent reading any of them is told that
`bd formula schema` (alias `primitives`), the curated
`examples/formulas/primitives/` directory, and the website primitives
reference exist. Without these pointers, agents land on the formula
surface and conclude there is no primitive index — which is the exact
failure mode GH#3621 is closing.

Adds cmd/bd/testdata/formula_help.txt as the regression gate: a
scripttest that runs `bd formula --help` (plus `--help` on the list
and show subcommands) and asserts the four pointers are present. If
someone deletes a pointer, the snapshot fails.

website/docs/cli-reference/formula.md is auto-generated from the Long
descriptions via `bd help --doc formula`, so the website doc inherits
the pointers on its next regeneration with no manual edit.

Item 1 of GH#3621.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(formula): curated primitive examples + smoke harness (beads-0sp)

Adds examples/formulas/primitives/ with one minimal `.formula.toml` per
empirically wired primitive in internal/formula/types.go:

  loop-count    LoopSpec.count       expand body 3x → .iter1.work…
  loop-range    LoopSpec.range/var   {n} substitutes into title
  children-epic Step.Children        epic + children w/ sibling needs
  branch-fanin  ComposeRules.Branch  fork-join, deploy depends on 3 sibs
  condition     Step.Condition       var-driven step inclusion
  gate-timer    Step.Gate            sibling gate-typed issue blocks step

Each fixture has a header doc-comment explaining the primitive in
plain language; README.md indexes them with a one-line description
each and points back at `bd formula schema`.

cmd/bd/formula_primitives_test.go is the smoke harness: for each
fixture it parses, cooks through the full transformation pipeline
(loops → branches → gates → advice → expansions → conditions), and
asserts the primitive's observable effect on the cooked subgraph
(issue IDs, blocking deps, substituted titles, gate await_type).
Cooks against an in-memory subgraph rather than a Dolt-backed temp
DB so the harness exercises the primitive transformation, not the
persistence/auto-export infrastructure.

A subtest fails if a fixture is added to the directory without a
registered assertion in cases[] — the harness exists to prove
primitives are wired, not just that fixtures parse.

Explicitly omits an `on_complete` fixture; that primitive is a
runtime no-op as of v1.0.3 and ships with beads-i02's resolution,
not this epic.

Item 3 of GH#3621.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(formula): satisfy CI gosec G306 + regen CLI doc for new help text

Two CI fixes for the formula primitives PR:

  - internal/formula/cmd/schemagen/main.go:26 — drop WriteFile perms
    from 0644 to 0600 (gosec G306).
  - website/docs/cli-reference/formula.md and the v1.0.0 mirror —
    regenerated from the updated `bd formula --help` Long text via
    scripts/generate-cli-docs.sh, using a CGO_ENABLED=0 bd build to
    match CI.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(formula): distinguish schema from wired primitives

* fix(formula): regen schema_gen.go for rebase onto current main

Upstream main's Formula struct gained an Intent field after PR #3781 was
opened; regenerate schema_gen.go via go generate so
TestSchemaGenIsCurrent passes after rebasing the PR's commits onto
current main.

Maintainer fix-merge for gastownhall/beads#3781.

Agent-Signature: claude-fable-5-medium on behalf of matt wilkie

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
2026-07-06 22:26:41 -07:00
Patrick Michaelsen
54af9d68e4
docs: add Related Projects pointer (scry) (#4101)
Introduces docs/RELATED_PROJECTS.md as a place for adjacent or
complementary projects (distinct from COMMUNITY_TOOLS.md, which lists
Beads integrations). Seeds it with one entry — scry — a marker-indexed
recall graph for AI coding agents that composes naturally with Beads:
task graph + recall layer.

Co-authored-by: scryspec-worker <scryspec-worker@reflecttech.ai>
Co-authored-by: matt wilkie <maphew@gmail.com>
2026-07-06 22:12:37 -07:00