Commit graph

19 commits

Author SHA1 Message Date
Bee
b485a0975e
feat(gate): bd gate create --repo names the repository a gh:run/gh:pr gate is checked in (#7176)
* feat(gate): bd gate create --repo names the repository a gh:run/gh:pr gate is checked in

A gh:pr gate for a PR in another repository could only be pointed there
through the blocked issue's metadata.repo; with none, `bd gate check`
resolved the bare number against the current repository and escalated
"pull request not found" on every check, with nothing in the text saying
which repository it had looked in. Five gates armed that way on 2026-10-03
never released after their PRs merged.

- `--repo OWNER/REPO` (or HOST/OWNER/REPO) on `bd gate create`: an
  explicit value wins over the inherited one; it goes through the same
  validator as metadata.repo (now `validateGitHubRepo`, split out of
  `githubRepoFromIssue`); it is refused on human/timer/bead gates, where
  nothing would read it. Both create routes call one helper,
  `gateMetadataForCreate`, so the flag cannot drift between them.
- The gh:pr not-found escalation reason names the repository the number
  was resolved against ("pull request not found: #42 in owner/repo" or
  "... in the current repository").
- Help text, docs/workflows/gates.md and the plugin's ASYNC_GATES.md say
  when the flag is needed. docs/cli-reference is pinned to the release
  and regenerates on its own.

Tests: TestGateMetadataForCreateExplicitRepo, TestCheckGHPRNotFoundNamesTheRepository
(unit); TestEmbeddedGateCreate/create_gate_with_repo + /repo_flag_on_human_gate_is_refused
(embedded); TestProxiedServerGateCreateInheritsRepoMetadata/explicit_repo_flag_wins_over_inherited
(proxied).

Refs ghosttrack/wyvern wy-2jh4v5.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* fix(gate): keep the create --repo workspace bypass off bd gate create

The root pre-run bypass for `bd create --repo` (GH#3686) matched the leaf
name "create", so `bd gate create --repo` outside a workspace took it: an
OWNER/REPO slug opened a stray ./OWNER/REPO/.beads workspace under the cwd
and failed with "issue not found", and an https:// URL skipped store wiring
and panicked on the nil store. Key the bypass on the command path, as
proxy_capability.go already does; gate create now fails with "no beads
database found" outside a workspace like every other command, and top-level
create --repo (local path and remote URL) still takes the bypass.

Also name the repository in the gh:run not-found escalation, as the gh:pr
one already does. Only stderr with a lowercase "not found" reaches that
arm: real gh reports a missing run as "HTTP 404: Not Found (<api url>)",
which takes the existing error path, and that URL already names the
repository. The match stays case-sensitive because a token without access
to the repository gets the same 404.

Tests: TestEmbeddedCreateRepoFromNonBeadsCwd/gate_create_repo_flag_is_not_a_workspace
(slug and URL forms, built binary run from an empty cwd) and the
cross_repo/current_repo subtests of TestCheckGHRunNotFoundNamesTheRepository
fail with the fixes reverted. Its real_gh_404_names_the_repository subtest
feeds gh's real 404 stderr and fails if the match is widened.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <julianknutsen@users.noreply.github.com>
2026-10-08 08:02:46 +00:00
Bee
8bb99b49d8
fix(close): verify bead gates on the proxied-server route (#5861 item 1) (#6962)
* fix(close): verify bead gates on the proxied-server route (wy-j48b3y)

The close pre-check built its bead-gate lookup on the local store, which
the proxied-server route never opens (the root pre-run short-circuits to
uowProvider). So `bd close <gate>` on a bead gate refused with
"no local store available" there even after the awaited bead had closed,
while `bd gate check` resolved the same gate through its fresh-read
getter. Item 1 of #5861.

The pre-check now picks the getter by route: proxied-server reads through
the same proxiedFreshReadGetter gate check uses (local read, then prefix
routes); direct and embedded keep the store-backed routed getter.

Tests: a proxied integration test covers the open-target refusal (which
now names the target's status), the closed-target close, and --force;
against the old code it fails with the exact upstream refusal. A unit
test pins the route selection. Docs and CHANGELOG drop the limitation.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* ci(shards): list TestProxiedServerCloseBeadGate in the proxied 30-shard manifest

#7129 turned the Bazel 30-shard block of
.github/scripts/proxied-cmd-test-shards.txt into an exact-once coverage
gate (TestProxiedShardManifestGeneratorNotStale in scripts/). This PR's
merge-base predates that gate, so after the rebase onto current main the
gate fails with "missing (1): TestProxiedServerCloseBeadGate", the
proxied integration test this PR adds.

Generated with the gate's own fix command,
`python3 scripts/ci/gen_proxied_shard_manifest.py 30 --weights=duration --write`.
The write is incremental: it puts the one name on the lightest shard (2)
and moves no existing assignment. The frozen 15-shard block is untouched.

Agent-Signature: claude-code-unknown-model-max on behalf of Eddie the Engineer
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.com>
2026-10-08 06:01:18 +00:00
Harry Miller
d0743f89d7
fix(formula): substitute vars in step assignee, labels, and metadata (#5758)
* fix(formula): substitute vars in step assignee, labels, and metadata

Cook and pour substituted title/description/notes/gate but copied
assignee, labels, and metadata through raw, so a poured bead carried
literal `{{var}}` text in all three.

- labels: every label-based query, filter, and automation silently stops
  matching, and nothing errors (GH#5110).
- metadata: general keys came through literal; only a top-level "repo"
  key on a gh:* gate was substituted (GH#5110).
- assignee: worse than cosmetic - close refuses when the actor doesn't
  match the assignee, so every step of a poured molecule is unclosable
  and the molecule can never advance (GH#5754).

internal/formula/expand.go already substituted assignee and labels on
the inline-expansion path, so the two paths disagreed on the same
fields; Step.Assignee is documented as "supports substitution" and
ExtractVariables already scanned it, meaning pour hard-failed demanding
a variable it then refused to resolve.

Both call sites are fixed together: runtime-mode cook feeds the proto
that pour clones, so a field left literal in either path ships a
placeholder onto the bead. Fixing cloneSubgraphInto covers pour, wisp,
bond, and the proxied-server paths, which all funnel through it.

substituteMetadataRepo is generalized to substituteMetadataVars, which
resolves every string leaf of the metadata JSON at any depth. This drops
the earlier gh:*-gate-only restriction (SF2/SF4): reading a `repo` key
AS a GitHub selector is only correct on a gh:* gate, but resolving a
{{var}} in it interprets the key not at all. The walk still decodes into
json.RawMessage, so untouched values stay byte-identical, and object
keys are never rewritten (a rewritten key could collide with a sibling).

The variable scan is widened to match: extractAllVariables (pour) and
ExtractVariables (cook) now cover assignee, labels, metadata strings,
notes, and await ID, so pour demands exactly the variables it resolves.
Undeclared handlebars are still filtered out by VarDefs.

Regression coverage asserts on a poured bead, and checks the assignee
via validation.AssigneeMatches rather than a string compare - a
substitution-only assertion would pass while the unclosable symptom
persisted.

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

* chore(formula): regenerate schema_gen.go after the types.go doc edits

TestSchemaGenIsCurrent holds schema_gen.go to a byte-for-byte rerun of
the generator over types.go, and the field docs are part of the
generated output — so the Labels/Metadata comment updates made it stale.

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

* fix(mol bond): resolve vars like pour instead of demanding every handlebar

buildAttachCloneOpts demanded every variable extractAllVariables found in
the proto subgraph and applied no declared defaults, unlike pour
(cmd/bd/pour.go) and wisp (cmd/bd/wisp.go). Widening the scanned field set
to assignee, labels and metadata therefore widened bond's hard refusal
along with it: a proto whose label or metadata carried an undeclared
documentation handlebar, or a declared var carrying only a default, made
`bd mol bond` fail with "missing required variables" where it previously
succeeded.

Run applyVariableDefaults + extractRequiredVariables there, matching the
sibling call sites. extractRequiredVariables returns the unfiltered list
when VarDefs is nil, so a legacy template still requires every var it
mentions; the change is strictly a reduction in false failures. Applying
the defaults also puts them in opts.Vars, which is the map
cloneSubgraphInto actually substitutes from.

Also from review:

- docs/workflows/gates.md no longer enumerates a stale three-field list for
  where `{{var}}` substitution applies.
- maxMetadataSubstitutionDepth's doc names walkJSONStrings (not the
  long-gone substituteJSONVars) and says plainly that hitting the bound
  deliberately ships a literal placeholder rather than erroring.

Reported-by: bee-ghosttrack
Agent-Signature: claude-code-opus-5-unknown-reasoning on behalf of Harry Miller

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

* build(bazel): add the validation dep to the bd_test go_test (make bazel-sync)

mol_embedded_test.go and template_test.go now import internal/validation
directly (validation.AssigneeMatches, to check the substituted step
assignee), so gazelle emits //internal/validation on bd_test. bd_lib
already carries the dep, so bd_test compiles through embed, but gazelle
lists every direct test import on the go_test itself. cmd/bd/BUILD.bazel
landed on main after this PR branched, so the PR could not carry the
line; without it, bazel.yml's "BUILD files in sync" step fails in the
required Bazel / test lane. Generated by `make bazel-sync`.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.local>
2026-09-30 18:08:44 -07:00
Harry Miller
fe5b9d1e0f
fix(formula): reject a waits_for gate with no spawner, and stop reporting invalid formulas as not found (#5761)
* fix(formula): reject a waits_for gate that has no spawner to wait for

waits_for = "all-children" (or "any-children") names no spawner, so
collectDependencies infers one from needs[0] and emits no dependency at
all when the step has no needs. Validation accepted that step, cooking
gave it a gate:all-children label, and the result was a step with zero
dependencies that is ready immediately — a fan-in that silently never
fans in. Only the label survived to suggest otherwise.

Reject it where the intent is still visible, naming both repairs: add
needs, or name the spawner with children-of(step-id), which carries its
own spawner and stays valid without needs. depends_on is deliberately not
accepted as a substitute, because the inference does not read it.

The fan-in example in docs/workflows/gates.md taught exactly the broken
shape — a summarize step with waits_for and no needs — so it is corrected
here alongside, with the spawner step it was missing.

* fix(formula): make a validation failure distinguishable from "not a formula"

Callers that resolve a name as a formula and fall back to a proto/issue
lookup have no way to tell the two apart, so a formula that exists and
does not validate is reported as not found and its real error is thrown
away. The spawnerless waits_for gate rejected above lands in exactly that
path.

ErrVarValidation already exists for the same reason, covering bad --var
values. Give Validate the matching sentinel; the message it produces is
unchanged. Wiring the fallbacks to it is a separate change.

* fix(mol): report an invalid formula instead of calling it not found

pour, wisp, bond and seed resolve a name as a formula first and fall back
to a proto/issue lookup. Any error from the formula path was treated as
"this is not a formula", so a formula that exists and fails validation
came back as "'<name>' not found as formula or proto ID" — with bd
formula list happily showing it. The real error was never printed, and
the advice to run bd formula list confirmed the wrong diagnosis.

Each fallback now reports a validation failure directly, the way it
already does for the bad --var values ErrVarValidation covers. A name
that really is not a formula is unaffected.

* fix(mol bond): make --dry-run validate the formula the real bond validates

resolveOrDescribe resolved a formula name with parser.LoadByName, which
never calls Formula.Validate - LoadByName -> loadFormula -> ParseFile does
not, and only parser.Resolve does. The real bond path
(resolveAndCookFormulaWithVars) calls Resolve, so the dry-run previewed
"will cook as proto" for every formula the real bond rejects, including
for the waits_for-without-a-spawner rule this branch adds. The function's
own comment already promised the opposite.

resolveOrDescribe now resolves before it validates provided vars, which
also means the --var check runs against the merged formula rather than the
unmerged one, so a var declared only in a parent is checked too. The two
error wrappings match the real path's, so the routes produce the same
message rather than merely the same exit code.

TestBdMolBondDryRun_RejectsInvalidFormulaLikeTheRealBond runs both routes
against the same invalid formula and asserts they agree - both fail, both
name waits_for, neither reports it as "not found as issue or formula". It
reproduces the gap against the old code:

    dry-run previewed a bond the real bond rejects:
      A: dryrun-invalid-gate (formula -> will cook as proto)

Also from review:

- validation_sentinel_test.go uses strings.HasPrefix instead of a slice
  that would panic with index-out-of-range rather than failing cleanly if
  the message ever shortened.
- Step.WaitsFor's field doc now states the needs requirement, and
  schema_gen.go is regenerated from it, so the generated schema documents
  the rule the validator enforces. docs/workflows/gates.md already said it.

The condition-filtering follow-up is filed as GH#6437: Validate runs
inside parser.Resolve, before FilterStepsByCondition, so a spawner dropped
by a false condition still reaches collectDependencies as a dangling
reference and is skipped silently - the same zero-dependency gate, past
the new check.

Reported-by: bee-ghosttrack
Agent-Signature: claude-code-opus-5-unknown-reasoning on behalf of Harry Miller

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

* test(mol bond): assert the dry-run gap in process, not through a subprocess

The regression test spawned an embedded bd and ran two CLI invocations,
which is the most expensive shape of test in cmd/bd - and cmd/bd already
runs 477s of its 600s budget on the macos runner, so the addition timed
the package out.

The process boundary was never what the test was about. resolveOrDescribe
and resolveOrCookToSubgraph are both reachable directly with a molReader
that answers "no such issue", and GT_ROOT puts a temp formula dir on
formula.DefaultSearchPaths without touching HOME or the working directory.
Same assertion - the two routes agree, both name waits_for, neither
reports an invalid formula as not found - in 0.03s instead of 18s.

Asserting the routes against each other rather than against a literal
message is deliberate: it is what stops a validation rule added later from
re-opening the same gap. The LoadByName control is now explicit too, since
that call still accepting the formula is the reason the bug existed; if it
ever starts validating, the comparison stops distinguishing anything and
the test says so instead of passing quietly.

Second case added while here: the dry-run validated --var values against
the UNMERGED formula, so a constraint declared only in a parent went
unchecked. Resolving first fixes that as well, and an extends chain with
the enum in the parent pins it:

    dry-run accepted a var value the real bond rejects; the enum is
    declared only in the parent (real bond said: formula "dryrun-child":
    variable validation failed:
      - variable "env": value "staging" not in allowed values [dev prod])

Agent-Signature: claude-code-opus-5-unknown-reasoning on behalf of Harry Miller

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

* docs(changelog): move this PR's entry under [Unreleased]

The 1.3.0 cut renamed the old [Unreleased] block, so the entry this branch
added there now merges cleanly into the released [1.3.0] section (#6643).

Agent-Signature: claude-code-opus-5-5-unknown-reasoning on behalf of Harry Miller
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* chore(bazel): enumerate the PR's two new test files in go_test srcs

Base added cmd/bd/BUILD.bazel and internal/formula/BUILD.bazel after this
branch's merge base, so the two untagged _test.go files this PR adds were
absent from their go_test srcs lists. Generated by 'make bazel-sync'
(bazel run //:gazelle); no hand edits. A second sync is a no-op.

* docs(formula): correct the waits_for spawner doc and the dry-run parity claim

Maintainer review fixup for the adoption of #5761 (review iteration 1
pre-merge checklist). Wording only -- no control flow changes.

internal/formula/types.go: the new Step.WaitsFor doc said "Requires needs
(or depends_on)", but Formula.Validate receives only step.Needs and cook
infers the spawner solely from Needs[0] (cmd/bd/cook.go:961-962) -- the
DependsOn loop never feeds waitsForSpawnerStepID, and the struct doc's
"merged during cooking" happens after Validate. A depends_on-only bare gate
is therefore correctly rejected: the code and the error message are right,
only the comment was wrong, and it shipped into the generated schema surface
agents read. docs/workflows/gates.md already states it correctly.
Regenerated schema_gen.go with `go generate ./internal/formula/`.

CHANGELOG.md: "so it fails on exactly what the real bond fails on" was an
overclaim. The dry-run now resolves and validates the way the real bond
does, but five later real-path failure surfaces (inline expansions,
expansions, aspect load/type, condition filtering) stay outside the preview.
Named that boundary rather than claiming total parity.

Contributor commits untouched.

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
2026-09-29 17:09:59 -07:00
Julian Knutsen
076e38ee3a
docs(gates): document multi-rig/proxied gate limitations for 1.3.0 (#6052)
The gate-types table claimed bead gates cannot be checked at all, which has
been wrong since local bead-gate evaluation was restored — only the cross-rig
`<rig>:<bead-id>` form stays pending. Fix the row and add a "Known
limitations" subsection covering the three behaviors users actually hit, each
quoting its verbatim error string so the text is searchable:

- cross-rig bead gates: `cannot be checked (multi-rig routing removed)`
- `bd close` of a bead gate in proxied-server mode: `no local store available`
- routed reads of a proxied-server target: `proxy server store needs to be
  uow provider`

Two matching troubleshooting entries under "Dolt Server Issues" give the
symptom, the cause, and the workarounds (`bd gate check`, `bd close --force`,
or running from the owning rig's workspace).

Docs only — no code or behavior change. 1.3.0 does not advertise multi-rig
proxied-server operation, so this documents the limitation rather than
fixing it.

Refs #5861

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-28 23:23:15 -07:00
Vishnu J
cff6bac4ed
fix(ui): stop using blocked ● for priority in CLI output (#5511)
Priority used the filled circle also mapped to status-blocked, so agents
misread ready work as blocked (GH#4996). Render P-labels only; document
the convention for agents; keep ● for blocked status alone.

Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
2026-08-10 06:19:51 -07:00
matt wilkie
3b41ab044a
Merge branch 'main' into fix/cross-repo-github-gates 2026-08-02 23:38:17 -07:00
matt wilkie
b5b11f35f4 docs(gate): note repo {{var}} substitution timing and cross-repo discover requirements
repo = "{{var}}" in a formula gate step is substituted at pour time (bd mol
pour --var ...), not at cook --persist time; and bd gate discover requires a
workflow name hint for a cross-repo gate and ignores the local branch filter
unless --branch is passed explicitly.

Agent-Signature: claude-sonnet-5-medium on behalf of matt wilkie
2026-08-01 13:51:18 -07:00
matt wilkie
62d362235b chore(gate): review nits - dead code, docs wording, createGateIssue repo gating
- Delete queryGitHubRuns (unreferenced since queries are scoped per-repo).
- docs/workflows/gates.md: metadata.repo inheritance on an ad-hoc gate created
  with `bd gate create` only applies to gh:run/gh:pr gates (SF4); reword to
  say so instead of implying it for all gate types.
- createGateIssue wrote {"repo":...} metadata for any gate type; gate it with
  the same isGitHubGateType helper repoMetadataForGate (SF4) already uses, so
  a repo field on a human/timer/bead gate step - unrelated, ordinary metadata
  for those types - is not mistaken for a GitHub repo selector.

Agent-Signature: claude-sonnet-5-medium on behalf of matt wilkie
2026-08-01 13:17:52 -07:00
matt wilkie
8369d9c922 feat(gate): let formula gates carry the repo selector (SF2)
createGateIssue built the gate issue directly without copying any
metadata, and formula.Gate had no field for it, so the declarative
cross-repo gate configuration documented for ad-hoc `bd gate create`
gates ("set the gate's string metadata.repo value") had no formula
equivalent. Add Gate.Repo (json/toml `repo`), thread it through
variable extraction and pour-time substitution alongside the other
gate fields, and propagate it onto the created gate issue's metadata
in createGateIssue. Validation of the value stays at check time
(githubRepoFromIssue), matching how any other gate's repo metadata is
validated. Document the new field in docs/workflows/gates.md.

Agent-Signature: claude-sonnet-5-medium on behalf of matt wilkie
2026-08-01 12:36:53 -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
Sjors Robroek
3fc52de505
fix(gate): honor repository metadata for GitHub checks (astro-plan-0mjq)
Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of Sjors Robroek
2026-07-22 15:20:40 +04:00
Chris Sells
69e33099b8 docs: apply PR #4722 review feedback to user docs
- FAQ: fix bulk migration/export commands (tracker pull/push need explicit
  IDs; bulk lives on sync --pull-only / --pull / --push-only / --push) and
  correct the cross-project isolation claim (hydration + external targets)
- quickstart: replace the broken DOLT.md blob URL with site links
- installation: Quick Install Script heading matches its macOS/Linux/FreeBSD
  body
- rewrite 33 stale SCREAMING_CASE link labels to the target pages' titles
- add description frontmatter to the 55 authored pages missing it
- docs.json: wildcard redirects for the old /next/ and version-prefixed
  route spaces (1.0.0, 1.0.4, 1.0.5)
2026-07-12 11:06:57 -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
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
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
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