Commit graph

10 commits

Author SHA1 Message Date
Tomasz Feliksik
33bed587e0
Accept uutils coreutils timeout in generated hooks, and check the shims against real implementations (#6561)
* Accept uutils coreutils timeout in generated hooks

The generated hook selects a timeout helper only when its --version
banner starts with "timeout (GNU coreutils) ". uutils coreutils reports
"timeout (uutils coreutils) " with the same command line and the same
exit 124 on expiry, so hosts that ship it (Ubuntu 25.10+, NixOS with
uutils-coreutils-noprefix) silently fell through to the Perl alarm, or
to the unbounded direct run when Perl is absent. Follow-up from #5522,
tracked in #5541.

- Widen the identity allowlist to uutils; the match stays by banner so
  Windows timeout.exe is still never probed (#5503).
- Add a backend-selection case using the GNU stub with the uutils
  banner: fails on the old shim (selects gtimeout), passes with the
  widening.
- Regenerate the managed sections in the tracked .githooks/* so
  TestTrackedManagedHookSectionsMatchGenerator stays green.
- Update the hook-timeout passages in docs/reference/git-integration.md
  and troubleshooting.md, which described the probe as GNU-only.

Verified on NixOS with uutils 0.10.0 as /run/current-system/sw/bin/timeout:
with Perl removed from PATH and a bd that hangs, the old shim runs
"without timeout" for the full duration; the new shim expires at
BEADS_HOOK_TIMEOUT and continues.

Agent-Signature: claude-code-claude-opus-5-unknown-reasoning on behalf of Tomasz Feliksik

* Regenerate tracked .githooks managed sections with make githooks-regen

TestTrackedManagedHookSectionsMatchGenerator holds the managed section in
each tracked .githooks/* byte-equal to the cmd/bd/hooks.go generator, but
nothing regenerated them: after a generator change a contributor had to
splice the new section in by hand, and the failure only dumped both
texts. The v1.2.0 bump reddened main this way (ce20a64bb), and #6561 shipped
its first revision with the five hooks stale.

- BD_UPDATE_GOLDEN=1 makes the test rewrite the section in place, keeping
  everything around the markers (the project's own hook logic) untouched.
  Same switch the package's events golden already uses.
- `make githooks-regen` wraps it, next to `corpus-regen`.
- The drift failure now names that command.
- The exactly-one-section check runs before any rewrite.

Verified: drifting one byte inside .githooks/pre-push fails the test with
the hint; `make githooks-regen` restores the file to the same blob SHA;
the test is green again.

Agent-Signature: claude-code-claude-opus-5-unknown-reasoning on behalf of Tomasz Feliksik

* Check the tracked hook shims against real timeout implementations

The Go tests pin the shim's helper selection with scripted stand-ins, so
they can only encode what the author believes each real `timeout` does.
That is where the last two defects lived: uutils prints a banner the
allowlist did not know (#5541), and busybox — which #5541 suggests
adding — exits 143 on expiry rather than 124, so allowlisting it would
turn every deadline into a failed hook and a blocked push.

checks.nix adds a flake check that runs the tracked .githooks/* managed
sections (held equal to the generator by
TestTrackedManagedHookSectionsMatchGenerator) against the binaries
themselves: GNU coreutils, uutils, busybox and toybox `timeout`, each
with and without perl, under dash, bash and busybox ash, for all five
hooks — 150 cases. Expectations come from a model of the contract (the
allowlist as data), so widening it is one line here and the binaries
either agree or they do not.

A fake bd on the shim's restricted PATH blocks on a held-open fifo until
a helper kills it, records the signal and re-raises it, so each case
asserts the backend that ran (TERM from timeout, ALRM from perl's alarm)
and not merely that the shim finished. No clock: a helper that fails to
kill the fake trips the harness's own `timeout 10`. Every case asserts
exit 0, since anything else blocks the user's push. Reading .githooks/*
instead of building bd keeps it at ~1 s and off the Go build's critical
path; CI's test-nix job runs it after its existing help-text smoke test.

Mutation-checked: restoring main's GNU-only sections fails all 30 uutils
cases (15 unbounded, 15 on the perl backend); allowlisting busybox with
a loosened probe fails all 30 busybox cases with hook exit 143.

Agent-Signature: claude-code-claude-opus-5-unknown-reasoning on behalf of Tomasz Feliksik

* Run the hook-timeout check under the gtimeout candidate name too

The shim probes `timeout` and then `gtimeout`, but the matrix only ever
put a binary named `timeout` on PATH, so the second candidate was never
run against a real implementation. Whether a helper is accepted under
that name depends on what its banner does with argv[0].

Measured: the uutils multicall dispatches on the argv[0] SUFFIX
(src/bin/coreutils.rs, `binary_as_util.ends_with(util)`) and then prints
the canonical utility name — invoked as gtimeout it reports
"timeout (uutils coreutils) 0.8.0" (this flake's nixos-25.11 pin; 0.11.0
identical), which the allowlist accepts. busybox and toybox know no
gtimeout applet and fail the probe outright, rejected as before. GNU is
immune by construction: Homebrew's gtimeout is a separate binary whose
banner is the fixed "timeout (GNU coreutils) 9.11"; nixpkgs' coreutils
is a single-binary multicall that refuses a foreign name ("unknown
program 'gtimeout'"), so it gets no variant here.

Each multicall is now also installed on a case PATH as `gtimeout` ALONE
(`installs`, derived from `implementations`; `backendFor` stays keyed on
the implementation, so the model's claim is "uutils is allowlisted
whatever it is called"). 240 cases on Linux, 80 on darwin (no busybox or
toybox there, and no busybox-ash shell). The shadowed
`out=` inside run_case is `case_out` now: it only survived because every
case is a backgrounded subshell, and a de-backgrounded case would have
died on the final `touch "$out"`.

Mutation-checked: installing the variant as `xtimeout` (a name the shim
never probes) fails exactly the 30 uutils-as-gtimeout cases — 15 with
nothing killing the fake bd, 15 on the perl backend (ALRM) instead of
coreutils; restored, 240 of 240 pass. The busybox/toybox variants cannot
distinguish (their expectation is rejection either way); their weight is
that the probe does not blow up on a foreign name.

* Run the flake checks on main too, by nix flake check; docs wording

pr-risk.yml's test-nix job ran the hook-timeout check on PRs only; the
byte-identical job in main.yml never got the step, so post-merge main
never ran it. Both jobs now run `nix flake check -L`: no hardcoded
`x86_64-linux` (the step beside it, `nix run .#default`, was already
system-agnostic), and a check added to checks.nix runs without a
workflow edit. checks.aarch64-darwin and .x86_64-darwin evaluate.

Measured on ubuntu-latest with a cold Nix store (fork run 35700791032,
this tree, 240 cases): `nix flake check -L` 3.6 s including substitution
of uutils, busybox, toybox, dash and perl; 0.08 s warm — beside the
4 min 9 s the existing `nix run .#default` step spends building bd in
the same job. The 10-minute timeout is not in question.

git-integration.md: on Git for Windows the preferred deadline backend is
"a coreutils timeout (GNU or uutils)", not GNU alone, since both now
qualify. troubleshooting.md: reflow a ragged paragraph.

* review: close the duplicated contracts around the uutils timeout accept

Maintainer review fixes for #6561. No change to the shim's behavior or to the
generated/tracked hook sections.

- cmd/bd/hooks_timeout_process_test.go: the uutils fixture was built with
  strings.Replace, which returns its input unchanged when the pattern is
  absent, so a later edit to the GNU stub's banner would silently degenerate
  the uutils case into a second copy of the GNU one — still green, no longer
  testing the new accept. Hoist the derivation and fail loudly when the banner
  no longer matches.
- cmd/bd/hooks_timeout_process_test.go: findHookProcessGNUTimeout held a second,
  un-widened copy of the identity allowlist, so on exactly the hosts this PR
  exists for (uutils timeout, no gtimeout) the only Go test that drives a real
  timeout binary skipped with a reason the fix had just made false. Widen the
  probe's case, rename it findHookProcessCoreutilsTimeout, and reword the skip
  and the subtest. Measured against stub PATHs: uutils goes rc=1 -> rc=0, GNU
  stays rc=0, a busybox banner stays rc=1.
- cmd/bd/init_hooks_test.go: TestGenerateHookSection_Timeout asserted only the
  GNU alternative, so deleting the new uutils one from the generator left the
  structural contract green (verified: it passes under that mutation before
  this change, and reports "section missing uutils coreutils identity check"
  after). Add the companion assertion.
- cmd/bd/init_hooks_test.go, Makefile: the regen arm rewrites tracked source
  files, so give it its own BD_UPDATE_HOOKS_GOLDEN rather than the package's
  shared BD_UPDATE_GOLDEN — an unscoped `BD_UPDATE_GOLDEN=1 go test ./cmd/bd/`
  used to turn genuine hook drift into a silent working-tree rewrite that
  reported PASS.
- cmd/bd/init_hooks_test.go: locate the managed section by marker prefix
  instead of the versioned marker line. Tracked hooks drift both from generator
  content and from the release version stamp; the exact-line lookup made the
  second class fatal ("tracked hook missing ...") before the regen arm was
  reachable, so `make githooks-regen` failed at exactly the moment a release
  engineer reaches for it. The versioned markers are still verified — they are
  part of the byte compare.
- checks.nix: the `rc -eq 124` safety-net verdict discarded both $case_out and
  the already-captured $signal, so the one failure mode that is intermittent
  and not locally reproducible was also the only one with no diagnostics.
  Report them like the `rc -ne 0` branch below it.
- docs/reference/troubleshooting.md, docs/reference/git-integration.md: mirror
  the coreutils wording across both docs this PR touches, and generalize the
  re-install guidance in both. Managed sections are never reported Outdated
  (getHookVersion returns IsShim for them and computeHookStatuses gates on
  !IsShim), so nothing tells an existing install it is stale; the sentence was
  still scoped to the older name-only check (#5503).
- CHANGELOG.md: add the [Unreleased] entry for #5541, worded to the actual
  scope — with Perl installed the shim still reached the Perl alarm arm, so the
  lost deadline bit uutils hosts without Perl — say that existing installs must
  run `bd hooks install` once, and drop the claim that stock NixOS ships uutils
  (this PR's own checks.nix takes GNU from pkgs.coreutils).

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-27 03:38:45 -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
Julian Knutsen
9a1f086a41
docs: pin the Dolt version instead of steering users to releases/latest (ga-m0dlk) (#5899)
The install instructions told users to run the upstream install.sh from
releases/latest, which today resolves to Dolt 2.3.1. Dolt 2.3.0 regressed
CALL DOLT_RESET('--hard'): a few percent of freshly created databases come
up with that procedure answering "Error 1105 (HY000): context canceled" for
the life of the server process. bd flatten and the Dolt-history compaction
in bd admin compact both finish by hard-resetting main onto a temporary
branch, and the merge-settle path behind bd dolt pull falls back to a hard
reset when it abandons a merge — so the documented happy path installed a
Dolt that breaks those operations on a database that otherwise looks fine.

Point the docs at a pinned version instead, with the measurements and the
raise criterion, and tell anyone already on 2.3.x how to check a database
and what to do about it. The pin and its rationale live in
scripts/ci/install-dolt.sh; the docs name the version once, on the Dolt
page, and everything else links there.

Also note that releases/latest resolves to the most recently created
release rather than the highest version, so it can move backwards — v1.88.2
was created after v2.2.4 and v2.3.0 — which makes "install latest" unsafe
independently of this defect.

test/docsync/doltpin_test.go keeps the documented pin, the copy-paste
install snippet and testutil.DoltDockerImage from drifting apart, which is
how the docs ended up on a broken release in the first place.

This documents the pin that gastownhall/beads#5894 applies to CI; land
after it so the reference to scripts/ci/install-dolt.sh resolves.
2026-08-20 22:41:24 -07:00
Bùi Phan Viết Cường
aa8cc065f4
docs(troubleshooting): document the two native-Windows integration traps (#5838)
* docs(troubleshooting): document the two native-Windows integration traps

bd.exe is a native Windows binary, and two consequences of that are
undocumented. Both cost real debugging time because neither fails loudly.

- npm installs bd as a generated bd.cmd shim, so Node's execFile/spawn --
  which run their target directly, without a shell -- never resolve it and
  die with "spawn bd ENOENT" while bd works in the same terminal.
- Git Bash resolves /tmp to its own temp directory; bd, being native,
  resolves it against the current drive root. `bd export -o /tmp/x.jsonl`
  reports success and writes C:\tmp\x.jsonl.

Adds a subsection for each under Platform-Specific Issues, following the
symptom/solution shape already used there, plus cross-links from the FAQ
Windows entry and the installation Windows notes.

Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of CuongBPV

* Update troubleshooting for Windows `/tmp` path issues

Clarify behavior of `/tmp` paths in Git Bash and provide solutions for Windows path handling.

* Update FAQ for Windows integration details

Clarify integration details regarding `bd.exe` and `/tmp` paths in Windows.

---------

Co-authored-by: CuongBPV <cuongbpv@fpt.com>
2026-08-20 05:41:39 -07:00
matt wilkie
21834e720d
feat(doltversion): dolt CLI discovery, hardened version probe, and warn-only version policy (contract part 1) (#5092)
* feat(doltversion): own dolt CLI discovery, hardened probe, and version policy in a leaf package

PR-1 of the dolt CLI install/version contract (design:
mybd reports/2026-07-25-psxg4-dolt-cli-contract-design.md). The dolt
executable managed proxied-server mode spawns was discovered by a bare
exec.LookPath with no override, probed nowhere, and version-checked only
by one advisory archive_level probe; a missing binary erred after
.beads/ creation and an incompatible one died opaquely.

internal/doltversion (stdlib-only) now owns:
- resolution order BEADS_DOLT_BIN env > clone-local sidecar (hook point;
  the sidecar itself lands with identity threading in PR-2) > PATH.
  Explicit values are absolutized before validation (a bare name would
  otherwise validate the cwd file but exec a PATH lookup) and an
  explicitly-named broken binary is an error, never a silent
  fall-through;
- a hardened probe: timeout + process kill, 64KiB output caps,
  unconditional symlink resolution recording given and real paths,
  errno-based exec-format diagnostics naming the likely arch mismatch,
  and file identity captured for later change detection;
- version parsing generalized from the archive_level probe, tolerating
  prerelease/dev suffixes;
- policy: NO hard version floor (adversarial review rejected 2.2.0 as
  policy-without-evidence); RecommendedMin 2.0.0 warns only, backed by
  the 2026-07-25 cross-version matrix run (cross-read of module-written
  storage requires >= 2.0.0). An unparseable version string is likewise
  a warning, not a refusal - the only hard failures are a missing,
  non-executable, or probe-failing binary.

Wired at the two entry points: the managed proxied UOW factory replaces
its bare LookPath and derives archive-level support from the probe it
already ran (no second dolt-version fork on the per-command hot path;
warning is printed once, suppressed under --quiet/--json), and bd init's
proxied preflight fails before any .beads/ write when the binary is
missing or broken (external proxied config is exempt - bd never spawns
that server). doltserver.Start's own bare LookPath is deliberately
untouched here; identity threading through every spawn site is PR-2.

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

* fix(doltversion): fail closed on prerelease archive_level; dedupe dolt advisory

Two review findings on this PR (see reports/2026-07-26-reviewer-dispatch-sweep.md
#5092 for the adversarial-review reasoning):

1. archive_level fail-open regression (major, re gastownhall/beads#4986).
   newManagedProxiedServerUOWProvider derived archiveLevelSupported straight
   from doltID.Version.AtLeast(MinDoltVersionForArchiveLevelConfig), but
   AtLeast deliberately ignores Version.Prerelease (by design, for the
   separate warn-only RecommendedMin check). That meant a prerelease build
   at or above the floor, e.g. "1.52.1-rc1", satisfied the >= 1.52.1 gate
   and had auto_gc_behavior.archive_level written into the YAML — even
   though the old doltVersionAtLeast (gc_config.go) already failed closed
   for any prerelease-suffixed string via strconv.Atoi. If that prerelease
   build predates the field, dolt sql-server's yaml.UnmarshalStrict refuses
   to start: the exact #4986 regression. Extracted the derivation into
   doltArchiveLevelSupported(id) and added a Prerelease == "" gate, plus
   TestDoltArchiveLevelSupported (table test covering above/at/below the
   floor and prerelease-at/-above-floor) and
   TestDoltArchiveLevelSupported_UnparsedVersionFailsClosed.

2. Duplicate dolt-version advisory (major, UX). `bd init --proxied-server`
   probed and printed the version-recommendation warning twice: once in its
   own preflight (init_proxied_server.go) and again ~90 lines later when
   newProxiedServerUOWProvider reaches newManagedProxiedServerUOWProvider,
   which resolved+probed again. The existing doltVersionWarnOnce didn't
   cover init's own Fprintf. Extracted one shared resolveAndProbeDolt(ctx,
   errPrefix) helper (uow_factory.go) that does resolve + probe +
   once-gated warn, called from both sites; init_proxied_server.go no
   longer needs its own copy of the Resolve/ProbeWithPolicy/error-wrapping
   sequence. This also folds the two call sites' warning gates (previously
   !in.quiet vs !quietFlag && !jsonOutput) into one JSON-mode-safe gate.

Verified: CGO_ENABLED=1 go build -tags gms_pure_go ./... clean;
CGO_ENABLED=1 go vet -tags gms_pure_go ./cmd/bd/... clean; gofmt -l on all
changed files empty; targeted tests pass (TestDoltArchiveLevelSupported,
TestDoltArchiveLevelSupported_UnparsedVersionFailsClosed,
TestNewProxiedServerUOWProvider_RoutesExternalConfigToExternalProvider,
TestNewExternalProxiedServerUOWProvider_*, TestBuildProxiedServerClientInfo,
and internal/doltversion's own suite).

Agent-Signature: builder-unknown-model-unknown-reasoning on behalf of maphew

* test(doltversion): resolve symlinks in RealPath expectations (macOS fix)

TestProbeNormalOutput and TestProbeSymlink failed on macOS CI because
t.TempDir lives under /var/folders, itself a symlink to
/private/var/folders. Probe derives RealPath via filepath.EvalSymlinks,
so it correctly returned the /private/var form while the tests compared
against the raw TempDir path.

Map the expected path through the same EvalSymlinks resolution (new
resolveSymlinks test helper). Verified against a symlinked TMPDIR on
Linux, which reproduced the failure before this change.

Agent-Signature: claude-fable-5-high on behalf of maphew

* refactor(cmd/bd): narrow resolveAndProbeDolt to drop the unused identity return

Upstream removed the archive-level gate from proxied-server mode
(68afa3d51), which was the only consumer of the probed identity at these
call sites; returning it now trips unparam on the PR-introduced line.
PR-2's revalidation consumer re-widens the signature when it lands.

Agent-Signature: claude-fable-5-high on behalf of maphew

* fix(doltversion): cross-process probe cache, PATHEXT completion, daily warning dedup

Review fixes (all three MERGE-AFTER-FIXES items from the 2026-08-10 review):

1. The per-command `dolt version` fork on the store-open hot path is gone
   for the steady state: ProbeWithPolicyCached fronts the fork with a JSON
   cache in the user cache dir, keyed by the binary's (real path, size,
   mtime) fingerprint - the exact fields Identity documents for caching.
   A fingerprint hit costs a stat; any change to the binary re-probes.
   Hard probe errors are never cached, and every cache failure direction
   fails open to the uncached behavior.

2. Windows: an explicit BEADS_DOLT_BIN spelled without its extension now
   completes via exec.LookPath's PATHEXT handling (exact spelled path wins
   when both exist), and the behavioral tests run on Windows through .cmd
   stubs instead of skipping wholesale - plus a focused windows-latest CI
   job (test-windows-liveness pattern) so those branches actually execute
   at PR time. skipOnWindows remains only where the subject genuinely
   doesn't exist there (exec-bit check, symlink creation).

3. The old/unverifiable-version advisory now repeats at most once per day
   (warn stamp in the same cache file) instead of on every bd invocation;
   troubleshooting docs state the cadence.

Nits from the same review: Ctrl-C during the probe no longer prints the
misleading install hint (call site branches on context.Canceled); Probe's
stat branch now uses validateExplicitPath's not-found/not-executable
taxonomy split; ParseVersion documents its trailing-integer laxity and the
tightening required before part-2 enforcement.

Agent-Signature: claude-fable-5-high on behalf of maphew

* fix(doltversion): honor init's local --quiet for the advisory; defer sidecar claim in docs

Cross-vendor review follow-ups: bd init defines a local --quiet that
shadows the persistent flag, so resolveAndProbeDolt now takes quiet as a
parameter (init passes in.quiet || quietFlag) instead of reading the
global; and the troubleshooting entry no longer advertises the clone-local
sidecar resolution source, which is a part-2 hook not yet wired
(SidecarValue is always empty in this PR).

Agent-Signature: claude-fable-5-high on behalf of maphew

* test: stop the Windows counting stub double-counting forks

cmd.exe includes the space before a mid-line '>>' in the written text,
so the batch stub's 'set /p =x >> file' appended two bytes ('x ') per
invocation and forkCount — which counts bytes — read every fork as two.
All four Windows failures were exactly doubled expectations; the cache
itself hit and skipped forks correctly. Lead with the redirection so
exactly one byte lands per invocation.

Agent-Signature: claude-fable-5-high on behalf of maphew
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019CwiLhLbAGZdJtKYT76CPp

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-12 21:18:24 -07:00
ecuthiell
766e6c17f2
fix: reject incompatible timeout in generated hooks (#5522)
Select timeout or gtimeout only after a successful GNU coreutils identity probe, validate BEADS_HOOK_TIMEOUT as positive whole seconds, and preserve the Perl and warned direct fallbacks under inherited shell options.

Keep GNU and Perl deadlines soft and backend-scoped, preserve natural status 137, regenerate every tracked hook artifact, and exercise the real process boundary through the required three-host preflight.

Fixes #5503

Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
2026-08-10 20:47:53 -07:00
Julian Knutsen
d59200bd39
refactor: delete the dead orphan-handling capability (bd-gwryr) (#5497)
BatchCreateOptions.OrphanHandling had four modes and one behavior. Every
production call site passed OrphanAllow (or left the field at its zero
value, which took the same branch), so CheckOrphan returned (false, nil)
on every path it could reach — after paying a SELECT COUNT(*)
parent-existence probe on every hierarchical-ID create to feed a switch
whose only reachable arm ignored the answer.

OrphanStrict and OrphanSkip were reachable from exactly one conformance
case, testAuditCreateOrphanHandling, which existed to execute them.
OrphanResurrect was never a branch at all: it shared the default arm with
OrphanAllow, and the "auto-resurrects missing parents from database
history" behavior its doc comment described left with the JSONL sync
layer. internal/beads' TestImportWithDeletedParent still asserted that
removed behavior; it goes too.

This removes the type, the four constants, the field, CheckOrphan and its
call site, the backend package's alias and re-exports (a breaking change
to a published package, signed off by the owner), the dead
ImportOptions.OrphanHandling, and the import.orphan_handling row in the
yaml-only-key test — replaced with import.unlisted-key, which keeps the
"import.* is exact-match, not a prefix namespace" assertion the row was
actually providing.

The behavior that remains is what OrphanAllow always did: a hierarchical
create whose parent is missing is accepted, and the child's auxiliary
counter row is skipped because it would have no owner
(TestReconcileChildCountersSkipsMissingParent pins that). The wasted
query is gone from the create path.

Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-09 12:03:18 -07: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
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
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